@zerwiz/ymir 0.1.4 → 0.1.7

package/.agents/skills/hamr-adapters/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: hamr
+description: >-
+  Agent-only reference for Brokk harness operations.
+  Use before spawning or recovering a Eindri or Eindri-home, handling a trust dialog, sending a harness-specific skill invocation, interrupting or exiting an agent, resuming an exited agent, or verifying a new harness adapter.
+  Contains verified facts for claude, codex, opencode, pi, pi-signed, grok, kimi, cursor, and muse.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# hamr-adapters — harness adapters — per-harness reference
+
+This is the one skill, trigger, and routing owner for harness-specific Brokk operations.
+Load this router first, then exactly the common reference and one harness reference selected below.
+When an action spans rows, load the union once rather than every reference.
+Files under `references/` are resources of this skill, not additional catalogued skills.
+
+## Path contract
+
+The skill directory is the directory containing this `SKILL.md`.
+Resolve on-demand reference links and relative links to their executable, documentation, or sibling-skill owners against the skill directory, including links named by a nested reference.
+Operational paths keep the context named by their owner: `config/` and active-home settings belong to the active Brokk home, `state/` belongs to that home, and project settings such as `.claude/settings.json` belong to the target project.
+
+## Non-negotiable safety
+
+Never dispatch a Eindri or Eindri-home on an unverified adapter.
+If `config/crew-harness` or `config/Eindri-home-harness` names one, tell the Allfather under `../../../AGENTS.md` section 9 that the requested worker runtime is not verified, use Brokk's own verified runtime for current work, and ask only whether to verify the requested runtime for future work.
+Do not pause current work for that choice.
+
+On `unknown`, ask the Allfather instead of guessing.
+A current Allfather override beats detection, while a per-task override governs only that dispatch.
+For recovery and control, use the exact `harness=` in `state/<id>.meta`; never infer it from a model or provider.
+
+Deliver lifecycle actions only through `../../../bin/brokk-control.sh <task-id> interrupt|exit|relaunch`.
+Never type an interrupt key or exit command through `brokk-send`, where routing-marked lifecycle text becomes chat.
+Trust handling is complete only when inspection proves the target started processing its instructions; delivery success alone is not proof.
+Muse is verified only for Eindri and scout work, never a Eindri-home or primary.
+
+## Detection
+
+`../../../bin/hamr-harness.sh` prints Brokk's own harness from verified environment markers, then process ancestry.
+Only `BROKK_PI_HARNESS=pi-signed` at the launch boundary together with `PI_CODING_AGENT=true` selects Pi-signed; shared unmarked launcher ancestry remains Pi.
+`../../../bin/einherjar-spawn.sh` owns worker marker establishment, while the README launch command owns the signed-primary boundary.
+`../../../bin/hamr-harness.sh crew` resolves `config/crew-harness`, where absent or `default` means Brokk's own harness.
+`../../../bin/hamr-harness.sh Eindri-home` resolves `config/Eindri-home-harness` -> `config/crew-harness` -> Brokk's own harness.
+`../../../bin/einherjar-spawn.sh` re-resolves on every spawn, and an explicit per-spawn argument wins for that spawn.
+A new adapter's verified marker and command name must land in `../../../bin/hamr-harness.sh`.
+
+## Operation-to-reference matrix
+
+Every emitted plan appends the selected or recorded harness reference after the named common references.
+The `harness-adapter-routing-v1` object is the machine-readable and human-visible selection contract: choose the operation, choose the scenario within it, then append the selected harness reference.
+`default` is the normal scenario when no narrower scenario applies.
+Kimi establishes its unsupported primary boundary in its selected harness reference; Muse follows Non-negotiable safety above.
+A new tool remains undispatchable until the `verify` plan, its harness entry, every named owner, and the live checks land.
+
+```json harness-adapter-routing-v1
+{
+  "operations": {
+    "start": {
+      "default": ["references/common/dispatch.md", "references/common/model-and-effort.md"],
+      "trust-dialog": ["references/common/control-and-recovery.md"]
+    },
+    "trust": {"default": ["references/common/control-and-recovery.md"]},
+    "skill": {"default": ["references/common/control-and-recovery.md"]},
+    "interrupt": {"default": ["references/common/control-and-recovery.md"]},
+    "exit": {"default": ["references/common/control-and-recovery.md"]},
+    "resume": {"default": ["references/common/control-and-recovery.md"]},
+    "recovery": {
+      "default": ["references/common/control-and-recovery.md"],
+      "replacement-profile": ["references/common/control-and-recovery.md", "references/common/dispatch.md", "references/common/model-and-effort.md"],
+      "Eindri-home": ["references/common/control-and-recovery.md", "references/common/primary-hooks.md"],
+      "replacement-Eindri-home": ["references/common/control-and-recovery.md", "references/common/dispatch.md", "references/common/model-and-effort.md", "references/common/primary-hooks.md"]
+    },
+    "primary": {"default": ["references/common/primary-hooks.md"]},
+    "model-effort": {
+      "default": ["references/common/model-and-effort.md"],
+      "configured-profile": ["references/common/model-and-effort.md", "references/common/dispatch.md"]
+    },
+    "verify": {"default": ["references/common/dispatch.md", "references/common/control-and-recovery.md", "references/common/primary-hooks.md", "references/common/model-and-effort.md"]}
+  },
+  "harnesses": {
+    "claude": "references/harness/claude.md",
+    "codex": "references/harness/codex.md",
+    "opencode": "references/harness/opencode.md",
+    "pi": "references/harness/pi.md",
+    "pi-signed": "references/harness/pi.md",
+    "grok": "references/harness/grok.md",
+    "kimi": "references/harness/kimi.md",
+    "cursor": "references/harness/cursor.md",
+    "muse": "references/harness/muse.md"
+  }
+}
+```
+
+## Organisation law (RULES/) — domains, houses, agents
+
+Hamr binds the harnesses; the house law governs *who* they run. The source of
+truth is `RULES/`:
+
+- **A house is a company** — and only that. **WayOf** is the house.
+- **A domain is a field of knowledge — a *Grein* (pl. *Greinar*).** The eight:
+  `ymirlabs` (the system itself) · `brokkforge` (engineering) · `runestone`
+  (records/compliance) · `muninn` (memory) · `dvalin` (crafted tools) ·
+  `utgard` (creative) · `askr` (human products) · `mannheim` (holding).
+- **Eindri are the specialists** (marketer, builder, researcher, planner,
+  reviewer, documenter, scout, …); each names its **domain** and its **craft**.
+
+**Agent binding (Rule 02) — Hamr's own concern:**
+
+- Canonical profiles live **only** in `.agents/agents/*.md`.
+- Every harness directory is a **symlink** to them — never a copy:
+  - OpenCode: `.opencode/agents/<name>.md` → `../../.agents/agents/<profile>.md`
+  - Pi: `.pi/agents/<profile>.md` → the same canonical files
+- Never edit `.opencode/agents/` or `.pi/agents/`; edit `.agents/agents/<profile>.md`
+  and run `bin/valknut-load.sh --all` to rebind. `bin/hamr-harness.sh` only
+  *detects* the harness shape; it never writes agents.
+- **No mock agents:** ids, names, domains, models, and status are real and
+  sourced. The demo roster is the single, labelled mock (demo mode only).
+
+In the code the eight are `DOMAINS` (`DomainId`/`DomainDef`) and an agent carries
+`domain` (not `house`) — see `src/data/realms.ts` and `AgentCard`.

