Skip to content

Add the hand-off channel: a witnessed work tree with MCP tools - #87

Merged
Akilleez-QA merged 2 commits into
mainfrom
feat/handoff-channel
Nov 17, 2026
Merged

Akilleez-QA merged 2 commits into
mainfrom
feat/handoff-channel

Conversation

@Akilleez-QA

Copy link
Copy Markdown
Owner

Change

This PR adds Wave 2G, the hand-off channel. adapters/work_tree.py is an event-sourced work tree that agents use to pass work to each other. It is ported from the unreviewed feat/assignment-runtime draft and reworked. The tree lives beside the POODO cores, not inside one, because a core is per-domain and single-caller and has no parent or completion API. poodo_core/ is unchanged.

  • Nodes: one node per hand-off.
    • Lineage (owner|routine|outside plus the owner message id) is set at the root and copied unchanged to every child.
    • Modes are work|consult|notify; replies are resume|poll|none.
    • Artifacts are typed references, checked against an optional host artifact_names table.
  • Flow rules:
    • Wake-once: a waiting requester is woken once, when every child that replies has settled.
    • An overdue child chases its requester once.
    • Two idle continuations in a row fail a node.
    • An owner hold cancels the domain's open nodes and refuses new ones.
    • An owner answer is returned to the caller and never recorded.
    • The provenance line is written by the harness, and model text in it is escaped.
  • Enforced limits, each refused with a typed code:
    • loop: no hand-off back up the branch.
    • depth: depth cap.
    • unreachable: the host reachable map in handoff.json decides who a sender can hand off to.
    • root_full: at most 4 open nodes per root by default.
    • busy: one live node per bot.
    • Also shields, not_yours, state, mode, artifact, held, unknown.
  • Durability: the log is append-only, flock'd JSON lines. Reopening rebuilds identical state, a torn tail is set aside, and an out-of-order event is refused.
  • Witness: every event is also appended as an observation to the session LedgerPort, on stream <bot>.handoff. That is the witnessed node log when ledger.json exists. The work tree file stays the queryable store; the ledger is the witness. A missed witness is reported and can be detected with witness_gaps.
  • MCP:
    • The tools are handoff_create, handoff_start, handoff_status, handoff_wait (non-blocking), handoff_settle, handoff_park and handoff_answer.
    • They are listed only when <state_root>/handoff.json exists. There is a golden fixture for them.
    • The requester is stamped from the session and is never an argument.
    • Holds, releases, sweeps, idle-continuation counting, owner answers and root creation are host-only.
    • I made minimal edits to adapters/mcp_stdio_server.py (+39), following the existing MAIL_TOOLS pattern. A separate server would have duplicated the session and the transport.
  • Wiring: a small block in bootstrap.py (+13) and an aor_session.py attribute plus close (+3).

Requirements, design and interface impact

  • Requirement added: CS-REQ-087 (Hand-off channel). The lead assigned this number; the repin worker is renumbering its own requirement.
  • Design row added: SDD-C29 (Hand-off channel). SDD-C21 is taken; SDD-C25, C26, C28 and C31 are claimed by sibling branches or PRs.
  • Verification matrix: one new row.
  • contracts/ADAPTERS.json: new row handoff-work-tree.
  • MCP interface: new section "Hand-off tools" in docs/guides/explanation/server-and-adapters.md, plus a §4 mention in the SRS.
  • Data dictionary: regenerated, adding MAX_TEXT and MAX_ARTIFACTS.

Verification

