DoneState

DoneState completes the work. OpsTruth proves it.

DoneState is a durable control plane for autonomous coding work in existing repositories. Give it a prose outcome and a standing authority envelope. It runs a coding harness, executes deterministic validation, survives ordinary restarts, and seals the exact result for an independent verifier.

It is deliberately not another coding model. Codex, Pi, OpenClaw or another process can be the harness. DoneState owns the parts that should not depend on model judgement: admission, authority, budgets, leases, idempotency, state transitions, audit evidence and completion semantics.

Why it exists

Most coding-agent workflows still make a person supervise tool calls or trust an agent's claim that the work is finished. DoneState changes the unit of control:

• A human authorises consequences once for an objective.
• A harness chooses implementation steps inside that boundary.
• Deterministic code records intent before each effect and settlement afterwards.
• Crashes with uncertain effects stop as AMBIGUOUS_EFFECT; they are not blindly replayed.
• Only a pinned, signed, independent verifier can move a run to VERIFIED.

flowchart TD
    A["Prose outcome"] --> B["Authority and policy"]
    B --> C["Durable execution"]
    C --> D["Validation and reconciliation"]
    D --> E["Sealed handoff"]
    E --> F["Independent verification"]

Install

Node.js 22.5 or newer is required.

npm install --global donestate

Fast path

Inside a Git repository with Codex CLI already authenticated:

donestate go "Fix issue 214 and preserve the public API" \
  --accept "The regression test passes and no public export changes"

The Codex adapter uses non-interactive codex exec, a workspace-write sandbox and no per-command approval prompts. DoneState still enforces its own objective policy and stops at AWAITING_VERIFICATION until an independent signed attestation arrives.

For an explicit, reviewable contract:

donestate init
# Edit .donestate/objective.json and .donestate/policy.json
donestate run \
  --objective .donestate/objective.json \
  --policy .donestate/policy.json

Inspect, resume and hand off a run:

donestate status RUN_ID
donestate resume RUN_ID
donestate handoff RUN_ID --out verification-handoff.json
donestate attest --file signed-attestation.json
donestate verify-log RUN_ID

Run the bounded local demonstration:

npx donestate demo

The demo intentionally ends at AWAITING_VERIFICATION. Self-verification would defeat the product boundary.

Authority model

DoneState requests authority for consequences, not permission for every tool call.

| Authority | Typical consequence | Default | |---|---|---:| | local_read | Inspect repository state | Granted | | local_write | Edit workspace files | Granted | | test | Run bounded validation | Granted | | commit | Create a local commit | Granted | | push | Mutate a remote branch | Denied | | open_pr | Create a pull request | Denied | | merge | Merge a reviewed change | Denied | | deploy | Mutate a live environment | Denied | | publish | Publish a package or release | Denied | | secret_access | Expose configured secrets to an action | Denied | | destructive | Delete or irreversibly rewrite | Denied |

An envelope can be bound to the SHA-256 digest of one exact objective and can expire. Executables, repository roots, environment keys, argument patterns and action budgets are separately constrained.

Completion contract

SUCCEEDED means a command returned successfully. It does not mean the objective is proven complete.

A run reaches VERIFIED only when all of these are true:

1. Every admitted action settled successfully.
2. Reconciliation stayed within policy budgets.
3. DoneState sealed the exact execution snapshot.
4. An Ed25519-signed attestation matches that snapshot.
5. The signer fingerprint was pinned in the run policy.
6. The issuer is independent of DoneState and supplies evidence references.

See Architecture, Trust model and Threat model.

Product boundaries

Version 0.1.0 provides the durable local controller, process-harness adapter, policy enforcement, Git changed-file budget, tamper-evident event chain, recovery semantics, signed verification handoff and CLI.

It does not yet provide a hosted multi-tenant control plane, an operating-system sandbox, provider-native GitHub merge queue, managed verifier key service or secret broker. A publication action can call a separately configured tool, but remote publication remains denied until its authority class is explicitly granted.

AgentProof remains the transaction and signed-receipt layer for consequential actions. OpsTruth remains the independent read-only verifier. DoneState neither duplicates their roles nor treats its own observations as proof.

Development

npm install
npm run check

The package has no runtime dependencies. State uses Node's built-in SQLite binding with WAL, full synchronous writes, foreign keys and fenced leases.

Licence

Apache-2.0.