package/.agents/skills/hamr-adapters/references/common/control-and-recovery.md

@@ -0,0 +1,37 @@
+# Control and recovery
+
+Load this with the running or recorded tool reference for trust, skill invocation, interrupt, exit, resume, or recovery.
+
+## Typed data and lifecycle control
+
+The router owns lifecycle-only control and recorded-harness selection.
+Conversation and harness-native skill invocation use `../../../bin/brokk-send.sh`.
+`../../../docs/agent-control.md` owns the data-plane split, and `../../../bin/brokk-control-lib.sh` owns executable capabilities.
+Tool-reference exit and interrupt values are empirical records, not keys to improvise; a new adapter remains uncontrollable until they land in that owner.
+Let the control plane verify postconditions.
+
+## Trust and skill submission
+
+Inspect after spawn within the tool's readiness window.
+Select only its documented trust choice from the active Brokk home, binding `BROKK_HOME` unless already correct, then inspect again under the router-owned completion postcondition.
+No observed dialog proves only that launch.
+
+Use the tool's exact skill form, or natural language only when no separate command is verified or the form remains uncertain.
+A successful send or key return is not proof of submission; require the tool-specific postcondition.
+Popup, queued-input, and readiness handling belongs to `../../../bin/brokk-composer-lib.sh` and the selected backend.
+
+## Interrupt and exit
+
+Use the control plane so capabilities are checked first.
+Interrupt preserves the agent and work; exit stops only the agent and preserves its endpoint, isolated copy, and uncommitted changes.
+Cleanup and discard are not lifecycle verbs.
+The tool reference records repeat, acknowledgement, and clearing behavior, while the executable owner sends or refuses the sequence.
+
+## Resume and recovery
+
+Native resume availability and form belong solely to the selected tool reference.
+Use native resume only when both that reference and the recovery procedure call for it.
+Deterministic relaunch instead trusts instructions on disk, not a private session.
+
+`../stuck-Eindri-recovery/SKILL.md` owns worker recovery and `../Eindri-home-provisioning/SKILL.md` owns Eindri-home recovery; both preserve recorded work.
+The router's recovery scenarios select the additional common references for replacement profiles and eindri-homes.

package/.agents/skills/hamr-adapters/references/common/dispatch.md

