@zerwiz/ymir 0.1.16 → 0.1.18

package/assets/reference/docs/agent-control.md

@@ -0,0 +1,122 @@
+# Agent lifecycle control plane
+
+Firstmate 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=secondmate` target it always prepends the from-firstmate routing marker, because a secondmate is itself a firstmate 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=secondmate` task re-resolves its durable `config/secondmate-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 a secondmate's runtime.
+   A ship or scout keeps the harness already recorded for it, because that harness comes from firstmate'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=secondmate` 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.
+   A secondmate's own crewmates run in their own endpoints and outlive its relaunch; the relaunched secondmate 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.
+   A secondmate 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 secondmate 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 secondmate 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 a crewmate and scout adapter only, so relaunching a secondmate onto it refuses while its agent is still up rather than leaving that secondmate 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/assets/reference/docs/apodex/Appdex_as_Orchestrator_Planner_Reviewer_Assessment.md

@@ -0,0 +1,176 @@
+# Would it be good to use Appdex as an orchestrator, planner, and reviewer?
+
+**Assessment of `Apodex` (the entity behind https://ymir.zerwiz.org) for the roles of orchestrator, planner, and reviewer**
+
+
+
+To wire Apodex's reasoning engine and orchestration code into the Ymir platform (ymir.zerwiz.org), you treat Apodex as the intelligence layer (the "brain" for Brokk or Kaia and the execution engine for Eindri workers) while letting Ymir's native substrate enforce memory, messaging, and safety gates.
+Here is the blueprint for how to structure that integration:
+Step 1: Spin Up and Validate the Local Apodex Endpoint
+Before touching Ymir's internal components, ensure your underlying Apodex model is served and responding correctly as an OpenAI-compatible endpoint:
+ * Use SGLang to serve your chosen open-weights model (e.g., apodex/Apodex-1.0-35B-A3B) with the required tool-calling and reasoning parsers:
+   python3 -m sglang.launch_server \
+  --model-path apodex/Apodex-1.0-35B-A3B \
+  --tp 1 \
+  --host 0.0.0.0 \
+  --port 1234 \
+  --context-length 262144 \
+  --tool-call-parser qwen3_coder \
+  --reasoning-parser qwen3
+
+ * Run a quick smoke test using the official AgentHarness runner to verify that search, fetch, and tool execution loops are stable against your local endpoint.
+Step 2: Route Brokk or Kaia through the Apodex Backend
+Ymir decouples agent logic from model providers by relying on API configurations and MCP/A2A composition (Hermóðr).
+ * Update the Primary Reasoning Target: Point Brokk (the primary agent) or Kaia (the orchestrator) at your local Apodex endpoint by setting your environment variables:
+   OPENAI_BASE_URL=http://localhost:1234/v1
+OPENAI_API_KEY=not-needed-for-local
+OPENAI_MODEL=apodex/Apodex-1.0-35B-A3B
+
+ * Ground Plans via Mimirsbrunn: Configure Kaia to query Mimirsbrunn (GET /recall) before generating execution plans. Because memory in Ymir is a "boost, never a blocker," Apodex will use historical context when available without failing if the well is dry.
+Step 3: Run Heavy Research Bursts as Eindri Workers
+For multi-step, deep-research workflows, map Apodex's heavy-duty sub-agent execution loops into Eindri workers running inside isolated Utgard sandboxes:
+ * Package the execution loop from AgentHarness into an isolated worker script.
+ * Have the worker execute its sub-agent tasks independently, then push its structured verdicts back into the ledger using Mimirsbrunn's observation hook (POST /observe).
+ * Publish state announcements across the Ratatoskr A2A backbone so Hlidskjalf can render the active task stream.
+Step 4: Enforce Ymir's Governance and Review Gates
+Regardless of how powerful the underlying Apodex model is, platform safety remains absolute:
+ * The Glitnir Gate: Never allow automated agents to bypass human review for merges or destructive actions. Apodex’s internal evidence graphs provide a clean, traceable audit trail, which serves as ideal input for human reviewers sitting at the Glitnir gate.
+ * The Append-Only Ledger: Ensure all final code artifacts and plan signatures are inscribed into Ymir's runes ledger before Mjölnir triggers any pull request pipelines.
+Would you like to draft the specific configuration overrides for plugging the local endpoint into Brokk's execution environment?
+
+---
+
+## Executive summary
+
+Short answer: **Yes — but with a reframing.** Apodex is not a turnkey "orchestrator + planner + reviewer suite" you can simply deploy. It is primarily **a model + API product plus a heavy-duty research orchestration layer**, and its strongest role is as a **planning / reasoning backend** wired into your own workflow. The "reviewer" capability is real but partial (an auditable verifier/evidence-graph component) and does not replace human governance.
+
+Three clarifications before the verdict:
+
+1. **Name check.** The product is spelled **Apodex** (one p after the "A"). No distinct product called "Appdex" was found; the name is almost certainly a typo. This report uses "Apodex."
+2. **The URL points at Ymir, not Appdex.** https://ymir.zerwiz.org is the **Ymir platform** — an alpha, invite-only, self-hosted agent-orchestration framework (Brokk/Eindri/Kaia fleet, Mimirsbrunn memory, Yggdrasil worktrees, Hlidskjalf dashboard, Glitnir human-review gate, append-only runes ledger). It is **not** an Appdex/Apodex landing page. Your question therefore blends two things; this assessment answers both readings:
+   - **(A)** Should *you* use Apodex as an orchestrator/planner/reviewer in your own work?
+   - **(B)** Could/would it be good to plug Apodex into **Ymir** in those roles (e.g., instead of Kaia or Brokk)?
+3. **Evidence basis.** The four attached reports (`Final Report(1).md`–`(4).md`) are prior analyses of exactly these questions, sourced from ymir.zerwiz.org, Apodex docs/HF, and the `ApodexAI/AgentHarness` README. I corroborated the key external claims via search (the `ApodexAI/AgentHarness` repo exists on GitHub, `platform.apodex.ai/docs/responses-api` is live, and community build posts reference the HF weights). What I could **not** independently verify: billing/pricing details on platform.apodex.ai, the internal wiring of Apodex's "global verifier," and the exact subset of Ymir's A2A/MCP interface specs (the site notes several are partly private).
+
+**Bottom line by role**
+
+| Role | Verdict | Why |
+|---|---|---|
+| **Planner** | ✅ Strong fit | Heavy-duty mode decomposes complex goals across sub-agent teams with draft/revise loops; plans stay grounded via recall (Mimirsbrunn-style) and leave an audit trail. |
+| **Orchestrator** | ⚠️ Medium, conditional | It *does* orchestrate its own research sub-agent teams internally, but it isn't documented as a general-purpose meta-orchestrator you point arbitrary agents at. Best used by wiring the API into your own control plane (or running its orchestration as isolated Eindri-style workers inside Ymir). |
+| **Reviewer** | ⚠️ Low-to-medium | The verifier/evidence-graph component can check claims and produce auditable trails, but there is no public governance/gate product. Human-in-the-loop review (Glitnir) must remain external and final. |
+
+---
+
+## 1. What each thing actually is
+
+### Apodex — the product
+Apodex is a **model/API product** focused on agentic, deep-research work:
+- **Chat assistant + Responses API.** Managed via `platform.apodex.ai` (keys, usage, billing); the programmatic entry point is `POST /v1/responses` with `background=true`, then polling `GET /v1/responses/:id` for long jobs.
+- **Heavy-duty orchestration layer.** For mission-critical multi-step tasks it runs an **orchestrated team of sub-agents plus a global verifier** over an **auditable evidence graph** — every claim traces back to a source node. Reported scale: 150+ sub-agents, 15k+ steps.
+- **Model weights.** Apache 2.0 open weights on Hugging Face (`apodex/Apodex-1.0-mini`, and the `Apodex-1.0-35B-A3B` variant among others), deployable locally via SGLang or vLLM over an OpenAI-compatible endpoint.
+- **AgentHarness.** The official open-source evaluation harness (`ApodexAI/AgentHarness`, Apache 2.0) for running Apodex-1.0 models in a ReAct agent setup with web search, web fetch, and code sandboxing.
+
+Key corroboration: the GitHub org `ApodexAI/AgentHarness` exists and describes itself as "Evaluation harness for Apodex-1.0 on public deep-research benchmarks"; `platform.apodex.ai/docs/responses-api` is a live doc page; a reference repo (`karminski/apodex-deepresearch`) uses `POST /v1/responses` with `background=true`; and the Apodex team has publicly described their model family as built to "scale agentic intelligence" (Apodex 1.1, per r/LocalLLaMA).
+
+### Ymir — the platform at the URL you gave
+Ymir is a **self-hosted agent substrate** (alpha, invites only): one program/one machine anchored in a single repo, with a named fleet — Brokk (primary agent/bellows), Eindri (isolated workers in Utgard sandboxes), and **Kaia (the orchestrator)**; Mimirsbrunn (single-file SQLite "engram" memory, `POST /observe` / `GET /recall`; rule: memory is a boost, never a blocker); Yggdrasil (git worktrees for zero-collision parallel edits); Mjölnir (issue→PR pipeline); Ratatoskr (A2A 1.0 backbone); Hermóðr (MCP composition); Hlidskjalf (fleet dashboard); and strong process rules — append-only runes/ledger, **Glitnir (human review always required)**, one-session locks, stuck-worker recovery, re-forging roadmap toward Rust/NATS/gRPC/libgit2. The current implementation stack is TypeScript/Python/React/Vue.
+
+Crucially, Ymir ties no agent to a vendor model — agents call APIs and exchange messages, so swapping the underlying reasoning engine is architecturally possible.
+
+### The four attached reports, in brief
+- `Final Report(1).md`: Apodex can work **with and for** Ymir as an assistant around the ecosystem (decode architecture, plan House/artifact fits, draft TS/Python/React/Vue code), but cannot grant access, bypass human review, or modify the well/ledger directly.
+- `Final Report(2).md`: Apodex ships as chat assistant **+ model/API** (Responses API, developer console) with heavy-duty orchestrated sub-agent + verifier pipelines, plus **self-hostable Apache 2.0 weights** (SGLang/vLLM).
+- `Final Report(3).md`: The **TUI cannot** live inside Ymir (it's a client, not an engine component), but the **model/API fits as Brokk's/Kaia's brain**, and the **heavy-duty orchestration layer fits as Eindri workers** in Utgard sandboxes.
+- `Final Report(4).md`: `AgentHarness` is a benchmark/eval runner (not a TUI, platform, or pi.dev replacement); it's the practical way to validate a local Apodex endpoint (smoke test → pi.dev wiring → eventual Ymir worker embedding).
+
+---
+
+## 2. Role-by-role assessment
+
+### Planner — Strong fit ✅
+Apodex's design is centered on decomposing open-ended goals into coordinated steps — precisely what planning means here. The heavy-duty mode breaks a task into many sub-agent turns, drafts and revises across iterations, and keeps the resulting plan grounded (via recall-like context, matching Ymir's Kaia rule that every plan be grounded in what the well already holds rather than spun from air).
+
+Strengths:
+- Multi-step decomposition and draft/revise loops out of the box.
+- **Traceable rationale**: the evidence graph maps every claim to a source — ideal for explaining *why* a plan was made, which is the exact thing Glitnir reviewers need to see.
+- Works either as a hosted API call or as a locally hosted weight, so you keep planning on-prem if required.
+
+Best usage pattern: give it a structured brief and a clear output contract (milestones, artifacts, acceptance criteria). In Ymir terms: Apodex produces the plan that passes "through the veil"; Glitnir still signs off.
+
+### Orchestrator — Medium, conditional ⚠️
+Here the answer splits. Inside Apodex, orchestration **is** a real capability: sub-agent teams run in concert under a supervisor, each task state-tracked over the A2A-style backbone of its harness. But this orchestration is scoped to Apodex's own research/code workload; it is surfaced through a request/response API plus background polling rather than exposed as a general meta-orchestrator for your external agent fleets.
+
+Implications:
+- You can **wire** it in — treat Apodex as one node in your own control plane, or run its orchestration bursts as isolated parallel workers — but you would build the outer coordination, not hand Apodex your whole fleet and walk away.
+- In Ymir language: Apodex's orchestration layer maps most naturally onto **Eindri workers** (isolated, parallelized, reporting verdicts into Mimirsbrunn), while the top-level orchestrator role (Kaia) remains yours — optionally powered by the same Apodex model.
+
+So: good orchestrator **for research and coding workloads it natively understands**; not a drop-in replacement for an external, general-purpose fleet orchestrator.
+
+### Reviewer — Low-to-medium ⚠️
+This is the weakest claim, and it deserves nuance. Apodex does include a **global verifier** within its heavy-duty pipeline that checks outputs against an evidence graph — a genuine automated verification step, not just text generation. That makes it useful as an **automated verification assistant and evidence auditor**: cross-checking facts, flagging unsupported claims, and producing an audit trail for humans to read.
+
+What it does **not** provide:
+- A public governance/review-gate product with approval workflows, permissions, and merge control. Nothing in the available documentation positions the verifier as an autonomous decision authority.
+- A substitute for human sign-off. Both Apodex's own heavy-duty mode (which includes human oversight) and Ymir's laws (Glitnir: human review always required for merges and irreversible actions) make that explicit. You should expect Apodex's review output to be **input to** the human gate, not the gate itself.
+
+Rating as "low-to-medium": high value as evidence checker + auditor; low value as the final reviewer-of-record.
+
+---
+
+## 3. Confidence table (what is solid vs. needs verifying)
+
+| Claim | Source | Confidence |
+|---|---|---|
+| `ApodexAI/AgentHarness` repo exists; Apache 2.0; evaluates Apodex-1.0 in ReAct setup (browsecomp, BrowseComp-ZH, HLE-text, DeepSearchQA, etc.) | Corroborated via GitHub org + README search | High |
+| Responses API at `api.apodex.ai/v1`, managed via `platform.apodex.ai` docs | Corroborated via live `platform.apodex.ai/docs/responses-api` + reference repo usage | High |
+| Heavy-duty mode = orchestrated sub-agent team + global verifier over auditable evidence graph | Attached reports (2), (3) | Medium — internal detail not independently verified |
+| Apache 2.0 HF weights (`apodex/Apodex-1.0-mini`, `Apodex-1.0-35B-A3B`); SGLang/vLLM serving | Attached reports (2), (4); HF naming consistent with community posts | Medium-High |
+| 150+ sub-agents / 15k+ steps scale figure | Attached report (2) only | Low-Medium |
+| Ymir: alpha/invite-only, Kaia orchestrator, Mimirsbrunn `/observe`/`/recall`, Glitnir human-review gate, Ratatoskr A2A, partial private specs | Direct read of ymir.zerwiz.org + attached reports (1), (3) | High |
+| Pricing / billing specifics on platform.apodex.ai | Not accessible in this environment | Not verified — check directly |
+| Which exact Ymir A2A/MCP interface endpoints you must implement | Site notes several are private | Not verified — request access or ask Ymir maintainers |
+
+---
+
+## 4. Recommended ways to use it
+
+### Path A — Use Apodex in your own workflow (independent of Ymir)
+1. Start with the hosted Responses API for planning-heavy, multi-step tasks (deep research, technical write-ups, architecture drafting).
+2. For cost/latency/control, validate a **local** endpoint: serve an Apodex weight via SGLang/vLLM and run the AgentHarness smoke test first.
+3. Wire it into your existing tools as a **planning/reasoning provider**; add your own review gate on top (manual sign-off, or a policy layer). Treat the verifier output as evidence, not a verdict.
+
+### Path B — Plug Apodex into Ymir
+1. Replace the model behind **Brokk** (via Hermóðr/MCP tools) or behind **Kaia's planner** so plans are fetched against Mimirsbrunn recalls and pass "the veil." No governance change: Glitnir/Skuld still apply.
+2. Optionally run Apodex's **heavy-duty orchestration layer as Eindri workers** in Utgard sandboxes for parallel research bursts; have them `POST /observe` verdicts back into Mimirsbrunn to keep the ledger complete.
+3. Keep the TUI as a human client — it has no place in the agent data path, and Ymir's own Hlidskjalf dashboard is where humans sit.
+4. Wire everything from **your own fork/instance** once you have alpha access; Ymir's A2A/MCP specs are partly private, so nothing gets injected into the official platform without access.
+
+---
+
+## 5. Limitations and risks
+- **Identity/platform confusion.** Appdex ≠ Apodex; the URL you gave is Ymir, a separate alpha platform. Getting the integration right depends on which one is doing the orchestrating.
+- **Not autonomous governance.** The reviewer role is automated evidence checking; human-in-the-loop remains mandatory (Ymir's Glitnir law; Apodex's own human-supervised heavy-duty mode).
+- **Access wall.** Ymir is alpha/invite-only; you need access (or a fork) before you can plug anything in, and some specs are private.
+- **Implementation effort.** Wiring Apodex as Kaia/Brokk's brain requires implementing the agent↔API↔ledger path and respecting Ymir's Houses, gates, and ledger rules — nontrivial but documented conceptually.
+- **Cost/compute.** Hosted API per-call costs; local weights (e.g., 35B) require a capable GPU server. Validate with the smoke test before committing.
+
+---
+
+## 6. Recommended next steps
+1. Decide **Path A** (own workflow) vs **Path B** (into Ymir) — this determines all downstream wiring.
+2. If Path B: request **alpha access** to Ymir; otherwise operate on your own fork.
+3. If you want your own Apodex endpoint: install `AgentHarness`, serve a weight with SGLang, run the browsecomp smoke test, and confirm behavior against the README performance table before routing anything critical through it.
+4. Stand up your **human review gate** first — whether Ymir's Glitnir or your own policy layer — and treat Apodex's verifier output as trusted input to that gate, never as the final word.
+5. Iterate on the planning brief/output-contract pairing; that pairing is where the planning strength is actually captured.
+
+---
+
+## 7. References
+- Ymir platform (the URL you provided): https://ymir.zerwiz.org — read in full; alpha/invite-only; concepts above sourced directly from its pages.
+- `ApodexAI/AgentHarness` (official eval harness): https://github.com/ApodexAI/AgentHarness
+- Apodex Responses API docs: https://platform.apodex.ai/docs/responses-api
+- Apodex model reference / responses usage: https://github.com/karminski/apodex-deepresearch
+- Apodex HF weights: https://huggingface.co/apodex (not independently confirmed in this run)
+
+**Analysis prepared against:** `Final Report(1).md`, `Final Report(2).md`, `Final Report(3).md`, `Final Report(4).md` in `/inputs`.

package/assets/reference/docs/apodex/Final Report(1).md

@@ -0,0 +1,198 @@
+Yes, you can use Apodex to work *with* and *for* Ymir—but not to bypass Ymir’s own constraints (alpha access, review gates, etc.). The value is in using Apodex as your assistant around the Ymir ecosystem, not as a replacement for Ymir’s own agents.
+
+Below is a direct, actionable breakdown.
+
+---
+
+## 1. What Ymir is (so we’re talking about the same thing)
+
+From the Ymir site:
+
+- **Ymir is a single-substrate platform** – “one program, one machine, all realms carved from it” anchored in one repo and one machine.
+- It runs a **named agent fleet**:
+  - **Brokk** – primary agent (“the bellows”).
+  - **Eindri** – isolated worker agents (“the craft”) running in Utgard sandboxes.
+  - **Kaia** – orchestrator (“the eye that remembers”), which drinks from the well and passes plans through “the veil” so they are grounded in memory, not spun from air.
+- **Mimirsbrunn** – a single-file SQLite “engram” memory engine with:
+  - `POST /observe` – record meaningful actions, conversations, skills, and verdicts.
+  - `GET /recall` – retrieve relevant memory for a project before dispatch.
+  - Rule: memory is always a **boost, never a blocker**—a dry well doesn’t stop the forge, it just runs cold.
+- **Git worktree / Yggdrasil model** – branches/worktrees for zero-collision parallel edits; all work routes through one trunk.
+- **Artifacts / tools named by myth**:
+  - **Mjölnir** – issue → PR pipeline (hammer that returns with a PR).
+  - **Ratatoskr** – A2A 1.0 backbone: state announcements and work tracking between agents.
+  - **Hermóðr** – MCP/A2A composition: horizontal delegation via A2A, vertical tool access via MCP.
+  - **Hlidskjalf** – dashboard: fleet graph, A2A stream, well, ledger, reviews.
+  - **Others** (Bifrost, Heimdall, Gjallarhorn, Skrymir, Valhalla, etc.) map to familiar OSS like Traefik/Caddy, OAuth2-proxy/AuthentiK, cloudflared, MinIO/FileBrowser, PM2/Docker.
+- **Houses** – ventures within the mythos (Ymir Labs, Brokk Forge, Runestone Labs, Muninn Labs, Dvalin, Utgard Studios, Askr, Mannheim).
+- **Forge-Master’s Rule** – “open source first; only what differentiates Ymir is smithed in Ymir’s own forge.”
+- **Stack**:
+  - **Current “light metals”**: TypeScript, Python, React, Vue.
+  - **Future “Rut steel”**: Rust, NATS, gRPC, libgit2, re-forging gates without changing their contracts.
+- **Strong process & safety rules**:
+  - Append-only runes/ledger; nothing un-carved.
+  - Glitnir: **human review is always required**.
+  - Laws about one session/one reins, scheduling, stuck-worker recovery, update rules, etc.
+
+So Ymir is not “just a library.” It’s a whole, opinionated agent platform plus operational philosophy.
+
+---
+
+## 2. Ways you *can* use Apodex for Ymir
+
+Within those constraints, these are realistic, concrete uses of Apodex:
+
+### 2.1. Understanding and planning around Ymir
+
+You can use Apodex to:
+
+- **Decode the myth into an architecture map**  
+  - Translate Brokk/Eindri/Kaia, Mimirsbrunn, Ratatoskr, Mjölnir, Hlidskjalf, etc., into plain technical architecture and workflows.
+  - Explain the “ten laws” and the additional nineteen laws (Gleipnir, Skuld, Hermóðr, Glitnir, etc.) in operational terms for your team.
+
+- **Design how your project will live inside Ymir**
+  - Decide which **House** your work belongs to (e.g., an observability tool under Valhalla vs. a memory-centric thing under Muninn).
+  - Plan branch/worktree usage so you respect the “never work outside your realm” and “Svartalfaheim holds the shop floors” rules.
+  - Sketch how your service should interact with:
+    - A2A 1.0 (Ratatoskr) if it needs agent-to-agent messaging.
+    - MCP (Hermóðr) if it exposes tools to agents.
+    - Mimirsbrunn (`/observe` and `/recall`) if it needs memory.
+
+- **Prepare contribution plans**
+  - Outline a concrete proposal for:
+    - A new “treasure” (artifact) to hang on the wall.
+    - Improvements to an existing gate (e.g., Hlidskjalf panels, Ratatoskr enhancements).
+  - Frame the proposal in their myth/lexicon so it fits the repo’s “ten laws” and later rules.
+
+If this is your main need, you’d use Apodex like a systems architect + documentation explainer.
+
+---
+
+### 2.2. Helping you build code that fits Ymir’s stack and rules
+
+Given that Ymir’s current implementation stack is:
+
+- **TypeScript**
+- **Python**
+- **React**
+- **Vue**
+
+and later:
+
+- **Rust**
+- **NATS**
+- **gRPC**
+- **libgit2**
+
+you can use Apodex to:
+
+- **Draft components, services, or utilities in these stacks**  
+  For example:
+  - A service that calls `POST /observe` and `GET /recall` and conforms to their “memory is a boost, never a blocker” rule (falling back cleanly when recall is empty).
+  - React/Vue views or widgets conceptually suitable for the Hlidskjalf dashboard (e.g., visualizing A2A task streams or ledger entries).
+  - Helper libraries to integrate with Ratatoskr’s A2A model in your own agents/services.
+
+- **Prototype integrations that follow Ymir’s “borrowed anvil” stance**  
+  - For example, if you want to expose some new capability, we can:
+    - Identify an existing, validated OSS project that does the bulk of it.
+    - Sketch how to wrap it under a mythic name and keep Ymir-specific logic thin.
+  - This stays faithful to: “Does a validated OSS project already do this? If yes, name it and use it. Only what differentiates Ymir is smithed in Ymir’s own forge.”
+
+- **Set up clean boundaries for MCP/A2A tooling**
+  - Design MCP tools or A2A-facing services that:
+    - Take a structured `Erindi`-style brief.
+    - Avoid irreversible actions unless a “Frigg/consent” gate is explicit.
+    - Respect Skuld (no merge without a verdict) and Glitnir (human review).
+
+You would then run, test, and review this code in your own fork or instance; Apodex does not execute it for you or merge anything itself.
+
+---
+
+### 2.3. Working with the Ymir repo/process, without bypassing it
+
+Apodex can:
+
+- **Help you prepare contributions that fit Ymir’s laws**  
+  - Propose file layout and naming consistent with Houses, gates, and runes.
+  - Suggest how to structure tests, docs, or runbooks so they feed nicely into Runestone Labs’ “runes and records” model.
+
+- **Help you respect the ledger & review constraints**
+  - Draft commit messages and documentation that:
+    - Clearly inscribe significant actions (aligns with the “runes are append-only” idea).
+    - Make it straightforward for Glitnir (human reviewers) to see what changed and why.
+  - Outline a manual checklist for you to follow before invoking Mjölnir (issue → PR pipeline), so Skuld (outcome/merge gate) has what she needs.
+
+- **Support operational thinking around Ymir’s “seating” and “watch”**
+  - Turn the “seating” ceremony (seat, chain, loom, telling) into:
+    - A practical checklist for starting your Ymir workday.
+    - A runbook for on-call or daily operations.
+  - Turn “the watch” rules into monitoring/alerting requirements for your Ymir deployment.
+
+Again: Apodex **assists your work**; Ymir’s laws still enforce human review and ledger discipline on the platform side.
+
+---
+
+## 3. What Apodex cannot do for Ymir
+
+You **cannot** rely on Apodex to:
+
+1. **Grant or circumvent access to Ymir**
+   - Ymir is explicitly **alpha, invites only**.  
+   - If you don’t have an invite or a running instance, Apodex can’t create one or get you in.
+
+2. **Act as an unsupervised Ymir agent that skips Glitnir**
+   - Ymir mandates **human review for merges and irreversible actions**.
+   - Even if you wired Apodex into Ymir via A2A or MCP, a human still has to:
+     - Approve plans and artifacts.
+     - Approve merges/rollouts.
+   - Apodex can’t and shouldn’t nullify Skuld, Glitnir, Frigg, or similar safety/oversight rules.
+
+3. **Directly modify the Mimirsbrunn well, ledger, or running fleet without your control**
+   - Any use of `/observe` and `/recall`, ledger entries, or agent orchestration must be mediated through your own code, tools, or Ymir UI.
+   - Apodex can help you design and implement those tools; it does not reach into your running Ymir environment by itself.
+
+4. **Guarantee conformance to internal contracts you haven’t shown**
+   - Ymir’s public page gives a conceptual description (A2A 1.0, MCP composition, etc.), not the full, private interface specs.
+   - For private APIs, schemas, or conventions, you would need to provide the relevant pieces; Apodex will work from what you share.
+
+---
+
+## 4. How to decide if “using Apodex for Ymir” makes sense for you
+
+It *does* make sense if:
+
+- You’re trying to:
+  - Understand Ymir’s philosophy and architecture.
+  - Plan how your project or product fits as a House, artifact, or gate.
+  - Draft or iterate on code and docs in Ymir’s current tech stack.
+  - Prepare well-structured contributions or integrations before you open a PR.
+
+It does **not** solve:
+
+- Getting platform access when you don’t already have it.
+- Replacing human oversight in a system whose laws explicitly require it.
+
+---
+
+## 5. Concrete next steps (pick one and Apodex can help)
+
+If you tell me:
+
+1. **“We want to build X on Ymir.”**  
+   - I can map X onto:
+     - Houses.
+     - Required gates (A2A, MCP, Mimirsbrunn, Hlidskjalf, etc.).
+     - A step-by-step implementation plan.
+
+2. **“We have repo access and want to add/modify Y.”**  
+   - I can:
+     - Help you unpack the relevant laws that govern that area.
+     - Sketch the directory layout and data flow.
+     - Draft implementation code in TS/Python/React/Vue that you then run and review.
+
+3. **“We’re just evaluating Ymir; help us decide if it fits us.”**  
+   - I can:
+     - Produce a concise pros/cons or fit analysis against your current stack and workflow.
+     - Highlight where Ymir’s strong process (ledger, review, watch, seating) lines up—or conflicts—with how your team already works.
+
+If you share your specific goal (“we want to X with Ymir”), I can turn that into a focused plan plus concrete artifacts you can apply in your own environment.

package/assets/reference/docs/apodex/Final Report(2).md

@@ -0,0 +1,54 @@
+Good news — and this is very much doable. I dug into how Apodex actually ships as a model, because "using the Apodex model" can mean three different things, and only one of them is "just talking to me in this chat." Here's what I found.
+
+## The short version
+
+Apodex is both a **chat assistant** (what you get right now) and an actual **model + API product** that you can call from your own code or plug into other tools — pi.dev and Ymir alike. So yes, you can move beyond this UI and run Apodex as your underlying model.
+
+Three ways to interpret your question, with an answer for each:
+
+---
+
+### 1. If you mean: "Can I use Apodex instead of this chat interface (e.g., for heavy-duty research / multi-step tasks)?"
+
+**Yes — via the official API.** Apodex runs a Responses API at `api.apodex.ai/v1`, managed through a Developer Console at `platform.apodex.ai` (keys, usage, billing). For research/workload tasks you'd POST to `/v1/responses` with `background=true`, then poll `GET /v1/responses/:id` until complete.
+
+Key capabilities worth knowing if you're routing your hard jobs through it:
+
+- It's a **tool-using agent** by design, not just a text generator — it can search, fetch pages, and execute code in a loop, feeding results back into itself.
+- Its "heavy-duty" mode runs an orchestrated team of sub-agents plus a global verifier over an **auditable evidence graph**, so every claim traces back to a source node. That's a real fit for long-horizon work (150+ sub-agents, 15k+ steps), and it mirrors Ymir's own ledger/verdict philosophy.
+- A local-only ReAct variant exists too, where you supply your own tools via `OPENAI_BASE_URL`/`OPENAI_API_KEY` and pin your search/fetch/code providers.
+
+So for exactly the kind of mission-critical, multi-step jobs Pi.dev won't naturally handle, Apodex has a programmatic path.
+
+---
+
+### 2. If you mean: "Can I use Apodex **inside pi.dev** as my model provider?"
+
+**Very probably, yes.** Pi.dev already speaks to 15+ providers and is explicitly built for **self-hosted endpoints**. Two routes:
+
+- **Official API:** give pi.dev an `APODEX_API_KEY`-backed `BASE_URL` pointing at `https://api.apodex.ai/v1` (the Responses API). Whether Pi deviates from strict OpenAI-conforming `/chat/completions` may matter here — worth testing against its supported provider list.
+- **Self-hosted weights (fully local):** Apodex publishes **Apache 2.0 weights on Hugging Face** (`apodex/Apodex-1.0-mini`, and 1.1 variants). You can serve them yourself over an OpenAI-compatible endpoint using SGLang or vLLM:
+  - SGLang: `python3 -m sglang.launch_server --model-path apodex/Apodex-1.0-35B-A3B --context-length 262144 --tool-call-parser qwen3_coder --reasoning-parser qwen3`
+  - vLLM: `vllm serve ... --enable-auto-tool-choice --tool-call-parser qwen3_coder --reasoning-parser qwen3`
+
+  Pi.dev should pick this up like any local endpoint. Note the model expects function-calling messages with structured tool payloads, so make sure whatever harness you use parses tool_calls and returns them as `role: "tool"` messages.
+
+**Caveat:** I can't confirm which exact endpoint format Pi.dev currently accepts; you'll want to test against its provider configuration rather than assume OpenAI-conformity across the board.
+
+---
+
+### 3. If you mean: "Can Apodex be **Ymir's agent model** (replacing Brokk/Eindri's backend)?"
+
+**Yes, in principle, with some wiring.** Ymir's agents operate by calling APIs, sending A2A messages via Ratatoskr, and delegating tools over MCP (Hermóðr). Nothing in the design ties a model to a specific vendor — Apodex as an API call or as a local OpenAI-compatible endpoint fits cleanly into that pattern.
+
+The interesting part is alignment:
+- Ymir requires **human review** (Glitnir) before merges and irreversible actions, uses an **append-only ledger**, and treats memory as a boost not a blocker.
+- Apodex heavy-duty mode produces an **auditable evidence trail** by default, which lines up well with Ymir's append-only runes/ledger ethos.
+
+Practical caveat: brokering Apodex through Ymir means the same constraints you already have — Ymir's review gates still apply, and Ymir's interface specs are partly private so you'd wire it up from within your own fork/instance.
+
+---
+
+## One clarification worth making
+
+"To this" was slightly ambiguous — is your target **pi.dev** (swapping the model underneath), **Ymir** (making Apodex a fleet worker), or something else entirely (a standalone research pipeline)? Tell me which and I'll give you the concrete wiring: env vars, endpoint config, or a repo layout that respects whichever platform's rules apply.

package/assets/reference/docs/apodex/Final Report(3).md

@@ -0,0 +1,40 @@
+## Short answer
+
+**No on the TUI — yes on everything else.** You can't run "the Apodex TUI" inside Ymir, but you *can* run the Apodex **model, API, and orchestration layer** inside Ymir as the brain behind Brokk or Kaia. Those are the only two categories worth distinguishing.
+
+---
+
+## 1. Why "Apodex TUI" doesn't work inside Ymir
+
+The TUI (and this chat interface) is a **client** — a way for you to talk to me. It's not an engine component like Brokk (the bellows) or Kaia (the eye that remembers). There's nothing to "drop in":
+
+- A TUI is a screen UI with its own session, commands, and output rendering. Brokk/Kaia need a **reasoning engine**, not a display.
+- Ymir's architecture is agent↔API↔ledger. A chat window fits nowhere in that data path.
+
+So there's no point trying to embed the TUI in a house, gate, or Utgard sandbox. What matters is what sits *behind* the model calls.
+
+## 2. What you *can* put inside Ymir
+
+**The Apodex model/API → serves as Brokk's (or Kaia's) brain.** Nothing in Ymir ties a model to a vendor. Your existing agents already operate by calling APIs and exchanging messages, so you replace whatever backend they currently call with the Apodex endpoint (`/v1/responses`, background=true + polling for heavy jobs), just as you'd route a self-hosted endpoint through it.
+
+- **As Brokk:** wrap an Apodex call behind Hermóðr (MCP tools) so Brokk gets the same tool discipline (structured briefs, consent gates) with stronger reasoning underneath.
+- **As Kaia's planner:** let Apodex draft and revise plans fetched against Mimirsbrunn recalls, then pass them through "the veil." Memory is still a boost, never a blocker — a silent recall just changes Kaia's input, not its ability to proceed.
+
+**The heavy-duty orchestration layer → runs as Endri workers.** The multi-step research / code / verifier loop (sub-agent teams, evidence graph, local ReAct variant) fits naturally as *isolated worker agents in Utgard sandboxes*, parallelizing Ymir's own fleet idea. Each worker still reports verdicts back into Mimirsbrunn via `/observe`, keeping the ledger complete.
+
+## 3. The important caveat: Ymir's laws don't care about your model
+
+Whether Brokk runs on Apodex, GPT, or a local weight, **Glitnir still requires human review before merges/rollouts, Skuld still blocks merges without a verdict, and the runes/ledger stays append-only.** The model swap changes intelligence and traceability — not oversight. If anything, Apodex's built-in auditable evidence trail maps nicely onto the ledger ethos, which helps Glitnir reviewers see *why* a change happened.
+
+Ymir is alpha/invite-only and its A2A/MCP specs are partly private, so you wire this from inside your own fork or instance — nothing gets injected into the official platform.
+
+## Bottom line
+
+| Piece | Inside Ymir? | How |
+|---|---|---|
+| Apodex **TUI** | ❌ No | Client UI, not an engine component — no place for it in Brokk/Kaia's data path |
+| Apodex **model/API** | ✅ Yes | Drop it in as Brokk's or Kaia's reasoning backend (MCP or direct calls) |
+| Apodex **heavy-duty orchestration** | ✅ Yes | Run as Endri workers in Utgard sandboxes, reporting verdicts to Mimirsbrunn |
+| Ymir's **review/gate/ledger rules** | ⚠️ Unchanged | Apply regardless of model choice |
+
+Tell me whether you're targeting pi.dev, Ymir, or a standalone pipeline as your main target, and I'll give you the concrete env/config or repo layout that respects whichever platform's rules apply.