@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/hamr-adapters/references/common/primary-hooks.md

@@ -0,0 +1,40 @@
+# Primary startup and hooks
+
+Load this with the detected primary's tool reference before changing session startup, turn-end handling, pre-tool protection, watcher supervision, or Eindri-home integration.
+The tool reference establishes either that identity's empirical path or its unsupported boundary.
+
+## Turn end
+
+`../../../docs/turnend-guard.md` owns the "no turn ends blind" contract, hook installation, per-surface blocking behavior, and tradeoffs when a hook cannot block.
+`../../../docs/supervision-protocols/` and `../../../bin/brokk-supervision-instructions.sh` own harness-specific wake protocols.
+Never substitute another harness's wait shape.
+`../../../bin/brokk-busy-lib.sh` remains the semantic busy owner; a tool reference names only its source and evidence.
+
+Validate any turn-end change against the real harness in a scratch project or throwaway home.
+Update its executable or hook owner, concise tool fact, and `../../../docs/verification/supervision.md` under "Turn-end guard".
+
+## Pre-tool protection
+
+Supported primaries deny watcher-arm anti-patterns before execution, including shell `&`, truncating pipes, bundling, and broad `pkill -f brokk-watch`.
+`../../../docs/arm-pretool-check.md` owns hook commands, output quirks, and evidence.
+The tool reference names the integration form.
+Validate changes against the real harness in a scratch project before trusting them.
+
+A primary must also account for built-in delegation that can create work outside Brokk's durable records.
+Claude's verified delegation guard is in `references/harness/claude.md`.
+`../../../docs/subagent-guard.md` owns its full contract, local hardening, escape hatch, and per-harness applicability review.
+Never generalize Claude tool names or permissions without live evidence.
+
+## Session start
+
+`../../../AGENTS.md` section 3 remains the behavioral owner.
+`../../../docs/sessionstart-nudge.md` owns native tier assignment, transport, source routing, runtime bound, and fail-open behavior.
+Read it before changing session-open behavior.
+`../../../docs/verification/supervision.md` under "Native session-start delivery" owns active dated evidence.
+
+## Watcher supervision
+
+`../../../bin/saga-session-start.sh` prints exactly one block for the detected primary.
+Follow only that rendered protocol.
+When changing a watcher adapter, update its file under `../../../docs/supervision-protocols/`, update `../../../docs/turnend-guard.md` if shared idle or turn-end behavior changed, and refresh the tool fact.
+An identity without a dedicated protocol uses its documented unsupported or unknown boundary; never invent one from a similar TUI.

package/.agents/skills/hamr-adapters/references/harness/claude.md

@@ -0,0 +1,55 @@
+# Claude
+
+Busy hooks verified 2026-07-28 on Claude Code 2.1.220.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Busy | Owned hooks: `UserPromptSubmit` opens while `Stop`, `StopFailure`, and `SessionEnd` close; manual interrupt emits no hook, so control reports delivered keys and live endpoint only, publishes no idle event or cancellation claim, and usually leaves `claude-hook` busy. |
+| Exit | `/exit`. |
+| Interrupt | Single Escape. |
+| Skill | `/<skill>`, for example `/no-mistakes`. |
+| Model | `--model <model>`; discover through the interactive `/model` picker, with alias or full-name shape documented by `claude --help`. |
+| Effort | `--effort <low\|medium\|high\|xhigh\|max>`, verified on 2.1.196. |
+
+Fresh-worktree or first-machine launch may show trust or bypass-permissions confirmation.
+Inspect within about 20 seconds, accept the required choice with `BROKK_HOME=<active-home> ../../../bin/brokk-send.sh <window> --key Enter` unless already bound, and verify instructions started.
+
+## Composer ghost
+
+Completed turns can render dim predicted text inside an empty composer, indistinguishable in plain `tmux capture-pane`.
+The spawn scopes `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false` to every Claude worker and Eindri-home without changing global config.
+CLI `--prompt-suggestions` affects print or SDK mode only and did not suppress interactive ghost text on v2.1.186.
+
+As defense in depth, `fm_composer_strip_ghost` in `../../../bin/brokk-composer-lib.sh` removes SGR-2 runs before pending classification on styled tmux, Herdr, and Zellij readers.
+`../../../docs/herdr-backend.md` under "Composer and injection safety" owns dark-TRUECOLOR tradeoffs and `../../../docs/verification/runtime-backends.md` owns captures.
+Styled capture stays internal to the boolean detector; `brokk-peek` and model-facing captures remain plain, without escapes.
+
+## Primary integration
+
+Primary behavior was verified 2026-07-04 on 2.1.201, preserved 2026-07-08 on 2.1.204, and Stop auto-arm revalidated 2026-07-24 on 2.1.219.
+This differs from the worker hook, which only touches a task marker through `.claude/settings.local.json`.
+
+Primary `.claude/settings.json` registers `../../../bin/syn-turnend-guard.sh --claude` and `../../../bin/brokk-claude-stop-autoarm.sh` with `asyncRewake: true` and `timeout: 28800`.
+Guard exit 2 plus stderr forces continuation.
+Stop payload `stop_hook_active=true` follows any hook-driven continuation, including async reawakening, so Claude mode ignores it and uses cooperative claim and epoch plus bounded re-block; default Codex mode keeps it as a one-block loop guard.
+
+Project `.claude/settings.json` loads only when the exact project root is the session root; Claude does not search parents, so Brokk starts at repository root.
+Hooks still run through cwd-sensitive `/bin/sh`, so tracked commands anchor through `"$CLAUDE_PROJECT_DIR"/bin/...`.
+`../../../docs/turnend-guard.md` owns details.
+
+The Stop-owned watcher hook runs every Stop, foregrounds `../../../bin/syn-watch-arm.sh` only when eligible, and uses exit-2 async reawakening as notification.
+The model handles notifications but never routine re-arm.
+Claude's PreToolUse seatbelt blocks directly, and its deny is honored only with empty stdout; `../../../docs/arm-pretool-check.md` owns that contract.
+
+### Delegation guard
+
+Claude delegation, scheduling, and worktree tools can create work without `state/<id>.meta`, making guards unable to count it.
+`../../../bin/brokk-subagent-pretool-check.sh` denies delegation-shaped tool names.
+A primary should also keep an untracked home-local `permissions.deny` for known delegation tools so they disappear from the schema.
+Never track it in project `.claude/settings.json`, which is Claude-only and propagates to worker copies where it would disarm legitimate delegation.
+`../../../docs/subagent-guard.md` owns the contract, recommendation, `BROKK_ALLOW_SUBAGENT=1`, and applicability review.
+
+On Claude 2.1.217 the tool presents as `Agent`, and both `Agent` and `Task` worked as deny keys in an A/B with nonsense control.
+`permissions.allow` pre-approves rather than controls availability, so no closed positive allowlist exists.