All runs were local on macOS with Python 3.13, using a throwaway venv in a scratch dir. No model calls were made and the Anthropic credential environment variables were unset.

  • python -B -m unittest discover -s tests: 770 tests, 76 failures, 4 errors, 8 skipped. The baseline on origin/main (0a9703b) is 734 tests, 76 failures, 4 errors, 8 skipped, and the failing set is identical by test id. Those are the known workcell/forge environment failures on macOS. The 36 new tests all pass.
  • python -B -O -m unittest discover -s tests: same counts as the plain run.
  • python -B tools/check_trace.py: 78 requirements, 0 failures.
  • python -B tools/check_links.py: 0 broken links.
  • python -B tools/gen_data_dictionary.py --check: passes after regeneration.
  • tests/test_work_tree.py covers:
    • A scenario suite plus a seeded random walk (12 seeds × 250 steps). It checks invariants I1 (waiting has an open child), I2 (one report), I3 (one delivery), I4 (terminal outcome), I7 (replay equals state), H1 (nothing open in a held domain) and C2 (one live instance) after every step.
    • Durability: reopen, two hosts on one file, torn tail.
    • Witness completeness and the ledger budget.
    • Concurrency refusals.
    • MCP schemas against the golden fixture, refusals, a round trip between two bots, and witnessed streams.
  • gitleaks / TruffleHog: not run locally. CI runs them. I also scanned the diff by hand for personal data and secrets: the tests use only generic bot names.

Not done

  • There is no host CLI yet for owner holds, releases, sweeps or owner answers. These are Python calls on WorkTree, so a host must call sweep() itself to make chases fire.
  • Artifact names are not tied to an agents/artifacts.json single-writer table. Workstream A has not landed that table, so the host passes artifact_names in handoff.json.
  • There is no TruthFace work-state port, so this is listed as hard_wired (ADR 005 item 11c).
  • CI uses Python 3.12; I ran 3.13 locally.

Peer review record

  • Reviewers: pending human review. Agent-authored.

🤖 Generated with Claude Code

Cstack and others added 2 commits November 16, 2026 23:44
Agents hand work to each other through adapters/work_tree.py, an
event-sourced work tree that lives beside the POODO cores rather than
inside one (a core is per-domain and single-caller, with no parent or
completion API). Ported and reworked from the feat/assignment-runtime
draft.

- One node per hand-off. Lineage (owner|routine|outside, owner message
  id) is set at the root and copied unchanged to children. Modes are
  work|consult|notify, replies resume|poll|none, and artifacts are typed
  references checked against an optional host table.
- A requester waits on its children and is woken once when all its
  replying children settle. An overdue child chases its requester once.
  Two idle continuations fail a node. Owner holds cancel a domain and
  refuse new work there. Owner answers are returned, never recorded.
- Typed refusals: loop (back up the branch), depth, unreachable (host
  reachable map), root_full (default 4 open nodes per root), busy (one
  live node per bot), shields, not_yours, state, mode, artifact, held,
  unknown.
- Append-only, flock'd JSONL log. Reopening rebuilds the same state,
  a torn tail is set aside, and an event out of order is refused. Every
  event is also appended to the session ledger (stream <bot>.handoff,
  the witnessed node log when configured).
- The MCP server lists handoff_create/start/status/wait/settle/park/
  answer only when <state_root>/handoff.json exists. The requester is
  stamped from the session. Holds, releases, sweeps and owner answers
  are host-only.

Docs: CS-REQ-087, SDD-C29, matrix row, ADAPTERS.json row
handoff-work-tree, hand-off tools section in server-and-adapters,
regenerated data dictionary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings in #84 (Foundations MCP server), #85 (cstack init) and #86
(starter agents). Conflicts in docs/architecture/architecture.md and
docs/requirements/requirements.md resolved by keeping both sides:
component rows in SDD order (C26, C28, C29, C31) and requirements
CS-REQ-084 to CS-REQ-086 before CS-REQ-087. EXPORT-MANIFEST.json
regenerated with tools/build_export_manifest.py; data dictionary
--check passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Akilleez-QA
Akilleez-QA marked this pull request as ready for review November 17, 2026 08:48
@Akilleez-QA
Akilleez-QA merged commit 9c247cd into main Nov 17, 2026
2 checks passed
Akilleez-QA pushed a commit that referenced this pull request Nov 17, 2026
Brings in #84 to #87. Conflicts resolved by keeping both sides:
CHANGELOG.md entries; requirements and verification-matrix revision
rows renumbered so main's 2.2 (cstack init) stays and this PR's
CS-REQ-088 row becomes 2.3, with each document's Version set to 2.3.
EXPORT-MANIFEST.json regenerated with tools/build_export_manifest.py;
data dictionary --check passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant