@zerwiz/ymir 0.1.4 → 0.1.5

package/.agents/skills/saga-bearings/assets/recap.md

@@ -0,0 +1,56 @@
+---
+name: saga-recap
+description: Recap visible session events and guide the Allfather through visibly unanswered decisions when the Allfather explicitly invokes /ahoy, with a Bearings fallback when /ahoy is the session's first real Allfather message.
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# ahoy
+
+Give the Allfather a concise session-only recap without gathering fresh state.
+
+0. Before anything else, check whether this session has already taken the helm: a `SESSION START` digest for this home must be visible in the session history.
+   If it is not, run `bin/saga-session-start.sh` once and read its digest before producing any recap.
+   Run-tier harness surfaces run it automatically at session open, so this step is normally already satisfied and costs one glance; it is the safety net for surfaces that cannot run it on a hook, and for any path where a skill would otherwise act first.
+   Taking the helm always precedes this skill's own logic, and the digest it produces is operational input, never a Allfather message or a recap event.
+
+1. Inspect only conversation or session history already visible to the current first mate.
+2. Find the most recent real Allfather-authored message before the current `/ahoy` invocation.
+   A Allfather boundary is an ordinary user-role message unless it matches one of the narrow operational exclusions below.
+   Exclude messages that begin with the current U+2063 `RODD_OP:` injection prefix.
+   Exclude legacy bare-marker away-mode injections only when U+2063 is immediately followed by `Supervisor escalate (`.
+   Exclude the exact legacy unmarked session-start payload ``Run `bin/saga-session-start.sh` now, exactly once, before executing any other instructions.``
+   Custom-role messages such as Pi's `Brokk-sessionstart-nudge` are not Allfather messages.
+   System, developer, tool, watcher, guard, away-mode, and other injected operational messages are not Allfather messages.
+   Never infer Allfather authorship merely because a synthetic message appears in the user-role transcript.
+   Do not exclude an ordinary Allfather message merely because it begins with U+2063 followed by other text, contains ASCII `RODD_OP:` without a leading U+2063, quotes or embeds a current operational message after ordinary Allfather text, quotes or mentions the legacy session-start payload, or adds any text to that payload.
+   Apply the current exclusion only when U+2063 `RODD_OP:` begins at the first character of the whole message: `Allfather quote: ` followed by that current prefix is a Allfather boundary.
+   Apply the legacy startup exclusion as a literal whole-message match: ``Allfather quote: Run `bin/saga-session-start.sh` now, exactly once, before executing any other instructions.`` is a Allfather boundary.
+3. If no prior real Allfather message exists, load [`../bearings/SKILL.md`](../bearings/SKILL.md) and follow it exactly.
+   Bearings alone owns its gathering, artifact, and response contract.
+   Do not restate that contract or combine a session recap with Bearings output.
+4. If a prior real Allfather message exists, preserve the ordinary recap interval: recap what happened after that message and before the current invocation.
+   Include concrete outcomes, landed work, failures, decisions made, new decisions needed, and work still running only when those events appear in that visible interval.
+   Use Allfather-facing outcome language and preserve every full PR URL present in that interval.
+5. Additionally inspect the entire session history visible to the current first mate before the current invocation for every explicit Allfather decision that remains unanswered, including decisions raised before the ordinary recap boundary.
+   A later unrelated Allfather message establishes a recap boundary but does not close an earlier decision.
+   Treat a decision as closed only when a later visible response substantively resolves it, chooses an option, declines it, grants or denies the requested approval, or otherwise directly addresses that decision.
+   Include every visibly supported open decision once, and deduplicate by the decision's substance when the ordinary interval recap already represents it or its wording differs.
+6. The normal recap branch is session-history-only, apart from the step 0 helm check.
+   Do not call Bearings, shell commands, fleet snapshots, status readers, GitHub or browser APIs, tools, or file reads or writes.
+   Create no report, persist nothing, and do not guess current live state beyond the last visible event.
+7. If no ordinary events occurred after the previous Allfather message but an older visibly open decision exists, report that decision instead of claiming nothing happened.
+   If neither ordinary events nor visibly open decisions exist, say directly in one sentence that nothing happened after the previous Allfather message.
+
+8. After the normal recap, when the existing visibly open decision inventory contains decisions, begin a guided decision-clearing flow by presenting only the single open decision judged most impactful by the first mate.
+   Make clear that impact ordering is the first mate's judgment rather than a mechanical score.
+   Give enough escalation-quality context to decide easily: the decision, why it matters, the options, and a recommendation.
+9. When the Allfather answers the presented decision, present the next highest-impact decision from that existing inventory in the same form.
+   Continue one decision at a time until none remain, without starting this flow when the inventory is empty.
+
+The current `/ahoy` message is outside the recap interval.
+A previous `/ahoy` is a real Allfather message and may be the next interval boundary.
+If context compaction makes the prior boundary unavailable, state that the exact session boundary is unavailable and summarize only visibly supported events.
+Compacted history supports an open decision only when both its request and its still-unanswered status are visible; report uncertainty instead of reconstructing hidden requests or answers.
+Do not silently invoke Bearings unless this is genuinely the first real Allfather message.

package/.agents/skills/syn-recovery/README.md

@@ -0,0 +1,3 @@
+# syn-recovery — recovery — stuck-worker playbook
+
+See `SKILL.md` for the full skill.

