@zerwiz/ymir 0.1.3 → 0.1.5

package/.agents/skills/galdr-ymirsystem/assets/harness-integration/opencode.md

@@ -0,0 +1,262 @@
+# OpenCode Harness Adapter (Öppencode)
+
+> **Purpose:** Rebuild, verify, or extend the OpenCode adapter — the `.opencode/plugins/*.js` shims that seat Brokk on `session.created`, arm **Sýn** on `session.idle`, guard the turn end, and enforce the PreToolUse seatbelts.
+
+OpenCode is Ymir's **primary harness** (`config/eindri-harness` = `opencode`; `opencode.json` sets `"default_agent": "brokk"`). Its adapters are Node ESM plugins auto-loaded from `.opencode/plugins/`.
+
+---
+
+## 1. Files
+
+| File | Export | Norse role | Contract part |
+|---|---|---|---|
+| `.opencode/plugins/saga-sessionstart.js` | `SagaSessionstart` | **Sága** — runs the digest and injects it into the session | Session-open injection |
+| `.opencode/plugins/syn-watch-arm.js` | `SynWatchArm` | **Sýn** — owns watcher continuity | Watch arm |
+| `.opencode/plugins/syn-turnend-guard.js` | `SynTurnendGuard` | **Sýn** — refuses a blind turn end | Turn-end guard |
+| `.opencode/plugins/syn-pretool-check.js` | `SynPretoolCheck` | **Sýn** — arm seatbelt | PreToolUse (arm) |
+| `.opencode/plugins/syn-cd-check.js` | `SynCdCheck` | **Sýn** — cd seatbelt | PreToolUse (cd) |
+| `.opencode/plugins/lib/rodd-operational-input.js` | `encodeRoddOperationalInput` | **Rödd** — the wire encoder | shared |
+| `.opencode/plugins/package.json` | — | declares `"type": "module"` | — |
+
+There is **no** `plugin` array in `opencode.json`; OpenCode discovers `.opencode/plugins/*.js` by path. The plugins are plain ESM and import only Node builtins plus their local `./lib/`.
+
+---
+
+## 2. How the plugins are shaped
+
+Each plugin is a named export that receives the OpenCode plugin context and returns an object of hook handlers:
+
+```js
+// .opencode/plugins/saga-sessionstart.js:44
+export const SagaSessionstart = async ({ client, directory, worktree }) => {
+  const root = worktree ? resolvePath(worktree) : await resolveRoot(directory);
+  return { event: async ({ event }) => { /* ... */ } };
+};
+```
+
+| Context field | Meaning |
+|---|---|
+| `client` | OpenCode SDK client; `client.session.promptAsync({ path:{id}, body:{parts:[{type:"text",text}]} })` injects a message |
+| `directory` | the session working directory |
+| `worktree` | the linked worktree root when OpenCode runs in one (an Eindri home) |
+| `event` | callback receiving `{ event }`, where `event.type` is the lifecycle event |
+| `tool.execute.before` | callback receiving `(input, output)`; **throw** to block |
+
+### Root resolution (all plugins)
+
+```js
+async function resolveRoot(anchor) {
+  if (!anchor) return "";
+  const result = await runProcess("git", ["-C", anchor, "rev-parse", "--show-toplevel"]);
+  const root = result.stdout.trim();
+  if (result.code === 0 && root) return root;
+  return resolvePath(anchor);   // realpathSync(anchor) || resolve(anchor)
+}
+```
+
+`worktree` wins when set, so an Eindri launched by `bin/einherjar-spawn.sh` into `.yggdrasil/<id>` resolves its **own** worktree root and never the primary checkout.
+
+---
+
+## 3. Event hooks used
+
+| Event | Plugin | Action |
+|---|---|---|
+| `session.created` | `saga-sessionstart.js` | run `bin/saga-sessionstart-run.sh` once per session id; inject its stdout |
+| `session.idle` | `syn-watch-arm.js` | ensure an arm cycle is running (`sessionOwnsLock`, primary root, `shouldArm`) |
+| `session.idle` | `syn-turnend-guard.js` | first ask the watch-arm coordinator; only if it could not arm, run `bin/syn-turnend-guard.sh` and re-prompt on exit 2 |
+| `tool.execute.before` | `syn-pretool-check.js` | run `bin/syn-arm-pretool-check.sh --command <cmd>`; throw on exit 2 |
+| `tool.execute.before` | `syn-cd-check.js` | run `bin/syn-cd-pretool-check.sh --command <cmd>`; throw on exit 2 |
+
+### 3.1 `session.created` — Sága injection
+
+`.opencode/plugins/saga-sessionstart.js:48-76`:
+
+1. Ignore unless `event.type === "session.created"`.
+2. Extract `sessionID = event.properties?.info?.id ?? event.properties?.sessionID`.
+3. Skip if already handled (`handledSessions` Set) or no root.
+4. Run `${root}/bin/saga-sessionstart-run.sh` with no args.
+5. If exit ≠ 0 or empty output, silently return (**never block the session**).
+6. Encode the digest via the Rödd bridge; on encoder failure fall back to the raw digest.
+7. `client.session.promptAsync({ path:{id:sessionID}, body:{parts:[{type:"text",text}]} })`; delivery errors are swallowed.
+
+Because the plugin **runs** the wrapper and injects the result, OpenCode is run-tier in execution with nudge-style delivery.
+
+### 3.2 `session.idle` — Sýn arm ownership
+
+`.opencode/plugins/syn-watch-arm.js:490-505`:
+
+```js
+export const SynWatchArm = async ({ client, directory, worktree }) => {
+  const root = worktree ? resolvePath(worktree) : await resolveRoot(directory);
+  const paths = effectivePaths(root);
+  globalThis[COORDINATOR_KEY] = {
+    ensureArmed: (sessionID, activeClient) => ensureArm(paths, sessionID, activeClient ?? client),
+  };
+  return {
+    event: async ({ event }) => {
+      if (event.type !== "session.idle") return;
+      const sessionID = event.properties?.sessionID;
+      if (!sessionID) return;
+      void ensureArm(paths, sessionID, client);
+    },
+  };
+};
+```
+
+`COORDINATOR_KEY = "__brokkOpenCodeWatchArm"` (line 15) is the shared handoff the turn-end guard reads.
+
+Arm gating (`.opencode/plugins/syn-watch-arm.js`):
+
+| Gate | Function | Rule |
+|---|---|---|
+| primary root only | `isPrimaryRoot` (102-111) | `AGENTS.md` + `bin/` must exist and `git rev-parse --git-dir` must equal `--git-common-dir` (a linked Eindri worktree reports a different git-dir and must not own supervision) |
+| live lock | `sessionOwnsLock` (123-140) | walk ancestors of `process.pid` up to 8 levels; must equal `state/.lock` pid |
+| arm needed | `shouldArm` (113-121) | false if `state/.afk` exists; true if `config/x-mode.env` exists; else true only if some `state/*.meta` exists |
+| single flight | `launchInFlight` (470-488) | serializes concurrent `session.idle` callbacks |
+
+The spawned command is:
+
+```js
+// .opencode/plugins/syn-watch-arm.js:355
+const armChild = spawn("bash", ["-lc",
+  'config_dir="${BROKK_CONFIG_OVERRIDE:-$BROKK_HOME/config}"; [ -f "$config_dir/x-mode.env" ] && . "$config_dir/x-mode.env"; exec "$BROKK_ROOT_OVERRIDE/bin/syn-watch-arm.sh" --restart'],
+  { cwd: paths.root, env, stdio: ["ignore","pipe","pipe"] });
+```
+
+`env` includes `BROKK_HOME`, `BROKK_ROOT_OVERRIDE`, `BROKK_CONFIG_OVERRIDE`, `BROKK_STATE_OVERRIDE`, `BROKK_WATCH_PREDECESSOR_ARM_PID`.
+
+Continuity: on any non-actionable close, `scheduleRetry` re-arms with exponential backoff (`BROKK_WATCH_REARM_RETRY_BASE_MS` 250 → `..._MAX_MS` 4000, limit `..._LIMIT` 5). On an actionable line, `restoreAfterActionableClose` starts a successor and then `deliverActionableWake` prompts the session.
+
+### 3.3 `session.idle` — Sýn turn-end guard
+
+`.opencode/plugins/syn-turnend-guard.js:65-104`:
+
+1. Ignore unless `event.type === "session.idle"`.
+2. If `skipNextIdle`, clear and return (prevents a re-prompt loop).
+3. `letWatchArmRun(sessionID, client)` calls `globalThis.__brokkOpenCodeWatchArm.ensureArmed(...)`; return early on `armed`, `wake`, or `failed`.
+4. Otherwise run `${root}/bin/syn-turnend-guard.sh` with stdin `{"stop_hook_active":false}`.
+5. Only on exit **2**: encode the fixed recovery text + stderr through Rödd and `promptAsync`; set `skipNextIdle`.
+
+The ordering matters: **watch-arm is asked first**. The guard exists for the residual case where the coordinator could not arm.
+
+### 3.4 `tool.execute.before` — seatbelts
+
+`.opencode/plugins/syn-pretool-check.js:50-60`:
+
+```js
+"tool.execute.before": async (input, output) => {
+  if (!root || input?.tool !== "bash") return;
+  const command = output?.args?.command;
+  if (!command || typeof command !== "string") return;
+  const result = await runProcess(`${root}/bin/syn-arm-pretool-check.sh`, ["--command", command]);
+  if (result.code !== 2) return;
+  throw new Error(result.stderr.trim() || "denied by the watcher-arm PreToolUse seatbelt");
+}
+```
+
+`.opencode/plugins/syn-cd-check.js` is identical but calls `bin/syn-cd-pretool-check.sh`. A thrown error blocks the tool call; the owner scripts hold the policy (`syn-arm-pretool-check.sh` denies backgrounding `syn-watch-arm.sh`; `syn-cd-pretool-check.sh` denies `cd .../../`).
+
+---
+
+## 4. The Rödd bridge
+
+`.opencode/plugins/lib/rodd-operational-input.js` is the **only** way the plugins encode operational text. It is a cross-language adapter; `bin/rodd-operational-input.sh` owns the protocol.
+
+```js
+// .opencode/plugins/lib/rodd-operational-input.js:6-15
+const adapterRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+export function encodeRoddOperationalInput(root, kind, content) {
+  const requested = `${root}/bin/rodd-operational-input.sh`;
+  const script = existsSync(requested) ? requested : `${adapterRoot}/bin/rodd-operational-input.sh`;
+  // spawn(script, ["encode", kind], ...) ; stdin = content ; stdout = encoded
+}
+```
+
+- Signature: `encodeRoddOperationalInput(root, kind, content) => Promise<string>`.
+- It spawns `bin/rodd-operational-input.sh encode <kind>` with the body on stdin.
+- It prefers the runtime's own `bin/` and falls back to the adapter's repo `bin/` (three levels up from `.opencode/plugins/lib/`).
+- Valid `kind`s are owned by the shell script (`RODD_KINDS`): `session-start watcher turn-end-guard away-supervisor launch-brief branch-outcome`, plus the special `from-brokk` carrier.
+- Wire form: `U+2063 RODD_OP: v1 <kind>: <body>`.
+
+Do **not** hand-build the marker in a plugin; call the bridge (or import `RODD_*` only from the shell library).
+
+---
+
+## 5. Configuration (`opencode.json`)
+
+The adapter reads runtime roots from the environment and OpenCode behaviour from `opencode.json`.
+
+| Key | Value in Ymir | Why it matters |
+|---|---|---|
+| `default_agent` | `"brokk"` | a bare OpenCode launch opens as Brokk |
+| `agent.brokk.mode` | `"primary"` | the primary agent |
+| `agent.*.mode` | `subagent` (build, builder, plan, planner, reviewer, documenter, scout) | dispatched Eindri profiles |
+| `skills.paths` | `[".agents/skills"]` | single skill source; the `galdr` skill loads from here |
+| `model` | `""` | empty → harness default |
+| `permission` | `allow` for read/edit/glob/grep/bash/task/skill/question/webfetch/websearch/external_directory | primary autonomy |
+
+OpenCode does **not** need a `plugin` declaration: `plugins/*.js` are auto-loaded. The `.opencode/plugins/package.json` exists only to force ESM:
+
+```json
+{ "private": true, "type": "module" }
+```
+
+---
+
+## 6. Install / enable / verify
+
+### Enable
+
+No install step is required beyond the files being present. OpenCode auto-loads `.opencode/plugins/*.js` on startup. To confirm the plugin modules parse:
+
+```bash
+cd "$BROKK_HOME"
+node --input-type=module -e 'await import("./.opencode/plugins/saga-sessionstart.js"); await import("./.opencode/plugins/syn-watch-arm.js"); await import("./.opencode/plugins/syn-turnend-guard.js"); await import("./.opencode/plugins/syn-pretool-check.js"); await import("./.opencode/plugins/syn-cd-check.js"); console.log("plugins import ok")'
+```
+
+### Verify the four contract parts
+
+```bash
+# 1) session-open: the wrapper the plugin runs
+bin/saga-sessionstart-run.sh | head -n 15 ; echo "exit=$?"
+
+# 2) Rödd encode round-trip (what the plugin calls)
+printf 'hello' | bin/rodd-operational-input.sh encode session-start | bin/rodd-operational-input.sh kind
+# expected: session-start
+
+# 3) watch arm + heartbeat + wake exit
+bin/syn-watch-arm.sh --restart &   # only with a live lock; prints watcher: started...
+sleep 1
+test -s state/.watch.heartbeat && echo "heartbeat ok"
+: > state/.wake-queue              # arm should exit with "signal: wake queue"
+
+# 4) seatbelts (exit 2 = block)
+bin/syn-arm-pretool-check.sh --command 'foo & bar';             echo "expect 0 -> $?"
+bin/syn-arm-pretool-check.sh --command 'bin/syn-watch-arm.sh &'; echo "expect 2 -> $?"
+bin/syn-cd-pretool-check.sh  --command 'cd ../..';              echo "expect 2 -> $?"
+```
+
+### End-to-end smoke
+
+```bash
+# OpenCode session in BROKK_HOME: the first injected message must begin with the
+# Sága digest (or the RODD_OP marker wrapping it), and the session must address
+# the operator as Allfather. Then drop a wake and confirm the watcher fires.
+: > state/.wake-queue
+```
+
+---
+
+## 7. Gotchas
+
+- **Two `session.idle` plugins race by design — but not for the guard.** `syn-watch-arm.js` and `syn-turnend-guard.js` both listen on `session.idle`; the guard *asks* the arm coordinator first, and only runs the guard when arming failed. Reversing this produces spurious "TURN WOULD END BLIND" prompts during normal operation.
+- **`handledSessions` is per-process, never persisted.** After an OpenCode restart the digest runs again for a new session id; that is intended. Do not persist the Set — a resumed session with a new id must still be seated.
+- **`promptAsync` failures are swallowed.** If OpenCode's SDK errors, the digest is silently dropped. Diagnose by running `bin/saga-sessionstart-run.sh` by hand; the plugin cannot surface a delivery error.
+- **`shouldArm` returns false with no `state/*.meta` and no `config/x-mode.env`.** A fresh home therefore arms nothing until there is a task or x-mode. This is deliberate: no fleet, no supervision. Do not "fix" it by always arming.
+- **The arm refuses on a linked worktree.** `isPrimaryRoot` requires `git-dir == git-common-dir`; an Eindri worktree under `.yggdrasil/<id>` will never own supervision. Correct — the primary owns it.
+- **`read-only` is final for the cycle.** If `sessionOwnsLock` is false, `beginArm` returns `read-only` and no retry is scheduled. A second OpenCode session must not fight the lock holder.
+- **The plugin must never be replaced by a model bash call.** `syn-arm-pretool-check.sh` denies backgrounding the arm precisely so the model cannot fork a second watcher.
+- **`config/x-mode.env` is sourced by the arm spawn** (`.opencode/plugins/syn-watch-arm.js:355`). It is not present by default; treat it as an operator opt-in.
+- **`.opencode/plugins/lib/` is not a package** — there is no `package.json` there. Relative imports (`./lib/rodd-operational-input.js`) are what make it work; the top-level `package.json` supplies `"type":"module"`.
+- **Tool name matching is exact.** The seatbelts only inspect `input.tool === "bash"`. If OpenCode renames the shell tool, both seatbelts silently stop enforcing.