@@ -0,0 +1,32 @@
+# Dispatch and start
+
+Load this with the selected tool reference for dispatch, start, or adapter verification; add `references/common/model-and-effort.md` for either profile axis.
+
+## Resolution
+
+Use the router's detection and safety sections for static crew and Eindri-home harness resolution and all explicit overrides.
+`config/crew-dispatch.json` can override that static default for one Eindri or scout with concrete harness, model, and effort axes.
+For a profile array, load `quota-array-dispatch` after establishing harness and provider facts here.
+
+`../Eindri-home-provisioning/SKILL.md` owns inherited local material.
+Its harness consequence is that a Eindri-home's workers receive literal `config/crew-harness` and `config/crew-dispatch.json`, while the primary-only `config/Eindri-home-harness` is never inherited because eindri-homes do not spawn eindri-homes.
+A concrete crew value such as `codex` carries that runtime into the Eindri-home home.
+Unset or `default` carries no concrete value, so its workers use that home's own or detected harness rather than the primary's effective crew harness.
+The inherited dispatch file applies the same best-fit profiles there.
+
+## Owners
+
+`../../../bin/einherjar-spawn.sh` owns launch, autonomy, concrete flags, task-kind compatibility, and worker turn-end wiring.
+Natural-language rules stay with Brokk, while scripts receive concrete axes.
+
+`../../../bin/brokk-busy-lib.sh` owns semantic busy trust.
+Composer shapes, glyphs, placeholders, popups, rendered delivery signals, and the `empty` / `pending` / `pending-unproven` / `unknown` decision belong only to `../../../bin/brokk-composer-lib.sh`.
+Tool references record empirical knowledge for those executable owners.
+
+## Adapter verification
+
+For an approved new adapter check, use the spawn owner's raw-launch escape hatch only for a trivial supervised task.
+Verify detection in `../../../bin/hamr-harness.sh`, launch in `../../../bin/einherjar-spawn.sh`, busy state in `../../../bin/brokk-busy-lib.sh`, shared composer behavior in `../../../bin/brokk-composer-lib.sh`, lifecycle in `../../../bin/brokk-control-lib.sh`, and tmux liveness in `../../../bin/backends/tmux.sh` when Eindri-home use is supported.
+Also verify primary integration through `references/common/primary-hooks.md`, model discovery through `references/common/model-and-effort.md`, and one tool record.
+A value remains unreachable until its executable owner, portable regression, applicable credentialed live guard, and verification record land together.
+`../Brokk-coding-guidelines/SKILL.md` owns harness-dependent proof.

package/.agents/skills/hamr-adapters/references/common/model-and-effort.md

@@ -0,0 +1,42 @@
+# Model and effort
+
+Load this with the selected tool reference before choosing, validating, or changing either axis.
+Add `references/common/dispatch.md` for configured profile precedence.
+
+## Axes and precedence
+
+`../../../bin/einherjar-spawn.sh` accepts concrete `--harness`, `--model`, and `--effort` values selected at intake; scripts never parse natural-language dispatch rules.
+The tool reference records verified flags, accepted values, omission behavior, and discovery.
+
+Effort precedence is a per-task Allfather instruction, then applicable dispatch profile or Eindri-home pin, then the fallback below.
+Never replace either higher-precedence value.
+Use the fallback only when neither specifies effort.
+
+Use `low` for well-understood work with an explicit bounded path and `xhigh` for ambiguous investigation or design.
+Choose intermediate levels as complexity, uncertainty, blast radius, or open-ended reasoning rises.
+If an adapter lacks `xhigh`, cap at its highest supported non-`max` level rather than silently omitting the intent.
+Never select `max` through this fallback; only an explicit per-task or standing Allfather preference permits it.
+
+If requested effort is outside the adapter's accepted set, the spawn records `effort=` in task metadata but emits no effort flag.
+This preserves launch success instead of passing a known-bad value.
+A harness with no verified interactive effort flag follows the same record-and-omit contract.
+
+## Harness and provider identity
+
+Harness identity is independent of model provider.
+`harness=pi` with `model=xai/grok-*` is Pi using xAI, not standalone Grok Build, and does not require Grok CLI login.
+`harness=cursor` with `model=cursor-grok-4.5-*` is Cursor routing a Grok model, not `harness=grok`.
+
+No script resolves credential provenance for you.
+Establish it from the tool's discovery surface and `quota-axi auth --json` per-provider sources, and show the reasoning rather than inferring it from a name.
+
+## Discovery
+
+Treat model and provider knowledge as current discovery, not a permanent namespace or mapping.
+Use the selected tool reference's authoritative surface in the current authenticated environment because availability changes by version, account, and configuration.
+
+For an unfamiliar namespace, establish support and provider identity from that harness's CLI help, model listing, or current documentation.
+An account-reaching listing that omits a model is concrete unsupported evidence; block the candidate and quote it.
+An unreachable surface establishes nothing; report uncertainty instead of a verdict.
+
+For a matched profile array, return to `quota-array-dispatch` only after establishing every candidate's harness support, provider relationship, and uncertainty.

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.