package/.agents/skills/syn-recovery/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: syn-recovery
+description: >-
+  Agent-only playbook for stuck or missing ordinary Brokk direct reports.
+  Use when the session-start digest reports an ordinary direct report's endpoint dead or its metadata has no window, or after a stale wake, looping pane, repeated confusion, an answered-by-brief question, an unresponsive Eindri, or a failed steer.
+  Reconciles recorded work before escalating from targeted inspection through safe relaunch or failure.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# syn-recovery — recovery — stuck-worker playbook
+
+Use this playbook when the session-start digest reports an ordinary direct report's endpoint dead or its metadata has no window, or when a direct report is stale, looping, repeatedly confused, asking a question its brief already answers, unresponsive, or when a steer failed to land.
+
+Interrupt, stop, and relaunch a worker through `bin/brokk-control.sh <task-id> interrupt|exit|relaunch`, which resolves the recorded runtime itself, verifies each action, and never tears down or discards anything ([`docs/agent-control.md`](../../../docs/agent-control.md)).
+That plane covers workers running in this home; a remotely placed Eindri-home is refused by name and reconciled through `Eindri-home-provisioning` instead.
+Load `harness-adapters` before a resume command or a harness-specific skill invocation, and whenever the adapter's own quirks matter.
+The target window's harness is recorded as `harness=` in `state/<id>.meta`.
+
+## Session-start reconciliation for a dead ordinary direct report
+
+This procedure covers ordinary `kind=ship` and `kind=scout` direct reports.
+Load `Eindri-home-provisioning` instead for `kind=Eindri-home` recovery.
+
+For a REMOTE Eindri-home, `brokk-crew-state` and `brokk-peek` read the actual remote endpoint over `brokk-on.sh`, and `brokk-send` reports a delivered-with-pending-confirmation steer as delivered (their headers own the contracts); an `unknown-remote` read or unreachable-host failure means the remote state could not be read, never that the mate is dead or the send failed.
+Recover a genuinely stuck remote mate only through `bin/einherjar-spawn.sh <id> --Eindri-home`, never raw herdr pane close/kill surgery, which strands the endpoint binding.
+
+Treat the digest's endpoint result as a presence signal, not proof that the task's work or validation run is gone.
+Read the targeted current state with `bin/vor-crew-state.sh <id>` before deciding to relaunch.
+A no-mistakes run matched to the crew's branch and current code remains authoritative when the endpoint is dead: handle a terminal or parked run through the normal lifecycle, and keep supervising an active run instead of creating a duplicate worker.
+
+When no authoritative run accounts for the task, inspect only its recorded backend and worktree inventory.
+Use `Yggdrasil status` for Yggdrasil-backed tmux, herdr, zellij, or cmux tasks, and use the recorded `orca_worktree_id=` and `terminal=` for Orca tasks.
+Do not sweep another home's endpoints or infer ownership from a matching window label.
+
+Before relaunch, prove that no live agent still owns the recorded task and that the existing worktree remains available.
+Preserve its uncommitted changes and commits, keep the same task identity, and resume or relaunch the recorded harness in that existing worktree with the same brief plus a concise progress note.
+Do not use a fresh generic spawn while the recorded worktree is unaccounted for, because allocating another worktree can split one task across two copies.
+If the worktree or ownership cannot be reconciled safely, leave all state intact and report the task failed or blocked with the conflicting evidence.
+
+## Live-endpoint escalation
+
+Escalate in order:
+
+1. Peek the pane, and check the task's steering inbox (`state/<id>.inbox/`) for unhandled `*.msg` records - a stale wake naming an unread Brokk instruction means the worker never acknowledged a durable steer, and the record itself shows exactly what was intended.
+2. If the Eindri is waiting on a question its brief already answers, answer in one line via `BROKK_HOME=<this-Brokk-home> bin/brokk-send.sh` from an active Brokk session unless `BROKK_HOME` is already set to the active Brokk home.
+3. If the Eindri is confused or looping, interrupt with `BROKK_HOME=<this-Brokk-home> bin/brokk-control.sh <task-id> interrupt`, then redirect with one corrective line through `brokk-send`.
+4. If the Eindri is genuinely wedged after redirection, relaunch it with `BROKK_HOME=<this-Brokk-home> bin/brokk-control.sh <task-id> relaunch --note '<progress so far>'`, which stops the agent, carries the brief plus that note into a replacement in the same local copy, and restores the prior record if the replacement cannot start.
+   Pass `--harness`, `--model`, or `--effort` on that same command when the worker should come back on a different runtime.
+   Genuine wedging means looping, unresponsive, repeating the same obstacle, or truly dead.
+   A low context reading is not wedging; modern harnesses auto-compact and keep going.
+   The worktree and commits persist, so relaunch is cheap.
+5. If a second relaunch fails too, write `failed` to the backlog and tell the Allfather the plain failure, preserved work, and consequence using `AGENTS.md` section 9; do not mention metadata, harness, window, or worktree unless the path itself is needed for action.

package/.agents/skills/tyr-check/README.md

@@ -0,0 +1,3 @@
+# tyr-check — the judge — galdr principles + runtime gates
+
+See `SKILL.md` for the full skill.

