Projects / Trailforge

MIT open source / v0.1.0a1 alpha

Trailforge

Bound the work.
Preserve the trail.

Read the technical study Download the full guide
Trailforge — bounded execution, durable trailsA scoped goal passes through bounded execution and host verification, with checkpoints preserved along the way.CUSTOM AGENT HARNESSMIT / ALPHATrailforgeBOUND THE WORK. PRESERVE THE TRAIL.Scoped goalBounded executionHost verificationCHECKPOINTS / RECEIPTS / RECOVERY
An execution system, not a simulated interface. A scoped goal, bounded work, and host verification share a durable trail.

00 / The idea

Intelligence proposes.
Authority stays
with the host.

I built Trailforge to make agent execution bounded, recoverable, and inspectable. It separates a model's proposal from a verified result—and a verified result from permission to act outside the system. It is also the harness behind Diffwise.

Challenge
Opaque agent runs, unsafe retries, and completion claims without retained evidence.
Approach
Finite contracts, durable checkpoints, digest-bound receipts, and explicit uncertainty.
Host owns
Identity, actual models/tools, policy, real provider limits, protected criteria, and publishers.
Release
MIT alpha v0.1.0a1. Zero third-party base dependencies; no production certification.

01 / System architecture

A small kernel.
Explicit boundaries.

The neutral Goal/Task Harness uses SQLite as its authority. Develop extends that execution path; the fixed Offline Review controller is separate. Optional integrations expose the kernel without making model output an authority source.

The host owns authority. The harness bounds execution.Trailforge / System map
Trusted application hostNeutral execution kernelBounded integrations
Identity & policytenant · resource · permissions · provider limits
Goal + ordered tasksexplicit effects · budget · required checks
Protected acceptancehost-controlled criteria and verification
Harnessadmit → execute → check → complete or hold
SQLite authoritycheckpoints · journal · reservations · versions
Develop profilefinite rounds · candidate/check continuity
Registered adaptersMODEL · TOOL · VERIFY / trusted host code
Artifacts & retrievalbounded bytes · revision-bound exact matches
Linux Docker runnerseparately configured isolation boundary
GuardedPublisherseparate exact approval / effect boundary
SQLite is the neutral runtime's authority. Optional PostgreSQL supports the separate legacy Review profile, not generic Goal/Task execution.
Work

Admit a finite plan.

Bind scope, inputs, dependencies, effects, required checks, and declared limits before execution.

Evidence

Preserve observations.

Checkpoints, task receipts, candidate/check digests, and explicit gaps keep the trail inspectable.

Authority

Keep approval separate.

Model proposals do not grant capabilities. Host-controlled checks and exact publication approvals remain distinct.

02 / Durable execution

Resume the work.
Not the guess.

Admission, reservation, and an active attempt are persisted before a callback runs. Valid outputs receive bound receipts. Reconstructed hosts reuse completed task results rather than starting the run over.

Persist admission before executing the taskTrailforge / System map
Bound contractDurable admissionTrusted callbackRecorded result
READYscope + goal + adapter binding
RUNNINGreserve units · persist attempt + lease
Adapterbounded input / dependencies → output
CHECKINGstore result + digest-bound receipt
Required checks → PASS: COMPLETED / FAIL: FAILED / UNKNOWN: WAITING_HUMAN. Callback uncertainty also holds the run. Cancellation is terminal.
Ambiguous outcomes retain the admitted attempt and units. A trusted host must explicitly choose RETRY or CANCEL; a lease fences commits, not callback execution.
Typed checks

PASS is not just JSON.

Required checks return a host VerifiedResult bound to the same goal. A verdict-shaped model response is not verifier authority.

Recovery

Retain UNKNOWN.

Ambiguous attempts hold the run. Explicit host RETRY or CANCEL retains admitted units and attempt counts.

Limits

Bound, don't overclaim.

Declared units are not tokens or dollars. Leases fence stale commits, not running Python or provider calls.

03 / The Develop profile

Build the candidate.
Protect acceptance.

One to three explicitly planned rounds run through six phases. BUILD alone receives candidate-write capability. VERIFY checks the exact candidate; HEALTH confirms its continuity before a handoff is issued.

Finite development rounds. Protected acceptance.Trailforge / System map
UnderstandCreate & inspectVerify & retain
PLANbounded objective and proposed approach
RESEARCHscoped observations · no candidate writes
BUILDonly phase granted CANDIDATE_WRITE
DEBUGinspect outcomes · no candidate writes
VERIFYhost criterion + exact candidate/check digests
HEALTHbuilt-in candidate continuity check
Handoffreview artifact, not deployment permission
One to three rounds are declared up front. The final round's VERIFY and HEALTH are required checks. A handoff requires the same candidate and protected check trees.

Candidate/check integrity is checked before and after phase work. Trusted host callbacks are not an OS sandbox; an unchanged, checked handoff is not merge or deployment permission.

04 / Evidence-bound review

A finding needs
a source trail.

The separate Offline Review demonstration binds paths, line ranges, preserved quotes, content digests, and revisions to captured source. Missing coverage stays visible. Its configured review roles use mock output, not bundled live LLM agents.

Source evidence is data, not authorityTrailforge / System map
CaptureProposeValidateReview
Bound snapshotscope · revision · paths · byte digests
Mock findingrole · path · lines · preserved quote
Evidence checksreceipt + exact source correspondence
Human reviewretained gaps · COMPLETE or PARTIAL
A complete workflow is not calibrated model quality. Independent acceptance and real-provider evaluations remain separate responsibilities.
The fixed Offline Review demonstration uses a mock callback. Exact citation validation establishes source correspondence, not that a proposed defect is real.

05 / External-effect boundary

Approve precisely.
Never resend blindly.

A publication intent binds scope, goal, policy, revision, action, and exact payload. Approval is consumed and a stable SENDING operation is recorded before dispatch. A lost response remains UNKNOWN until the same operation can be inspected.

Approval is bound to an exact effectTrailforge / System map
Intent & authorityDurable dispatchObserve outcome
Exact intentscope · goal · policy · revision · action · payload
Host approvallive authorization · expiry · revocation
SENDINGconsume approval + persist operation first
Publisher adapterexecute the bound operation
ACCEPTEDvalid acknowledgement for the same operation
UNKNOWNlost response or invalid acknowledgement
Reconcileinspect the same operation · no re-execution
The included publisher is a durable local simulation. Real external publishers and customer identity are host integrations; ambiguous publication is inspected, never blindly resent.

The included publisher is a durable local simulator. Real customer authentication and external publishers are host integrations; intent deduplication is not a universal exactly-once provider guarantee.

06 / Engineering underneath

Keep the kernel
independent.

Python's standard library supplies the base runtime. Optional LangGraph scheduling, legacy PostgreSQL/broker integration, Linux Docker isolation, exact retrieval, artifacts, and allowlisted telemetry are composed deliberately by the host.

07 / Release evidence

Test the boundaries.
Name the limits.

The v0.1.0a1 guide records installed-wheel, optional integration, and native Linux container conformance. These are documented release results, not new portfolio benchmarks or model-accuracy measurements.

Portable matrix
62 cases per OS / Python cell
Legacy PostgreSQL
56 Linux installed-extra cases
Linux Docker
5 container-boundary cases
LangGraph
2 installed-extra cases

The portable matrix covers Ubuntu 24.04 / Windows 2022 × Python 3.11 / 3.13.15. The guide reports zero failures, errors, skips, or expected failures in accepted reports. Alpha APIs can change; independent acceptance and real-provider quality evaluation remain separate gates.

Read the complete engineering study