@zerwiz/ymir 0.1.4 → 0.1.7

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`.

package/.agents/skills/herdr-panes/assets/herdr-backend.md

@@ -0,0 +1,346 @@
+# Herdr runtime backend
+
+Herdr is an experimental agent-native terminal backend with native per-pane agent state and push events.
+Brokk requires Herdr protocol 14 or newer; broad backend verification covers versions 0.7.1, 0.7.3, 0.7.4, 0.7.5, and 0.8.0, while protocol-16 features remain gated by availability.
+Default-on presentation spaces have a higher floor of Herdr 0.8.0 for the reason given under [Presentation spaces](#presentation-spaces).
+Herdr provides the terminal session while Treehouse continues to provide task worktrees.
+[`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns shared backend selection and metadata semantics.
+
+## Setup
+
+Pick Herdr when you want native busy, idle, and blocked state and accept the experimental limits below.
+
+Prerequisites:
+
+- Herdr protocol 14 or newer, installed from [herdr.dev](https://herdr.dev).
+- `jq` for JSON responses.
+- The universal harness and toolchain requirements in [`configuration.md`](configuration.md#toolchain).
+- `python3` only for optional protocol-16 presentation-space ordering and native event subscription.
+
+Herdr is dual-licensed AGPL-3.0-or-later or commercial.
+Brokk invokes its CLI as a separate process.
+
+Select Herdr with local `config/backend` containing `herdr`, `FM_BACKEND=herdr` for one launch, or an explicit request to Brokk.
+A remote Eindri agent is the one case with no choice: it always runs on Herdr, and [`remote-secondmates.md`](remote-secondmates.md) owns that requirement and the readiness its host must meet.
+It is also auto-detected when the primary runs natively under `HERDR_ENV=1` and is not inside tmux.
+A tmux pane nested inside Herdr resolves to tmux because the innermost multiplexer wins.
+An auto-detected Herdr spawn prints an opt-out notice.
+
+Spawn stops before creating a Herdr container or acquiring a task worktree when `herdr`, `jq`, or the protocol floor is unavailable.
+No separate first-run provisioning is required.
+
+The required CI lane uses the pinned installers in `bin/fm-install-herdr.sh` and `bin/fm-install-treehouse.sh`.
+Those script headers own release assets, checksums, download bounds, and post-install gates.
+Real harness credential tests remain opt-in rather than part of default CI.
+
+## Watching and task containers
+
+The ordinary topology puts one task tab per endpoint in the exact workspace of the Brokk or Eindri-home that launches it.
+When the launcher has no Herdr workspace to inherit, the adapter maintains one durable home-labeled workspace instead.
+The primary home label is `firstmate`.
+An Eindri-home label is `2ndmate-<secondmate-id>`, derived from its validated `.fm-secondmate-home` marker.
+An Eindri-home launched by the primary receives a narrowly scoped home override during container creation.
+
+Attach to the selected named Herdr session and switch to the relevant home workspace to watch its task tabs.
+Routine supervision uses `bin/fm-peek.sh <id>` and `FM_HOME=<home> bin/fm-send.sh <id> '<text>'` without attaching.
+
+Workspace and tab creation use `--no-focus`.
+The first workspace in a completely empty Herdr session must become focused because no prior target exists, but later task creation does not intentionally steal focus.
+
+Herdr does not enforce workspace or tab label uniqueness, so a label can never decide where a worker goes.
+Herdr 0.7.5 exports `HERDR_ENV`, `HERDR_PANE_ID`, `HERDR_SESSION`, `HERDR_SOCKET_PATH`, `HERDR_TAB_ID`, and `HERDR_WORKSPACE_ID` into every process it manages a pane for, and a Brokk or Eindri agent's own commands inherit them.
+Older injection shapes are unverified, so a claimed launcher pane without the injected socket identity cannot be trusted.
+With presentation spaces disabled, an Eindri or scout is created in the exact workspace that identity currently resolves to, read live from Herdr rather than from the injected snapshot, so the worker always appears beside the agent that launched it.
+Duplicate labels elsewhere in the session are irrelevant, and the globally focused workspace is never the target.
+A `--secondmate` launch is the deliberate exception: it stands up that Eindri-home's own workspace instead of joining the launcher's.
+
+A claimed parent identity that cannot be resolved exactly stops the spawn before any worker endpoint exists, rather than falling back to a label search.
+That covers a missing or unusable socket identity, a closed or unreadable launcher pane, a pane and tab that disagree about their workspace, a workspace missing from the session, and a pane belonging to another named session or Herdr server.
+
+Brokk running outside Herdr entirely has no launcher workspace to inherit, so its workers use this home's own labeled workspace, created on first use.
+That path needs the home label to identify exactly one workspace: two workspaces sharing it are an unresolvable placement and refuse rather than adopting either.
+Avoid naming a personal workspace `firstmate` or `2ndmate-<id>` for that reason, and because the adapter cannot distinguish that label collision from its own container.
+An older Eindri-home workspace using `firstmate-<id>` is not migrated automatically; rename it manually before expecting new tasks or recovery to use it.
+Recovery and list-live still scan the first workspace matching the home label, because they address panes they already recorded rather than choosing where new work goes.
+
+Existing task operations use recorded endpoint ids and do not move a live task when labels change.
+The per-home workspace is reused while it has task tabs.
+Closing its last tab can remove the workspace, and the next spawn recreates it.
+
+## Presentation spaces
+
+Each new Eindri or scout is placed in a disposable one-task workspace by default, on Herdr 0.8.0 and newer.
+A home opts out by writing `off` into local gitignored `config/herdr-presentation-spaces`, and forces the projection on by writing `on`.
+An absent file leaves the choice to the version floor below, an empty file and the value `on` are both a deliberate opt-in, values are compared with whitespace stripped and case ignored, and an unrecognized value warns and follows the unconfigured default rather than failing a spawn over a purely visual setting.
+The empty file is the historical presence-based opt-in form, so every home that had already enabled the projection stays enabled with no migration step, and no previously enabled home can be turned off by the default or by the floor.
+A home that never created the file gains the projection at its next Herdr spawn on a supported release; that flip is deliberate, and it reaches only the Herdr backend because no other runtime backend has a projection path.
+
+Projecting each task into its own workspace makes every task cleanup a workspace-emptying removal, which is the only removal shape Herdr's pre-0.8.0 focus defect touches, and the focus-safe removal plan below can only avoid it while the closing pane's shell can be proved lone, childless, and idle.
+A persistent child of that shell - a `gitstatusd`, a `zsh-async` worker, or `direnv` - fails that proof permanently and forces the plain explicit close, which on those releases moves the active workspace for roughly a seventh of a second before the restore backstop pulls it back, once per task cleanup.
+An unconfigured home is therefore projected only on a release at or above the 0.8.0 floor, where every workspace-removal primitive preserves focus and that proof stops being load-bearing.
+Below the floor an unconfigured home uses the ordinary flat per-home layout instead and warns once per home per detected release, naming the running release and the upgrade that restores the projection.
+That one-warning-per-release record is a `state/.herdr-presentation-floor-<release>` marker; deleting it only makes the same warning appear again, and an upgrade or downgrade re-announces itself because the release is part of the key.
+The floor reads both the installed client's protocol and version and the selected named session's server signals while that server is running, requires both applicable releases to pass, and uses only the client when status positively reports no running server because that client will start it.
+The unconfigured default is rechecked after the server is started or adopted and before any presentation journal or workspace is created, while an unreadable server state or release is treated as unsupported rather than guessed at.
+An explicit `on` is honored below the floor, so a home that deliberately opted in is never silently downgraded; it accepts that documented focus move, and the exact prior-tab restore stays its backstop.
+The floor has a single owner, the spawn-time gate, so cleanup for a projection that already exists always runs and never strands a workspace, whatever release the home is on now.
+Upgrading Herdr to 0.8.0 or newer is the fix; writing `off` is the immediate mitigation for a home that cannot upgrade yet.
+The setting is inherited into Eindri-homes through the normal configuration-convergence owner, and the default needs no special convergence: the primary's absent file and an Eindri-home's absent file both mean the same unconfigured default, so leaving it converges an Eindri-home to that same default rather than turning it off, and only an explicit primary `off` propagates the opt-out.
+The Eindri-home's own agent always stays in its ordinary parent workspace; only children launched by that home are eligible.
+An unconverged opt-out keeps the default projection in that home until convergence.
+
+Presentation is a best-effort visual projection, never task ownership or lifecycle authority.
+Only a fresh task with neither metadata nor an existing presentation journal is eligible for projected creation.
+Brokk atomically publishes a three-field version 1 journal containing a random 128-bit base64url token before asking Herdr to create anything.
+After the new workspace converges to one exact task endpoint beneath one exact parent workspace id, the journal advances to a version 2 binding that records the physical home, named session, endpoint, parent, and immutable expected labels.
+Another parent with the same presentation label does not prevent publication or participate in restart reclaim.
+The token is visible in the workspace title because Herdr exposes no verified hidden persistent field, but neither token, title, nor journal authorizes send, capture, task ownership, Treehouse return, or general recovery.
+
+The owning parent is the launcher's own exact workspace, resolved from the same identity the flat path uses, and falls back to a unique home-label lookup only for a Brokk outside Herdr.
+Projected children are never collapsed back into that parent; it is the placement and ordering reference the projection is bound under.
+The normal `fm-<id>` task tab is created in the exact new workspace returned by Herdr.
+Only the exact seeded default tab returned by the same workspace-create response can be pruned.
+Before and after create, prune, order, abort cleanup, and normal cleanup, Brokk verifies exact workspace, tab, pane, and active-focus ids.
+An ambiguous response grants no mutation or cleanup authority.
+
+Protocol 16 exposes `workspace.move` over the named session socket but no CLI subcommand.
+`bin/backends/herdr-workspace-move.py` sends only that whitelisted method and verifies the complete returned workspace order.
+Projected children are placed in one contiguous block immediately after their owning home when the session layout, protocol, socket, `python3`, and machine-private per-session lock are all verifiable.
+Existing legacy child labels may extend an already adjacent block read-only but are never renamed or migrated.
+A foreign, ambiguous, detached, or manually interleaved child makes ordering skip with a warning rather than rewriting the layout.
+
+Ordering failure never fails the task spawn.
+Brokk does not retry, adopt, reuse, close, delete, or rename anything in response to an unavailable method, lock contention, ambiguous socket, lost response, failed move, or verification mismatch.
+The worker remains on the ordinary flat or Herdr-current-order path.
+
+Normal task metadata remains the sole endpoint authority after creation.
+Cleanup closes only the exact recorded task pane and never calls `workspace close`.
+Herdr 0.7.5's explicit close moves focus to a neighbor whenever it empties a non-focused workspace, while its pane-death removal preserves the focused workspace whenever the dying workspace sits behind it or the focused workspace is last; both behaviors are fixed in Herdr 0.8.0, and the exact rules live in the adapter header of `bin/backends/herdr.sh`.
+Projected cleanup therefore runs under the same session lock, captures the exact active tab, refuses to delete the active tab, and treats a workspace-emptying close as a focus-safe removal: it verifies the close would empty the workspace, repositions the doomed workspace behind the focused one through the verified `workspace.move` transport when needed, proves the pane holds one lone idle shell, and ends that shell so Herdr removes the emptied workspace through its focus-preserving pane-death path.
+The repositioning move-to-last preserves every surviving workspace's relative order, and removal is confirmed against the exact moved workspace rather than inferred from pane disappearance before an unconfirmed removal makes one verified attempt under the same session lock to roll the doomed workspace back to its exact original position.
+If that rollback cannot restore the verified original order, cleanup warns loudly and leaves the retained records for inspection rather than retrying the shared-layout mutation.
+The pane-death signals are pid-exact: the escalation re-reads the pane's process information and refuses unless the same shell pid still passes the strict bare-idle ownership proof, so an exited and reused pid is never signaled.
+Any ambiguity, unsupported or failed move, or unproved shell falls back to the plain explicit close, and the exact prior-tab restore remains the backstop behind every close, so degraded behavior is never worse than the pre-mitigation sub-second restore.
+Ordinary non-projected task removal serializes through the same session lock, applies the same focus-safe plan when its close would empty a non-focused workspace, keeps the legitimate plain close when the target is the active tab, and refuses an unlocked close if the lock cannot be acquired.
+Task cleanup acquires that session lock before the task's isolated copy is returned, so a contended lock refuses up front while the copy, every durable record, and the endpoint are all intact for a plain rerun.
+Forced Eindri-home cleanup recursively preflights every Herdr child endpoint and acquires every affected named-session lock before mutating any child, then retains each child's durable identity unless that exact pane returns structured not-found after its close.
+Durable task records are erased only once the exact pane is confirmed gone through its structured presence: after every close path, only a structured not-found response counts as gone, while a present or unknown result retains every record with a visible, retryable error.
+Missing or malformed endpoint identity and missing confirmation machinery are ambiguity, never proof of a gone pane, and refuse record removal the same way.
+If lock, snapshot, pane identity, or restoration is ambiguous, cleanup warns and preserves the journal for manual inspection.
+
+Recovery is deliberately conservative and presentation-only.
+An existing journal suppresses another projected create.
+Before any recovery mutation, Brokk holds both the task spawn lock and the named-session presentation lock.
+A same-identity version 2 binding may replace one exact agent-free restart husk in place only when the physical home, session, metadata endpoint, unique token match, workspace shape and labels, parent identity and placement, and non-target focus snapshot all agree.
+The replacement tab and pane are created and verified before the old pane is rechecked and closed, then the journal advances atomically to the replacement endpoint before metadata publication.
+The reclaim path never moves, closes, deletes, or renames a workspace and never touches a parent, a sibling, an Allfather-owned pane, or a foreign pane.
+A failed replacement rolls back only the exact response-derived new pane when focus-safe verification permits it.
+Version 1 journals, dead or missing panes, duplicate or absent tokens, renamed or detached spaces, cross-home mismatches, inconsistent endpoint bindings, active target tabs, and ambiguous identity or focus fall back flat without mutating the old projection when duplicate-agent risk is positively absent.
+A live or unknown recorded or token-matched endpoint refuses duplicate launch.
+
+Locked session start has one narrower cleanup for a restored projected child that is no longer current task state.
+It runs only when the current home has at least one ordinary presentation journal and considers only that home; a primary never recursively sweeps an Eindri-home.
+Discovery starts from the exact current `└ <concise-task> · p:<22-character-token>` grammar, but a title or token alone is never mutation authority.
+The title must contain exactly one token occurrence across the named-session snapshot and must equal the title derived from exactly one valid presentation journal in this home's own `state/`; a version 2 journal additionally must bind this exact physical home, named session, workspace, tab, and pane.
+The task's ordinary metadata must be absent, and the candidate must have exactly one tab and exactly one pane.
+Before cleanup, Brokk acquires the existing task-id spawn lock and then the shared named-session presentation lock.
+Inside both locks it takes one exact snapshot, requires one unambiguous non-target focus and the exact title, token, tab, and pane shape, positively confirms no registered agent, and reads Herdr's process information for the exact named-session pane.
+The process proof requires one recognized idle shell as both the shell process and the sole foreground process-group member, an operating-system process-table row for that shell, no child process, and a sleeping or idle shell state.
+The proof retries strict single samples for a bounded settle window because an idle interactive shell transiently hosts short-lived prompt helpers; a genuinely busy pane fails every sample.
+Any foreground command, child process, active shell job, unknown shell, unreadable process table, missing field, or API error preserves the pane.
+Brokk immediately revalidates the same journal, metadata absence, workspace title and token uniqueness, one-tab and one-pane topology, exact pane relationship, absent agent, process proof, and non-target focus before calling the existing exact-pane focus-preserving close helper.
+It closes only that pane, never a workspace.
+The matching journal is retired only after the exact pane is positively confirmed gone; an unconfirmed close retains the journal, while a confirmed close may retire it even when focus restoration reported an error after the close.
+A second run finds no matching title or journal and is a no-op.
+A malformed or missing title or token, duplicate token, zero or multiple journal matches, cross-home version 2 binding, current metadata, registered or unknown agent, extra tab or pane, active target, busy lock, changed revalidation, unreadable check, or any error preserves the candidate and lets session startup continue with at most a concise warning.
+
+Operational compromises:
+
+- Grouping is best-effort; only an exact same-identity version 2 binding survives a Herdr restart in place.
+- A failed journal publication or projected workspace create stops that spawn instead of falling back flat, so a Herdr create failure surfaces as a spawn failure in every Herdr home rather than only in homes that opted in; every earlier degradation on the fresh projected-create path (no session server, contended presentation lock, absent or ambiguous parent) still warns and continues flat.
+- Recovery of an existing presentation journal deliberately refuses the spawn when the shared presentation lock is contended rather than falling back flat, and default-on makes that refusal reachable in any Herdr home.
+- Existing layouts are not force-renamed or rearranged.
+- Missing or ambiguous restart bindings fall back to the ordinary home workspace while the old projection remains untouched.
+- Crashes, lost responses, failed exact-pane cleanup, or human renames can leave quarantined spaces; session start removes only the exact home-local, uniquely journal-correlated, childless idle-shell shape above.
+- Spaces have no cross-home cleanup path, and an Eindri-home's child can clean up only from its exact home.
+- Every stale-looking space outside that narrow startup proof still requires manual cleanup in Herdr's UI after human inspection.
+- Regaining a dedicated space after degradation requires stopping the flat task, manually checking the stale projection, and clearing its journal before a genuinely fresh launch.
+- The visible token is only a restart-stable correlator and never substitutes for the exact binding.
+
+`tests/fm-backend-herdr-presentation-e2e.test.sh` covers multi-home ordering, concurrency, lock contention, legacy coexistence, focus preservation, exact same-identity restart replacement, ambiguous bindings and tokens, and exact-pane cleanup through the guarded lab path.
+`tests/fm-herdr-session-cleanup.test.sh` covers every discovery, ownership, topology, process, locking, revalidation, focus, retirement, and continue-on-error boundary.
+`tests/fm-herdr-session-cleanup-e2e.test.sh` covers the restored-shell cleanup in a guarded non-default named lab.
+`tests/fm-backend-herdr-focus-flash-e2e.test.sh` reproduces the raw explicit-close focus steal on the installed release and proves the focus-safe emptying-close plan removes a doomed workspace with no wrong-focus interval; [`verification/runtime-backends.md`](verification/runtime-backends.md#workspace-removal-focus-safety) owns the active versioned evidence.
+
+## Default-tab prune safety
+
+`herdr workspace create` seeds one default tab.
+Brokk prunes it only after a real task tab exists and only when the same create response supplied the seeded tab id.
+An adopted workspace never supplies that id and can never enter the prune path, regardless of labels or tab count.
+Immediately before close, Brokk rechecks the exact tab, expected seed label, and native agent state.
+A working seed pane is never closed.
+
+This created-versus-adopted gate is a destructive safety boundary.
+A prior label heuristic could adopt an Allfather-owned workspace named `firstmate` and close its live seed-shaped tab.
+The current structural gate removes label inference from cleanup authority.
+`tests/fm-backend-herdr-prune-safety-e2e.test.sh` reproduces the collision in an isolated named session and proves the adopted pane remains untouched.
+
+## Endpoint metadata
+
+```text
+backend=herdr
+window=<session>:<pane-id>
+herdr_session=<session>
+herdr_workspace_id=<workspace-id>
+herdr_tab_id=<tab-id>
+herdr_pane_id=<pane-id>
+```
+
+A Herdr pane id contains a colon, so the adapter splits `window=` on the first colon only.
+The recorded pane is the operational fast path.
+Workspace and tab ids support verification and cleanup but are not inferred from mutable labels during normal operation.
+
+## Current transport behavior
+
+The adapter starts and polls a named server before workspace, tab, pane, or agent calls.
+Every Herdr invocation goes through `fm_backend_herdr_cli`, which sets the environment and passes an explicit trailing `--session <name>`.
+An environment variable alone is not reliable when another Herdr server is running.
+
+Literal text and Enter are separate operations on `fm-send.sh`'s typed plane; ordinary local text steers instead use the durable steering inbox and send only its best-effort constant doorbell through this adapter.
+Spawn-time fixed commands may use Herdr's atomic run primitive.
+Enter, Escape, and Ctrl-C are supported.
+Typed-plane slash input, and dollar-prefixed skill input for Codex, uses the shared harness-aware settle before the first Enter so a completion popup cannot consume it.
+Typed-plane text is typed once; only Enter is retried.
+
+On an idle or done native baseline, submit confirmation first waits for `working` or `blocked` across a bounded polling window.
+If native status stays idle, the shared composer verdict is the next positive signal: a cleared composer is delivery, and proven pending text retries Enter.
+After the retry budget, `fm_composer_queued_enter_verdict` treats proven pending text plus a generating busy signal as a queued delivered Enter, and keeps an idle pending composer as a genuine swallow.
+On an already active or unreadable baseline, the adapter falls back to conservative composer clearance, with a pre-Enter rendered-footer transition when that baseline is unavailable.
+A fully unreadable target stops retrying and reports unknown.
+blocked is not treated as a queued-Enter busy signal, so a Cursor pane that reports blocked in every state does not receive that conversion.
+
+Some harnesses never present a legibly idle native baseline at all, so the composer fallback is their only path.
+Herdr reports a Cursor pane `blocked` in every state, and Cursor's mid-turn composer renders its placeholder beside a right-aligned busy token, which is composer content and therefore `pending` on a composer that holds no user text.
+That fallback alone reported every delivered steer as unconfirmed, so it is paired with a rendered-footer transition: the pane's verified busy footer is read once before the first Enter, and an idle-to-busy transition across that Enter confirms the submit.
+It is the same semantic signal the native path uses and the same one the tmux submit core reads.
+A pane already mid-turn cannot borrow a rendered-footer transition as proof of this delivery; after retries, only proven pending text plus native `working` can establish that its Enter was accepted and queued.
+The composer verdict itself is deliberately unchanged: a right-aligned status token on the composer row stays content for every other caller, including the away-mode pre-injection guard.
+The poll density bounds the residual possibility of an extremely fast complete turn; a missed native transition falls through to the composer verdict rather than reporting a false swallow.
+
+`pane read --lines N` can return empty output when N is below the viewport height.
+The capture owner requests at least 200 lines from Herdr and trims locally to the caller's bound.
+This generous floor is required for small composer and peek reads.
+
+Herdr's native agent state can read idle while a harness waits on its own long foreground tool.
+The shared worker-state path therefore accepts a native `busy` as evidence of activity but never a native `idle` as evidence that a worker has stopped; the task's own semantic busy state (`bin/fm-busy-lib.sh`) decides that.
+A human-blocked permission dialog has no busy banner and still surfaces.
+
+## Composer and injection safety
+
+Herdr has no direct cursor-row primitive.
+The adapter is a thin capture: it hands a bounded ANSI tail plus Herdr's capability facts to the fleet-wide classifier in `bin/fm-composer-lib.sh`, which owns every shape - bordered boxes, bare agent-glyph rows (including muse's `⟩`, which the adapter's retired local pattern silently omitted), opencode's left bar, and the Pi separator region this adapter pioneered, admitted only when native `agent get` identity is exactly Pi and state is idle or done.
+A blocked Pi is parked on an interactive prompt, so its blank composer region is a menu's and not a free composer's; that state defers instead of proving emptiness.
+A working Pi, pending middle row, missing identity, incomplete separator pair, or over-tall candidate remains unknown or pending.
+Identity stays a lazy second read, consulted only when a separator pair could change the verdict.
+
+ANSI capture preserves de-emphasized placeholder style.
+`bin/fm-composer-lib.sh` is the fleet-wide owner that strips dim or faint runs and dark truecolor placeholders while retaining bright typed input.
+If the ANSI capture ever fails, the plain fallback declares itself unstyled and the classifier degrades a glyph row carrying trailing text to `unknown` instead of misreading ghost suggestions as typed input, which safely defers injection and eventually raises the wedge alarm.
+
+A bare shell prompt is never an empty agent composer.
+Away-mode injection proceeds only on an affirmative `empty` result, never on unknown.
+This prevents a dead agent pane from receiving and possibly executing an escalation as shell input.
+
+The current operational envelope starts with U+2063 and `FIRSTMATE_OP: `.
+The separate routed-request carrier uses `[fm-from-firstmate]` plus U+2063.
+U+2063 survives Herdr terminal input as text, unlike the legacy ASCII control separator that could erase the visible routing label.
+`bin/fm-operational-input.sh` owns current operational construction and parsing, and the AFK skill owns legacy away-input compatibility.
+No Herdr-specific copy of that protocol exists.
+
+## Restart and liveness behavior
+
+Stopping and restarting a named Herdr server preserves workspace, tab, pane, and label ids, but the underlying harness processes and live agent registrations do not survive.
+A restored same-labeled tab with a missing pane or no registered agent is a husk.
+Create replaces only a confidently dead or no-agent husk, creates the replacement before closing the old tab, and refuses live or unknown states.
+This prevents closing the workspace's last tab before a replacement exists.
+
+The generic Herdr agent-liveness probe reuses the same classifier.
+A structurally gone pane becomes `missing`, a restored agent-less shell becomes `dead`, a registered agent becomes `alive`, and an unexpected read becomes `unreadable`.
+Unlike tmux process-name inspection, native registration can classify Pi without guessing from a generic interpreter name.
+
+The session-start sweep uses this probe.
+Mid-session Eindri-home agent-process liveness is not implemented because idle Eindri-homes are deliberately exempt from stale-pane escalation and need a separate periodic identity signal.
+
+## Push events and polling fallback
+
+Protocol 16 can subscribe to `pane.agent_status_changed` over one bounded Unix-socket reader.
+`bin/fm-transition-lib.sh` owns the backend-neutral transition vocabulary and policy.
+The Herdr adapter subscribes before reconciling current levels, buffers edges during reconciliation, and returns fresh blocked transitions for this home's panes.
+The watcher maps the pane back to the task and skips Eindri-home endpoints, declared `paused:` waits, and verified `Allfather-held` transfers, because a declared wait already names the human the fast escalation would report and is left to the watcher's own bounded pause cadence.
+
+The push path only shortens latency.
+Polling runs every cycle and remains the permanent fallback when protocol 16, the event schema, Python, connection, subscription, or repeated reader execution is unavailable.
+There is still one watcher process; the event reader is a bounded child of that watcher.
+
+`tests/fm-backend-herdr-eventwait-smoke.test.sh`, `tests/fm-transition-lib.test.sh`, and `tests/fm-supervision-events.test.sh` cover capability, subscribe-then-reconcile ordering, dedupe, exemptions, and polling fallback.
+
+## Away-mode supervisor support
+
+The away daemon supports tmux and Herdr supervisor panes only.
+It refuses Zellij, Orca, and cmux as supervisor backends rather than applying the wrong transport.
+For Herdr, target existence, native state, capture, composer state, and verified submit all route through the shared backend dispatcher and the explicit named-session CLI owner.
+The pane-independent max-defer alert is configured in [`wedge-alarm.md`](wedge-alarm.md).
+
+Harnesses with native tracked background execution can run the daemon in their terminal.
+Pi has no such mechanism.
+`bin/fm-afk-launch.sh` therefore creates a dedicated unfocused Herdr workspace, runs the daemon there with an explicit supervisor target and backend, records the exact daemon pane, and closes only that pane on stop.
+It never splits the Allfather's active tab and never uses shell `&`.
+Recovery reconciles only the recorded exact id.
+
+On stop, the daemon receives termination while `state/.afk` still exists so its final flush can run, the recorded terminal is closed, and the AFK flag is removed last.
+A fresh entry clears stale transient escalation caches, while durable queue and task records remain authoritative.
+
+## Destructive lab safety
+
+Never use ambient `herdr server stop` for Brokk verification.
+An environment-only session selection can silently reach a different running server, and the ambient stop command has no explicit target.
+
+`bin/fm-herdr-lab.sh` is the sole supported lifecycle helper for isolated verification.
+It provisions only non-default names beginning with `fm-lab-`, appends an explicit `--session` to allowed task commands, refuses caller-supplied session flags and server/session lifecycle subcommands, and performs destructive stop/delete only through its guarded lifecycle actions.
+Immediately before every destructive call it re-queries the named session and refuses empty, missing, literal `default`, or `default:true` identities.
+Its before/after tripwire requires the live default-session snapshot to remain byte-identical.
+
+The helper's header and `--help` own exact commands.
+Tests use thin compatibility wrappers in `tests/herdr-test-safety.sh` and never duplicate the destructive policy.
+
+## Active limits
+
+- Herdr remains experimental.
+- Presentation ordering needs protocol 16 and Python and is best-effort only.
+- Mutable labels can collide; they are never placement or destructive authority.
+- A Brokk outside Herdr cannot resolve a launcher workspace, so a colliding home label refuses new spawns until the collision is cleared.
+- Ghost and placeholder recognition uses ANSI de-emphasis when available; an unstyled glyph row carrying trailing non-idle text fails safely to `unknown`.
+- Mid-session Eindri-home agent-process liveness is not implemented.
+- Only tmux and Herdr can host the away-mode supervisor terminal.
+
+## Regression entry points
+
+```sh
+tests/fm-backend-herdr.test.sh
+tests/fm-composer-lib.test.sh
+tests/fm-herdr-submit-confirm-live-e2e.test.sh
+tests/fm-backend-herdr-smoke.test.sh
+tests/fm-backend-herdr-prune-safety-e2e.test.sh
+tests/fm-backend-herdr-respawn-idem-e2e.test.sh
+tests/fm-backend-herdr-workspace-per-home-e2e.test.sh
+tests/fm-backend-herdr-launcher-workspace-e2e.test.sh
+tests/fm-backend-herdr-presentation-e2e.test.sh
+tests/fm-backend-herdr-eventwait-smoke.test.sh
+tests/fm-herdr-session-cleanup.test.sh
+tests/fm-herdr-session-cleanup-e2e.test.sh
+tests/fm-afk-inject-herdr-e2e.test.sh
+tests/fm-afk-pi-herdr-return-e2e.test.sh
+```
+
+Real Herdr tests use the named lab helper and default-session tripwire.
+[`verification/runtime-backends.md`](verification/runtime-backends.md#herdr) records the active version, CLI, projection, event, and lifecycle evidence without task-specific chronology.