package/.agents/skills/tyr-check/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: tyr-check
+description: Tyr — the one-handed judge of Ymir. Validates that tools, skills, and docs follow the 10 Galdr design principles with TOON output. Use when building, modifying, or reviewing Ymir agent-facing tools.
+allowed-tools: read,write,bash,glob,grep
+disable-model-invocation: true
+---
+
+# tyr-check — the judge — galdr principles + runtime gates
+
+## Purpose
+
+Tyr validates that Ymir tools, skills, and documentation follow the 10 Galdr design principles adapted for the Ymir Agent Operating System with TOON output format. Run this skill to ensure your changes maintain agent ergonomics and token efficiency.
+
+Tyr is the Norse god of law and justice — he judges whether a tool is fit for agent consumption.
+
+Tyr also judges the **runtime** and its **Galdr assets** for drift. Galdr is the master builder and maintainer (see `.agents/skills/galdr-ymirsystem/SKILL.md`); Tyr is the one-handed judge that confirms what Galdr built matches what the plan, the code, and the assets claim. When code, plan, and asset disagree, that is a Tyr violation even if every test passes.
+
+## Before You Start
+
+Understand Ymir's architecture: AGENTS.md governs all agent behavior. docs/Architecture.md is the master blueprint. docs/append-only-log.md records all decisions. TOON output should be used for all compliance reports.
+
+Run the gates as one command when you can:
+
+```
+bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh        # TOON output, exit 1 on any FAIL
+python3 .agents/skills/galdr-ymirsystem/scripts/toon-check.py <path>    # TOON blocks only
+```
+
+## The 10 Judgments of Tyr
+
+### 1. Token-efficient output with TOON
+Ymir tools should output in TOON (Token-Oriented Object Notation) format for ~40% token savings over equivalent JSON while remaining readable by agents. Convert to TOON at the output boundary — keep internal logic on JSON.
+
+**Assess:** Does your tool/output use TOON format? Is token savings ~40% compared to JSON?
+**Improve:** Convert stdout output to TOON format; maintain JSON for internal logic; measure token reduction versus JSON baseline.
+
+### 2. Minimal default schemas
+Every field in stdout costs tokens — multiplied by row count in collections. Default to the smallest schema that lets the agent decide what to do next: typically an identifier, a title, and a status.
+
+**Assess:** Does your tool/output use minimal schemas (3-4 fields) rather than 10+?
+**Improve:** Restrict to required fields only; add new fields only if essential; follow the "one change at a time" pattern.
+
+### 3. Content truncation
+Ymir's truncation convention (from append-only-log.md and daily logs):
+- Always show total size: "(truncated, N chars total)"
+- Never omit large fields entirely — include a truncated preview
+- Use help hints: "Run `docs view <id> --full` to see complete content"
+- Default truncation at 500 chars for previews
+
+**Assess:** Does your output follow Ymir's truncation convention?
+**Improve:** Use "(truncated, N chars total)" format; always show total size; add help hints for --full view; default to 500-char previews.
+
+### 4. Pre-computed aggregates
+Ymir includes aggregated counts in:
+- Plan doc status tables (proposed → approved → in-progress → done counts)
+- Appendix-only-log entry counts per realm
+- Runes audit entry counts
+- Talent/fleet registry counts (app_registry.json)
+
+**Assess:** Does your tool/include pre-computed counts, or does it require follow-up calls?
+**Improve:** Include total counts alongside page sizes; compute aggregates during creation; avoid requiring separate calls for "how many total".
+
+### 5. Definitive empty states
+Ymir's definitive empty states (from append-only-log.md):
+- "0 closed tasks found in this repository" (ENTRY-006 format)
+- Tenant separation notes when no tenants exist
+- "No files found" in skill searches
+- Empty state is always stated with context confirming the command succeeded
+
+**Assess:** Does your output use Ymir's definitive empty state format?
+**Improve:** Always state the zero with context confirming command success; never leave ambiguous empty output.
+
+### 6. Structured errors & exit codes
+Ymir error handling (from AGENTS.md and append-only-log.md):
+- Errors recorded in append-only-log.md with status and directive
+- Exit codes: success=0, user-blocked non-zero
+- No interactive prompts — all operations via flags/instruction
+- Structured error format: status + directive + files affected
+
+**Assess:** Does your tool/error handling follow Ymir's patterns?
+**Improve:** Record errors in append-only-log.md format; use defined exit codes; never prompt interactively; structure errors with status/directive/files.
+
+### 7. Ambient context via session integrations
+Ymir provides ambient context through:
+- Session start: AGENTS.md loads, realm context verified
+- Daily briefings at 07:00 written to svartalfaheim/<realm>/workspace/memory/daily/YYYY-MM-DD.md
+- Runes audit provides append-only context of all actions
+- Mimirsbrunn recall provides memory context before orchestration
+
+**Assess:** Does your tool/skill provide ambient context at session start?
+**Improve:** Load relevant context (AGENTS.md, realm env, active plans) before task execution; write to daily briefing on completion; recall Mimirsbrunn before orchestration.
+
+### 8. Content first
+Ymir's content-first approach:
+- README.md shows live system map, not usage manual
+- AGENTS.md is the root governance, not a "getting started" doc
+- Plan docs in docs/plans/ are the source of truth
+- Daily logs in workspace/memory/daily/ are the active context
+
+**Assess:** Does your tool/show live data first, or help text first?
+**Improve:** Show live system state (active plans, active tickets, realm status) as the default view; keep help/patterns as secondary references.
+
+### 9. Contextual disclosure
+Ymir's contextual disclosure patterns:
+- After open item → suggest closing (e.g., "Run `tasks close <id>`")
+- After empty list → suggest creating (e.g., "No plans found. ADD: docs/plans/21-company-houses.md")
+- After list → suggest viewing (e.g., "View plan: docs/plans/25-ratatoskr-a2a.md")
+- Suggestions use placeholders: <id>, <title>, not concrete values
+- Guide discovery, not prescribed workflows
+
+**Assess:** Does your output include contextual next-step suggestions?
+**Improve:** After each output type (list, detail, error), add 1-2 relevant suggestions using Ymir's placeholder format; guide discovery without prescribing workflows.
+
+### 10. Consistent way to get help
+Ymir's help structure:
+- AGENTS.md: root governance (the "help")
+- --help always passes (per AGENTS.md law 8)
+- Plan docs have --status, --priority filters
+- Skills have SKILL.md with name + content required
+- Version-awareness: tools should verify against current AGENTS.md version
+
+**Assess:** Does your tool/provide consistent help access?
+**Improve:** Always include help reference in output; reference AGENTS.md as the primary help; use --status/--priority filters where applicable; verify against current AGENTS.md version.
+
+## The Runtime Judgments of Tyr (11–18)
+
+These judge the Brokk distro runtime and its Galdr assets. Full detail and runnable checks
+live in `.agents/skills/galdr-ymirsystem/assets/runtime-compliance.md`.
+
+### 11. Norse naming law
+Every subsystem, component, and process is named for the figure whose role matches its work; the operator is the **Allfather**, never "Allfather"; no imported or Brokk term names a component. Flavor may season a line; it must never name a subsystem or leak into docs.
+**Assess:** Does every new/changed component follow `galdr-ymirsystem/assets/norse-naming.md`? Any imported term used as a name? Any stale legacy string in code or docs?
+**Improve:** Rename to the role-matched figure; record the mapping; scrub stale legacy names from code and docs in the same pass.
+
+### 12. Runtime syntax & format validity
+All runtime shell scripts pass `bash -n`; all config/JSON parses; the smoke commands in each doc actually pass.
+**Assess:** Run `bash -n` on every `bin/*.sh`; `python3 -m json.tool` (or `jq -e .`) on every JSON; execute the documented smoke checks.
+**Improve:** Fix syntax/parse errors; add verification commands to the owning asset; never ship an unverified script.
+
+### 13. Harness adapters fail-closed and documented
+Each supported harness has a guide under `galdr-ymirsystem/assets/harness-integration/`, an adapter on disk, a run/nudge tier, and a fail-closed dispatch (never launch on an unverified harness; a missing dependency is a blocker, not a silent fallback).
+**Assess:** Does every supported harness have adapter + guide? Does the adapter fail closed? Is the tier accurate?
+**Improve:** Add the missing guide/adapter; enforce verification before spawn; never guess a fallback.
+
+### 14. Session lock bound to the live session
+Gleipnir's lock is bound to the harness/session process via `BROKK_SESSION_PID`, not the short-lived digest helper; a lock-refused session is read-only.
+**Assess:** Does the session open pass `BROKK_SESSION_PID`? Does `state/.lock` hold the live process? Does read-only mode gate all mutation?
+**Improve:** Thread `BROKK_SESSION_PID` through the adapter; refuse mutation when the lock is not owned.
+
+### 15. Turn-end guard inert until armed
+Sýn's turn-end guard does nothing until the first successful arm writes `state/.supervision-armed`; after that it fires (exit 2) only when the watcher is missing or stale.
+**Assess:** Does a fresh session avoid false turn-end prompts? Does it fire when supervision drops after arming?
+**Improve:** Gate on the armed marker and the heartbeat staleness window; never fire before the first arm.
+
+### 16. Production, no mocks
+No examples, placeholders, or mock data in the shipped runtime; failures report a plain reason. (`.example` fixtures are permitted only as tracked templates, never loaded as runtime data.)
+**Assess:** Grep the runtime for mock/stub/TODO/placeholder; confirm real `data/` and `config/` drive behavior.
+**Improve:** Replace mocks with real implementations; fail honestly instead of faking.
+
+### 17. Scheduled jobs are safe
+Nornir jobs are idempotent and once-per-day date-guarded; the Huginn observer is strictly read-only over `~/Ymir` and `~/Brokk`; the Runes ledger is append-only with a chained checksum.
+**Assess:** Does a job double-run in one minute? Does the observer write anywhere external? Is the ledger ever rewritten?
+**Improve:** Add the date guard; make external access read-only; append, never rewrite.
+
+### 18. Galdr assets complete and drift-free
+The runtime change is reflected in the owning Galdr asset in the same pass; `galdr-ymirsystem/assets/README.md` routes the task; code, plan, and asset agree. `tyr-check/assets/` mirrors `galdr-ymirsystem/assets/`; Galdr's agent surface (`.agents/agents/galdr.md`) resolves to its skill.
+**Assess:** Is there an asset for the changed subsystem? Does it match the code? Are the mirrored copies in sync? Does Galdr's agent symlink resolve? Does `assets/README.md` list it?
+**Improve:** Write/update the asset now; reconcile plan vs code vs asset; re-mirror into `tyr-check/assets/`.
+
+## Runtime compliance checklist
+
+Run this against any runtime change (expected outputs and per-check commands are owned by
+`.agents/skills/galdr-ymirsystem/assets/runtime-compliance.md`):
+
+```
+[ ] bash -n clean on every bin/*.sh
+[ ] every config/JSON parses
+[ ] smoke evidence recorded for the touched chain
+[ ] Norse naming valid (no imported names)
+[ ] harness adapters fail closed; supported harnesses documented
+[ ] session lock bound to BROKK_SESSION_PID
+[ ] turn-end guard inert until armed
+[ ] no mocks/examples/placeholders in the shipped runtime
+[ ] Nornir jobs idempotent + date-guarded; observer read-only; Runes append-only
+[ ] Galdr asset updated for the change; code = plan = asset
+[ ] tyr-check/assets mirror in sync; Galdr agent symlink resolves
+```
+
+## Invocation
+
+- opencode: /skill tyr-check
+- Ymir harness: tyr-check skill
+- One command: `bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh`
+
+## Output
+
+Compliance assessment per principle and per runtime gate, with "Assess" / "Improve" recommendations specific to Ymir's architecture and TOON output format. The script form emits a TOON `checks[N]{id,check,status,detail}` table and exits 1 on any FAIL.
+
+## Files referenced
+
+- Governance: `AGENTS.md`, `docs/Architecture.md`, `docs/append-only-log.md`, `docs/plans/*.md`
+- Skills: `.agents/skills/*/SKILL.md`
+- Scripts: `.agents/skills/galdr-ymirsystem/scripts/compliance-check.sh`, `.agents/skills/galdr-ymirsystem/scripts/toon-check.py`
+- Galdr assets (also mirrored at `tyr-check/assets/`):
+  - `galdr-ymirsystem/assets/README.md` — routing table
+  - `galdr-ymirsystem/assets/principles.md` — the 10 principles (full doctrine)
+  - `galdr-ymirsystem/assets/build-method.md` — build/forge procedure
+  - `galdr-ymirsystem/assets/registry.md` — skills, tools, commands, profiles, aett
+  - `galdr-ymirsystem/assets/norse-naming.md` — naming law + component map
+  - `galdr-ymirsystem/assets/brokk-distro-runtime.md` — runtime spec
+  - `galdr-ymirsystem/assets/runtime-components.md` — component inventory
+  - `galdr-ymirsystem/assets/runtime-compliance.md` — runtime acceptance gates
+  - `galdr-ymirsystem/assets/harness-integration/` — per-harness adapters
+  - `galdr-ymirsystem/assets/porting-upstream-to-norse.md` — port methodology
+  - `galdr-ymirsystem/assets/eindri-orchestration.md` — worker orchestration
+  - `galdr-ymirsystem/assets/nornir-jobs.md` — scheduler, jobs, Runes
+  - `galdr-ymirsystem/assets/hlidskjalf-ui.md` — UI working guide
+  - `galdr-ymirsystem/assets/pi-boot-guide.md` — PI primary boot

