Phase 10.2A: restrict worker lifecycle authority on v0.20

[yshen92]

Summary

Phase 10.2A-local closes the H3 runtime handoff gap on the exact v0.20 line: a native Kanban worker can report only its own bounded complete/block result to the trusted dispatcher without receiving writable board-DB or graph-mutation authority.

The worker sends one identity-free, size-bounded Unix datagram. Linux SCM_CREDENTIALS and dispatcher-owned spawn state bind it to the exact PID/UID/task/run/profile/workspace/board/claim. The dispatcher revalidates current DB state atomically, then calls the existing canonical complete_task / block_task paths so artifacts, redaction, hooks, cleanup, events/runs, ready recomputation, typed blocking, and failure accounting remain unchanged. Liveness stays dispatcher/PID-owned; restricted workers do not write DB heartbeats.

Restricted mode is default-off under kanban.restricted_workers in config.yaml. Tool and DB guards are defense in depth. Activation remains blocked until the separately reviewed Phase 10.1 launcher drops UID before Python, execs with stable PID, kills children on parent death, denies DB/WAL/SHM access, and passes real restricted-UID raw-SQL/CLI/import preflight.

Exact provenance

• Upstream base: 3c27eb6234bf91b8ceee9e9071591b31e9b148cb (v2026.8.3, package 0.20.0)
• Exact recovered R0: 01edcadbd194f81bd7eceb9ca267737830ce24c0
• Immutable evidence ref: yshen92/hermes-agent:refs/heads/r0-evidence/v2026.8.3-01edcad
• Phase 10.2A runtime candidate: fe085446b864cb7d31f57499e407ce0f7275c511
• PR head/provenance record: e07ef7de52ca31b065b7f1545582ee7a5f66e341

The R0 object was fetched and verified directly. It was not reconstructed, amended, squashed, or rebased, and its evidence ref was not modified.

Reuse disposition

• Reuses v0.20 canonical completion/block/failure finalizers, task-run claims, PID supervision, artifact preservation, redaction, cleanup, hooks, and delegated-child guards.
• Adapts PR feat(kanban): allow orchestrator-only graph mutation policy NousResearch/hermes-agent#68029's worker/orchestrator graph separation for restricted mode as defense in depth.
• Adapts PR feat: add atomic Kanban terminal handoff NousResearch/hermes-agent#63297's useful task/run/profile/workspace/claim validation direction, while rejecting its parallel receipt store and duplicate finalization SQL.
• Adds no daemon, network listener, authorization DB, scheduler, capability registry, or second lifecycle implementation.

See REUSE_DISPOSITION.md, UPSTREAM_EXTRACTION_MAP.md, ADVERSARIAL_REVIEW.md, MAINTENANCE_DISPOSITION.md, and RUNTIME_PROVENANCE.md.

Verification

• Focused final suite: 93 passed, 1 skipped (Linux-only SCM credential integration skipped on macOS)
• Ruff: passed
• Python compilation: passed
• Windows footguns: passed across 913 files
• git diff --check: passed
• Independent Terra review of the comment-fix delta: no blockers; all four inline findings verified and addressed
• Prior GitHub CI: all required checks passed, including all eight Python slices, Windows footguns, contributor attribution, ruff/ty, JS/TS, docs, supply chain, OSV, history and lockfile checks

The review follow-up additionally binds each control channel to its board DB, turns artifact-preservation errors into dispatcher refusal events without losing scratch state, rejects restricted created_cards before handoff, and unifies false-like restricted-mode prompt parsing.

Boundaries

• No VPS deployment, gateway/runtime mutation, framework activation, service change, pilot, or provider/model call was performed.
• This is the blocking local source track only. Any upstream NousResearch contribution is separate and non-blocking.
• Do not start Phase 10.2B until this PR passes independent review and merges.

[yshen92]

Multi-pass review — Phase 10.2A restricted worker lifecycle

Reviewed at head ba3c3278 against base 01edcadb (full diff, all 17 files) in three passes: core-runtime review, supporting-files review, and an adversarial verification pass that attempted to refute each candidate finding (the two behavioral findings below were reproduced with executable repros against this tree, not just traced).

What checked out clean:

