@zerwiz/ymir 0.1.3 → 0.1.5

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

@@ -0,0 +1,197 @@
+# Claude Code Harness Adapter
+
+> **Purpose:** Rebuild, verify, or extend the Claude Code adapter — the `.claude/settings.json` `SessionStart` and `Stop` hooks that run the Sága digest at session open and re-arm **Sýn** + guard the turn end at Stop.
+
+Claude Code is a **run-tier** harness: `SessionStart` hook stdout is injected into the session context, so the digest is seated before the model acts. Claude is **not** an Eindri dispatch target in Ymir (the verified launch set is `opencode pi pi-signed`), but it is a fully wired Brokk surface.
+
+---
+
+## 1. Files
+
+| File | Contract parts |
+|---|---|
+| `.claude/settings.json` | Session-open injection + turn-end guard + re-arm |
+
+There is **no** PreToolUse seatbelt in Ymir's `.claude/settings.json` (upstream Brokk has them; see §7). There is no `.claude/hooks/` directory and no plugin runtime — Claude's adapter is pure hook JSON.
+
+---
+
+## 2. The hook file (verbatim)
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ -z \"${GROK_AGENT:-}${GROK_HOOK_EVENT:-}\" ] || exit 0; exec \"$CLAUDE_PROJECT_DIR\"/bin/saga-sessionstart-run.sh",
+            "timeout": 180
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ -z \"${GROK_AGENT:-}${GROK_HOOK_EVENT:-}\" ] || exit 0; exec \"$CLAUDE_PROJECT_DIR\"/bin/syn-turnend-guard.sh --claude"
+          },
+          {
+            "type": "command",
+            "command": "[ -z \"${GROK_AGENT:-}${GROK_HOOK_EVENT:-}\" ] || exit 0; out=$(exec \"$CLAUDE_PROJECT_DIR\"/bin/syn-watch-arm.sh --restart); rc=$?; case \"$out\" in *signal:*|*stale:*|*check:*|*heartbeat:*) printf '%s\n' \"$out\" >&2; exit 2;; esac; exit $rc",
+            "asyncRewake": true,
+            "timeout": 28800
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`.claude/settings.json` is 31 lines; the entire adapter is these two hook groups.
+
+---
+
+## 3. SessionStart — run-tier injection
+
+### Command anatomy
+
+```bash
+[ -z "${GROK_AGENT:-}${GROK_HOOK_EVENT:-}" ] || exit 0     # (1) skip when a Grok hook process reuses Claude settings
+exec "$CLAUDE_PROJECT_DIR"/bin/saga-sessionstart-run.sh    # (2) run the wrapper; stdout is injected
+```
+
+1. **The Grok guard.** Claude Code is Claude-compatible and Grok reuses `.claude/settings.json`; a Grok hook process carries `GROK_AGENT` or `GROK_HOOK_EVENT`. If either is set, the hook exits 0 without running, so the digest is not taken twice. (Grok's own adapter is not implemented in Ymir, but this guard is retained from the upstream pattern and is harmless.)
+2. **`$CLAUDE_PROJECT_DIR`** is Claude's project root env var; the runtime root is derived from it directly, not from `pwd`. The runtime must be at `$CLAUDE_PROJECT_DIR/bin/`.
+3. **`exec`** replaces the shell so the hook's exit status is the wrapper's. `timeout: 180` seconds.
+
+### Run vs nudge on this hook
+
+The wrapper is run-tier here, but it still routes internally:
+
+| `source` (from hook stdin JSON) | Wrapper behavior |
+|---|---|
+| `startup`, `new` | run `bin/saga-session-start.sh`; write `state/.session-start-complete` |
+| `clear`, `compact` | if already complete, print a short `CONTEXT RE-EMIT` note; else run the full digest |
+| `resume`, `reload`, `fork` | print the nudge line: `Run \`bash .../bin/saga-session-start.sh\` exactly once now ...` |
+
+Claude sends a JSON payload on stdin shaped like `{"source":"startup",...}`; `bin/saga-sessionstart-run.sh` parses it without `jq` (`bin/saga-sessionstart-run.sh:34-44`). If `source` is absent or unrecognized it defaults to `startup` — taking the helm redundantly is cheap; not taking it is the bug.
+
+> **Exit-code law.** Claude's `SessionStart` hook exit 2 blocks session initialization. The wrapper therefore **always exits 0 on the transport path** (`bin/saga-sessionstart-run.sh` header comment). A failed session start must arrive as digest text the agent can act on, never as a refusal to open. Do not add a hook that can fail the open.
+
+---
+
+## 4. Stop — turn-end guard + re-arm
+
+Stop runs **two independent commands**, in order.
+
+### 4.1 Turn-end guard
+
+```bash
+[ -z "${GROK_AGENT:-}${GROK_HOOK_EVENT:-}" ] || exit 0
+exec "$CLAUDE_PROJECT_DIR"/bin/syn-turnend-guard.sh --claude
+```
+
+- `--claude` is a compatibility tag. The current guard has **no argument parsing**, so it is ignored; do not rely on it changing behavior. (The peer `--cursor` tags *are* parsed by the seatbelt scripts, which ignore them via a `*)` branch.)
+- stdin receives `{"stop_hook_active":false}`, which the guard drains (`cat >/dev/null`).
+- **exit 0** when supervision is healthy or was never armed.
+- **exit 2** when supervision was armed and the watcher is missing/stale; stderr carries:
+  ```
+  Brokk supervision is off: the watcher cycle is missing, failed, or unhealthy.
+  Recovery: re-arm through the harness extension (gna_watch_arm). Do not end the turn blind.
+  ```
+  Claude surfaces the stderr and re-prompts instead of ending the turn.
+
+### 4.2 Async re-arm
+
+```bash
+out=$(exec "$CLAUDE_PROJECT_DIR"/bin/syn-watch-arm.sh --restart); rc=$?
+case "$out" in *signal:*|*stale:*|*check:*|*heartbeat:*) printf '%s\n' "$out" >&2; exit 2;; esac
+exit $rc
+```
+
+- `"asyncRewake": true`, `"timeout": 28800` (8 hours) keeps the arm running out of band at the end of a turn — this is Claude's continuity mechanism in lieu of a plugin-owned child.
+- Any actionable line (`signal:` / `stale:` / `check:` / `heartbeat:`) is printed to stderr and forces exit 2, which rewakes the session.
+- Otherwise the arm's own exit code is passed through.
+
+### Why two Stop hooks
+
+The guard answers "is supervision healthy right now?"; the arm answers "keep it healthy". They are separate commands so a healthy guard never blocks the re-arm, and an actionable arm always forces a rewake even if the guard's heartbeat window still looked fresh.
+
+---
+
+## 5. Install / enable / verify
+
+### Enable
+
+`.claude/settings.json` is tracked and project-local; Claude Code reads it automatically. No symlink or registration is needed. The runtime scripts it calls must exist under `$CLAUDE_PROJECT_DIR/bin/`.
+
+### Syntax / schema
+
+```bash
+cd "$BROKK_HOME"
+python3 -m json.tool .claude/settings.json >/dev/null && echo "claude settings JSON ok"
+```
+
+### Verify SessionStart exactly as the hook runs
+
+```bash
+printf '{"source":"startup"}' | "$BROKK_HOME/bin/saga-sessionstart-run.sh" | head -n 20
+printf '{"source":"startup"}' | "$BROKK_HOME/bin/saga-sessionstart-run.sh" >/dev/null; echo "exit=$? (must be 0)"
+printf '{"source":"resume"}' | "$BROKK_HOME/bin/saga-sessionstart-run.sh" | head -n 2
+# expected: Run `bash .../bin/saga-session-start.sh` exactly once now ...
+```
+
+### Verify Stop
+
+```bash
+# Guard, inert:
+rm -f state/.supervision-armed
+echo '{"stop_hook_active":false}' | bin/syn-turnend-guard.sh --claude; echo "inert -> $? (expect 0)"
+# Guard, armed + stale:
+touch state/.supervision-armed; rm -f state/.watch.heartbeat
+echo '{"stop_hook_active":false}' | bin/syn-turnend-guard.sh --claude; echo "armed+stale -> $? (expect 2)"
+
+# Re-arm command body, emulated (must own the lock):
+state=$(mktemp -d)
+out=$(BROKK_STATE_OVERRIDE="$state" BROKK_HOME="$BROKK_HOME" bin/syn-watch-arm.sh --restart); rc=$?
+case "$out" in *signal:*|*stale:*|*check:*|*heartbeat:*) echo "would rewake";; esac
+echo "arm rc=$rc"
+```
+
+### Verify the Grok guard
+
+```bash
+# With a Grok marker set, both hooks must no-op with exit 0.
+GROK_AGENT=1 bash -c '[ -z "${GROK_AGENT:-}${GROK_HOOK_EVENT:-}" ] || exit 0; echo "skipped"'
+```
+
+---
+
+## 6. Gotchas
+
+- **Do not let SessionStart exit non-zero.** Exit 2 blocks Claude session initialization. The wrapper is designed to always exit 0; a hook that wraps it must preserve that.
+- **`$CLAUDE_PROJECT_DIR` must point at the runtime root.** Ymir's scripts are rooted at `$CLAUDE_PROJECT_DIR/bin`; if the runtime is installed elsewhere, set the env var or the hooks no-op/err.
+- **The Grok guard is load-bearing, not cosmetic.** Claude-compatible harnesses (Grok) reuse `.claude/settings.json`; without the `GROK_AGENT`/`GROK_HOOK_EVENT` guard the digest would run twice.
+- **`asyncRewake` re-arm is the only continuity on Claude.** There is no long-lived plugin child; if the Stop hook is removed or its timeout shortened, supervision dies at the first turn end.
+- **No PreToolUse seatbelts here.** Ymir's `.claude/settings.json` omits the arm/cd PreToolUse entries that upstream Brokk ships. A model bash call that backgrounds `syn-watch-arm.sh` is therefore not blocked on Claude. Treat this as a known gap (§7) and rely on the guard, not the seatbelt.
+- **The Stop guard and re-arm are independent.** Removing one silently degrades supervision: no guard → blind turn ends; no arm → immediate stale heartbeat.
+- **stdin is consumed.** Hook commands receive JSON on stdin; any wrapper you add must not block reading it. The guard drains stdin itself.
+- **`timeout: 28800` is deliberate.** Shortening the Stop arm timeout causes it to be killed mid-session and the guard to report stale on the next turn.
+
+---
+
+## 7. Known gaps (code-vs-doc)
+
+| Plan 29 §7 says | Ymir `.claude/settings.json` truth |
+|---|---|
+| Claude Code is `SessionStart` + `Stop` | correct — those are the only two hook groups present |
+| (implicit: same four contract parts as other harnesses) | **no `PreToolUse`** arm/cd seatbelts are registered |
+
+Upstream Brokk registers two `PreToolUse` entries (`Bash` matcher → `fm-arm-pretool-check.sh --claude`, `fm-cd-pretool-check.sh --claude`). To close the gap, add the equivalent `PreToolUse` block calling `bin/syn-arm-pretool-check.sh --claude` and `bin/syn-cd-pretool-check.sh --claude`. Do not assume the seatbelt is active until it is added and smoke-tested.
+
+**Skills.** This harness reads project skills from `.claude/skills/`; `bin/valknut-load.sh` binds it to the one tree (`.claude/skills -> ../.agents/skills`). Never copy a `SKILL.md` in — a copy is drift, and a nested `SKILL.md` with frontmatter is loaded as a phantom skill.

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

@@ -0,0 +1,191 @@
+# Codex Harness Adapter
+
+> **Purpose:** Rebuild, verify, or extend the Codex adapter — the `.codex/hooks.json` `SessionStart`, `PreToolUse`, and `Stop` hooks that run the Sága digest, enforce the seatbelts, and guard the turn end, gated by `[features].hooks = true`.
+
+Codex is a **run-tier session-open** harness when the hooks feature is enabled. Each hook is a defensive `bash -lc` one-liner that self-locates with `pwd -P`, self-verifies that it is really registered in the project's `.codex/hooks.json`, and only then calls the runtime.
+
+---
+
+## 1. Files and gate
+
+| File | Role |
+|---|---|
+| `.codex/hooks.json` | project hook registrations (SessionStart, PreToolUse, Stop) |
+| `~/.codex/config.toml` | must contain `[features]\nhooks = true` for hooks to load |
+
+Codex will not run project hooks unless the feature flag is on. The observed global config on this host:
+
+```toml
+[features]
+  hooks = true
+```
+
+There is no plugin runtime and no per-harness script directory; the adapter is the hook JSON plus the feature flag.
+
+---
+
+## 2. The hook file (verbatim)
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -lc 'payload=$(cat 2>/dev/null || true); [ -n \"$payload\" ] || exit 0; command -v jq >/dev/null 2>&1 || exit 0; root=$(pwd -P) || exit 0; [ -x \"$root/bin/saga-sessionstart-run.sh\" ] || exit 0; [ -f \"$root/AGENTS.md\" ] || exit 0; [ -f \"$root/.codex/hooks.json\" ] || exit 0; jq -e \"any(.hooks.SessionStart[]?.hooks[]?.command?; type == \\\"string\\\" and contains(\\\"saga-sessionstart-run.sh\\\"))\" \"$root/.codex/hooks.json\" >/dev/null 2>&1 || exit 0; printf \"%s\" \"$payload\" | \"$root/bin/saga-sessionstart-run.sh\"'",
+            "timeout": 180
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "bash -lc '... | \"$root/bin/syn-arm-pretool-check.sh\"'", "timeout": 10 },
+          { "type": "command", "command": "bash -lc '... | \"$root/bin/syn-cd-pretool-check.sh\"'",  "timeout": 10 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "bash -lc '... | \"$root/bin/syn-turnend-guard.sh\"'", "timeout": 30 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+(The PreToolUse/Stop commands are long; their full text is in `.codex/hooks.json:20`, `:25`, `:36`. Each is the same defensive preamble plus the owner script.)
+
+---
+
+## 3. The defensive preamble (shared by every hook)
+
+Every hook uses the same `bash -lc` shape. Read it as a fail-closed gate:
+
+```bash
+payload=$(cat 2>/dev/null || true)          # 1. read the hook JSON payload
+[ -n "$payload" ] || exit 0                 #    no payload → no-op
+command -v jq >/dev/null 2>&1 || exit 0     # 2. jq is required for payload handling/verification
+root=$(pwd -P) || exit 0                    # 3. Codex runs the hook from the project root
+[ -x "$root/bin/<script>" ] || exit 0       # 4. the runtime script must exist and be executable
+[ -f "$root/AGENTS.md" ] || exit 0          # 5. this must look like a Brokk home
+[ -f "$root/.codex/hooks.json" ] || exit 0  # 6. this project's hook file must exist
+jq -e "any(.hooks.<Event>[]?.hooks[]?.command?; type == \"string\" and contains(\"<script>\"))" \
+   "$root/.codex/hooks.json" >/dev/null 2>&1 || exit 0   # 7. self-verify registration
+printf "%s" "$payload" | "$root/bin/<script>"            # 8. run the owner script
+```
+
+The **self-verification** step (7) is the distinctive Codex safeguard: the hook refuses to run unless the project's own `.codex/hooks.json` still declares a command containing the target script name. A copy of the hook JSON placed in a foreign home, or a hijacked registration, no-ops instead of running the runtime.
+
+`root=$(pwd -P)` resolves symlinks, so a hook launched through a symlinked path still resolves the real project root.
+
+---
+
+## 4. Per-event behavior
+
+### 4.1 `SessionStart` → `bin/saga-sessionstart-run.sh`
+
+- Pipes the JSON payload into the wrapper; the wrapper parses `source` without `jq` (`bin/saga-sessionstart-run.sh:34-44`).
+- Source routing is the same as Claude: `startup`/`new` run the digest; `clear`/`compact` re-emit after a completed startup; `resume`/`reload`/`fork` nudge.
+- `timeout: 180`.
+- The wrapper always exits 0 on the transport path; a run-tier print of the digest reaches model context.
+
+### 4.2 `PreToolUse` (matcher `Bash`) → seatbelts
+
+Two hooks, each piping the payload to an owner script:
+
+```bash
+... printf "%s" "$payload" | "$root/bin/syn-arm-pretool-check.sh"
+... printf "%s" "$payload" | "$root/bin/syn-cd-pretool-check.sh"
+```
+
+- `timeout: 10`.
+- Exit **2** blocks the Bash call; the reason is on stderr.
+- These scripts normally take `--command <cmd>`; in the Codex flow the command is carried in the payload. The owner scripts are the policy holders either way.
+
+### 4.3 `Stop` → `bin/syn-turnend-guard.sh`
+
+- Pipes the payload (typically `{"stop_hook_active":false}`) into the guard.
+- Exit **2** surfaces the recovery instruction and re-prompts instead of letting the turn end blind.
+- `timeout: 30`.
+- **No re-arm.** Codex has no async Stop continuation in this adapter, so there is no long-lived arm child. The guard is inert until something else writes `state/.supervision-armed`.
+
+---
+
+## 5. Install / enable / verify
+
+### Enable the feature gate
+
+```bash
+# Codex global config must have:
+grep -A1 '^\[features\]' ~/.codex/config.toml   # expect: hooks = true
+```
+
+If absent, add:
+
+```toml
+[features]
+hooks = true
+```
+
+### Syntax / schema
+
+```bash
+cd "$BROKK_HOME"
+python3 -m json.tool .codex/hooks.json >/dev/null && echo "codex hooks JSON ok"
+command -v jq >/dev/null && echo "jq present" || echo "jq MISSING - adapter will no-op"
+```
+
+### Verify the session-open path
+
+```bash
+printf '{"source":"startup"}' | bin/saga-sessionstart-run.sh | head -n 20; echo "exit=$?"
+printf '{"source":"compact"}' | bin/saga-sessionstart-run.sh | head -n 3
+```
+
+### Verify the self-verification gate
+
+```bash
+# The jq expression the SessionStart hook runs; must be true in-tree:
+jq -e 'any(.hooks.SessionStart[]?.hooks[]?.command?; type == "string" and contains("saga-sessionstart-run.sh"))' .codex/hooks.json
+jq -e 'any(.hooks.PreToolUse[]?.hooks[]?.command?; type == "string" and contains("syn-arm-pretool-check.sh"))' .codex/hooks.json
+jq -e 'any(.hooks.Stop[]?.hooks[]?.command?; type == "string" and contains("syn-turnend-guard.sh"))' .codex/hooks.json
+# All three must print true and exit 0.
+```
+
+### Verify Stop
+
+```bash
+rm -f state/.supervision-armed
+printf '{"stop_hook_active":false}' | bin/syn-turnend-guard.sh; echo "inert -> $? (expect 0)"
+touch state/.supervision-armed; rm -f state/.watch.heartbeat
+printf '{"stop_hook_active":false}' | bin/syn-turnend-guard.sh; echo "armed+stale -> $? (expect 2)"
+```
+
+### Verify seatbelts
+
+```bash
+bin/syn-arm-pretool-check.sh --command 'bin/syn-watch-arm.sh &'; echo "arm -> $? (expect 2)"
+bin/syn-cd-pretool-check.sh  --command 'cd ../..';             echo "cd  -> $? (expect 2)"
+```
+
+---
+
+## 6. Gotchas
+
+- **`[features].hooks = true` is mandatory and lives in the global config**, not the project. Without it, `.codex/hooks.json` is ignored entirely.
+- **`jq` is a hard dependency.** Every hook exits 0 if `jq` is missing, disabling injection, seatbelts, and the guard.
+- **The self-verification step can brick the adapter after an edit.** If you rename `saga-sessionstart-run.sh` or `syn-arm-pretool-check.sh`, the `contains(...)` check silently starts returning false and the hooks no-op. Keep script names stable or update the strings in `.codex/hooks.json` in the same change.
+- **`pwd -P` requires Codex to launch hooks from the project root.** If a future Codex version runs hooks from elsewhere, the root resolves wrong and every gate fails closed (silent no-op).
+- **There is no re-arm.** Do not assume Codex owns supervision across turns; the guard is inert until an arm exists.
+- **No `PreToolUse` matcher for non-Bash tools.** Only `Bash` is guarded; other tool calls bypass the seatbelts by design.
+- **Payload shape is assumed JSON.** A hook with empty stdin no-ops (`[ -n "$payload" ]`).
+- **Do not simplify the preamble.** Each guard (`AGENTS.md`, `.codex/hooks.json`, executable bit, registration self-check) exists to keep the adapter from running in a foreign or partially installed home.
+
+**Skills.** This harness reads project skills from `.codex/skills/`; `bin/valknut-load.sh` binds it to the one tree (`.codex/skills -> ../.agents/skills`). Never copy a `SKILL.md` in — a copy is drift, and a nested `SKILL.md` with frontmatter is loaded as a phantom skill.

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

@@ -0,0 +1,193 @@
+# Cursor Harness Adapter
+
+> **Purpose:** Rebuild, verify, or extend the Cursor adapter — the `.cursor/hooks.json` project hooks that inject the Sága digest via `additional_context`, emit a turn-end `followup_message`, and run the PreToolUse seatbelts.
+
+Cursor is a **run-tier session-open** harness (it injects `additional_context`) and a **turn-end-only** harness (the `stop` hook returns a `followup_message`; there is no long-lived arm child). Cursor is not an Eindri dispatch target in Ymir, but it is a wired Brokk surface.
+
+---
+
+## 1. Files
+
+| File | Contract parts |
+|---|---|
+| `.cursor/hooks.json` | Session-open injection + turn-end guard + PreToolUse seatbelts |
+
+The adapter is pure hook JSON. There is no plugin runtime and no `.cursor/rules/` dependency.
+
+---
+
+## 2. The hook file (verbatim)
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "command": "digest=$(\"$CURSOR_PROJECT_DIR\"/bin/saga-sessionstart-run.sh --source startup </dev/null 2>/dev/null); [ -n \"$digest\" ] || exit 0; command -v jq >/dev/null 2>&1 || exit 0; jq -n --arg c \"$digest\" '{additional_context:$c}' 2>/dev/null || true",
+        "timeout": 180
+      }
+    ],
+    "stop": [
+      {
+        "type": "command",
+        "command": "guard=$(\"$CURSOR_PROJECT_DIR\"/bin/syn-turnend-guard.sh 2>&1 </dev/null); rc=$?; [ \"$rc\" -eq 2 ] || exit 0; command -v jq >/dev/null 2>&1 || exit 0; jq -n --arg m \"$guard\" '{followup_message:$m}' 2>/dev/null || true",
+        "timeout": 30
+      }
+    ],
+    "preToolUse": [
+      {
+        "matcher": "Shell",
+        "type": "command",
+        "command": "\"$CURSOR_PROJECT_DIR\"/bin/syn-arm-pretool-check.sh --cursor",
+        "timeout": 10
+      },
+      {
+        "matcher": "Shell",
+        "type": "command",
+        "command": "\"$CURSOR_PROJECT_DIR\"/bin/syn-cd-pretool-check.sh --cursor",
+        "timeout": 10
+      }
+    ]
+  }
+}
+```
+
+`.cursor/hooks.json` is 33 lines. `"version": 1` is Cursor's hook schema version and is required.
+
+---
+
+## 3. `sessionStart` — run-tier injection
+
+```bash
+digest=$("$CURSOR_PROJECT_DIR"/bin/saga-sessionstart-run.sh --source startup </dev/null 2>/dev/null)
+[ -n "$digest" ] || exit 0                  # no digest → no-op
+command -v jq >/dev/null 2>&1 || exit 0     # jq is required to shape JSON
+jq -n --arg c "$digest" '{additional_context:$c}' 2>/dev/null || true
+```
+
+- **Root** comes from `$CURSOR_PROJECT_DIR`.
+- **Source is explicit** (`--source startup`): unlike Claude/Codex, Cursor does not deliver a source-bearing JSON payload here.
+- **stdin is closed** (`</dev/null`) so the wrapper never blocks on a read.
+- **Output shape:** `{"additional_context": "<digest>"}`. Cursor injects that string as session context. This is the run-tier injection.
+- **`|| true`** means a `jq` failure degrades to no context rather than a failed hook. `jq` is a hard dependency for Cursor; without it the whole adapter no-ops.
+- `timeout: 180`.
+
+Cursor also loads the tracked Claude settings, so upstream guards against double-running. Ymir's `.cursor/hooks.json` passes an explicit `--source` and does **not** pipe a payload, so the wrapper does not run the foreign-host detection.
+
+---
+
+## 4. `stop` — turn-end guard
+
+```bash
+guard=$("$CURSOR_PROJECT_DIR"/bin/syn-turnend-guard.sh 2>&1 </dev/null); rc=$?
+[ "$rc" -eq 2 ] || exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+jq -n --arg m "$guard" '{followup_message:$m}' 2>/dev/null || true
+```
+
+- Runs the guard with **stderr merged into stdout** (`2>&1`), so the recovery text is captured.
+- Only exit **2** produces output; all other exits are silent (`exit 0`).
+- **Output shape:** `{"followup_message": "<guard text>"}`. Cursor posts that message as a follow-up to the session, which is how the blind-turn-end refusal reaches the model.
+- `timeout: 30`.
+
+There is **no re-arm** hook: Cursor has no async/background Stop continuation in this adapter. Supervision is expected to be owned elsewhere (or the session runs with the guard inert until an arm exists). Treat Cursor as the weakest supervision surface.
+
+---
+
+## 5. `preToolUse` — seatbelts
+
+Two entries, both `"matcher": "Shell"`:
+
+```bash
+"$CURSOR_PROJECT_DIR"/bin/syn-arm-pretool-check.sh --cursor   # timeout 10
+"$CURSOR_PROJECT_DIR"/bin/syn-cd-pretool-check.sh  --cursor   # timeout 10
+```
+
+- `--cursor` selects Cursor's transport semantics in the owner scripts.
+- Exit **2** blocks the shell call; the reason is on stderr.
+- `syn-arm-pretool-check.sh` denies a command that backgrounds `syn-watch-arm.sh`; `syn-cd-pretool-check.sh` denies `cd .../../`.
+- Both are inert-by-default contracts: they allow everything else.
+
+---
+
+## 6. Trust
+
+Cursor project hooks require the workspace to be launched with **`--trust`**. Without it, none of the project hooks load and Brokk is never seated.
+
+```bash
+cursor-agent --trust
+```
+
+Upstream Brokk also notes a hard limit worth carrying into Ymir: **headless `cursor-agent -p` has no turn-end hook**, so a Cursor primary must be run **interactively** for supervision to work. If Cursor is driven headlessly, only `sessionStart` and `preToolUse` fire.
+
+---
+
+## 7. Install / enable / verify
+
+### Enable
+
+`.cursor/hooks.json` is tracked and project-local. Cursor reads it when the workspace is trusted. The runtime scripts must exist under `$CURSOR_PROJECT_DIR/bin/`. `jq` must be installed.
+
+### Syntax / schema
+
+```bash
+cd "$BROKK_HOME"
+python3 -m json.tool .cursor/hooks.json >/dev/null && echo "cursor hooks JSON ok"
+command -v jq >/dev/null && echo "jq present" || echo "jq MISSING - adapter will no-op"
+```
+
+### Verify sessionStart output shape
+
+```bash
+digest=$("$BROKK_HOME/bin/saga-sessionstart-run.sh" --source startup </dev/null 2>/dev/null)
+echo "digest bytes: ${#digest}"
+jq -n --arg c "$digest" '{additional_context:$c}' | jq -e 'has("additional_context")' && echo "shape ok"
+```
+
+### Verify stop output shape
+
+```bash
+# Inert guard:
+rm -f state/.supervision-armed
+guard=$(bin/syn-turnend-guard.sh 2>&1 </dev/null); rc=$?
+echo "rc=$rc (expect 0; no followup_message emitted)"
+
+# Armed + stale → emit followup_message:
+touch state/.supervision-armed; rm -f state/.watch.heartbeat
+guard=$(bin/syn-turnend-guard.sh 2>&1 </dev/null); rc=$?
+echo "rc=$rc (expect 2)"
+[ "$rc" -eq 2 ] && jq -n --arg m "$guard" '{followup_message:$m}' | jq -e 'has("followup_message")' && echo "shape ok"
+```
+
+### Verify preToolUse
+
+```bash
+bin/syn-arm-pretool-check.sh --cursor --command 'bin/syn-watch-arm.sh &'; echo "arm -> $? (expect 2)"
+bin/syn-cd-pretool-check.sh  --cursor --command 'cd ../..';             echo "cd  -> $? (expect 2)"
+```
+
+> Note: `--command` and `--cursor` are both parsed by the owner scripts; the hook commands above pass only `--cursor` because in the real hook the command text arrives on stdin. For a local smoke test, pass `--command` explicitly.
+
+---
+
+## 8. Gotchas
+
+- **`--trust` is mandatory.** No trust → no hooks → no Brokk.
+- **`jq` is a hard dependency.** Both `sessionStart` and `stop` shape JSON with `jq` and exit 0 if it is missing. A missing `jq` silently disables injection and the guard.
+- **Headless Cursor has no turn-end hook.** `cursor-agent -p` fires only `sessionStart`/`preToolUse`; run interactively for supervision.
+- **`stop` is guard-only; there is no arm.** `syn-turnend-guard.sh` is inert until something else arms supervision. With no arm on Cursor, the guard's exit 2 only occurs if an arm exists from another source. Do not claim Cursor has turn-end supervision until an arm path is verified.
+- **stderr is merged into stdout in `stop`.** Do not "clean up" `2>&1`; the guard's recovery text lives on stderr.
+- **Explicit `--source startup` means resume/compact are not differentiated.** Cursor always takes the full digest at session open. Acceptable (redundant but cheap), but it means a resumed Cursor session re-runs the digest rather than nudging.
+- **`|| true` hides `jq` failures.** A malformed digest cannot fail the hook; it just produces no context. Diagnose by running the two commands by hand.
+- **`matcher: "Shell"` is exact.** If Cursor renames the shell tool, both seatbelts stop firing.
+- **PreToolUse timeout is 10s.** A slow `bin/syn-*-pretool-check.sh` call can time out and allow the command; keep the owner scripts fast (they are pure `case` matches).
+
+---
+
+## 9. Code-vs-doc note
+
+Plan 29 §7 describes Cursor as "run interactive only (no headless turn-end)". The code matches that limitation, but it **also** implements a `sessionStart` `additional_context` injection and a `stop` `followup_message`. So Cursor is a full session-open + turn-end surface interactively — not merely a runner.
+
+**Skills.** This harness reads project skills from `.cursor/skills/`; `bin/valknut-load.sh` binds it to the one tree (`.cursor/skills -> ../.agents/skills`). Never copy a `SKILL.md` in — a copy is drift, and a nested `SKILL.md` with frontmatter is loaded as a phantom skill.