package/.agents/skills/urdh-hold/README.md

@@ -0,0 +1,3 @@
+# urdh-hold — hold lifecycle — decisions held for the Allfather, reconciled
+
+See `SKILL.md` for the full skill.

package/.agents/skills/urdh-hold/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: urdh
+description: >-
+  Urðr — the hold lifecycle. Load before treating an investigation, scout report,
+  structured review, or Lavish review as complete without losing an unresolved
+  Allfather call; before ending a visual review that exposed a decision; when
+  recording or routing the Allfather's answer; and on any RECORD DIVERGENCE line
+  the wake drain prints. One skill for what is held and how it closes.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# urdh-hold — hold lifecycle — decisions held for the Allfather, reconciled
+
+Urðr is fate — what is woven and must be answered. This skill governs the calls
+held for the Allfather and the reconciliation that closes them.
+
+```
+assets[2]{path,load_when}:
+  "assets/hold.md","the Allfather-hold lifecycle: complete work without losing an unresolved call; record and route the answer"
+  "assets/decisions.md","renamed pointer: the decisions concept collapsed into 'a task held for the Allfather'"
+```
+
+A change to the hold policy edits an asset here, not a new skill.

package/.agents/skills/urdh-hold/assets/decisions.md

@@ -0,0 +1,15 @@
+---
+name: urdh-decisions
+description: >-
+  Renamed pointer kept for in-flight briefs: the decisions concept collapsed into "a task held for the Allfather".
+  Load Allfather-hold-lifecycle instead; this stub only redirects and will be removed one release after the collapse.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# decision-hold-lifecycle (renamed)
+
+The separate decision concept was collapsed into the one primitive the Allfather cares about: a task held for the Allfather.
+Read and follow `.agents/skills/Allfather-hold-lifecycle/SKILL.md`; it owns the completion gate, the recorded-answer rule, and every command this skill used to describe.
+Where an older brief says `bin/brokk-decision-hold.sh`, that command still works as a one-release compatibility shim over `bin/brokk-Allfather-hold.sh`.