• The claim-binding CAS is genuinely atomic: _validate_restricted_binding is advisory and every predicate is re-checked inside the complete_task/block_task UPDATE WHERE clauses under write_txn. No TOCTOU.
• SCM_CREDENTIALS binding is sound against sibling/grandchild forgery (kernel stamps sender PID/UID at send time; socketpair is inheritance-only), and multiple/oversized/foreign datagrams all fail closed.
• Heartbeat-less liveness works: release_stale_claims extends live-PID claims (hb None never trips the stale backstop), detect_stale_running skips live bound workers, and enforce_max_runtime + mandatory positive max_runtime_seconds remain the hard bound (dispatcher-restart story covered by tests).
• The claim-expiry refusal race is intentional and test-covered (test_claim_expiry_is_rechecked_inside_finalizer_cas) — considered and discarded as a non-finding.
• Default-off wiring is provable: the env var is only ever set under restricted_worker_config() gating; default config path cannot set it. Supporting files (CI base_sha fix, attribution script/mapping, prompt guidance, config version bump) are all consistent and injection-safe; docs make no claim the code doesn't back.

Findings (4): one medium (dispatcher tick abort on worker-declared artifacts), one medium multi-board scoping issue, and two minor — see inline comments. None are activation blockers given the feature is default-off and externally gated on the Phase 10.1 launcher, but the two medium ones are worth fixing before 10.2B builds on this channel.

CI at this head is green (the earlier Review label gate failure was the pre-label run; the label rerun passed).

[yshen92]

[medium] Worker-declared artifacts can abort the whole dispatch tick via uncaught ArtifactPreservationError.

complete_task here runs with worker-supplied metadata["artifacts"] (merged in _normalize_restricted_result). For a scratch-workspace task, _persist_scratch_completion_artifacts raises ArtifactPreservationError when a declared path resolves inside the workspace but is missing, a directory, or oversized — and nothing between this call and the top of _dispatch_once_locked catches it. The direct-worker path has a dedicated except kb.ArtifactPreservationError in tools/kanban_tools.py (~L795) that returns a tool error the live worker can correct; this new dispatcher-side route into the same raise has no equivalent guard.