package/.agents/skills/hamr-adapters/references/harness/codex.md

@@ -0,0 +1,43 @@
+# Codex
+
+Verified on 2026-06-11 with codex-cli 0.139.0 unless a fact gives a newer version.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Busy state | Unknown until a semantic source is live-verified: the app-server turn lifecycle is unreachable for a pane worker, and project lifecycle hooks did not fire for a Brokk-launched worker. |
+| Exit command | `/quit`; its slash popup needs about one second between text and Enter, which the shared submit path used by the control plane handles. |
+| Interrupt | Single Escape. |
+| Skill invocation | `$<skill>`, for example `$no-mistakes`; `/<skill>` is Claude-only and Codex rejects it as "Unrecognized command". |
+| Resume | `codex resume <session-id>`, using the id printed on quit. |
+| Model flag | `--model <model>`. |
+| Effort flag | `-c 'model_reasoning_effort="<low\|medium\|high\|xhigh>"'`, verified on codex-cli 0.142.1 whose installed schema contains `model_reasoning_effort`, active config uses it, and bundled catalog advertises only these four values while omitting `max`. |
+| Model discovery | Open the current interactive session's `/model` picker. |
+
+A directory trust dialog appears on the first run for a repository root: "Do you trust the contents of this directory?"
+Accept it with Enter and verify the instructions begin processing.
+The decision persists for the repository, so later worktrees of the same project skip it.
+
+## Skill popup
+
+A `$<skill>` invocation opens a `$` autocomplete popup.
+Submitting too fast lets the popup swallow Enter, so the invocation never lands.
+`../../../bin/brokk-send.sh` gives a leading `$` a 1.2-second settle before the first Enter only when the exact task metadata records `harness=codex`, with the target backend's submit retry as the safety net.
+That scope is load-bearing because a leading `$` commonly starts ordinary text such as `$5/month` or `$HOME`.
+An explicit `session:window` target has no metadata, so its harness is unknown and uses the non-Codex fast path.
+This is why `$no-mistakes` reaches a Codex worker instead of being consumed by the popup.
+
+## Primary integration
+
+The primary integration was verified on 2026-07-08 with codex-cli 0.142.1.
+The Brokk primary's `.codex/hooks.json` registers a Stop hook that pipes Codex's payload to `../../../bin/syn-turnend-guard.sh`.
+Codex Stop hooks preserve exit status 2 and stderr to block, and expose `stop_hook_active` for the same one-block loop safety used by the guard's default mode.
+
+The Stop payload includes `cwd`, but the tracked hook does not use it to choose the guard executable.
+Codex runs the Stop command with process PWD set to the hook-loaded project root, while no `CODEX_PROJECT_DIR`, `CODEX_WORKSPACE_ROOT`, or `CODEX_CWD` root variable is set.
+The tracked hook anchors to `pwd -P`, verifies that root is Brokk-shaped and hook-bearing, and then invokes the guard with the original payload.
+
+Codex's primary watcher protocol is `../../../bin/brokk-watch-checkpoint.sh --seconds "${BROKK_CODEX_WATCH_CHECKPOINT:-180}"`, not `../../../bin/syn-watch-arm.sh`.
+Codex cannot reason while a foreground tool call is running, so the checkpoint is deliberately foreground and bounded to return control regularly for user messages and queued notifications.
+Codex's PreToolUse watcher-arm seatbelt blocks directly through its project hook.

package/.agents/skills/hamr-adapters/references/harness/cursor.md

