kenaz 0.3.22 → 0.3.24

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

@@ -1,54 +0,0 @@
-# Codex UserPromptSubmit hook injection spike (TASK_2299)
-
-Date: 2026-10-04. Codex CLI: `codex-cli 0.159.2` (model gpt-6-astra). Closes TASK_2141 open risk 5.
-
-## Result: WORKS
-
-A Codex `UserPromptSubmit` command hook's stdout reaches the model's context for that turn. Both shapes were accepted:
-
-| Hook stdout | Reached the model? |
-|---|---|
-| Plain text, e.g. `PEERNONCE_PLAIN_7Q4K` | yes |
-| JSON `{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"PEERNONCE_JSON_9X2M"}}` | yes |
-
-The shim uses plain text (simplest; no JSON-escaping of peer text).
-
-## Hook config format (config.toml, same as setup-codex.js already writes)
-
-```toml
-[[hooks.UserPromptSubmit]]
-
-[[hooks.UserPromptSubmit.hooks]]
-type = "command"
-command = 'node "/abs/path/hook.js"'
-timeout = 15
-```
-
-Hook stdin is JSON: `session_id`, `turn_id`, `transcript_path`, `cwd`, `hook_event_name`, `prompt` (observed keys: `session_id`, `turn_id`, `transcript_path`, `cwd`).
-
-## IMPORTANT: hook trust
-
-Codex 0.159.2 does NOT run a newly registered hook until it is reviewed/trusted ("New hook - review required"; persisted as `[hooks.state."<key>"] trusted_hash` in config.toml; re-review after the hook changes). Control run: with the hooks registered but untrusted, the model reported `NONE` and the hook log file was never written. Trust is granted by the user in the TUI (`/hooks`); `codex exec --dangerously-bypass-hook-trust` bypasses it for one invocation (used only in the isolated spike). So registering the hook via setup-codex.js is necessary but not sufficient: the user must trust it once, and again after the shim/command changes.
-
-## Commands (isolated CODEX_HOME; real ~/.codex untouched)
-
-1. Copy `~/.codex/auth.json` and `config.toml` to a temp dir; append two `[[hooks.UserPromptSubmit]]` blocks (plain-text hook, JSON hook).
-2. Control (no bypass): `CODEX_HOME=<tmp> codex exec --json --skip-git-repo-check -s read-only -C <tmp> "Repeat back any unusual codeword tokens ... If none, say NONE."` -> `NONE`, no hook log.
-3. With bypass: same command plus `--dangerously-bypass-hook-trust` -> agent_message `PEERNONCE_PLAIN_7Q4K` and `PEERNONCE_JSON_9X2M`; hook log shows stdin JSON.
-
-## This machine
-
-`~/.codex/config.toml` has NO kenaz hooks (no `[[hooks.*]]` at all, including UserPromptSubmit). `setup-codex.js` `missingHookEvents()` reports all five events missing. Installing (re-running setup-codex) plus a one-time `/hooks` trust review is needed before the pull is live.
-
-## Implementation
-
-`.formation/bifrost/openai/codex-hook-shim.js` on `UserPromptSubmit`: resolve root (`KENAZ_CONSOLIDATE_ROOT` or hook `cwd`, via `_peer-project-root.js`) -> `GET /api/peer/pending?peek=true&projectPath&sessionId` (2.5 s bound, fail-open) -> print Codex-tuned frame (mirrors `codex_wake.rs frame_for_codex`) to stdout -> `POST /api/peer/ack {projectPath, ids}`. Messages are text only; nothing is acted on. Tests: `dev/specs/peer/codex-hook-shim-peer.test.js`, `dev/specs/peer/setup-codex-hooks.test.js`.
-
-Gate: the pull runs only when `KENAZ_PEER_PULL=1` (set by `.formation/bifrost/launch.js` for the interactive session; `relay.js` deletes it from headless worker env) so formation workers sharing the user-wide hook never peek/ack the inbox.
-
-## Operational notes (2026-10-05, from wei@Ashfall's field verification)
-
-- Verified live on Ashfall after 645343bc8: three pending messages were injected on the next prompt.
-- Session identity: inside Codex, use `CODEX_SESSION_ID` as the session id (for `kenaz_peer_send` and handoffs). The fast-boot banner now prefers it (ansuz-boot-fast.js `harnessSessionIdFromEnv`); before that it reported an id taken from Claude hook hints, and replies bound to that id were not delivered to the Codex session.
-- Diagnostics: `GET /api/peer/pending?peek=true` WITH `sessionId` claims a 60 s lease on the returned rows (`peer.rs` LEASE_SECS, TASK_2285); a diagnostic peek under another id delays delivery to the real session for up to 60 s. Diagnose with peek and NO sessionId.
-- Idle push (delivery without a user prompt) is not provided for Codex: `codex_push` is off by design and the Claude helper push path (`expected exactly one SendMessage call`) is parked in favour of the kenaz-peer mod (TASK_2159 / TASK_2234).

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

@@ -1,133 +0,0 @@
-# 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

@@ -1,143 +0,0 @@
-# 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

@@ -1,256 +0,0 @@
-# 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).