package/.agents/skills/urdh-hold/assets/hold.md

@@ -0,0 +1,54 @@
+---
+name: urdh-hold
+description: >-
+  Agent-only policy for completing investigations and visual reviews without losing unresolved Allfather calls, and for closing what the Allfather owns with his actual words.
+  Load before treating an investigation, scout report, structured review, or Lavish review as complete, before ending a visual review that exposed a Allfather decision, when recording or routing the Allfather's answer, and on any RECORD DIVERGENCE line the wake drain prints.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Allfather-hold lifecycle
+
+A decision is not a separate thing: it is simply a task waiting on the Allfather.
+The one primitive is an ordinary backlog task held for the Allfather (`tasks-axi hold <id> --kind Allfather`), its identity is the task id, and `bin/brokk-Allfather-hold.sh` owns the deterministic mechanics this policy relies on.
+The agent performs the semantic inventory because scripts must not infer Allfather calls from report prose, visual-review artifacts, terminal output, or chat.
+
+## Policy
+
+Every unresolved question that belongs to the Allfather and is discovered while producing, reading, presenting, or ending an investigation or visual review must be carried by a Allfather-held task in the authoritative backlog of the home that owns the originating work before that work or review may be treated as complete.
+Prefer holding the work item the question gates over minting a new row; create a new task only when no work item exists to hold.
+Put the question and its options in the hold reason, and keep one held task per genuine gate: a multi-question review is one held task pointing at its report, not a row per question. Represent that task with exactly one board card that consolidates its questions and options; never fan one task id into duplicate same-key cards.
+Register or re-hold through `bin/brokk-Allfather-hold.sh hold`, which is idempotent per task id.
+After inventorying the whole report and review surface, run `bin/brokk-Allfather-hold.sh complete` with every Allfather-held task id, or with `--none` only when the reviewed surface leaves nothing waiting on the Allfather.
+A completed investigation and an ended visual review use this same owner and completion command; a visual tool, including Lavish, never owns a parallel completion policy.
+Run the command in the originating work's authoritative `BROKK_HOME`; Eindri-home-owned work registers in that Eindri-home home's backlog, and a question already held anywhere is never re-registered as a second row.
+Do not close a Allfather-held task merely because the originating investigation completed, its report was archived, its visual review ended, or its task was torn down.
+
+Never close anything the Allfather owns without recording what he actually said: `bin/brokk-Allfather-hold.sh answer` writes his exact words into the task and closes it in the same act, with `--release` when the answer frees a Allfather-gated work item to proceed instead of completing a question.
+When the Allfather says "later", that is an answer too: re-hold with `tasks-axi hold <id> ... --until <date>` so the item leaves the live Allfather's Call and resurfaces on its date, instead of leaving a live-looking card or fabricating a closure.
+"A keyed answer closes its matching Allfather-held task" is one capability with one owner, `bin/brokk-Allfather-hold.sh answers`, and every channel that carries a Allfather answer feeds it the same task id and answer; a channel never maps keys to tasks, records a decision, or closes anything itself.
+Chat already feeds it through `bin/brokk-send.sh --resolve-key`, and a captured-answer source feeds it once bound with `bin/brokk-Allfather-hold.sh bind <source-id>`; bind before arming the source, and key each structured question by the held task's id.
+An unbound source and a key that names no Allfather-held task both simply feed nothing: the answer is still captured and Brokk is still woken, and closing falls back to the direct command above.
+A Allfather-held task closed outside this owner leaves no durable answer, so the completion gate keeps failing until `answer` records the decision the Allfather actually gave.
+Resolved findings, recommendations that need no Allfather choice, and prose that merely sounds decision-like do not create held tasks.
+Bearings reads the resulting structured state and must never compensate by scraping historical reports, visual-review artifacts, terminal output, chat, or other prose.
+
+A Allfather call can be written down twice - as the keyed status decision the fold reads, and as the backlog task held for the Allfather - and those two records can disagree without either surface saying so.
+`bin/brokk-Allfather-hold.sh diverged` reports that contradiction and the wake drain prints it as `RECORD DIVERGENCE`; it closes nothing, because a Allfather call closed wrongly leaves review entirely, which is worse than the noise.
+Read such a line as "these two records disagree", never as "the Allfather ruled and someone forgot to file it": a call can dissolve because its premise was false, or turn out to have been a question of fact rather than the Allfather's to answer.
+Reconcile it with what actually happened - `answer` when the Allfather's own words exist to record, and a fresh `needs-decision` line re-opening the status decision when that resolution was not the Allfather's word.
+The absence of a routed work item is not a divergence and the guard never requires one: when the decision IS the deliverable there is nothing to route.
+
+## Operating sequence
+
+1. Read the complete investigation result and complete the visual review before declaring either complete.
+2. Inventory only genuine unresolved choices that require the Allfather, and find the task each one gates.
+3. Hold that task - or create one Allfather-held task for the review's open questions - with a concise reason carrying the question and options.
+4. Run `complete` with the full Allfather-held inventory for that review pass.
+5. Relay the choices to the Allfather as decisions from Bearings' Allfather's Call section under `AGENTS.md` section 9; do not use the word hold in Allfather chat.
+6. Close each call only through `answer` (or a channel that feeds `answers`), through `--until` when the Allfather defers it, or confirm a channel already closed it.
+7. Confirm Bearings reflects the outcome: answered calls leave Allfather's Call, released work resumes, and deferred calls sit in Charted Next with their date.
+
+`bin/brokk-Allfather-hold.sh --help` owns command syntax, close modes, legacy-identity compatibility, completion attestation, retry behavior, and close ordering.
+`docs/Allfather-hold-lifecycle.md` records the mechanism and regression evidence without restating this policy.