@@ -0,0 +1,75 @@
+# Cursor Agent
+
+Verified for crew and scout work on tmux on 2026-08-11 and Herdr on 2026-08-12, and for Eindri-home and primary work on 2026-08-13, with Cursor Agent CLI 2026.08.11-e8db854.
+Cross-harness provider and credential identity is owned by `references/common/model-and-effort.md`.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Binary | `fm_cursor_resolve_binary` in `../../../bin/brokk-cursor-lib.sh` resolves stable launcher `cursor-agent` or legacy `agent`, never `cursor`; both symlink into `~/.local/share/cursor-agent/versions/<version>/cursor-agent`, whose target auto-update replaces. |
+| Launch | Positional instructions with `--trust`, `--yolo`, optional `--model <model>`, and `--workspace <absolute-task-worktree>`, after clearing foreign primary markers. |
+| Models | Use current-account `cursor-agent --list-models` or legacy `agent --list-models`; the drifting observed list had only `cursor-grok-4.5-high` and `cursor-grok-4.5-high-fast` for Grok plus several `xhigh` ids, so choose a returned reasoning id and never assume low or medium Grok. |
+| Busy state | `../../../bin/brokk-busy-lib.sh` folds the per-conversation transcript as `cursor-transcript`: `role:user` opens and typed `turn_ended` closes success or abort, covering manual interrupt; nothing is armed or seeded, and this backend-agnostic source was identical on tmux and Herdr. |
+| Exit command | `/exit`. |
+| Interrupt | Single Escape returns the placeholder with no clear key; control makes no cancellation claim because an aborted transcript close appeared within seconds in some runs and not within twenty in others. |
+| Skill invocation | `/<skill>`, for example `/no-mistakes`; Cursor discovers Brokk's user skills. |
+| Resume | No verified native pane resume; use deterministic relaunch. |
+| Autonomy | `--yolo`, documented alias for `--force`; footer `Run Everything`. |
+| Trust | `--trust` suppresses the dialog; `--yolo` does not, and every task has a fresh path. |
+| Marker | `CURSOR_INVOKED_AS=cursor-agent` on agent and children, plus `CURSOR_AGENT=1` on child or tool processes; other `CURSOR_*` variables are not identity markers. |
+| Effort | No verified flag; `references/common/model-and-effort.md` owns unsupported-value handling. |
+| Composer | Bare borderless row with `→` (U+2192); de-emphasized placeholders `Plan, search, build anything` when fresh and `Add a follow-up` later. |
+
+The slash popup consumes the first Enter; that Enter closes it and a genuine second Enter submits through the shared retry.
+
+## Detection
+
+Cursor does not clear inherited `CLAUDECODE`, so a Cursor worker under Claude carries both markers.
+`../../../bin/hamr-harness.sh` tests Cursor first, and launch also clears foreign markers.
+Both remain necessary: sanitization covers Brokk launches, ordering covers hand-started sessions.
+
+Cursor is a bundled Node script, so tmux can report bare `node` while `ps -o comm=` carries its install path.
+Bare `node` matches nothing; `../../../bin/brokk-cursor-lib.sh` proves identity from Cursor's name or install tree in path or argv zero.
+Unrelated `node` or `agent` remains `other`, folded to ambiguous rather than dead.
+Auto-update changes the target, not this rule.
+
+## Composer and delivery
+
+Cursor parks its terminal cursor outside the composer: `#{cursor_y}` was below the footer idle and typed, with `#{cursor_flag}` zero, so cursor-anchored reads are always unknown.
+`../../../bin/brokk-tmux-lib.sh` lets the bottom-most shape win only after structural Cursor proof.
+The composite then reads empty or pending, verified on 2026-08-13, while every other harness keeps strict blank-cursor behavior and a dead shell never reads empty.
+`../../../bin/brokk-supervise-daemon.sh` can therefore require affirmatively empty before away-mode delivery without a Cursor-only branch.
+
+Submission also uses an idle-to-busy transition.
+Match stable token `ctrl+c to stop`, never spinner verbs that changed from `Working` to `Running` between turns.
+
+Confirmation is verified only on tmux and Herdr.
+Herdr reports Cursor `blocked` in every state, so its native idle path is unreachable; the composer path sees the mid-turn placeholder beside `ctrl+c to stop` as pending.
+`../../../bin/backends/herdr.sh` baselines before Enter and confirms the footer transition, so an already-busy pane cannot confirm.
+
+Zellij, cmux, and Orca do not consult that footer.
+A typed-plane native invocation or explicit backend send lands but reports unconfirmed and exits nonzero; ordinary steering uses the durable inbox and exits zero at enqueue.
+Treat this as confirmation failure, not loss, because text lands and busy state comes from the transcript.
+Teaching those backends is separate cross-harness work requiring live checks.
+
+Reverse-video placeholder remnants and Herdr half-block edges belong to `../../../bin/brokk-composer-lib.sh`; without the edges a bare composer swallows the footer and idle reads pending.
+`../../../docs/verification/runtime-backends.md` owns captures.
+Refresh with `BROKK_HARNESS_LIVENESS_DRIFT=1 ../../../bin/brokk-test-run.sh ../../../tests/brokk-harness-liveness-drift-live-e2e.test.sh`.
+
+## Worktree boundary
+
+Brokk enters its acquired worktree and passes the same absolute path through `--workspace`.
+Never pass Cursor `-w` or `--worktree`, which allocates a second copy under `~/.cursor/worktrees` and breaks isolation.
+The CLI supports repeatable `--add-dir`, but the adapter adds none; positional instructions need no grant to their private directory.
+Example: `../../../bin/einherjar-spawn.sh <task-id> <project> --scout --harness cursor --model cursor-grok-4.5-high`.
+
+## Primary integration
+
+Primary supervision is the stop-hook park in `../../../docs/supervision-protocols/cursor.md` through tracked `.cursor/hooks.json`; primary and Eindri-home launches require `--trust` or hooks do not load.
+Cursor exposes 20 project events plus a Claude-Code compatibility map that loads `.claude/settings.json`.
+Tracked hooks register `stop`, `sessionStart`, and two `preToolUse` seatbelts through `$CURSOR_PROJECT_DIR`; Claude entries stand down on Cursor payloads under `../../../docs/turnend-guard.md`.
+
+`stop` cannot block because exit 2 is a silent no-op, so `../../../bin/brokk-turnend-guard-cursor.sh` parks on supervision and returns one bounded `followup_message`.
+It does not fire in headless `cursor-agent -p`.
+`preCompact` is unregistered because it cannot inject context, so digest re-emission after Cursor compaction remains deferred.

package/.agents/skills/hamr-adapters/references/harness/grok.md

