kenaz 0.0.0-stage → 0.3.2

package/core/dev/specs/peer/MODS_SPIKE.md

@@ -0,0 +1,133 @@
+# Claude Code mods spike (TASK_2225)
+
+Date: 2026-10-03. CLI: Claude Code 2.1.288 (Windows 11). Status: spike report, no production code changed.
+
+Question: can a Claude Code mod (function-hooks plugin, CLI >= 2.1.287) running inside each
+Ansuz session replace (a) the peer wake helper (`peer_wake.rs`, a `claude -p` helper calling
+ListAgents + SendMessage) and (b) the peer pull in the `UserPromptSubmit` hook
+(`.claude/hooks/turn-context.js` -> `GET /api/peer/pending`)?
+
+## Reproduce
+
+- Probe mod: `dev/spikes/mods/kenaz-mod-probe/` (`claude plugin validate` passes; not installed globally).
+- One-shot run: `claude -p --plugin-dir dev/spikes/mods/kenaz-mod-probe --output-format json "<ask for the MODPROBE_CONTEXT line>"`.
+- Long-lived idle run: `node dev/spikes/mods/drive-probe.js <repo> 80000`. This opens a stream-json session, sends one prompt,
+  then holds stdin open for 80 s so the session sits idle but alive.
+- Evidence: `dev/spikes/mods/evidence/probe-<sessionId>.jsonl` (written by the mod itself) and
+  `evidence/stream-cebdf1f7.jsonl` (the session's stream-json output).
+
+The probe records: `session.start` -> `$.session.id/cwd`; `$.http.fetch` to the backend plus a closed
+port as a negative control; `$.clock.every(10s)` capped at 6 ticks; a `prompt.submit` hook that adds a
+per-load random token as context; `$.clock.after(15s)` -> `$.prompt.submit(...)`.
+
+## Step 1: doc claims vs live behaviour
+
+| Claim | Verdict | Evidence |
+|---|---|---|
+| A `prompt.submit` hook can add context that only the model reads | **VERIFIED** | Run `006a6e65`: the model replied `MODPROBE_CONTEXT token=8ayfzh14 session=006a6e65-…`. The token is random per load, so the model cannot guess it. The user never sees it. |
+| `$.http.fetch` reaches `127.0.0.1:18080` | **VERIFIED** | `/api/health` returned `200 {"status":"ok","service":"kenaz-dashboard","version":"0.2.257",…}`. The control fetch to `127.0.0.1:1` rejected with `ECONNREFUSED`, so the success is not vacuous. |
+| `$.session.id()` equals the hook payload / harness `session_id` | **VERIFIED** | The mod recorded `id=006a6e65-d807-…`, identical to `session_id` in the `claude -p` JSON output. Run 2 shows the same: mod `cebdf1f7-…` equals the stream-json `init session cebdf1f7-…`. |
+| `$.clock.every` runs background timers | **VERIFIED** | Run `cebdf1f7`: 6 ticks at +10.0 s spacing (`1791014909642` … `1791014959648`), then `cancel()` stopped it. Ticks kept firing while no turn was running. |
+| `$.prompt.submit` waits until the session is idle and starts a new turn with no user input | **VERIFIED (SDK host + real TTY)** | TTY run `eb21147d` (2026-10-03, see caveat 1): idle submit started a turn and the model answered. SDK run `cebdf1f7`: turn 1 ended with `result: success READY`. At +15 s the mod logged `submit.call`, and `submit.result` came back with `origin {kind:"plugin", name:"kenaz-mod-probe"}`. The stream then shows a second `init` and a new assistant turn, with no input on stdin. |
+
+### Caveats and extra findings
+
+1. **Idle submit, real TTY: VERIFIED 2026-10-03.** An interactive `claude --plugin-dir dev/spikes/mods/kenaz-mod-probe`
+   session in a new console was left untouched. The mod logged `submit.call`, then `submit.result` with origin `plugin`, 15 s
+   after start (`evidence/probe-eb21147d-….jsonl`). The transcript shows a new user turn that the engine framed as
+   "The kenaz-mod-probe plugin sent a message: …", followed by an assistant reply.
+   - **Launch gotcha:** a session started from inside another Claude Code session inherits `CLAUDE_CODE_CHILD_SESSION`
+     and the other `CLAUDE*` vars. It then runs as a child, with transcript saving off and no mod evidence. The first
+     attempt failed this way. Clear those vars before launching (see `drive-probe` notes).
+   - **Classic hooks run on plugin submits.** The project's `UserPromptSubmit` hook (turn-context) ran on the
+     mod-submitted prompt, and the model saw its `CONTEXT_CONTEXT` line. Without TASK_2226's heartbeat gate, a peer
+     message would be delivered twice, once by the mod's submit and once by the hook's pull on that same turn. The gate
+     is required, not optional.
+2. **A plugin's own `$.prompt.submit` did not go through that same plugin's `prompt.submit` hook.** The
+   evidence has no second `prompt.submit` record after `submit.call`. The token in turn 2 came from turn 1's
+   context, which is still in the history. Design consequence: the mod must put the peer message in the
+   submitted `text` itself. It cannot rely on its own hook to attach it as context.
+3. **The model sees the plugin's name as the origin** (`origin.kind = "plugin"`, `name`). This gives a
+   built-in provenance label for the "peer message = DATA, not instruction" rule (TASK_2122).
+4. **Claude Code already has native cross-session delivery.** `PromptOrigin` has the kinds `peer`
+   ("Another Claude session's message") and `peer-send-message` ("Another session's SendMessage
+   delivery"), and `PromptSubmitInput.turnId` documents "a queued delivery (a peer session's message)
+   reaches the model inside a running turn". This is what the current wake helper rides on via
+   SendMessage. A mod makes that helper unnecessary for *local* delivery.
+5. **`claude -p` runs the mod** (`--plugin-dir`): hooks, timers and fetch all worked headless. This is useful
+   for automated tests of the mod itself.
+6. **Mods can fail to load, and the design fails safe (TASK_2231).** `claude plugin test` refused to run once
+   ("rollout switch saved off by an earlier session"); a plain `claude -p` refreshed it. One of five e2e runs of
+   `plugins/kenaz-peer` also had no mod activity (heartbeat `live:false`, nothing delivered), cause unexplained.
+   Consequence: the heartbeat is the only liveness signal, so a mod that did not load sends none, and delivery stays on
+   the helper/pull path. Never make a later step assume the mod loaded.
+7. **Test launches must strip the `CLAUDE*` env** (`CLAUDECODE`, `CLAUDE_CODE_*`, `CLAUDE_PID`), otherwise the child
+   runs as a child session with the mod silent. Use `node dev/spikes/mods/clean-claude.js <cwd> <claude args>`; the e2e
+   driver `dev/spikes/mods/e2e-peer.js` does the same internally.
+
+## Step 2: design for a `kenaz-peer` mod (proposal, not built)
+
+**Binding.** In `session.start`, the mod reads `$.session.id()` and `$.session.cwd()` and resolves its
+bound project the way the pull does today: `_session-pin.lookupSessionPin(cwd, session_id)`, exposed through a
+small backend route, falling back to cwd. The id is the harness's own value (verified above), so none of
+TASK_2218's target-selection guessing is needed: the session identifies itself.
+
+**Delivery loop.** Every N seconds (`$.clock.every`, e.g. 5 s):
+1. `GET /api/peer/pending?projectPath=<bound>&peek=true`. This reads without acking (TASK_2217 contract).
+2. If messages are waiting, call `$.prompt.submit({ text: <framed batch> })`. The engine holds the submit until the
+   session is idle; a mid-turn delivery is queued, not interleaved.
+3. When `submit` resolves (the prompt entered the session), ack the delivered ids.
+   **Backend gap:** today the non-peek `GET /pending` is take-and-ack in one step. The mod needs an
+   ack-by-id route, e.g. `POST /api/peer/ack {ids}`, so a crash between peek and submit cannot lose a message.
+   This is the only backend change on the critical path.
+
+**Pull path.** The same mod's `prompt.submit` hook replaces the turn-context peer pull for user-typed prompts.
+It peeks, attaches the messages as `context` (verified), and acks them. This retires the per-install-layout
+`UserPromptSubmit` registration problem from the TASK_2218 review for peer messages.
+
+**Coexistence and retirement of `peer_wake.rs`.** The mod sends a heartbeat on its timer:
+`POST /api/peer/mod-heartbeat {session_id, project}`. `peer_wake::wake_session` skips projects with a
+live heartbeat (< 2 ticks old) and keeps today's helper as the fallback otherwise. Likewise, turn-context.js
+skips its peer pull when a heartbeat exists for its `session_id`. Once installs report the mod as
+present, delete the helper path. That removes the `.cmd` argv handling (TASK_2217), console windows,
+haiku-per-push cost, and permission-mode holds.
+
+**Distribution.** Ship the mod as a plugin inside kenaz-core and have the installer write
+`enabledPlugins` (user scope). On CLI < 2.1.287 the mod does not load, so no heartbeat is sent and the
+backend keeps using the helper plus the pull, with no behaviour change. The installer can log
+`claude --version` so the dashboard shows which path each machine uses.
+
+**Remote peers are unchanged.** The relay, `peer_poller` storing into the local inbox, and the send-side gates
+(`evaluate_send_gate`) stay as they are. The mod only replaces the last hop from the local inbox into a live session.
+
+## Step 3: moving the whole hook chain into mods
+
+Mods can hook every settings-hook event as `classic.<Event>` (for example `classic.PreToolUse`). They
+return the same fields, such as `additionalContext` and `block` (types: `ClassicResultFields`), so the
+shape of each hook ports 1:1. But mods run with no Node runtime. turn-context, memory-guard,
+pulse-before-*, task-bridge and the handoff hooks are Node scripts that use `require`, the filesystem and
+local modules. Porting them means either a rewrite against `$.fs`/`$.http`, or `$.process.run(['node', script])`.
+The second option recreates today's hook with an extra hop.
+
+**Recommendation: no-go for now.** The install-layout problem is real, but it hurts only the peer pull,
+and Step 2 removes that dependency. Keep the other hooks in `.claude/settings.json`. Revisit hook by hook
+only when one becomes cheap to express against `$.*`, for example the SessionStart HTTP ping, which is
+already a single fetch.
+
+## Go / no-go
+
+**GO for Step 2** (peer delivery mod), in phases:
+1. Backend: `POST /api/peer/ack {ids}` plus `POST /api/peer/mod-heartbeat`, and make `peer_wake` and turn-context
+   skip their peer work for heartbeat-live sessions.
+2. Mod: `kenaz-peer` in kenaz-core (peek -> submit -> ack loop, pull via the `prompt.submit` context hook),
+   with `claude plugin test` coverage.
+3. Installer: write `enabledPlugins`; report the CLI version.
+4. Confirm in a real terminal (caveat 1), run a two-machine Ashfall test, then delete the helper path.
+
+Fallback for CLI < 2.1.287: today's path, chosen automatically by the heartbeat being absent.
+
+**NO-GO for Step 3** (whole-chain migration), for the reasons above.
+
+## TASK_2241 - the LLM push helper is unsafe for framing integrity
+
+Observed live on 0.2.259: the `claude -p` helper delivered a paraphrase of a bridge reply WITHOUT the `[Peer message ...]` header and fence; the verifier rejected it only after `SendMessage` had already delivered it. Framing is what keeps peer text as data, and an LLM in the path cannot guarantee it. Mitigations in the helper path (bridge stand-down to a live core mod, a one-line "delivered unverified" notice on the rolled-back redelivery, sha256 audit of expected vs delivered text) reduce but do not remove the risk. Only the mod path (deterministic exact framed text, engine-stamped origin, no LLM) closes it, which raises the priority of the TASK_2234 mod rollout.

package/core/dev/specs/peer/PER_PROJECT_ADDRESSING.md

@@ -0,0 +1,143 @@
+# Per-project peer addressing (TASK_2237)
+
+Status: option B implemented behind wire compatibility; awaiting user review of the open questions at the end.
+
+## 1. Problem
+
+Peer messages are addressed to a **machine** (`node_name`), not to a project folder. Two project folders on one
+machine that belong to the same Yggdrasil room cannot be told apart, and only one of them receives. Field case
+(node gamem-DESKTOP-1TR25AE, thread 0b849325): `C:\project\Ashfall` (ART) and `C:\project\Ashfall_code` (CODE)
+share room `github.com/xyz9516/Ashfall` and one `node_name`. Art questions were injected into the CODE session
+and arrived twice (turn-context pull plus UDS helper push). This is a plausible contributor to field report
+TASK_2206 (one-way messages).
+
+## 2. Current model (before this task), with evidence
+
+| Fact | Evidence |
+|---|---|
+| `node_name` is one per machine by design (global git user.name, then os user, then hostname) | `mcp_tools/pool.rs:311-326` (TASK_2124 comment) |
+| Send writes `to_node = <machine name>`, `project = <room>`; payload is only `kind/body/refs/reply_to` | `mcp_tools/peer.rs` `send_with_cfg` |
+| Poll runs once per room: roots resolving to the same `(http_base, project_key)` are deduped, the first root polls and stores into **its** inbox only | `peer_poller.rs` `poll_all_rooms` (`seen_rooms` HashSet) |
+| Poll query is `task_events?to_node=<node>&project=<room>&include_acked=0` | `peer_poller.rs` `poll_with_cfg_bounded` |
+| Relay matches `to_node` exactly and scopes by team and project | `yggdrasil-relay/src/routes/task_events.rs:236` |
+| Ack is per event and removes it for every poller of that `to_node` (`WHERE ... AND to_node = ?4`) | `task_events.rs:294-298` |
+| Relay validates `to_node` against the `nodes` table (team-scoped) on create | `task_events.rs:110-114` |
+| Relay stores `payload` verbatim as `payload_json` and returns it unchanged; only a size cap applies | `task_events.rs:85-90, 100` |
+| Bridge roots (TASK_2157) only let a session at the CORE root drain bridge inboxes; they do not split one room between two ordinary projects | `routes/peer.rs` `select_bridge_roots` |
+
+Consequences: (1) a message to the machine reaches only the first-listed root; (2) a send from local project A to
+local project B has `from_node == to_node` and lands in the first root (possibly A itself); (3) a reply cannot
+choose A or B; (4) the second root's `peer_poll_state` is never advanced, so any attempt to poll it too would
+contend for acks with the first poll.
+
+Reproduction is in tests (no live registry or relay touched): see section 7.
+
+## 3. Options for identity
+
+### Option A: `node@project-instance` as the relay-level node id
+`to_node` becomes e.g. `gamem-DESKTOP@a1b2c3d4e5f6`; each root registers its own presence row and polls its own
+`to_node`.
+- Wire: old nodes only know machine names. A message to `machine@proj` is rejected by the relay (`to_node` must
+  exist in `nodes`), so old senders cannot reach a new node unless the machine row is kept as well.
+- Relay: presence/nodes table grows one row per root (the node list UI, `kenaz_pool_nodes`, claim ownership
+  `created_by = node_name` all assume one row per machine); `to_node` matching works unchanged but every
+  consumer of node names (pool claims, TASK_2139 stale-identity drain, mute/block lists) changes meaning.
+- Ack: becomes per instance, which fixes the shared-ack problem for free.
+- Pin/mod: the session pin picks an instance by construction.
+- Cost: relay deploy plus a new node-identity concept across pool, presence, UI. Highest blast radius.
+
+### Option B: machine node plus a project sub-address in the event payload (recommended)
+`to_node` stays the machine name. The payload carries `from_project` (instance id), `from_project_label`
+(folder name, display only) and optional `to_project`. Routing is client-side.
+- Wire: additive JSON fields inside `payload`. Old nodes ignore them (verified: they only read `kind`, `body`,
+  `refs`). The relay stores payload verbatim (section 2), so **no relay change**.
+- Relay: none. `to_node` matching, `nodes` rows, size cap, TTL and ack semantics are untouched. Ack stays
+  per event per machine, which is fine because ONE poll per room per machine remains the only poller.
+- Pin/mod: the receiving Ansuz sees `from node@label (project <id>)` in the framed header and replies with
+  `kenaz_peer_send toProject=<id>`; the sender needs no registry lookup. The session pin / kenaz-peer mod keep
+  working per root because each root has its own inbox, so a pull at root X only sees rows delivered to X.
+  Bridge roots (TASK_2157) are just another local root in the room and are routed like any other.
+- Weakness: addressing is advisory, not enforced by the relay (a sender can omit or forge `to_project`);
+  acceptable because peers are team-claimed and all content is already framed as untrusted.
+
+### Option C: a separate relay route / per-instance mailbox
+Rejected: new relay surface for no benefit over B at current scale.
+
+| | A: node@instance | B: payload sub-address |
+|---|---|---|
+| Old node can send to a new node | only if the machine row is kept | yes, unchanged |
+| New node can send to an old node | needs the old machine name | yes, fields ignored |
+| Relay change | yes (presence, pool, UI semantics) | none |
+| Ack isolation per project | yes | no (not needed, one poll per room) |
+| Rollback | hard (rows, ids) | trivial (stop reading fields) |
+
+## 4. Instance id
+
+Folder names are not safe: `Ashfall` vs `Ashfall_code` differ by a suffix and the same name can repeat on other
+machines. The id is the **first 12 hex chars of sha256 over the normalized absolute root path** (forward
+slashes, no trailing slash, lower-cased on Windows). Properties:
+- Same function on send and receive (`mcp_tools/peer.rs::project_instance_id`), derived from the root the
+  existing `resolve_peer_project_root` already agrees on; no new stored state, nothing to migrate.
+- Full local paths never go on the wire; the folder name travels only as `from_project_label` for display.
+- Not portable across machines by design: it identifies a local root, and the remote peer only echoes it back.
+- Weakness: moving or renaming a folder changes the id. In-flight replies then name an unknown id and fall back
+  to "all roots" (below), so nothing is lost. A `project.yaml` uuid would survive moves; see open questions.
+
+## 5. Behaviour (implemented)
+
+Send (`send_with_cfg_addressed`, MCP `kenaz_peer_send`):
+- payload adds `from_project`, `from_project_label`, and `to_project` (null unless `toProject` is given).
+- `toProject` is validated against the peer-id charset; `to_node` is still the machine name.
+
+Receive (`peer_poller.rs`, `route_roots`):
+- Still ONE GET and one ack per event per room; all local roots of the room are collected in `poll_all_rooms`.
+- `to_project` matches a local root's id: delivered only to that root.
+- `to_project` absent (legacy sender, first contact): delivered to **every** local root in the room, one inbox
+  row each (same relay id, separate sqlite files, so no PK clash). A single-root machine behaves exactly as before.
+- `to_project` present but unknown: delivered to all roots and logged at info.
+- Mute/block is evaluated per destination root. If an inbox cannot be opened the event is not acked, so it is
+  retried next tick (INSERT OR IGNORE dedups the inboxes that succeeded).
+- The sender's own outbound row (`direction='out'`, id `out:...`) is never inbound; a same-machine A to B message
+  returns from the relay on the normal poll and lands in B only.
+- Inbox schema gains nullable `from_project`, `to_project`, `from_project_label` (idempotent ALTER migration).
+  The pending API adds `from_project` and `from_project_label`; the framed header becomes
+  `from <node>@<label> (project <id>)` when the sender is a new node, otherwise unchanged.
+- Wake/push (peer_wake, codex_wake) now batches per destination root, so each project is woken with its own messages.
+
+Not addressed here: the double delivery in the field report (pull plus UDS push) is a separate TASK_2223 path;
+delivering the same message to two roots does not change its per-inbox claim/ack logic.
+
+## 6. Migration and interop
+
+| Sender | Receiver | Result |
+|---|---|---|
+| old | old | unchanged |
+| old | new | no `to_project`: delivered to all local roots of the room (previously: first root only) |
+| new | old | extra fields ignored; old node behaves as today |
+| new | new | addressed delivery; unaddressed first contact reaches all roots |
+
+No flag day: rollout is per node, in any order. The only behaviour change for an old sender is that a new
+multi-root machine now shows its messages in every root of the room instead of one, which is the safer failure
+(duplicate visibility rather than silent misrouting). Rollback = deploy the old build; rows with the new nullable
+columns are ignored by it.
+
+## 7. Tests (peer_poller.rs `e2e_stub_relay`, filter `task_2237`)
+
+- `task_2237_addressed_message_lands_only_in_the_matching_root` (ART/CODE-style fixture, one GET per room)
+- `task_2237_local_a_to_b_lands_in_b_only_with_sender_project` (outbound row not re-stored; sender shown)
+- `task_2237_unaddressed_and_unknown_to_project_reach_all_roots` (legacy event without sub-address; no redelivery)
+- `task_2237_project_instance_id_is_stable_across_path_variants`
+
+The pre-fix characterization of the defect (second root empty, `from_node == to_node`) was converted into these
+assertions once the fix landed.
+
+## 8. Open questions for the user
+
+1. Instance id stability: is path-hash acceptable (breaks on folder move), or should a uuid in
+   `.kenaz/project.yaml` be minted and used instead (survives moves, needs a one-time write per project)?
+2. Unaddressed messages now fan out to every root in the room. Prefer that, or fan out only to roots with an
+   active session, or keep a per-room "default root" setting?
+3. Broadcast (`to='*'`) is per machine row today; should it ever fan out to specific projects? (Left unchanged.)
+4. Do we want the relay to eventually validate `to_project` (Option A style) once most nodes are upgraded, or
+   keep addressing advisory?
+5. Same-machine delivery uses a relay round trip (needs network). Acceptable, or add a local short-circuit?

package/core/dev/specs/peer/SWARM_PROTOCOLS.md

@@ -0,0 +1,256 @@
+# Swarm-coordination protocols for Yggdrasil: evaluation (TASK_2228)
+
+Status: DESIGN ONLY, for user review. No protocol or production code is changed by this document.
+Date: 2026-10-03. Baseline: main at fb7867827 (TASK_2227 merged).
+
+Question asked: should Yggdrasil peer collaboration borrow from slime mould, bees and ants?
+
+Short answer: the one mechanism that paid off is the lease-style claim (a), and it paid off only after
+being tuned to human absence rather than to biology. For (b)-(f) I found no field report or peer log
+showing the failure each would prevent, and at 2-5 nodes most of them lose the property that makes them
+work in nature. One cheap, flag-only slice is recommended at the end to collect the missing evidence.
+
+## 0. Ground rules used in this document
+
+- "Current behaviour" claims cite a file and line in the main repo, or a field report. Field reports
+  are cards tagged `field-report` in `.kenaz/tasks/cancel/` (TASK_2205, 2206, 2207, 2208, 2212, 2132).
+  Those cards are duplicate re-cards from a self-heal at 2026-10-02T16:18Z, but each carries the
+  original report text (report id, received_at, app_version), which is what is cited here.
+- The local peer log is not usable as evidence: `.kenaz/peer/inbox.sqlite` in the KenazAI repo has 0
+  rows in `peer_messages`. The Ashfall traffic lives on other machines. Where a mechanism has no
+  incident, this document says so rather than inventing one.
+- Scale: Kenaz runs 2-5 nodes plus humans. Honeybee swarm decisions average over hundreds of scouts;
+  Temnothorax quorum over tens of ants; Physarum prunes a mesh of thousands of tube segments with
+  random exploration; the response-threshold model (Bonabeau 1998) is a statement about the
+  distribution of thresholds across a population. None of these statistical properties exist with
+  3 nodes. Local rules transfer; averaging and random exploration do not.
+- Principle carried from (a), supplied by the user's rejection of auto-release: biology's automatic
+  decay must be tuned to how long a member may legitimately be absent, and where a wrong automatic
+  action costs duplicated human work, prefer "flag, then explicit action with an event recorded" over
+  automatic action.
+
+Sources: Seeley et al. 2012, Science 335:108 (stop signals); Bonabeau et al. 1998, Bull Math Biol
+(response thresholds); Grueter et al. 2012, PLoS ONE, PMC3440389 (crowding negative feedback); Tero
+et al. 2010, Science (Physarum network design).
+
+## Summary table
+
+| | Mechanism | Evidence of a real failure | Cost | Pays off at 2-5 nodes | Verdict |
+|---|---|---|---|---|---|
+| a | Decaying claims / leases | Yes: offline owner holds a card (design reason for TASK_2227); human-absence cost drove the redesign | Done | Yes, as flag + explicit takeover | SHIPPED (reference) |
+| b | Response-threshold claiming | None found | Medium | No (needs a population of thresholds); a read-time age flag is cheap | DEFER |
+| c | Crowding / load signal | Partial: invisibility of claim progress (TASK_2207), since fixed; no overload incident | Low for a read-only flag | Marginal; humans already see load | DEFER (flag only, if ever) |
+| d | Stop signals / cross-inhibition | None found for approach conflicts; file conflicts already gated | Medium-high | Automatic inhibition is harmful at N=2 | NO-GO automatic; DEFER advisory |
+| e | Quorum for shared-outcome decisions | None found; no such decision path exists in code | High | No: N=2 quorum is unanimity or nothing | NO-GO |
+| f | Physarum-style reinforced routing | None found; observed routing failures are identity bugs | Medium | No: sender already knows whom to ask | NO-GO |
+
+## (a) Decaying claims / leases (reference, shipped as TASK_2227)
+
+Card text asked for automatic expiry of claims. What shipped is different and is the right shape:
+
+- A claim is stale when its owner has not heartbeated (`nodes.updated_at`) for 4 hours, or, if the
+  owner never registered, when `claimed_at` is 4 hours old (`yggdrasil-relay/src/routes/tasks.rs:838-841`,
+  `claim_staleness` at 846-860). Staleness is computed at read time and nothing is released
+  automatically (comment at 840).
+- Another node may take a stale claim only by explicitly claiming it. `claim_task` first tries the
+  atomic unclaimed update (922-930), refuses an owner re-claiming itself (944-946) and a non-stale
+  claim (949-951), re-checks `claimed_by` in the UPDATE so a concurrent change is not clobbered
+  (953-961), and writes a `reason=takeover` event with `previous_owner` and `stale_since` (965-972).
+- `unclaim_task` returns a card to the pool and records `reason=unclaim` (978-1001).
+- The client side, `tool_pool_claim`, keeps the relay row after the local write so the publisher keeps
+  seeing the card (`dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/pool.rs:747-750`).
+  That closes the visibility gap reported in TASK_2207 (publisher could no longer see a card after the
+  other lane claimed it).
+
+Why the biology had to be changed: an ant pheromone trail evaporates in minutes and the colony loses
+nothing when a trail dies, because workers are interchangeable and cheap. A Kenaz claim is a human's
+or an agent's hours of context. An offline Dashboard (laptop closed overnight) is not abandoned work,
+and an automatic release would hand the card to a second node that then duplicates the first node's
+unfinished work. So the decay constant is 4 h, not minutes, and the "evaporation" is only a flag.
+
+Lesson carried into (b)-(f): any proposed automatic action must state (1) the longest legitimate
+absence or silence, (2) the cost of a wrong automatic action, and (3) the flag-plus-explicit
+alternative. If (2) is duplicated human work, default to the flag.
+
+Verdict: SHIPPED. No further work here.
+
+## (b) Response-threshold claiming (urgency rises with age, per-node thresholds by skill)
+
+Biology: each worker has a threshold for a task stimulus; stimulus grows while the task is
+unattended, and workers with lower thresholds respond first. Specialisation emerges from a
+distribution of thresholds across many workers (Bonabeau 1998).
+
+Current Kenaz behaviour:
+- Pool cards are listed in static order: `ORDER BY priority, created_at`
+  (`yggdrasil-relay/src/routes/tasks.rs:103`). Priority is a fixed string defaulting to "P2"
+  (`tasks.rs:204`). Nothing grows with age.
+- Role is a display/filter field only, "independent of assigned_to" (`tasks.rs:154` and the `role`
+  column in `yggdrasil-relay/src/routes/nodes.rs:38`). There is no per-node skill threshold.
+- Claiming is a manual act by an agent or human calling `kenaz_pool_claim` (`pool.rs:631`), with an
+  atomic first-wins relay update (`tasks.rs:922-930`).
+- Dependency gating already hides cards whose dependencies are unmet (`tasks.rs:80-87`).
+
+Failure it would prevent: a card sitting unclaimed because nobody prefers it. Evidence: none found.
+TASK_2207 reports the opposite problem (claimed cards invisible to the publisher), and TASK_2132 is a
+room-key activation bug, not a starvation case. I did not find a report of an unclaimed card
+languishing.
+
+Why it transfers poorly: a threshold distribution needs a population; with 3 nodes plus a human who
+reads the list, "node X has a lower threshold for UI cards" is a hand-written preference, i.e. the
+existing `role` field. Automatic escalation would only re-sort a list a human reads anyway.
+
+Cost: Low for a read-time `age_secs` annotation plus an "unclaimed for > N h" flag (same pattern as
+`annotate_claim_state`, `tasks.rs:863-874`). Medium for per-node thresholds (schema + config + UX).
+
+Verdict: DEFER. If evidence appears, the only form worth building is the read-time age flag, not
+automatic urgency escalation and not automatic assignment.
+
+## (c) Crowding negative feedback (a busy node signals load)
+
+Biology: Grueter et al. describe foragers reducing recruitment when a food source is crowded; the
+negative signal is local and cheap.
+
+Current Kenaz behaviour:
+- Load-like data already exists in presence: each node row carries `current_task`, `touching_files`,
+  `uncommitted`, `work_summary`, `planned_tasks`, `is_online` (`yggdrasil-relay/src/routes/nodes.rs:37-38`,
+  upsert at 103-126). `kenaz_pool_nodes` exposes it (`pool.rs:916`).
+- Negative feedback on message volume already exists: the TASK_2161 adaptive loop guard, 30 sends per
+  thread per hour and a ping-pong cooldown, is in `evaluate_send_gate`
+  (`dashboard/src-tauri/src/infrastructure/http_server/routes/mcp_tools/peer.rs:457-502`), called at
+  1098-1134, plus a per-minute rate limit at 1067-1081.
+- A send to an offline or stale target is still delivered but warned (`peer.rs:1179-1186`), and a
+  target that is not in the room is refused with the live node list (1181).
+
+Evidence of failure: the relevant incidents are about the guard being wrong, not about missing load
+signals. The earlier human-in-the-loop guard refused sends after the user had typed a new prompt
+(TASK_2208, app 0.2.251, 2026-09-29; TASK_2212, app 0.2.254, 2026-10-02): "the very next
+kenaz_peer_send on the same thread was refused with the identical loop-guard error", blocking
+completion notices. TASK_2161 replaced that design (`peer.rs:1083-1086`). I have no field data yet on
+the new guard, so I cannot say whether its constants (30/h, ping-pong) are right. The lesson for any
+new negative-feedback rule: it must be tied to a signal that actually resets, and a false refusal
+costs more than a missed throttle at this scale.
+- TASK_2207 (app 0.2.252): a publisher could not see a claimed card's progress. Resolved in direction
+  by `pool.rs:747-750`; the remaining ask there (status moving to in_progress/done with commit hashes
+  on the relay row) is a visibility feature, not a crowding signal.
+
+Why it transfers poorly: at 2-5 nodes, "node B is busy" is already in presence data and in the human's
+head. A numeric load score with thresholds that suppresses sends or claims would be an automatic action
+whose wrong case (a node refused work because a stale `planned_tasks` says busy) is blocked human work.
+
+Cost: Low for a read-only `busy` flag in `kenaz_pool_nodes`; the data is already there.
+
+Verdict: DEFER. Do not gate sends or claims on load. If done, flag only.
+
+## (d) Bee stop signals (cross-inhibition when two nodes start conflicting approaches)
+
+Biology: scouts for site A headbutt scouts for site B, cutting their dance duration; this breaks
+deadlock between equal-quality sites and prevents a split decision, where the swarm divides between
+two sites (Seeley 2012). Tuned wrongly, inhibition fails either way: too much and the swarm stalls
+(deadlock), too little and it fragments (split decision).
+
+Current Kenaz behaviour:
+- File-level conflict is already a pre-dispatch gate. `remote-conflict.js` compares a candidate card's
+  `scope_paths` with other nodes' claimed tasks and with their live `touching_files`
+  (`.formation/tools/remote-conflict.js:3-4`, `hasRemoteConflict` 44-64, `hasRemoteFileConflict` 72-87),
+  with a 10 s cache (line 14), and `dispatch.js:1062-1066` consults both before dispatching. That is
+  already a stop signal, on the dimension where Kenaz can detect conflict mechanically. It skips a
+  card (it does not abort running work).
+- Approach-level conflict (two nodes solving the same problem differently without overlapping
+  `scope_paths`, or before either has touched a file) has no detection. Peer messages are free text
+  with kinds `question|answer|notice|request` (`peer.rs:59`); nothing relates them to cards.
+
+Evidence of failure: none found. No field report describes two nodes starting conflicting approaches.
+The only two-lane traffic on file (Ashfall, TASK_2206/2207) shows dependency sequencing needs
+(TASK_470 before BA's edit; TASK_492 before TASK_500), which the dependency gate in `tasks.rs:80-87`
+and the "claimed card stays visible" change address.
+
+Why automatic inhibition is harmful here: with N=2, mutual cross-inhibition becomes deadlock: A
+tells B to stop and B tells A to stop, and both stall, or a tie-break rule is needed, which
+is just "lower node name wins" and arbitrary. The cost of a wrong stop is a node idling or discarding
+work while a human is away, which is the (a) lesson.
+
+Cost: Medium for an advisory (compare scope/touching overlap at claim time and report it), high for
+anything that stops running work.
+
+Verdict: NO-GO for automatic inhibition. DEFER an advisory; it is the basis of the recommended slice
+because it also yields the evidence that this section lacks.
+
+## (e) Quorum before committing shared-outcome decisions
+
+Biology: Temnothorax ants and honeybees commit only after enough scouts are at the candidate site;
+this converts noisy individual votes into a reliable group choice.
+
+Current Kenaz behaviour:
+- I found no code path in the relay or peer tools that makes a shared-outcome decision across nodes.
+  Peer messages are advisory text (`peer.rs:59`, framed at 281-299 as untrusted peer content). Pool
+  claim is first-wins atomic, a single-writer decision (`tasks.rs:922-930`). Merging to main is a git
+  operation by a human or agent, outside the relay.
+- The decisions that matter (what lands on main, whether an approach is accepted) are made by the
+  human owners, who are the real quorum.
+
+Evidence of failure: none found. No report shows a shared decision committed by one node that others
+objected to.
+
+Why it does not transfer: quorum exists to average out unreliable individuals. With 2 nodes a
+quorum threshold is 1 (no protection) or 2 (any offline node blocks everything, the (a) failure again).
+With 3 nodes, 2-of-3 requires a third machine online, and the cost of waiting for it is human time.
+Humans already provide the check at the points where it matters.
+
+Cost: High (new message kind, vote storage, timeout policy, offline handling).
+
+Verdict: NO-GO. Revisit only if a concrete shared-outcome decision type is identified and its
+absence causes a logged incident.
+
+## (f) Physarum-style reinforced routing (send questions to peers whose answers proved useful)
+
+Biology: tubes carrying more flow thicken, others shrink; the network converges on efficient paths
+through many cycles of flow and random exploration (Tero 2010).
+
+Current Kenaz behaviour:
+- Routing is explicit by name: `to` is a node name or `*` for broadcast to every other registered
+  node, offline included (`peer.rs:1005-1012`, `1158-1172`). A non-room target is refused with the
+  node list (`1179-1181`); a stale one is warned (`1182-1184`).
+- Local rows record kind, thread and direction (`peer.rs:633` schema, `751` thread query), so answer
+  rate and latency per node could be computed, but nothing does.
+- Identity, not choice, is where routing has actually failed. TASK_2205 (app 0.2.249): a reply to the
+  sender's `from_node` "BA" failed with relay 403 because the routable name was "dashboard-node".
+  TASK_2206 (app 0.2.251): replies "never arrive" after a node rename without a Dashboard restart; the
+  lane "had to relay its answer through the human by copy-paste". Both are name-resolution defects
+  addressed by TASK_2139 (target check and stale-target warning at `peer.rs:1174-1189`, 403 fallback
+  at 1206-1210), not routing-quality problems.
+
+Evidence of failure that reinforcement would fix: none. A learned weight cannot repair a name that
+does not resolve.
+
+Why it does not transfer: the Physarum result needs many flow events and random exploration to
+estimate usefulness. A room with 2-5 nodes has a handful of threads; the sender knows whom to ask,
+and the model has no data to learn from. Exploration (asking the wrong peer on purpose) costs a human
+a confusing message.
+
+Cost: Medium (per-node usefulness score, decay, UI), for a decision that is currently a human choice
+among at most four options.
+
+Verdict: NO-GO.
+
+## Recommended single next slice
+
+Title: Claim-time overlap advisory with recorded event (flag only, relay + `kenaz_pool_claim` response).
+
+What: when a node claims a pool card, the relay compares the card's `scope_paths` with the
+`touching_files` and active-claim `scope_paths` of other nodes (reusing the matching rule in
+`remote-conflict.js:44-87`, ported to the relay or exposed via an existing endpoint), and returns an
+`overlap_advisory` list in the claim response without refusing the claim. It writes a
+`reason=overlap_advisory` event into `task_state_events` with the other node and file, the same way
+`reason=takeover` is recorded at `tasks.rs:965-972`. The claimer or human decides what to do.
+
+Why this one: it is the only mechanism with an existing data source, an existing mechanical rule and a
+flag-only shape that cannot cause duplicated human work. It adds no automatic action. It also produces
+the evidence (how often overlap actually occurs, at claim time) that (b), (c) and (d) currently lack,
+so a later decision can be made on logs rather than on biology.
+
+Size: normal card, about 2 files plus tests: relay `tasks.rs` (advisory + event + tests against an
+in-memory DB like the TASK_2227 tests) and `pool.rs` (pass the advisory through the claim result).
+It does not change the peer wire protocol. It still touches shared relay behaviour, so it needs the
+user's go-ahead after this document.
+
+Not recommended now: any of (b), (e), (f); automatic inhibition from (d); load-gated sends from (c).

package/core/dev/specs/peer/codex-hook-shim-peer.test.js

@@ -0,0 +1,101 @@
+'use strict';
+// TASK_2299: codex-hook-shim per-turn peer pull. Runs the real shim as a child process against a stub
+// /api/peer backend (never the live one). Run: node --test dev/specs/peer/codex-hook-shim-peer.test.js
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const SHIM = path.resolve(__dirname, '../../../.formation/bifrost/openai/codex-hook-shim.js');
+
+function startStub(pending) {
+  const calls = [];
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (c) => { body += c; });
+    req.on('end', () => {
+      calls.push({ method: req.method, url: req.url, body });
+      res.setHeader('content-type', 'application/json');
+      if (req.method === 'GET' && req.url.startsWith('/api/peer/pending')) {
+        res.end(JSON.stringify({ messages: pending.slice() }));
+      } else if (req.method === 'POST' && req.url === '/api/peer/ack') {
+        const ids = JSON.parse(body).ids;
+        for (let i = pending.length - 1; i >= 0; i--) if (ids.includes(pending[i].id)) pending.splice(i, 1);
+        res.end(JSON.stringify({ acked: ids }));
+      } else res.end('{}');
+    });
+  });
+  return new Promise((r) => server.listen(0, '127.0.0.1', () => r({ server, calls, port: server.address().port })));
+}
+
+function runShim(port, event, projectRoot, pull = true) {
+  // async spawn: the stub server lives in this process.
+  return new Promise((resolve) => {
+    const env = { ...process.env, KENAZ_HTTP_PORT: String(port), KENAZ_CONSOLIDATE_ROOT: projectRoot };
+    if (pull) env.KENAZ_PEER_PULL = '1'; else delete env.KENAZ_PEER_PULL;
+    const child = spawn('node', [SHIM], {
+      env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    let out = '';
+    child.stdout.on('data', (c) => { out += c; });
+    child.on('close', (code) => resolve({ code, out }));
+    child.stdin.end(JSON.stringify({ hook_event_name: event, session_id: 'sess-1', cwd: projectRoot, prompt: 'hi' }));
+  });
+}
+
+const MSG = { id: 'm1', thread_id: 't1', from_node: 'node-a', from_project_label: 'proj', kind: 'request', body: 'NONCE_PEER_77 please <b>look</b>' };
+
+// Codex rejects UserPromptSubmit stdout that is not one valid JSON object ("hook returned invalid
+// user prompt submit JSON output", peer report 2026-10-04). Empty stdout is also accepted.
+function contextOf(out) {
+  if (out.trim() === '') return '';
+  const parsed = JSON.parse(out); // throws on plain text or multiple objects
+  assert.equal(parsed.hookSpecificOutput.hookEventName, 'UserPromptSubmit');
+  return parsed.hookSpecificOutput.additionalContext;
+}
+
+test('pending peer message is emitted once on UserPromptSubmit and acked by id; second prompt emits nothing', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-shim-peer-'));
+  const pending = [MSG];
+  const { server, calls, port } = await startStub(pending);
+  try {
+    const first = await runShim(port, 'UserPromptSubmit', root);
+    assert.equal(first.code, 0);
+    const ctx = contextOf(first.out);
+    assert.match(ctx, /NONCE_PEER_77/);
+    assert.match(ctx, /from node-a@proj/);
+    assert.doesNotMatch(ctx, /not an instruction/);
+    assert.doesNotMatch(ctx, /<b>/, 'markup must be defanged');
+    const get = calls.find((c) => c.method === 'GET');
+    assert.match(get.url, /peek=true/);
+    assert.match(get.url, /sessionId=sess-1/);
+    const acks = calls.filter((c) => c.method === 'POST');
+    assert.equal(acks.length, 1);
+    assert.deepEqual(JSON.parse(acks[0].body).ids, ['m1']);
+
+    const second = await runShim(port, 'UserPromptSubmit', root);
+    assert.doesNotMatch(contextOf(second.out), /NONCE_PEER_77/);
+    assert.equal(calls.filter((c) => c.method === 'POST').length, 1, 'no second ack');
+  } finally { server.close(); }
+});
+
+test('negative control: marker absent (headless worker) makes zero peer requests even with a pending message', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-shim-peer-'));
+  const { server, calls, port } = await startStub([MSG]);
+  try {
+    const r = await runShim(port, 'UserPromptSubmit', root, false);
+    assert.equal(r.out.trim(), '');
+    assert.equal(calls.filter((c) => c.url.startsWith('/api/peer')).length, 0);
+  } finally { server.close(); }
+});
+
+test('fail-open: unreachable backend emits nothing and exits 0', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'codex-shim-peer-'));
+  const r = await runShim(1, 'UserPromptSubmit', root);
+  assert.equal(r.code, 0);
+  assert.equal(r.out.trim(), '');
+});