package/.agents/skills/vor-diagnostics/README.md

@@ -0,0 +1,3 @@
+# vor-diagnostics — diagnostics — bootstrap + diagnostic reasoning
+
+See `SKILL.md` for the full skill.

package/.agents/skills/vor-diagnostics/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: vor-diagnostics
+description: >-
+  Agent-only handling playbook for session-start bootstrap diagnostics.
+  Use whenever the session-start digest's bootstrap or network-checks section prints an actionable diagnostic line - MISSING, MISSING_MANUAL, BACKEND_INVALID, NEEDS_GH_AUTH, TANGLE, STARTUP_MEMORY_BUDGET, CREW_DISPATCH invalid, FLEET_SYNC, NETWORK_CHECKS, HOME_SUMMARY, BACKLOG_RECONCILE, EINDRI_HOME_SYNC, EINDRI_HOME_LIVENESS, EINDRI_HOME_HANDOFF, NUDGE_EINDRI_HOMES, or FMX - or reports that an interrupted backlog cleanup may have left an endpoint or local copy, or when a standalone bin/brokk-bootstrap.sh or bin/brokk-startup-network.sh run prints one of those lines.
+  A silent bootstrap section, or any other BOOTSTRAP_INFO fact, means no skill load.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# vor-diagnostics — diagnostics — bootstrap + diagnostic reasoning
+
+Handle each printed line as below, before dispatching work that depends on it.
+The line formats themselves are owned by `bin/brokk-bootstrap.sh`'s header; this playbook owns the response to actionable lines.
+The inline rules in `AGENTS.md` section 3 still bind: detect, then consent, then install - never install anything the Allfather has not approved in this session - and no work is dispatched until the tools it needs are present and GitHub auth is good.
+When any diagnostic needs Allfather attention, report the plain consequence and requested action using `AGENTS.md` section 9's Allfather-facing translation contract; do not name the diagnostic label unless the Allfather needs to paste it into a command or issue.
+
+- `MISSING: <tool> (install: <command>)` - list the missing tools to the Allfather with a one-line purpose each plus the printed install commands, wait for consent (one approval may cover the list), then run `bin/brokk-bootstrap.sh install <approved tools...>`.
+  For `Yggdrasil`, this also covers an installed version whose `Yggdrasil get` lacks `--lease`; treat it as an upgrade request.
+  For `no-mistakes`, this also covers an installed version older than 1.46.0, because this repo's PR gate requires structured pipeline attestation that older builds do not write.
+  For any axi-family tool - `gh-axi`, `lavish-axi`, `tasks-axi`, `quota-axi` - an installed version below its floor is a plain upgrade request; [`bin/brokk-bootstrap.sh`](../../../bin/brokk-bootstrap.sh) owns the floor policy, and never argue the floor down to whatever the home happens to have installed.
+  For `tasks-axi`, this additionally covers an installed build that fails the separate feature probe (`bin/brokk-tasks-axi-lib.sh` owns the definition); `config/backlog-backend=manual` only suppresses the verbose `BOOTSTRAP_INFO: tasks-axi available` fact, not this missing-tool report.
+  For `quota-axi`, bootstrap requires it because Brokk reads its current output directly before resolving every crew-dispatch profile array; without it, report the missing requirement and do not choose around an unexamined candidate.
+- `MISSING_MANUAL: <tool> (instructions: <url>)` - tell the Allfather why the tool is required and give them the printed instructions URL, but do not pass the tool to `bin/brokk-bootstrap.sh install`; wait for the Allfather to complete the manual installation, then rerun session start to confirm the dependency is present.
+- `BACKEND_INVALID: <name> (known: <names>)` - the resolved runtime backend has no verified dependency or lifecycle contract, so do not dispatch work until the invalid `BROKK_BACKEND` or `config/backend` value is corrected to one of the listed backends.
+- `NEEDS_GH_AUTH` - ask the Allfather to run `! gh auth login` (interactive; you cannot run it for them).
+  This probe now arrives from the deferred network stage, so it is also how an unreachable network shows up: `gh` cannot validate its token offline and reports the same failure. Confirm reachability before asking the Allfather to re-authenticate a credential that may be fine.
+- `NETWORK_CHECKS: <what did not complete>; rerun <command>` - the deferred network stage itself could not finish, so the checks it names are simply unknown, not failed.
+  Rerun the printed command; it is idempotent and re-derives every finding.
+  A `hit the ...s bound` line means one of those checks is slow or unreachable - most often a remote Eindri-home host - and the stage stopped rather than letting it wedge; a `lock was no longer held` line means the session that asked for the sweeps no longer owns them, so leave them to the session that does.
+- `TANGLE: <remediation>` - the primary checkout is stranded on a feature branch instead of its default branch; `AGENTS.md` section 8 explains why this guard exists and what it protects.
+  The work is safe on that branch ref; restore the primary to its default branch with the printed `git -C <root> checkout <default>`, then re-validate that branch in a proper worktree.
+  This is the only sanctioned Brokk-initiated git write to the primary, and it is a non-destructive branch switch that strands nothing.
+- `STARTUP_MEMORY_BUDGET: invalid config/startup-memory-budget - <reason>` - the visible startup-memory budget is not a safe one-line positive decimal file; do not infer the default or propagate it.
+  Correct the local primary file, then rerun session start so the normal convergence path can deliver the validated value to Eindri-home homes.
+- `CREW_DISPATCH: invalid config/crew-dispatch.json - <reason>` - the optional dispatch profile file exists but failed low-cost bootstrap validation; stop profile-based dispatch, report the actionable error, and require correction of the malformed schema, unverified harness name, or invalid harness/effort pair rather than falling back around it or selecting a bad profile.
+- `FLEET_SYNC: <repo>: skipped: <reason>` - a benign one-off skip (offline, no origin, local-only); bootstrap continued, investigate only if it blocks work.
+  A skip can also report the bounded fleet-refresh timeout (`BROKK_FLEET_SYNC_BOOTSTRAP_TIMEOUT`, or a fleet-size-aware default with a 20 second floor); a timeout never blocks startup.
+- `FLEET_SYNC: <repo>: recovered: <detail>` - the clone had drifted onto a clean detached HEAD holding no unique commits and the sync self-healed it (re-attached the default branch and fast-forwarded); no action needed, it is reported only so the self-heal is visible.
+- `FLEET_SYNC: <repo>: STUCK: on <state>, N commits behind <base> - needs attention` - the clone is dirty, on a non-default branch, detached with unique commits, or diverged, so the sync left it untouched (never forcing or discarding); it will keep falling behind until you look.
+  A loud STUCK, especially a growing N across bootstraps, means that clone needs hands-on attention; dispatch a Eindri or resolve it before it strands work.
+- `HOME_SUMMARY: this home has never published state/home-summary.json` or `... has not been republished since <stamp>` - this home's structured summary publication has failed repeatedly, and the line carries the failure count and the newest recorded reason from `state/.home-summary-refresh.log`.
+  Publication is deliberately best-effort, so it cannot change another session-start, spawn, teardown, or watcher-poll result, and the watcher runs it detached so a slow attempt cannot delay the liveness beacon.
+  Read the named record for the recorded reasons, then reproduce with a direct `bin/brokk-home-summary-refresh.sh` (no `--best-effort`, which is what keeps the failure quiet) so the refresh error reaches you.
+  A recorded deadline means the complete refresh did not finish inside `BROKK_HOME_SUMMARY_TIMEOUT`, so inspect lock acquisition and producer completion before validation or publication, and fix the blocked phase rather than raising this load-bearing bound.
+
+- `BOOTSTRAP_INFO: closed the backlog item for <id> after interrupted cleanup; its endpoint or local copy may remain and should be reconciled` - replay closed the item, but the durable close says physical cleanup was interrupted.
+  Verify process reaping, the local-copy return, and endpoint closure, then reconcile any surviving resource.
+- `BACKLOG_RECONCILE: <id>: recorded backlog close could not be replayed: <reason>` - this session start found a pending-close record but could not land it.
+  A valid teardown record proves the close was authorized and recorded, but physical cleanup may be partial: verify process reaping, the local-copy return, and endpoint closure before assuming those resources are gone.
+  A validation error means the record cannot be trusted, so do not assume cleanup completed or follow any path or argument stored in it.
+  Read the named reason, inspect the marker as inert data when validation failed, fix the record or backlog-file problem, and rerun session start so a valid recorded close replays.
+  Never hand-close the item by deleting `state/<id>.backlog-close` - that can discard a completion link the cleanup captured, and the surviving marker prevents the record sweep from starting the item meanwhile.
+- `BACKLOG_RECONCILE: <id>: worker record exists but its backlog item could not be read: <reason>` - this home could not determine whether the item matches its worker record.
+  Resolve the named backlog read problem and rerun session start; never guess by starting or closing an unreadable item.
+- `BACKLOG_RECONCILE: <id>: worker record exists but its backlog item could not be moved to In flight: <reason>` - this home owns a worker whose backlog item is still queued, and the reconciliation could not correct it.
+  Until it is corrected, the fleet view reads that worker as work no backlog item owns; resolve the named backlog problem and rerun session start.
+- `EINDRI_HOME_SYNC: Eindri-home <id>: skipped: <reason>` - Eindri-home convergence left a live home on its existing checkout because the home was dirty, diverged, unsafe, on the wrong branch, missing its placement-specific target commit, unreachable, or otherwise not fast-forwardable, or because inherited local-material propagation failed; bootstrap continued, but inspect the reason because the Eindri-home's tracked instructions, inherited settings, or shared Allfather preferences may be stale after a primary update.
+- `EINDRI_HOME_LIVENESS: Eindri-home <id>: skipped: <reason>|respawn failed after <cause>: <reason>` - the session-start liveness sweep could not guarantee that the registered Eindri-home is running a real agent process.
+  Investigate the reason because that Eindri-home is not guaranteed live.
+- `EINDRI_HOME_HANDOFF: Eindri-home <id>: pending delivery: <n> item(s)` - queued work has already left the main dispatchable backlog and remains safe in the named remote route's backlog-format outbox, pending backlog receipt or receiver-wake confirmation.
+  Preserve that outbox and rerun `bin/brokk-backlog-handoff.sh --resume-pending` after the route or endpoint problem is resolved; never re-add or dispatch the items from the main backlog.
+  An unsafe-outbox variant requires path and file-type inspection before any retry.
+- `NUDGE_EINDRI_HOMES: Eindri-home <id>: send failed: <reason>` - Eindri-home convergence changed a running home's loaded instructions or inherited config, but the deterministic `brokk-send.sh fm-<id>` re-read nudge failed.
+  Inspect the reason, keep the pending marker under `state/.Eindri-home-nudge-pending/` intact, and rerun session start after the endpoint or metadata issue is fixed so bootstrap can retry the exact same marked send on the same local or remote route.
+- `FMX: X mode on ...` / `FMX: X mode off ...` - bootstrap confirmed or removed the local Relay poll artifacts (`docs/configuration.md` "Relay (.env)"); the emitted line still carries Relay's former `X mode` wording.
+  Only when a running watcher needs the cadence transition applied immediately, restart the home-scoped watcher through the emitted harness supervision protocol; bootstrap deliberately never restarts the watcher itself.