@@ -0,0 +1,69 @@
+# Grok Build
+
+The xAI `grok` TUI is Claude-Code-compatible.
+Verified initially on 2026-06-29 with 0.2.73, slash submission on 2026-07-03 with 0.2.82, effort on 2026-07-13 with 0.2.99, and exit on 2026-07-19 with 0.2.103.
+Launch shape: `grok --always-approve "$(cat <brief>)"`.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Busy state | The last rendered-tail fallback, isolated to Grok pending a semantic source: ASCII mid-turn `Ctrl+c:cancel`, absent from idle bar `Shift+Tab:mode │ Ctrl+.:shortcuts`, never the locale-fragile braille spinner. |
+| Exit | `/exit` prints `Resume this session with: grok --resume <session-id>`; fallback is `Ctrl+Q` twice within 1000ms, `Ctrl+D` quits in VS Code-family terminals, and `Ctrl+C` interrupts. |
+| Interrupt | Single `Ctrl+C`; Escape only focuses scrollback. |
+| Skill | `/<skill>`, for example `/no-mistakes`, with end-to-end user-skill discovery, invocation, and real `no-mistakes axi run` evidence; the popup may consume Enter and fill an argument placeholder, requiring a real second Enter. |
+| Autonomy | `--always-approve`, footer `· always-approve`, verified unattended; `--permission-mode bypassPermissions` is stronger equivalent. |
+| Marker | `GROK_AGENT=1` on child or tool processes in 0.2.73 and no `CLAUDECODE`; a 1.0.0 hook instead had `GROK_HOOK_EVENT`, `GROK_HOOK_NAME`, `GROK_SESSION_ID`, and `GROK_WORKSPACE_ROOT` without `GROK_AGENT`, so ancestry guarantees identity. |
+| Resume | `grok --resume <session-id>`, or `grok -c` / `--continue` for cwd latest; `--fork-session` creates a new id. |
+| Model | `--model <model>`; discover current account models with `grok models`. |
+| Effort | `--reasoning-effort <low\|medium\|high>`, alias `--effort`; version 0.2.99 rejects `xhigh` and `max` with `use one of: high, medium, low`; `references/common/model-and-effort.md` owns fallback and unsupported-value handling. |
+
+Reliable Grok rules must account for hook markers as well as the child fast path.
+`../../../docs/turnend-guard.md` under "Harness integrations" owns the marker contract.
+
+## Submission and startup
+
+Slash autocomplete can turn the first Enter into selection plus an argument hint, including `/no-mistakes`'s optional task argument or `/compact compaction instructions`, without submission.
+The shared classifier keeps that text pending, and retry sends the second Enter on both verified backends; Herdr may also prove a turn through native state.
+
+On 2026-07-03 two Grok 0.2.82 Herdr workers left `/no-mistakes` typed for minutes while send returned success.
+Old Herdr logic treated any pane delta as submission, including popup closure and placeholder fill.
+Tmux and Herdr now route captures through `../../../bin/brokk-composer-lib.sh`, which classifies real text on every proven content row.
+`../../../docs/herdr-backend.md` owns the boundary and `../../../tests/brokk-backend-herdr.test.sh` covers it.
+
+The "Run Grok Build in a project directory?" picker appears only outside a project, such as home, Desktop, Downloads, or `/tmp`.
+The spawn starts in the isolated git root, so Grok trusts it and needs no key.
+For unavoidable non-project launch, `[hints] project_picker_disabled = true` in `~/.grok/config.toml` suppresses the picker.
+
+## Composer
+
+Fresh placeholder `Type a message...` uses dark 24-bit TRUECOLOR, not SGR-2.
+`fm_composer_strip_ghost` in `../../../bin/brokk-composer-lib.sh` drops dim or faint and truecolor below `BROKK_COMPOSER_GHOST_LUMA_MAX`, default 128.
+On Grok 0.2.93, real input `38;2;224;222;244` measured about 225 luminance, while borders and placeholder ranged from `38;2;50;47;70` through `38;2;110;106;134`, about 51-110, and were dropped.
+The truecolor rule assumes the fleet's dark theme; SGR-2 is theme-independent.
+Coverage is `../../../tests/brokk-composer-ghost.test.sh` and `../../../tests/brokk-backend-herdr.test.sh`.
+
+Tmux `#{cursor_y}` may point at the pristine composer's bottom border.
+The shared classifier locates the full box and all content rows, so border cursor and multi-row composers require no adapter offsets.
+
+## Worker turn-end hook
+
+Grok fires `Stop` each turn.
+Project hooks require folder trust in `~/.grok/trusted_folders.toml`, which Brokk does not edit; global `~/.grok/hooks/` is always trusted.
+The spawn installs guarded global `brokk-turn-end.json` and `brokk-turn-end.sh`.
+They act only when workspace `.brokk-grok-turnend` matches the registry under `~/.grok/hooks/brokk-turn-end.d/`, then touch the task's `state/<id>.turn-ended` through always-set `GROK_WORKSPACE_ROOT`, which equals the worktree.
+This stays outside the worktree, needs no trust grant, and writes only Brokk files.
+`../../../bin/brokk-teardown.sh` removes the gitignored pointer before pooling.
+Eindri-homes skip it because idle is healthy and ordinary stale-pane detection does not apply.
+
+## Primary integration
+
+Verified on 2026-07-28 with 0.2.112 and genuine pre-native 0.2.73.
+`.grok/hooks/brokk-primary-turnend-guard.json` invokes `../../../bin/brokk-turnend-guard-grok.sh`.
+The exact running Stop payload selects same-process continuation on 0.2.112; 0.2.73 omits that capability and needs one guarded `grok --resume`.
+`../../../docs/turnend-guard.md` owns adaptive and malformed-input behavior.
+
+Grok also loads Claude project settings, so Claude entries for Grok-covered events stand down under `GROK_AGENT` or `GROK_HOOK_EVENT`; that owner records the exact set and why `GROK_SESSION_ID` is excluded.
+Project-local hooks require launch-time `--trust`; without it the guard steps aside and `../../../bin/brokk-guard.sh` is the next-command alarm.
+Watcher supervision remains tracked background notification around `../../../bin/syn-watch-arm.sh`, not Pi-style extension ownership.
+PreToolUse blocks directly, but every `$VAR` in a hook command needs inline `:-default` or Grok refuses the hook.

