feat(agent-harness): persist command intents and execution receipts

[iscekic]

No new behavior — The apps do not use this recovery support yet.

---

Summary

HarnessClient adds serialized recovery through ClientOptions and CommandTransport; ClientResult and ClientProblem distinguish accepted, rejected, waiting, unsent, and unknown outcomes. Recovery never repeats uncertain effects; stale_revision message rejections require explicit review, while non-retryable access_revoked and retired rejections permit unrelated dispatch. Scope changes invalidate the client, storage failures block normal operations, and only a live readiness recheck can release a proven unstarted intent.

Files

• packages/agent-harness/src/client.ts — Added, 371 lines. Adds createHarnessClient and queued submit, recover, dispatch, and dispose operations. Injects scope tracking, storage, the bridge, the clock, and argument hashing; transport adapters must authenticate the supplied scope and reject ambiguous transport failures. Persists canonical commands before transport, then commits acknowledgments before removing intents; matching retries reuse replies, while changed payloads return command_conflict. Recovery processes stored receipts before evidence queries, replays pending commands with their original identifiers, and returns stale rejections until reviewedCommandId records explicit review. New dispatch checks ownership, the argument digest, expiry, tool state, and identifier reservations; it checks readiness before and after persisting the intent. Readiness loss before execution atomically releases only the current dispatch's intent; a crash leaves the intent unresolved. Existing executions retain their original grants and inputs; persisted receipts from another host take precedence over late executor results. Completion requires a matching stored receipt; invalid snapshots, revision regressions, or failed compare-and-swap block normal operations until recovery reads valid storage.

JournalScopeSchema, CommandIntentSchema, CommandReplySchema, ExecutionRequestSchema, ExecutionIntentSchema, and JournalSnapshotSchema define strict, scoped records for commands, grants, receipts, and recovery. HarnessJournal requires atomic durable reads and compare-and-swap writes; missing or corrupt storage is an error, never an empty replacement. A fresh storage generation requires a fresh client identifier; storage loss suspends the old registration and prevents reuse of its grants.

Files

• packages/agent-harness/src/journal.ts — Added, 125 lines. Adds inferred types and an immutable scope for the owner, client, and storage generation. Validates canonical input, acknowledgment identifiers, grant-to-tool matching, uniqueness, ownership, and stale-review links. Uses conversation and tool-call identifiers for execution keys; completionCommand requires a receipt and retains the reserved identifier and grant generation. Rejects completions without matching stored receipts and review links that do not reference a stale rejection in the same conversation. Requires a single durable transaction for scope and revision checks, explicit false for no write, rejection of uncertain commits, and no memory fallback.

ClientBridge separates execution from evidence-only receipt reconciliation; an unknown receipt never permits execution or grant transfer. BridgeReadinessSchema and BridgeReadiness define availability, foreground, connectivity, unlock, and gesture gates; unknown connectivity or unlock state blocks execution. Adapters must recheck the account, grant, and gates at the effect boundary, return only confirmed outcomes, and never retry effects internally.

Files

• packages/agent-harness/src/bridge.ts — Added, 28 lines. Adds bridgeWaitReason, with wait priority unavailable, background, offline, locked, then gesture. Separates readiness, execute, and reconcileReceipt; null from reconciliation means the outcome remains unknown.

Tests: 1 test file added, packages/agent-harness/src/client.test.ts (+970 lines). The handoff reports 155 passing client tests and five passing scoped checks.
Generated: 0 files changed.

---

Verification

• No manual tests ran because this level adds command and receipt recovery without deployed consumers.

Visual Changes

Visual Changes: N/A

Reviewer Notes

Human steps

None before or after merge.

Notes

E2E: This level adds command and receipt recovery without deployed consumers. Full runtime verification runs on the completed stack tip.

Stacked PRs — merge bottom to top. Each level shows only its own diff.

Runtime verification (E2E, user advocacy, simplify) runs on the tip PR over every level.
Every level keeps its own checks, its own bot review, and its own threads; each one is answered on its own PR.
Each level is its own deliverable: it builds and passes its own checks alone.
A finding on a level is repaired on that level, then carried upward with stack.sh forward.