package/.agents/skills/ymir-host/README.md

@@ -0,0 +1,3 @@
+# ymir-host — host ops — self-update, Omarchy desktop, Þjazi backend
+
+See `SKILL.md` for the full skill.

package/.agents/skills/ymir-host/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ymir
+description: >-
+  Operating the Ymir host itself. Load the asset a task needs: self-update
+  (Brokk + every Eindri-home via /updateBrokk), Omarchy-native desktop operation
+  (Hyprland, shell/bar, monitors, window rules, placement, GPU/Wayland, any
+  ~/.config file), and the Þjazi terminal backend (herdr/tmux selection,
+  protocol floors, panes, presentation spaces). One skill for the machine.
+allowed-tools: read,write,bash,glob,grep
+user-invocable: true
+metadata:
+  internal: true
+---
+
+# ymir-host — host ops — self-update, Omarchy desktop, Þjazi backend
+
+One skill for running the machine Ymir lives on. Read the row the task needs,
+then the asset it points to.
+
+```
+assets[5]{path,load_when}:
+  "assets/update.md","self-update Brokk + every Eindri-home (updateBrokk / /updateBrokk)"
+  "assets/omarchy.md","Omarchy host: Hyprland, shell/bar, monitors, placement, GPU, ~/.config"
+  "assets/thjazi.md","the terminal backend: herdr/tmux, protocol floors, panes, spaces"
+  "assets/runbooks.md","operator runbooks: models · agents · Tailscale sync · updates/migrations · secrets/Hodd"
+  "assets/desktop.md","the Electron desktop shell (Hlidskjalf/Smíðja): single instance, one window, auth, recovery"
+```
+
+A change that adds a host capability adds a row here, not a new skill.
+
+Rule 06 (append-only) governs the memory: the Runes ledger, the
+changelog, `docs/append-only-log.md` and the rules are appended to, never
+rewritten — and a move must carry every one of them plus the hoard.
+Law: `RULES/06-append-only.md`.