package/.agents/skills/hamr-adapters/references/harness/kimi.md

@@ -0,0 +1,51 @@
+# Kimi Code
+
+Verified on 2026-07-25 with Kimi Code CLI 0.29.1.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Binary | Absolute executable resolved from `PATH`, then executable `$HOME/.kimi-code/bin/kimi`; spawning refuses if neither exists. |
+| Launch | Bare interactive TUI with `--auto`, followed by readiness-gated pointer delivery; positional prompts are rejected. |
+| Models | Observed default `kimi-code/kimi-for-coding`, `kimi-code/kimi-for-coding-highspeed`, `kimi-code/k3`, and `kimi-code/k3-256k`; use `kimi provider list --json` for current configuration. |
+| Busy state | Standalone Kimi is unknown pending a live-verified semantic source, preferring Wire's `prompt` lifetime then documented hooks including `Interrupt`; Kimi behind Pi uses Pi lifecycle, and the moon-phase spinner is never a state source. |
+| Exit command | `/exit`. |
+| Interrupt | Single Escape, which prints `Interrupted by user`. |
+| Skill invocation | `/<skill>`, for example `/no-mistakes`; Brokk skills are discovered. |
+| Autonomy | `--auto`; `-y` and `--yolo` are weaker and are not used. |
+| Trust dialog | None observed on a clean first launch in a fresh pooled worktree. |
+| Slash submission | One Enter submits, with no popup swallow or settle hazard. |
+| Environment marker | None; detection uses process ancestry command name `kimi`. |
+| Composer | Bordered box with a bare `>` prompt glyph and no observed ghost or placeholder text. |
+| Effort | No verified reasoning-effort flag; `references/common/model-and-effort.md` owns unsupported-value handling. |
+
+## Readiness-gated start
+
+`../../../bin/einherjar-spawn.sh` launches Kimi bare, waits for the composer box or `Welcome to Kimi Code!`, sends only `Read the brief at <absolute-path> and follow it exactly.`, and requires a cleared composer plus either the echoed `✨` submission or nonzero context before accepting delivery.
+This launch-then-send shape is mandatory because Kimi rejects positional instructions as an unknown command.
+The path must be absolute because the instructions live outside the task worktree and Kimi reads them there without `--add-dir`.
+
+Sending before readiness was reproduced as a silent drop with zero exit status, an empty composer, `context: 0%`, no echoed user message, and a healthy-looking idle pane.
+The startup input-readiness window is the established cause; the banner is not.
+An early Enter can expand the composer to multiple content rows, leaving pointer text on the first row and the cursor on an empty later row.
+The shared tmux reader therefore locates the complete bordered composer and treats real text on any content row as positive evidence that submission remains pending.
+No rendering signal proves Kimi will accept input during this window, so delivery retries Enter through the shared submit core and retains the postcondition verification rather than relaxing readiness.
+
+Observed spinner captures had optional leading whitespace, a moon-phase glyph, whitespace around `·`, and rotating tip text, including during tool execution.
+The delivery-only matcher requires the observed whitespace, deliberately excludes the unobserved zero-whitespace form, and does not require trailing tip text.
+Kimi's footer tip can show `ctrl+c: cancel` while idle, and its idle bar can contain lowercase `thinking` as an effort label.
+Neither is a busy-state source.
+The delivery-only spinner match covers the full moon-phase glyph set but remains locale- and emoji-font-sensitive because Kimi exposes no stable ASCII busy token.
+
+## Crew turn-end hook and primary limit
+
+Kimi is outside the primary turn-end guard scope.
+`../../../docs/turnend-guard.md` owns its separate global hook surface and Allfather-approved crew wake integration.
+
+`../../../bin/einherjar-spawn.sh` installs one marker-delimited Brokk entry in `$HOME/.kimi-code/config.toml`, one silent always-zero hook script, and one private token registry under `$HOME/.kimi-code/brokk-turn-end.d/`.
+Each Kimi worker worktree receives a gitignored `.brokk-kimi-turnend` pointer.
+The global hook touches `state/<id>.turn-ended` only when the Stop payload's `cwd`, pointer, and registry entry all agree.
+A guarded silent hook cannot be verified from absence of effect, so prove invocation with an unguarded probe before concluding it did not fire.
+The guarded turn-end signal remains a wake notification.
+Standalone Kimi has no busy-state source until one is live-verified.

package/.agents/skills/hamr-adapters/references/harness/muse.md