Reproduced end-to-end on this tree: tick 1 — dispatch_once raises (gateway's broad except logs "tick failed" and the board skips reclaim/spawn/crash accounting for the tick; binding not popped, channel not closed, datagram already consumed); tick 2 — refusal lands as the misleading "lifecycle channel unavailable: BlockingIOError", then protocol-violation accounting reruns the task and the worker's handoff is permanently lost. The trigger is routine, not adversarial — an LLM naming a deliverable it never wrote is common (it's exactly what the tool-layer guard exists for), and there is no test covering a missing/directory/oversized artifact in restricted mode.

Suggested fix: catch ArtifactPreservationError (or Exception) around the finalizer call in _apply_restricted_worker_result and convert it into a normal (False, reason) refusal so it flows into the existing lifecycle_result_refused event path.

[yshen92]

Addressed in fe08544. The restricted completion path now catches only ArtifactPreservationError around the canonical complete_task call and returns a normal refusal. The regression drives an authenticated clean-exit result through process_restricted_worker_results and verifies the task remains running, scratch workspace survives, the binding is cleaned up, and lifecycle_result_refused records the missing artifact.

[yshen92]

[medium] _restricted_worker_bindings is process-global but processed per-board connection — cross-board result destruction in multi-board gateways.

process_restricted_worker_results(conn) iterates every binding in the process, but conn belongs to whichever board is ticking (gateway/kanban_watchers.py runs _tick_once_for_board per board in one process, each with its own connection). When board A ticks first after board B's restricted worker exits cleanly, A's tick consumes B's datagram, validates binding.task_id against A's DB, fails with "task no longer exists", records the refusal event against the wrong board, pops the binding, and closes the channel — B's completed work is permanently lost and later surfaces as a protocol violation on B.

Single-board deployments are unaffected. Suggested fix: record the board/DB identity in RestrictedWorkerBinding at spawn time and have process_restricted_worker_results skip bindings that don't belong to the ticking board's DB path.

[yshen92]

Addressed in fe08544. RestrictedWorkerBinding now captures the canonical board DB path at spawn, and process_restricted_worker_results derives the ticking connection's main DB path and skips nonmatching bindings before reading or closing their channels. The two-board regression proves board A leaves board B's result intact and board B then finalizes it.

[yshen92]

[minor] created_cards is forwarded here but the dispatcher unconditionally refuses it — pre-reject it like board.

_normalize_restricted_result refuses any non-empty created_cards ("restricted workers cannot claim created cards"), but only after the worker has received ok: true / status: "pending_dispatcher" and exited — at which point the entire completion is discarded and the task ends refused → protocol-violated → rerun (verified by repro). board is already pre-rejected a few lines up in this same branch; created_cards deserves the same synchronous rejection so the model gets an immediate tool_error it can correct in-loop. Likelihood is low (kanban_create is hidden in restricted mode so there are no real ids to pass), but KANBAN_COMPLETE_SCHEMA's description still invites populating the field, and the cost when it fires is a lost run.

[yshen92]

Addressed in fe08544. Restricted kanban_complete now rejects non-empty created_cards synchronously before emit_result, with a regression asserting no lifecycle handoff is emitted.

[yshen92]

[nit] Raw env truthiness diverges from is_restricted_worker().

This gate (and the agent_init-bypass fallback in agent/system_prompt.py) treats any non-empty HERMES_KANBAN_RESTRICTED_WORKER as restricted — including "0"/"false"/"off" — while kanban_lifecycle.is_restricted_worker() parses only {"1","true","yes","on"}, so those values yield the restricted system prompt while the tool/DB layers run in normal direct mode. Nothing shipped hits this (the dispatcher only sets "1") and the divergence fails safe (guidance stricter than reality), so purely a consistency nit: call is_restricted_worker() here instead. The raw-truthiness ImportError fallbacks elsewhere are correct as written — they intentionally fail closed.

[yshen92]

Addressed in fe08544. Both agent initialization and the system-prompt fallback now use kanban_lifecycle.is_restricted_worker(), while the ImportError fallback remains fail-closed. False-like values (false/0/off/no) are covered by regression tests.

[yshen92]

Round 2 — 4 resolved, 0 still present, 0 new

Re-reviewed the delta ba3c3278..e07ef7de (fe085446b fix + e07ef7de5 provenance refresh) against the round-1 findings. Every prior finding is fixed at the flagged site with a dedicated regression test:

Finding	Status	Fix verified
F1 (medium) — uncaught ArtifactPreservationError aborts dispatcher tick	✅ RESOLVED	_apply_restricted_worker_result now catches it and converts to a (False, reason) refusal, so it flows into the normal lifecycle_result_refused event with the real artifact reason instead of killing the tick. Test: test_artifact_preservation_failure_refuses_result_without_aborting_tick asserts no raise, task still running, binding cleaned, and the refusal payload names the missing artifact.
F2 (medium) — cross-board binding consumption in multi-board gateways	✅ RESOLVED	RestrictedWorkerBinding now carries board_db_path (realpath, captured at spawn), and process_restricted_worker_results resolves the ticking connection's main DB via PRAGMA database_list and skips foreign bindings — failing safe (no consumption) when the path can't be resolved. Test: test_dispatcher_processes_restricted_results_only_for_matching_board asserts board A's tick leaves board B's channel unread and binding intact.
F3 (minor) — created_cards forwarded then always refused post-exit	✅ RESOLVED	Tool-level pre-reject added beside the existing board rejection, so the model gets an immediate tool_error in-loop. Test: test_restricted_complete_rejects_created_cards_before_handoff.
F4 (nit) — raw env truthiness vs is_restricted_worker()	✅ RESOLVED	Both agent_init and the system_prompt fallback now use the lifecycle parser (system_prompt keeps a fail-closed ImportError fallback; agent_init already imports hermes_cli unconditionally, so no new coupling). Parametrized test covers false/0/off/no.

No new issues found in the delta. The provenance doc correctly advances the runtime candidate to fe085446b and describes the hardening accurately.

Verification: focused suite run locally at e07ef7de — 33 passed, 1 skipped (Linux-only SCM credential integration). CI was in progress at post time with no failures; nothing in this delta touches the previously-green non-Python lanes.

Verdict: LGTM — all blocking findings resolved; nothing outstanding from my review. (Own-PR review, so this comment stands in for approval.)