[alexhraber]

Executive summary

Pincher now has an executable, versioned, test-proven governed-run boundary:

Decapod custody and governed context precede inference, and authoritative validation and proof precede readiness.

The implementation is deliberately one bounded deterministic provider turn. It does not claim to be a complete coding agent.

Architectural problem

The previous engine could accept an unbound intent, resolve context through concrete wrappers, call a placeholder model, and represent validation or proof as local booleans. That made the core boundary unable to prove that inference was governed or that readiness was authoritative.

This PR makes those requirements executable through typed ports, an explicit lifecycle, a versioned host contract, and deterministic fake-backed tests.

Ownership boundary

• Amnion owns the soft human-facing terminal UI/UX, rendering, and interaction policy.
• Pincher owns the governed run loop, typed state/outcomes/events, provider-turn port, and host contract.
• Decapod owns repository/session/task/work-unit/workspace custody, governed context, approvals, interlocks, validation, proof, and promotion truth.

Pincher does not add a UI, transport, daemon, parallel governance store, or real provider.

Governed-run lifecycle

The v1 contract is pincher.governed-run@1.0.0.

Prepared -> ContextResolved -> Executing -> Verifying -> Ready

Blocked paths use AwaitingApproval -> Blocked; failed paths retain typed causes; terminal outcomes can be HandedOff without erasing evidence.

Exact pre-inference gate ordering

1. Validate the versioned RunRequest.
2. Require session, task, work-unit, repository, and workspace custody references.
3. Ask Decapod to validate custody and confirm the isolated workspace is allowed.
4. Resolve governed context through Decapod.
5. Evaluate authoritative interlocks and allowed-next-operation semantics.
6. Resolve approval status; stop with a typed blocked outcome when required.
7. Construct GovernedInferenceRequest.
8. Invoke ProviderTurn only after all preceding gates succeed.

Provider output is an untrusted proposal. It cannot create approval, validation, proof, or readiness.

Readiness rule

Ready is reachable only after Decapod returns successful validation evidence and successful proof evidence, each retained by reference in the snapshot and event envelope. Local hashes, process success, provider assertions, host actions, and Pincher events cannot manufacture those facts.

Public API and compatibility changes

• Added governed_run with strong identifier newtypes, RunRequest, RunState, RunSnapshot, RunOutcome, typed blocked/failure/remediation values, versioned RunEvent, EventSink, DecapodControlPlane, ProviderTurn, and GovernedRunEngine.
• Added InMemoryEventSink and deterministic fake-backed integration tests.
• Deprecated the old unbound AgentEngine::execute(&str) path; it now fails closed and directs hosts to the governed contract.
• Removed local validated and attested authority booleans from the legacy governance state.
• Replaced local proof verification with a local-integrity-only state; Decapod remains the authority for proof truth.
• Stopped the legacy broker event emitter from printing to stdout; host-facing events use the explicit sink.
• Redacted legacy ModelConfig.api_key from serialization.
• Refreshed Decapod-generated metadata/spec fingerprints through decapod rpc --op specs.refresh.

Test matrix

• cargo test: pass; 1 unit test, 19 governed-run integration tests, and 0 doctest failures.
• cargo test --test governed_run_contract --quiet: pass; 19 tests.
• cargo clippy --all-targets -- -D warnings: pass.
• cargo clippy -- -D warnings: pass.
• git diff --check: pass.
• cargo fmt --check: fails on pre-existing formatting drift across legacy Decapod modules and the existing workflow example; unrelated legacy formatting was not rewritten.
• Contract coverage includes custody-before-provider ordering, every missing custody reference, blocking/advisory semantics, validation/proof requirements, typed failures, illegal transitions, deterministic event ordering, serialization, unknown events, secret absence, local-integrity limits, blocked/failed/ready handoff outcomes, and unsupported-adapter fail-closed behavior.

Decapod governance evidence

• Todo: bugs_01ky3bnzrzybw4pz
• Claimed agent: unknown
• Work unit intent: governed-run-contract-v1
• Workspace: agent/unknown/bugs-01ky3bnzrzybw4pz at the isolated Decapod worktree
• Proof plan: cargo-clippy, cargo-test, decapod-validate, governed-run-contract-tests
• Recorded proof: cargo-clippy pass, cargo-test pass, governed-run-contract-tests pass; decapod-validate fail recorded with local blockers.
• Latest specs refresh receipt: 01KY3DFCMZA34J0AKMDND5NMY3
• Latest generated-spec fingerprint: 9a5d7d51c64c895500d86c3b1bf40b14922d860d7043ed1094c7adf5ea2475fa
• Latest Decapod validation epoch: ve_7dcc26e459c7188e, 175 gates passed and 12 local/environment/governance failures remained.

The remaining Decapod failures are concrete environment/control-plane blockers: the installed validator reports generated-artifact whitelist rules that are visibly present in the repository, requires container-workspace proof, and reports pre-existing plan/proof debt from another done TODO. The repository CI runs its own decapod init --proof --force and validation path.

Follow-up issues

• #7: Prove the concrete Decapod adapter against current control-plane envelopes
• #6: Add the first real provider adapter behind the governed turn port
• #9: Define governed actions, tools, and patch proposals
• #8: Add approval resume, cancellation, retries, and idempotency
• #5: Define governed run reconstruction and event replay
• #4: Prove Pincher and Amnion host-contract compatibility

Explicit non-goals

No real Claude/Codex/Gemini/OpenAI/local-model adapter; no Amnion UI; no HTTP/WebSocket/MCP/gRPC/daemon transport; no tools or patch application; no autonomous multi-turn or multi-agent execution; no Pincher-owned governance persistence; no full retry/resume/replay/crash recovery; no production metrics; no direct promotion or merge behavior.

Known limitations and deviations

• The concrete Decapod CLI/RPC adapter is intentionally unsupported until its actual structured envelopes, receipts, interlocks, advisories, attestations, errors, and allowed-next-operation semantics are proven. The engine fails closed rather than inventing evidence.
• The provider is a deterministic fake/fixture port only.
• The current repository has legacy formatting drift outside this focused change.
• Local Decapod validation could not reach a clean result because of the blockers listed above.
• No Amnion source change is included because this PR establishes the producer contract; cross-repository consumer proof is explicitly tracked in issue feat: prove Pincher and Amnion host-contract compatibility #4.
• GitHub Decapod Validate workflow run 29874742366: pass (22 seconds), including the CI decapod init --proof --force and decapod validate path.