@@ -0,0 +1,70 @@
+# Muse Code
+
+Verified 2026-08-05 on Muse Code 0.1.0-R708.1, build sha 427a430436.
+The router owns Muse's task-kind boundary.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Binary | Absolute `muse` from `PATH`, refused if absent; launcher `~/.local/bin/muse` execs versioned `muse-bin-<version>`, so live process name changes on update. |
+| Launch | Positional instructions, like Grok or Pi. |
+| Models | `--model <model>`; only provider `meta`. |
+| Busy | Durable session event log folded by `../../../bin/brokk-busy-lib.sh`; no hook or plugin writer, arming, or seeded busy record. |
+| Exit | `/exit`, one Enter; prints `To continue this session, run muse resume <session-uuid>`. |
+| Interrupt | Single Escape records `terminal: cancelled` and restores bright prompt text, so control follows with `Ctrl+U`; the legacy typed key path uses the same clear table. |
+| Skill | `/<skill>`, the Claude or Grok form. |
+| Resume | `muse resume --last` or `muse resume <session-uuid>`; bare `muse resume` opens a picker. |
+| Autonomy | `--yolo` disables approval and sandbox and trusts the workspace. |
+| Trust | Dialog `Do you trust this workspace?`, choice `1 Trust and continue` preselected for Enter; `--yolo` suppresses it, which fresh task paths require. |
+| Marker | None; detect anchored `muse-bin-*` ancestry after clearing foreign primary markers, while `MUSE_CURRENT_SESSION_LOG` is a path rather than identity and its export to tools is unverified. |
+| Composer | Bordered `⟩`, truecolor `38;2;90;160;255`, luminance about 149.9 and narrowly above ghost threshold 128; typed text is `38;2;204;211;219`, about 209.8, with no observed placeholder or ghost. |
+| Effort | `--reasoning-effort`, default `high`, accepts `none\|minimal\|low\|medium\|high\|xhigh\|ultra`; shared values expose low through xhigh, explicit Allfather `max` maps to `ultra`, and `none` or `minimal` remain unreachable. |
+
+## Credential preflight
+
+Muse reads winning `META_API_KEY` or `${XDG_CONFIG_HOME:-$HOME/.config}/muse/auth.json` written by OIDC device-code `muse login` or `muse auth set --api-key-stdin`.
+The spawn accepts the environment key only if the backend worker already has it: caller-only variables do not cross a long-lived daemon, and secrets never enter argv.
+Stored credentials are the supported fleet path.
+It resolves non-secret `XDG_CONFIG_HOME` and `XDG_DATA_HOME` absolutely before preflight and forwarding, keeping auth and logs aligned.
+
+With neither worker-reachable credential, spawn refuses.
+Unauthenticated Muse otherwise waits forever at `Sign in at this page: https://auth.meta.com/oauth/device/?code=XXXX-XXXX` and `Waiting for approval…`, which resembles a wedge.
+Escalate the refusal as a needed credential.
+
+## Foreign personal context
+
+Muse sends operator rules from `~/.claude` to Meta-hosted inference on every run.
+Its notice names Claude personal rules and `/settings` but appears only once through `tui.foreign_context_notice_shown`, so later silence proves nothing; isolated `XDG_CONFIG_HOME` does not prevent loading.
+
+Interactive Muse rejects exec-only `--no-foreign-personal-context`.
+The pane control is `MUSE_EXPERIMENTAL_FOREIGN_PERSONAL_CONTEXT_KILL=on`, set on every spawn and verified to remove foreign `rules_file` while retaining project `AGENTS.md`.
+
+## Session event log
+
+Logs live at `${XDG_DATA_HOME:-$HOME/.local/share}/muse/sessions/YYYY/MM/DD/<session-uuid>/session.jsonl`.
+The spawn writes `state/<id>.muse-session` with root, worktree, binding incarnation, and pre-existing matching main logs, then unique resolution pins `state/<id>.muse-session-current`.
+It folds that path while the bounded current-day main namespace is unchanged and resolves again if the namespace changes, path disappears, or a newer binding wins.
+
+Turns are bracketed by `{"payload":{"kind":"run","run_id":"<uuid>","event":{"kind":"started"` and matching `"event":{"kind":"terminal"`, observed as `completed` or `cancelled`.
+Interrupt therefore has a real terminal, unlike Claude Stop.
+Never use `--no-session-log`, which removes Muse's only busy source.
+
+The fold must reject nested `"record":{"kind":"terminal"}` cleanup effects and depth-bound away native sub-agent logs under `subagent/<child-session-id>/session.jsonl`.
+The recorded resolved `XDG_DATA_HOME` is also forwarded to the worker, preserving daemon alignment.
+An open run is trusted busy and settled log trusted idle; missing binding or match, unreadable log, or run-free log is unknown.
+`../../../docs/verification/muse.md` owns credentialed idle evidence and refresh.
+
+## Native sub-agents and worktrees
+
+Native children use per-child worktrees only with opt-in `--subagent-worktree-isolation`; capability says default-on while omission stays shared, and verified labs produced no nested copy.
+`../../../bin/brokk-teardown.sh` excludes no Muse path.
+It excludes `.claude/settings.local.json` because Brokk writes it, but Muse scratch is worker output and must refuse cleanup when uncommitted.
+Inspect, never force past, that refusal.
+
+## Maturity and primary limit
+
+Muse 0.1.0 is day-zero beta; its hourly channel poll can replace the binary and process name.
+The Allfather accepted this, so Brokk does not set `MUSE_NO_AUTO_UPDATE=1`; a fleet may set it without adapter change.
+Plugins report unavailable unless `MUSE_EXPERIMENTAL_PLUGINS=on`, so busy state uses logs.
+The compatibility dialect explicitly lacks `asyncRewake` and model reawakening; the router owns the resulting primary boundary.

package/.agents/skills/hamr-adapters/references/harness/opencode.md