1. shared-agent-harness-3bb0 — chore(agent-harness): register workspaces and enforce CI boundaries #5632
2. shared-agent-harness-3bb0-s2 — feat(agent-harness): define portable domain and snapshots #5637
3. shared-agent-harness-3bb0-s3 — feat(agent-harness): define commands tools and permission policy #5639
4. shared-agent-harness-3bb0-s4 — feat(agent-harness): share client state and cursor recovery #5643
5. shared-agent-harness-3bb0-s5 — feat(agent-harness): persist command intents and execution receipts #5647 ← this PR
6. shared-agent-harness-3bb0-s6 — feat(db): add harness ingress grants and retirement fences #5655
7. shared-agent-harness-3bb0-s7 — feat(agent-harness): deliver legacy history and project durable text #5659
8. shared-agent-harness-3bb0-s8 — feat(agent-harness): authorize durable grants and registered clients #5662
9. shared-agent-harness-3bb0-s9 — feat(agent-harness): fence retirement and retry payload cleanup #5667
10. shared-agent-harness-3bb0-s10 — feat(agent-harness): persist authoritative state in SQLite #5675
11. shared-agent-harness-3bb0-s11 — feat(agent-harness): admit durable runs and revisioned commands #5678
12. shared-agent-harness-3bb0-s12 — feat(agent-harness): recover queued runs and stream checkpointed steps #5688
13. shared-agent-harness-3bb0-s13 — feat(agent-harness): resolve interactions and dispatch tools sequentially #5693
14. shared-agent-harness-3bb0-s14 — feat(agent-harness): fence designated client tool execution #5697
15. shared-agent-harness-3bb0-s15 — feat(agent-harness): synchronize durable snapshots and legacy history #5701
16. shared-agent-harness-3bb0-s16 — feat(agent-harness): reuse authorized invitations with durable replay #5704
17. shared-agent-harness-3bb0-s17 — feat(integrations): bound repository transport for harness reads #5710
18. shared-agent-harness-3bb0-s18 — feat(integrations): expose bounded authorized repository reads #5714
19. shared-agent-harness-3bb0-s19 — feat(agent-harness): expose named authorized resource reads #5718
20. shared-agent-harness-3bb0-s20 — feat(sessions): bound history transport for harness reads #5724
21. shared-agent-harness-3bb0-s21 — feat(agent-harness): read scoped Cloud Agent context and progress #5726
22. shared-agent-harness-3bb0-s22 — fix(agent-harness): preserve ordered Cloud Agent dispatch identity #5731
23. shared-agent-harness-3bb0-s23 — feat(agent-harness): hand coding work to authorized Cloud Agent sessions #5733
24. shared-agent-harness-3bb0-s24 — feat(agent-harness): authorize scoped MCP gateway connections #5737
25. shared-agent-harness-3bb0-s25 — feat(agent-harness): bound MCP gateway transport in the Worker #5740
26. shared-agent-harness-3bb0-s26 — feat(agent-harness): execute validated remote MCP tools #5743
27. shared-agent-harness-3bb0-s27 — refactor(exa): share provider dispatch and usage recording #5746
28. shared-agent-harness-3bb0-s28 — feat(agent-harness): authorize bounded web provider requests #5747
29. shared-agent-harness-3bb0-s29 — feat(agent-harness): normalize web sources and preserve citations #5749
30. shared-agent-harness-3bb0-s30 — feat(agent-harness): define closed internal operation contracts #5753
31. shared-agent-harness-3bb0-s31 — feat(agent-harness): authorize internal maintenance operations #5754
32. shared-agent-harness-3bb0-s32 — feat(agent-harness): authorize named Kilo operation dispatch #5755
33. shared-agent-harness-3bb0-s33 — feat(agent-harness): authorize internal provider operations #5757
34. shared-agent-harness-3bb0-s34 — feat(agent-harness): secure the internal operations endpoint #5758
35. shared-agent-harness-3bb0-s35 — feat(agent-harness): bound and sanitize model streams #5767
36. shared-agent-harness-3bb0-s36 — feat(agent-harness): secure billed model inference #5776
37. shared-agent-harness-3bb0-s37 — test(agent-harness): cover model gateway security boundaries #5777 (tip)

[kilo-code-bot]

WARNING: Post-commit readiness throws leave a durable unstarted execution fence

After the execution intent commits, a second readiness() call that returns a wait reason releases the fence; a throw does not. Grant expiry and a non-finite clock throw access_revoked inside that helper, and malformed bridge readiness throws from BridgeReadinessSchema.parse. execute never runs, run() still reports outcome "unsent", and the journal keeps receipt: null.

Later recover/dispatch only call reconcileReceipt, which returns null → unknown. blocksUnrelatedDispatch then rejects unrelated tools as well. This live dispatch still knows execute was not called — the same proof the wait-release comment describes. Catch this throw, release the fence, and return access_revoked rather than unsent.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 1 Issue Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	1
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/agent-harness/src/client.ts	352	Post-commit readiness throws leave a durable unstarted execution fence

Files Reviewed (4 files)

• packages/agent-harness/src/bridge.ts - 0 issues
• packages/agent-harness/src/client.test.ts - 0 issues
• packages/agent-harness/src/client.ts - 1 issue
• packages/agent-harness/src/journal.ts - 0 issues

Fix these issues in Kilo Cloud

---

_{Reviewed by grok-4.6 · Input: 187.3K · Output: 25.5K · Cached: 436K}

_{Review guidance: REVIEW.md from base branch shared-agent-harness-3bb0-s4}

[iscekic]

Closing: the owner stopped this workflow section. The branch is retained.