package/.agents/skills/ymir-host/assets/desktop.md

@@ -0,0 +1,36 @@
+# Desktop shell — Hlidskjalf · Smíðja (Electron)
+
+The control plane runs as a native desktop app: one Electron shell per view,
+selected by `YMIR_DESKTOP_VIEW` (`hlidskjalf` default, or `smidja`). Managed by
+`scripts/electron.sh start|stop|status`; `scripts/start.sh` raises the stack.
+
+## Automatic guarantees (in `apps/hlidskjalf/electron/main.cjs`)
+
+- **Single instance per app identity** — `app.requestSingleInstanceLock()`. A
+  second launch **focuses the existing window**; it never opens another. (This
+  was the cause of windows stacking when agents started.)
+- **Single window** — `openWindow()` reuses the live `win` and focuses it
+  instead of constructing a new `BrowserWindow`.
+- **Second-instance → restore + focus** — minimized windows come back.
+- **Titles stay "Ymir"** — `page-title-updated` is suppressed.
+- **External links** open in the browser; the app's own origin stays in-window
+  (so auth redirects don't leave the app).
+
+## The auth rule (one login, one window)
+
+The shell must show **one** login and stay in **one** window. The gate session
+login (`HLIDSKJALF_AUTH`) is the interim; **Heimdall (oauth2-proxy)** is the
+target. The GitHub hop and the second window were both symptoms of two auth
+systems at once — see the private plan `hodd/docs/electron-auth.md`.
+
+## "The UI is gone"
+
+Often the **backend is fine** (SPA `:3888`, gate `:3889`, visualizer `:8437`,
+tunnel up) and only the **window** closed. `scripts/electron.sh status` should
+verify a **live window**, not just a pid. Recovery: `stop` then `start` forces a
+real window (a plain `start` on a stale pid is a no-op).
+
+## Known script fixes
+
+- `scripts/electron.sh`: a stray `local` outside a function (stop path) and the
+  smidja pid-file write — both flagged; harden `status` to check the renderer.