@@ -0,0 +1,42 @@
+# OpenCode
+
+Verified on 2026-06-11 across versions 1.15.7 through 1.17.6, with busy-queue behavior re-verified on 2026-07-20 using 1.18.4.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Busy state | The Brokk-owned plugin's semantic `session.status`: `busy` and `retry` are active, `idle` is inactive, latched to the worker's own session. |
+| Exit command | `/exit`. |
+| Interrupt | Double Escape; it is known to be flaky while a long shell command runs, so use `../../../bin/brokk-control.sh <task-id> relaunch` for a wedged pane. |
+| Skill invocation | No separate verified form beyond normal slash-command behavior; use natural language when the exact command is uncertain. |
+| Resume | Relaunch with `--continue` to resume the most recent session for the current directory, then send the next instruction after the TUI is ready because `--prompt` does not auto-submit alongside `--continue`. |
+| Model flag | `--model <provider/model>`. |
+| Effort flag | None for Brokk's interactive `opencode --prompt` launch verified on 1.17.6; `opencode run` has `--variant`, but that is not this path. |
+| Model discovery | Run `opencode models [provider]` to list available provider/model identifiers. |
+| Trust dialog | None. |
+
+OpenCode can auto-upgrade in the background, and the running TUI can exit mid-task.
+That behavior was observed live during an upgrade from 1.15.7 to 1.17.3.
+If the pane shows the exit banner, use the verified resume path above.
+
+## Busy-queued Enter
+
+While OpenCode 1.18.4 is mid-turn, its composer accepts Enter as a "send when the turn ends" keystroke but does not clear the typed text until the turn finishes.
+Without a conversion, every typed-plane send to a busy OpenCode pane falsely reports "Enter swallowed", and a daemon escalation that lands while the primary is mid-turn appears wedged.
+
+Tmux and Herdr delegate this exception to the one `fm_composer_queued_enter_verdict` policy in `../../../bin/brokk-composer-lib.sh`.
+Backend-specific signals are documented in `../../../docs/tmux-backend.md` and `../../../docs/herdr-backend.md`.
+Regression coverage is `../../../tests/brokk-tmux-submit-busy.test.sh`, `../../../tests/brokk-composer-lib.test.sh`, and `../../../tests/brokk-backend-herdr.test.sh`.
+The live Herdr guard is `BROKK_HERDR_SUBMIT_CONFIRM_LIVE=1 ../../../tests/brokk-herdr-submit-confirm-live-e2e.test.sh`.
+
+## Primary integration
+
+The primary integration was verified on 2026-07-08 with OpenCode 1.17.6.
+`.opencode/plugins/brokk-primary-turnend-guard.js` listens for `session.idle`.
+Throwing from `session.idle` does not block `opencode run`, so the primary adapter treats the event as passive and uses `client.session.promptAsync` to force one follow-up turn when `../../../bin/syn-turnend-guard.sh` returns 2.
+The follow-up was verified in the interactive TUI.
+`opencode run` can exit before displaying a queued follow-up, so the adapter steps aside in headless mode.
+
+The companion `.opencode/plugins/brokk-primary-watch-arm.js` owns normal TUI watcher supervision, wakes it with `client.session.promptAsync`, and coordinates with the guard before a blind-turn follow-up.
+The PreToolUse-equivalent watcher-arm seatbelt blocks by throwing from `tool.execute.before`.

package/.agents/skills/hamr-adapters/references/harness/pi.md

@@ -0,0 +1,56 @@
+# Pi and Pi-signed
+
+The combined contract is genuine: Pi and the signed wrapper expose the same verified CLI and TUI behavior.
+Verified on 2026-07-27 with Pi and Pi-signed 0.82.0 unless a fact gives another version.
+
+## Operating facts
+
+| Fact | Value |
+|---|---|
+| Busy state | The Brokk-owned extension's `agent_start` marks busy and `agent_settled`, confirmed by `ctx.isIdle()`, marks idle; this covers retries, compaction, tool loops, and queued continuations. |
+| Exit command | `/quit`. |
+| Interrupt | Single Escape. |
+| Skill invocation | No separate verified form beyond normal command behavior; use natural language when the exact command is uncertain. |
+| Model flag | `--model <model>`. |
+| Effort flag | `--thinking <low\|medium\|high\|xhigh\|max>`; both identities expose the same levels and completed the same model-qualified max-thinking smoke. |
+| Model discovery | Run the selected executable as `<executable> --list-models [search]`; Pi's installed `docs/models.md` owns how built-in, extension-registered, and custom provider/model entries reach that list. |
+
+Pi has no permission system, so workers are always autonomous.
+Pi's installed `packages/coding-agent/docs/settings.md` UI and display section documents `regular` as the `tuiMode` default and `fullscreen` as experimental.
+Fullscreen can bury steering messages by rewriting scrollback, so Brokk avoids it when the installed CLI supports the override.
+`../../../bin/einherjar-spawn.sh --help` owns the executable-pinning and version-safe launch mechanics.
+
+Pi-signed is the signed wrapper identity verified on version 0.82.0.
+Brokk records `pi-signed` without normalization and refuses rather than falling back to `pi` when that wrapper is unavailable.
+The observed signed process tree has an exact `pi-signed` wrapper parent with the Pi application as its child, while tmux reports the foreground command as the exact `pi-launcher` name for either selected executable.
+The installed plain `pi` command also execs that signed launcher.
+The router's Detection section owns how launch markers and ancestry select between the identities.
+
+Keep the instructions as one positional argument.
+Multiple positional arguments become separate queued messages; the spawn template already preserves the one-argument shape.
+
+A project trust dialog can appear on the first Pi run in any not-yet-trusted directory, including a clean worktree.
+Accept it with Enter and verify the instructions begin processing.
+The decision persists per path in `~/.pi/agent/trust.json`, so later spawns in the same pooled slot skip it.
+
+## Worker turn-end extension
+
+`../../../bin/einherjar-spawn.sh` keeps the worker turn-end extension in `state/`, outside the worktree, because project-local extension files worsen the trust gate and pollute the project.
+The extension listens for Pi's `turn_end` event, not `agent_end`, so supervision is notified after each completed turn rather than only when the whole run exits.
+Pi sets `PI_CODING_AGENT=true` for its children as its harness-detection marker.
+
+## Primary integration
+
+The primary turn-end behavior was verified on 2026-07-09 with Pi 0.80.5.
+`.pi/extensions/brokk-primary-turnend-guard.ts` listens for logical-run `agent_settled`, not per-tool-loop `turn_end`, and uses `pi.sendUserMessage(..., { deliverAs: "followUp" })` to force one guarded follow-up when `../../../bin/syn-turnend-guard.sh` returns 2.
+Without `deliverAs: "followUp"`, Pi rejects the send while the agent is still processing.
+
+The primary watcher protocol also requires `.pi/extensions/brokk-primary-pi-watch.ts`.
+The Pi engine auto-discovers both tracked project-local extensions once the project is trusted.
+The model arms through the `fm_watch_arm_pi` tool, never through a foreground shell arm.
+The tool result and clean-exit fallback are owned by `../../../docs/supervision-protocols/pi.md`.
+`../../../bin/saga-session-start.sh` reports when the live Pi-family session has not loaded both extensions and points at the selected executable after project trust as the fix, with `-e` as a trust-free fallback.
+
+When a Eindri-home is launched on Pi or Pi-signed, `../../../bin/einherjar-spawn.sh --Eindri-home` launches the selected executable with both `-e .pi/extensions/brokk-primary-turnend-guard.ts` and `-e .pi/extensions/brokk-primary-pi-watch.ts`.
+Both files already exist in the Eindri-home home's git worktree.
+The PreToolUse-equivalent watcher-arm seatbelt returns `{block: true}` from the `tool_call` event.