package/.agents/skills/galdr-ymirsystem/assets/harness-integration/pi.md

@@ -0,0 +1,295 @@
+# Pi Harness Adapter
+
+> **Purpose:** Rebuild, verify, or extend the Pi adapter — the `.pi/extensions/*.ts` modules that inject the Sága digest before the first turn, own the Gná watcher, guard the turn end, and run the PreToolUse seatbelts on `@earendil-works/pi-coding-agent`.
+
+Pi is a **run-tier** harness with an in-process extension API: the extension runs the digest itself and injects its output into model context before the first turn. Two tracked project extensions are required; both auto-load once the project is trusted.
+
+---
+
+## 1. Files
+
+| File | Norse role | Contract parts |
+|---|---|---|
+| `.pi/extensions/syn-turnend-guard.ts` | **Sýn** — session-start injection + compaction re-emit + turn-end guard + PreToolUse seatbelts | 1, 3, 4 |
+| `.pi/extensions/gna-pi-watch.ts` | **Gná** — watcher continuity (arm, re-arm, deliver actionable wakes) | 2 |
+| `.pi/extensions/lib/vordr-sessionstart-supervisor.mjs` | **Vörðr** — detached child supervisor for the digest | 1 (transport) |
+| `.pi/extensions/lib/rodd-operational-input.ts` | **Rödd** — TypeScript wire bridge | shared |
+| `.pi/extensions/README.md` | prose inventory (see §11: partially stale) | — |
+
+`.pi/extensions/` has **no** `package.json`; Pi loads the `.ts` sources directly and they import `@earendil-works/pi-coding-agent` (types), `@earendil-works/pi-tui` (Gná render), and `typebox` (tool schema).
+
+Both extensions use `import.meta.url` to locate themselves and derive the root as `resolve(extensionDir, "../..")` — i.e. the repo root that holds `bin/`:
+
+```ts
+// .pi/extensions/syn-turnend-guard.ts:23-29
+const extensionFile = fileURLToPath(import.meta.url);
+const extensionDir = dirname(extensionFile);
+const root = resolve(extensionDir, "../..");
+const brokkHome = process.env.BROKK_HOME || process.env.BROKK_ROOT_OVERRIDE || root;
+const state = process.env.BROKK_STATE_OVERRIDE || `${brokkHome}/state`;
+const marker = `${state}/.pi-syn-turnend-loaded`;
+const extensionVersion = `sha256:${createHash("sha256").update(readFileSync(extensionFile)).digest("hex")}`;
+```
+
+---
+
+## 2. Required Pi lifecycle events
+
+Pi emits the following events the adapter binds (via `pi.on?.(...)`). The adapter must tolerate optional events (`?.`) because Pi adds them across minor versions.
+
+| Pi event | Bound in | Payload / signature | Adapter action |
+|---|---|---|---|
+| `session_start` | both extensions | `(event, ctx)`; `event.reason` ∈ `startup \| reload \| new \| resume \| fork` | start a session-start generation (Sýn); activate a watcher generation (Gná) |
+| `before_agent_start` | Sýn | `(_event, ctx)` | claim and return the digest as a message (`{ message }`) |
+| `session_compact` | Sýn | `(_event, ctx)` | create a `compact` generation and `pi.sendMessage(...)` the re-emit |
+| `session_shutdown` | both | `()` | stop the active generation (Sýn/Gná) |
+| `agent_settled` | Sýn | `()` | run `bin/syn-turnend-guard.sh`; on exit 2, `pi.sendUserMessage(content,{deliverAs:"followUp"})` |
+| `tool_call` | Sýn | `(event)`; `event.toolName`, `event.input.command` | for `bash`, run cd-check then arm-check; return `{block:true, reason}` on exit 2 |
+
+Sýn also registers a `process.once("exit", ...)` cleanup that SIGKILLs the digest process group.
+
+### 2.1 `session_start` source mapping (Sýn)
+
+```ts
+// .pi/extensions/syn-turnend-guard.ts:522-534
+pi.on?.("session_start", (event, ctx) => {
+  const reason = String(event.reason ?? "");
+  const source = reason === "startup"
+    ? startupRebuildSource(ctx) ?? "startup"     // maps -c/-r/--session/--fork to resume/fork
+    : { new: "clear", resume: "resume", fork: "fork" }[reason];
+  markLoaded();
+  if (!source) return;                            // reload → no new generation
+  sessionstartGeneration = createSessionstartGeneration(source, sessionIdFromContext(ctx));
+});
+```
+
+- `reason === "new"` (Pi `/new`) → `clear` → wrapper re-emits context.
+- `reason === "reload"` → no generation (prior context kept).
+- `reason === "resume" | "fork"` → a nudge, not a full run.
+- `reason === "startup"` is refined by `startupRebuildSource(ctx)`: a restored-session timestamp older than `performance.timeOrigin` plus `-c/--continue`, `-r/--resume`, `--session`, `--session-id`, or `--fork` yields `resume`/`fork`.
+
+### 2.2 `before_agent_start` delivery (Sýn)
+
+```ts
+pi.on?.("before_agent_start", async (_event, ctx) => {
+  const generation = sessionstartGeneration;
+  if (!generation) return;
+  const message = await claimSessionstartMessage(generation, ctx);
+  return message ? { message } : undefined;
+});
+```
+
+The returned message is a `syn-sessionstart-nudge` `SessionstartMessage` with encoded content. `claimSessionstartMessage` refuses to deliver when the generation was superseded or the session id changed.
+
+### 2.3 `session_compact` (Sýn)
+
+Manual compaction is idle and auto-compaction may retry without another `before_agent_start`, so the compact handler creates its own generation and calls `pi.sendMessage(message)` directly (`.pi/extensions/syn-turnend-guard.ts:546-557`).
+
+### 2.4 `agent_settled` turn-end guard (Sýn)
+
+```ts
+pi.on("agent_settled", async () => {
+  if (guardFollowupActive) { guardFollowupActive = false; return; }
+  const result = await runGuard();                 // spawns bin/syn-turnend-guard.sh, stdin {"stop_hook_active":false}
+  if (result.code !== 2) return;
+  guardFollowupActive = true;
+  const content = encodeRoddOperationalInput("turn-end-guard",
+    "TURN WOULD END BLIND - supervision is off. ...\n\n" + result.stderr);
+  await pi.sendUserMessage(content, { deliverAs: "followUp" });
+});
+```
+
+`guardFollowupActive` suppresses the immediate re-fire after the guard's own follow-up creates another settle.
+
+### 2.5 `tool_call` seatbelts (Sýn)
+
+```ts
+pi.on("tool_call", async (event) => {
+  if (event.type !== "tool_call" || event.toolName !== "bash") return {};
+  const command = String(event.input?.command ?? "");
+  const cdResult = await runCdCheck(command);              // bin/syn-cd-pretool-check.sh
+  if (cdResult.code === 2) return { block: true, reason: cdResult.stderr.trim() || "..." };
+  const result = await runPretoolCheck(command);           // bin/syn-arm-pretool-check.sh
+  if (result.code !== 2) return {};
+  return { block: true, reason: result.stderr.trim() || "..." };
+});
+```
+
+Both seatbelts piggyback on the same extension file so no extra `-e` flag is needed at launch.
+
+---
+
+## 3. The Vörðr digest supervisor
+
+`.pi/extensions/lib/vordr-sessionstart-supervisor.mjs` runs the Sága runner as a **detached child** so Pi can stream and cap output without blocking the session open.
+
+Sýn spawns it (`.pi/extensions/syn-turnend-guard.ts:260-282`):
+
+```ts
+const supervised = process.platform !== "win32";
+const runner = `${root}/bin/saga-sessionstart-run.sh`;
+child = spawn(
+  supervised ? "node" : runner,
+  supervised
+    ? [`${extensionDir}/lib/vordr-sessionstart-supervisor.mjs`, runner, "--source", generation.source, "--pi-prerequisite"]
+    : ["--source", generation.source, "--pi-prerequisite"],
+  {
+    detached: supervised,
+    env: { ...process.env, BROKK_SESSION_PID: String(process.pid) },
+    stdio: supervised ? ["ignore", "pipe", "ignore", "ipc"] : ["ignore", "pipe", "ignore"],
+  },
+);
+```
+
+Vörðr's contract (`.pi/extensions/lib/vordr-sessionstart-supervisor.mjs`):
+
+- `process.argv.slice(2)` = `[runner, ...args]`.
+- Spawns the runner with `env.VORDR_SESSIONSTART_SUPERVISOR_PID`.
+- Streams child stdout to its own stdout and counts `outputBytes`.
+- Sends `{ type: "result", code, bytes }` over IPC once writes drain.
+- On `disconnect` (parent died) it `process.kill(-process.pid, "SIGKILL")` to reap the group.
+
+Sýn therefore treats the **result message** as the completion signal, not the `close` event (which can arrive early). This is why `completePending` waits until `observedBytes >= result.bytes` before settling.
+
+### `BROKK_SESSION_PID` lock binding
+
+The digest child is launched with `env.BROKK_SESSION_PID = String(process.pid)` — the **live Pi process**. `bin/gleipnir-lock-lib.sh` writes that pid to `state/.lock` (`gleipnir_lock_acquire`), so the lock survives the short-lived digest helper. Both Sýn and Gná verify ownership by walking `ps -o ppid=` ancestry up to 8 levels and comparing to the `.lock` pid (`lockOwnership()` in both files). `other` means read-only; `missing` means the lock is gone/stale.
+
+Liveness sees real death (`gleipnir_pid_alive` / `pidAlive`). `kill(0)` alone reports a zombie (dead but unreaped) and a recycled pid as “alive”, which stranded the machine lock after an agent was turned off. The lock therefore also records the owner's starttime in a sidecar (`brokk.lock.starttime`, `/proc/<pid>/stat` field 22) and rejects a holder whose state is `Z`/`X` or whose recorded starttime no longer matches. `gleipnir_lock_reap` (session start) and `gleipnir_lock_acquire` clear such locks, and Gná releases its own lock on real process exit (`releaseLockIfOwned` in the `exit` hook) so a clean quit never leaves the helm behind.
+
+### Delivery cap and truncation
+
+Sýn caps injected bytes at `sessionstartDeliveryBytes = 512 * 1024` (`.pi/extensions/syn-turnend-guard.ts:71`). On overflow it appends:
+
+```
+PI SESSION-START DELIVERY TRUNCATED - the digest exceeded 512 KiB. Treat omitted context as unread and inspect the named files directly before acting on it.
+```
+
+On a failed/empty startup it substitutes the manual fallback:
+
+```
+Run `bin/saga-session-start.sh` now, exactly once, before executing any other instructions.
+```
+
+Pi's prerequisite exit is `sessionstartIneligibleExit = 3`; a stand-down (`BROKK_SESSIONSTART_INELIGIBLE=1`) exits 3 and is mapped to `{ kind: "ineligible" }` rather than `failed`.
+
+---
+
+## 4. Gná watcher continuity
+
+`.pi/extensions/gna-pi-watch.ts` owns the watcher in the persistent TUI. It exposes:
+
+- **Command** `pi.registerCommand("gna-watch-arm", ...)` (line 530).
+- **Tool** `pi.registerTool({ name: "gna_watch_arm", ... })` (line 538) with `promptGuidelines` telling the model to call it **only** for the first cycle or after an actionable notification, never after ordinary work — the extension re-arms automatically.
+- **Events** `session_start` (activate generation, `markLoaded`) and `session_shutdown` (stop generation).
+
+Arm spawn (`.pi/extensions/gna-pi-watch.ts:397-434`):
+
+```ts
+const ownership = lockOwnership();
+if (ownership === "other")  return { ok:false, message:"watcher: read-only - session lock is held by another Brokk session" };
+if (ownership === "missing") { reclaimStaleLock(resolvedLockPath()); return startArm(owner, predecessorArmPid); }
+const env = { ...process.env, BROKK_HOME, BROKK_ROOT_OVERRIDE, BROKK_CONFIG_OVERRIDE,
+              BROKK_WATCH_ARM_SCRIPT, BROKK_WATCH_PREDECESSOR_ARM_PID, BROKK_SESSION_PID: String(process.pid) };
+const armChild = spawn("bash", ["-lc", 'exec "$BROKK_WATCH_ARM_SCRIPT" --restart'], { cwd: brokkRoot, env, ... });
+```
+
+`missing` (recorded holder dead / zombie / pid reused) no longer punts to `bin/saga-session-start.sh`: Gná reclaims the helm directly (`reclaimStaleLock`, mirroring `gleipnir_lock_acquire` — pid + starttime sidecar + `state/.lock-path` pointer) and arms immediately, so a leftover lock can never strand supervision.
+
+Continuity: `classifyClose` separates **actionable** (`signal:`/`stale:`/`check:`/`heartbeat:` line) from **failure**. Actionable → `restoreAfterActionableClose` (retries with backoff) then `deliverActionableWake` (encodes a `watcher` Rödd message and `pi.sendUserMessage(..., {deliverAs:"followUp"})`). Failure → `scheduleRetry`. Retry knobs: `BROKK_WATCH_REARM_RETRY_BASE_MS` (250), `..._MAX_MS` (4000), `..._LIMIT` (5); readiness `BROKK_PI_ARM_READY_TIMEOUT_MS` (12s, 35s on win32); retire `BROKK_WATCH_ARM_RETIRE_TIMEOUT_MS` (1000).
+
+On an actionable close, Gná calls `bin/syn-watch-arm.sh --handling-delivered <generation> --watcher-pid <pid>` to acknowledge handling; the script prints `watcher: handling delivered ...` and exits 0 (`bin/syn-watch-arm.sh:26-31`).
+
+Loaded markers written by the extensions (skipped while lock is `other`):
+
+| Marker | Written by |
+|---|---|
+| `state/.pi-syn-turnend-loaded` | Sýn `markLoaded()` |
+| `state/.pi-gna-watch-loaded` | Gná `markLoaded()` |
+
+Content is `<extensionVersion sha256>\n<pid>\n`.
+
+---
+
+## 5. Trust
+
+Pi will not auto-load tracked `.pi/extensions/*.ts` until the project is trusted. **Approve the project trust prompt once per clone on first launch.** If trust is not approved, the extensions never load and the session is unseated.
+
+Upstream's trust-free fallback is to launch the selected executable with the extension flags explicitly:
+
+```bash
+pi -e .pi/extensions/syn-turnend-guard.ts -e .pi/extensions/gna-pi-watch.ts
+```
+
+Use this only for diagnosis or an untrusted checkout; the production path is the trust prompt.
+
+---
+
+## 6. Install / enable / verify
+
+### Enable
+
+Extension files must be present under `.pi/extensions/`. Signing/selection is a Pi-side concern (`BROKK_PI_HARNESS=pi-signed` selects the `pi-signed` identity in `bin/hamr-harness.sh`).
+
+### Verify loading
+
+```bash
+cd "$BROKK_HOME"
+# Markers are written on extension load (and session_start for Sýn).
+test -f state/.pi-syn-turnend-loaded && echo "Sýn loaded: $(head -n1 state/.pi-syn-turnend-loaded)"
+test -f state/.pi-gna-watch-loaded   && echo "Gná loaded: $(head -n1 state/.pi-gna-watch-loaded)"
+```
+
+### Verify the digest before the first turn
+
+```bash
+# What Sýn runs under Vörðr:
+node .pi/extensions/lib/vordr-sessionstart-supervisor.mjs bin/saga-sessionstart-run.sh --source startup --pi-prerequisite | head -n 20
+echo "exit=$?"   # wrapper exits 0; Vörðr reports {type:"result",code,bytes}
+# Direct wrapper for comparison:
+bin/saga-sessionstart-run.sh --source startup --pi-prerequisite | head -n 5
+```
+
+### Verify the turn-end guard
+
+```bash
+rm -f state/.supervision-armed
+echo '{"stop_hook_active":false}' | bin/syn-turnend-guard.sh; echo "inert -> $? (expect 0)"
+touch state/.supervision-armed; rm -f state/.watch.heartbeat
+echo '{"stop_hook_active":false}' | bin/syn-turnend-guard.sh; echo "armed+stale -> $? (expect 2)"
+```
+
+### Verify the seatbelts as `tool_call` would
+
+```bash
+bin/syn-cd-pretool-check.sh  --command 'cd ../../etc';            echo "cd -> $? (expect 2)"
+bin/syn-arm-pretool-check.sh --command 'bin/syn-watch-arm.sh &';  echo "arm -> $? (expect 2)"
+```
+
+### Verify Gná's arm tool path
+
+```bash
+# With a live lock owned by this process tree:
+bash -lc 'BROKK_SESSION_PID=$$ exec bin/syn-watch-arm.sh --restart' &
+sleep 1; test -s state/.watch.heartbeat && echo "heartbeat ok"
+bin/syn-watch-arm.sh --handling-delivered test-gen --watcher-pid 12345
+```
+
+---
+
+## 7. Gotchas
+
+- **Gná is Pi-only.** OpenCode's watcher is **Sýn** (`.opencode/plugins/syn-watch-arm.js`). Do not look for `gna-*` in `.opencode/`.
+- **Neither extension is inert by accident.** Sýn's guard is inert until `state/.supervision-armed` exists; arm first, then test.
+- **`supervised` only on non-Windows.** On Windows Sýn runs the runner directly with no Vörðr and no IPC; completion comes from the `close` event. Do not assume the IPC result path exists cross-platform.
+- **Vörðr kills its process group on disconnect.** If Pi dies, the digest child is SIGKILLed. A lingering `VORDR_SESSIONSTART_SUPERVISOR_PID` means the reap failed.
+- **The digest is capped at 512 KiB.** A large digest is truncated with an explicit marker; treat omitted context as unread.
+- **`session_compact` bypasses `before_agent_start`.** The compact handler calls `pi.sendMessage` directly; if you refactor delivery, keep both paths.
+- **`guardFollowupActive` is module-global.** It assumes one guard cycle at a time; concurrent settles can drop one due to the boolean.
+- **`markLoaded()` refuses while the lock is `other`.** A read-only Pi session will not write markers, so absence of a marker alone does not prove the extension failed to load.
+- **Tool event filtering is `event.toolName === "bash"`.** A renamed shell tool disables both seatbelts silently.
+- **Trust is per clone.** A fresh clone or a copied home that never approved the prompt has no loaded extensions. Restart with explicit `-e` flags only to diagnose.
+- **`.pi/extensions/README.md:36-38` is stale.** It claims "the `.opencode` plugins and Claude/Grok/Codex/Cursor/adapters … are still to come." They are landed; see [`opencode.md`](opencode.md), [`claude-code.md`](claude-code.md), [`codex.md`](codex.md), [`cursor.md`](cursor.md). Grok remains unimplemented in Ymir.
+- **`vordr` and `rodd` use different extensions** (`.mjs` vs `.ts`) deliberately: Vörðr is a plain Node child, so it cannot import the Pi TypeScript lib.
+
+**Skills.** Pi discovers skills **natively** — it walks up from the cwd to `.agents/skills` (and `~/.agents/skills`), and `--skill <path>` adds more; `--no-skills` disables discovery. No link and no config: a second root under `.pi/` would double-load the same skill.