@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/eindri-homes/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: eindri-homes
+description: >-
+  Agent-only reference for persistent Eindri-home setup and retirement.
+  Use when creating, seeding, validating, launching, recovering, handing backlog to, pushing inherited local material into, or retiring a Eindri-home home, or when editing data/eindri-homes.md.
+  Covers local leases, whole-home remote routes, transactional seeding, record intake for an existing or inherited domain, project clone restrictions, Eindri-home harness pins, inherited local-material push, idle charter, handoff helper, and teardown safety.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# eindri-homes — worker homes — provisioning and upkeep of Eindri homes
+
+Use this reference before creating, seeding, validating, launching, handing backlog to, recovering, pushing inherited local material into, or retiring a persistent Eindri-home, and before editing `data/eindri-homes.md`.
+
+Keep the always-inline routing rules in `AGENTS.md` authoritative: route by natural-language `scope:`, local-only projects stay with the main Brokk, and eindri-homes are idle by default.
+
+## Routing table
+
+`data/eindri-homes.md` has one parser-compatible line per persistent Eindri-home.
+A local route uses:
+
+```markdown
+- <id> - <one-sentence charter summary> (home: <absolute-home-path>; scope: <natural-language responsibility>; projects: <project-a>, <project-b>; added <date>)
+```
+
+A whole-home remote route uses:
+
+```markdown
+- <id> - <one-sentence charter summary> (host: <ssh-alias>; root: <absolute-remote-code-root>; home: <absolute-remote-home>; scope: <natural-language responsibility>; projects: <project-a>, <project-b>; added <date>)
+```
+
+Each registry entry stays concise and single-line: the summary is one sentence naming the durable charter, `scope:` is the natural-language intake responsibility, `projects:` is the non-exclusive clone list, and any extra prose is limited to genuinely domain-specific hard rules that change routing or safety for that Eindri-home.
+Natural-language summary and `scope:` text may contain parentheses and semicolons; keep the generated `(home: ...; scope: ...; projects: ...; added ...)` suffix intact so operational consumers resolve its explicit field markers.
+The `home:` path points to the seeded home containing `data/charter.md`; no extra registry pointer field is needed.
+For a remote route, `host:` is an OpenSSH config alias and `root:` is that host's separate tracked Brokk code root.
+A remote Eindri-home agent always runs on the Herdr backend and every seed, launch, and liveness relaunch first gates its host on `bin/brokk-remote-doctor.sh` readiness, so an unready host refuses with that doctor's own gap text rather than half-creating a route; the workers that Eindri-home supervises keep the home's ordinary backend selection.
+This release places whole Eindri-home homes remotely and never individual workers.
+[`docs/remote-eindri-homes.md`](../../../docs/remote-eindri-homes.md) owns current operator setup and transport behavior.
+The home-seeded `data/charter.md` is the sole owner of boilerplate idle-by-default behavior, the normal delegation lifecycle, and standard escalation contracts, so point to that charter rather than restating those contracts in the registry entry.
+The `scope:` field is used during intake.
+The `projects:` field is a non-exclusive clone list, not ownership.
+
+## Charter and seed
+
+Scaffold a Eindri-home charter with:
+
+```sh
+bin/erindi-brief.sh <id> --Eindri-home {<project>...|--no-projects}
+```
+
+The scaffold writes a charter brief instead of a task brief.
+Set `BROKK_EINDRI_HOME_CHARTER='<charter>'` to fill the charter text and `BROKK_EINDRI_HOME_SCOPE='<scope>'` when the routing scope differs.
+If you scaffold without `BROKK_EINDRI_HOME_CHARTER`, replace the `{TASK}` placeholder before seeding.
+Pass `--no-projects` instead of a project list to scaffold a project-less charter for a domain whose subject is the Brokk repo itself, whose home is a Brokk worktree and whose Eindri take pooled worktrees of the same repo.
+`--no-projects` is mutually exclusive with a project list, and omitting both still fails loudly, so an accidental omission is never mistaken for a deliberate project-less seed.
+Re-seeding a populated home as project-less is refused non-destructively when the home contains project clones or `data/projects.md` entries.
+Retire or clean that home first, and re-scaffold a stale project-bearing charter with `--no-projects` before seeding.
+Keep custom charter text focused on the persistent responsibility, available project clones, and genuinely domain-specific hard rules.
+The scaffolded charter, later copied to `data/charter.md`, owns the standard lifecycle and escalation wording.
+Preserve the generated charter sections unless the domain genuinely needs a hard rule.
+
+Provision a local persistent home and registry entry after the charter is filled:
+
+```sh
+bin/brokk-home-seed.sh <id> <home|-> {<project>...|--no-projects}
+```
+
+Provision a whole remote home through its configured SSH host with:
+
+```sh
+bin/brokk-remote-home-seed.sh <id> <ssh-alias> <remote-root> <remote-home> {<project>[=<origin-url>]...|--no-projects}
+```
+
+You resolve each project's origin yourself - from the Allfather, the project registry, a clone that exists elsewhere, `gh-axi`, or an explicit paste - and name it as `<project>=<origin-url>`; the seed validates and transports what you supply.
+A remote seed therefore creates nothing in this home beyond the route, the charter brief, and a launch record once it is launched: never clone a project into `projects/`, initialize no-mistakes here, or run a fleet sync just to seed a remote Eindri-home.
+A bare `<project>` remains a convenience for a project this home already has cloned, whose configured origin is read instead.
+[`docs/remote-eindri-homes.md`](../../../docs/remote-eindri-homes.md#provision-a-route) owns the rest of the operator contract, and [`bin/brokk-project-origin-lib.sh`](../../../bin/brokk-project-origin-lib.sh) owns the accepted origin forms.
+Pass `--no-projects` in the project position to seed the project-less home described above; the same mutual-exclusion and fail-loud-on-omission rules apply.
+It may only seed a home with no project clones or project-registry entries, and refuses conversion of populated homes without changing them.
+`-` durably leases a fresh Brokk worktree via `Yggdrasil get --lease` under the Eindri-home id.
+The lease survives with no live process and is never recycled by later `Yggdrasil get` or `prune`.
+The slot stays reserved across restarts until the lease is released.
+Release happens only on explicit retirement or seed rollback, never on routine restart or recovery.
+
+`bin/brokk-home-seed.sh` copies the charter into the Eindri-home home as `data/charter.md`.
+It also writes the gitignored `.brokk-Eindri-home-parent` durable binding before the required `.brokk-Eindri-home-home` identity marker; the parser header in [`bin/brokk-Eindri-home-parent-lib.sh`](../../../bin/brokk-Eindri-home-parent-lib.sh) owns the record contract, and both files must remain in place.
+`bin/einherjar-spawn.sh --Eindri-home` launches it through the Eindri-home harness path, resolving `config/Eindri-home-harness` -> `config/eindri-harness` -> the primary's own harness unless an explicit per-spawn harness override is passed.
+
+`config/Eindri-home-harness` may also pin a concrete model and effort for the Eindri-home agent, in the SAME file rather than a new one: the format is a single whitespace-separated line `<harness> [<model>] [<effort>]`, with only the first non-empty, non-comment line parsed.
+A bare `<harness>` (today's format, e.g. `claude`) behaves exactly as before - harness only, no model/effort flag - so this is fully backward-compatible.
+`bin/hamr-harness.sh Eindri-home-model` and `bin/hamr-harness.sh Eindri-home-effort` print the optional 2nd/3rd tokens (empty when absent, or when the file is absent/`default`/harness-only); they read only `config/Eindri-home-harness`, never `config/eindri-harness`, which stays a bare adapter name.
+For a `--Eindri-home` spawn, `bin/einherjar-spawn.sh` populates `MODEL`/`EFFORT` from those tokens only when the harness itself came from the Eindri-home config path for that spawn.
+For a local route, an explicit per-spawn `--harness` flag, positional harness arg, or raw launch command starts clean on model and effort too, unless the caller also passes explicit `--model` or `--effort`.
+A remote route accepts only a verified harness adapter and refuses a raw launch command at the host boundary.
+When the file's tokens do apply, an explicit per-spawn `--model` or `--effort` flag always wins over the file's token for that axis.
+Because this resolves from the file on every spawn, the pin is durable across every respawn (recovery, `/updateBrokk`, restart) exactly like the harness axis itself - e.g. `config/Eindri-home-harness` containing `claude opus` keeps a Eindri-home pinned to Opus even if the primary's own default model later changes.
+This is Eindri-home-only: Eindri/scout model resolution is untouched by this file.
+
+This section is the single owner of the Eindri-home sync and inherited-local-material propagation contract; `AGENTS.md` sections 3 and 4 point here.
+Before a local launch, `einherjar-spawn.sh --Eindri-home` locally fast-forwards the home to the primary Brokk checkout's current default-branch commit when it is safe; dirty, diverged, or in-flight homes launch unchanged with a warning.
+The locked session-start deferred network stage runs the same bootstrap sweep for every live local Eindri-home home, discovered from `state/<id>.meta` records with `kind=Eindri-home` (`data/eindri-homes.md` only backfills `home=` for older records).
+That no-fetch path is a purely local fast-forward of tracked files, never an origin fetch, and it never touches the gitignored operational dirs, so a Eindri-home's backlog, projects, and in-flight work are never disturbed; a linked worktree advances immediately, while a standalone clone that lacks the target receives Brokk updates through `/updateBrokk`'s origin refresh.
+A remote launch and the deferred bootstrap sweep ask the configured host to fast-forward its persistent home to that host's code-root commit under the same clean and ancestry guards.
+`/updateBrokk` first updates the remote code root from its own origin, then runs that guarded home sync.
+SSH exit 255 preserves the route and reports unknown completion; it never triggers local respawn or failover.
+The same placement-specific launch and deferred bootstrap sweep also propagate the primary's declared inherited local material: `config/crew-dispatch.json`, `config/eindri-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, `config/startup-memory-budget`, and the one shared Allfather-preference file `data/Allfather-shared.md`.
+Because these paths are gitignored, that propagation is a separate, primary-authoritative copy independent of the tracked-files fast-forward: it re-converges every live home whether or not its tracked files advanced, and it touches only the declared items.
+Propagation failures warn without blocking Eindri-home launch or session-start continuation, and the destination keeps whatever safely validated state the helper left behind.
+Inheritance copies the literal `config/eindri-harness` file, so a Eindri-home's own Eindri use the primary's Eindri harness only when it names a concrete adapter such as `codex`; an unset or `default` value has nothing concrete to inherit, and the Eindri-home's own Eindri fall back to the Eindri-home's own or detected harness instead.
+Inherited `config/backend` becomes that Eindri-home home's local runtime-backend default for future spawns only; it never retargets, rewrites, migrates, stops, or restarts an already-live worker endpoint.
+A present primary value always converges byte-exact into validated Eindri-home homes, and primary absence removes the destination so those homes keep runtime auto-detection.
+Explicit per-spawn `--backend` and `BROKK_BACKEND` remain stronger than every home's local `config/backend`, including an inherited default.
+`config/Eindri-home-harness` is not inherited because it is only the primary's knob for launching Eindri-home agents.
+`data/Allfather-shared.md` is main-authoritative in the primary home and read-only in Eindri-home homes.
+Its primary file header must state that the file is main-authoritative, read-only in Eindri-home homes, must not be edited there, and that new Allfather-preference discoveries are routed to the main Brokk through marked status or a document pointer.
+Every propagation point converges the Eindri-home copy to the primary bytes; when the primary file is absent, any existing Eindri-home copy is quarantined and removed so absence converges too.
+The helper rejects unsafe directories, symlinked or nonordinary source or destination artifacts, and hardlinked destination files.
+Between propagation runs, the Eindri-home copy is filesystem read-only; the helper may make its owned destination writable only around a guarded update and restores read-only mode on success, unchanged bytes, and recoverable failure paths.
+Before replacing divergent Eindri-home bytes, the helper hash-compares source and destination, quarantines the Eindri-home-local version to a collision-safe private dated sibling file, and emits a `EINDRI_HOME_SYNC:` diagnostic naming the home and quarantine artifact.
+Never copy any Eindri-home `data/Allfather-shared.md` back into the primary.
+Keep each home's `data/Allfather.md` domain-local.
+After first propagation to an existing home, trim that home's local `data/Allfather.md` by hand to domain-specific content plus pointers to `data/Allfather-shared.md`; do not automate or silently delete private content.
+Keep every `data/learnings.md` fully local by Allfather decision; route fleet-general machinery facts into tracked documentation through the normal Brokk repo path rather than inventing shared learnings propagation.
+No AGENTS.md reread nudge is needed at spawn or respawn because the agent reads instructions fresh on launch; only the bootstrap sweep's running-home instruction-surface advance needs that AGENTS.md re-read.
+Bootstrap reports successful AGENTS.md re-read sends as `BOOTSTRAP_INFO:` and only emits `NUDGE_EINDRI_HOMES:` when that send fails and needs retry.
+A separate, literal-content config reread is required whenever inherited `config/*` material changes under an already-running Eindri-home.
+For a local home, after each successful allowlisted config write, both the locked bootstrap convergence path and mid-session `bin/brokk-config-push.sh` use the shared propagation report to build one per-home generation-specific private instruction file from the validated destination post-write bytes for only the allowlisted config items that actually changed for that home (`config/crew-dispatch.json`, `config/eindri-harness`, `config/backlog-backend`, `config/backend`, `config/herdr-presentation-spaces`, `config/startup-memory-budget`), in deterministic allowlist order.
+Each changed path is printed with clear begin/end delimiters and the destination file's full exact new bytes unparsed, or the explicit token `ABSENT` when propagation removed the destination copy.
+The instruction uses only minimal framing that these are defaults/rules and do not remove judgment; it never includes SHA values, selected profiles, parsed summaries, or any other generated interpretation.
+`data/Allfather-shared.md` is not a config file and is never inlined into this instruction file or message.
+Homes whose allowlisted config files were all unchanged receive no config-reread message when no retry is pending.
+Different homes may receive different changed-file sets based on their pre-push destination bytes.
+Delivery uses the existing routed Eindri-home path (`brokk-send`) with only a single-line `CONFIG_REREAD: <absolute generation-specific instruction path>` pointer; a failed instruction publication retains the generated exact bytes in a bounded private retry queue when possible, legacy retry reports remain recoverable, a failed publication or retry-marker write retains the exact generation until it can be delivered, a failed send records a per-generation durable retry marker when possible, and all failures surface a concrete `CONFIG_REREAD:` diagnostic without claiming the live agent already re-read the values.
+The propagation, generation publication, and pointer-delivery sequence holds one per-home inheritance lock, so concurrent mid-session pushes cannot deliver an older generation after a newer one.
+A newly launched or relaunched Eindri-home already reads its files at launch, so its pending config-reread generations are discarded or quarantined after cleanup failure and it needs no redundant live-agent config nudge unless propagation changes files after launch.
+Quarantined pre-relaunch generations are retained in bounded private history, and cleanup skips creating an empty quarantine generation.
+Successfully delivered generations are retained only within a bounded per-home state history, while pending generations remain until delivery succeeds or a launch supersedes them.
+A remote home receives the same allowlisted bytes through `brokk-remote-inherit.sh` and gets one marked re-read instruction after a changed transfer.
+The parent records that nudge before delivery, retains it after a failed send, and retries the exact same route during locked bootstrap convergence.
+It does not receive a pointer to a primary-local generation path that cannot exist on that host.
+These config values remain defaults and rules only; they must not harden `brokk-spawn` to reject a deliberate runtime choice that differs from the configured defaults.
+For already-live eindri-homes, use `bin/brokk-config-push.sh` to push a mid-session inherited local-material change without running the tracked-file fast-forward.
+It uses the same live-home discovery and propagation helper as bootstrap, reports each item as `pushed`, `unchanged`, `skipped`, or `error`, and follows the config-reread contract above for changed or pending generations.
+`bin/brokk-home-seed.sh` refuses to copy a missing or placeholder charter.
+
+Direct seed without a preexisting brief requires `BROKK_EINDRI_HOME_CHARTER`.
+Run `bin/brokk-home-seed.sh validate` when checking registry integrity; its header owns the complete validation and refusal mechanics.
+
+Seeding is transactional.
+If validation, cloning, no-mistakes initialization, or registry update fails, generated briefs, new homes, new project clones, and registry edits are rolled back.
+
+Eindri-home project lists may include `no-mistakes` and `direct-PR` projects only.
+`local-only` projects stay with the main Brokk.
+For `no-mistakes` projects, seeding initializes only projects newly cloned into a Eindri-home home and refuses to mutate a preexisting clone that is not already initialized.
+
+## Record intake for an existing or inherited domain
+
+Classify the domain before seeding, because this step applies to only one of the two cases.
+A greenfield domain has no delivered domain work yet: nothing already shipped in its projects, no live deployment, and no predecessor records to import.
+Seed a greenfield domain normally; there is nothing to reconcile and this section adds no work to it.
+An existing or inherited domain is any domain whose product is already in development, and any predecessor's domain a new mate takes over, including a consolidation after a retirement.
+Both of those cases require record intake before the new mate acts on any inherited plan.
+
+For an existing or inherited domain, the creating agent must:
+
+1. Reconcile every inherited plan against the domain's authoritative shipped state, which is `origin/main` for each relevant project plus the live deployment.
+   A fetched clone of each relevant project is a precondition of that reconciliation, so wire the home to its projects before reconciling rather than on first task.
+   The imported backlog, the predecessor's own notes, instruction-surface prose, and an absent or unfetched local view are all inadmissible as shipped-state evidence.
+2. Seed the new home with only genuinely open work plus the domain's durable knowledge, meaning the learnings, decisions, and delivery posture that are still live.
+3. Never inherit a plan backlog blind.
+   A plan row whose work is already shipped is dropped, or recorded as done with the merged evidence that settles it, and is never carried forward as open.
+
+A live backlog keeps only the configured recent Done entries by design, so an inherited queue structurally over-represents plans and under-represents deliveries.
+Treat an inherited queue that carries plans with no matching delivery record as unreconciled rather than as open work, and record whatever could not be reconciled as an explicit residual-uncertainty list in the new home rather than leaving that gap silent.
+
+## Backlog handoff
+
+Apply `AGENTS.md` section 10's work-items-only backlog contract before creation or handoff.
+When a Eindri-home is created for a domain, existing main-backlog items that fall under its scope should become its work instead of staying stranded in the main backlog.
+Scope-matching is Brokk's judgment against the Eindri-home's natural-language scope, not a keyword rule.
+Read `data/backlog.md`, pick queued items that fit the new scope, and move them with:
+
+```sh
+bin/brokk-backlog-handoff.sh <Eindri-home-id> <item-key>...
+```
+
+After seeding, run this handoff for the new Eindri-home's in-scope queued items.
+For an existing or inherited domain, complete record intake first so no already-shipped plan row is handed off as open work.
+For a local route, the helper resolves and validates the Eindri-home home from `data/eindri-homes.md`, then delegates the item move to `tasks-axi mv` (the single owner of the backlog format), which moves each named item - and a whole connected set, blocker plus dependents, atomically - from the main `data/backlog.md` into the Eindri-home home's `data/backlog.md`.
+For a remote route, the same helper first moves the dependency-closed set atomically from the main backlog into `data/handoff/<id>.outbox.md`, then transfers that backlog-format outbox through `brokk-on.sh` and lets the remote home's `brokk-backlog-receive.sh` move every not-already-present key under the destination lock.
+After a new local placement or a remote outbox receipt becomes durable, the helper sends one marked routed-work instruction through the receiving Eindri-home's recorded endpoint; missing or failed delivery makes the command fail loudly with the moved work intact, and the same handoff command retries known-undelivered wake intent without moving an already-present item again.
+An unresolved delivery attempt is never blindly resent.
+For a remote route, the outbox remains until both backlog receipt and receiver wake are confirmed; `--resume-pending` retries unfinished outboxes, while the script header owns its stable wake-correlation recovery state.
+There is no two-phase handoff journal and no tasks-axi release beyond the already-required atomic `mv` capability.
+Bootstrap retries pending outboxes when mutation is authorized and emits `EINDRI_HOME_HANDOFF:` for any that remain.
+This delegated route remains required when `config/backlog-backend=manual`, which controls only routine Brokk backlog edits.
+It moves each queued item's whole block - the `- [ ] <id> ...` header plus every following two-or-more-space-indented body line and blank separator, up to the next item or column-0 section heading - byte-exact under the same section, treating an indented `## ...` line as body rather than a section boundary, so neither the header nor its body is duplicated or orphaned.
+It refuses a selected item with a single-space or tab-indented continuation rather than risk leaving content orphaned in the main backlog.
+It accepts in-scope `## Queued` entries only and refuses `## In flight` and historical `## Done` entries.
+Done records stay with their home for pruning or archiving.
+It is idempotent; an item already in the Eindri-home backlog is skipped.
+After a successful move it warns for any moved key that still owes a public relay reply bound to `main/<key>`, because that binding no longer names the home owning the work; rebind the commitment to `Eindri-home:<id>` through the `fmx-respond` promised-final procedure, which owns those commands.
+That same rule governs routing generally: a Relay-linked request whose work goes to a Eindri-home cannot use the home-local mention link at all and needs a promised-final commitment bound to that Eindri-home's home.
+It refuses any destination that is not a genuine seeded Brokk home with safe operational directories and a matching `.brokk-Eindri-home-home` marker, so a move can never land in a project.
+Do not hand off `local-only` items.
+
+## Recovery
+
+For local `kind=Eindri-home` meta with no window, treat the Eindri-home as a dead persistent direct report and respawn it with:
+
+```sh
+bin/einherjar-spawn.sh <id> --Eindri-home
+```
+
+Use the recorded `home=` in meta.
+If meta is missing but `data/eindri-homes.md` still registers the Eindri-home, respawn from the registry entry and its persistent home.
+For a remote route, the same command probes and relaunches only on the configured host.
+An SSH transport failure or unreadable remote endpoint remains unknown and must be reconciled on that host; never launch a local replacement.
+`stuck-Eindri-recovery`'s remote-Eindri-home note owns why the endpoint-dead and send-failed verdicts that seem to justify this are themselves unreliable.
+Respawn re-resolves the Eindri-home harness from current config, uses the same guarded pre-launch sync, and re-propagates inherited local material, so recovered eindri-homes converge inherited config items and shared Allfather preferences whenever their home validates; tracked-file sync remains guarded separately.
+If the Eindri-home is already running and only inherited local material changed, prefer `bin/brokk-config-push.sh` over respawning.
+To move a live LOCAL Eindri-home onto a newly pinned harness, model, or effort without a full recovery, set `config/Eindri-home-harness` and then relaunch it with `bin/brokk-control.sh <id> relaunch`, which re-resolves that pin, stops the agent, and launches the replacement in the same home ([`docs/agent-control.md`](../../../docs/agent-control.md)).
+That plane refuses a remotely placed Eindri-home by name, because its agent runs on another host where none of the plane's postconditions can be read; use the remote route's own relaunch path for those.
+
+Do not reconstruct a Eindri-home's whole tree from the main home.
+The main Brokk reconciles only direct reports.
+Each Eindri-home is a Brokk in its own home, so it runs recovery on startup and reconciles its own Eindri.
+A Eindri-home's recovery reconciles only work that is already its own and then idles.
+It never initiates a survey or audit during recovery.
+
+## Retirement and teardown
+
+A Eindri-home is persistent by default.
+An empty queue is healthy and does not trigger teardown.
+Run `bin/brokk-teardown.sh <id>` for `kind=Eindri-home` only when the Allfather or main Brokk explicitly decides to retire that persistent Eindri-home.
+
+The safety check is the Eindri-home's own home.
+Teardown refuses while its `state/*.meta` contains in-flight work.
+A remote route delegates the same guard to its configured host and additionally refuses while the primary has a pending handoff outbox or unresolved routed reply.
+SSH exit 255 preserves the route and local records because remote completion is unknown.
+When safe, teardown kills the direct endpoint, removes the `data/eindri-homes.md` route, clears the main home metadata, and removes the retired Eindri-home home.
+Removing a leased home releases its durable Yggdrasil lease via `Yggdrasil return`, so the pool slot is freed for reuse rather than left leased forever.
+A plain-clone home with no pool slot is simply removed.
+If `Yggdrasil return` fails for a leased home, teardown stops with state intact rather than raw-removing the directory and hiding a held lease.
+Before either return or direct removal, teardown asks the target home's process-event runner to retire its registrations and physically owned machine-wide claims through the safe generation-bound path.
+It refuses retirement while that cleanup is uncertain or unavailable, preserving the home and retirement records for a later retry.
+Raw deletion is unsupported because a blocking process-event child can outlive its home.
+
+With `--force`, teardown is the explicit discard path.
+It kills child windows, discards child work and state inside the Eindri-home home, removes the route, releases the lease, and removes the retired Eindri-home home.
+If forced teardown contends with a fresh task publication in any affected home, one command refuses without publishing or removing task state; treat that refusal as terminal and inspect the other operation before retrying.
+Relaunch and non-forced teardown remain outside that serialization.
+Never use `--force` unless the Allfather explicitly said to discard the work.
+
+## Fleet preferences
+
+Fleet-wide per-user settings live in `data/fleet.md` (gitignored), one
+`key: value` per line. `bin/fleet-apply.sh` writes each into THIS home and every
+registered home's gitignored `state/` (for `ro`: `state/ro`), and
+`bin/brokk-update.sh` re-applies them on every sweep — so one fleet setting
+reaches every home without dirtying any tracked tree. Remote routes are reported,
+not written. Keys: `ro: on | off` (Ró calm presentation).
+
+## Dispatch (full chain)
+
+Seating a worker is a chain, not a guess: role → **`bin/model-resolve.sh`** →
+harness rule (local→pi, online→opencode) → **`bin/herdr-run.sh eindri`** (pane)
+→ **`bin/local-model-lock.sh`** → A2A register. Read
+`assets/dispatch.md` before dispatching, and never guess a model.
+
+## Tools this skill drives (in `bin/`)
+
+Use these — never hand-run herdr/tmux:
+
+```
+tools[6]{tool,plane}:
+  "bin/eindri-start.sh \"<task>\" [--role] [--model] [--pane|--tab|--space]","one command: role -> model-resolve -> seat -> serve"
+  "bin/herdr-run.sh eindri [--model] <role> -- \"<task>\"","the seat engine (pane/tab/space)"
+  "bin/eindri-send.sh <agent> \"<text>\"","DATA plane — talk to a running Eindri"
+  "bin/eindri-control.sh interrupt|exit|read <agent>","CONTROL plane — allowlisted lifecycle"
+  "bin/einherjar-spawn.sh <id> --Eindri-home","launch a persistent home (recovery/retire above)"
+  "bin/model-resolve.sh · bin/local-model-lock.sh","model choice + one-local-at-a-time"
+```
+
+## Assets
+
+```
+assets[1]{path,holds}:
+  "assets/control-plane.md","agent lifecycle control plane (from the upstream distro): DATA plane (conversational send) vs CONTROL plane (allowlisted verbs interrupt/exit/relaunch), per-harness mechanics, per-backend capability"
+```

package/.agents/skills/eindri-homes/assets/control-plane.md

@@ -0,0 +1,122 @@
+# Agent lifecycle control plane
+
+Brokk talks to a running agent two ways, and they are not the same channel.
+
+The **data plane** is [`bin/fm-send.sh`](../bin/fm-send.sh): conversational text for the agent to read.
+For a `kind=eindri-home` target it always prepends the routing marker (`[fm-from-firstmate]`), because an Eindri-home runs its own primary Brokk and its reply must come back through the status path rather than a chat nobody reads.
+
+The **control plane** is [`bin/fm-control.sh`](../bin/fm-control.sh): allowlisted lifecycle verbs addressed to an exact task id.
+
+The split exists because the data plane's marking is exactly right for a message and exactly wrong for a lifecycle command.
+A routing-marked `/quit` arrives as ordinary chat - `[fm-from-firstmate] /quit` - which the agent reasons about instead of executing.
+The failure repeated across harnesses and homes, and the workaround (remember to use an unmarked send for agent-control commands, and improvise the right key or command per harness) lived only in agent prose, so it failed again every time a session did not happen to recall it.
+
+## What the control plane owns
+
+`bin/fm-control-lib.sh` is the single executable owner of three capability tables, with no side effects, so it can be read as a contract:
+
+- The **verb allowlist**: `interrupt`, `exit`, `relaunch`.
+  There is no arbitrary-text and no generic raw-key entry point.
+  A caller either names an allowlisted verb or is refused.
+- **Per-harness mechanics**: the key that cancels a running turn, how many times it must be delivered, whether the composer needs clearing afterwards, the command that exits the agent, and which task kinds the adapter is verified to run.
+  These were previously carried only in the [`harness-adapters`](../.agents/skills/harness-adapters/SKILL.md) skill's tool references, which now point here.
+  `bin/fm-send.sh`'s `--key` path reads the composer-clear table from this owner too, rather than keeping a second copy of it.
+- **Per-backend capability**: which named keys a runtime backend can deliver, and whether it has a recovery-grade agent-state classifier able to prove an agent stopped.
+
+A recorded `harness=` is not always an exact adapter name: a task launched from a raw command records that command's basename instead.
+`fm_control_harness_family` is the one place that prefix rule is stated, and an unrecognized value resolves to no adapter rather than being guessed into one.
+
+## Verbs
+
+| Verb | Effect | Postcondition |
+| --- | --- | --- |
+| `interrupt` | Deliver the harness's verified interrupt sequence while leaving the agent running. | Delivery succeeds while the endpoint still exists and the agent is still alive where the backend can classify that; cancellation is confirmed only from an adapter-owned acknowledgement and otherwise reports `cancel=unconfirmed`. |
+| `exit` | Stop the agent, preserving the endpoint, the worktree, and every uncommitted change. | The backend's recovery-grade classifier reports the agent gone. Already-stopped is idempotent success. |
+| `relaunch` | Replace the running agent with a new one in the same endpoint and worktree, on the exact recorded adapter or an explicitly chosen harness, model, and effort. | The new agent is alive on the recorded endpoint, and the durable record names the harness that is actually running. |
+
+An exit that delivers lifecycle input but cannot prove the agent stopped fails with `exit=unconfirmed`, reports the observed agent state and any interrupt cancellation claim, and never claims that nothing changed.
+Interrupt never rewrites busy state as proof of its own success.
+Claude exposes no lifecycle acknowledgement for a manual interrupt, so delivery succeeds with `cancel=unconfirmed` and its adapter-owned busy state remains as observed.
+muse's session log records `terminal=cancelled` for the interrupted run, so the control plane reports `cancel=confirmed` only after observing that exact acknowledgement.
+
+An interrupt is not complete until the composer is empty.
+muse is the one verified adapter that restores the cancelled prompt back into its composer as real text, so its interrupt key is followed by a Ctrl+U clear; without it the next submitted line - including this plane's own exit command - would concatenate onto the restored prompt and submit both as one line.
+The clear is refused before anything is sent when the recorded backend cannot deliver it.
+
+**Teardown and discard are not verbs and will not become verbs.**
+`exit` stops an agent and preserves everything else.
+Removing a worktree, closing an endpoint, or discarding work stays with [`bin/fm-teardown.sh`](../bin/fm-teardown.sh), which owns the landed-work test.
+
+**`resume` is not a verb.**
+It is not deterministic across the verified adapters: codex and grok resume only from a session id printed at exit, opencode continues the most recent session for the cwd, and claude, pi, pi-signed, and kimi have no verified pane-resume contract.
+`relaunch` covers the same need on every adapter, because the brief on disk - not a harness-private session - is the durable instruction.
+
+## Transactional relaunch
+
+`relaunch` is the only verb that changes durable records, so it runs as a transaction with a journal at `state/<id>.control-relaunch`, the prior record preserved beside it, and a ship or scout's prior instructions preserved when a progress note is appended.
+
+1. **Resolve the profile.**
+   An explicit `--harness`, `--model`, or `--effort` wins.
+   Otherwise a `kind=eindri-home` task re-resolves its durable `config/eindri-harness` pin, including that file's optional model and effort tokens, exactly as every other respawn does - so setting the pin and relaunching is the ordinary way to move an Eindri-home's runtime.
+   A ship or scout keeps the harness already recorded for it, because that harness comes from Brokk's dispatch-profile judgment at intake and must not be silently re-read from configuration.
+   A recorded raw-command basename that differs from its resolved adapter cannot reproduce the command actually running, so relaunch refuses before the checkpoint unless the caller passes an explicit `--harness` to choose the replacement runtime deliberately.
+   A harness change resets model and effort unless they are named too, because a model chosen for one adapter does not transfer to another.
+2. **Safe checkpoint.**
+   The recorded worktree must exist and be a worktree root; its head and dirty state are recorded.
+   For a `kind=eindri-home` task, the home's identity marker must match and its child records must be readable, so a relaunch can never strand child work behind an unreadable home.
+   The Eindri an Eindri-home launched run in their own endpoints and outlive its relaunch; the relaunched home reconciles them from its home's durable records at startup.
+3. **Record the note.**
+   A ship or scout relaunch requires `--note`, because the replacement inherits the local copy but none of the conversation; the note is appended to the instructions it reads.
+   An Eindri-home relaunch does not require one and never rewrites its standing charter.
+4. **Stop the old agent** through the `exit` verb, with its postcondition.
+5. **Launch the replacement** through its single owner, `bin/fm-spawn.sh --relaunch`, which adopts the recorded endpoint and worktree instead of creating either, clears the previous harness's per-task wiring, and arms a fresh busy generation.
+
+Switching harness is therefore one ordinary relaunch rather than a separate mechanism.
+
+### Failure and rollback
+
+- A refusal **before** the agent is stopped leaves the durable record and the instructions byte-identical.
+- A launch failure **after** the agent is stopped restores the prior durable record, keeps the progress note so a later recovery still has it, marks the journal `failed:launching`, and reports plainly that no agent is running and where the work is preserved.
+- If the launch owner already published the new record but no running agent can be confirmed, the new record is kept: the task is recorded on the new harness with no agent confirmed, which is exactly what recovery reconciles.
+  Rewriting it back to the old harness would be a second, worse inaccuracy.
+
+## Fail-closed boundaries
+
+- Targeting is exact.
+  Only a bare task id with a `state/<id>.meta` record in this home is accepted, and that record must pass the shared endpoint-identity validation.
+  A legacy `fm-<id>` window label, an explicit `session:window` endpoint, and a record whose `endpoint_task_id` names another task are all refused.
+- A remotely placed Eindri-home is refused by name.
+  Its agent runs on another host, so none of the postconditions this plane verifies could be read for it here; local endpoint validation would refuse the record regardless, because `window=remote:<id>` can never match a local backend's required shape.
+  Drive that lifecycle on its own host and reconcile it through the Eindri-home recovery path.
+- An unverified harness is refused rather than guessed at.
+- An implicit relaunch from a prefixed raw-command basename is refused before the agent or durable state is touched because its original launch command cannot be reconstructed.
+- An adapter that is not verified for this task's kind is refused **before** the running agent is stopped, not after.
+  Muse is an Eindri and scout adapter only, so relaunching an Eindri-home onto it refuses while its agent is still up rather than leaving that Eindri-home with no agent when the launch owner refuses.
+- A backend that cannot deliver the harness's interrupt key, or the composer clear that key needs, is refused rather than sent a different key.
+  Orca's terminal API exposes only an interrupt and an Enter, so it can deliver neither Escape nor Ctrl+U.
+- `exit` and `relaunch` require a backend with a recovery-grade agent-state classifier - tmux and herdr - because without one the "the agent stopped" postcondition cannot be proven.
+  zellij, orca, and cmux are refused rather than reported as successful blind.
+- An ambiguous or unreadable endpoint state refuses.
+  Only a positively classified state acts.
+- `fm-spawn --relaunch` independently refuses unless the recorded endpoint is positively agent-free and its shell is sitting in the recorded worktree, so a replacement can never join a live agent or start outside the copy holding the work.
+
+## Capability matrix
+
+Backend capability comes from each adapter's real surface, not from a policy choice.
+
+| Backend | Escape | Enter | Ctrl+C | Ctrl+U | Recovery-grade agent state |
+| --- | --- | --- | --- | --- | --- |
+| tmux | yes | yes | yes | yes | yes |
+| herdr | yes | yes | yes | yes | yes |
+| zellij | yes | yes | yes | yes | no |
+| cmux | yes | yes | yes | yes | no |
+| orca | no | yes | yes | no | no |
+
+Per-harness interrupt keys, repeat counts, composer clears, exit commands, and supported task kinds live in `bin/fm-control-lib.sh` and are exercised for every verified harness by `tests/fm-control.test.sh`.
+The empirical basis for each adapter's value is the `harness-adapters` skill's verification record for that adapter.
+
+## Verification
+
+- `tests/fm-control.test.sh` - the adapter contract for every verified harness, the backend capability matrix, exact-id scoping, the closed verb list, the busy, idle, dead, and idempotent lifecycle cases, and marker non-regression, all against a stubbed session provider.
+- `tests/fm-control-relaunch.test.sh` - the relaunch transaction: identity preservation, harness switching, the progress note, checkpoint refusals, and rollback after a failed launch.
+- `tests/fm-control-herdr-smoke.test.sh` - the second state-verified backend against the real herdr binary, on an isolated throwaway lab session.

package/.agents/skills/eindri-homes/assets/dispatch.md

@@ -0,0 +1,80 @@
+# Dispatching an Eindri — the full chain
+
+How a request becomes a seated, running worker. Every link is a real script; the
+chain must never guess a model or skip the lock.
+
+```
+dispatch[8]{step,who,what}:
+  "1 request","Allfather / Brokk","a task, optionally naming a model or locality"
+  "2 role","bin/eindri-role.sh choose","pick the smith by craft (whole-word match)"
+  "3 model","bin/model-resolve.sh resolve","friendly/exact -> {locality,harness,provider,model}; unresolved -> ASK"
+  "4 harness","config/agents.yaml harness rule","local -> pi, online -> opencode (agent may pin harness:)"
+  "5 seat","bin/herdr-run.sh eindri (or bin/eindri-start.sh)","herdr pane/tab/space; --model resolution happens here"
+  "6 lock","bin/local-model-lock.sh","serialize local inference per host (local_concurrency)"
+  "7 register","a2a MCP (a2abridge bridge)","agent announces its card; reachable over A2A"
+  "8 report","herdr agent list / Hlidskjalf Fleet","state: working/blocked/done; tasks from Runes"
+```
+
+## The commands
+
+```bash
+# resolve a request (no side effects)
+bin/model-resolve.sh resolve "qwen 3.6 iq2"
+#  -> locality=local harness=pi provider=llama-cpp model=qwen3.6-35b-a3b@q2_k_xl
+
+# seat the right smith on the right model, in a visible pane
+bin/herdr-run.sh eindri bragi --model "qwen 3.6 iq2" -- "do marketing research"
+# convenience front door:
+bin/eindri-start.sh "do marketing research"        # role + seat; add --model to pin
+```
+
+## Rules (non-negotiable)
+
+- **One local model at a time per machine** — route local runs through
+  `bin/local-model-lock.sh` (`local_concurrency` in `config/agents.yaml`).
+- **Local → `pi`, online → `opencode`** — unless an agent pins `harness:`.
+- **Never guess a model** — a low/medium confidence resolve for an explicit
+  request must **ask** (`ask_user_question`).
+- **A model token must be servable** — match `pi --list-models` and the running
+  llama server `/v1/models`; `iq2` has no id today (nearest `q2_k_xl`).
+- **Seat visibly** — a pane beside the work; never a hidden process.
+
+## Known gaps to close (to 100%)
+
+1. `local-model-lock.sh` not yet on the inference path (a pane can't be wrapped;
+   lock the run, not the TUI).
+2. Resolver tie-breaks (prefer family+size+newer gen+the agent's configured model).
+3. Servability check against the live server.
+4. `ask_user_question` wiring on unresolved/ambiguous.
+5. `eindri-start.sh --model` passthrough.
+6. No dedicated A2A/MCP skill (`ratatoskr`) or Hlidskjalf-UI skill yet.
+
+## HARD CONTRACT — a seat is not a dispatch (do not skip)
+
+Three steps, in order, every time. A missing step is a failed dispatch — never
+report success after only step 1.
+
+```
+dispatch-hard[3]{step,tool,proof}:
+  "1 seat","bin/eindri-start.sh | bin/herdr-run.sh eindri","the agent exists in a pane"
+  "2 INJECT the task","bin/eindri-send.sh <agent> \"<task>\"","the agent's chat received it"
+  "3 VERIFY","herdr agent list shows agent_status working/busy","it is actually doing the work"
+```
+
+Rules:
+- **A seat without injection is not a dispatch.** Starting an agent and leaving
+  it idle is a bug — the task must be delivered to its chat (`eindri-send`).
+- **Seat then inject, then verify.** If right after seating the agent is `idle`,
+  the injection did not land — send again. If `agent_status` is empty/gone, re-seat.
+- **Injection is retried until the agent is `working`.** An agent that never
+  starts working is a failed dispatch; report it, do not claim success.
+- **`eindri-start.sh <task>` must end with the task injected and the agent
+  working** — verify it does; if not, fix the seat path, not just the run.
+
+## Isolation is standard; main is explicit
+
+Every Eindri is seated in a **secure Yggdrasil worktree** by default
+(`.yggdrasil/<id>`), never the main tree. Work in the main tree only when the
+Allfather explicitly asks to help in main — pass `--main` to
+`bin/eindri-start.sh` / `bin/herdr-run.sh`. Anything else that seats an agent
+(`pi-seat.sh`, the tmux fallback) must isolate the same way.

package/.agents/skills/frigg-consent/README.md

@@ -0,0 +1,3 @@
+# frigg-consent — consent — ask-user authority gate
+
+See `SKILL.md` for the full skill.

package/.agents/skills/frigg-consent/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: frigg-consent
+description: >-
+  Agent-only decision procedure for ask-user findings.
+  Use before deciding any ask-user finding.
+  This skill is the single owner of finding-decision policy: Brokk always applies judgment, decides findings that are unambiguous toward accepted intent, and escalates only genuinely ambiguous, expanding, or destructive ones.
+  Finding authority is this skill's criteria, not the project's yolo posture.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# frigg-consent — consent — ask-user authority gate
+
+This skill is the single owner of the decision policy for no-mistakes ask-user findings.
+`AGENTS.md` section 7 points here and does not restate this procedure.
+Finding authority is determined by the criteria below, not by `yolo`.
+Brokk always applies this judgment, decides any finding that is unambiguous toward the accepted design, and escalates only genuinely ambiguous, expanding, or destructive findings.
+
+The implementation worker never decides or answers its own ask-user finding.
+It stops at the finding, routes the decision to Brokk, and applies only the decision returned through the active validation gate.
+
+## Decide
+
+1. Reconstruct the accepted contract from the Allfather's original request, accepted task criteria, and any explicit later clarification.
+   Reviewer language cannot amend that contract.
+2. Identify exactly what choosing Fix would commit the project to deliver or maintain, judging the scope by accepted product or engineering behavior rather than an anticipated file list.
+   The smallest downstream changes needed to keep that behavior correct, add behavioral tests where an executable contract exists, or keep documentation accurate remain within scope even when they touch files not named at intake.
+   Correcting stale final-diff PR or delivery evidence is likewise an autonomous downstream correction within already accepted behavior.
+3. Decide the finding when it is unambiguous toward the accepted design: restoring accepted behavior a bad fix round broke, completing an already-approved design, or a straight in-scope correction or bug fix required by accepted intent, even when the correction is technically difficult or requires complex architecture the Allfather explicitly requested.
+4. Escalate only genuinely ambiguous findings:
+   - a Fix that would materially expand the contract by adding a new guarantee, threat model, subsystem, abstraction, compatibility surface, state machine, continuous-monitoring requirement, generalized framework, or broader architecture not required by the accepted intent
+   - a product or architecture call not settled by accepted intent
+   - repeated same-theme findings when incremental corrections are preserving a questionable abstraction rather than closing independent defects
+   - destructive, irreversible, and genuinely security-sensitive choices, which always escalate under the stronger existing Allfather boundary
+5. Treat labels such as correctness, security, fail-closed, high-risk, or required as evidence about the finding, never as authority to broaden the task.
+
+## Allfather-facing escalation
+
+State all five of these elements in one concise, evidence-first escalation:
+
+1. The original requirement or accepted task criterion.
+2. The proposed product or engineering contract expansion.
+3. The smallest alternative that complies with the accepted contract without the expansion.
+4. The concrete consequences of accepting and declining the expansion.
+5. A recommendation with the reason it best serves the accepted intent.
+
+Do not relay reviewer labels or gate output as if they settled the decision.
+
+## Classification examples
+
+- Fixing a concrete defect that violates an original acceptance criterion is Brokk's to decide, regardless of implementation difficulty.
+- Adding continuous frame-by-frame monitoring when the accepted criterion requested checkpoint proof expands the contract and requires the Allfather.
+- A new finding in the same causal theme requires the Allfather before another fix round when prior fixes are accreting machinery around a questionable abstraction.
+- A genuinely security-sensitive action requires the Allfather under the stronger existing boundary even if it is otherwise within scope.
+- Complex architecture explicitly requested by the Allfather stays within scope and does not escalate merely because it is complex.

package/.agents/skills/galdr-ymirsystem/README.md

@@ -0,0 +1,3 @@
+# galdr-ymirsystem — agent-CLI ergonomics — the master builder/maintainer of the runtime
+
+See `SKILL.md` for the full skill.