package/.agents/skills/herdr-panes/README.md

@@ -0,0 +1,3 @@
+# herdr-panes — terminal panes — seat/control panes, tabs, workspaces, agents (HERDR_ENV=1)
+
+See `SKILL.md` for the full skill.

package/.agents/skills/herdr-panes/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: herdr
+description: >-
+  Herdr — the terminal multiplexer that hosts Ymir's agent panes. Load when
+  inspecting or controlling panes, tabs, workspaces, or a running agent; when
+  seating an Eindri visibly beside the work (pane/tree/tab/space); or when
+  starting a coding agent in a pane. Requires HERDR_ENV=1 (you must be inside a
+  herdr pane). Read this before using the herdr CLI.
+allowed-tools: read,write,bash,glob,grep
+---
+
+# herdr-panes — terminal panes — seat/control panes, tabs, workspaces, agents (HERDR_ENV=1)
+
+Herdr is a mouse-first, agent-aware terminal multiplexer: a background server
+owns the terminals, clients attach, and it recognises coding agents in panes.
+`herdr` is the upstream name (aka `hdr`); it is the backend behind Þjazi.
+
+## First law
+
+Control only works from **inside** a herdr pane:
+
+```bash
+test "${HERDR_ENV:-}" = 1      # else: say you are outside and stop
+```
+
+Inside, `herdr` talks to the current session. The binary is the authority —
+`herdr --skill` prints this contract, `herdr agent|pane|tab|workspace` prints
+each command group. Don't run bare `herdr` (it launches the TUI).
+
+## The hierarchy
+
+`Session > Workspace (w1) > Tab (w1:t1) > Pane (w1:p1)`. A **pane** is a real
+terminal; an **agent** is a process herdr recognises inside one. `agent start`
+needs an existing shell pane — it never creates layout.
+
+## Seat an agent where you can see it
+
+```
+seat-roads[4]{mode,how,use}:
+  "pane","herdr pane split --current --direction right","one agent beside the work"
+  "tree","recursive splits (parent + children)","a coordinator with its workers, visible as a tree"
+  "tab","herdr tab create --label ...","a workstream off to the side"
+  "space","herdr workspace create","a disposable space for one errand"
+```
+
+Then:
+
+```bash
+herdr pane split --current --direction right --cwd "$PWD"   # -> .result.pane.pane_id
+herdr agent start <name> --kind pi --pane <pane> -- --model <provider>/<id>
+herdr agent prompt <name> "<task>"
+herdr agent list            # states: working · blocked · done · idle · unknown
+```
+
+## In Ymir
+
+- `bin/pi-seat.sh [--tab] [--task …]` — seat a pi agent (local model) visibly.
+- `bin/eindri-start.sh "<task>" [--pane|--tab|--space]` — role → seat → task.
+- `bin/pi-local.sh` — run a local model headless (print mode).
+- One **local model at a time per machine** — see `bin/local-model-lock.sh` and
+  `local_concurrency` in `config/agents.yaml`. Different machines, different
+  models; local inference is serialized on a box.
+
+## Tools this skill drives (in `bin/`)
+
+```
+tools[4]{tool,does}:
+  "bin/eindri-start.sh \"<task>\" [--pane|--tab|--space]","one command to seat an Eindri visibly"
+  "bin/pi-seat.sh [-n name] [-m model] [--task]","seat a pi agent (local model) in a pane"
+  "bin/eindri-send.sh <agent> \"<text>\" · bin/eindri-control.sh ...","talk to / control a seated agent (data · control plane)"
+  "bin/herdr-run.sh","the seat engine that calls herdr agent start/prompt"
+```
+
+## Assets
+
+```
+assets[2]{path,holds}:
+  "assets/herdr-backend.md","the Herdr runtime backend: setup, protocol floor, presentation spaces, capabilities"
+  "assets/tmux-backend.md","the tmux runtime backend: setup, capabilities"
+```
+
+## HARD CONTRACT — seat, inject, verify
+
+```
+hard[3]{step,command,proof}:
+  "seat","bin/eindri-start.sh \"<task>\" | bin/herdr-run.sh eindri","agent in a pane"
+  "inject","bin/eindri-send.sh <agent> \"<task>\"","the task is in the agent's chat"
+  "verify","herdr agent list -> agent_status working","it is doing the work"
+```
+Seating without injecting leaves an idle agent — not a dispatch. If the agent is
+`idle` right after seating, re-send; if it is gone, re-seat. Only report success
+once the agent is `working`.