feat(agent-harness): fence designated client tool execution

[iscekic]

No new behavior — this change prepares device actions without enabling them in the product.

---

Summary

ClientToolCommand accepts claimClientTool and completeClientTool; ClientToolAuthorizer supplies ClientToolAuthority through AuthoritySchema, including authenticated identity and original journal availability.
Validation checks IntentSchema and rejects inconsistent grants, calls, or receipts before replay; revocation, journal loss, or incompatible capabilities also block replay.
Canonical replay skips dispatch preparation and new reservations but retains authority and fingerprint checks, so committed waits survive later policy failures or budget exhaustion.

Files

• services/agent-harness/src/client-tools.ts — adds command validation, scoped authentication before and after preparation, journal fingerprints, canonical replies, and structured rejections. Requires exactly one matching grant and attempt; validates ownership, context, input digest, definition version, generation, and immutable completion. Constructs client_action updates for waits and reconciliation.

commitDispatch accepts an optional ExecutionGrant inside the existing scheduler transaction, committing the grant, linked attempt, policy, and executing state atomically.
Each grant binds the client, account, conversation, context, input digest, tool version, and generation; existing backend callers continue without a grant.
Concurrent valid claims reuse the same committed grant rather than creating another attempt.

Files

• services/agent-harness/src/dispatch.ts — persists the grant and links its identifier to the existing attempt before the compare-and-set transition to executing.

clientTool and clientUnavailable extend the scheduler with ordered client_action waits and receipt settlement for the originating client.
Dispatch preparation reserves time before checks; ExecutionGrant.expiresAt keeps that deadline, interrupted preparation stays charged, and idle device waits consume no time.
Stop cancels undispatched work; expired or interrupted grants require receipt reconciliation, including client reads, without transfer or reexecution.

Files

• services/agent-harness/src/scheduler.ts — adds grant claims, validated immutable completions, and lifecycle notifications without a second scheduler. Persists background, offline, locked, gesture, unavailable, and reconciliation waits; clears client actions when they settle. Shares dispatch and settlement transitions, rechecks checkpoint scope, input digests, and call order, and keeps approval, permission-revision, and Stop gates. Reserves preparation before authorization and policy checks, bounds those checks, and retains the original grant deadline. Lost preparation retains its full reservation; failed checks and losing claims release only their own preparation. Only a committed grant takes the active lease. Accepts the original grant's validated receipt after expiry or Stop and preserves the actual outcome. Confirmed receipts resume waiting runs unless Stop blocks continuation; waits and uncertain outcomes continue to block later calls and runs.

Tests: 1 test file added: services/agent-harness/src/client-tools.test.ts (+1,326 lines). Covers SQLite claims, waits, receipts, replay, timing, Stop, corruption, crash recovery, and shared journal faults.
Generated: 0 files changed.

---

Visual Changes

Visual Changes: N/A

Verification

• No manual tests ran for this level. Full backend, browser, iOS, and Android verification awaits the completed stack tip.
• Live behavior and continuous integration for the current head are not verified.

Reviewer Notes

This description covers level 14 only, based on level 13.

Human steps

• after merge — Provision the Worker and scoped server configuration before later activation.
• before merge — No human steps are required for this level.

Recorded checks

The implementer recorded four passing scoped checks through run-checks.sh. This description round did not rerun them.

• pnpm --filter @kilocode/agent-harness-worker exec vitest run src/client-tools.test.ts — passed on the local SQLite test Worker.
• oxlint on the four changed files — passed.
• oxfmt --check on the four changed files — passed.
• git diff --check on the four changed files — passed.

Notes

E2E: bot-e2e — full backend, browser, iOS, and Android verification remains pending at 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
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 ← this PR
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 (tip)

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Files Reviewed (4 files)

• services/agent-harness/src/client-tools.ts
• services/agent-harness/src/client-tools.test.ts
• services/agent-harness/src/dispatch.ts
• services/agent-harness/src/scheduler.ts

---

_{Reviewed by grok-4.6 · Input: 315.3K · Output: 20.8K · Cached: 596.1K}

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