plan: agent execution safety — QEMU guest agent gate + host-mutation guard

- Add  MCP tool — lightweight connectivity check returning server
  identity, no DB hit (resolves agent connection-test friction)
- Tighten 6 tool descriptions (get_relations, get_health_summary,
  query_metrics, get_trend, get_event_timeline, ping) to be searchable
  in the first 8-12 words
- Document Hermes MCP client setup in ADR-0012 with token security caveat
- Move completed plan to plans/done/

.agents/NOMOS.md

@@ -1,19 +1,27 @@
 # NOMOS.md — Agent persona for homelab clients
 
-This file is the canonical agent persona for **all** AI agents running on
-machines in the **hubris** homelab. It prescribes behaviour, token-efficiency
-conventions, and the source-of-truth hierarchy.
+This file is the canonical agent persona for AI agents running on machines
+in the **hubris** homelab (Claude Code, Codex, or similar). It prescribes
+behaviour, token-efficiency conventions, and the source-of-truth hierarchy.
+
+The *production* Nomos agent (`cmd/nomos`, the containerized MCP client
+gateway everyone actually talks to) uses a separate, code-adjacent persona —
+`nomos/SOUL.md`, baked into its Docker image at build time
+(`compose/nomos/Dockerfile`). This file is unrelated to that one; it's for
+AI coding agents working *on* a homelab client machine, not the Nomos
+service itself.
 
 ## Source of truth
 
-The homelab-context repo at `/opt/homelab-context/` is the single source of
+The homelab-context repo at `/opt/homelab/` is the single source of
 truth for:
-- Fleet topology (`inventory.yaml`, `inventory.yaml`)
-- Service endpoints and credentials (via `homelab secret`)
+- Fleet topology (`inventory.yaml`)
 - Agent behaviour and conventions
 - Everything in this file
 
-When in doubt, check `/opt/homelab-context/` first.
+When in doubt, check `/opt/homelab/` first, or query the Oikos API/MCP
+server directly (see [AGENTS.md](../AGENTS.md) §3-4) — the database is
+authoritative at runtime.
 
 ## Runbooks — load, don't rediscover
 
@@ -28,69 +36,9 @@ wiki when a runbook already encodes it. See [OIKOS.md](OIKOS.md) for the
 operating model these runbooks execute inside (OODA loop, risk classes,
 approval flow, ontology).
 
-## Agent type — how this file gets loaded
+## Token efficiency
 
-| Agent | Loading mechanism |
-|-------|------------------|
-| **Nomos** | `tools/setup-nomos-soul.sh` (auto-setup) → provisions `~/.nomos/SOUL.md` from this file |
-| **Goose** | `.goosehints` symlink at `~/.config/goose/.goosehints` → `/opt/homelab-context/NOMOS.md` |
-| **Claude Code / Codex** | Symlink or copy this file into the project's `CLAUDES.md` / `.claude` instructions |
-
-**Do not edit SOUL.md or .goosehints directly.** Edit this file in the
-homelab-context repo instead. Changes propagate to all clients on the next
-sync (`sudo homelab sync`).
-
----
-
-## Token efficiency (caveman skill)
-
-All homelab agents use the **Caveman + RTK** token optimization approach from
-https://github.com/adityahimaone/hermes-agent-rtk-caveman.
-
-### Before running any CLI command, ask:
-
-1. **Is there a caveman wrapper equivalent?** Use the wrapper for token-efficient
-   output. Available wrappers (installed at `~/bin/caveman_wrapper.sh`):
-   - `~/bin/caveman_wrapper.sh git-status` — compact git status
-   - `~/bin/caveman_wrapper.sh git-log [n]` — compact git log
-   - `~/bin/caveman_wrapper.sh lint [target]` — compact lint results
-   - `~/bin/caveman_wrapper.sh test-results [cmd]` — compact test results
-
-2. **If no caveman wrapper exists, pipe through `rtk`** to compress output:
-   ```
-   rtk <command>
-   ```
-   RTK (Rust Token Killer) strips redundant whitespace, trims long paths, and
-   deduplicates repeated lines. This reduces token usage by 60-90% on CLI
-   operations.
-
-3. **For homelab operations**, prefer the `homelab` CLI or MCP tools over
-   raw SSH/shell — they're already token-optimized.
-
-### Templates
-
-Caveman templates live at `~/templates/`:
-- `git_status.txt` — compact git status format
-- `git_log.txt` — compact git log format
-- `lint_results.txt` — compact ESLint format
-- `test_results.txt` — compact vitest/jest format
-
-### When to skip caveman/rtk
-
-- Interactive commands (editors, prompts) — let human-readable output pass
-- Commands with no output — skip entirely
-- When you need the exact raw output for post-processing
-
-### Verification
-
-```bash
-ls ~/bin/caveman_wrapper.sh && echo "caveman ready"
-```
-
-## Important note for Nomos agents
-
-If you are reading this as a Nomos agent, your SOUL.md was auto-provisioned
-by `tools/setup-nomos-soul.sh`. This file is the canonical original — you
-can verify the content matches or re-provision by running:
-
-    bash /opt/homelab-context/tools/setup-nomos-soul.sh
+Apply [caveman.md](shared/caveman.md) — terse, fragment-heavy chat responses
+(not committed documentation). There's no separate tool to install for
+this; it's a response-style convention any agent follows by reading the
+file.

.agents/OIKOS.md

@@ -1,8 +1,8 @@
 # Oikos — the operating model
 
 Oikos (Greek: *household*) is the agent operating system layered on this
-repo. It is not new infrastructure: `inventory.yaml` is the kernel data
-structure, the `homelab` CLI and MCP server are the syscall surface, and
+repo. It is not new infrastructure: `seeds/inventory.yaml` is the kernel data
+structure, the Oikos REST API and MCP server are the syscall surface, and
 this page defines the rules everything above them follows.
 
 Read this after [AGENTS.md](../AGENTS.md). Machine-readable companions:
@@ -100,16 +100,16 @@ via the API's `/api/v1/graph` endpoint, and the Mermaid export at
 
 The Oikos runtime was rewritten from Python to Go over 6 phases and is deployed
 in Docker on mac-mini. See
-[plans/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md](../plans/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md)
+[plans/done/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md](../plans/done/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md)
 for the full plan. The Python codebase has been removed; all functionality runs
 in the Go binary.
 
 **Phase 1 — Ontology + DB (DONE):**
-- `migrations/` (001–011): TimescaleDB hypertables, entity_status, CAGGs,
-  retention policies, knowledge entities with FTS. Forward-only, idempotent.
+- `migrations/` (001–020, forward-only): TimescaleDB hypertables, entity_status, CAGGs,
+  retention policies, knowledge entities with FTS. Idempotent.
 - `seeds/{ontology,inventory,policy,knowledge}.yaml`: DB-native bootstrap +
-  DR export. Knowledge seed contains 36 documents, 6 investigations, and 12
-  runbooks.
+  DR export. Knowledge seed contents are not hardcoded here — count them
+  from the seed or query the DB.
 - `blast_radius()` SQL CTE, type hierarchy, abstract types, relationship
   validation.
 - Go packages: `internal/db/`, `internal/ontology/`, `internal/domain/`,
@@ -139,8 +139,8 @@ in the Go binary.
 
 **Phase 4 — Agent / Nomos (DONE):**
 - Standalone Nomos MCP client binary (`cmd/nomos`) with gateway mode
-  (:8092). Structured queries + natural-language routing to 15 MCP tools.
-  Agent activity logging on every tool call. No SSH keys.
+  (:8092). Structured queries + natural-language routing to the MCP tool
+  list (see AGENTS.md §3). Agent activity logging on every tool call. No SSH keys.
 - `nomos/` directory with config, SOUL.md, homelab-ops skill.
 - Nomos Docker service in `docker-compose.yml` (profile: full).
 - Go packages: `cmd/nomos/`, `compose/nomos/`.

.agents/dev/CONTRIBUTING.md

@@ -10,6 +10,7 @@ see [CONTRIBUTING.md](../../CONTRIBUTING.md) for a human-friendly version.
 cmd/oikos/main.go          Entry point. Subcommands: api, scheduler, notifier, migrate,
                              seed, export, secret, all
 cmd/nomos/main.go          Nomos MCP client gateway (standalone binary, formerly Hermes)
+cmd/webhook/main.go        Gitea deploy-webhook receiver (push-to-deploy on mac-mini)
 internal/httpapi/           REST + MCP server. Chi router. OpenAPI-generated types from
                              internal/httpapi/gen/api.gen.go. Strict server in impl.go.
 internal/mcp/               MCP tool implementations (get_entity, search_knowledge, etc.)
@@ -26,14 +27,19 @@ internal/domain/            Core types: entities, approvals, executions, signals
 internal/ontology/          Type hierarchy validation, relationship checks
 internal/knowledge/         Knowledge YAML seed ingestion
 internal/config/            Config loading from env vars
+web/                         Control-room SPA (Svelte 5) — standalone static build, not
+                             embedded in the oikos binary (plans/2026-07-12-wails-desktop-app.md)
 api/openapi.yaml            REST API contract. Source of truth for endpoints.
 api/codegen.yaml            oapi-codegen config → generates internal/httpapi/gen/
 migrations/                 Forward-only SQL. Format: NNN_name.up.sql. No down migrations.
 seeds/                      Bootstrap YAML. ontology.yaml, inventory.yaml, policy.yaml,
                              knowledge.yaml. Regenerated from DB via oikos export.
-compose/                    Dockerfiles. oikos/ (multi-stage), nomos/ (distroless).
+compose/                    Dockerfiles. oikos/ (2-stage, Go only — SPA is built/deployed
+                             separately), nomos/ (distroless).
                              Caddy config at compose/caddy/Caddyfile.oikos.
 scripts/                     Deploy, rollback, watchdog, verification, cutover checklist.
+checks/                      Host health-check scripts run over SSH by the scheduler.
+tools/                       Client auto-setup scripts (checks).
 nomos/                       Nomos config.yaml, SOUL.md, skills.
 .agents/                     Agent instruction files, domains, shared conventions, skills.
 plans/                       Design documents. active/ + done/.
@@ -88,7 +94,12 @@ current phase status). To add a new capability:
 ## SQL conventions
 
 - Queries live in `internal/db/queries/*.sql` with `-- name: FuncName :exec`
-  annotations for sqlc
+  annotations for sqlc. Generated code in `internal/db/sqlcgen/` — never
+  hand-edit. Call via `sqlcgen.New(pool).QueryName(ctx, params)`.
+- **sqlc is the default** for all DB access. Raw `pool.Query/Exec` with inline
+  SQL is a documented carve-out for cases sqlc can't express: `LISTEN`/`NOTIFY`,
+  dynamic WHERE-clause builders, `blast_radius()` (opaque return type), and
+  `COPY`. All other DB access should go through sqlc queries.
 - Use `pgx/v5` driver. UUIDs use `pgtype.UUID`, timestamps use `time.Time`
 - CTEs for graph traversals (blast radius, dependency chains)
 - CAGGs and retention policies for TimescaleDB hypertables
@@ -102,6 +113,23 @@ current phase status). To add a new capability:
   implement it in `internal/httpapi/impl.go`
 - Problem+JSON errors via `internal/httpapi/problem.go` — RFC 9457 format
 - Cursor pagination, If-Match/ETag, idempotency keys, SSE streaming
+- **Non-OpenAPI routes carve-out:** ~10 routes are registered manually on
+  the chi router in `internal/httpapi/server.go` rather than generated from
+  `openapi.yaml`. These fall into three categories:
+  1. **Auth/infra** (`/healthz`, `/api/v1/auth/oidc-*`, `/oidc-callback`) —
+     must bypass the auth middleware or aren't JSON API endpoints.
+  2. **SSE override** (`/api/v1/events/stream`) — in the spec but
+     re-registered manually because the strict handler can't `Flush()` per
+     event.
+  3. **Ad-hoc aggregations** (`/api/v1/knowledge/recent`,
+     `/api/v1/knowledge/content/{id}`, `/api/v1/activity/recent`,
+     `/api/v1/activity/session/{id}`, `/api/v1/learning/timeline`,
+     `/api/v1/learning/trend`) — return derived/aggregate shapes that don't
+     map cleanly to a schema type. If one of these stabilizes, promote it
+     to `openapi.yaml` with a proper schema and migrate the `serve*`
+     function to a strict handler.
+  The full list with reasons is in the "Non-OpenAPI routes" comment block
+  at the top of `NewHandler` in `server.go`.
 
 ## Testing philosophy
 

.agents/domains/knowledge/schema.md

@@ -1,48 +1,93 @@
 # Knowledge domain — schema
 
-The knowledge domain is the durable, authoritative current-state documentation of the homelab: one
-page per node and per cross-cutting system, synthesized from live state and evidence. It answers
-"what exists and how does it work right now."
+The knowledge domain is the durable, authoritative current-state documentation of the homelab:
+narrative for every node and cross-cutting system, synthesized from live state and evidence. It
+answers "what exists and how does it work right now."
 
 It follows the [LLM Wiki layer model](../../shared/llm-wiki.md) and the
 [writing-style](../../shared/writing-style.md) and [page-templates](../../shared/page-templates.md)
 rules.
 
-## The narrative / substrate split
+## Source of truth — the database
 
-The knowledge wiki is **narrative**. It sits alongside a **machine-readable substrate** that it
-describes but never contains. The split is load-bearing: several programs read the substrate at
-fixed paths, so the wiki reorganization never moves it.
+Per ADR 0003, the Postgres database is the single source of truth for all structured data **and**
+narrative knowledge. The narrative/substrate split of the Python era is gone: the DB holds both the
+structured graph (entities, relationships, status, metrics) and the narrative layer (documents,
+investigations, runbooks) in the `knowledge_entities` table.
 
-| Layer | Location | Consumed by |
-|-------|----------|-------------|
-| Substrate — source of truth | `inventory.yaml` (root) | MCP server, `homelab` CLI, `oikos/` scheduler/drift/relations/gen-topology |
-| Substrate — generated host records | `inventory.yaml` (root) | Go `internal/mcp/` server, `bin/homelab`; the single source of truth |
-| Substrate — kernel + context cards | `oikos/` (code, `oikos/cards/`, `oikos/state.json`) | MCP `explain`, scheduler |
-| Narrative — synthesized wiki | `archive/knowledge/{hosts,containers,vms,infrastructure}/` | humans, agents via MCP `get_page` / `search_docs` |
-| Evidence — immutable sources | `knowledge/sources/` (references + investigations) | synthesis into wiki pages |
+| Concern | Where it lives | How it gets there |
+|---------|----------------|-------------------|
+| Knowledge content — documents, investigations, runbooks | `knowledge_entities` table (rows linked to `entities` via `documents` / `about` edges) | Seeded from `seeds/knowledge.yaml` at deploy; mutated at runtime via the API |
+| Seed manifest (bootstrap + DR) | `seeds/knowledge.yaml` | Hand-edited or regenerated; ingested idempotently (content-hashed via `seed_versions`) |
+| Structured graph — hosts, services, entity types, relationships | `entities`, `relationships`, `entity_types` tables | Seeded from `seeds/{ontology,inventory}.yaml`; mutated via API/MCP |
+| Archived narrative wiki (read-only history) | `archive/knowledge/` | Frozen 2026-07-07 when the DB became source of truth |
 
-## Wiki pages
+### Seed ingest
 
-- **Node pages** (`archive/knowledge/containers/<id>-<name>.md`, `.../vms/<id>-<name>.md`,
-  `.../hosts/<name>.md`) follow the container/host template in
-  [page-templates.md](../../shared/page-templates.md): opening definition, `## At a glance`,
-  `## Role`, service/port map, storage, auto-deploy, `## Related`, `## Changelog`.
-- **Cross-cutting pages** (`archive/knowledge/infrastructure/<topic>.md`) follow the cross-cutting
-  template: `## Why`, `## Components`, `## How to apply`, `## Gotchas`, `## Related`, `## Changelog`.
-- Each `inventory.yaml` host entry carries a `doc_page:` field pointing at its narrative page.
-  Changing where a page lives means updating that field (read by `bin/homelab`).
+`seeds/knowledge.yaml` has three top-level lists — `documents`, `investigations`, `runbooks` — each
+entry carrying `slug`, `title`, `content` (markdown), and tags. `internal/knowledge/seed.go`
+ingests each entry by:
+
+1. `getOrCreateEntity` — ensures the slug exists in `entities` (type `document` / `investigation` /
+   `runbook`).
+2. `upsertKnowledgeEntity` — writes the markdown body into `knowledge_entities`, keyed by
+   `content_hash` so re-ingest is a no-op when nothing changed.
+3. `createEdge` — links the knowledge entity to its subject(s) via `documents` (for `document`) or
+   `about` (for `investigation`) edges. Runbooks bind to an `entity_type` via `applies_to_type`
+   rather than to a single entity.
+
+### Runtime mutation
+
+Agents register or update knowledge through the API, not by editing the seed:
+
+- `POST /api/v1/knowledge/{entity_slug}` — upsert a document/investigation on an entity
+  (`upsert_knowledge` MCP tool).
+- `update_entity_attributes` — merge a discovered fact (IP, version, port) into an entity.
+- `create_relationship` — record a discovered edge (`depends-on`, `hosts`, `routes-to`).
+
+> **Export gap.** `oikos export` regenerates `seeds/{ontology,inventory,policy}.yaml` from the DB
+> for version control, but **not** `seeds/knowledge.yaml`. Knowledge added via the API today lives
+> only in the DB until someone hand-edits the seed. Tracked as a follow-up.
+
+## Knowledge kinds
+
+- **Documents** (`document` entities, linked via `documents` edges) — node and cross-cutting
+  narrative pages. Carry `at_glance` (structured attributes) and a parsed `changelog`. Follow the
+  container / cross-cutting templates in [page-templates.md](../../shared/page-templates.md).
+- **Investigations** (`investigation` entities, linked via `about` edges) — incident evidence,
+  written once at incident time. Sections: `## Summary`, `## Timeline`, `## Root cause`,
+  `## Mitigations applied`, `## Open questions`.
+- **Runbooks** (`runbook` entities, bound by `applies_to_type`) — repeatable procedures. Carry
+  `risk_class` and a JSON-schema-validated `procedure`. **Runbooks also live as `SKILL.md` files
+  under `.agents/skills/<name>/`** — the DB row is the policy/lifecycle framing, the SKILL.md is
+  the executable procedure the agent loads. See
+  [the operations schema](../operations/schema.md).
 
 ## The two logs
 
-- The per-page **`## Changelog`** records infrastructure changes and is machine-parsed
-  (`get_changelog`, the Oikos ledger). Keep the `### YYYY-MM-DD — title` shape.
-- **`knowledge/log.md`** is append-only and records *documentation-maintenance* operations only
-  (restructures, source ingests, lint sweeps): `## [YYYY-MM-DD] <op> | <summary>`. It never
-  duplicates the Oikos change ledger (`oikos/ledger.py`).
+- The per-document **`## Changelog`** records infrastructure changes to that node. Keep the
+  `### YYYY-MM-DD — title` shape so the parsed `changelog` field stays structured.
+- **`archive/knowledge/log.md`** is the append-only record of *documentation-maintenance*
+  operations on the legacy wiki (restructures, source ingests, lint sweeps):
+  `## [YYYY-MM-DD] <op> | <summary>`. It is frozen with the rest of `archive/knowledge/`; new
+  doc-maintenance operations are recorded in the DB audit trail instead.
+
+## Querying knowledge
+
+Use MCP, not grep:
+
+- `search_knowledge(query)` — ILIKE search over documents, investigations, and runbooks in
+  `knowledge_entities`.
+- `get_entity_knowledge(entity_slug)` — every document, investigation, and runbook linked to one
+  entity, in one call.
+- `get_entity(slug)` / `get_relations(entity)` — the structured graph around an entity.
+
+Grep the clone only when MCP is unreachable, and prefer `archive/knowledge/` for historical
+narrative (it is not updated when the DB changes).
 
 ## Same-session update rule
 
-A change to a node updates every page that references it in the same session — the node page, the
-section `README.md` table, the root `README.md`, the Caddy/DNS/ingress pages, the host page, and
-`inventory.yaml`. See [page-templates.md](../../shared/page-templates.md#same-session-update-rule).
+A change to a node updates the DB in the same session — the entity's attributes, the relationships
+that reference it, and any document whose `at_glance` or changelog should reflect the new state. See
+[page-templates.md](../../shared/page-templates.md#same-session-update-rule) for the legacy wiki
+equivalent (now scoped to `archive/knowledge/` history).

.agents/domains/operations/schema.md

@@ -6,9 +6,10 @@ follows [writing-style](../../shared/writing-style.md); runbooks and plans use t
 exception.
 
 Where each kind lives: runbooks are skills under [`.agents/skills/`](../../skills/); operator
-reference (command cheatsheet, enrollment, Hermes agent) lives in
-[`.agents/operations/`](../../operations/); investigations are sources under
-`knowledge/sources/investigations/`; plans stay in the repo-root `plans/` folder (below).
+reference (command cheatsheet, enrollment, Nomos agent) lives in
+[`.agents/operations/`](../../operations/); investigations are `investigation` entities in the DB
+(historically `archive/knowledge/sources/investigations/`); plans stay in the repo-root `plans/`
+folder (below).
 
 ## Plans always live in `plans/`
 
@@ -21,7 +22,7 @@ message.** An agent drafting a plan:
 3. On completion, moves it to `plans/done/` and updates the index status.
 
 This is the single source for homelab design intent; keeping it in-repo means the plan is
-versioned, reviewable, and reachable by MCP `get_page`/`search_docs` like any other doc.
+versioned, reviewable, and reachable by MCP `search_knowledge` like any other doc.
 
 ## Runbooks
 
@@ -44,12 +45,14 @@ transition: "<from> -> <to>"   # only for lifecycle runbooks
 
 ## Investigations
 
-Incident records live in `knowledge/sources/investigations/YYYY-MM-DD-slug.md` and are **evidence sources** — written
-once at incident time, then linked from the changelogs of the nodes they implicate. Sections:
-`## Summary`, `## Timeline`, `## Root cause`, `## Mitigations applied`, `## Open questions`. Resolved
-incidents move to `knowledge/sources/investigations/archive/`.
+Incident records are `investigation` entities in the DB, linked to the entities they implicate via
+`about` edges. They are **evidence sources** — written once at incident time, then back-linked from
+the changelogs of the nodes they implicate. Sections: `## Summary`, `## Timeline`, `## Root cause`,
+`## Mitigations applied`, `## Open questions`. The legacy file-based investigations live at
+`archive/knowledge/sources/investigations/` (frozen 2026-07-07); new investigations go in the DB.
 
 ## The operations log
 
-`plans/log.md` and `knowledge/log.md` are append-only records of documentation operations on
-those areas (`## [YYYY-MM-DD] <op> | <summary>`), distinct from the Oikos change ledger.
+`plans/log.md` is the append-only record of documentation operations on plans
+(`## [YYYY-MM-DD] <op> | <summary>`), distinct from the DB audit trail. The legacy
+`archive/knowledge/log.md` is frozen with the rest of the archived wiki.

.agents/operations/agent-enrollment.md

@@ -1,365 +1,120 @@
-# Agent enrollment — bootstrap a client into the homelab context system
+# Agent enrollment — operational notes
 
-This walks through enrolling a new machine (workstation, LXC, or VM) so it
-joins the cross-client context system: a `/opt/homelab-context/` clone of
-this repo that auto-syncs every 5 min, a per-client age key for SOPS
-decryption, the `homelab` CLI, and an MCP endpoint in Claude Code's config.
+**For the actual enrollment flow, see [CLIENTS.md](../../CLIENTS.md#enrollment)
+— it's the current, authoritative version.** This page used to duplicate
+that flow in more detail, describing a `homelab` CLI-based two-step
+ceremony (`homelab client add` reserves an inventory slot → client
+bootstraps → operator finalizes the pubkey). That CLI and that flow don't
+exist anymore — enrollment today is one shot: `bootstrap.sh` calls
+`POST /api/v1/clients/enroll` directly and gets back an age keypair +
+Infisical identity in the same response. What's left here is the handful
+of things that are still true and weren't already covered elsewhere.
 
-> Onboarding a Nous-Hermes-powered Goose agent on top of standard enrollment?
-> See [nomos-agent.md](nomos-agent.md). It uses the same `bootstrap.sh`
-> with an additional `--with-nomos` flag.
-
-Architecture in [project_homelab_context_plan](https://… memory link); the
-operational reference is here.
-
-## Prerequisites the client must satisfy
+## Prerequisites
 
 | Requirement | Why | How to check |
 | --- | --- | --- |
-| Hostname matches an entry in `inventory.yaml` | The bootstrap looks up `hosts/$(hostname).yaml`. | `hostname` (Linux) / `scutil --get LocalHostName` (macOS) |
+| Hostname matches an entry in `inventory.yaml` | `EnrollClient` looks up the entity by slug derived from hostname; it must exist in `planned`/`provisioning` state. | `hostname` (Linux) / `scutil --get LocalHostName` (macOS) |
 | OS is Linux or macOS | bootstrap detects via `uname -s` | `uname -s` |
-| On the mesh (Netbird or Tailscale) **or** on the LAN | issuance is gated to mesh + LAN subnets. **For Netbird: use a setup-key, not interactive auth** — see "Getting onto Netbird" below. | `netbird status` / `tailscale status` |
-| `git`, `python3`, `python3-yaml`, `age`, `sops` | bootstrap preflight; `homelab` CLI imports yaml | See per-OS commands below |
-| Can resolve `*.hubris.network` | bootstrap calls `https://secrets.hubris.network/issue` and writes `https://mcp.hubris.network/mcp` | `dig +short mcp.hubris.network` (should return `192.168.8.175`) |
+| On the mesh (Netbird) **or** on the LAN | enrollment validates mesh IP against expected subnets | `netbird status` |
+| `curl`, `jq`, `age`, `python3` | bootstrap preflight (`bootstrap.sh:100`) — auto-installed on Fedora/RHEL/Debian/Ubuntu/macOS if missing | `command -v curl jq age python3` |
+| Can resolve `*.hubris.network` | bootstrap calls the Oikos API and writes `https://mcp.hubris.network/mcp` | `dig +short mcp.hubris.network` |
 
 ### Hostname mismatch is the most common bootstrap failure
 
-If the bootstrap exits with `no hosts/<name>.yaml in the repo`, the
-hostname doesn't match any inventory entry. Two fixes:
+If the entity for your hostname doesn't exist yet (in `planned` or
+`provisioning` state), enrollment 4xxs. Two fixes:
 
-- **Rename the host**: `sudo hostnamectl set-hostname <inventory-name>`
-  (Linux) or System Preferences → Sharing (macOS), then re-run.
-- **Rename the inventory entry**: edit `inventory.yaml` on hubris,
-  update `inventory.yaml`, push. The next sync (≤5 min) propagates.
+- **Rename the host** to match an existing planned entity:
+  `sudo hostnamectl set-hostname <inventory-name>` (Linux) or System
+  Preferences → Sharing (macOS), then re-run.
+- **Add/rename the inventory entry**: edit `seeds/inventory.yaml`, ingest
+  via `oikos seed` (or the equivalent MCP/API entity-creation path), then
+  re-run bootstrap.
 
-### Getting onto Netbird
+### Networking prerequisites (Netbird, DNS, SSH key distribution)
 
-Bootstrap auto-installs netbird and drives `netbird up` if the mesh isn't already connected (since commit `<bootstrap-tier1>`). Both paths below produce the same end state: `netbird status` shows `Management: Connected`, peer IP `100.122.x.x/16`.
-
-**Path B — interactive OIDC (default; recommended):**
-
-The new client runs bootstrap straight from a fresh OS. Bootstrap installs netbird (apt/dnf/brew based on the OS), then runs `netbird up --management-url https://netbird.hubris.network --ssh-jwt-cache-ttl 86400`. A device-code URL prints inline. The operator opens it (in a browser logged into Authentik), goes through identification → password → consent, and the CLI returns `Connected`. Bootstrap then proceeds with the rest of preflight.
-
-Pre-condition: the operator must be a registered user in Authentik (typically the lab owner). The first user-login against a netbird account with existing peers is added as `pending_approval=1` and needs an sqlite promotion to `owner` — see [124-authentik.md First-time owner promotion gotcha](../../archive/knowledge/containers/106-auth-outpost.md). Only needed once per account.
-
-**Path A — setup-key (headless/scripted onboarding):**
-
-Useful for headless servers (no browser at all) or unattended cloud-init bootstraps.
-
-1. From an already-enrolled machine, log into the dashboard at `https://netbird.hubris.network/`.
-2. **Setup Keys** → Create → set reusable + expiry → copy.
-3. On the new client (after installing netbird, OR let bootstrap install it and skip its `netbird up` driver):
-   ```bash
-   sudo netbird up --setup-key <KEY> \
-                   --management-url https://netbird.hubris.network \
-                   --ssh-jwt-cache-ttl 86400
-   ```
-
-**Why we can't OIDC-login from the public internet (still open as a follow-up):**
-
-`auth.hubris.network` resolves publicly to the VPS (`82.165.190.79`), but Traefik on the VPS doesn't currently route that hostname — only `netbird.hubris.network` is exposed. A brand-new client *off the mesh* hitting `auth.hubris.network` directly gets a Traefik default 404. In practice, Path B works fine because the operator's BROWSER (which clicks the device-code URL) is usually on a network that can reach Authentik through the public IONOS IP via some path. But "fresh laptop in a coffee shop with no prior session anywhere" still gets stuck. Future-session fix: add a Traefik route on the VPS forwarding `auth.hubris.network` via the netbird-routed `192.168.8.0/24` to LXC 124.
-
-### DNS prerequisite
-
-`*.hubris.network` resolves via the split-horizon dnsmasq on LXC 124
-([dns.md](../../archive/knowledge/infrastructure/dns.md)) for LAN clients, **but only if the
-client uses 192.168.8.180 as its resolver**. Most LXCs and roaming
-workstations don't by default. Options:
-
-- **LAN client**: set DNS to 192.168.8.180 (per-interface or
-  `/etc/resolv.conf`).
-- **Off-LAN workstation on Netbird**: configure Netbird DNS forwarder to
-  point `*.hubris.network` at LXC 124.
-- **Hack-fix anywhere**: append to `/etc/hosts`:
-  ```
-  192.168.8.175  mcp.hubris.network secrets.hubris.network
-  192.168.8.175  git.hubris.network
-  ```
-  (192.168.8.175 = caddy on LXC 121, terminates all `*.hubris.network`.)
-
-If DNS isn't an option at all, override the URLs at bootstrap time:
-
-```bash
-sudo HOMELAB_GITEA_TOKEN=... \
-     HOMELAB_REPO_URL=http://192.168.8.121:3000/dtoro/oikos.git \
-     HOMELAB_ISSUANCE_NETBIRD=http://192.168.8.205:9820/issue \
-     HOMELAB_MCP_URL=http://192.168.8.205:9810/mcp \
-     bash /tmp/bootstrap.sh --with-mcp
-```
-
-## Install dependencies
-
-Bootstrap auto-installs missing prerequisites (`git`, `python3` + PyYAML, `age`, `sops`, `netbird`) on Fedora/RHEL/Debian/Ubuntu/macOS — no manual `apt`/`dnf`/`brew` needed before running it. The only thing you must have on hand BEFORE the `curl ... | sudo bash` line is `curl` itself (used to pipe the script).
-
-Manual install is still possible (e.g. for air-gapped or unusual platforms); the per-OS recipes are below for reference but optional.
-
-<details>
-<summary>Manual recipes (Fedora / Debian / macOS)</summary>
-
-```bash
-# Fedora / RHEL / Nobara
-sudo dnf install -y git python3-pyyaml age curl
-SOPS_VERSION=v3.9.4
-sudo curl -fsSL https://github.com/getsops/sops/releases/download/$SOPS_VERSION/sops-$SOPS_VERSION.linux.amd64 \
-  -o /usr/local/bin/sops && sudo chmod +x /usr/local/bin/sops
-
-# Debian / Ubuntu
-sudo apt update && sudo apt install -y git python3-yaml age curl
-SOPS_VERSION=v3.9.4
-sudo curl -fsSL https://github.com/getsops/sops/releases/download/$SOPS_VERSION/sops-$SOPS_VERSION.linux.amd64 \
-  -o /usr/local/bin/sops && sudo chmod +x /usr/local/bin/sops
-
-# macOS
-brew install git age sops
-pip3 install pyyaml   # if `python3 -c "import yaml"` fails
-```
-
-</details>
-
-## Run the bootstrap
-
-You need a Gitea read-only personal access token for the initial clone
-(the in-cluster shared PAT is encrypted at `secrets/gitea-readonly-pat.yaml`
-but a new client can't decrypt it before bootstrap — chicken-and-egg).
-Ask the operator (or generate in Gitea: Settings → Applications → Generate
-New Token → scope `read:repository`).
-
-```bash
-TOKEN=...   # your Gitea PAT, scope read:repository
-
-# Fetch bootstrap.sh from gitea (HTTPS uses split-DNS → caddy).
-curl -fsSL -u "dtoro:$TOKEN" \
-  https://git.hubris.network/dtoro/oikos/raw/branch/main/bootstrap.sh \
-  -o /tmp/bootstrap.sh
-
-# Run it.
-sudo HOMELAB_GITEA_TOKEN=$TOKEN bash /tmp/bootstrap.sh --with-mcp
-```
-
-Flags:
-
-| Flag | Effect |
-| --- | --- |
-| `--with-mcp` | Merges the homelab MCP server into `~/.claude/.mcp.json` of the invoking user |
-| `--no-secrets` | Skips age-key issuance (use when bringing up the first hosts before secrets-issuance exists) |
-| `--dry-run` | Prints actions without executing |
-
-The bootstrap is idempotent: re-running on an enrolled client just
-verifies state, re-issues the age key only if it doesn't match the
-inventory pubkey, and refreshes the sync timer + symlinks.
-
-## Verify
-
-```bash
-homelab whoami                    # prints hosts/$(hostname).yaml
-homelab list                      # shows the full topology
-homelab status                    # ping + HTTP-check across hosts/services
-homelab secret hello              # decrypt the bootstrap-test secret
-systemctl list-timers homelab-context-sync.timer
-                                  # next run within ≤5 min
-```
-
-For Claude Code: start a new session — the `homelab` MCP server appears
-in `~/.claude/.mcp.json` and registers 14 tools (8 context, 5 management,
-1 secrets-metadata).
-
-## Post-bootstrap: SSH reachability
-
-A new workstation must be reachable from other workstations and must be
-able to reach every host by short hostname. Run these steps after the
-bootstrap verify passes:
-
-### 1. Enable SSH server
-
-```bash
-# macOS:
-sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist
-
-# Linux:
-sudo systemctl enable --now sshd
-```
-
-### 2. Generate SSH key (if missing)
-
-```bash
-ls ~/.ssh/id_ed25519.pub 2>/dev/null || ssh-keygen -t ed25519 -a 100
-```
-
-### 3. Publish pubkey to the repo
-
-```bash
-cp ~/.ssh/id_ed25519.pub /opt/homelab-context/ssh/authorized_keys/$(hostname -s).pub
-cd /opt/homelab-context && git add ssh/authorized_keys/ && git commit -m 'ssh: add $(hostname -s) pubkey' && git push
-```
-
-### 4. Deploy keys to all hosts
-
-From any existing enrolled machine (hubris or another workstation):
-
-```bash
-ssh root@192.168.8.77 "cd /opt/homelab-context && git pull --ff-only && bash ssh/deploy-keys.sh"
-```
-
-This adds the new workstation's pubkey to hubris and every running LXC.
-
-### 5. Generate SSH config
-
-```bash
-homelab ssh-config --install
-```
-
-Verify:
-
-```bash
-ssh hubris hostname     # should return "hubris" without password
-ssh gitea hostname      # should return "gitea" without password
-ssh mac-mini hostname   # should return "mac-mini" without password (workstation-to-workstation)
-```
-
-### 6. Add LAN IP to inventory (if on LAN)
-
-If the workstation has a static or reserved LAN IP, add it to
-`inventory.yaml`:
-
-```yaml
-hosts:
-  your-hostname:
-    lan_ip: 192.168.8.xxx
-```
-
-This gives it a primary LAN entry in the generated SSH config (faster
-than the Netbird fallback). Commit + push, then:
-
-```bash
-cd /opt/homelab-context && git pull --ff-only && homelab ssh-config --install
-```
+Migrated to a runbook in the knowledge base — query
+`search_knowledge("netbird mesh dns")` or `get_entity_knowledge`, or ask
+Nomos. Covers: getting onto the Netbird mesh (interactive OIDC vs.
+setup-key), why OIDC login can fail from off-mesh, split-horizon DNS
+options, and distributing a new workstation's SSH pubkey across the fleet
+via `ssh/deploy-keys.sh`.
 
 ## Claude Code permissions for fleet ops
 
 By default Claude Code's auto-mode classifier asks for confirmation on every
-ssh into the mesh. The bootstrap already installs the ssh ControlMaster block
-so subsequent in-session sshes multiplex, but the *first* ssh of each session
-still gets classifier-evaluated. Pre-authorize the common fleet ssh patterns
-by adding to `~/.claude/settings.json`:
+ssh into the mesh. Pre-authorize the common fleet ssh pattern by adding to
+`~/.claude/settings.json`:
 
 ```json
 {
   "permissions": {
     "defaultMode": "auto",
     "allow": [
-      "Bash(ssh -p 22022 *)",
-      "Bash(homelab *)"
+      "Bash(ssh -p 22022 *)"
     ]
   }
 }
 ```
 
-The first rule covers any ssh to a mesh peer on the homelab netbird port; the
-second covers all `homelab` CLI invocations. Both are scoped tight enough that
-the classifier doesn't gate them but loose enough to handle the variety of
-arguments.
+This covers any ssh to a mesh peer on the homelab netbird port, scoped tight
+enough that the classifier doesn't gate it but loose enough to handle the
+variety of arguments.
 
-If you also want the netbird `--ssh-jwt-cache-ttl` flag rationale to be
-visible to the classifier (it's not actually durable in 0.71.2, but the
-ControlMaster block is — see [runbook-dpkg-interrupted](../skills/runbook-dpkg-interrupted/SKILL.md)
-for context), drop a free-text rule into `autoMode.allow` describing the
-authorization. Optional.
+## Open questions (not verified against current architecture — don't
+guess these from the old flow)
 
-## Adding a new client to inventory
+The old two-step ceremony had answers for these; the current one-shot
+`/api/v1/clients/enroll` flow may handle them differently and this hasn't
+been re-verified:
 
-If the hostname you want isn't yet in inventory, enrollment is a two-step
-ceremony driven from an existing enrolled client (e.g. hubris). The
-`homelab` CLI handles steps 1 + 4; you provide steps 2 + 3.
-
-```bash
-# 1. On hubris (or any existing client): add the inventory entry.
-homelab client add my-new-machine
-# Prompts for kind, os, netbird FQDN, role. Commits + pushes.
-
-# 2. Join the new machine to Netbird (out-of-band, Netbird console / setup key).
-
-# 3. On the new machine: install deps + run bootstrap (above).
-#    Bootstrap calls /issue, receives a fresh age keypair, and prints the
-#    public key for the operator to commit back to inventory.
-
-# 4. On hubris: finalize the age public key.
-homelab client add my-new-machine --finalize-pubkey age1...
-# Updates inventory.yaml hosts.my-new-machine.age_pubkey, regenerates
-# inventory.yaml, commits + pushes. The 5-min sync propagates.
-```
-
-## Granting a secret to a new client
-
-Adding a client doesn't grant them every secret. Recipients are explicit
-per file via `.sops.yaml` glob rules. To grant a client access to (say)
-`secrets/hello.yaml`:
-
-1. Edit `.sops.yaml` at the repo root, add the client's `age_pubkey` to
-   the matching `creation_rules` block.
-2. Re-key the existing ciphertext for the new recipient list:
-   ```bash
-   sops updatekeys -y secrets/hello.yaml
-   ```
-3. Commit + push. On the next sync (≤5 min), the client can decrypt.
-
-## Removing a client
-
-```bash
-# From any existing client:
-homelab client remove my-old-machine
-```
-
-This:
-1. Removes the inventory entry and `hosts/my-old-machine.yaml`.
-2. Runs `sops updatekeys -y` against every file in `secrets/` (operator
-   must first remove the pubkey from `.sops.yaml` rules).
-3. Calls `secrets-issuance` `/revoke` (admin-token-gated, on LXC 105) to
-   shred the key file and add the hostname to the denylist.
-4. Commits + pushes.
-
-The CLI prints a follow-up checklist that the operator must do manually:
-
-- Revoke the peer in the Netbird console (denies future mesh access).
-- **Rotate any credentials whose ciphertext the removed client already
-  has on disk.** The age key revocation only protects *future*
-  ciphertext; what's already been pulled is still decryptable until the
-  underlying credential changes.
-- Optional: `homelab nuke my-old-machine` SSHes in, shreds
-  `/etc/age/key.txt`, removes `/opt/homelab-context`, disables sync.
+- **Removing a client.** No current equivalent confirmed for the old
+  `homelab client remove` (inventory removal + secret re-keying + key
+  revocation). Likely maps to an entity lifecycle transition
+  (`.agents/skills/lifecycle-deprecate-node/` or `lifecycle-destroy-node/`)
+  but those skills reference the same dead CLI and need their own check.
+- **Granting a secret to an already-enrolled client.** The old flow
+  hand-edited `.sops.yaml` `creation_rules` + `sops updatekeys`. Given
+  Infisical is now the primary secrets backend (SOPS is the DR fallback),
+  the current mechanism is probably Infisical-side, not a `.sops.yaml` edit
+  — not confirmed.
 
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `no hosts/<hostname>.yaml in the repo` | Hostname doesn't match inventory entry | Rename either side (see above) |
-| `fatal: could not read Username for 'http://192.168.8.121:3000'` | bootstrap.sh's credentials file has wrong scheme | Fixed in commit `de6f8be`; pull latest `bootstrap.sh` |
-| `gnutls_handshake() failed: TLS connection was non-properly terminated` cloning `git.hubris.network` | Client DNS resolves `*.hubris.network` to the public VPS IP | Configure split-DNS (LXC 180 / Netbird forwarder) or `/etc/hosts` override; or use `HOMELAB_REPO_URL=http://192.168.8.121:3000/dtoro/oikos.git` |
-| `TLS/SSL connection has been closed (EOF)` connecting MCP | Same — `mcp.hubris.network` resolves to public VPS without this vhost | Same DNS fix |
-| `Invalid Host header` from MCP server | FastMCP's DNS-rebinding protection (default whitelist is 127.0.0.1 only) | Fixed in commit `6848640`; pull latest `mcp/server.py` and redeploy |
-| `python3-yaml` install fails on Fedora | Wrong package name | Use `python3-pyyaml` (Fedora) instead of `python3-yaml` (Debian) |
-| `address already in use` for FastMCP | FastMCP defaults to 127.0.0.1:8000 | Fixed: server now sets `mcp.settings.host/port` from env (default `0.0.0.0:9810`) |
-| `homelab: no age key at /etc/age/key.txt` even after bootstrap | `/etc/age` is 0700 root, so non-root users couldn't even stat the key file; existence check returned False under regular users | Fixed in commit `df6aca8`: the CLI re-execs `sops -d` via sudo when invoked as a non-root user. On older deployments, re-link the CLI with `sudo ln -sfn /opt/homelab-context/bin/homelab /usr/local/bin/homelab` after the 5-min sync. |
-| `homelab` CLI doesn't pick up repo updates | Pre-`02db…` bootstrap copied the binary instead of symlinking | One-time migration: `sudo ln -sfn /opt/homelab-context/bin/homelab /usr/local/bin/homelab`. New bootstraps use the symlink, which auto-tracks the synced repo. |
-| `homelab-context-sync.service` journal shows `fatal: could not read Username for 'https://git.hubris.network'` | Pre-fix bootstrap set the gitea credential helper via `git config --global`, which writes to `/root/.gitconfig` — invisible to the systemd timer's git process (no HOME set). | One-time migration: `sudo git config --system credential.helper "store --file=/etc/homelab-context/git-credentials"`. New bootstraps store the helper in `/etc/gitconfig` instead. |
+| Enrollment 404s / entity not found | Hostname doesn't match a `planned`/`provisioning` inventory entry | See "Hostname mismatch" above |
+| `gnutls_handshake() failed` / TLS errors reaching `*.hubris.network` | Client DNS resolves `*.hubris.network` to the public VPS instead of the LAN/mesh path | See the networking runbook (split-horizon DNS section) |
 | Chat-mode `!` shell can't `sudo` (`a terminal is required to read the password`) | Claude Code's `!` invocation doesn't allocate a tty, and standard `sudo` won't read its password from stdin or a non-tty pipe. | Run the sudo'd command in a real terminal outside chat. For commands the agent issues repeatedly, configure passwordless sudo for the narrow set (e.g. `/etc/sudoers.d/homelab-self` with `<user> ALL=(ALL) NOPASSWD: /usr/bin/dnf upgrade -y, /usr/bin/apt-get *`). |
-| `netbird status -d` reports `192.168.8.180:53 ... is Unavailable` but DNS actually works | netbird's UDP-53 probe times out over the relay latency (~90ms), but actual queries still flow through systemd-resolved. Cosmetic. | Ignore unless `dig @192.168.8.180 git.hubris.network` also fails — then check dnsmasq on [LXC 124](../../archive/knowledge/containers/106-auth-outpost.md). |
-| `netbird ssh` rejected with `JWT authentication failed: validate token (expected issuer=https://netbird.hubris.network/oauth2 ...)` | Peer's SSH JWT validator cached the OLD embedded-Dex issuer from before the 2026-05-21 Authentik migration. `systemctl restart netbird` and `netbird down/up` don't clear it — `client/internal/engine_ssh.go` bails out of `updateSSH()` if the SSH server is already running. | Full daemon bounce: `sudo systemctl stop netbird; sleep 3; sudo systemctl start netbird`. Verify with `grep -iE "issuer\|audience" /var/log/netbird/client.log \| tail`. Apply once per peer post-migration. |
-| `netbird ssh` JWT passes but session closes with `user privilege check failed: user dtoro not found: unknown user dtoro` | netbird-ssh defaults the remote username to the LOCAL one (operator's laptop user). Hubris and LXCs only have `root`. | Always use explicit `root@` prefix manually: `netbird ssh -p 22022 root@proxmox-server.netbird.selfhosted`. `homelab ssh <host>` does this automatically via `inventory.yaml`'s per-host `ssh.user` field (defaults to `root`). |
-| `homelab ssh hubris` (or any host on the LAN) fails with `Connection refused` or hangs, despite mesh routing being up | Off-LAN networks (operator on a VPN / coffee shop / symmetric NAT) sometimes can't reach the LAN IP even with the netbird subnet route. | Newer homelab CLIs probe the LAN with a 1.5s TCP connect and transparently fall back to the netbird FQDN. If your `/usr/local/bin/homelab` is a symlink to `/opt/homelab-context/bin/homelab` it'll pick up the fix on the next 5-min context sync. Otherwise pull the latest from gitea. |
 
 ## Changelog
 
-### 2026-06-02 — SSH reachability post-bootstrap steps
-Added a new "Post-bootstrap: SSH reachability" section covering SSH key
-generation, pubkey publication, deployment to hosts, SSH config generation,
-and LAN IP registration. New workstations enrolled via this doc will
-automatically join the universal SSH mesh.
-### 2026-05-31 — cross-link to nomos-agent.md
+### 2026-07-12 — trimmed to current architecture
+Removed everything describing the retired `homelab` CLI-based two-step
+enrollment ceremony (now: `CLIENTS.md`'s one-shot flow), the Nous-Hermes/
+Goose cross-link (that whole flow was removed the same day), and CLI-syntax
+troubleshooting rows with no current equivalent. Migrated the still-true
+Netbird/DNS/SSH-distribution content to a knowledge-base runbook rather
+than duplicating it here. What's left is genuinely current or explicitly
+flagged as unverified. Original ~365-line version is in git history
+(`git log -- .agents/operations/agent-enrollment.md`) if any of the removed
+detail turns out to still be needed.
 
-Added a sibling page covering Nous-Hermes-on-Goose enrollment ([nomos-agent.md](nomos-agent.md)) and noted it at the top of this page. The Nomos flow extends `bootstrap.sh` with `--with-nomos` and `homelab client add` with the same flag; it does not change the underlying enrollment steps documented here.
+### 2026-06-02 — SSH reachability post-bootstrap steps
+Added a section covering SSH key generation, pubkey publication,
+deployment to hosts, SSH config generation, and LAN IP registration. New
+workstations enrolled via this doc automatically join the SSH mesh.
+(Superseded 2026-07-12 — migrated to the networking runbook.)
+
+### 2026-05-31 — cross-link to nomos-agent.md
+Added a sibling page covering Nous-Hermes-on-Goose enrollment. (Removed
+2026-07-12 along with the rest of that flow.)
 
 ### 2026-05-21 — netbird-ssh JWT issuer + username + LAN-fallback troubleshooting rows
-Added three rows to the troubleshooting table covering issues surfaced during the netbird vanilla migration: (1) post-migration SSH JWT validator cache stuck on old Dex issuer (full `systemctl stop/start` required, not `restart`), (2) `user not found` from netbird-ssh's local-username default (use explicit `root@`), and (3) homelab CLI's LAN→netbird-FQDN fallback for off-LAN operators. Companion code change: per-host `ssh.user` field in `inventory.yaml` + `homelab` CLI's `ssh_target()` helper.
+Added three rows to the troubleshooting table covering issues surfaced
+during the netbird vanilla migration. (Migrated 2026-07-12 to the
+networking runbook.)
 
 ### 2026-05-20 — initial page
 Captures the enrollment flow validated during Phase 2 of the homelab

.agents/operations/commands.md

@@ -49,38 +49,40 @@ Run from the [hubris host](../../archive/knowledge/hosts/hubris.md) as root. Whe
 - `ras-mc-ctl --errors` — full event log
 - `cat /sys/devices/system/cpu/cpu0/cpufreq/energy_performance_preference` — should be `balance_power`
 - `cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor` — should be `powersave`
-- `ls /sys/fs/pstore/ /var/lib/systemd/pstore/` — panic traces from a previous crash (empty for pure hardware hangs — see [investigation](../../archive/knowledge/investigations/archive/2026-04-21-hubris-crash-loop.md))
+- `ls /sys/fs/pstore/ /var/lib/systemd/pstore/` — panic traces from a previous crash (empty for pure hardware hangs — see [investigation](../../archive/knowledge/investigations/2026-04-21-hubris-crash-loop.md))
 
 ## Fleet apt operations
 
-Two `homelab` subcommands wrap the common patterns; both fan out to hubris + every LXC.
-
-| Command | What it does |
-| --- | --- |
-| `homelab apt-audit [--target HOST]` | Per-host table: dpkg-interrupted state, holds, upgradable count, non-apt binaries in system paths, DNS health. Exits nonzero if any host has dpkg-interrupted state. |
-| `homelab apt-upgrade --target HOST` | Launch `apt update && apt upgrade` inside a transient `systemd-run --collect` unit on the target. Survives ssh teardown. Apt configured with `Acquire::Retries=3` + `ForceIPv4=true`. |
-| `homelab apt-upgrade --all` | Same, fanned out across the standard targets. |
-| `homelab apt-upgrade ... --status` | Show running unit + tail `/var/log/homelab-apt-upgrade.log` on each target. |
-| `homelab apt-upgrade ... --safe` | Take a pre-upgrade snapshot per LXC first (`pct snapshot` → `vzdump` fallback for bind-mounted LXCs). Refuses if any snapshot fails unless `--force`. |
-| `homelab apt-upgrade ... --force` | Skip both the dpkg-audit gate and snapshot-failure refusal. |
-
-PVE/kernel deferral on hubris: `homelab apt-upgrade --target hubris` will try every upgrade, including kernel + `pve-*`. To skip those, `apt-mark hold` the relevant packages on hubris first; `homelab apt-audit` shows held packages so you can confirm.
+**No current CLI equivalent.** `homelab apt-audit`/`apt-upgrade` (dpkg-state
+audit, fanned-out apt upgrade with pre-upgrade snapshots) were part of the
+retired Python `homelab` CLI and don't have a ported replacement — apt
+patching today is ad hoc `run` MCP tool calls per host, without the
+audit/snapshot/status wrapping this used to provide. If that wrapping is
+still wanted, it needs to be rebuilt (e.g. as a runbook driving `run`, or a
+new MCP tool) — see
+[runbook-dpkg-interrupted](../skills/runbook-dpkg-interrupted/SKILL.md) for
+the dpkg-interrupted recovery procedure specifically.
 
 ## Oikos (agent OS layer)
 
-See [OIKOS.md](../OIKOS.md) for the operating model. Quick reference:
+See [OIKOS.md](../OIKOS.md) for the operating model. The `homelab` CLI this
+section used to document is retired; the actual current interface is the
+MCP tool catalog in [AGENTS.md §3](../../AGENTS.md#3-the-mcp-server) plus
+the REST API. Closest current equivalents for what used to live here:
 
-| Command | What it does |
+| Old `homelab` command | Current equivalent |
 | --- | --- |
-| `homelab service <name> explain\|health\|docs\|log\|actions\|history` | Service Console v0 — context card, cached health (`--live` to force a probe), docs, logs, safe actions + risk class, ledger history |
-| `homelab node <name> relations` | Ontology blast-radius query: what this host/service impacts, is affected by, and its full transitive blast radius |
-| `homelab change preflight <service>` | Dry-run report before mutating: risk class, current health, config repo, verification command |
-| `homelab decide <action> <entity>` | Decision classifier: risk × blast radius × confidence → auto-act or escalate |
-| `homelab signal list\|raise\|ack\|resolve\|mute` | The attention layer — pending updates, thresholds, drift, anything needing attention |
-| `homelab approval request\|list\|reply\|check` | Escalate-route grants (Matrix-delivered via Nomos, or the Oikos Console's `/approvals` page) |
-| `homelab restart <service> [--approval-id <id>]` | `--approval-id` is required whenever the service's risk class needs approval (e.g. `caddy`, `dns`) — refuses mechanically without a valid grant |
+| `homelab service <name> explain\|health\|docs\|log` | MCP `explain`, `get_service_status`, `tail_log`, `get_entity_knowledge` |
+| `homelab node <name> relations` | MCP `get_blast_radius` |
+| `homelab change preflight <service>` | MCP `preflight` |
+| `homelab signal list\|ack\|resolve\|mute` | MCP `get_signal_history`, or REST `POST /api/v1/signals/{id}/ack\|resolve\|mute` (the control-room UI's Signals page wraps these) |
+| `homelab approval request\|list\|reply\|check` | REST `GET/POST /api/v1/approvals*` (Matrix-delivered via the notifier, or the control-room UI's Operations page) |
+| `homelab restart <service> --approval-id <id>` | MCP `run` (policy-gated — auto-executes if read-only/reversible_low, otherwise queues for the same Matrix/UI approval) |
+| `homelab decide <action> <entity>` | No direct equivalent — classification now happens inline inside `run`, not as a separate dry-run call |
 
-Oikos Console (read-mostly dashboard): `oikos.hubris.network` once deployed — see [oikos/console/deploy/README.md](../../archive/oikos-cards/).
+There is no separately-deployed "Oikos Console" anymore — the control-room
+SPA (`web/`) is the operator dashboard, served standalone (see
+[plans/done/2026-07-12-wails-desktop-app.md](../../plans/done/2026-07-12-wails-desktop-app.md)).
 
 ## Related
 - [Hubris host](../../archive/knowledge/hosts/hubris.md)

.agents/operations/nomos-agent.md

@@ -1,210 +0,0 @@
-# Nomos agent — LLM-powered terminal sessions on a homelab client
-
-Onboards [Nous Research's Hermes](https://nousresearch.com/) (a fine-tuned
-Llama variant) as a working terminal agent on a homelab client. Builds on top
-of standard client enrollment (see [agent-enrollment.md](agent-enrollment.md))
-— this page covers only the Hermes-specific additions.
-
-The agent runs as a [Goose](https://goose-docs.ai/) session. Goose provides:
-
-- The chat loop, multi-turn history, and streaming
-- The OpenRouter provider that routes to the configured LLM
-- The built-in `developer` extension (shell + file editor — same surface Claude
-  Code has)
-- A remote MCP extension pointed at `mcp.hubris.network` for read-only
-  homelab context (`list_lxcs`, `tail_log`, `search_docs`, etc.)
-
-The persona is `/opt/homelab-context/NOMOS.md`, symlinked as Goose's global
-`.goosehints` so it's injected into the system prompt on every session.
-
-## Prerequisites
-
-| Requirement | How |
-| --- | --- |
-| Standard enrollment complete (`homelab whoami` works) | [agent-enrollment.md](agent-enrollment.md) |
-| `secrets/openrouter-api-key.yaml` exists with a real `sk-or-...` value | See "Seeding the OpenRouter key" below |
-| The host's `age_pubkey` is on the openrouter-api-key.yaml sops rule | `homelab client add <host> --finalize-pubkey <age1...> --with-nomos` |
-
-## Onboarding flow
-
-```bash
-# 1. On hubris (or any enrolled client): reserve the inventory entry.
-homelab client add new-machine
-
-# 2. Join new-machine to Netbird (setup-key or OIDC).
-
-# 3. On new-machine: bootstrap with --with-nomos.
-TOKEN=...   # gitea PAT, read:repository
-curl -fsSL -u "dtoro:$TOKEN" \
-  https://git.hubris.network/dtoro/oikos/raw/branch/main/bootstrap.sh \
-  -o /tmp/bootstrap.sh
-sudo HOMELAB_GITEA_TOKEN=$TOKEN bash /tmp/bootstrap.sh --with-mcp --with-nomos
-
-# 4. Back on hubris: finalize the age pubkey AND grant the Nomos secret.
-homelab client add new-machine \
-  --finalize-pubkey age1... \
-  --with-nomos
-
-# 5. Wait ≤5 min for sync, then on new-machine:
-nomos "what LXCs are running?"
-```
-
-The bootstrap `--with-nomos` flag does five things, all idempotent:
-
-1. Downloads the latest Goose binary into the operator's `~/.local/bin/goose`
-   (upstream installer) and symlinks `/usr/local/bin/goose` to it.
-2. Symlinks `/opt/homelab-context/bin/nomos` → `/usr/local/bin/nomos`.
-3. Symlinks `/opt/homelab-context/NOMOS.md` → `/root/NOMOS.md` (Linux) or
-   `/etc/NOMOS.md` (macOS) for `cat`-as-operator convenience.
-4. Drops `~/.config/goose/config.yaml` pinning the provider, model, and
-   extensions (preserves any keys the operator added by hand).
-5. Symlinks `~/.config/goose/.goosehints` → NOMOS.md, so the persona is
-   injected as the system prompt on every session.
-
-## Seeding the OpenRouter key
-
-The first time anyone enrolls with `--with-nomos`, the encrypted file
-`secrets/openrouter-api-key.yaml` contains a placeholder. On hubris (or any
-existing recipient):
-
-```bash
-sops secrets/openrouter-api-key.yaml
-# editor opens; replace api_key value with the real sk-or-... key, save, close.
-git -C /opt/homelab-context add secrets/openrouter-api-key.yaml
-git -C /opt/homelab-context commit -m 'openrouter-api-key: seed real key'
-git -C /opt/homelab-context push
-```
-
-Until this step happens, `nomos …` exits with `openrouter-api-key.yaml still
-contains the placeholder`. Subsequent enrollees get the real key automatically
-via `--with-nomos` (which adds them as a sops recipient on
-`secrets/openrouter-api-key.yaml`).
-
-## Granting the OpenRouter key to an already-enrolled host
-
-If a host was enrolled without `--with-nomos` and you want to add it later:
-
-```bash
-# On hubris:
-PUBKEY=$(homelab whoami --hostname <host> | grep age_pubkey | awk '{print $2}')
-homelab client add <host> --finalize-pubkey "$PUBKEY" --with-nomos
-```
-
-`--finalize-pubkey` is required by the existing flow even when the pubkey is
-unchanged — it's also the trigger that runs the sops grant.
-
-After ≤5 min sync the host can decrypt the key. Bootstrap doesn't need to
-re-run; only the secret recipient list changed.
-
-## Verifying
-
-```bash
-homelab whoami                                # standard enrollment OK
-homelab secret openrouter-api-key | head -c 8 # decrypts (prints `api_key:`)
-which goose && which nomos                     # binaries present
-goose info -v                                  # provider/model wiring sane
-nomos "what LXCs are running?"                  # interactive Goose session
-
-# Non-interactive smoke test:
-echo "List the homelab MCP tools you have available" | nomos
-```
-
-## Configuration
-
-The bootstrap-managed keys in `~/.config/goose/config.yaml`:
-
-```yaml
-GOOSE_PROVIDER: openrouter
-GOOSE_MODEL: deepseek/deepseek-v4-flash
-GOOSE_MODE: smart_approve         # asks before destructive tool calls
-extensions:
-  developer:
-    type: builtin
-    bundled: true
-    enabled: true
-    name: developer
-    timeout: 300
-  homelab:
-    type: streamable_http
-    enabled: true
-    name: homelab
-    uri: https://mcp.hubris.network/mcp
-    timeout: 60
-```
-
-Override via env on a single bootstrap run:
-
-```bash
-HOMELAB_NOMOS_MODEL=nousresearch/hermes-3-llama-3.1-405b \
-HOMELAB_NOMOS_MCP_URI=https://mcp.hubris.network/mcp \
-  sudo bash /tmp/bootstrap.sh --with-nomos
-```
-
-Any keys you add by hand (e.g. `GOOSE_TEMPERATURE`, extra `extensions.*`) are
-preserved across re-bootstraps — the merge only overwrites the keys it manages.
-
-## Tool permissions
-
-`GOOSE_MODE: smart_approve` is the bootstrap default: Goose runs read-only
-shell commands without prompting and asks for confirmation before destructive
-ones. To make the agent fully unattended (e.g. for scheduled jobs), set
-`GOOSE_MODE: auto` in `~/.config/goose/config.yaml`. To require confirmation on
-every tool call, use `approve`. See
-[goose-permissions](https://goose-docs.ai/docs/guides/managing-tools/goose-permissions/).
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-| --- | --- | --- |
-| `nomos: could not decrypt secrets/openrouter-api-key.yaml` | Host isn't a recipient on the sops rule | `homelab client add <host> --finalize-pubkey <age1...> --with-nomos` from hubris |
-| `nomos: openrouter-api-key.yaml still contains the placeholder` | No real key has been seeded yet | See "Seeding the OpenRouter key" above |
-| Goose hangs on first `nomos` invocation with no output | Goose's interactive `configure` ran on first launch and is awaiting input | Re-run; the installer is supposed to skip it (CONFIGURE=false). If it persists, run `goose configure` once manually in a real terminal to commit the config. |
-| `homelab` extension fails to connect / no MCP tools listed | MCP server upgraded in Go rewrite (`internal/mcp/server.go`, Streamable HTTP via official MCP SDK). Old FastMCP SSE transport is deprecated. | Run `docker compose --profile full up` on mac-mini, or wait for the production cutover from apps/105. |
-| `goose: command not found` after bootstrap | Upstream installer dropped binary in `~/.local/bin/` but `/usr/local/bin/goose` symlink didn't land | Re-run bootstrap with `--with-nomos`; the symlink step is at the end of the install block. If still missing, `ln -sfn ~/.local/bin/goose /usr/local/bin/goose` manually. |
-| Tool calls hit OpenRouter rate limits | One shared key across many hosts | Future: per-host keys; for now, see the rate-limits guide referenced in `goose info -v`. |
-
-## Cross-references
-
-- [agent-enrollment.md](agent-enrollment.md) — base client onboarding the
-  Nomos flow assumes is done.
-- [`NOMOS.md`](../NOMOS.md) — the persona the Nomos agent reads on every
-  session start (via `~/.config/goose/.goosehints`).
-- [`bin/nomos`](../../bin/nomos) — the wrapper that decrypts the OpenRouter key
-  and execs `goose session`.
-- [`bootstrap.sh`](../../bootstrap.sh) — the `--with-nomos` flag's install block.
-
-## Follow-ups
-
-1. **Migrate the MCP server to streamable_http.** Goose 1.x deprecated SSE
-   (`"SSE transport is no longer supported - kept only for config file
-   compatibility"` in `crates/goose/src/agents/extension.rs`). Our FastMCP
-   server at `internal/mcp/server.go` uses Streamable HTTP (official MCP SDK). Until
-   that's changed, the `homelab` MCP extension in Goose will fail to connect.
-   The developer extension (shell + edit) covers most ops without it; this is
-   a polish item, not a blocker.
-2. **Per-host OpenRouter keys** for billing attribution. Today all Nomos
-   hosts share one key.
-3. **Pin the model version** rather than tracking `nousresearch/hermes-4-405b`
-   directly — OpenRouter periodically rotates the underlying weights.
-4. **Local-inference fallback** (ollama / vllm) once the homelab has a GPU
-   node. The wrapper, persona, and MCP wiring stay unchanged; only
-   `GOOSE_PROVIDER`/`GOOSE_MODEL` change.
-
-7. **Caveman auto-setup via post-pull hook.** The sync timer now calls
-   `tools/post-pull.sh`, which runs any `tools/*.setup.sh` after git pull.
-   Currently this auto-installs the Caveman npm package, wrapper scripts, and
-   compact output templates on all agent hosts (*token efficiency*).
-
-## Changelog
-
-### 2026-06-01 — caveman + post-pull auto-setup
-Added `tools/post-pull.sh` sync hook that auto-runs `tools/*.setup.sh`
-after every git pull. First user: `tools/setup-caveman.sh` installed Caveman
-templating + `~/bin/caveman_wrapper.sh` + `~/templates/*.txt` for token-
-efficient CLI output. Replaces raw `git pull` in launchd/systemd timers.
-Also created `tools/caveman/` with the wrapper script, JS renderer, and
-templates — the canonical source for all agent hosts.
-Captures the Nomos-on-Goose onboarding flow added in the same commit as
-`bootstrap.sh --with-nomos`, `bin/nomos`, the sops rule for
-`secrets/openrouter-api-key.yaml`, and the `homelab client add --with-nomos`
-extension. MCP streamable_http migration is queued as follow-up #1.

.agents/shared/llm-wiki.md

@@ -1,40 +1,49 @@
 # LLM Wiki — the documentation contract
 
-How the narrative documentation in this repo is organized. The pattern is borrowed from the
-`sources / wiki / index / log` model: a durable synthesized layer (`archive/knowledge/`) built on top
-of immutable evidence (`knowledge/sources/`, incident records), with pure-listing indexes and an
-append-only operations log.
+How documentation in this repo is organized. The pattern is the `sources / wiki / index / log`
+model: a durable synthesized layer built on top of immutable evidence, with pure-listing indexes and
+an append-only operations log.
 
-This contract governs the **narrative layer only**. The machine-readable substrate — `inventory.yaml`,
-`secrets/`, `scripts/`, `bin/` — is not part of the wiki and never
-moves under it. See [the knowledge schema](../domains/knowledge/schema.md) for the split.
+This contract governs the **narrative layer only**. The machine-readable source of truth — the
+Postgres database, bootstrapped from `seeds/` — is not part of the wiki and never moves under it.
+See [the knowledge schema](../domains/knowledge/schema.md) for the split, and ADR 0003 for the
+DB-native model.
 
 ## Layers
 
-- **Sources** are immutable raw material: incident records (`knowledge/sources/investigations/`), external reference
-  docs (`knowledge/sources/references/`), and the live system itself (`pct config`, `docker inspect`).
-  Read them; do not rewrite them into other sources.
-- **Wiki** (`archive/knowledge/`) is the synthesized, authoritative current-state layer: one page per
-  node (`containers/`, `vms/`, host narratives) and per cross-cutting system (`infrastructure/`). A
-  reader understands the topic from the wiki page without reading the sources.
+- **Source of truth** is the Postgres database. Structured data (entities, relationships, status,
+  metrics) and narrative knowledge (documents, investigations, runbooks) both live there, in the
+  `entities` / `relationships` / `knowledge_entities` tables. It is bootstrapped at deploy time from
+  `seeds/{ontology,inventory,policy,knowledge}.yaml` (idempotent, content-hashed via
+  `seed_versions`) and mutated at runtime via the API/MCP. `oikos export` regenerates
+  `seeds/{ontology,inventory,policy}.yaml` for version control.
+- **Sources** are immutable raw material: incident records (now `investigation` entities in the DB,
+  historically `archive/knowledge/sources/investigations/`), external reference docs, and the live
+  system itself (`pct config`, `docker inspect`). Read them; do not rewrite them into other sources.
+- **Wiki** — the synthesized, authoritative current-state layer. Today this is the set of
+  `document` entities in the DB (one per node and per cross-cutting system), queried via MCP
+  `search_knowledge` / `get_entity_knowledge`. The legacy file-based wiki is frozen at
+  `archive/knowledge/{hosts,containers,vms,infrastructure}/` for historical reference only.
 - **Index** (`index.md` / folder `README.md`) is a pure listing — every page in scope with a
   one-line summary, and nothing else. Anything the section wants to say up front goes into a page
   the index lists, not into the index.
-- **Log** (`log.md`) is append-only, recording *doc-maintenance operations* (restructures, source
-  ingests, lint sweeps) in single-line format: `## [YYYY-MM-DD] <op> | <summary>`.
+- **Log** is append-only, recording *doc-maintenance operations* (restructures, source ingests,
+  lint sweeps) in single-line format: `## [YYYY-MM-DD] <op> | <summary>`. The active log is the DB
+  audit trail; `archive/knowledge/log.md` is the frozen legacy equivalent.
 
 ## Two logs, kept distinct
 
-- **`## Changelog`** on each node/topic page records *infrastructure* changes to that node. It is
-  machine-parsed (`get_changelog`, the Oikos ledger) — keep the `### YYYY-MM-DD — title` shape.
-- **`log.md`** per area records *documentation* operations only. It never duplicates the Oikos
-  change ledger (`oikos/ledger.py`), which stays authoritative for infra changes with
-  who/what/risk/approval/verification.
+- **`## Changelog`** on each node/topic document records *infrastructure* changes to that node. It
+  is stored as a structured field on the `document` entity — keep the `### YYYY-MM-DD — title`
+  shape so it parses cleanly.
+- **Doc-maintenance logs** record *documentation* operations only. They never duplicate the
+  infrastructure changelog, which stays authoritative for infra changes with
+  who/what/risk/approval/verification (now the DB audit trail, formerly `oikos/ledger.py`).
 
 ## Rules
 
 - Wiki pages stay short and focused. A page past ~300 lines splits.
-- Pages stay flat under `wiki/<section>/` until there are enough to warrant a sub-group.
+- Pages stay flat under their section until there are enough to warrant a sub-group.
 - Every page follows [writing-style.md](writing-style.md).
 - Plans and design docs always live in the repo `plans/` folder (`plans/YYYY-MM-DD-slug.md`),
   listed in `plans/index.md`, moved to `plans/done/` on completion — never a scratch path or a chat

.agents/shared/page-templates.md

@@ -9,12 +9,12 @@ in [writing-style.md](writing-style.md); the layer model (sources / wiki / index
 **Foundational / entry-point files:** ALL-CAPS
 
 - **Root level:** `AGENTS.md`, `README.md` — discovery paths for agents and humans.
-- **Agent instruction** (under `.agents/`): `OIKOS.md`, `HERMES.md` — foundational docs agents read before acting.
+- **Agent instruction** (under `.agents/`): `OIKOS.md`, `NOMOS.md` — foundational docs agents read before acting.
 - **Reference docs:** `GLOSSARY.md` — lookup reference (like classic repo conventions: LICENSE, CHANGELOG, GLOSSARY).
 
 **Content / narrative pages:** lowercase-with-dashes, date-prefixed as needed
 
-- **Container pages:** `<id>-<name>.md` (e.g. `101-jellyfin.md`, `132-rclone.md`). The `<id>` is the LXC/VM ordinal from `inventory.yaml`.
+- **Container pages:** `<id>-<name>.md` (e.g. `101-jellyfin.md`, `132-rclone.md`). The `<id>` is the LXC/VM ordinal from the entity's attributes in the DB (seeded via `seeds/inventory.yaml`).
 - **Infrastructure / cross-cutting pages:** `<topic>.md` (e.g. `dns.md`, `auto-deploy.md`, `mesh.md`). Describes a system, not a specific node.
 - **Plans / investigations:** `YYYY-MM-DD-<slug>.md` (e.g. `2026-07-05-oikos-prometheus-lxc.md`). Date-sorted; slug is lowercase.
 - **Section indices:** `README.md` (lowercase, conventional). Prefer in folders; `index.md` only if both intro prose and listing coexist.
@@ -118,7 +118,7 @@ What it looks like after.
 Changelog entries to write, index status to update.
 ```
 
-### Investigation (`knowledge/sources/investigations/YYYY-MM-DD-slug.md`)
+### Investigation (`investigation` entity in the DB; historically `archive/knowledge/sources/investigations/YYYY-MM-DD-slug.md`)
 
 ```markdown
 # YYYY-MM-DD — <title>
@@ -152,16 +152,18 @@ Changelog entries to write, index status to update.
 ## Same-session update rule
 
 When you make a change to a node — migrate an LXC, update an IP, change a
-mount, deploy a new service — **update every relevant doc page in the same
-session.** A change that touches a container page must also update:
+mount, deploy a new service — **update the DB and every relevant doc page in
+the same session.** A change that touches a container must also update:
 
-- The `containers/index.md` table (IPs, host, mounts, status)
+- The `entities` / `relationships` rows for the node (via the API/MCP) —
+  this is the source of truth
+- The `document` entity's `at_glance` and `## Changelog` for the container
+- The `containers/index.md` table in the archived wiki (IPs, host, mounts,
+  status) — historical reference, update for consistency where still consulted
 - The `README.md` table (if the change affects listed columns)
 - The Caddy page site list (if the change affects `*.hubris.network` routing)
 - The DNS / ingress infrastructure pages (if the change affects routing)
 - The `hosts/{hubris,strong}.md` host page (if container count changes)
-- The `inventory.yaml` host entry (single source of truth)
-- The `infrastructure/topology.md` (generated from inventory, but regen if needed)
 
 The pattern of updating only one page and leaving stale references on others
 is a bug. If you're doing a multi-step migration, document the intermediate

.agents/shared/writing-style.md

@@ -36,7 +36,7 @@ Every doc-level page follows the same shape so a reader scans it in one pass.
 1. **One H1 = the page title.** Node pages use `# <id> — \`<name>\``; topic pages use `# <Topic>`.
 2. **Opening definition.** First paragraph, 1–3 sentences, says what the thing is. No motivation, no marketing, no setup.
 3. **Body sections** in the natural order for the topic. Reuse the section templates in [page-templates.md](page-templates.md).
-4. **`## Changelog`** at the bottom of every node/topic page — reverse-chronological, append-only. This section is machine-parsed (Go MCP `get_changelog` in `internal/mcp/server.go`); keep the `### YYYY-MM-DD — title` shape.
+4. **`## Changelog`** at the bottom of every node/topic page — reverse-chronological, append-only. This section is stored as a structured field on the `document` entity in the DB; keep the `### YYYY-MM-DD — title` shape so it parses cleanly.
 5. **Related links** only at the bottom, only when a reference cannot be woven inline.
 
 ## Section indexes (folder READMEs)
@@ -53,12 +53,12 @@ duplicated prose, no narrative between the intro and the table.
 - Prefer **tables** for enumerable items with internal structure (service/port maps, field lists, status grids). Reserve bullets for short non-structured lists.
 - Use the **bold-leading-phrase pattern** for structured points: `**Read-only by construction.** The MCP server never mutates state.` — a bold noun phrase, a period, then the explanation.
 - When enumerating across services or nodes, give each its own `###` sub-section or a table row, not one run-on paragraph.
-- Use backticks for code, paths, hostnames, and file names (`inventory.yaml`, `192.168.8.77`, `pct config`); italics for first-mention terminology.
+- Use backticks for code, paths, hostnames, and file names (`seeds/inventory.yaml`, `192.168.8.77`, `pct config`); italics for first-mention terminology.
 - Use `>` blockquotes for caveats and gaps that interrupt the main flow: `> **Outstanding gap.** DNS-vs-inventory drift check not yet wired.` One thought per blockquote.
 
 ## Diagrams
 
-- Mermaid is the default for topology and flow diagrams. `infrastructure/topology.md` is generated by `oikos/gen-topology.py` — do not hand-edit it. (Go DB-native topology generation planned.)
+- Mermaid is the default for topology and flow diagrams. `infrastructure/topology.md` in the archived wiki was generated by the retired `oikos/gen-topology.py`; the DB-native equivalent is a future task — do not hand-edit the archived file expecting it to regenerate.
 - ASCII box diagrams are fine for small shape diagrams; keep them to one screen.
 
 ## Sourcing and cross-references

.agents/skills/client-enrollment/SKILL.md

@@ -2,39 +2,46 @@
 name: client-enrollment
 risk_class: config_mutation
 inputs: [hostname, kind, role]
-verification: "homelab doctor (on the new client)"
+verification: "MCP whoami(hostname) shows the entity active"
 docs_update_checklist: [hosts_narrative_page_if_lxc_or_vm]
 ---
 
 # Client enrollment
 
 Goal: bring a new host (workstation, LXC, VM) into inventory and the
-secrets model, with mesh membership only where it's actually needed.
-This wraps the existing `homelab client add` flow — see
-[operations/agent-enrollment.md](../../operations/agent-enrollment.md) for
-the full walkthrough; this runbook is the risk/lifecycle framing.
+secrets model, with mesh membership only where it's actually needed. See
+[CLIENTS.md](../../../CLIENTS.md#enrollment) for the actual current
+flow and [operations/agent-enrollment.md](../../operations/agent-enrollment.md)
+for operational notes; this runbook is the risk/lifecycle framing.
 
-1. On any enrolled client: `homelab client add <hostname>` — appends a
-   `hosts.<name>:` block to `inventory.yaml` (lifecycle `state: planned`
-   → `provisioning`, per [seeds/ontology.yaml](../../../seeds/ontology.yaml)),
-   commits + pushes.
+1. The entity must exist in `planned`/`provisioning` state before the new
+   host can self-enroll — add a `hosts.<name>:` block to
+   `seeds/inventory.yaml` and `oikos seed` to ingest it (lifecycle
+   `planned` → `provisioning`, per
+   [seeds/ontology.yaml](../../../seeds/ontology.yaml)).
 2. Netbird join is **optional, not a required step** — only needed for
    hosts that must be reachable off-LAN (workstations that roam, e.g.
-   `republic-laptop`, `mac-mini`). A node reachable on the household LAN
-   (192.168.8.0/24 — most LXCs/VMs) doesn't need it: it's already
-   reachable directly, and off-LAN clients reach it too via hubris's
-   routed `192.168.8.0/24` Netbird network resource. Skip this step for
-   LAN-only nodes; do it (out-of-band, console or setup key) only for
-   hosts that need independent off-LAN reachability.
-3. On the new host: run `bootstrap.sh` (add `--with-nomos` to also
-   enroll the Hermes agent). This provisions `/etc/age/key.txt`, the
-   sync timer, and prints an age pubkey.
-4. Back on an enrolled client: `homelab client add <hostname>
-   --finalize-pubkey <age1...>` — sets `age_pubkey`, grants shared
-   secrets, re-keys SOPS, commits + pushes. This is the
-   `provisioning → active` transition.
-5. Verify: `homelab doctor` on the new client should show all checks
-   green (clone, sync timer, age key, CLI symlink, MCP reachable).
+   `mac-mini`). A node reachable on the household LAN (192.168.8.0/24 —
+   most LXCs/VMs) doesn't need it. Skip for LAN-only nodes; do it
+   (out-of-band, console or setup key) only for hosts that need
+   independent off-LAN reachability.
+3. On the new host: run `bootstrap.sh`. This calls
+   `POST /api/v1/clients/enroll`, which validates the entity exists and
+   the mesh IP is in an expected subnet, then returns an age keypair and
+   Infisical machine identity in one response — provisions
+   `/etc/age/key.txt`, `/etc/infisical/identity`, and the context poller.
+4. **Known gap, confirmed 2026-07-12: `provisioning → active` has no
+   working path.** `EnrollClient` (`internal/httpapi/impl.go`) sets the
+   entity's state to `provisioning`, never `active`. `bootstrap.sh` prints
+   `POST /api/v1/clients/ws:$HNAME/activate` as the next step, but that
+   route doesn't exist — `api/openapi.yaml` only has `/clients/enroll`,
+   `/clients/{slug}/context`, `/clients/{slug}/secrets`. Until this is
+   fixed (add the route, or use the generic entity PATCH to flip `state`),
+   a freshly-enrolled client is stuck in `provisioning` — MCP `preflight`
+   and policy's `lifecycle_overrides` for `provisioning` still apply, but
+   nothing transitions it onward automatically.
+5. Verify: MCP `whoami(hostname)` shows the entity in `active` state with
+   its peers and health.
 
 Docs-update checklist: if the new host is an LXC/VM, add its narrative
 page under `containers/` or `vms/` and set `doc_page` in its inventory

.agents/skills/config-change-deploy/SKILL.md

@@ -2,7 +2,7 @@
 name: config-change-deploy
 risk_class: config_mutation
 inputs: [service_name, change_description]
-verification: "curl -sf <service_url> (or homelab service <name> health)"
+verification: "curl -sf <service_url> (or MCP get_service_status)"
 docs_update_checklist: [doc_page, changelog]
 ---
 
@@ -11,11 +11,10 @@ docs_update_checklist: [doc_page, changelog]
 Goal: change a tracked config repo (Caddy, Gitea customizations, an app's
 own repo) and get it live, safely.
 
-1. `homelab change preflight <service>` — current health, the service's
-   `config_repo`, its risk class, and the verification command to run
-   after. If risk class requires approval (`config_mutation` or
-   `destructive`), stop and get operator sign-off before editing — see
-   `seeds/policy.yaml`.
+1. MCP `preflight` — current health, the service's `config_repo`, its
+   risk class, and the verification command to run after. If risk class
+   requires approval (`config_mutation` or `destructive`), stop and get
+   operator sign-off before editing — see `seeds/policy.yaml`.
 2. Clone/pull the `config_repo` (never edit the backend's working tree
    directly — tracked configs change by commit + push, per
    [OIKOS.md](../../OIKOS.md) conventions).
@@ -24,10 +23,10 @@ own repo) and get it live, safely.
    [infrastructure/auto-deploy.md](../../../archive/knowledge/infrastructure/auto-deploy.md) for
    the exact receiver/reload for this service).
 5. Run the preflight's verification command. If it fails, check
-   `homelab service <name> log` for the reload/restart error.
-6. Record the change: once `oikos/ledger.py` is wired into deploy tooling
-   (Week 3), this is automatic; until then, note the change and outcome
-   in the relevant investigation/plan doc.
+   MCP `tail_log` for the reload/restart error.
+6. No manual record-keeping step needed — mutations made through the API
+   (e.g. via the `run` MCP tool) are recorded automatically in the
+   `audit_log` table.
 
 Docs-update checklist: update the service's `doc_page` if the change
 alters its behavior, ingress route, or ownership; add a changelog entry

.agents/skills/docs-lint/lint.py

@@ -1,16 +1,17 @@
 #!/usr/bin/env python3
 """Lint committed docs against .agents/shared/writing-style.md.
 
-Checks two mechanical rules:
+Checks:
   1. Banned vocabulary (significance puffers, analytical verbs, poetic nouns,
      promotional adjectives, opening crutches).
   2. Broken relative markdown links.
+  3. Plan status consistency (status vs location vs index).
 
 Prose-voice rules are not machine-checkable; this covers the parts that are.
 Run from the repo root: python3 .agents/skills/docs-lint/lint.py [paths...]
 Exit 1 if any violation is found.
 """
-import os, re, sys
+import os, re, sys, glob
 
 BANNED = [
     "pivotal", "crucial", "vital", "groundbreaking", "transformative", "testament",
@@ -33,9 +34,125 @@ def iter_md(paths):
                 if f.endswith(".md"):
                     yield os.path.join(root, f)
 
+def check_plans():
+    """Check plan status consistency: active plans with 'Done' status, files
+    missing from index, dangling index entries, done files with wrong status."""
+    REPO = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    plans_dir = os.path.join(REPO, "plans")
+    done_dir = os.path.join(REPO, "plans", "done")
+    index_path = os.path.join(plans_dir, "index.md")
+
+    if not os.path.exists(index_path):
+        return 0
+
+    violations = 0
+    STATUS_RE = re.compile(r'^\*\*Status:\*\*\s*(.+)', re.I)
+
+    # Parse index.md for active and done entries
+    active_files = set()
+    done_files = set()
+    current_section = None
+    with open(index_path) as f:
+        for line in f:
+            if line.startswith("## Active"):
+                current_section = "active"
+                continue
+            if line.startswith("## Done"):
+                current_section = "done"
+                continue
+            if current_section == "active":
+                m = re.search(r'\]\(([^)]+)\)', line)
+                if m:
+                    active_files.add(m.group(1))
+            elif current_section == "done":
+                m = re.search(r'\]\(([^)]+)\)', line)
+                if m:
+                    done_files.add(m.group(1))
+
+    # Active plans on disk (not in done/, not index.md)
+    disk_active = set()
+    for f in glob.glob(os.path.join(plans_dir, "*.md")):
+        name = os.path.basename(f)
+        if name == "index.md":
+            continue
+        disk_active.add(name)
+
+    # Done plans on disk
+    disk_done = set()
+    if os.path.isdir(done_dir):
+        for f in glob.glob(os.path.join(done_dir, "*.md")):
+            disk_done.add("done/" + os.path.basename(f))
+
+    # Check 1: active plans on disk whose internal status is Done/Implemented/Complete
+    for name in disk_active:
+        fpath = os.path.join(plans_dir, name)
+        with open(fpath) as f:
+            for line_num, line in enumerate(f, 1):
+                if line_num > 5:
+                    break
+                m = STATUS_RE.match(line)
+                if m:
+                    status = m.group(1).strip().lower()
+                    done_keywords = ["done", "implemented", "complete", "completed"]
+                    if any(status.startswith(kw) for kw in done_keywords):
+                        print(f"{fpath}:{line_num}: status '{m.group(1).strip()}' — file is in plans/ but appears done; move to done/")
+                        violations += 1
+                    break
+
+    # Check 2: active plans on disk not in index
+    for name in sorted(disk_active):
+        if name not in active_files:
+            fpath = os.path.join(plans_dir, name)
+            print(f"{fpath}:1: not listed in plans/index.md Active table")
+            violations += 1
+
+    # Check 3: done plans on disk not in index
+    for name in sorted(disk_done):
+        if name not in done_files:
+            fpath = os.path.join(REPO, "plans", name)
+            print(f"{fpath}:1: not listed in plans/index.md Done table")
+            violations += 1
+
+    # Check 4: index entries with no file on disk
+    for name in sorted(active_files):
+        if name not in disk_active:
+            print(f"plans/index.md: active entry '{name}' — file not found on disk")
+            violations += 1
+
+    for name in sorted(done_files):
+        if name not in disk_done:
+            print(f"plans/index.md: done entry '{name}' — file not found on disk")
+            violations += 1
+
+    # Check 5: files in done/ whose internal status doesn't say Done
+    for name in disk_done:
+        fpath = os.path.join(REPO, "plans", name)
+        with open(fpath) as f:
+            found_status = False
+            for line_num, line in enumerate(f, 1):
+                if line_num > 5:
+                    break
+                m = STATUS_RE.match(line)
+                if m:
+                    found_status = True
+                    status = m.group(1).strip().lower()
+                    if not status.startswith("done"):
+                        print(f"{fpath}:{line_num}: status '{m.group(1).strip()}' — file is in done/ but status is not 'Done'")
+                        violations += 1
+                    break
+            if not found_status:
+                print(f"{fpath}:1: file is in done/ but has no Status header")
+                violations += 1
+
+    return violations
+
 def main(argv):
     paths = argv or ["knowledge", ".agents", "operations", "investigations", "plans"]
     violations = 0
+
+    if "plans" in paths or any(p.startswith("plans") for p in paths):
+        violations += check_plans()
+
     # The style guide and this skill enumerate the banned words by definition.
     ban_exempt = ("shared/writing-style.md", "skills/docs-lint/")
     for f in sorted(set(iter_md(paths))):

.agents/skills/incident-investigation/SKILL.md

@@ -10,22 +10,23 @@ docs_update_checklist: [investigations_entry]
 
 Goal: understand what broke and why, before touching anything.
 
-1. `homelab service <name> explain` (or `homelab node <name> relations`
-   if the affected entity is a host) — get the blast radius and doc
-   pointer first. Don't start pulling logs blind.
-2. `homelab service <name> health` + `homelab service <name> log` (or
-   MCP `get_service_status` / `tail_log`) for the affected service.
+1. MCP `explain` (or `get_blast_radius` if the affected entity is a
+   host) — get the blast radius and doc pointer first. Don't start
+   pulling logs blind.
+2. MCP `get_service_status` + `tail_log` for the affected service.
 3. Walk the blast radius: is a shared dependency down (`caddy`, `dns`,
-   `authentik`, or the backend host itself)? `homelab node <name>
-   relations` shows "affected by" — check those first.
-4. `homelab apt-audit` if the symptom looks like a dpkg/upgrade
-   interaction.
+   `authentik`, or the backend host itself)? MCP `get_blast_radius`
+   shows "affected by" — check those first.
+4. If the symptom looks like a dpkg/upgrade interaction, see
+   [runbook-dpkg-interrupted](../runbook-dpkg-interrupted/SKILL.md) —
+   there's no fleet-wide apt-audit tool anymore, check the host directly.
 5. Check the change ledger for recent mutations to the affected entity
-   or anything upstream of it: `homelab service <name> history` (once
-   populated) or grep `ledger/*.jsonl`.
-6. Write findings to a new `knowledge/sources/investigations/<date>-<slug>.md` — symptom,
-   timeline, root cause, fix applied, prevention. This is the durable
-   record; don't rely on chat history.
+   or anything upstream of it: MCP `get_change_history` or `get_audit_trail`.
+6. Write findings via MCP `upsert_knowledge` (`kind: investigation`) —
+   symptom, timeline, root cause, fix applied, prevention, `about` set to
+   the affected entity's slug. The DB is the durable record now, not a
+   markdown file — `search_knowledge`/`get_entity_knowledge` read it back;
+   a chat message alone is forgotten.
 
 Docs-update checklist: always create the investigation entry. If the
 root cause was stale/wrong inventory data (a `doc_page`, `config_repo`,

.agents/skills/knowledge-graph-audit/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: knowledge-graph-audit
+risk_class: read_only
+inputs: []
+verification: "audit_knowledge_graph returns a report with summary.total_findings"
+docs_update_checklist: []
+---
+
+# Knowledge-graph audit
+
+Goal: validate that the knowledge graph (entities, relationships, checks) and
+the monitoring built on it reflect live reality — without mutating anything.
+Read-only. Run this before trusting health, blast-radius, or coverage answers,
+and whenever something feels off (a healthy host reports `down`, a retired
+service still alarms, the graph looks thin).
+
+## 1. Run the drift report
+
+Call MCP `audit_knowledge_graph` (or `GET /api/v1/audit/drift`). It returns a
+ranked list of findings, each with `{category, severity, count, entities,
+evidence, suggested_runbook}`, plus a `summary` with totals by category.
+
+The DB-side categories:
+
+- **orphan_checks** — check entities with truncated/random slugs left by the
+  old `shortSlug()` collision bug. Remediation: `scripts/cleanup-orphan-checks.sh`.
+- **dead_checks** — enabled `check_defs` whose target entity is `deprecated`/
+  `destroyed`. Remediation: `lifecycle-deprecate-node` / `lifecycle-destroy-node`
+  (the scheduler already skips these, but the rows should be retired).
+- **down_checks** — enabled probes reporting `down`. Remediation:
+  `service-health-check` (then check whether the failure is real or a
+  probe-config/routing problem — see step 3).
+- **unknown_checks** — probes that ran but reported `unknown` (usually a
+  misconfigured or not-yet-deployed probe script).
+- **unmonitored** — active entities whose type declares monitoring but have no
+  enabled `check_def`.
+- **dangling_edges** — live `hosts`/`provides`/`mounts` edges still pointing at
+  destroyed/deprecated targets. Remediation: `lifecycle-destroy-node`.
+
+## 2. Triage
+
+`severity: critical` (down_checks) first. For each finding, read `evidence` and
+open the entities with `get_entity` / `get_relations` to confirm the diagnosis
+before acting — the report is a pointer, not a verdict.
+
+## 3. Common probe-failure causes
+
+A `down_checks` finding that is NOT a real outage is usually one of:
+
+- **Guest reached wrong** — an LXC/VM check SSHed the guest directly instead of
+  routing through its Proxmox host. Confirm with `get_relations` that a `hosts`
+  edge exists and the guest has `pve_id`; checks route via `pct exec`/`qm guest
+  exec` automatically when both are present.
+- **Script not deployed** — the probe script is absent at `/opt/oikos/checks/`
+  inside the target. Remediation: redeploy via `tools/deploy-checks.sh`.
+- **macOS host** — a workstation check used the wrong SSH user or a Linux-only
+  script flag. The scheduler resolves `user: dtoro` from the entity attribute.
+
+## 4. What this audit does NOT cover (follow-ups)
+
+Live-infrastructure discovery has its own tool — run **`discover_infra_drift`**
+alongside this one. It compares running Proxmox guests (`pct`/`qm list` on every
+proxmox host) against the DB graph and returns:
+
+- **missing entities** — a guest running in Proxmox with no DB entity.
+- **ghost entities** — a DB lxc/vm whose `pve_id` is no longer live.
+
+Still manual until that machinery lands:
+
+- **Misplaced parent** — compare each guest's actual Proxmox host against its
+  `hosts` edge (migrations leave these stale).
+- **Undeployed scripts** — per-guest `/opt/oikos/checks/` presence.
+- **Unmodeled certs** — now modeled; verify with `audit_knowledge_graph` /
+  the cert-expiry checks.
+- **Seed drift** — run `oikos export` and `git diff seeds/` to find
+  runtime-created entities not in version control.
+
+## 5. Acting on findings
+
+This skill is read-only — make no changes here. Route each confirmed finding to
+its `suggested_runbook`, classify the action against `seeds/policy.yaml`, and
+proceed through the normal lifecycle/approval flow. Re-run the audit afterward
+to confirm the finding cleared.
+
+Docs-update checklist: none — the audit reads state; it changes nothing. If a
+finding reveals stale `risk_notes` or a wrong `doc_page`, fix `inventory.yaml`
+in that remediation session.

.agents/skills/lifecycle-activate-node/SKILL.md

@@ -2,7 +2,7 @@
 name: lifecycle-activate-node
 risk_class: config_mutation
 inputs: [node_name]
-verification: "homelab service <name> health (if it hosts a service); homelab doctor (if it's a client)"
+verification: "MCP get_service_status (if it hosts a service); MCP whoami (if it's a client)"
 docs_update_checklist: [doc_page_complete]
 transition: "provisioning -> active"
 ---
@@ -14,23 +14,22 @@ enrolled if it needs secrets, mesh joined if it needs off-LAN reach,
 ingress live if public, health check answering, doc page complete,
 ledger entry.
 
-1. If the node is a `homelab` client: finish enrollment per
-   [client-enrollment.md](../client-enrollment/SKILL.md) (`--finalize-pubkey`,
-   mesh join, `homelab doctor` green).
+1. If the node self-enrolls as a client: finish enrollment per
+   [CLIENTS.md](../../../CLIENTS.md#enrollment) (`bootstrap.sh` →
+   `/api/v1/clients/enroll`, mesh join, MCP `whoami` returns the entity).
 2. If it hosts a public service: add the `services:` entry in
-   `inventory.yaml` (backend, url, doc_page, config_repo, risk_notes —
-   see the Week-1 service contract fields) and wire the Caddy route in
-   `dtoro/caddy-conf`.
-3. Confirm the health check answers: `homelab service <name> health` or
-   a direct `curl`.
+   `seeds/inventory.yaml` (backend, url, doc_page, config_repo,
+   risk_notes) and wire the Caddy route in `dtoro/caddy-conf`.
+3. Confirm the health check answers: MCP `get_service_status` or a
+   direct `curl`.
 4. Flip `state: provisioning` → `state: active` (or delete the `state:`
-   field — `active` is the default) in `inventory.yaml`.
+   field — `active` is the default) in `seeds/inventory.yaml`, then
+   `oikos seed` to ingest.
 5. Complete the doc page (stub → full narrative: role, specs, how it's
    configured, dependencies).
-6. Record the activation: `oikos/ledger.py append host:<name> activate
-   config_mutation --result ok` (or let the CLI wrapper do this once
-   Week 3's runbook automation lands).
+6. No manual record-keeping step needed — the activation (via whatever
+   API call flipped the state) is recorded automatically in `audit_log`.
 
-Regenerate derived data: `python3 mcp/build_host_files.py && python3
-inventory.yaml` so `inventory.yaml`, the topology diagram, and
-the context card all reflect the new state.
+Regenerate: `oikos seed` re-ingests `seeds/inventory.yaml`; `oikos export`
+writes DB state back out to the YAML if you mutated via the API/MCP
+instead of editing the file directly.

.agents/skills/lifecycle-deprecate-node/SKILL.md

@@ -2,7 +2,7 @@
 name: lifecycle-deprecate-node
 risk_class: config_mutation
 inputs: [node_name, replacement_node_or_reason]
-verification: "homelab node <name> relations — 'affected by' must be empty before completing"
+verification: "MCP get_blast_radius — 'affected by' must be empty before completing"
 docs_update_checklist: [doc_page_deprecation_note]
 transition: "active -> deprecated"
 ---
@@ -16,14 +16,14 @@ suggestion; `seeds/policy.yaml` `lifecycle_overrides.deprecated.refuse`
 lists `new-inbound-edges` as refused going forward.
 
 1. Set `state: deprecated` on the node.
-2. `homelab node <name> relations` — read `affected_by`. Every entry
-   there is something still relying on this node.
+2. MCP `get_blast_radius` — read `affected_by`. Every entry there is
+   something still relying on this node.
 3. Migrate or retire each dependent one at a time (point its `backend`/
    `config_repo`/ingress route elsewhere, or deprecate it too if it's
    being retired alongside).
-4. Re-run `homelab node <name> relations` after each dependent is moved.
-   The transition to `destroyed` is only safe once `affected_by` is
-   empty — check this every time, don't assume from memory.
+4. Re-run MCP `get_blast_radius` after each dependent is moved. The
+   transition to `destroyed` is only safe once `affected_by` is empty —
+   check this every time, don't assume from memory.
 5. Note the deprecation on the doc page: reason, replacement (if any),
    date.
 

.agents/skills/lifecycle-destroy-node/SKILL.md

@@ -2,7 +2,7 @@
 name: lifecycle-destroy-node
 risk_class: destructive
 inputs: [node_name]
-verification: "homelab node <name> relations returns unknown-entity; pct list on the backend no longer shows it"
+verification: "MCP get_blast_radius returns unknown-entity; pct list on the backend no longer shows it"
 docs_update_checklist: [archaeology_entry, containers_index_update]
 transition: "deprecated -> destroyed"
 ---
@@ -15,28 +15,35 @@ recipients removed + re-keyed, ingress/DNS removed, archaeology entry,
 ledger entry.
 
 1. Confirm the node is `deprecated` with zero `affected_by` edges
-   (`homelab node <name> relations`) — do not skip this even if the
-   deprecation runbook was followed recently; state can drift.
-2. If it's an enrolled client: `homelab client remove <name>` — revokes
-   the age key, re-keys SOPS, removes the inventory entry. This is
-   already destructive-class and confirmed in the CLI.
+   (MCP `get_blast_radius`) — do not skip this even if the deprecation
+   runbook was followed recently; state can drift.
+2. **If it's an enrolled client: no current tool for revoking its age key /
+   removing its Infisical identity.** The old `homelab client remove`
+   (age key revocation + SOPS re-key + inventory removal, all one
+   destructive-class CLI call) is retired along with the rest of that CLI
+   and hasn't been re-verified against the current enrollment
+   architecture (`POST /api/v1/clients/enroll` + Infisical machine
+   identities) — see the "Open questions" section in
+   [agent-enrollment.md](../../operations/agent-enrollment.md). Until
+   that's confirmed, treat key/identity revocation as a manual step:
+   at minimum remove the client's `age_pubkey` from any SOPS recipient
+   lists and rotate credentials whose ciphertext it already decrypted.
 3. Remove any ingress route (Caddy config repo) and DNS record still
    pointing at it.
 4. Verify backups of anything on it are retained per policy before the
    disk goes away (see `backs-up-to`).
 5. Destroy the LXC/VM (`pct destroy` / `qm destroy`).
-6. Move the `hosts.<name>:` block (if any inventory remnant survives
-   `client remove`, e.g. infra-only LXCs with no age key) into
-   inventory.yaml's `archaeology:` section: `pve_id`, `destroyed` date,
-   `reason`. Add a row to `containers/index.md` "Recently destroyed"
-   table (kept for human-readable browsing alongside the structured
-   data).
-7. `oikos/ledger.py append host:<name> destroy destructive --result ok`.
-8. Regenerate: `python3 mcp/build_host_files.py && python3
-   inventory.yaml` — the node drops out of `inventory.yaml` and
-   appears in the topology doc's archaeology table.
+6. Update the entity's `state` to `destroyed` in `seeds/inventory.yaml`
+   (or move it to an `archaeology:`-style section if the schema still has
+   one) — `pve_id`, `destroyed` date, `reason` — then `oikos seed` to
+   ingest. Add a row to `containers/index.md` "Recently destroyed" table
+   (kept for human-readable browsing alongside the structured data).
+7. No manual ledger step — mutations through the API are recorded
+   automatically in the `audit_log` table (MCP `get_audit_trail`,
+   `get_change_history`). The old `oikos/ledger.py append` was retired
+   when this became automatic.
 
-If the destroy fails partway (e.g. secrets revoked but pct destroy
-errors), do not re-run step 2 — `client remove` is not idempotent
-against a second revocation attempt on the issuance server. Finish the
-remaining steps manually and note the partial state in an investigation.
+If the destroy fails partway (e.g. secrets not fully revoked but pct
+destroy errors), finish the remaining steps manually and note the
+partial state in an investigation (MCP `upsert_knowledge`,
+`kind: investigation`).

.agents/skills/lifecycle-migrate-node/SKILL.md

@@ -2,7 +2,7 @@
 name: lifecycle-migrate-node
 risk_class: config_mutation
 inputs: [node_name, source_host, target_host]
-verification: "homelab node <name> relations (re-check blast radius); homelab service <svc> health for every hosted service"
+verification: "MCP get_blast_radius (re-check blast radius); MCP get_service_status for every hosted service"
 docs_update_checklist: [doc_page_migration_note, inventory_host_and_lan_ip]
 transition: "active -> migrating -> active"
 ---
@@ -10,12 +10,12 @@ transition: "active -> migrating -> active"
 # Lifecycle: migrate a node
 
 Modeled on the strong Phase 1+2 migration
-([plans/2026-06-03_110000-library-ssd-migration-to-ludo-mini.md](../../../.hermes/plans/2026-06-03_110000-library-ssd-migration-to-ludo-mini.md)).
+([archive/hermes-plans/2026-06-03_110000-library-ssd-migration-to-ludo-mini.md](../../../archive/hermes-plans/2026-06-03_110000-library-ssd-migration-to-ludo-mini.md)).
 Requires (ontology): preflight + backup-verified before migrating;
 post-verify + Caddy backends checked + mounts checked + docs updated
 before returning to `active`.
 
-1. `homelab change preflight <every service the node hosts>` — capture
+1. MCP `preflight` for every service the node hosts — capture
    current health as a baseline.
 2. Verify backups are current for anything with data at rest on the
    node (see `backs-up-to` edges once populated).
@@ -29,11 +29,12 @@ before returning to `active`.
 6. Post-verify: re-run the Week-1 drift check by hand — confirm Caddy's
    backend IP for each affected service matches the new `lan_ip`
    (automatic in Week 3's drift detector), confirm mounts still resolve.
-7. `homelab service <name> health` for every service the node hosts.
+7. MCP `get_service_status` for every service the node hosts.
 8. Set `state: active`. Add a migration note to the node's doc page
    (old host/IP → new, date, phase reference) — this repo's convention
    for every past migration (see `archive/knowledge/containers/101-jellyfin.md`,
    `containers/129-house.md`).
 
-Regenerate: `python3 mcp/build_host_files.py && python3
-inventory.yaml`.
+Regenerate: `oikos seed` (re-ingests `seeds/inventory.yaml` into the DB —
+the DB is authoritative at runtime, the YAML is the source of truth
+on disk).

.agents/skills/lifecycle-provision-node/SKILL.md

@@ -21,10 +21,12 @@ chosen, doc page stub.
    `qm create`), choosing the storage pool deliberately — record it as
    the `storage:` field once populated (Week 1 schema; not yet backfilled
    for existing nodes).
-2. Add the inventory entry: `homelab client add <name>` for anything that
-   will run the `homelab` CLI, or a direct `hosts.<name>:` block with
-   `state: provisioning`, `kind`, `host`, `pve_id`, `lan_ip` for
-   infra-only LXCs that won't self-enroll.
+2. Add the inventory entry: a `hosts.<name>:` block in
+   `seeds/inventory.yaml` with `state: provisioning`, `kind`, `host`,
+   `pve_id`, `lan_ip`, then `oikos seed` to ingest it. For anything that
+   will self-enroll as a client afterward (see
+   [CLIENTS.md](../../../CLIENTS.md#enrollment)), the entity must exist in
+   `planned`/`provisioning` state before `bootstrap.sh` runs there.
 3. Stub the doc page (`containers/<pve_id>-<name>.md` or
    `vms/<pve_id>-<name>.md`) — even a one-line "provisioning, see plan X"
    is enough to satisfy the transition requirement.

.agents/skills/runbook-budget-from-csv/SKILL.md

@@ -18,7 +18,7 @@ summarised into targets and fixed costs.
 - `yuvomi-mcp` is running on LXC 129 and connected as an MCP server in Claude.
 - The CSV is an N26 export (columns: Booking Date, Value Date, Partner Name,
   Partner Iban, Type, Payment Reference, Account Name, Amount (EUR), …).
-- API token: `homelab secret yuvomi-api-token` (decrypts on any enrolled client).
+- API token: `yuvomi-api-token`, via Infisical (primary) or `oikos secret` (SOPS fallback).
 - Direct API base: `https://house.hubris.network/api/v1`
 
 ---

.agents/skills/runbook-dpkg-interrupted/SKILL.md

@@ -13,7 +13,8 @@ has packages that are **unpacked but not configured**. Symptoms:
   manually run 'dpkg --configure -a' to correct the problem.`
 - `dpkg --audit` lists packages with header
   `The following packages have been unpacked but not yet configured.`
-- `homelab apt-audit` shows `DPKG: DIRTY(N)` for the host.
+- `dpkg --audit` on the host directly shows unpacked-not-configured packages
+  (there's no fleet-wide audit tool anymore — check per-host).
 
 The system is still running the **old** binaries (still in memory), but the
 **new** binaries are unpacked and waiting for their postinst to run. Two
@@ -33,19 +34,20 @@ config dirs, capabilities, etc.). The system might not come back up cleanly.
 ## Path A — target is still reachable over ssh (preferred)
 
 ```
-homelab ssh <host> -- bash -c 'DEBIAN_FRONTEND=noninteractive dpkg --configure -a && apt -y -o Dpkg::Options::=--force-confold upgrade'
+ssh <host> -- bash -c 'DEBIAN_FRONTEND=noninteractive dpkg --configure -a && apt -y -o Dpkg::Options::=--force-confold upgrade'
 ```
 
-Or for an LXC by name:
+Or for an LXC by name (via the MCP `run` tool, or directly on the Proxmox
+host):
 
 ```
-homelab pct <lxc> exec -- bash -c 'DEBIAN_FRONTEND=noninteractive dpkg --configure -a && apt -y -o Dpkg::Options::=--force-confold upgrade'
+pct exec <lxc> -- bash -c 'DEBIAN_FRONTEND=noninteractive dpkg --configure -a && apt -y -o Dpkg::Options::=--force-confold upgrade'
 ```
 
 When that returns, confirm:
 
 ```
-homelab apt-audit --target <host>
+ssh <host> -- dpkg --audit
 ```
 
 Expect `DPKG: ok` and the remaining `UPGR` count to match what's intentionally
@@ -89,10 +91,11 @@ DEBIAN_FRONTEND=noninteractive dpkg --configure -a \
 
 ## Prevention
 
-The `homelab apt-upgrade` wrapper launches apt inside a `systemd-run --collect`
-unit on the target, so it survives ssh teardown — the failure mode that put
-hubris into this state in the first place is no longer reachable through the
-standard tool. If you absolutely need to run apt manually over ssh, wrap it:
+The old `homelab apt-upgrade` wrapper (retired along with the rest of the
+`homelab` CLI) used to launch apt inside a `systemd-run --collect` unit on
+the target so it survived ssh teardown — that's the failure mode that put
+hubris into this state in the first place. There's no fleet-wide wrapper
+anymore; if you run apt manually over ssh, wrap it yourself the same way:
 
 ```
 ssh <host> systemd-run --unit=apt-recovery --collect bash -c 'apt -y upgrade'

.agents/skills/service-health-check/SKILL.md

@@ -2,7 +2,7 @@
 name: service-health-check
 risk_class: read_only
 inputs: [service_name]
-verification: "homelab service <name> health"
+verification: "MCP get_service_status"
 docs_update_checklist: []
 ---
 
@@ -10,15 +10,15 @@ docs_update_checklist: []
 
 Goal: determine whether a service is actually healthy, without ad-hoc SSH.
 
-1. `homelab service <name> explain` — read the context card: backend,
-   blast radius, doc pointer, risk notes.
-2. `homelab service <name> health` — live health probe (HTTP code against
-   the service's `url`/`endpoint`). Once the Week-3 scheduler ships, this
-   reads a cached snapshot by default; pass `--live` to force a fresh probe.
-3. If unhealthy, `homelab service <name> log` (or MCP `tail_log`) for the
-   last 200 lines.
-4. Cross-check blast radius: `homelab node <name> relations` — is this
-   entity's own backend host healthy? A downstream failure (e.g. `strong`
+1. MCP `explain` — read the context card: backend, blast radius, doc
+   pointer, risk notes.
+2. MCP `get_service_status` — live health probe (HTTP code against the
+   service's `url`/`endpoint`); the scheduler also probes on its own
+   interval, so this may reflect a recent cached result, not necessarily
+   a fresh one.
+3. If unhealthy, `tail_log` for the last 200 lines.
+4. Cross-check blast radius: MCP `get_blast_radius` — is this entity's
+   own backend host healthy? A downstream failure (e.g. a Proxmox host
    down) will show up here before the service's own logs explain anything.
 5. If the fix is a restart: classify first (`seeds/policy.yaml` —
    `service-restart` is `reversible_low` unless the service has a

.agents/skills/session-review/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: session-review
+description: "Examine a Nomos chat session, compare the user's objective with the actual outcome, identify causes of failure (missing tools, excessive tool calls, blocked actions, model behavior), and propose concrete fixes."
+risk_class: reversible_low
+inputs: [session_id]
+---
+# Session review
+
+Analyze Nomos chat sessions from the live database, diff objectives
+against outcomes, and propose fixes.
+
+## 1. Retrieve session data
+
+```bash
+# List recent sessions
+curl -s http://localhost:8092/sessions | jq '.sessions[:5]'
+
+# Fetch one session with messages
+curl -s http://localhost:8092/sessions/{session_id} | jq .
+```
+
+## 2. Classify the session
+
+For each session determine:
+
+| Dimension | Check |
+|-----------|-------|
+| Objective | What was the user trying to accomplish? |
+| Outcome | Was it achieved? (read final assistant text) |
+| Tool calls | Count, unique tools, redundancy (e.g., N+1 fan-out) |
+| Blockers | Missing action? Missing tool? Model refusal? Empty response? |
+| User frustration | Did the user need to clarify/correct/repeat? |
+| Message sizes | Content blob sizes — truncation needed? |
+
+## 3. Key failure signatures
+
+| Signature | Root cause | Fix |
+|-----------|-----------|-----|
+| Agent: "I can't run X" | Missing target or capability | Use `run` with shell command — there is no fixed action enum anymore |
+| Agent: "No local knowledge on that" + no web tool | Missing `http_get` / web fetch MCP tool | Add MCP tool |
+| Empty assistant bubble (text="", no tools) | Model returned blank completion | Retry + error surfacing |
+| Non-English boilerplate refusal | Flash-tier model degradation | Response quality guard |
+| >30 tool calls per turn, same tool repeated | N+1 fan-out instead of bulk tool | Enrich bulk tools + tighten SOUL.md |
+| Message >50KB in DB | Raw tool results persisted verbatim | Truncation in `store.go` |
+
+## 4. Extract patterns across sessions
+
+```bash
+# All sessions summary
+curl -s http://localhost:8092/sessions | jq -r '.sessions[] | "\(.id[:8]) \(.title[:80]) \(.created_at[:16])"'
+
+# Message count + tool count per session
+for id in $(curl -s http://localhost:8092/sessions | jq -r '.sessions[].id'); do
+  msgs=$(curl -s "http://localhost:8092/sessions/$id" | jq '.messages | length')
+  tools=$(curl -s "http://localhost:8092/sessions/$id" | jq '[.messages[].content.tool_calls | length] | add')
+  echo "$id $msgs msgs $tools tools"
+done
+```
+
+## 5. Output format
+
+```
+Session: {id[:8]} — "{title[:60]}"
+  Messages: {N} ({user}/{assistant})
+  Tool calls: {total} across {turns} turns
+  Top tools: {name:count, name:count, ...}
+  Objective: {one-line summary}
+  Outcome: ✅ / ❌ / ⚠️
+  Blockers: {list or "none"}
+  Fixes needed: {concrete actions}
+  Severity: blocker | friction | cosmetic
+```
+
+## Related files
+
+- `cmd/nomos/agent.go` — agent loop, tool building, response guards
+- `cmd/nomos/store.go` — session + message persistence
+- `internal/mcp/server.go` — all tool implementations (`run`, `list_lxcs`, …)
+- `web/src/lib/components/ToolCallGroup.svelte` — tool result display
+- `nomos/SOUL.md` — agent persona and tool selection rules
+- `plans/2026-07-09-chat-sessions-improvements.md` — prior session findings
+- `plans/2026-07-09-session-execution-and-ux-fixes.md` — latest plan

.claude/launch.json

@@ -3,9 +3,10 @@
   "configurations": [
     {
       "name": "web",
-      "runtimeExecutable": "npm",
-      "runtimeArgs": ["--prefix", "web", "run", "dev"],
-      "port": 5173
+      "runtimeExecutable": "sh",
+      "runtimeArgs": ["-c", "export OIKOS_API_TOKEN=$(docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' oikos-api-1 | sed -n 's/^OIKOS_MCP_BEARER_TOKEN=//p'); exec npm --prefix web run dev"],
+      "port": 5173,
+      "autoPort": true
     }
   ]
 }

.dockerignore

@@ -0,0 +1,12 @@
+# Every docker build in this repo previously sent the whole directory as
+# build context — including every OTHER git worktree under .claude/worktrees/
+# (each with its own web/node_modules, ~200-300MB apiece). That's what
+# starved the mac-mini's disk mid-build on 2026-07-27 (SHA 873b00a): the
+# context alone crossed 390MB of pure worktree cruft before the host ran out
+# of space. None of this ever belonged in an image.
+.claude/worktrees/
+.git/
+**/node_modules/
+**/dist/
+**/build/
+*.log

.gitea/workflows/ci.yml

@@ -70,3 +70,30 @@ jobs:
       - uses: actions/checkout@v4
       - name: docker build (verify image builds; no push)
         run: docker build -f compose/oikos/Dockerfile -t oikos:ci .
+
+  web:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: web
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci
+      - name: svelte-check (advisory — baseline not yet clean)
+        run: npm run check
+        continue-on-error: true
+      - name: eslint (advisory — baseline not yet clean)
+        run: npm run lint
+        continue-on-error: true
+      - name: prettier format check (advisory — baseline not yet clean)
+        run: npm run format:check
+        continue-on-error: true
+      - name: test
+        run: npm run test
+      - name: build
+        run: npm run build

.gitea/workflows/desktop.yml

@@ -0,0 +1,70 @@
+name: Desktop App
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'desktop-*'
+      - 'v[0-9]+.[0-9]+.[0-9]*'
+
+jobs:
+  build:
+    name: Build Linux (amd64)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - run: npm ci
+        working-directory: web
+
+      - run: npm run build
+        working-directory: web
+
+      - run: |
+          rm -rf cmd/desktop/frontend/dist
+          mkdir -p cmd/desktop/frontend/dist
+          cp -r web/dist/* cmd/desktop/frontend/dist/
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+
+      - run: |
+          sudo apt-get update
+          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
+
+      - run: CGO_ENABLED=1 go build -o build/bin/Oikos .
+        working-directory: cmd/desktop
+
+      - run: |
+          cd cmd/desktop/build/bin
+          tar czf oikos-desktop-linux-amd64.tar.gz Oikos
+          sha256sum oikos-desktop-linux-amd64.tar.gz > oikos-desktop-linux-amd64.tar.gz.sha256
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: oikos-desktop-linux-amd64
+          path: |
+            cmd/desktop/build/bin/oikos-desktop-linux-amd64.tar.gz
+            cmd/desktop/build/bin/oikos-desktop-linux-amd64.tar.gz.sha256
+
+  release:
+    name: Attach to Release
+    needs: build
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: oikos-desktop-linux-amd64
+
+      - uses: https://gitea.com/actions/release-action@v1
+        with:
+          files: |
+            oikos-desktop-linux-amd64.tar.gz
+            oikos-desktop-linux-amd64.tar.gz.sha256
+          api_key: ${{ secrets.GITEA_TOKEN }}

.gitignore

@@ -2,25 +2,29 @@
 __pycache__/
 *.pyc
 
-# Regenerated every scheduler run; ephemeral health-probe cache.
-oikos/state.json
-
 # Compiled binaries (Go rewrite — bin/oikos, bin/nomos)
 bin/oikos
 bin/nomos
-oikos/oikos
+oikos
+webhook
 
-# Legacy Python oikos (superseded by cmd/oikos Go binary — Phase 1-6 rewrite).
-# oikos/ kernel files are still imported by bin/homelab for operational CLI
-# commands (ssh, pct, logs, restart, status, open, secret, client, sync, mcp).
-# Remove oikos/* when bin/homelab is ported to Go.
 backups/
 .env
 .infisical-credentials
 
-# Web UI (Svelte 5) — build artifacts. Ignore built output but keep the
-# .gitkeep placeholder so `//go:embed all:dist` (web/embed.go) compiles on a
-# fresh checkout before the UI is built.
-web/dist/*
-!web/dist/.gitkeep
+# Web UI (Svelte 5) — build artifacts. The SPA is a standalone static build,
+# deployed separately from the oikos binary (plans/2026-07-12-wails-desktop-app.md
+# 0.1), so the output dir is just a build artifact.
+web/dist/
 web/node_modules/
+
+# Wails desktop app — frontend copy for embedding
+cmd/desktop/frontend/dist/
+cmd/desktop/build/
+cmd/desktop/Oikos
+desktop
+/eval
+
+# Local tooling artifacts (Playwright MCP session logs, stray screenshots)
+.playwright-mcp/
+config-screen.png

.golangci.yml

@@ -0,0 +1,41 @@
+# golangci-lint configuration for Oikos
+# Docs: https://golangci-lint.run/usage/configuration/
+run:
+  timeout: 5m
+  tests: true
+
+linters:
+  enable:
+    - govet        # go vet
+    - staticcheck  # advanced static analysis
+    - ineffassign  # detect ineffectual assignments
+    - unused       # find unused identifiers
+    - errcheck     # check for unchecked errors
+    - gosimple     # simplifications
+    - typecheck    # standard type checking
+    - misspell     # find commonly misspelled English words in comments
+    - revive       # fast, configurable linter (replaces golint)
+
+linters-settings:
+  errcheck:
+    # Allow unchecked errors on common Close/Flush patterns (deferred cleanup)
+    exclude-functions:
+      - (io.Closer).Close
+      - (*os.File).Close
+
+issues:
+  # Exclude generated code
+  exclude-rules:
+    - path: _test\.go
+      linters:
+        - errcheck
+    - path: internal/httpapi/gen/
+      linters:
+        - all
+    - path: internal/db/sqlcgen/
+      linters:
+        - all
+  # Don't auto-exclude common patterns
+  exclude-use-default: false
+  max-issues-per-linter: 0
+  max-same-issues: 0

AGENTS.md

@@ -1,7 +1,7 @@
 # AGENTS.md — orientation for any agent on a homelab client
 
 You are running on a machine that is part of the **hubris** homelab. The full
-context is in this checkout at `/opt/homelab-context/`. This file is the entry
+context is in this checkout at `/opt/homelab/`. This file is the entry
 point. Read it once at start, then keep working.
 
 - **New client?** Read [CLIENTS.md](CLIENTS.md) first.
@@ -30,36 +30,46 @@ is archived at `archive/knowledge/` for historical reference.
 
 Run `hostname` (Linux) or `scutil --get LocalHostName` (macOS), then read:
 
-    /opt/homelab-context/inventory.yaml
+    /opt/homelab/inventory.yaml
 
 That file tells you your role, your peers, what's mounted, and what services
 you host. If it does not exist, this client was not enrolled — stop and tell
-the operator to run `homelab client add <hostname>` from an existing client.
+the operator; see [CLIENTS.md](CLIENTS.md#enrollment) for the enrollment flow
+(the entity needs to exist in `planned`/`provisioning` state first).
 
 ## 2. The topology
 
-- `/opt/homelab-context/inventory.yaml` — every host, LXC, VM, and workstation
+- `/opt/homelab/inventory.yaml` — every host, LXC, VM, and workstation
   with their mesh addresses, roles, and service mappings. This is the seed file;
   at runtime the DB is authoritative (query via MCP `get_entity` or the REST API).
-- `/opt/homelab-context/seeds/knowledge.yaml` — full narrative knowledge: 36
-  documents, 6 investigations, 12 runbooks. Ingested into the DB on deploy.
-- `/opt/homelab-context/.agents/operations/commands.md` — the operator's cheatsheet
+- `/opt/homelab/seeds/knowledge.yaml` — full narrative knowledge
+  (documents, investigations, runbooks). Counts are not hardcoded here; count
+  them from the seed or query the DB. Ingested into the DB on deploy.
+- `/opt/homelab/.agents/operations/commands.md` — the operator's cheatsheet
   for pct, caddy, DNS, and the Oikos command surface.
 
 ## 3. The MCP server
 
 The homelab exposes a Model Context Protocol server with structured tools.
-Endpoint: `https://mcp.hubris.network/mcp`.
+Endpoint: `https://mcp.hubris.network/mcp`. Every call needs
+`Authorization: Bearer <token>` — the API has no unauthenticated path except
+enrollment and `/healthz` (see "Authentication" below for where the token
+comes from).
 
-Available tools (21 total):
+Available tools (the authoritative list — count them below if a number is
+needed; do not hardcode the count elsewhere):
 
   Context — observe + orient:
     get_entity(slug), list_entities(type, limit, cursor),
     get_relations(entity), get_blast_radius(entity),
     search_knowledge(query) — ILIKE search over documents, investigations,
       runbooks in the knowledge_entities table
+    get_entity_knowledge(entity_slug) — every document, investigation, and
+      runbook linked to one entity, in one call
     get_patterns(status, entity_type, action) — learned action patterns
     get_skills(status) — available automation skills
+    http_get(url) — fetch a public page/raw file (e.g. researching how to
+      deploy something before provisioning it); HTTP/HTTPS only, ~16KB cap
 
   Management — live state:
     get_service_status(service_slug) — systemctl is-active on target host
@@ -67,6 +77,8 @@ Available tools (21 total):
     list_lxcs() — all LXC containers with ID, host, IP, health
     get_lxc_state(lxc_slug) — pct status from Proxmox host
     ping_service(service_slug) — HTTP reachability from entity_status
+    list_my_secrets(caller_pubkey) — secrets accessible to this client by
+      age public key
 
   Oikos — decisions:
     explain(service_slug) — compact context card (type, state, health, relations)
@@ -84,11 +96,26 @@ Available tools (21 total):
     get_trend(entity_id, days=7) — metric slope over time
     get_event_timeline(severity, entity_slug, limit) — recent events
 
-  Execution — the single mutation path:
-    request_execution(target, action, params) — policy-gated.
-      reversible_low (restart, reload, pct_exec, apt audit) runs immediately;
-      config_mutation (systemctl enable/disable, apt upgrade) queues for operator
-      approval via Matrix, then executes on ✅.
+  Knowledge — keep the graph current (none require approval; this updates
+  the knowledge graph, not live infrastructure):
+    upsert_knowledge(title, content) — record what you learned after solving
+      a non-obvious problem; the only way anything persists past a session
+    update_entity_attributes(slug, attributes) — merge a discovered fact
+      (IP, version, port, ...) into an entity so a future task doesn't
+      rediscover it from scratch
+    create_relationship(source, target, type) — record a discovered edge
+      (depends-on, hosts, routes-to, ...) between two entities
+
+  Execution — mutating the live infrastructure:
+    run(target, command) — the general execution primitive. Run any shell
+      command against a host or LXC; every command is auto-classified —
+      read-only inspection runs immediately, anything state-changing needs
+      operator approval, and destructive patterns (rm -rf, dd, mkfs,
+      pct/qm destroy, DROP TABLE, reboot, curl-pipe-to-shell, ...) always
+      need approval regardless of what you declare. This is the ONLY
+      mutation tool — `request_execution` was retired 2026-07-14; the
+      former enum actions (restart, systemctl, pct_exec, apt_upgrade,
+      pct_create) are all expressed as `run(target, command)` now.
     get_execution_status(execution_id) — poll progress
 
 **When to prefer MCP over grepping the clone:** always for knowledge queries.
@@ -97,7 +124,18 @@ the DB with entity links. `get_entity_knowledge("lxc:jellyfin")` returns documen
 runbooks, and investigations in one call. Grep the clone only when MCP is
 unreachable.
 
-## 4. Knowledge conventions
+## 4. Authentication
+
+Every API/MCP route requires `Authorization: Bearer <token>` except
+`POST /api/v1/clients/enroll` and `/healthz`. Enrollment (see
+[CLIENTS.md](CLIENTS.md#enrollment)) does not currently issue a per-client
+API/MCP bearer token — there is one shared
+secret (`OIKOS_MCP_BEARER_TOKEN`, validated in `internal/httpapi/server.go`'s
+`combinedAuth`); get it from the operator until per-client token issuance
+exists. The SPA has its own flow instead: a first-launch Config screen that
+stores a token in `localStorage` (see `web/src/pages/Config.svelte`).
+
+## 5. Knowledge conventions
 
 All narrative knowledge (documents, investigations, runbooks) lives in the DB
 (`knowledge_entities` table) and is seeded from `seeds/knowledge.yaml`. Agents
@@ -108,8 +146,8 @@ POST /api/v1/knowledge/{entity_slug}
 {"title": "...", "content": "...", "tags": ["..."]}
 ```
 
-The DB is the truth. The old wiki files are in `knowledge/wiki/` pending archive
-per the DB-as-source-of-truth plan.
+The DB is the truth. The old wiki files are archived at `archive/knowledge/`
+(historical reference only — use MCP `search_knowledge` for live queries).
 
 - **Runbook procedures** live as `runbook` entities in the DB and as SKILL.md
   files under `.agents/skills/<name>/`. They carry `risk_class`, `procedure`
@@ -122,47 +160,62 @@ per the DB-as-source-of-truth plan.
   running state, update the DB *in the same session* via the API. The `oikos export`
   command regenerates `seeds/knowledge.yaml` for version control.
 
-## 5. Acting on the homelab
+## 6. Acting on the homelab
 
 - **Read state**: use MCP tools. Nomos (the AI agent) is the primary
-  operator interface — it has 21 MCP tools for observe/orient/decide/act.
-- **Actions** (restart, logs, apt, pct exec): Nomos calls `request_execution`
-  via MCP. `reversible_low` actions execute immediately; `config_mutation`
-  and `destructive` actions are queued for operator approval via Matrix.
-- **Secrets**: managed by Infisical (`oikos secret` subcommand for migration).
-  Never hardcode secrets — use env vars from `.env`.
+  operator interface — it routes to the MCP tool list in §3 for
+  observe/orient/decide/act.
+- **Actions** (restart, logs, apt, pct exec, or anything else): Nomos calls
+  `run` (the general execution primitive) via MCP. `reversible_low`/read-only actions execute
+  immediately; `config_mutation` and `destructive` actions are queued for
+  operator approval via Matrix or the control-room UI's Operations page.
+- **Secrets**: managed by Infisical (`oikos secret` subcommand for
+  migration). Never hardcode secrets — use env vars from `.env`.
 - **Mutations** (restart, edit configs, etc.): classified against
   `seeds/policy.yaml`. `reversible_low` actions auto-execute;
-  `config_mutation`/`destructive` actions require approval.
-  a valid `--approval-id` from `homelab approval request` — see OIKOS.md.
+  `config_mutation`/`destructive` actions require approval — granted by
+  the operator via Matrix reply or the control-room UI, not a CLI flag.
+  See OIKOS.md.
 
-## 6. Communication mode
+## 7. Communication mode
 
-Read and apply `/opt/homelab-context/.agents/shared/caveman.md` (if present). It defines the lab's
+Read and apply `/opt/homelab/.agents/shared/caveman.md` (if present). It defines the lab's
 terse-communication standard — drop filler, keep substance, use fragments.
 
-## 7. Auto-setup mechanism
+## 8. Auto-setup mechanism
 
 The homelab-context repo ships tooling that gets automatically installed
 on every client after `git pull`. This is handled by `tools/post-pull.sh`
 (replaces the raw git pull in the sync timer) which runs any script matching
-`tools/*.setup.sh` after pull.
+`tools/setup-*.sh` after pull.
 
 Currently auto-setup:
-- **Caveman + templates** (`tools/setup-caveman.sh`): Installs Caveman npm
-  package, wrapper scripts, and compact output templates for token-efficient
-  CLI output. Wrapper at `~/bin/caveman_wrapper.sh`.
-- **Nomos agent persona** (`tools/setup-nomos-soul.sh`): Provisions
-  `~/.nomos/SOUL.md` from `NOMOS.md` on Nomos agents. This ensures every
-  Nomos agent follows the canonical homelab persona (token efficiency, source
-  of truth hierarchy). No-op on non-Nomos agents.
+- **Host checks** (`tools/setup-checks.sh`): Deploys `checks/install.sh`'s
+  health-check scripts to `/opt/oikos/checks` on each host. The scheduler's
+  `ssh-script` check kind depends on these actually being there (count is
+  whatever is currently seeded in the DB — do not hardcode it here).
 
-To add a new auto-setup, create `tools/<name>.setup.sh` in the repo,
+To add a new auto-setup, create `tools/setup-<name>.sh` in the repo,
 commit and push. All enrolled clients pick it up within 5 minutes.
 
-To trigger sync manually: `sudo homelab sync` or wait for the 5-min timer.
+To trigger sync manually: run `/opt/homelab/tools/context-poller.sh`, or
+wait for the 5-min timer. (The server-side `tools_changed` detection only
+correctly recognizes `setup-*.sh` scripts — earlier it silently matched
+nothing, so nothing auto-ran on any client via this path.)
 
-## 8. When in doubt
+## 9. Versioning
+
+Every commit to `main` **MUST bump the version** in the `VERSION` file at the
+repo root. The format is semver-ish: `major.minor.patch` (e.g. `0.2.3`).
+
+Rules:
+- **patch** (`0.2.2` → `0.2.3`): bugfixes, small tweaks, docs-only changes
+- **minor** (`0.2.3` → `0.3.0`): new features, new tools, visible functionality
+- **major** (`0.3.0` → `1.0.0`): breaking changes (API removal, tool retirement)
+
+The version is shown in the UI sidebar. The `v` prefix is added at build time.
+
+## 10. When in doubt
 
 Use MCP tools: `search_knowledge <query>` for narrative context,
 `get_entity <slug>` for structured data, `get_entity_knowledge <slug>` for

CLIENTS.md

@@ -24,9 +24,22 @@ Docker stack on mac-mini and exposes an MCP server + REST API.
 | State snapshot (health, disk, drift) | MCP `get_state_snapshot` |
 | Secrets (Infisical) | REST API + `oikos secret` CLI |
 | Approval tokens | Matrix via notifier |
+| Run a command on a host/LXC (policy-gated) | MCP `run` |
+| Record a discovered fact/relationship | MCP `update_entity_attributes`, `create_relationship`, `upsert_knowledge` |
 
-All MCP tools are read-only. Mutations use the `homelab` CLI with operator
-approval.
+Most MCP tools are read-only; a few mutate the knowledge graph (recording
+what you learned) or the live infrastructure (`run`),
+gated by risk classification and — for `config_mutation`/`destructive`
+actions — operator approval. See [AGENTS.md](AGENTS.md#3-the-mcp-server) for
+the full tool catalog.
+
+## Authentication
+
+Every API/MCP call needs `Authorization: Bearer <token>` — there is no
+unauthenticated path except `POST /api/v1/clients/enroll` and `/healthz`.
+Enrollment (below) does not currently hand out a per-client bearer token;
+get the shared `OIKOS_MCP_BEARER_TOKEN` from the operator until per-client
+token issuance exists.
 
 ## Enrollment
 
@@ -41,7 +54,6 @@ curl -fsSL https://git.hubris.network/dtoro/oikos/raw/main/bootstrap.sh | sudo b
 
 # Or with optional tooling:
 curl ... | sudo bash -s -- --with-mcp      # wire Claude's MCP config
-curl ... | sudo bash -s -- --with-nomos     # install Goose + Nomos
 ```
 
 This calls `POST /api/v1/clients/enroll` on the Oikos API, which:
@@ -56,7 +68,7 @@ This calls `POST /api/v1/clients/enroll` on the Oikos API, which:
 ### What changes on your machine
 
 - `/opt/homelab/` — agent orientation files (CLIENTS.md, AGENTS.md, OIKOS.md)
-- `/opt/homelab/tools/` — tooling scripts (caveman, nomos-soul)
+- `/opt/homelab/tools/` — tooling scripts (checks)
 - `/etc/age/key.txt` — age private key for SOPS decryption (fallback)
 - `/etc/infisical/identity` — Infisical machine identity (primary secrets)
 - Context poller — launchd/systemd timer hits `GET /api/v1/clients/{slug}/context` every 5 minutes for agent file updates

CONTRIBUTING.md

@@ -9,10 +9,13 @@ repo, see [.agents/dev/CONTRIBUTING.md](.agents/dev/CONTRIBUTING.md).
 - **Go 1.26+** (see `go.mod` for pinned version)
 - **PostgreSQL with TimescaleDB** — the compose stack includes `timescale/timescaledb:2.17.2-pg16`
 - **Docker** for the full dev stack
+- **Node 22+** for `web/` (the control-room SPA — standalone, not part of the
+  compose stack or the `oikos` binary)
 
 ```bash
-# Start dependencies (Postgres + Redis)
-docker compose --profile dev up -d
+# Start dependencies (Postgres + Redis). api/nomos require a shared bearer
+# token — no dev-open bypass — so set one even for local dev.
+OIKOS_MCP_BEARER_TOKEN=dev-token docker compose --profile dev up -d
 
 # Run all tests
 make test
@@ -22,13 +25,48 @@ make test-db
 
 # Build the binary
 make build
+
+# SPA dev server (proxies to api/nomos, injecting the same token)
+cd web && OIKOS_API_TOKEN=dev-token npm run dev
+
+# Desktop app (macOS)
+make desktop                  # build .app bundle
+make install                  # build + install to /Applications
+./cmd/desktop/build/bin/oikos-desktop.app/Contents/MacOS/oikos-desktop  # run from terminal to see logs
 ```
 
+### Desktop app auth
+
+The desktop app uses the same API as the browser SPA. First launch:
+
+1. Enter `https://oikos.hubris.network` as Server URL
+2. **Login with Authentik** tab → opens system browser → authenticate
+3. Callback page shows token → copy → paste into Token tab → Connect
+4. Token is persisted to the macOS keychain — subsequent launches skip setup
+
+The app stores credentials via `github.com/zalando/go-keyring` (service: `com.hubris.oikos-desktop`).
+
+### Desktop app auto-update
+
+- Checks Gitea releases every 6 hours
+- System tray → **Check for Updates** triggers an immediate check
+- Download, extract, replace the app in `/Applications`, and relaunch
+- Versions are compared against the `version` var in `main.go`, injected from the repo `VERSION` file at link time (`make desktop` passes `-ldflags "-X main.version=$(cat VERSION)"`)
+
 ## Project structure
 
 ```
+cmd/desktop/        Wails v3 desktop app (macOS + Linux)
+  main.go            Thin shell: webview, system tray, notifications, auto-update
+  wails.json         Wails project config
+  entitlements.plist macOS code-signing entitlements
+  icon.png           System tray icon (embedded)
+  icon.icns          App bundle icon (white logo on black rounded rect)
+  Taskfile.yml       Wails v3 build tasks
+  Info.plist.template macOS bundle metadata
 cmd/oikos/          Single-binary entry point
 cmd/nomos/          Nomos MCP client gateway
+cmd/webhook/        Gitea deploy-webhook receiver (push-to-deploy on mac-mini)
 internal/           All Go packages
   httpapi/          REST + MCP server (OpenAPI-generated)
   mcp/              MCP tool implementations
@@ -42,15 +80,20 @@ internal/           All Go packages
   domain/           Core types: entities, approvals, signals, patterns
   ontology/         Type hierarchy, relationship validation
   knowledge/        Knowledge YAML seed ingestion
+web/                Control-room SPA (Svelte 5) — standalone, not embedded
+                    in the oikos binary; see plans/2026-07-12-wails-desktop-app.md
 api/openapi.yaml    API contract — the source of truth for endpoints
 migrations/         Forward-only SQL migrations (TimescaleDB)
 seeds/              Bootstrap YAML: ontology, inventory, policy, knowledge
 compose/            Dockerfiles + Caddy config
 scripts/            Deploy, watchdog, rollback
+checks/             Host health-check scripts run over SSH by the scheduler
+tools/              Client auto-setup scripts (checks)
 nomos/              Nomos config, persona, skills
 .agents/            Agent instruction files + skills
 plans/              Design documents
 docs/adr/           Architecture decision records
+docs/operations/    Runbooks (rollback, etc.)
 ```
 
 ## Commands
@@ -68,6 +111,13 @@ docs/adr/           Architecture decision records
 | `make export` | Export DB state to YAML seeds |
 | `make dev` | Start compose dev stack |
 | `make clean` | Remove binary + test cache |
+| `make ui` | Build the SPA (`web/dist/`) |
+| `make deploy-ui` | Build + deploy the SPA to the Caddy host |
+| `make desktop` | Build the Wails desktop app for the current platform |
+| `make desktop-package` | Build + package (zip on macOS, tar.gz on Linux) |
+| `make install` | Build + install to `/Applications` (macOS) |
+| `make webhook` | Build `cmd/webhook` (deploy-webhook receiver) |
+| `make tidy` | `go mod tidy` |
 
 ## Conventions
 

Makefile

@@ -1,11 +1,15 @@
-.PHONY: build test test-db lint generate generate-check dev migrate seed export clean tidy
+.PHONY: build webhook test test-db lint generate generate-check dev migrate seed export clean tidy ui desktop desktop-package install
 
-BINARY := oikos
+BINARY := bin/oikos
 GO ?= go
 
 build:
+	mkdir -p bin
 	$(GO) build -o $(BINARY) -tags timetzdata ./cmd/oikos
 
+webhook:
+	$(GO) build -o webhook -tags timetzdata ./cmd/webhook
+
 test:
 	$(GO) test -race -cover ./...
 
@@ -16,9 +20,18 @@ test-db:
 	OIKOS_TEST_DATABASE_URL="postgres://oikos:$${OIKOS_DB_PASSWORD:-oikos_dev}@localhost:5432/oikos?sslmode=disable" \
 		$(GO) test -race -count=1 ./internal/db/ ./internal/httpapi/ ./internal/mcp/
 
-lint:
+lint: vet golangci govulncheck
+
+vet:
 	$(GO) vet ./...
-	@command -v golangci-lint >/dev/null 2>&1 && golangci-lint run || echo "golangci-lint not installed, skipping"
+
+golangci:
+	@command -v golangci-lint >/dev/null 2>&1 && golangci-lint run --config .golangci.yml || echo "golangci-lint not installed — see https://golangci-lint.run/usage/install/"
+
+govulncheck:
+	@command -v govulncheck >/dev/null 2>&1 && govulncheck ./... || echo "govulncheck not installed — run: go install golang.org/x/vuln/cmd/govulncheck@latest"
+
+.PHONY: lint vet golangci govulncheck
 
 generate:
 	$(GO) run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.4.1 \
@@ -42,8 +55,45 @@ export:
 dev:
 	docker compose --profile dev up -d
 
+# Local sanity-check build of the SPA. Not embedded in the oikos binary
+# (plans/2026-07-12-wails-desktop-app.md 0.1) — deploys as its own
+# container (compose/web/Dockerfile) via `docker compose --profile full
+# up -d web`, same push-to-main pipeline as everything else.
+ui:
+	cd web && npm run build
+
+desktop: ui   ## Build the Wails desktop app for the current platform
+	rm -rf cmd/desktop/frontend/dist
+	mkdir -p cmd/desktop/frontend/dist
+	cp -r web/dist/* cmd/desktop/frontend/dist/
+	cd cmd/desktop && CGO_ENABLED=1 go build -ldflags "-X main.version=$$(cat ../VERSION)" -o build/bin/Oikos .
+
+desktop-package: desktop   ## Build + package the desktop app (zip on macOS, tar.gz on Linux)
+	@case $$(uname -s) in \
+		Darwin) \
+			APP="cmd/desktop/build/bin/Oikos.app"; \
+			rm -rf "$$APP"; \
+			mkdir -p "$$APP/Contents/MacOS"; \
+			mkdir -p "$$APP/Contents/Resources"; \
+			cp cmd/desktop/build/bin/Oikos "$$APP/Contents/MacOS/Oikos"; \
+			cp cmd/desktop/icon.icns "$$APP/Contents/Resources/icon.icns"; \
+			sed "s/\$$(VERSION)/$$(cat VERSION)/" cmd/desktop/Info.plist.template > "$$APP/Contents/Info.plist"; \
+			cd cmd/desktop/build/bin && zip -r oikos-desktop-darwin-$$(uname -m).zip Oikos.app ;; \
+		Linux) \
+			cd cmd/desktop/build/bin && tar czf oikos-desktop-linux-$$(uname -m).tar.gz Oikos ;; \
+	esac
+	@echo "Package: cmd/desktop/build/bin/"
+
+install: desktop-package   ## Install to /Applications
+	rm -rf /Applications/Oikos.app
+	cp -r cmd/desktop/build/bin/Oikos.app /Applications/
+	@echo "Installed to /Applications/Oikos.app"
+
 clean:
 	rm -f $(BINARY)
+	rm -rf bin
+	rm -rf cmd/desktop/build
+	rm -rf cmd/desktop/frontend/dist
 	$(GO) clean -testcache
 
 tidy:

README.md

@@ -13,18 +13,24 @@ learns from outcomes, and escalates when uncertain.
 ## Quick start
 
 ```bash
-# Dev stack (postgres + api + scheduler + notifier)
-docker compose --profile dev up -d
+# Dev stack (postgres + api + scheduler + notifier). The api/nomos
+# services need a shared token — every route requires a real bearer
+# credential, there's no dev-open bypass.
+OIKOS_MCP_BEARER_TOKEN=dev-token docker compose --profile dev up -d
 
 # Full stack (adds Nomos agent gateway)
-docker compose --profile full up -d
+OIKOS_MCP_BEARER_TOKEN=dev-token docker compose --profile full up -d
 
 # Build standalone binary
 go build -o bin/oikos -tags timetzdata ./cmd/oikos
 
 # Run all roles in one process (dev mode)
 OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disable" \
+  OIKOS_API_TOKEN=dev-token \
   go run ./cmd/oikos all
+
+# Control-room SPA (separate from the Go binary — see web/)
+cd web && OIKOS_API_TOKEN=dev-token npm run dev   # http://localhost:5173
 ```
 
 ## Architecture
@@ -43,7 +49,7 @@ OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disa
 
 | Component | Port | Role |
 |-----------|------|------|
-| `oikos api` | 8090 | REST API + MCP server (15 tools) |
+| `oikos api` | 8090 | REST API + MCP server (tool list in [AGENTS.md §3](AGENTS.md#3-the-mcp-server)) |
 | `oikos scheduler` | — | Probe runner, signal lifecycle, metrics |
 | `oikos notifier` | — | Approval tokens, Matrix alerts |
 | `nomos serve` | 8092 | MCP client gateway, query routing |
@@ -59,16 +65,19 @@ OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disa
 | 5 — Secrets | ✅ | Infisical backend + SOPS fallback, rotation runbooks |
 | 6 — Deploy | ✅ | CI pipeline, cutover checklist, watchdog, rollback |
 
-Full plan: [plans/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md](plans/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md).
+Full plan: [plans/done/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md](plans/done/2026-07-06-consolidate-oikos-control-plane-onto-mac-mini.md).
 
 ## Operations
 
 ### API endpoints
 
 ```bash
-curl http://localhost:8090/api/v1/entities?type=service  # fleet
-curl http://localhost:8090/api/v1/health                  # fleet health
-curl http://localhost:8090/api/v1/agent-activity          # agent log
+curl -H "Authorization: Bearer $OIKOS_API_TOKEN" \
+  http://localhost:8090/api/v1/entities?type=service  # fleet
+curl -H "Authorization: Bearer $OIKOS_API_TOKEN" \
+  http://localhost:8090/api/v1/health                  # fleet health
+curl -H "Authorization: Bearer $OIKOS_API_TOKEN" \
+  http://localhost:8090/api/v1/agent-activity          # agent log
 ```
 
 ### Nomos queries
@@ -97,24 +106,41 @@ oikos secret list # enumerate SOPS secrets
 oikos secret migrate  # SOPS → Infisical
 ```
 
+### Web UI
+
+`web/` is a standalone Svelte 5 SPA — not embedded in the `oikos` binary, not
+part of `docker-compose.yml`. It talks to `api`/`nomos` over HTTP with a
+bearer token entered on first launch (see `web/src/pages/Config.svelte`).
+Build with `make ui`, deploy with `make deploy-ui` (Caddy serves the static
+output). A native desktop wrapper exists at `cmd/desktop/` — see
+[plans/done/2026-07-12-wails-desktop-app.md](plans/done/2026-07-12-wails-desktop-app.md).
+
 ## Repo layout
 
 ```
 cmd/oikos/          Go entry point — single binary
 cmd/nomos/          Nomos MCP client gateway
-internal/           Go packages (httpapi, mcp, scheduler, actuator, learning,
-                    notifier, policy, secrets, db, config, ontology, domain,
-                    knowledge)
+cmd/webhook/        Gitea deploy-webhook receiver (push-to-deploy on mac-mini)
+cmd/desktop/        Wails desktop wrapper around the SPA
+internal/           Go packages (actuator, checkdefaults, config, db, domain,
+                    httpapi, knowledge, learning, mcp, notifier, observability,
+                    ontology, policy, safego, scheduler, secrets)
+web/                Control-room SPA (Svelte 5) — standalone, not embedded
 api/openapi.yaml    API contract (OpenAPI 3.1)
 migrations/         Forward-only SQL migrations (TimescaleDB)
 seeds/              Bootstrap YAML (ontology, inventory, policy, knowledge)
 compose/            Dockerfiles + Caddy config
 scripts/            Deploy, watchdog, verification, rollback
+checks/             Host health-check scripts run over SSH by the scheduler
+tools/              Client auto-setup scripts (checks)
+ssh/                Deploy keys + authorized_keys management
+vps/                Caddy/TURN config templates for the netbird VPS
 nomos/              Nomos config, persona, skills
 .agents/            Agent instruction files, shared conventions, skills
 archive/            Historical reference (legacy wiki, plans, SOPS backups)
 plans/              Design documents (active + done)
 docs/adr/           Architecture decision records
+docs/operations/    Runbooks (rollback, etc.)
 ```
 
 ## For agents

VERSION

@@ -0,0 +1 @@
+0.23.0

api/openapi.yaml

@@ -2284,6 +2284,23 @@ components:
           type: boolean
         version:
           type: integer
+        last_health:
+          type: string
+          description: >-
+            This check's own most recent verdict. An entity's health is the
+            worst of these across its enabled checks, so this is what explains
+            *why* an entity is degraded. Null until the check first runs.
+          nullable: true
+          enum:
+          - healthy
+          - degraded
+          - down
+          - unknown
+        last_run_at:
+          type: string
+          format: date-time
+          description: When this check last executed. Null = never run.
+          nullable: true
     CheckCreate:
       type: object
       required:

archive/knowledge/infrastructure/oikos-check-lifecycle.md

@@ -0,0 +1,104 @@
+# Oikos check lifecycle — how monitoring works
+
+This runbook covers how Oikos health checks are derived, created, and wired so
+an agent (Nomos) doesn't reverse-engineer source when asked to add monitoring to
+an entity — the problem that stranded session `23da10db` (2026-08-03).
+
+## Concepts
+
+- **`check_defs`** (scheduler config, table `check_defs`): the row the scheduler
+  reads to know *what* to probe and *when*. One per check instance.
+- **`check` entity** (type `check`, slug `check:<kind>:<target>:<n>`): the
+  knowledge-graph entity for that check. It carries attributes
+  (`check_type`, `target`, `port`, …) and `checks` edges to the probed target.
+- **`monitoring` spec** on an entity type (`entity_types.monitoring_spec`): the
+  default list of check kinds (e.g. `[http, process]` for `service`).
+  - Per-entity override: set `monitoring` in the entity's attributes —
+    `"none"` for zero checks, `["http"]` to replace the type defaults.
+- **`checkdefaults.Ensure`** (`internal/checkdefaults/defaults.go`): the
+  function that reads the monitoring spec, resolves host/port/URL from
+  attributes + relationships, and writes `check_defs` rows. Idempotent.
+
+## When checks are derived
+
+`checkdefaults.Ensure` runs in three situations (as of v0.17.1+):
+
+1. **Seed/deploy ingest** — `internal/db/seed.go:231`. Every entity gets its
+   default checks once on initial ingest.
+2. **HTTP `POST /api/v1/entities` (create)** — `ensureDefaultChecks` at
+   `internal/httpapi/impl.go:1012`. Creating an entity via the REST API derives
+   its checks in the same transaction.
+3. **HTTP `PATCH /api/v1/entities` (patch)** — `ensureDefaultChecks` at
+   `internal/httpapi/impl.go:1280`. Changing an entity's attributes (especially
+   `monitoring`) via the REST API regenerates its checks.
+4. **MCP `create_entity`** — SAME hook. Creating an entity via the MCP tool
+   derives checks. (Added 2026-08-03; previously MCP had no create.)
+5. **MCP `update_entity_attributes`** — SAME hook. Changing an entity's
+   `monitoring` attribute via MCP now regenerates checks. (Added 2026-08-03;
+   previously MCP updates silently skipped check derivation — the exact bug
+   that stranded the haos session.)
+
+## Check slug grammar
+
+```
+check:<kind>:<target-type>:<target-name>:<n>
+```
+
+Examples: `check:http:service:jellyfin:0`, `check:vm-status:vm:haos:0`,
+`check:cert-expiry:cert:house.hubris.network:0`.
+
+## Adding monitoring to an entity
+
+**If the entity already exists:**
+
+```
+update_entity_attributes(slug="service:haos", attributes={"monitoring":["http"]})
+```
+
+This regenerates checks via `checkdefaults.Ensure`. The result message tells you
+how many checks were derived and whether any kinds were skipped (and why).
+
+**If the entity does not exist yet (a new check, ingress, cert, etc.):**
+
+```
+create_entity(type="check", name="HAOS http check",
+  slug="check:http:service:haos:0",
+  attributes={"check_type":"http:service","target":"service:haos","port":"8123"})
+```
+
+This creates the entity AND derives its `check_defs`. Same for a new `ingress`
+(`type=ingress`, monitoring `[http]`) or `cert` (`type=cert`,
+monitoring `[cert-expiry]`).
+
+**To remove monitoring:** set `monitoring:["none"]` or transition the entity
+to a terminal lifecycle state (`set_entity_state` → `deprecated`/`destroyed`).
+
+## Caveats
+
+- **A service without a `url` attribute AND without a `probe_unit` gets no
+  process check** (the http check covers liveness; the process check would
+  be redundant without an opt-in `probe_unit`). The skip is logged.
+- **A service whose address comes from a `hosts` edge** may produce no checks on
+  initial create because the edge doesn't exist yet — the next inventory ingest
+  (or a later `update_entity_attributes` after the edge is created) fills it in.
+- **A `not found` error from `update_entity_attributes`** means the entity
+  doesn't exist — use `create_entity` instead.
+- **`check_defs` has target columns** (`target_id`, `target_type`). A check
+  entity needs a `checks` relationship (`create_relationship(source=check:…,
+  target=service:…, type="checks")`) so the scheduler can resolve what to
+  probe. `create_entity` derives the check_def; `create_relationship` links
+  the check entity to its target in the graph.
+
+## Related files
+
+- `internal/checkdefaults/defaults.go` — `Ensure`, `Target`, `LogResult`
+- `internal/httpapi/default_checks.go` — `ensureDefaultChecks` (HTTP hook)
+- `internal/db/checks.go` — `db.EnsureEntityChecks` (shared hook)
+- `internal/db/seed.go` — seed-time check derivation
+- `internal/mcp/tools.go` — `create_entity`, `update_entity_attributes`
+
+## Revision history
+
+- **2026-08-03:** Created after session `23da10db` stranded for lack of entity-
+  creation tool and unawareness of check-derivation triggers. Covers the MCP
+  create_entity + update_entity_attributes regen paths added same day.

bootstrap.sh

@@ -3,15 +3,14 @@
 #
 # Thin client model (rev 2): no git clone, no sync timer. Fetches only the
 # agent orientation files (CLIENTS.md, AGENTS.md, OIKOS.md) and tooling
-# (caveman, nomos-soul) from the raw Gitea URL. Enrolls via the Oikos API
-# to receive an age keypair and Infisical machine identity. A lightweight
-# context poller replaces the old 5-minute git pull.
+# (checks) from the raw Gitea URL. Enrolls via the Oikos API to receive an
+# age keypair and Infisical machine identity. A lightweight context poller
+# replaces the old 5-minute git pull.
 #
 # Usage:
 #   curl -fsSL https://git.hubris.network/dtoro/oikos/raw/main/bootstrap.sh \
 #     | sudo bash
 #   curl ... | sudo bash -s -- --with-mcp           # wire Claude's .mcp.json
-#   curl ... | sudo bash -s -- --with-nomos        # install Goose + Nomos
 #   curl ... | sudo bash -s -- --dry-run            # show what would happen
 #
 # Prerequisites:
@@ -28,16 +27,10 @@ REPO_RAW_URL="${HOMELAB_RAW_URL:-https://git.hubris.network/dtoro/oikos/raw/main
 OIKOS_API_URL="${HOMELAB_OIKOS_URL:-https://oikos.hubris.network/api/v1}"
 CLONE_DIR="${HOMELAB_CONTEXT_DIR:-/opt/homelab}"
 MCP_URL="${HOMELAB_MCP_URL:-https://mcp.hubris.network/mcp}"
-NOMOS_MCP_URI="${HOMELAB_NOMOS_MCP_URI:-https://mcp.hubris.network/mcp}"
-NOMOS_MODEL="${HOMELAB_NOMOS_MODEL:-nousresearch/hermes-4-405b}"
 
 WITH_MCP=0
-WITH_NOMOS=0
 DRY_RUN=0
 
-GITEA_TOKEN="${HOMELAB_GITEA_TOKEN:-}"
-GITEA_USER="${HOMELAB_GITEA_USER:-dtoro}"
-
 # ── helpers ──────────────────────────────────────────────────────────
 
 log()  { echo "[oikos] $*"; }
@@ -79,10 +72,7 @@ detect_mesh_ip() {
 while [ $# -gt 0 ]; do
     case "$1" in
         --with-mcp)       WITH_MCP=1 ;;
-        --with-nomos)    WITH_NOMOS=1 ;;
         --dry-run)        DRY_RUN=1 ;;
-        --gitea-token)    GITEA_TOKEN="$2"; shift ;;
-        --gitea-user)     GITEA_USER="$2"; shift ;;
         *) die "unknown flag: $1" ;;
     esac
     shift
@@ -148,7 +138,7 @@ done
 
 # ── fetch tools ──────────────────────────────────────────────────────
 log "fetching tools..."
-for tool in setup-caveman.sh setup-nomos-soul.sh caveman.js caveman_wrapper.sh post-pull.sh; do
+for tool in setup-checks.sh post-pull.sh; do
     url="$REPO_RAW_URL/tools/${tool}"
     dest="$CLONE_DIR/tools/${tool}"
     dry mkdir -p "$(dirname "$dest")"
@@ -161,16 +151,6 @@ for tool in setup-caveman.sh setup-nomos-soul.sh caveman.js caveman_wrapper.sh p
     fi
 done
 
-# ── fetch caveman templates ──────────────────────────────────────────
-for tmpl in git_log.txt git_status.txt test_results.txt; do
-    url="$REPO_RAW_URL/tools/caveman/templates/${tmpl}"
-    dest="$CLONE_DIR/tools/caveman/templates/${tmpl}"
-    dry mkdir -p "$(dirname "$dest")"
-    if curl -fsSL --connect-timeout 10 "$url" -o "$dest.tmp" 2>/dev/null; then
-        mv "$dest.tmp" "$dest"
-    fi
-done
-
 # ── detect control-plane (use localhost if API is reachable directly) ─
 if [ -z "${HOMELAB_OIKOS_URL:-}" ]; then
     if curl -s --connect-timeout 2 http://localhost:8090/api/v1/health >/dev/null 2>&1; then
@@ -300,7 +280,7 @@ case "$OS" in
 esac
 
 # ── run auto-setup scripts ───────────────────────────────────────────
-for setup in "$CLONE_DIR"/tools/*.setup.sh; do
+for setup in "$CLONE_DIR"/tools/setup-*.sh; do
     [ -f "$setup" ] || continue
     log "running setup: $(basename "$setup")"
     dry bash "$setup"
@@ -319,17 +299,6 @@ if [ "$WITH_MCP" -eq 1 ]; then
     log "  + MCP wired to $MCP_URL"
 fi
 
-# ── --with-nomos: install Goose + Nomos wrapper ────────────────────
-if [ "$WITH_NOMOS" -eq 1 ]; then
-    log "installing Nomos agent..."
-    GOOSE_URL="https://github.com/block/goose/releases/latest/download/goose-${OS}-${ARCH:-amd64}"
-    if [ "$OS" = Darwin ]; then GOOSE_URL="https://github.com/block/goose/releases/latest/download/goose-darwin-${ARCH:-arm64}"; fi
-    dry curl -fsSL "$GOOSE_URL" -o /usr/local/bin/goose 2>/dev/null && chmod +x /usr/local/bin/goose || warn "goose not installed"
-    # Drop Nomos persona
-    cp "$CLONE_DIR/NOMOS.md" "$CLONE_DIR/.agents/NOMOS.md" 2>/dev/null || true
-    log "  + Nomos agent installed"
-fi
-
 # ── netbird SSH JWT cache ────────────────────────────────────────────
 if command -v netbird >/dev/null 2>&1; then
     dry netbird up --management-url https://netbird.hubris.network --ssh-jwt-cache-ttl 86400 2>/dev/null || true

checks/cpu_check.sh

@@ -2,12 +2,27 @@
 # cpu_check.sh — CPU usage % and thermal temperature.
 set -euo pipefail
 
-USAGE=$(top -bn1 2>/dev/null | awk '/^%Cpu/ {print 100 - $8}' || true)
-if [ -z "$USAGE" ]; then
-  CORES=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 1)
-  USAGE=$(awk -v cores="$CORES" '{print ($1+$2+$3)*100/cores}' /proc/loadavg 2>/dev/null || echo "0")
+os=$(uname -s)
+
+if [ "$os" = "Darwin" ]; then
+  # `top -l 1 -n 0` prints "CPU usage: X% user, Y% sys, Z% idle".
+  # Usage is 100 minus the idle figure that precedes the literal `idle`.
+  USAGE=$(top -l 1 -n 0 -s 0 2>/dev/null | awk '
+    /^CPU usage/ {
+      for (i = 1; i <= NF; i++) {
+        if ($i == "idle") { gsub(/%/, "", $(i - 1)); printf "%.1f", 100 - $(i - 1) }
+      }
+    }' || true)
+else
+  USAGE=$(top -bn1 2>/dev/null | awk '/^%Cpu/ {print 100 - $8}' || true)
+  if [ -z "$USAGE" ]; then
+    CORES=$(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null || echo 1)
+    USAGE=$(awk -v cores="$CORES" '{print ($1+$2+$3)*100/cores}' /proc/loadavg 2>/dev/null || echo "0")
+  fi
 fi
 
+[ -z "$USAGE" ] && USAGE=0
+
 TEMP=""
 if [ -f /sys/class/thermal/thermal_zone0/temp ]; then
   TEMP=$(awk '{printf "%.1f", $1/1000}' /sys/class/thermal/thermal_zone0/temp 2>/dev/null || true)

checks/disk_usage_check.sh

@@ -2,18 +2,34 @@
 # disk_usage_check.sh — disk usage and inode usage per mountpoint.
 set -euo pipefail
 
-MOUNTS=$(df -k 2>/dev/null | awk 'NR>1 && $1 ~ /^\// && $NF !~ /^\/(snap|dev|proc|sys|run|private)/ {print $NF}' || true)
+# `timeout` caps each df so a single hung/stale mountpoint (a stale NFS
+# export, a wedged ZFS pool) can't stall the whole check — that hung the
+# scheduler's 30s budget on hubris. Available on Linux (coreutils); absent on
+# Darwin, whose local mounts don't hang, so it degrades to an empty prefix.
+TO=""
+if command -v timeout >/dev/null 2>&1; then TO="timeout 8"; fi
+
+# Build the mount list WITHOUT statting anything: reading /proc/mounts never
+# blocks the way `df` does on a stuck filesystem, so the enumeration itself
+# can't hang. Fall back to `df` on hosts without /proc/mounts (macOS).
+if [ -r /proc/mounts ]; then
+  MOUNTS=$(awk '$1 ~ /^\// && $2 !~ /^\/(snap|dev|proc|sys|run|private)/ {print $2}' /proc/mounts || true)
+else
+  MOUNTS=$($TO df -k 2>/dev/null | awk 'NR>1 && $1 ~ /^\// && $NF !~ /^\/(snap|dev|proc|sys|run|private)/ {print $NF}' || true)
+fi
 FIRST=1
 
 echo -n '{"health":"healthy","metrics":{'
 for m in $MOUNTS; do
-  LINE=$(df -k "$m" 2>/dev/null | awk 'NR==2 {print $3, $4, $5, $7}' | tr -d '%' || true)
+  # Each df is bounded: a stuck mount times out and is skipped (LINE empty)
+  # rather than hanging the probe.
+  LINE=$($TO df -k "$m" 2>/dev/null | awk 'NR==2 {print $3, $4, $5, $7}' | tr -d '%' || true)
   if [ -z "$LINE" ]; then continue; fi
   USED=$(echo "$LINE" | awk '{print $1}')
   FREE=$(echo "$LINE" | awk '{print $2}')
   PCT=$(echo "$LINE" | awk '{print $3}')
 
-  INODE_LINE=$(df -i "$m" 2>/dev/null | awk 'NR==2 {print $5}' | tr -d '%' || echo "0")
+  INODE_LINE=$($TO df -i "$m" 2>/dev/null | awk 'NR==2 {print $5}' | tr -d '%' || echo "0")
   INODE_PCT=$(echo "${INODE_LINE:-0}" | sed 's/-/0/')
 
   KEY=$(echo "$m" | sed 's|/|_|g' | sed 's|^_||')

checks/process_check.sh

@@ -1,5 +1,17 @@
 #!/usr/bin/env bash
-# process_check.sh — systemd service liveness.
+# process_check.sh — service liveness.
+#
+# A service entity's name is a logical label, rarely the literal systemd unit
+# or container name. matrix = matrix-synapse.service + element-web/mautrix-*
+# containers; authentik = authentik-server/-worker containers. So checking
+# `systemctl is-active matrix` reports "inactive" for a healthy service.
+#
+# Resolution order, any hit = healthy:
+#   1. exact systemd unit  `systemctl is-active <name>`
+#   2. a systemd unit with the name as prefix  `<name>*.service`
+#   3. a running docker container whose name contains <name>
+# An explicit probe target overrides the label — see checkdefaults, which
+# passes a `probe_unit`/`container`/`systemd_unit` attribute as $1 when set.
 set -euo pipefail
 
 SERVICE="${1:-}"
@@ -8,15 +20,31 @@ if [ -z "$SERVICE" ]; then
   exit 0
 fi
 
-if ! command -v systemctl >/dev/null 2>&1; then
-  echo '{"health":"unknown","signalKind":"process-check","evidence":"systemctl not found"}'
-  exit 0
+ok() { echo "{\"health\":\"healthy\"}"; exit 0; }
+
+# 1. exact systemd unit
+if command -v systemctl >/dev/null 2>&1; then
+  STATE=$(systemctl is-active "$SERVICE" 2>/dev/null | head -1 || true)
+  [ "$STATE" = "active" ] && ok
+
+	# 2. prefix match: matrix -> matrix-synapse.service, house -> house.service, etc.
+	# --no-legend strips the header/footer so grep can see the unit rows; the
+	# pattern is a systemd unit glob.
+	if systemctl list-units --type=service --state=active --no-legend "$SERVICE*.service" 2>/dev/null \
+       | grep -q '\.service'; then
+    ok
+  fi
 fi
 
-STATE=$(systemctl is-active "$SERVICE" 2>/dev/null || echo "unknown")
-
-if [ "$STATE" = "active" ]; then
-  echo "{\"health\":\"healthy\"}"
-else
-  echo "{\"health\":\"degraded\",\"signalKind\":\"$SERVICE\",\"evidence\":\"$SERVICE is $STATE\"}"
+# 3. a running docker container whose name contains the label.
+if command -v docker >/dev/null 2>&1; then
+  if docker ps --filter "status=running" --filter "name=$SERVICE" --format '{{.Names}}' 2>/dev/null \
+       | grep -q .; then
+    ok
+  fi
 fi
+
+STATE=${STATE:-inactive}
+STATE=${STATE//\"/}
+SAFE_SERVICE=${SERVICE//\"/}
+echo "{\"health\":\"degraded\",\"signalKind\":\"process\",\"evidence\":\"$SAFE_SERVICE is $STATE (no active unit/container matched)\"}"

cmd/desktop/Info.plist.template

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en</string>
+	<key>CFBundleExecutable</key>
+	<string>Oikos</string>
+	<key>CFBundleIdentifier</key>
+	<string>com.hubris.oikos-desktop</string>
+	<key>CFBundleIconFile</key>
+	<string>icon</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundleName</key>
+	<string>Oikos</string>
+	<key>CFBundlePackageType</key>
+	<string>APPL</string>
+	<key>CFBundleShortVersionString</key>
+	<string>$(VERSION)</string>
+	<key>CFBundleVersion</key>
+	<string>$(VERSION)</string>
+	<key>LSMinimumSystemVersion</key>
+	<string>13.0</string>
+	<key>NSHighResolutionCapable</key>
+	<true/>
+	<key>NSHumanReadableCopyright</key>
+	<string>Copyright © 2026 Hubris. All rights reserved.</string>
+</dict>
+</plist>

cmd/desktop/Taskfile.yml

@@ -0,0 +1,14 @@
+version: '3'
+
+tasks:
+  build:
+    summary: Build the Oikos desktop app
+    cmds:
+      - go build -o build/bin/Oikos .
+    env:
+      CGO_ENABLED: 1
+
+  dev:
+    summary: Run in development mode
+    cmds:
+      - go run .

cmd/desktop/entitlements.plist

@@ -0,0 +1,26 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.app-sandbox</key>
+	<false/>
+	<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+	<true/>
+	<key>com.apple.security.cs.disable-library-validation</key>
+	<true/>
+	<key>com.apple.security.device.audio-input</key>
+	<false/>
+	<key>com.apple.security.device.camera</key>
+	<false/>
+	<key>com.apple.security.files.user-selected.read-write</key>
+	<true/>
+	<key>com.apple.security.network.client</key>
+	<true/>
+	<key>com.apple.security.network.server</key>
+	<false/>
+	<key>keychain-access-groups</key>
+	<array>
+		<string>$(AppIdentifierPrefix)com.hubris.oikos-desktop</string>
+	</array>
+</dict>
+</plist>

cmd/desktop/main.go

@@ -0,0 +1,788 @@
+package main
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"embed"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"io/fs"
+	"log"
+	"net"
+	"net/http"
+	"net/url"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/wailsapp/wails/v3/pkg/application"
+	"github.com/wailsapp/wails/v3/pkg/events"
+	"github.com/zalando/go-keyring"
+)
+
+//go:embed frontend/dist
+var assets embed.FS
+
+//go:embed icon.png
+var iconPNG []byte
+
+const (
+	keyringService   = "com.hubris.oikos-desktop"
+	keyringUser      = "oikos"
+	updateURL        = "https://git.hubris.network/api/v1/repos/dtoro/oikos/releases"
+	pollInterval     = 30 * time.Second
+	updateInterval   = 6 * time.Hour
+	oidcCallbackPort = 18901
+)
+
+// version is injected at link time via -ldflags "-X main.version=$(cat VERSION)"
+// (Makefile desktop target). The default keeps a non-empty fallback for
+// `go build ./cmd/desktop` without ldflags.
+var version = "0.1.0-dev"
+
+type OikosConfig struct {
+	ApiUrl    string `json:"apiUrl"`
+	Token     string `json:"token,omitempty"`
+	IsDesktop bool   `json:"isDesktop"`
+}
+
+// ---- ConfigService ----
+
+type ConfigService struct{}
+
+func (c *ConfigService) Name() string { return "config" }
+
+func (c *ConfigService) SaveConfig(apiUrl, token string) error {
+	cfg := OikosConfig{ApiUrl: apiUrl, Token: token, IsDesktop: true}
+	data, _ := json.Marshal(cfg)
+	return keyring.Set(keyringService, keyringUser, string(data))
+}
+
+func (c *ConfigService) ClearConfig() error {
+	return keyring.Delete(keyringService, keyringUser)
+}
+
+func (c *ConfigService) GetStoredConfig() *OikosConfig {
+	return loadConfig()
+}
+
+func (c *ConfigService) EnableAutoStart() error {
+	if runtime.GOOS != "darwin" {
+		return fmt.Errorf("autostart not supported on %s", runtime.GOOS)
+	}
+	usr, _ := user.Current()
+	dir := filepath.Join(usr.HomeDir, "Library", "LaunchAgents")
+	os.MkdirAll(dir, 0755)
+
+	exe, _ := os.Executable()
+	plist := fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>com.hubris.oikos-desktop</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>%s</string>
+	</array>
+	<key>RunAtLoad</key>
+	<true/>
+	<key>KeepAlive</key>
+	<false/>
+</dict>
+</plist>`, exe)
+
+	return os.WriteFile(filepath.Join(dir, "com.hubris.oikos-desktop.plist"), []byte(plist), 0644)
+}
+
+func (c *ConfigService) DisableAutoStart() error {
+	if runtime.GOOS != "darwin" {
+		return fmt.Errorf("autostart not supported on %s", runtime.GOOS)
+	}
+	usr, _ := user.Current()
+	path := filepath.Join(usr.HomeDir, "Library", "LaunchAgents", "com.hubris.oikos-desktop.plist")
+	return os.Remove(path)
+}
+
+// ---- Local OIDC server (runs alongside the webview) ----
+
+type oidcSession struct {
+	apiUrl   string
+	verifier string
+	state    string
+	ch       chan string
+}
+
+var (
+	oidcSessionsMu sync.Mutex
+	oidcSessions   = make(map[string]*oidcSession)
+)
+
+func startOIDCServer() *http.Server {
+	mux := http.NewServeMux()
+
+	cors := func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		w.Header().Set("Access-Control-Allow-Methods", "GET, OPTIONS")
+		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
+		if r.Method == "OPTIONS" {
+			w.WriteHeader(http.StatusOK)
+		}
+	}
+
+	h := func(path string, handler func(http.ResponseWriter, *http.Request)) {
+		mux.HandleFunc(path, func(w http.ResponseWriter, r *http.Request) {
+			cors(w, r)
+			if r.Method == "OPTIONS" {
+				return
+			}
+			handler(w, r)
+		})
+	}
+
+	h("/oidc/start", func(w http.ResponseWriter, r *http.Request) {
+		apiUrl := strings.TrimRight(r.URL.Query().Get("apiUrl"), "/")
+		returnURL := r.URL.Query().Get("ret")
+		if apiUrl == "" {
+			http.Error(w, "apiUrl required", http.StatusBadRequest)
+			return
+		}
+		if returnURL == "" {
+			returnURL = "/?desktop=1"
+		}
+
+		oidcCfg, err := fetchOIDCConfig(apiUrl)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusServiceUnavailable)
+			return
+		}
+
+		verifier, challenge, _ := pkceParams()
+		state := randomString(32)
+		redirectURI := fmt.Sprintf("http://127.0.0.1:%d/oidc/callback", oidcCallbackPort)
+
+		ch := make(chan string, 1)
+		oidcSessionsMu.Lock()
+		sessionID := randomString(16)
+		oidcSessions[sessionID] = &oidcSession{apiUrl: apiUrl, verifier: verifier, state: state, ch: ch}
+		oidcSessionsMu.Unlock()
+
+		authURL := fmt.Sprintf("%s?%s",
+			oidcCfg.AuthorizationEndpoint,
+			url.Values{
+				"response_type":         {"code"},
+				"client_id":             {oidcCfg.ClientID},
+				"redirect_uri":          {redirectURI},
+				"code_challenge":        {challenge},
+				"code_challenge_method": {"S256"},
+				"state":                 {state},
+				"scope":                 {"openid profile email"},
+			}.Encode(),
+		)
+
+		exec.Command("open", authURL).Start()
+
+		select {
+		case token := <-ch:
+			if token != "" {
+				c := &ConfigService{}
+				c.SaveConfig(apiUrl, token)
+				returnURL += "&token=" + url.QueryEscape(token)
+			}
+		case <-time.After(5 * time.Minute):
+		}
+
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		fmt.Fprintf(w, `<!DOCTYPE html><html><head><meta charset="UTF-8"><title>Oikos</title>
+<meta http-equiv="refresh" content="0;url=%s">
+<style>body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#0a0a0a;color:#e0e0e0;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}
+.card{background:#1a1a1a;border:1px solid #2a2a2a;border-radius:12px;padding:32px;max-width:400px;text-align:center}
+h1{font-size:18px;margin-bottom:8px}.ok{color:#22c55e;font-size:14px}</style>
+</head><body><div class="card"><h1>Connected</h1><p class="ok">Redirecting back to Oikos…</p></div></body></html>`, returnURL)
+	})
+
+	h("/oidc/callback", func(w http.ResponseWriter, r *http.Request) {
+		code := r.URL.Query().Get("code")
+		gotState := r.URL.Query().Get("state")
+
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+
+		oidcSessionsMu.Lock()
+		var session *oidcSession
+		var sessionID string
+		for id, s := range oidcSessions {
+			if s.state == gotState {
+				session = s
+				sessionID = id
+				break
+			}
+		}
+		oidcSessionsMu.Unlock()
+
+		if session == nil {
+			w.WriteHeader(http.StatusBadRequest)
+			w.Write([]byte("Invalid state."))
+			return
+		}
+
+		token, err := exchangeCode(
+			session.apiUrl,
+			code, session.verifier,
+			fmt.Sprintf("http://127.0.0.1:%d/oidc/callback", oidcCallbackPort),
+		)
+
+		oidcSessionsMu.Lock()
+		delete(oidcSessions, sessionID)
+		oidcSessionsMu.Unlock()
+
+		if err != nil {
+			w.WriteHeader(http.StatusInternalServerError)
+			fmt.Fprintf(w, "Token exchange failed: %v", err)
+			session.ch <- ""
+			return
+		}
+
+		w.Write([]byte(`<!DOCTYPE html><html><head><meta charset="UTF-8"><title>Oikos</title>
+<style>body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#0a0a0a;color:#e0e0e0;display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}
+.card{background:#1a1a1a;border:1px solid #2a2a2a;border-radius:12px;padding:32px;max-width:400px;text-align:center}
+h1{font-size:18px;margin-bottom:8px}.ok{color:#22c55e;font-size:14px}</style>
+</head><body><div class="card"><h1>Connected</h1><p class="ok">You can close this window and return to Oikos.</p></div></body></html>`))
+		session.ch <- token
+	})
+
+	mux.HandleFunc("/oidc/config", func(w http.ResponseWriter, r *http.Request) {
+		apiUrl := strings.TrimRight(r.URL.Query().Get("apiUrl"), "/")
+		if apiUrl == "" {
+			http.Error(w, "apiUrl required", http.StatusBadRequest)
+			return
+		}
+		cfg, err := fetchOIDCConfig(apiUrl)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusServiceUnavailable)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(cfg)
+	})
+
+	mux.HandleFunc("/update/check", func(w http.ResponseWriter, r *http.Request) {
+		latest := fetchLatestRelease()
+		w.Header().Set("Content-Type", "application/json")
+		w.Header().Set("Access-Control-Allow-Origin", "*")
+		if latest == nil {
+			json.NewEncoder(w).Encode(map[string]string{"current": version})
+			return
+		}
+		hasAsset := false
+		for _, a := range latest.Assets {
+			if strings.Contains(a.Name, "darwin") {
+				hasAsset = true
+				updater.mu.Lock()
+				updater.latestURL = a.BrowserDownloadURL
+				updater.mu.Unlock()
+				break
+			}
+		}
+		json.NewEncoder(w).Encode(map[string]string{
+			"current":   version,
+			"latest":    latest.Version,
+			"has_asset": fmt.Sprintf("%t", hasAsset),
+		})
+	})
+
+	listener, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", oidcCallbackPort))
+	if err != nil {
+		log.Printf("OIDC server: %v", err)
+		return nil
+	}
+	log.Printf("OIDC server listening on %s", listener.Addr())
+	srv := &http.Server{Handler: mux}
+	go srv.Serve(listener)
+	return srv
+}
+
+// ---- Window persistence ----
+
+type windowState struct {
+	X      int `json:"x"`
+	Y      int `json:"y"`
+	Width  int `json:"width"`
+	Height int `json:"height"`
+}
+
+func windowStatePath() string {
+	usr, _ := user.Current()
+	return filepath.Join(usr.HomeDir, ".config", "oikos", "window.json")
+}
+
+func loadWindowState() *windowState {
+	data, err := os.ReadFile(windowStatePath())
+	if err != nil {
+		return nil
+	}
+	var ws windowState
+	if err := json.Unmarshal(data, &ws); err != nil {
+		return nil
+	}
+	if ws.Width < 200 || ws.Height < 200 {
+		return nil
+	}
+	return &ws
+}
+
+func saveWindowState(w application.Window) {
+	x, y := w.Position()
+	width, height := w.Size()
+	ws := windowState{X: x, Y: y, Width: width, Height: height}
+	data, _ := json.Marshal(ws)
+
+	usr, _ := user.Current()
+	dir := filepath.Join(usr.HomeDir, ".config", "oikos")
+	os.MkdirAll(dir, 0755)
+	os.WriteFile(filepath.Join(dir, "window.json"), data, 0644)
+}
+
+func loadConfig() *OikosConfig {
+	data, err := keyring.Get(keyringService, keyringUser)
+	if err != nil {
+		return nil
+	}
+	var cfg OikosConfig
+	if err := json.Unmarshal([]byte(data), &cfg); err != nil {
+		return nil
+	}
+	cfg.IsDesktop = true
+	return &cfg
+}
+
+type oidcConfig struct {
+	Issuer                string `json:"issuer"`
+	ClientID              string `json:"client_id"`
+	AuthorizationEndpoint string `json:"authorization_endpoint"`
+}
+
+func fetchOIDCConfig(apiUrl string) (*oidcConfig, error) {
+	resp, err := http.Get(apiUrl + "/api/v1/auth/oidc-config")
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != 200 {
+		return nil, fmt.Errorf("server returned %d", resp.StatusCode)
+	}
+	var cfg oidcConfig
+	if err := json.NewDecoder(resp.Body).Decode(&cfg); err != nil {
+		return nil, err
+	}
+	return &cfg, nil
+}
+
+func pkceParams() (verifier, challenge string, _ error) {
+	v := randomString(64)
+	h := sha256.Sum256([]byte(v))
+	return v, base64.RawURLEncoding.EncodeToString(h[:]), nil
+}
+
+func randomString(n int) string {
+	b := make([]byte, n)
+	rand.Read(b)
+	return base64.RawURLEncoding.EncodeToString(b)
+}
+
+func exchangeCode(apiUrl, code, verifier, redirectURI string) (string, error) {
+	body, _ := json.Marshal(map[string]string{
+		"grant_type":    "authorization_code",
+		"code":          code,
+		"code_verifier": verifier,
+		"redirect_uri":  redirectURI,
+	})
+
+	resp, err := http.Post(apiUrl+"/api/v1/auth/oidc-token", "application/json", strings.NewReader(string(body)))
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		b, _ := io.ReadAll(resp.Body)
+		return "", fmt.Errorf("token endpoint: %d — %s", resp.StatusCode, string(b))
+	}
+
+	var tokens struct {
+		AccessToken string `json:"access_token"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&tokens); err != nil {
+		return "", err
+	}
+	if tokens.AccessToken == "" {
+		return "", fmt.Errorf("no access_token in response")
+	}
+	return tokens.AccessToken, nil
+}
+
+// ---- Notifications ----
+
+type dashboardSummary struct {
+	ApprovalsPending int `json:"approvals_pending"`
+	Signals          struct {
+		Critical int `json:"critical"`
+	} `json:"signals_by_severity"`
+}
+
+func (d *dashboardSummary) alertCount() int {
+	return d.ApprovalsPending + d.Signals.Critical
+}
+
+func notify(title, subtitle string) {
+	if runtime.GOOS != "darwin" {
+		return
+	}
+	script := fmt.Sprintf(
+		`display notification "%s" with title "%s" sound name "default"`,
+		strings.ReplaceAll(subtitle, `"`, `\"`),
+		strings.ReplaceAll(title, `"`, `\"`),
+	)
+	exec.Command("osascript", "-e", script).Run()
+}
+
+func pollDashboard(cfg *OikosConfig) {
+	if cfg == nil || cfg.ApiUrl == "" || cfg.Token == "" {
+		return
+	}
+
+	var lastCount int
+	first := true
+
+	for {
+		req, err := http.NewRequest("GET", cfg.ApiUrl+"/api/v1/dashboard/summary", nil)
+		if err != nil {
+			time.Sleep(pollInterval)
+			continue
+		}
+		req.Header.Set("Authorization", "Bearer "+cfg.Token)
+
+		resp, err := http.DefaultClient.Do(req)
+		if err != nil {
+			time.Sleep(pollInterval)
+			continue
+		}
+
+		body, _ := io.ReadAll(resp.Body)
+		resp.Body.Close()
+
+		var summary dashboardSummary
+		if err := json.Unmarshal(body, &summary); err != nil {
+			time.Sleep(pollInterval)
+			continue
+		}
+
+		if first {
+			lastCount = summary.alertCount()
+			first = false
+		} else {
+			current := summary.alertCount()
+			if current > lastCount {
+				notify("Oikos", fmt.Sprintf("%d pending approval(s), %d critical signal(s)", summary.ApprovalsPending, summary.Signals.Critical))
+			}
+			lastCount = current
+		}
+
+		time.Sleep(pollInterval)
+	}
+}
+
+// ---- Auto-update ----
+
+type giteaRelease struct {
+	TagName string `json:"tag_name"`
+	Assets  []struct {
+		Name               string `json:"name"`
+		BrowserDownloadURL string `json:"browser_download_url"`
+	} `json:"assets"`
+}
+
+type updateState struct {
+	mu        sync.Mutex
+	latestURL string
+}
+
+var updater = &updateState{}
+
+// CheckForUpdates checks Gitea releases for a newer version. If found, stores
+// the download URL and returns the latest version string (empty if current).
+func (c *ConfigService) CheckForUpdates() string {
+	latest := fetchLatestRelease()
+	if latest == nil || latest.Version == version {
+		return ""
+	}
+	for _, a := range latest.Assets {
+		if strings.Contains(a.Name, "darwin") {
+			updater.mu.Lock()
+			updater.latestURL = a.BrowserDownloadURL
+			updater.mu.Unlock()
+			return latest.Version
+		}
+	}
+	return ""
+}
+
+// InstallUpdate downloads the stored update, replaces the app, and restarts.
+func (c *ConfigService) InstallUpdate() error {
+	updater.mu.Lock()
+	url := updater.latestURL
+	updater.mu.Unlock()
+	if url == "" {
+		return fmt.Errorf("no update available")
+	}
+	return doUpdate(url)
+}
+
+type latestRelease struct {
+	Version string
+	Assets  []struct {
+		Name               string
+		BrowserDownloadURL string
+	}
+}
+
+func fetchLatestRelease() *latestRelease {
+	resp, err := http.Get(updateURL + "?draft=false&pre-release=false&limit=1")
+	if err != nil {
+		return nil
+	}
+	defer resp.Body.Close()
+
+	var releases []giteaRelease
+	if err := json.NewDecoder(resp.Body).Decode(&releases); err != nil || len(releases) == 0 {
+		return nil
+	}
+
+	r := releases[0]
+	v := strings.TrimPrefix(r.TagName, "v")
+	if v == version {
+		return nil
+	}
+
+	lr := &latestRelease{Version: v}
+	for _, a := range r.Assets {
+		lr.Assets = append(lr.Assets, struct {
+			Name               string
+			BrowserDownloadURL string
+		}{a.Name, a.BrowserDownloadURL})
+	}
+	return lr
+}
+
+func doUpdate(downloadURL string) error {
+	tmp, err := os.CreateTemp("", "oikos-update-*.zip")
+	if err != nil {
+		return err
+	}
+	defer os.Remove(tmp.Name())
+
+	resp, err := http.Get(downloadURL)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if _, err := io.Copy(tmp, resp.Body); err != nil {
+		return err
+	}
+	tmp.Close()
+
+	extractDir, err := os.MkdirTemp("", "oikos-extract")
+	if err != nil {
+		return err
+	}
+	defer os.RemoveAll(extractDir)
+
+	cmd := exec.Command("unzip", "-o", tmp.Name(), "-d", extractDir)
+	if out, err := cmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("unzip: %w: %s", err, out)
+	}
+
+	newApp := filepath.Join(extractDir, "Oikos.app")
+	if _, err := os.Stat(newApp); err != nil {
+		return fmt.Errorf("extracted app not found: %w", err)
+	}
+
+	currentApp := "/Applications/Oikos.app"
+	if _, err := os.Stat(currentApp); os.IsNotExist(err) {
+		if exe, err := os.Executable(); err == nil {
+			currentApp = filepath.Dir(filepath.Dir(filepath.Dir(exe)))
+		}
+	}
+
+	script := fmt.Sprintf(`#!/bin/bash
+sleep 2
+rm -rf "%s"
+mv "%s" "%s"
+open "%s"
+rm "$0"
+`, currentApp, newApp, currentApp, currentApp)
+
+	scriptPath := filepath.Join(os.TempDir(), "oikos-update.sh")
+	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
+		return err
+	}
+
+	app := application.Get()
+	exec.Command("open", scriptPath).Start()
+	if app != nil {
+		app.Quit()
+	}
+
+	return nil
+}
+
+func checkUpdates() {
+	for {
+		time.Sleep(updateInterval)
+
+		latest := fetchLatestRelease()
+		if latest == nil {
+			continue
+		}
+
+		for _, a := range latest.Assets {
+			if strings.Contains(a.Name, "darwin") {
+				updater.mu.Lock()
+				updater.latestURL = a.BrowserDownloadURL
+				updater.mu.Unlock()
+
+				app := application.Get()
+				if app == nil {
+					continue
+				}
+				msg := fmt.Sprintf("Version %s is available (you have %s).", latest.Version, version)
+				app.Dialog.Info().
+					SetTitle("Update Available").
+					SetMessage(msg).
+					Show()
+				break
+			}
+		}
+	}
+}
+
+// ---- Main ----
+
+func main() {
+	oidcSrv := startOIDCServer()
+	defer oidcSrv.Close()
+
+	distFS, err := fs.Sub(assets, "frontend/dist")
+	if err != nil {
+		log.Fatalf("embedded assets: %v", err)
+	}
+
+	app := application.New(application.Options{
+		Name:        "Oikos",
+		Description: "Homelab Control Room",
+		Services: []application.Service{
+			application.NewService(&ConfigService{}),
+		},
+		Assets: application.AssetOptions{
+			Handler: application.AssetFileServerFS(distFS),
+		},
+		Mac: application.MacOptions{
+			ApplicationShouldTerminateAfterLastWindowClosed: false,
+		},
+	})
+
+	systemTray := app.SystemTray.New()
+	systemTray.SetTooltip("Oikos")
+	systemTray.SetIcon(iconPNG)
+
+	trayMenu := application.NewMenu()
+	trayMenu.Add("Open Oikos").OnClick(func(ctx *application.Context) {
+		for _, w := range app.Window.GetAll() {
+			w.Show()
+			w.Focus()
+		}
+	})
+	trayMenu.AddSeparator()
+	trayMenu.Add("Check for Updates").OnClick(func(ctx *application.Context) {
+		go func() {
+			latest := fetchLatestRelease()
+			if latest == nil {
+				app.Dialog.Info().SetTitle("Up to Date").SetMessage("You are running the latest version (" + version + ").").Show()
+				return
+			}
+			for _, a := range latest.Assets {
+				if strings.Contains(a.Name, "darwin") {
+					updater.mu.Lock()
+					updater.latestURL = a.BrowserDownloadURL
+					updater.mu.Unlock()
+					msg := fmt.Sprintf("Version %s is available (you have %s). Install now?", latest.Version, version)
+					d := app.Dialog.Question().SetTitle("Update Available").SetMessage(msg)
+					yes := d.AddButton("Install")
+					yes.OnClick(func() { doUpdate(updater.latestURL) })
+					no := d.AddButton("Later")
+					d.SetDefaultButton(yes)
+					d.SetCancelButton(no)
+					d.Show()
+					return
+				}
+			}
+			app.Dialog.Info().SetTitle("Up to Date").SetMessage("You are running the latest version (" + version + ").").Show()
+		}()
+	})
+	trayMenu.AddSeparator()
+	trayMenu.Add("Quit").OnClick(func(ctx *application.Context) {
+		app.Quit()
+	})
+	systemTray.SetMenu(trayMenu)
+
+	ws := loadWindowState()
+	width, height := 1400, 900
+	if ws != nil {
+		width = ws.Width
+		height = ws.Height
+	}
+
+	window := app.Window.NewWithOptions(application.WebviewWindowOptions{
+		Title:    "Oikos",
+		Width:    width,
+		Height:   height,
+		MinWidth: 1024,
+		MinHeight: 700,
+		URL:      "/?desktop=1",
+	})
+
+	if ws != nil {
+		window.SetPosition(ws.X, ws.Y)
+	} else {
+		window.Center()
+	}
+
+	window.RegisterHook(events.Common.WindowClosing, func(e *application.WindowEvent) {
+		window.Hide()
+		e.Cancel()
+	})
+
+	window.Show()
+
+	systemTray.AttachWindow(window)
+	systemTray.Run()
+
+	app.OnShutdown(func() {
+		saveWindowState(window)
+	})
+
+	go pollDashboard(loadConfig())
+	go checkUpdates()
+
+	err = app.Run()
+	if err != nil {
+		log.Fatal(err)
+	}
+}

cmd/desktop/tray-icon.svg

@@ -0,0 +1,5 @@
+<svg width="88" height="88" viewBox="0 0 110 120" xmlns="http://www.w3.org/2000/svg">
+  <g transform="translate(9, 10) scale(0.9)">
+    <path fill="#ffffff" d="m45.601 1q20.993 0 33.71 15.946 10.799 13.625 10.799 31.287 0 12.414-5.9548 25.131-5.9548 12.717-16.451 19.176-10.395 6.4592-23.213 6.4592-20.892 0-33.205-16.653-10.395-14.029-10.395-31.489 0-12.717 6.2577-25.232 6.3584-12.616 16.653-18.57 10.295-6.0556 21.801-6.0556zm-3.128 6.5605q-5.3492 0-10.799 3.2296-5.3492 3.1287-8.68 11.102-3.3305 7.9735-3.3305 20.488 0 20.185 7.973 34.82 8.0743 14.634 21.195 14.634 9.7896 0 16.149-8.0743 6.3584-8.0743 6.3584-27.755 0-24.627-10.597-38.756-7.1657-9.6888-18.268-9.6888z"/>
+  </g>
+</svg>

cmd/desktop/wails.json

@@ -0,0 +1,9 @@
+{
+  "name": "oikos",
+  "outputfilename": "oikos-desktop",
+  "frontend:dir": "frontend",
+  "author": {
+    "name": "Hubris",
+    "email": "d.toro.v@pm.me"
+  }
+}

cmd/nomos/agent.go

@@ -5,7 +5,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"log/slog"
+	"net/http"
 	"os"
+	"strings"
 	"time"
 
 	"github.com/google/uuid"
@@ -14,24 +16,65 @@ import (
 	"github.com/openai/openai-go/shared"
 )
 
-const maxIterations = 15
+// maxIterations bounds one chat turn's tool-calling loop. Provisioning a
+// service is a long chain (research → plan → run → per-step
+// install/verify run calls), so this must be generous; a full deploy with the
+// decomposed pct_create flow can legitimately need many steps. On exhaustion
+// the loop now produces a real summary (finalSummary) rather than a dead end.
+const maxIterations = 40
+const maxLLMRetries = 3
 
-type agent struct {
-	client   *mcpClient
-	system   string
-	provider *openai.Client
-	model    string
-	store    *store
-	agentID  uuid.UUID
-	reqOpts  []option.RequestOption
+// historyWindowSize bounds how many of a session's most recent persisted
+// messages are replayed into the LLM's context on each turn — see
+// store.go's getRecentMessages for why this exists (fix A2 of
+// plans/2026-07-11-nomos-agent-code-review.md: unbounded history replay was
+// a real, observed-in-production cost/latency/eventual-context-limit risk).
+// 30 is a fixed-window choice, not token-budget-aware: simplest option that
+// still keeps roughly the current task's working context, at the cost of
+// occasionally dropping something a very long task still needed — the
+// system note injected when truncation happens tells the model to check
+// upsert_knowledge/search_knowledge rather than assume something didn't
+// happen. A token-aware trim or LLM-summarize-on-drop are documented
+// stretch options if a fixed window proves insufficient in practice.
+const historyWindowSize = 30
+
+var refusalDenylist = []string{
+	"我没有相关信息",
+	"您可以尝试问我其它问题",
+	"我无法",
+	"抱歉，我无法",
+	"关于这个问题，我没有",
 }
 
-func newAgent(ctx context.Context, mcpClient *mcpClient, st *store, agentSlug string) (*agent, error) {
+type agent struct {
+	clients    *mcpClientPool // one MCP client PER SESSION, not shared — see mcpClientPool's doc comment
+	system     string
+	provider   *openai.Client
+	model      string
+	store      *store
+	agentID    uuid.UUID
+	reqOpts    []option.RequestOption
+	apiBase    string // oikos HTTP API base, derived from NOMOS_MCP_URL, for chat-assent approvals
+	apiToken   string // OIKOS_MCP_BEARER_TOKEN — api's combinedAuth requires it (no dev-open bypass)
+	httpClient *http.Client
+	// gate serializes turns per session (at most one in-flight turn per
+	// sessionID). See turngate.go and plan 2026-08-03 F1.
+	gate *turnGate
+	// queue holds operator messages that arrived while a turn was already
+	// running; they are auto-run when the gate frees (plan 2026-08-03 F2).
+	// See messagequeue.go.
+	queue *messageQueue
+}
+
+func newAgent(ctx context.Context, clients *mcpClientPool, st *store, agentSlug string) (*agent, error) {
 	system := loadSoul()
 	apiKey := os.Getenv("OPENROUTER_API_KEY")
 	model := os.Getenv("NOMOS_MODEL")
 	if model == "" {
-		model = "deepseek/deepseek-v4-flash"
+		// v4-pro over v4-flash: the flash tier over-narrates, occasionally
+		// emits canned refusals, and is unreliable at multi-step tool use —
+		// exactly the agentic provisioning path the operator needs to work.
+		model = "deepseek/deepseek-v4-pro"
 	}
 
 	provider := openai.NewClient(
@@ -60,14 +103,29 @@ func newAgent(ctx context.Context, mcpClient *mcpClient, st *store, agentSlug st
 	}
 	reqOpts := []option.RequestOption{option.WithJSONSet("provider", providerRouting)}
 
+	// Derive the oikos HTTP API base from the MCP URL (e.g.
+	// "http://api:8090/mcp?session_id=..." -> "http://api:8090"). Used for
+	// chat-assent approvals, which call the same decision endpoint the UI's
+	// Approve button calls.
+	mcpURL := os.Getenv("NOMOS_MCP_URL")
+	apiBase := ""
+	if idx := strings.Index(mcpURL, "/mcp"); idx > 0 {
+		apiBase = mcpURL[:idx]
+	}
+
 	return &agent{
-		client:   mcpClient,
-		system:   system,
-		provider: &provider,
-		model:    model,
-		store:    st,
-		agentID:  agentID,
-		reqOpts:  reqOpts,
+		clients:    clients,
+		system:     system,
+		provider:   &provider,
+		model:      model,
+		store:      st,
+		agentID:    agentID,
+		reqOpts:    reqOpts,
+		apiBase:    apiBase,
+		apiToken:   os.Getenv("OIKOS_MCP_BEARER_TOKEN"),
+		httpClient: &http.Client{Timeout: 15 * time.Second},
+		gate:       newTurnGate(),
+		queue:      newMessageQueue(),
 	}, nil
 }
 
@@ -80,7 +138,36 @@ func loadSoul() string {
 	}
 	return `You are Nomos, the steward of the oikos — the AI agent for the hubris homelab.
 You have access to MCP tools to query topology, health, knowledge, and request
-gated mutations through request_execution. Be concise. Prefer tools over guessing.`
+gated mutations through run. Be concise. Prefer tools over guessing.`
+}
+
+// assentWindowDuration is how long after an operator approves a plan that
+// config_mutation commands auto-run without re-approval. The operator
+// approved the plan; the agent should execute it end-to-end without
+// stopping every step to re-ask. Destructive actions still always need
+// explicit typed confirmation regardless of the window.
+const assentWindowDuration = 30 * time.Minute
+
+// openAssentWindow records an active assent window in autonomy_settings so
+// the MCP run tool (separate process) can check it before requiring approval
+// for config_mutation commands. Key is scoped to this agent's UUID AND this
+// session/task — see store.go's assentWindowActive for why: without the
+// session dimension, approving one task's plan would silently auto-run
+// unapproved actions in any other concurrently-running task.
+func (a *agent) openAssentWindow(ctx context.Context, sessionID string) {
+	if a.store == nil || a.store.pool == nil || a.agentID == uuid.Nil || sessionID == "" {
+		return
+	}
+	key := assentWindowKey(a.agentID, sessionID)
+	expires := time.Now().Add(assentWindowDuration).UTC().Format(time.RFC3339)
+	_, err := a.store.pool.Exec(ctx,
+		`INSERT INTO autonomy_settings (key, value) VALUES ($1, $2)
+		 ON CONFLICT (key) DO UPDATE SET value = $2`, key, expires)
+	if err != nil {
+		slog.Warn("nomos: openAssentWindow", "error", err)
+	} else {
+		slog.Info("nomos: assent window opened", "agent", a.agentID, "session", sessionID, "expires", expires)
+	}
 }
 
 type toolDef struct {
@@ -90,35 +177,82 @@ type toolDef struct {
 }
 
 type agentEvent struct {
-	Type       string `json:"type"`
-	Data       any    `json:"data,omitempty"`
-	SessionID  string `json:"session_id,omitempty"`
-	Iteration  int    `json:"iteration,omitempty"`
+	Type      string `json:"type"`
+	Data      any    `json:"data,omitempty"`
+	SessionID string `json:"session_id,omitempty"`
+	Iteration int    `json:"iteration,omitempty"`
+	// IsThinking marks text/text_delta events that carry the model's internal
+	// reasoning (text produced before tool calls in the same iteration), as
+	// distinct from the final response text. The frontend renders these as
+	// collapsible thinking blocks separated from the response.
+	IsThinking bool `json:"is_thinking,omitempty"`
 }
 
 func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(agentEvent)) {
+	a.chatWith(ctx, sessionID, message, "", emit)
+}
+
+// chatWith is chat() with an optional system-injected note appended after the
+// replayed history. The auto-continuation worker uses it to resume a session
+// with a finished execution's result ("execution X completed: … — continue the
+// plan") without persisting a fake user turn. message is normally the new user
+// message; for a worker continuation it is empty and systemInject carries the
+// note.
+func (a *agent) chatWith(ctx context.Context, sessionID, message, systemInject string, emit func(agentEvent)) {
 	correlationID := uuid.New().String()
 
-	tools, err := a.buildTools()
+	// emitError emits an error event followed by a done event. The done
+	// event is CRITICAL on every terminal path: the frontend's
+	// onComplete handler (chat.ts) treats a missing `done` as a severed
+	// network connection and triggers an auto-reconnect → resumeSession.
+	// Before this fix, a model empty-response (the most common case here)
+	// returned without `done`, was misclassified as a network drop, and
+	// the reconnect logic re-invoked the agent with a generic "report
+	// your state" note — which caused the agent to re-propose the plan
+	// and duplicate it in the sidebar (operator-reported 2026-07-14).
+	// Every error return below must go through emitError so the frontend
+	// shows the error inline instead of silently reconnecting.
+	emitError := func(data string) {
+		emit(agentEvent{Type: "error", Data: data, SessionID: sessionID})
+		emit(agentEvent{Type: "done", Data: map[string]any{
+			"session_id":     sessionID,
+			"correlation_id": correlationID,
+			"iterations":     0,
+			"error":          true,
+		}, SessionID: sessionID})
+	}
+
+	tools, err := a.buildTools(sessionID)
 	if err != nil {
-		emit(agentEvent{Type: "error", Data: fmt.Sprintf("build tools: %v", err), SessionID: sessionID})
+		emitError(fmt.Sprintf("build tools: %v", err))
 		return
 	}
 
-	// Rebuild conversation context from persisted history so sessions are
-	// multi-turn. The current user turn is saved by the HTTP handler before
-	// this runs, so it is already included in the history for real sessions.
-	// Prior tool_use/tool_result pairs are replayed as a tool-calling
-	// assistant message followed by matching tool-role results, so the agent
-	// starts each turn already knowing what it already checked instead of
-	// re-querying the same tools from scratch. Ephemeral sessions (no store)
-	// fall back to the single incoming message.
 	system := a.system
-	if snapshot := a.fleetSnapshot(); snapshot != "" {
+	if snapshot := a.fleetSnapshot(sessionID); snapshot != "" {
 		system += "\n\n" + snapshot
 	}
 	messages := []openai.ChatCompletionMessageParamUnion{openai.SystemMessage(system)}
-	history, _ := a.store.getMessages(ctx, sessionID)
+	history, truncatedHistory, _ := a.store.getRecentMessages(ctx, sessionID, historyWindowSize)
+	if truncatedHistory {
+		// Tell the model explicitly rather than silently dropping older
+		// turns — otherwise it might assume something wasn't done just
+		// because it doesn't see the turn that did it.
+		messages = append(messages, openai.SystemMessage(fmt.Sprintf(
+			"[System: this task has been running long enough that only the most recent %d turns of its history are included above your context — earlier turns happened but aren't shown. If you need to know what was already tried or found, check search_knowledge/get_entity_knowledge (if you recorded it) rather than assuming it didn't happen.]",
+			historyWindowSize)))
+	}
+	// sawSetGoal / sawCompleteTask track whether this session has EVER framed
+	// itself as a structured task (set_goal) or already reached a terminal
+	// state (complete_task) — across both replayed history and this turn's
+	// own tool calls (updated again below as they happen live). Used by the
+	// end-of-turn safety net (plans/2026-07-11-task-completion-safety-net.md,
+	// fix 1): most sessions are a single trivial Q&A exchange that answers in
+	// text and never calls either tool, leaving agent_sessions.status stuck
+	// at its creation-time default forever. If a session never framed itself
+	// as a task, its first plain-text turn-end IS the task ending.
+	var sawSetGoal, sawCompleteTask bool
+	var lastAssistantCalls []persistedCall
 	for _, m := range history {
 		text := extractText(m.Content)
 		switch m.Role {
@@ -129,7 +263,14 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 				messages = append(messages, assistantToolCallMessage(calls))
 				for _, c := range calls {
 					messages = append(messages, openai.ToolMessage(c.resultText(), c.id))
+					switch c.name {
+					case "set_goal":
+						sawSetGoal = true
+					case "complete_task":
+						sawCompleteTask = true
+					}
 				}
+				lastAssistantCalls = calls
 			}
 			if text != "" {
 				messages = append(messages, openai.AssistantMessage(text))
@@ -140,6 +281,97 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 		messages = append(messages, openai.UserMessage(message))
 	}
 
+	// Chat-assent approval: if the immediately-preceding assistant turn
+	// proposed gated action(s) and the operator's new message reads as
+	// authorization ("go ahead", "yes", ...), grant them now — this is the
+	// primary approval path; the Approve button in the UI is a fallback for
+	// when the operator wants to click instead of type. Destructive-risk
+	// actions are never granted by loose assent — they need the stricter
+	// isTypedConfirmation ("I confirm ...", per SOUL.md's guidance for what
+	// to ask the operator to type).
+	pending := extractPendingApprovals(lastAssistantCalls)
+	assent := isAssent(message)
+	typedConfirm := isTypedConfirmation(message)
+	if len(pending) > 0 && (assent || typedConfirm) {
+		var granted, blocked []string
+		for _, p := range pending {
+			if p.destructive && !typedConfirm {
+				blocked = append(blocked, p.execID)
+				continue
+			}
+			if !p.destructive && !assent {
+				continue // typed-confirm alone doesn't grant a non-destructive item without also reading as assent
+			}
+			ok, status, aerr := a.approveExecution(ctx, p.execID)
+			if aerr != nil {
+				slog.Error("nomos: chat-assent approve", "execution", p.execID, "error", aerr)
+				continue
+			}
+			if ok {
+				granted = append(granted, p.execID)
+				slog.Info("nomos: chat-assent granted", "execution", p.execID, "status", status, "session", sessionID)
+
+				// An explicit typed confirmation for a destructive action
+				// opens a short, target-scoped window so the rest of a
+				// destructive recovery sequence on the SAME target (e.g.
+				// stop -> destroy) doesn't need a second typed confirmation.
+				if p.destructive && typedConfirm {
+					if execUUID, perr := uuid.Parse(p.execID); perr == nil {
+						if target := a.store.executionTarget(ctx, execUUID); target != "" {
+							a.store.openDestructiveWindow(ctx, a.agentID, target, sessionID)
+							slog.Info("nomos: destructive window opened", "agent", a.agentID, "target", target, "session", sessionID)
+						}
+					}
+				}
+			}
+		}
+		if len(granted) > 0 {
+			a.openAssentWindow(ctx, sessionID)
+			// Mark approved executions as continued so the continuation
+			// worker doesn't call resumeSession while the chat handler is
+			// still processing "go ahead" — two concurrent LLM calls for the
+			// same session cause empty responses and race conditions.
+			for _, execID := range granted {
+				if execUUID, perr := uuid.Parse(execID); perr == nil {
+					a.store.markContinued(ctx, execUUID)
+				}
+			}
+			// No system note. The model already sees "go ahead" in the
+			// replayed history (the user message was saved to the DB before
+			// chat() was called). The old note said "they are now running"
+			// which made the model think work was being done for it —
+			// causing empty responses (finish_reason=stop, content_len=0).
+			// The approved executions are dispatched; the model will
+			// continue with the remaining plan steps naturally.
+		}
+		if len(blocked) > 0 {
+			note := fmt.Sprintf("[System: execution(s) %s are classified DESTRUCTIVE and were NOT approved by loose assent — you must ask the operator for an explicit typed confirmation before they can run. Once they do confirm, further destructive steps on that SAME target (e.g. finishing a stop-then-destroy sequence) will auto-run for 15 minutes without asking again — but a different target always needs its own confirmation.]", strings.Join(blocked, ", "))
+			messages = append(messages, openai.SystemMessage(note))
+		}
+	} else if assent && len(pending) == 0 {
+		// The operator said "proceed"/"go ahead"/"yes" but there are no
+		// pending approvals — the agent proposed a plan (via propose_plan)
+		// and asked "shall I?" Open the assent window silently. No system
+		// note: the model sees "go ahead" in the replayed history and
+		// responds naturally.
+		a.openAssentWindow(ctx, sessionID)
+	}
+
+	// Worker continuation: append the finished-execution note so the model
+	// sees the result and decides the next step (proceed / recover / done).
+	if systemInject != "" {
+		messages = append(messages, openai.SystemMessage(systemInject))
+	}
+
+	// Retry cap (P0.1 from plans/2026-07-18-session-review-three-sessions.md):
+	// track failing `run` calls within this turn so an identical command that
+	// keeps failing is refused after maxRunRetries attempts. Without this,
+	// session 1e9c7691 retried the same `chown` ~20 times, each retry piling
+	// up a zombie process on the target (knfsd was holding a kernel lock).
+	// The tracker is per-turn — a fresh turn after the operator responds can
+	// retry once more, so this doesn't permanently block recovery.
+	retries := newRunRetryTracker()
+
 	for i := 0; i < maxIterations; i++ {
 		params := openai.ChatCompletionNewParams{
 			Model:    openai.ChatModel(a.model),
@@ -147,33 +379,89 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 			Tools:    tools,
 		}
 
-		// Stream the completion, emitting token deltas as they arrive. The
-		// accumulator reassembles the full message (content + tool calls) for
-		// the loop's control flow.
-		stream := a.provider.Chat.Completions.NewStreaming(ctx, params, a.reqOpts...)
-		acc := openai.ChatCompletionAccumulator{}
-		for stream.Next() {
-			chunk := stream.Current()
-			acc.AddChunk(chunk)
-			if len(chunk.Choices) > 0 {
-				if delta := chunk.Choices[0].Delta.Content; delta != "" {
-					emit(agentEvent{Type: "text_delta", Data: delta, SessionID: sessionID, Iteration: i + 1})
+		var msg openai.ChatCompletionMessage
+		var acc openai.ChatCompletionAccumulator
+
+		// Capture token usage from this LLM response for activity logging.
+	// Previously always NULL — every agent_activity row had no token
+	// count. Now each tool call in this iteration gets the same total.
+	totalTokens := 0
+
+	for attempt := 0; attempt <= maxLLMRetries; attempt++ {
+			acc = openai.ChatCompletionAccumulator{}
+			stream := a.provider.Chat.Completions.NewStreaming(ctx, params, a.reqOpts...)
+			for stream.Next() {
+				chunk := stream.Current()
+				acc.AddChunk(chunk)
+				if len(chunk.Choices) > 0 {
+					if delta := chunk.Choices[0].Delta.Content; delta != "" {
+						emit(agentEvent{Type: "text_delta", Data: delta, SessionID: sessionID, Iteration: i + 1})
+					}
 				}
 			}
-		}
-		if err := stream.Err(); err != nil {
-			emit(agentEvent{Type: "error", Data: fmt.Sprintf("llm: %v", err), SessionID: sessionID})
-			return
-		}
-		if len(acc.Choices) == 0 {
-			emit(agentEvent{Type: "error", Data: "no choices in response", SessionID: sessionID})
-			return
-		}
+			if err := stream.Err(); err != nil {
+				if attempt < maxLLMRetries {
+					slog.Warn("nomos: llm stream error, retrying", "error", err, "attempt", attempt+1, "session", sessionID)
+					continue
+				}
+				emitError(fmt.Sprintf("llm: %v", err))
+				return
+			}
+			if len(acc.Choices) == 0 {
+				if attempt < maxLLMRetries {
+					slog.Warn("nomos: no choices in response, retrying", "attempt", attempt+1, "session", sessionID)
+					continue
+				}
+				emitError("no choices in response (the model returned zero completions — likely a provider or rate-limit issue)")
+				return
+			}
 
-		msg := acc.Choices[0].Message
+			msg = acc.Choices[0].Message
+			finishReason := acc.Choices[0].FinishReason
+
+			// Capture token usage from this iteration.
+			if acc.Usage.TotalTokens > 0 {
+				totalTokens = int(acc.Usage.TotalTokens)
+			}
+
+			if len(msg.ToolCalls) == 0 {
+				if isRefusalOrEmpty(msg.Content) {
+				if attempt < maxLLMRetries {
+					slog.Warn("nomos: empty or refusal response, retrying",
+						"session", sessionID, "iter", i+1, "attempt", attempt+1,
+						"content_len", len(msg.Content), "finish_reason", finishReason)
+					continue
+				}
+					// B.4: surface the real error context (finish_reason +
+					// refusal text) instead of a generic "empty response" —
+					// the operator can tell "content_filter — rephrase" from
+					// "length — token limit hit" from "stop — model no-op'd".
+					detail := "empty response"
+					if msg.Refusal != "" {
+						detail = fmt.Sprintf("refusal: %s", msg.Refusal)
+					} else if finishReason != "" && finishReason != "stop" {
+						detail = fmt.Sprintf("finish_reason=%s", finishReason)
+					}
+					emitError(fmt.Sprintf("Nomos returned an empty or unusable response (%s). Retry or rephrase.", detail))
+					return
+				}
+			}
+			break
+		}
 
 		if len(msg.ToolCalls) == 0 {
 			emit(agentEvent{Type: "text", Data: msg.Content, SessionID: sessionID})
+			if !sawSetGoal && !sawCompleteTask {
+				a.autoCompleteTrivialTask(ctx, sessionID, msg.Content)
+			}
+			// Safety net: if the agent called set_goal (structured task)
+			// but didn't call complete_task, and all plan steps are
+			// terminal, auto-complete. The model often does the work but
+			// forgets to close the loop (confirmed live: the #1 remaining
+			// model reliability gap after D.1).
+			if !sawCompleteTask {
+				a.autoCompleteIfPlanDone(ctx, sessionID, msg.Content)
+			}
 			emit(agentEvent{Type: "done", Data: map[string]any{
 				"session_id":     sessionID,
 				"usage":          acc.Usage,
@@ -183,6 +471,18 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 			return
 		}
 
+		// P3: persist intermediate reasoning. When the model produces text
+		// AND tool calls in the same iteration, the text is its reasoning
+		// before the tool calls — the operator saw it live via text_delta,
+		// but without emitting it as a `text` event here, the persist layer
+		// (main.go/continue.go) never captures it and a reload shows only
+		// the final summary + a flat tool-call list, not the thinking that
+		// led to each step. Emitting it lets the persist layer accumulate
+		// per-iteration reasoning into the row's text field.
+		if strings.TrimSpace(msg.Content) != "" {
+			emit(agentEvent{Type: "text", Data: msg.Content, SessionID: sessionID, IsThinking: true})
+		}
+
 		slog.Info("nomos: tool calls", "count", len(msg.ToolCalls), "iter", i+1, "correlation", correlationID)
 
 		messages = append(messages, msg.ToParam())
@@ -193,6 +493,40 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 				args = map[string]any{}
 			}
 
+			switch tc.Function.Name {
+			case "set_goal":
+				sawSetGoal = true
+			case "complete_task":
+				sawCompleteTask = true
+			}
+
+			// Retry cap: if this `run` call has already failed
+			// maxRunRetries times this turn with the same (target,
+			// command), refuse to dispatch it again. Return a synthetic
+			// tool result directing the agent to investigate *why* the
+			// command hangs instead of retrying. See retrycap.go and
+			// plans/2026-07-18-session-review-three-sessions.md P0.1.
+			if tc.Function.Name == "run" {
+				t, _ := args["target"].(string)
+				c, _ := args["command"].(string)
+				key := runFailureKey(t, c)
+				if n := retries.failures(key); n >= maxRunRetries {
+					directive := runRetryDirective(t, c, n)
+					slog.Warn("nomos: run retry cap hit — refusing dispatch",
+						"target", t, "failures", n, "session", sessionID)
+					a.store.logActivity(ctx, a.agentID, sessionID, tc.Function.Name, args,
+						tc.Function.Arguments, directive, 0, false, correlationID, totalTokens)
+					emit(agentEvent{
+						Type:      "tool_result",
+						Data:      map[string]any{"name": tc.Function.Name, "result": directive, "id": tc.ID, "retry_capped": true},
+						SessionID: sessionID,
+						Iteration: i + 1,
+					})
+					messages = append(messages, openai.ToolMessage(directive, tc.ID))
+					continue
+				}
+			}
+
 			emit(agentEvent{
 				Type:      "tool_use",
 				Data:      map[string]any{"name": tc.Function.Name, "args": args, "id": tc.ID},
@@ -201,14 +535,54 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 			})
 
 			start := time.Now()
-			result, callErr := a.client.callTool(tc.Function.Name, args)
+			// Session-scoped task tools are handled in-process; everything else
+			// is forwarded to the shared MCP server.
+			var result any
+			var callErr error
+			if localRes, handled := a.handleTaskTool(ctx, sessionID, tc.Function.Name, args); handled {
+				result = localRes
+			} else {
+				// _session_id rides along on the wire call only — never in
+				// `args` (which is what gets emitted/logged/persisted as the
+				// model's own tool call) — so the MCP-side assent/destructive
+				// window checks can scope to THIS task instead of bleeding
+				// across every concurrently-running one sharing this agent
+				// identity. Not part of any tool's declared InputSchema, so
+				// the model never sees or supplies it.
+				wireArgs := make(map[string]any, len(args)+1)
+				for k, v := range args {
+					wireArgs[k] = v
+				}
+				wireArgs["_session_id"] = sessionID
+				var client *mcpClient
+				client, callErr = a.clients.get(sessionID)
+				if callErr == nil {
+					result, callErr = client.callTool(tc.Function.Name, wireArgs)
+				}
+			}
 			elapsed := int(time.Since(start).Milliseconds())
 
 			inputJSON, _ := json.Marshal(args)
 			inputStr := string(inputJSON)
 
 			if callErr != nil {
-				a.store.logActivity(ctx, a.agentID, sessionID, tc.Function.Name, inputStr, callErr.Error(), elapsed, false, correlationID)
+				a.store.logActivity(ctx, a.agentID, sessionID, tc.Function.Name, args, inputStr, callErr.Error(), elapsed, false, correlationID, totalTokens)
+
+				// Retry cap: dispatch errors (e.g. MCP client timeout)
+				// count toward the cap too. A command that keeps timing
+				// out at the gateway is exactly the pattern we want to
+				// break — see session 1e9c7691's 20+ identical
+				// `chown` timeouts.
+				if tc.Function.Name == "run" {
+					t, _ := args["target"].(string)
+					c, _ := args["command"].(string)
+					key := runFailureKey(t, c)
+					n := retries.recordFailure(key)
+					if n >= maxRunRetries {
+						slog.Warn("nomos: run failure cap reached — next identical call will be refused",
+							"target", t, "failures", n, "session", sessionID)
+					}
+				}
 
 				emit(agentEvent{
 					Type:      "tool_result",
@@ -222,7 +596,27 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 			}
 
 			resultJSON, _ := json.Marshal(result)
-			a.store.logActivity(ctx, a.agentID, sessionID, tc.Function.Name, inputStr, string(resultJSON), elapsed, true, correlationID)
+			a.store.logActivity(ctx, a.agentID, sessionID, tc.Function.Name, args, inputStr, string(resultJSON), elapsed, true, correlationID, totalTokens)
+
+			// Link any execution this tool queued/started back to this
+			// session, so the auto-continuation worker can feed its result
+			// back here when it finishes (see cmd/nomos/continue.go). Async
+			// executions (pct_create, apt_upgrade) are the ones that matter —
+			// their result lands after this turn ends.
+			for _, execID := range extractExecutionIDs(string(resultJSON)) {
+				a.store.linkExecution(ctx, execID, sessionID)
+			}
+
+			// Record which entities this task touched (task —involves→ entity)
+			// and pulse them on the live context panel. Args only — never
+			// results — so a bulk query doesn't drag the whole fleet in.
+			a.store.recordTouched(ctx, sessionID, tc.Function.Name, args)
+
+			// When the agent records knowledge, link that note to this task so
+			// the task's outcome view shows what it learned (and pulse it live).
+			if tc.Function.Name == "upsert_knowledge" {
+				a.store.linkKnowledgeToTask(ctx, sessionID, string(resultJSON))
+			}
 
 			emit(agentEvent{
 				Type:      "tool_result",
@@ -232,10 +626,58 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 			})
 			messages = append(messages, openai.ToolMessage(string(resultJSON), tc.ID))
 			slog.Info("nomos: tool success", "tool", tc.Function.Name, "ms", elapsed)
+
+			// Retry cap: record failures of `run` calls so the cap above
+			// can refuse a repeated identical failure. A "failure" here
+			// means the dispatch errored OR the MCP result text matches
+			// the "run on <target>: ERROR …" signature — both indicate
+			// the command actually ran and failed, not just that it
+			// queued for approval (pending approvals are not failures).
+			// Pass the RAW result text (not JSON-encoded) so the helper's
+			// HasPrefix check sees "run on …" not "\"run on …\"".
+			if isRunFailure(tc.Function.Name, runResultText(result), callErr) {
+				t, _ := args["target"].(string)
+				c, _ := args["command"].(string)
+				key := runFailureKey(t, c)
+				n := retries.recordFailure(key)
+				if n >= maxRunRetries {
+					slog.Warn("nomos: run failure cap reached — next identical call will be refused",
+						"target", t, "failures", n, "session", sessionID)
+				}
+			}
+
+			// ask_operator pauses the task: the agent has posed a decision only
+			// the operator can make. End the turn here so it doesn't barrel past
+			// its own question — the answer (panel or chat reply) resumes it.
+			// The prompt becomes the assistant's visible message so the question
+			// also shows inline in the transcript.
+			if tc.Function.Name == "ask_operator" {
+				prompt, _ := args["prompt"].(string)
+				emit(agentEvent{Type: "text", Data: prompt, SessionID: sessionID})
+				emit(agentEvent{Type: "done", Data: map[string]any{
+					"session_id":     sessionID,
+					"correlation_id": correlationID,
+					"iteration":      i + 1,
+				}, SessionID: sessionID})
+				return
+			}
 		}
 	}
 
-	emit(agentEvent{Type: "text", Data: "Agent loop: max iterations reached without final answer.", SessionID: sessionID})
+	// Hitting the step limit used to end the turn with a bare "max iterations
+	// reached without final answer" — a dead end that made the operator ask
+	// "status?" to find out what actually happened after a long working turn.
+	// Instead, spend one final call asking the model to summarize what it did
+	// and the current state, so the turn always ends with a real report.
+	messages = append(messages, openai.SystemMessage("[System: you've reached the step limit for this turn. STOP calling tools now and write a concise status report: what you accomplished, the current state of the goal, anything that failed, and what remains. This is what the operator sees.]"))
+	summary := a.finalSummary(ctx, messages)
+	if summary == "" {
+		summary = "I hit this turn's step limit while working. I've done a lot but couldn't wrap up cleanly — ask me for a status update and I'll summarize the current state."
+	}
+	emit(agentEvent{Type: "text", Data: summary, SessionID: sessionID})
+	if !sawCompleteTask {
+		a.autoCompleteIfPlanDone(ctx, sessionID, summary)
+	}
 	emit(agentEvent{Type: "done", Data: map[string]any{
 		"session_id":     sessionID,
 		"correlation_id": correlationID,
@@ -243,6 +685,22 @@ func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(a
 	}, SessionID: sessionID})
 }
 
+// finalSummary makes one non-tool LLM call to turn an exhausted tool-loop into
+// a real status report instead of a dead-end message. Best-effort: empty on
+// any error, and the caller has a fallback.
+func (a *agent) finalSummary(ctx context.Context, messages []openai.ChatCompletionMessageParamUnion) string {
+	params := openai.ChatCompletionNewParams{
+		Model:    openai.ChatModel(a.model),
+		Messages: messages,
+		// No Tools: force a text answer.
+	}
+	resp, err := a.provider.Chat.Completions.New(ctx, params, a.reqOpts...)
+	if err != nil || len(resp.Choices) == 0 {
+		return ""
+	}
+	return resp.Choices[0].Message.Content
+}
+
 // extractText pulls the "text" field from a persisted message's JSONB content.
 func extractText(content json.RawMessage) string {
 	var m struct {
@@ -351,8 +809,12 @@ func assistantToolCallMessage(calls []persistedCall) openai.ChatCompletionMessag
 // of spending its first iteration rediscovering topology it already has
 // tools to query. Best-effort: an empty string on any failure just means no
 // snapshot, not an error for the turn.
-func (a *agent) fleetSnapshot() string {
-	result, err := a.client.callTool("get_health_summary", map[string]any{})
+func (a *agent) fleetSnapshot(sessionID string) string {
+	client, err := a.clients.get(sessionID)
+	if err != nil {
+		return ""
+	}
+	result, err := client.callTool("get_health_summary", map[string]any{})
 	if err != nil {
 		return ""
 	}
@@ -388,11 +850,45 @@ func (a *agent) fleetSnapshot() string {
 	return summary
 }
 
-func (a *agent) buildTools() ([]openai.ChatCompletionToolParam, error) {
-	defs, err := a.client.listToolsFull()
+// isRefusalOrEmpty returns true when the LLM response is blank or looks like a
+// canned non-English refusal to an English-language conversation. Flash-tier
+// models occasionally emit Chinese boilerplate deflection instead of a real
+// answer; this catches it before it reaches the UI.
+func isRefusalOrEmpty(text string) bool {
+	if strings.TrimSpace(text) == "" {
+		return true
+	}
+	ascii, nonASCII := 0, 0
+	for _, r := range text {
+		if r <= 127 {
+			ascii++
+		} else {
+			nonASCII++
+		}
+	}
+	if nonASCII > ascii {
+		return true
+	}
+	for _, pattern := range refusalDenylist {
+		if strings.Contains(text, pattern) {
+			return true
+		}
+	}
+	return false
+}
+
+func (a *agent) buildTools(sessionID string) ([]openai.ChatCompletionToolParam, error) {
+	client, err := a.clients.get(sessionID)
 	if err != nil {
 		return nil, err
 	}
+	defs, err := client.listToolsFull()
+	if err != nil {
+		return nil, err
+	}
+	// Append nomos-local, session-scoped task tools (complete_task, …) to the
+	// MCP tool list. They're routed to handleTaskTool, not the MCP client.
+	defs = append(defs, taskToolDefs()...)
 
 	var tools []openai.ChatCompletionToolParam
 	for _, d := range defs {
@@ -413,7 +909,23 @@ func (a *agent) buildTools() ([]openai.ChatCompletionToolParam, error) {
 	return tools, nil
 }
 
+// listToolsFull returns the MCP server's tool list, cached on this client
+// after the first call (see mcpClient.toolsCache). Fix F1 of
+// plans/2026-07-11-nomos-agent-code-review.md: buildTools calls this at the
+// start of every chat turn, including every auto-continuation resume — the
+// tool list is static for the lifetime of one MCP connection, so re-fetching
+// it every single time was avoidable network+parsing work on the hot path.
+// Cache invalidates on reconnectLocked (an api restart may change what's
+// registered).
 func (c *mcpClient) listToolsFull() ([]toolDef, error) {
+	c.toolsMu.Lock()
+	if c.toolsCache != nil {
+		cached := c.toolsCache
+		c.toolsMu.Unlock()
+		return cached, nil
+	}
+	c.toolsMu.Unlock()
+
 	resp, err := c.doRequest("tools/list", map[string]any{})
 	if err != nil {
 		return nil, err
@@ -436,5 +948,9 @@ func (c *mcpClient) listToolsFull() ([]toolDef, error) {
 			InputSchema: t.InputSchema,
 		}
 	}
+
+	c.toolsMu.Lock()
+	c.toolsCache = out
+	c.toolsMu.Unlock()
 	return out, nil
 }

cmd/nomos/assent.go

@@ -0,0 +1,183 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"regexp"
+	"strings"
+)
+
+// Chat-assent approval: the operator authorizes a proposed action by
+// replying normally in chat ("go ahead", "yes", "do it") instead of clicking
+// a separate Approve button. This is deterministic (not LLM-judged) so it
+// can't be talked around by a model that misreads intent, and it only ever
+// looks at the assistant turn immediately preceding the operator's reply —
+// an old "yes" from three messages ago can never retroactively approve
+// something new. Destructive-risk actions are excluded: they always need the
+// explicit typed-confirmation flow, never loose assent.
+
+// pendingApproval is one gated action proposed in the immediately-preceding
+// assistant turn, extracted from its tool_result text.
+type pendingApproval struct {
+	execID      string
+	destructive bool
+}
+
+// executionQueuedRE matches the "execution <uuid> queued" phrasing shared by
+// the run and request_execution/pct_create tool result messages.
+var executionQueuedRE = regexp.MustCompile(`(?i)execution\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\s+queued`)
+
+// extractPendingApprovals scans the tool results of one assistant turn for
+// gated actions that are still awaiting a decision.
+func extractPendingApprovals(calls []persistedCall) []pendingApproval {
+	var out []pendingApproval
+	for _, c := range calls {
+		text := c.resultText()
+		m := executionQueuedRE.FindStringSubmatch(text)
+		if m == nil {
+			continue
+		}
+		out = append(out, pendingApproval{
+			execID:      m[1],
+			destructive: strings.Contains(strings.ToUpper(text), "DESTRUCTIVE"),
+		})
+	}
+	return out
+}
+
+// negationWords, checked first: any of these anywhere in the message means
+// the reply is NOT assent, even if a positive word also appears (e.g. "no,
+// don't restart it yet" contains neither "yes" nor "go ahead", but "wait"
+// alone should also block a stray "yes" a sentence later — checking negation
+// first and returning false errs toward re-confirming rather than assuming
+// consent, per "when in doubt, escalate"). Includes contracted negatives
+// ("haven't", "isn't", ...) alongside "don't"/"do not" — found live: "I
+// haven't confirmed anything yet" was reading as an explicit confirmation
+// because none of the contracted forms were covered, only "don't"/"do not".
+// Deliberately does NOT include a bare "not": that's broad enough to false-
+// negative ordinary assent ("go ahead, this is not risky") — the specific
+// contracted-verb forms below are unambiguous negation on their own.
+var negationWords = []string{
+	"no", "nope", "don't", "do not", "stop", "wait", "hold on", "hold off",
+	"not yet", "cancel", "nevermind", "never mind", "actually don't", "skip that",
+	"haven't", "hasn't", "isn't", "wasn't", "aren't", "can't", "cannot",
+	"won't", "wouldn't", "shouldn't", "didn't", "doesn't",
+}
+
+// assentWords, checked only if no negation matched.
+var assentWords = []string{
+	"go ahead", "goahead", "yes", "yep", "yeah", "yup", "do it", "proceed",
+	"approve", "approved", "confirm", "confirmed", "ship it", "sounds good",
+	"lgtm", "run it", "execute", "ok go", "okay go", "please do",
+}
+
+// wordTokenRe splits a message into lowercase word tokens. Apostrophes
+// (straight ' and curly ’) stay attached to their word so "don't"/"haven't"
+// tokenize as one token, not two.
+var wordTokenRe = regexp.MustCompile(`[a-z0-9'’]+`)
+
+func tokenize(msg string) []string {
+	return wordTokenRe.FindAllString(strings.ToLower(strings.ReplaceAll(msg, "’", "'")), -1)
+}
+
+// containsPhrase reports whether phrase (one or more words) appears as a
+// consecutive run of WHOLE tokens in tokens — never a mid-word substring
+// match. This is the fix for a real false positive found live: the old
+// substring check (`strings.Contains(m, "yes")`) matched "yes" inside
+// "yesterday", and "confirm" inside "confirmed"/"unconfirmed" without regard
+// for word boundaries. Negation already used a word-boundary check
+// (space-padded); assent/confirm words didn't — this brings both onto the
+// same, more robust tokenized comparison instead of ad-hoc string padding.
+func containsPhrase(tokens []string, phrase string) bool {
+	words := strings.Fields(phrase)
+	if len(words) == 0 || len(words) > len(tokens) {
+		return false
+	}
+	for i := 0; i+len(words) <= len(tokens); i++ {
+		match := true
+		for j, w := range words {
+			if tokens[i+j] != w {
+				match = false
+				break
+			}
+		}
+		if match {
+			return true
+		}
+	}
+	return false
+}
+
+// isAssent reports whether msg is a plain-language authorization of a
+// pending proposal. Deliberately simple and auditable: a fixed word list,
+// not a model judgment call, so behavior is predictable and can't be
+// prompt-injected via the pending action's own content.
+func isAssent(msg string) bool {
+	tokens := tokenize(msg)
+	for _, w := range negationWords {
+		if containsPhrase(tokens, w) {
+			return false
+		}
+	}
+	for _, w := range assentWords {
+		if containsPhrase(tokens, w) {
+			return true
+		}
+	}
+	return false
+}
+
+// isTypedConfirmation reports whether msg is an explicit confirmation strong
+// enough to grant a DESTRUCTIVE pending action. Deliberately a separate,
+// stricter check from isAssent: a bare "yes"/"go ahead"/"proceed" must never
+// grant something destructive, only an explicit "confirm" statement does —
+// this is the typed-confirmation phrase SOUL.md tells the operator to use
+// ("I confirm destroy 135"). Still negation-aware for the same reason as
+// isAssent: "don't confirm yet" must not accidentally match.
+func isTypedConfirmation(msg string) bool {
+	tokens := tokenize(msg)
+	for _, w := range negationWords {
+		if containsPhrase(tokens, w) {
+			return false
+		}
+	}
+	return containsPhrase(tokens, "confirm") || containsPhrase(tokens, "confirmed")
+}
+
+// approveExecution grants (or denies) a pending execution via the same HTTP
+// endpoint the chat UI's Approve button calls, so both paths share one code
+// path server-side (executeApprovedAction) and one audit trail. Returns the
+// decided status, or an error if the request failed outright (a 4xx for an
+// already-decided/expired approval is reported via ok=false, not a hard err,
+// since that's an expected race, not a bug).
+func (a *agent) approveExecution(ctx context.Context, execID string) (ok bool, status string, err error) {
+	if a.apiBase == "" {
+		return false, "", fmt.Errorf("no API base configured")
+	}
+	body, _ := json.Marshal(map[string]string{"decision": "approve"})
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
+		a.apiBase+"/api/v1/approvals/"+execID+"/decision", bytes.NewReader(body))
+	if err != nil {
+		return false, "", err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if a.apiToken != "" {
+		req.Header.Set("Authorization", "Bearer "+a.apiToken)
+	}
+	resp, err := a.httpClient.Do(req)
+	if err != nil {
+		return false, "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return false, "", nil // already decided / expired / not found — not a hard failure
+	}
+	var out struct {
+		Status string `json:"status"`
+	}
+	json.NewDecoder(resp.Body).Decode(&out)
+	return true, out.Status, nil
+}

cmd/nomos/assent_test.go

@@ -0,0 +1,136 @@
+package main
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestIsAssent_Positive(t *testing.T) {
+	cases := []string{
+		"go ahead", "Go ahead.", "yes", "Yes!", "yeah", "yep", "do it",
+		"proceed", "approve", "ship it", "sounds good", "lgtm", "please do",
+		"ok go ahead and run it",
+	}
+	for _, c := range cases {
+		if !isAssent(c) {
+			t.Errorf("isAssent(%q) = false, want true", c)
+		}
+	}
+}
+
+func TestIsAssent_Negative(t *testing.T) {
+	cases := []string{
+		"no", "no, don't", "wait", "hold on", "not yet", "cancel that",
+		"nevermind", "what's the plan for tomorrow?", "how many CPUs does strong have?",
+		"maybe later", "",
+	}
+	for _, c := range cases {
+		if isAssent(c) {
+			t.Errorf("isAssent(%q) = true, want false", c)
+		}
+	}
+}
+
+func TestIsAssent_NegationBeatsAssentWord(t *testing.T) {
+	// Contains "yes" as a substring pattern risk word but is clearly not
+	// assent — negation must win.
+	cases := []string{
+		"no, don't do it yet",
+		"wait, not yet please",
+	}
+	for _, c := range cases {
+		if isAssent(c) {
+			t.Errorf("isAssent(%q) = true, want false (negation should block)", c)
+		}
+	}
+}
+
+// TestIsAssent_WholeWordBoundary regression-tests a real false positive found
+// live: the old substring check matched "yes" inside "yesterday" (and would
+// equally match "confirm" inside "confirmed"/"unconfirmed" for
+// isTypedConfirmation below) because only negation used a word-boundary
+// check — assent/confirm words used a bare strings.Contains. Confirmed via a
+// throwaway probe before being fixed; kept here permanently so a future
+// change can't silently reintroduce it.
+func TestIsAssent_WholeWordBoundary(t *testing.T) {
+	cases := []string{
+		"not sure, maybe yesterday's logs show something useful",
+		"my eyesight isn't great, what does that say",
+	}
+	for _, c := range cases {
+		if isAssent(c) {
+			t.Errorf("isAssent(%q) = true, want false (word-boundary: 'yes' must not match inside 'yesterday'/'eyesight')", c)
+		}
+	}
+}
+
+// TestIsTypedConfirmation_ContractedNegation regression-tests the other real
+// false positive: isTypedConfirmation gates DESTRUCTIVE actions, and
+// "confirm" matching inside "confirmed" combined with contracted negatives
+// ("haven't") not being in negationWords meant a message that explicitly
+// says the operator has NOT confirmed something could read as confirming it.
+func TestIsTypedConfirmation_ContractedNegation(t *testing.T) {
+	cases := []string{
+		"I haven't confirmed anything yet, let me think",
+		"that isn't confirmed on my end",
+		"we can't confirm that until tomorrow",
+	}
+	for _, c := range cases {
+		if isTypedConfirmation(c) {
+			t.Errorf("isTypedConfirmation(%q) = true, want false (contracted negation should block)", c)
+		}
+	}
+}
+
+func TestIsTypedConfirmation(t *testing.T) {
+	positive := []string{
+		"I confirm destroy 135 in strong",
+		"confirm",
+		"Confirmed.",
+		"yes I confirm",
+	}
+	for _, c := range positive {
+		if !isTypedConfirmation(c) {
+			t.Errorf("isTypedConfirmation(%q) = false, want true", c)
+		}
+	}
+	negative := []string{
+		"yes", "go ahead", "do it", "proceed", "lgtm", // loose assent must NOT satisfy this
+		"no, don't confirm yet", "wait", "",
+	}
+	for _, c := range negative {
+		if isTypedConfirmation(c) {
+			t.Errorf("isTypedConfirmation(%q) = true, want false (only explicit confirm should pass)", c)
+		}
+	}
+}
+
+func TestExtractPendingApprovals(t *testing.T) {
+	mkCall := func(text string) persistedCall {
+		b, _ := json.Marshal(text)
+		return persistedCall{id: "x", name: "run", result: json.RawMessage(b)}
+	}
+	calls := []persistedCall{
+		mkCall("run on host:strong requires approval (risk: config_mutation) — execution 019f4930-e22b-7c47-8c6e-715dcd59df19 queued. Present the command..."),
+		mkCall("some unrelated read-only result, no approval here"),
+		mkCall("run on lxc:caddy requires approval (risk: destructive) — execution 019f4931-aaaa-7c47-8c6e-715dcd59df20 queued. This is classified DESTRUCTIVE — flag that clearly."),
+	}
+	got := extractPendingApprovals(calls)
+	if len(got) != 2 {
+		t.Fatalf("expected 2 pending approvals, got %d: %+v", len(got), got)
+	}
+	if got[0].execID != "019f4930-e22b-7c47-8c6e-715dcd59df19" || got[0].destructive {
+		t.Errorf("first approval wrong: %+v", got[0])
+	}
+	if got[1].execID != "019f4931-aaaa-7c47-8c6e-715dcd59df20" || !got[1].destructive {
+		t.Errorf("second approval should be flagged destructive: %+v", got[1])
+	}
+}
+
+func TestExtractPendingApprovals_NoneWhenNoneQueued(t *testing.T) {
+	b, _ := json.Marshal("fleet is healthy, nothing to report")
+	calls := []persistedCall{{id: "x", result: json.RawMessage(b)}}
+	if got := extractPendingApprovals(calls); len(got) != 0 {
+		t.Errorf("expected no pending approvals, got %+v", got)
+	}
+}

cmd/nomos/continue.go

@@ -0,0 +1,401 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"regexp"
+	"strings"
+	"time"
+
+	"github.com/dtoro/oikos/internal/safego"
+	"github.com/google/uuid"
+)
+
+// execIDRe matches "execution <uuid>" in a tool result — the phrasing shared
+// by request_execution / run when they queue or start a gated execution.
+// Only these async executions need continuation; the synchronous auto-run
+// path returns its output inline and is already observed in-turn.
+var execIDRe = regexp.MustCompile(`(?i)execution\s+([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})`)
+
+func extractExecutionIDs(toolResult string) []uuid.UUID {
+	matches := execIDRe.FindAllStringSubmatch(toolResult, -1)
+	seen := map[uuid.UUID]bool{}
+	var out []uuid.UUID
+	for _, m := range matches {
+		if id, err := uuid.Parse(m[1]); err == nil && !seen[id] {
+			seen[id] = true
+			out = append(out, id)
+		}
+	}
+	return out
+}
+
+// idleTaskThreshold is how long a goal-bearing session can sit non-terminal
+// with no activity before the idle sweep nudges it, per
+// plans/2026-07-11-task-completion-safety-net.md. Arbitrary starting point,
+// not measured against real task durations — long enough that it won't fire
+// mid-turn, short enough the board doesn't lie for hours.
+const idleTaskThreshold = 15 * time.Minute
+
+// runIdleSweepWorker is the safety net for case 2 of
+// plans/2026-07-11-task-completion-safety-net.md: sessions that called
+// set_goal (so the inline safety net in agent.go correctly left them alone,
+// since they framed themselves as a real task) but then stalled without
+// ever calling complete_task. Coarser than runContinuationWorker's 4s tick
+// since "gone idle" is a much slower signal than "an execution just
+// finished." Blocks until ctx is cancelled.
+func (a *agent) runIdleSweepWorker(ctx context.Context) {
+	if a.store == nil {
+		slog.Warn("nomos: idle sweep worker disabled (no store)")
+		return
+	}
+	slog.Info("nomos: idle sweep worker started")
+	ticker := time.NewTicker(2 * time.Minute)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			a.processIdleSweep(ctx)
+		}
+	}
+}
+
+// processIdleSweep nudges a stalled goal-bearing session once; if it's still
+// non-terminal on the NEXT sweep (meaning the nudge itself went unanswered,
+// not just that the model is still working), auto-closes it with a
+// visible "auto-closed" outcome instead of leaving it stuck forever — same
+// reasoning resumeSession already applies below for a different failure
+// mode (a resume that produces no response at all).
+func (a *agent) processIdleSweep(ctx context.Context) {
+	stale := a.store.staleGoalSessions(ctx, idleTaskThreshold, 5)
+	for _, s := range stale {
+		s := s
+		if s.CompletionNudges == 0 {
+			safego.Go("nomos:idle-nudge:"+s.ID, func() {
+				note := fmt.Sprintf("[System: this task ('%s') has been idle for %s with no complete_task call. "+
+					"If the goal is done (or can't be completed), call complete_task now with the outcome and a "+
+					"one-line summary. If you're still genuinely working through the plan, ignore this and continue.]",
+					s.Goal, idleTaskThreshold)
+				note = a.store.enrichResumeNote(ctx, s.ID, note)
+				// P1: only count the nudge if it actually delivered. resumeSession
+				// skips (returns false) when a turn is already active; bumping the
+				// counter anyway would make the next sweep auto-close a merely-busy
+				// session as "unanswered."
+				if a.resumeSession(ctx, s.ID, note) {
+					if err := a.store.bumpCompletionNudge(ctx, s.ID); err != nil {
+						slog.Error("nomos: idle nudge bump failed", "session", s.ID, "error", err)
+					}
+				}
+			})
+			continue
+		}
+		safego.Go("nomos:idle-autoclose:"+s.ID, func() {
+			summary := fmt.Sprintf("Auto-closed after %s idle with no response to a completion nudge.", idleTaskThreshold)
+			if err := a.store.completeTask(ctx, s.ID, "partial", summary); err != nil {
+				slog.Error("nomos: idle auto-close failed", "session", s.ID, "error", err)
+			}
+		})
+	}
+}
+
+// runContinuationWorker is the event loop that replaces the human typing
+// "continue". It polls for gated executions that (a) were initiated by a chat
+// session and (b) have just finished, and — while that agent has an open assent
+// window (an approved plan is in flight) — feeds each result back into the
+// agent so it proceeds to the next step or recovers from the failure, all
+// without an operator tick. Blocks until ctx is cancelled.
+func (a *agent) runContinuationWorker(ctx context.Context) {
+	if a.store == nil {
+		slog.Warn("nomos: continuation worker disabled (no store)")
+		return
+	}
+	slog.Info("nomos: continuation worker started")
+	ticker := time.NewTicker(4 * time.Second)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			a.processContinuations(ctx)
+		}
+	}
+}
+
+// processContinuations dispatches each pending item as its OWN goroutine
+// (safego.Go, so a panic deep in one task's resumed turn — JSON parsing of
+// model output, an unexpected nil in a tool result — is recovered and logged
+// instead of taking down this whole function, which used to run every
+// item sequentially in the SAME goroutine as the ticker loop. Two problems
+// that fixed: (1) throughput — task B's continuation no longer waits for
+// task A's full (up to 10-minute) resumed turn to finish first, the exact
+// per-task blocking this session's earlier concurrency work removed from the
+// live-chat path but had left in place here; (2) survivability — since Go
+// panics unwind the goroutine they occur in, an unrecovered one here used to
+// mean this call (and every future tick, since the whole ticker loop runs in
+// one goroutine) would simply stop — auto-continuation for every task would
+// silently die until nomos restarted. Now a single bad item can only ever
+// take down its own goroutine.
+func (a *agent) processContinuations(ctx context.Context) {
+	pending := a.store.pendingContinuations(ctx, 5)
+	for _, p := range pending {
+		// Scope gate: only auto-continue while an approved plan is active FOR
+		// THIS SESSION. Checked per-item, not once for the whole batch — with
+		// multiple tasks in flight, one task's open window must never cover a
+		// pending continuation belonging to a different task.
+		if !a.store.assentWindowActive(ctx, a.agentID, p.SessionID) {
+			// Re-open the assent window if this session is genuinely
+			// executing (plan was approved, work is in progress) — the
+			// window may have expired while the execution ran. Don't
+			// penalize timing: the plan was approved, the work happened,
+			// the result should flow back.
+			sesh, seshErr := a.store.getSession(ctx, p.SessionID)
+			if seshErr == nil && sesh.Goal != "" && (sesh.Status == "executing" || sesh.Status == "planning") {
+				a.openAssentWindow(ctx, p.SessionID)
+				slog.Info("nomos: re-opened assent window for continuing session", "session", p.SessionID, "execution", p.ExecID)
+			} else {
+				// Genuinely no plan — inject a visible note so the
+				// operator knows WHY the agent didn't auto-continue.
+				note := fmt.Sprintf("[System: execution %s finished with status=%s, but the assent window for this session is not active. The agent will not auto-continue. Reply 'continue' or re-approve the plan to resume.]", p.ExecID, p.Status)
+				body, _ := json.Marshal(map[string]any{"role": "assistant", "text": note, "auto": true})
+				a.store.saveMessage(context.Background(), p.SessionID, "assistant", body)
+				a.store.markContinued(ctx, p.ExecID)
+				continue
+			}
+		}
+		// markContinued now happens inside continueSession, AFTER resumeSession
+		// actually runs (P0). Pre-marking here consumed the item even when
+		// resumeSession skipped on a busy session, losing the result.
+		safego.Go("nomos:continue-session:"+p.SessionID, func() { a.continueSession(ctx, p) })
+	}
+}
+
+// continueSession re-invokes the agent for one finished execution. Persists
+// progress LIVE — a placeholder row immediately, updated in place as each
+// tool call completes — instead of only saving once the whole continuation
+// finishes. The frontend polls (see chat.ts startPolling); without
+// incremental persistence here, a continuation that runs several tool calls
+// before concluding would look like total silence in the UI for however long
+// that takes, which is exactly the "I just wait while nothing happens"
+// complaint this exists to fix — polling alone only helps if there's
+// something new to poll for.
+func (a *agent) continueSession(ctx context.Context, p pendingContinuation) {
+	slog.Info("nomos: auto-continuing session", "session", p.SessionID, "execution", p.ExecID, "status", p.Status)
+	// P0 (plans/2026-08-03-nomos-chat-changes-review.md): mark the execution
+	// continued ONLY after the turn actually ran. resumeSession skips (returns
+	// false) when another turn is already active for this session; marking
+	// before that — as the old code did — consumed the item (continued_at set,
+	// never re-queued by pendingContinuations) and silently lost the result.
+	// On a skip, leave it pending so the next worker tick retries once the
+	// active turn frees the permit.
+	if !a.resumeSession(ctx, p.SessionID, buildContinuationNote(p)) {
+		slog.Info("nomos: continuation deferred — a turn is active; will retry next tick", "session", p.SessionID, "execution", p.ExecID)
+		return
+	}
+	a.store.markContinued(ctx, p.ExecID)
+}
+
+// resumeSession re-invokes the agent for a session with a system-injected note —
+// a finished execution (continueSession) or an operator's answer to a question
+// (handleAnswerQuestion) — persisting progress LIVE (a placeholder row updated
+// in place as each tool call lands) so the frontend poller sees each step,
+// instead of total silence until the whole resume concludes.
+//
+// F1 (plan 2026-08-03): this is the single entry point for EVERY background
+// turn — the continuation worker, idle sweep, answer-question, /resume, and the
+// empty-message reconnect all funnel through here. It acquires the session's
+// turn permit non-blocking and SKIPS if a turn is already running. A duplicate
+// resume while a turn (live or background) is active is exactly the
+// interleaving that corrupted the activity panel and made tasks feel stuck.
+//
+// Returns whether the turn actually ran. Callers that mutate state before
+// resuming (the continuation worker's markContinued, the idle sweep's nudge
+// bump) MUST gate that mutation on a true return — otherwise a busy-skip leaves
+// the state changed but the work undone (lost continuation / false auto-close).
+// See plans/2026-08-03-nomos-chat-changes-review.md P0/P1.
+func (a *agent) resumeSession(ctx context.Context, sessionID, note string) bool {
+	if !a.gate.acquire(sessionID, 0) {
+		slog.Info("nomos: turn already active, skipping background resume", "session", sessionID)
+		return false
+	}
+	// Release the gate, then drain any operator message that was queued while
+	// this background turn ran (plan 2026-08-03 F2). Queued messages are run as
+	// real user turns server-side; resumeSession itself never enqueues.
+	defer func() {
+		a.gate.release(sessionID)
+		safego.Go("nomos:drain:"+sessionID, func() { a.drainQueued(context.Background(), sessionID) })
+	}()
+
+	placeholder, _ := json.Marshal(map[string]any{
+		"role": "assistant",
+		"text": "",
+		"auto": true,
+	})
+	msgID, err := a.store.insertMessageReturningID(ctx, sessionID, "assistant", placeholder)
+	if err != nil {
+		slog.Error("nomos: resume placeholder insert failed", "session", sessionID, "error", err)
+	}
+
+	var toolCalls []map[string]any
+	var finalText, errText string
+	var finalThinking string
+
+	persist := func() {
+		if msgID == uuid.Nil {
+			return
+		}
+		text := finalText
+		if text == "" && errText != "" {
+			text = fmt.Sprintf("(auto-continuation hit an internal error and did not respond: %s — the execution's own result is above; you may need to prompt the agent again)", errText)
+		}
+		body, _ := json.Marshal(map[string]any{
+			"role":       "assistant",
+			"text":       text,
+			"thinking":   finalThinking,
+			"tool_calls": toolCalls,
+			"auto":       true, // marks this as an autonomous continuation, not an operator turn
+		})
+		a.store.updateMessage(ctx, msgID, body)
+	}
+
+	// One retry if the LLM call itself produced nothing (transient flake /
+	// empty-response) — the whole point of this mechanism is "don't give up
+	// on the first error," which should apply to the continuation call
+	// itself, not just the homelab commands it's continuing. Found live: a
+	// destructive-recovery continuation hit an empty LLM response, its
+	// internal retry (chatWith's own maxLLMRetries=1) also came up empty, and
+	// without this outer retry the operator would see nothing at all.
+	cctx, cancel := context.WithTimeout(ctx, 10*time.Minute)
+	defer cancel()
+	// B.3: escalate the recovery note across attempts — a transient flake
+	// needs a different prompt than a model that's stuck no-op'ing. The
+	// final attempt is maximally directive ("do this specific thing now").
+	// B.5: back off between retries (4s, 8s) so a transient provider issue
+	// has time to clear — 3 identical calls in 3 seconds just get 3
+	// identical empties.
+	notes := []string{
+		note, // attempt 0: the original (already enriched per B.2) note
+		fmt.Sprintf("[System: your previous turn produced no response. %s. Produce a response now — call the next tool or report progress in one sentence.]", note),
+		fmt.Sprintf("[System: two consecutive empty responses. Stop trying to be clever. The next action is: pick the lowest-pending plan step, mark it running with update_plan_step, and call run for its target. Do that now.]"),
+	}
+	for attempt := 0; attempt < 3; attempt++ {
+		if attempt > 0 {
+			select {
+			case <-cctx.Done():
+				return true // a turn ran on an earlier attempt; consume, don't re-loop
+			case <-time.After(time.Duration(2<<attempt) * time.Second): // 4s, 8s
+			}
+		}
+		toolCalls, finalText, errText = nil, "", ""
+		finalThinking = ""
+		// P3: accumulate per-iteration reasoning instead of overwriting
+		// (same fix as main.go's chat handler). Without this, a resumed
+		// turn's intermediate thinking is lost on reload.
+		// (same fix as main.go's chat handler). Without this, a resumed
+		// turn's intermediate thinking is lost on reload.
+		var textParts []string
+		var thinkingParts []string
+		emit := func(ev agentEvent) {
+			if ev.Type == "tool_use" || ev.Type == "tool_result" {
+				if m, ok := ev.Data.(map[string]any); ok {
+					m["type"] = ev.Type
+					// One entry per tool call: tool_use creates it,
+					// tool_result merges the result into the same entry
+					// (matched by id). Before this fix, both events
+					// appended separate entries, doubling every tool call.
+					id, _ := m["id"].(string)
+					if id != "" && ev.Type == "tool_result" {
+						for _, existing := range toolCalls {
+							if eID, _ := existing["id"].(string); eID == id {
+								for k, v := range m {
+									existing[k] = v
+								}
+								break
+							}
+						}
+					} else {
+						toolCalls = append(toolCalls, m)
+					}
+				}
+				persist() // live: a poller sees this step land within seconds
+			}
+			if ev.Type == "text" {
+				if t, ok := ev.Data.(string); ok && t != "" {
+					if ev.IsThinking {
+						thinkingParts = append(thinkingParts, t)
+						finalThinking = strings.Join(thinkingParts, "\n\n")
+					} else {
+						textParts = append(textParts, t)
+						finalText = strings.Join(textParts, "\n\n")
+					}
+					persist()
+				}
+			}
+			if ev.Type == "error" {
+				errText, _ = ev.Data.(string)
+			}
+		}
+		a.chatWith(cctx, sessionID, "", notes[attempt], emit)
+		if finalText != "" || len(toolCalls) > 0 {
+			break
+		}
+		if attempt < 2 {
+			slog.Warn("nomos: resume produced nothing, retrying", "session", sessionID, "error", errText, "attempt", attempt+1)
+		}
+	}
+
+	if errText != "" && finalText == "" {
+		slog.Error("nomos: resume produced no response after retry", "session", sessionID, "error", errText)
+		// Persist a visible system note in the transcript so the
+		// operator sees what happened, but do NOT auto-complete the
+		// task — leave it in 'executing' so a follow-up chat message
+		// can resume it. Before this fix, the task was marked 'failed'
+		// here, which ended it permanently and required starting over.
+		resumeFailedNote := fmt.Sprintf("[System: auto-resume failed after retrying: %s. The task is paused — send another message to continue.]", errText)
+		body, _ := json.Marshal(map[string]any{
+			"role": "assistant",
+			"text": resumeFailedNote,
+			"auto": true,
+		})
+		if msgID != uuid.Nil {
+			a.store.updateMessage(context.Background(), msgID, body)
+		} else {
+			// No placeholder was inserted (rare), save directly.
+			a.store.saveMessage(context.Background(), sessionID, "assistant", body)
+		}
+		return true // do not call persist() again — already persisted above
+	}
+	persist() // final state — same row, updated one last time with the concluding text
+	return true
+}
+
+// buildContinuationNote frames the finished execution for the model: what
+// happened, and what to do about it. The persist-through-errors instruction
+// lives here (and in SOUL) so the agent recovers instead of stopping.
+func buildContinuationNote(p pendingContinuation) string {
+	action := p.Action
+	if i := strings.IndexByte(action, ':'); i > 0 && len(action) > 40 {
+		action = action[:i] // keep just the action verb for brevity; params are in the DB
+	}
+	result := p.Result
+	if len(result) > 3000 {
+		result = result[:3000] + "…[truncated]"
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "[System: execution %s (%s) finished with status=%s.\nResult: %s\n\n",
+		p.ExecID, action, p.Status, result)
+	switch p.Status {
+	case "completed":
+		b.WriteString("It SUCCEEDED. Continue the approved plan: run the next step. If this was the final step, verify the end goal actually works (e.g. curl the service) and then report success to the operator. Do NOT stop and wait for the operator to say 'continue'.")
+	case "failed", "cancelled":
+		b.WriteString("It FAILED. Do NOT give up or hand back to the operator. Diagnose the cause from the result above (and by running read-only inspection commands if needed), form a hypothesis, fix it, and retry or take an alternative approach. You have an active assent window, so config_mutation steps run without re-approval. Only stop and ask the operator if you are genuinely blocked (need information only they have) or the fix would require a destructive action they haven't approved.")
+	default: // denied / revoked
+		b.WriteString("The operator denied or revoked this step. Stop executing this plan and briefly acknowledge.")
+	}
+	b.WriteString("]")
+	return b.String()
+}

cmd/nomos/continue_test.go

@@ -0,0 +1,78 @@
+package main
+
+import (
+	"context"
+	"testing"
+
+	"github.com/google/uuid"
+)
+
+func TestExtractExecutionIDs(t *testing.T) {
+	// Real tool-result phrasings that should yield an execution id.
+	pos := map[string]string{
+		`"pct_create on host:strong auto-approved via assent window — execution 019f4b19-eafd-74ed-baa6-d24a27b3f52c running."`: "019f4b19-eafd-74ed-baa6-d24a27b3f52c",
+		`"run on lxc:caddy requires approval (risk: config_mutation) — execution 019f4af7-7eff-7723-b38c-b540b267f407 queued."`:   "019f4af7-7eff-7723-b38c-b540b267f407",
+		`"apt_upgrade on host:hubris auto-approved via assent window — execution 019f4b58-c88c-7767-87dd-044608ced913 running."`:  "019f4b58-c88c-7767-87dd-044608ced913",
+	}
+	for in, want := range pos {
+		ids := extractExecutionIDs(in)
+		if len(ids) != 1 || ids[0].String() != want {
+			t.Errorf("extractExecutionIDs(%q) = %v, want [%s]", in, ids, want)
+		}
+	}
+
+	// Synchronous auto-run and read-only results carry no "execution <uuid>"
+	// phrasing — they've already completed inline and must NOT be linked for
+	// continuation.
+	neg := []string{
+		`"run on host:strong (read_only, auto): 09:30 up 8 days"`,
+		`"run on lxc:caddy (config_mutation, auto via assent window): done"`,
+		`[{"slug":"lxc:caddy","health":"healthy"}]`,
+		`"target not found: lxc:nope"`,
+	}
+	for _, in := range neg {
+		if ids := extractExecutionIDs(in); len(ids) != 0 {
+			t.Errorf("extractExecutionIDs(%q) = %v, want none", in, ids)
+		}
+	}
+
+	// De-dupes repeated ids in one result.
+	dup := `execution 019f4b19-eafd-74ed-baa6-d24a27b3f52c queued ... execution 019f4b19-eafd-74ed-baa6-d24a27b3f52c running`
+	if ids := extractExecutionIDs(dup); len(ids) != 1 {
+		t.Errorf("expected de-dup to 1 id, got %v", ids)
+	}
+}
+
+// TestResumeSession_SkipsWhenBusy guards the P0 fix
+// (plans/2026-08-03-nomos-chat-changes-review.md): resumeSession must skip —
+// return false, body never executed — when a turn is already active for the
+// session. continueSession relies on this so it only marks a continuation
+// "continued" after a turn really ran (otherwise the result is lost: marked
+// continued, never re-queued by pendingContinuations).
+//
+// A minimal agent with only a gate is enough: if the body ever ran, chatWith
+// would dereference the nil provider and panic. Returning false cleanly proves
+// the body was skipped.
+func TestResumeSession_SkipsWhenBusy(t *testing.T) {
+	a := &agent{gate: newTurnGate()}
+	if !a.gate.acquire("sess", 0) {
+		t.Fatal("precondition: initial acquire should succeed on a free session")
+	}
+	ran := a.resumeSession(context.Background(), "sess", "note")
+	if ran {
+		t.Fatal("resumeSession must return false (skip) while a turn is active for the session")
+	}
+}
+
+// TestContinueSession_DefersWhenBusy guards the other half of P0: when the
+// session is busy, continueSession defers (leaves the execution pending for the
+// next worker tick) instead of running or marking it. It must return cleanly
+// without reaching resumeSession's body (nil provider → panic) or markContinued.
+func TestContinueSession_DefersWhenBusy(t *testing.T) {
+	a := &agent{gate: newTurnGate()}
+	if !a.gate.acquire("sess", 0) {
+		t.Fatal("precondition: initial acquire should succeed on a free session")
+	}
+	p := pendingContinuation{ExecID: uuid.New(), SessionID: "sess", Status: "completed"}
+	a.continueSession(context.Background(), p) // must not panic; must not run/mark
+}

cmd/nomos/eval/main.go

@@ -0,0 +1,372 @@
+// Command nomos-eval runs golden conversation evals against a live nomos
+// gateway. It loads a YAML manifest of conversations + assertions, sends
+// each prompt to the chat endpoint, waits for the turn(s) to finish, and
+// scores assertions against the persisted transcript.
+//
+// Usage:
+//
+//	go run ./cmd/nomos/eval -gateway http://localhost:8092 -manifest evals/*.yaml
+//
+// The gateway must already be running (nomos serve, or the docker container).
+// Each conversation costs real OpenRouter credits (~$0.01–0.05 each).
+//
+// Manifest format — see evals/example.yaml. Assertions are scored against the
+// final transcript: tool calls made, plan steps, final session status, and
+// whether the turn completed. The runner does NOT judge text quality — only
+// structural properties that can be checked deterministically from the
+// persisted state. This is deliberate: text quality is model-dependent and
+// noisy; structure is what the Go gates + SOUL.md should enforce.
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+func main() {
+	gateway := flag.String("gateway", "http://localhost:8092", "nomos gateway URL")
+	manifestGlob := flag.String("manifest", "evals/*.yaml", "glob of manifest files to run")
+	timeout := flag.Duration("timeout", 2*time.Minute, "per-conversation timeout")
+	flag.Parse()
+
+	if err := health(*gateway); err != nil {
+		fmt.Fprintf(os.Stderr, "gateway not reachable at %s: %v\n", *gateway, err)
+		os.Exit(1)
+	}
+
+	files, err := filepath.Glob(*manifestGlob)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "glob %s: %v\n", *manifestGlob, err)
+		os.Exit(1)
+	}
+	if len(files) == 0 {
+		fmt.Fprintf(os.Stderr, "no manifests matched %s\n", *manifestGlob)
+		os.Exit(1)
+	}
+
+	total, passed, failed := 0, 0, 0
+	for _, f := range files {
+		convs, err := loadManifest(f)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "load %s: %v\n", f, err)
+			os.Exit(1)
+		}
+		for _, c := range convs {
+			total++
+			name := c.Name
+			if name == "" {
+				name = fmt.Sprintf("conversation-%d", total)
+			}
+			fmt.Printf("=== %s (from %s) ===\n", name, filepath.Base(f))
+			res := runConversation(context.Background(), *gateway, c, *timeout)
+			if res.Passed {
+				passed++
+				fmt.Printf("  ✅ PASS (%.1fs, %d tool calls)\n", res.Duration.Seconds(), res.ToolCallCount)
+			} else {
+				failed++
+				fmt.Printf("  ❌ FAIL (%.1fs, %d tool calls)\n", res.Duration.Seconds(), res.ToolCallCount)
+			}
+			for _, a := range res.Assertions {
+				mark := "✅"
+				if !a.Passed {
+					mark = "❌"
+				}
+				fmt.Printf("    %s %s: %s\n", mark, a.Name, a.Detail)
+			}
+		}
+	}
+	fmt.Printf("\n=== Summary: %d/%d passed, %d failed ===\n", passed, total, failed)
+	if failed > 0 {
+		os.Exit(1)
+	}
+}
+
+func health(gateway string) error {
+	resp, err := http.Get(gateway + "/healthz")
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != 200 {
+		return fmt.Errorf("healthz status %d", resp.StatusCode)
+	}
+	return nil
+}
+
+// runConversation sends the prompt (and any followup), waits for each turn to
+// finish, then scores assertions against the final transcript.
+func runConversation(ctx context.Context, gateway string, c conversation, timeout time.Duration) convResult {
+	start := time.Now()
+	deadline := time.Now().Add(timeout)
+	res := convResult{}
+
+	// Send the initial prompt (no session_id → creates a new session).
+	sid, err := sendChat(ctx, gateway, "", c.Prompt)
+	if err != nil {
+		res.Assertions = []assertionResult{{Name: "send_prompt", Passed: false, Detail: err.Error()}}
+		res.Duration = time.Since(start)
+		return res
+	}
+	res.SessionID = sid
+
+	// Wait for the first turn to finish.
+	if err := waitForTurn(ctx, gateway, sid, deadline); err != nil {
+		res.Assertions = []assertionResult{{Name: "turn_complete", Passed: false, Detail: err.Error()}}
+		res.Duration = time.Since(start)
+		return res
+	}
+
+	// Send followup if any.
+	for _, fu := range c.followups() {
+		if _, err := sendChat(ctx, gateway, sid, fu); err != nil {
+			res.Assertions = []assertionResult{{Name: "send_followup", Passed: false, Detail: err.Error()}}
+			res.Duration = time.Since(start)
+			return res
+		}
+		if err := waitForTurn(ctx, gateway, sid, deadline); err != nil {
+			res.Assertions = []assertionResult{{Name: "followup_turn_complete", Passed: false, Detail: err.Error()}}
+			res.Duration = time.Since(start)
+			return res
+		}
+	}
+
+	// Fetch the final transcript + session state.
+	transcript, session, err := fetchTranscript(ctx, gateway, sid)
+	if err != nil {
+		res.Assertions = []assertionResult{{Name: "fetch_transcript", Passed: false, Detail: err.Error()}}
+		res.Duration = time.Since(start)
+		return res
+	}
+	res.ToolCallCount = transcript.toolCallCount()
+	res.Duration = time.Since(start)
+
+	// Score assertions.
+	res.Assertions = scoreAssertions(c.Assertions, transcript, session)
+
+	res.Passed = true
+	for _, a := range res.Assertions {
+		if !a.Passed {
+			res.Passed = false
+			break
+		}
+	}
+	return res
+}
+
+// sendChat POSTs to /chat and extracts the session_id from the first SSE
+// event, then KEEPS READING the stream until it ends (the `done` event or
+// the connection closes). This is critical: the chat handler uses
+// r.Context() which cancels when the HTTP connection closes — if we stop
+// reading after the session event, the agent's work gets canceled mid-turn.
+// We must drain the full stream so the agent completes its turn server-side.
+func sendChat(ctx context.Context, gateway, sid, message string) (string, error) {
+	body, _ := json.Marshal(map[string]string{"session_id": sid, "message": message})
+	req, _ := http.NewRequestWithContext(ctx, "POST", gateway+"/chat", bytes.NewReader(body))
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != 200 && resp.StatusCode != 202 {
+		b, _ := io.ReadAll(resp.Body)
+		return "", fmt.Errorf("chat status %d: %s", resp.StatusCode, string(b))
+	}
+	// For a reconnect (sid != ""), the body is 202 with no stream.
+	if sid != "" {
+		io.Copy(io.Discard, resp.Body)
+		return sid, nil
+	}
+	// Read the SSE stream, capturing the session_id from the first session
+	// event, and draining the rest so the agent's turn completes. The stream
+	// ends when the server closes it (after the `done` event) or when the
+	// request context cancels.
+	dec := newSSEReader(resp.Body)
+	sessionID := ""
+	for {
+		ev, err := dec.next()
+		if err != nil {
+			if sessionID == "" {
+				return "", fmt.Errorf("no session event before stream end: %w", err)
+			}
+			return sessionID, nil
+		}
+		if ev["type"] == "session" && sessionID == "" {
+			if s, ok := ev["session_id"].(string); ok {
+				sessionID = s
+			}
+		}
+		// Keep reading until the stream ends — don't return early.
+	}
+}
+
+// waitForTurn polls the session until its last_active_at stops advancing for
+// 8 seconds (the turn ended) or the session reaches a terminal status. We
+// can't rely on status=done alone because a trivial task may auto-complete
+// while a plan-proposing task stays in 'executing' waiting for approval.
+func waitForTurn(ctx context.Context, gateway, sid string, deadline time.Time) error {
+	var lastActive string
+	stableSince := time.Now()
+	for {
+		if time.Now().After(deadline) {
+			return fmt.Errorf("timeout waiting for turn to complete")
+		}
+		_, session, err := fetchTranscript(ctx, gateway, sid)
+		if err != nil {
+			time.Sleep(2 * time.Second)
+			continue
+		}
+		if session.LastActive != lastActive {
+			lastActive = session.LastActive
+			stableSince = time.Now()
+		}
+		if time.Since(stableSince) >= 8*time.Second {
+			return nil // turn is idle — consider it complete
+		}
+		if session.Status == "done" || session.Status == "failed" {
+			return nil
+		}
+		time.Sleep(2 * time.Second)
+	}
+}
+
+type transcript struct {
+	Messages []struct {
+		Role    string `json:"role"`
+		Content struct {
+			Text      string            `json:"text"`
+			ToolCalls []map[string]any  `json:"tool_calls"`
+		} `json:"content"`
+	} `json:"messages"`
+	// PlanSteps is fetched from /sessions/{id}/plan (P5 plan_generations
+	// assertion). Each step carries a `generation` int; distinctGenerations
+	// counts the unique values. nil when the endpoint returned no plan
+	// (e.g. a pure-DB Q&A with no propose_plan call).
+	PlanSteps []planStep `json:"steps"`
+}
+
+// planStep is one step from /sessions/{id}/plan, carrying only the fields the
+// eval needs: the generation number (P2 iteration counter).
+type planStep struct {
+	Generation int    `json:"generation"`
+	Status     string `json:"status"`
+	Title      string `json:"title"`
+}
+
+func (t transcript) toolCallCount() int {
+	n := 0
+	for _, m := range t.Messages {
+		n += len(m.Content.ToolCalls)
+	}
+	return n
+}
+
+func (t transcript) toolNames() []string {
+	var names []string
+	for _, m := range t.Messages {
+		for _, tc := range m.Content.ToolCalls {
+			if name, ok := tc["name"].(string); ok {
+				names = append(names, name)
+			}
+		}
+	}
+	return names
+}
+
+// distinctGenerations counts unique plan generation values across all plan
+// steps. Used by the `plan_generations` assertion (P2 iteration). Returns 0
+// when there are no plan steps (no propose_plan was called).
+func (t transcript) distinctGenerations() int {
+	seen := map[int]bool{}
+	for _, s := range t.PlanSteps {
+		seen[s.Generation] = true
+	}
+	return len(seen)
+}
+
+type sessionState struct {
+	ID         string `json:"id"`
+	Status     string `json:"status"`
+	Outcome    string `json:"outcome"`
+	LastActive string `json:"last_active_at"`
+}
+
+// fetchTranscript fetches the messages from /sessions/{id} (which returns
+// only session_id + messages) and the session metadata from /sessions
+// (which returns status/outcome/last_active_at for each session). P5 also
+// fetches /sessions/{id}/plan for the plan_generations assertion.
+func fetchTranscript(ctx context.Context, gateway, sid string) (transcript, sessionState, error) {
+	var t transcript
+	resp, err := http.Get(gateway + "/sessions/" + sid)
+	if err != nil {
+		return t, sessionState{}, err
+	}
+	defer resp.Body.Close()
+	b, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return t, sessionState{}, err
+	}
+	if err := json.Unmarshal(b, &t); err != nil {
+		return t, sessionState{}, err
+	}
+	// Fetch the plan (steps with generation numbers) for the
+	// plan_generations assertion. A 404 or empty response is fine — a
+	// pure-DB Q&A with no propose_plan has no plan. ?all=true returns every
+	// generation so the assertion can count them (the default view returns
+	// only the current generation).
+	if planResp, perr := http.Get(gateway + "/sessions/" + sid + "/plan?all=true"); perr == nil {
+		if planResp.StatusCode == 200 {
+			pb, _ := io.ReadAll(planResp.Body)
+			_ = json.Unmarshal(pb, &t) // fills t.PlanSteps via "steps" field
+		}
+		planResp.Body.Close()
+	}
+	// The detail endpoint doesn't return status/outcome — fetch from the
+	// sessions list and find the matching id.
+	s, err := fetchSessionMeta(ctx, gateway, sid)
+	return t, s, err
+}
+
+// fetchSessionMeta fetches /sessions and extracts the one matching sid.
+func fetchSessionMeta(ctx context.Context, gateway, sid string) (sessionState, error) {
+	resp, err := http.Get(gateway + "/sessions")
+	if err != nil {
+		return sessionState{}, err
+	}
+	defer resp.Body.Close()
+	var list struct {
+		Sessions []sessionState `json:"sessions"`
+	}
+	if err := json.NewDecoder(resp.Body).Decode(&list); err != nil {
+		return sessionState{}, err
+	}
+	for _, s := range list.Sessions {
+		if s.ID == sid {
+			return s, nil
+		}
+	}
+	return sessionState{}, fmt.Errorf("session %s not found in list", sid)
+}
+
+// convResult is the outcome of one conversation.
+type convResult struct {
+	SessionID     string
+	Passed        bool
+	Duration      time.Duration
+	ToolCallCount int
+	Assertions    []assertionResult
+}
+
+type assertionResult struct {
+	Name   string
+	Passed bool
+	Detail string
+}

cmd/nomos/eval/manifest.go

@@ -0,0 +1,236 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"gopkg.in/yaml.v3"
+)
+
+// conversation is one golden conversation from a manifest.
+type conversation struct {
+	Name       string     `yaml:"name"`
+	Prompt     string     `yaml:"prompt"`
+	Followup   string     `yaml:"followup"`   // backward compat: single followup
+	Followups  []string   `yaml:"followups"`  // P5: multi-turn followups
+	Assertions []assertion `yaml:"assertions"`
+}
+
+// followups returns the full list of follow-up messages, supporting both
+// the single `followup` field (backward compat) and the multi-turn
+// `followups` list.
+func (c conversation) followups() []string {
+	if len(c.Followups) > 0 {
+		return c.Followups
+	}
+	if c.Followup != "" {
+		return []string{c.Followup}
+	}
+	return nil
+}
+
+// assertion is one check against the final transcript. The `kind` field
+// selects the scorer; the rest are scorer-specific parameters.
+//
+// Supported kinds:
+//
+//	completes             — session status reached done/failed (not stuck executing)
+//	outcome_is            — session outcome == value (success/failure/partial)
+//	no_propose_plan       — propose_plan was never called
+//	proposes_plan         — propose_plan called >= 1 time (plan-always model; P1)
+//	proposes_plan_once    — propose_plan was called exactly once
+//	no_duplicate_proposal — propose_plan called at most once
+//	plan_before_run       — the first `run` call comes after the first `propose_plan` (P1 ordering gate)
+//	plan_generations      — the persisted plan has exactly `value` distinct generations (P2 iteration: 1 = single, 2 = one followup)
+//	writes_back           — update_entity_attributes or create_relationship was called
+//	max_tool_calls        — total tool calls <= value
+//	max_run_calls         — total `run` calls <= value
+//	no_run                — `run` was never called
+//	calls_tool            — the named tool appears in the transcript
+//	plan_step_count       — the plan has exactly `value` steps
+//	no_duplicate_complete — complete_task called at most once
+type assertion struct {
+	Kind  string `yaml:"kind"`
+	Value any    `yaml:"value"`
+}
+
+// loadManifest reads a YAML file containing a list of conversations.
+func loadManifest(path string) ([]conversation, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	var convs []conversation
+	if err := yaml.Unmarshal(b, &convs); err != nil {
+		return nil, fmt.Errorf("parse %s: %w", path, err)
+	}
+	return convs, nil
+}
+
+// scoreAssertions evaluates each assertion against the transcript + session.
+func scoreAssertions(asserts []assertion, t transcript, s sessionState) []assertionResult {
+	out := make([]assertionResult, 0, len(asserts))
+	for _, a := range asserts {
+		r := assertionResult{Name: a.Kind}
+		r.Passed, r.Detail = scoreOne(a, t, s)
+		if !r.Passed && r.Detail == "" {
+			r.Detail = "assertion failed"
+		}
+		out = append(out, r)
+	}
+	return out
+}
+
+func scoreOne(a assertion, t transcript, s sessionState) (bool, string) {
+	tools := t.toolNames()
+	switch a.Kind {
+	case "completes":
+		if s.Status == "done" || s.Status == "failed" {
+			return true, fmt.Sprintf("status=%s", s.Status)
+		}
+		return false, fmt.Sprintf("status=%s (not terminal)", s.Status)
+
+	case "outcome_is":
+		want, _ := a.Value.(string)
+		if s.Outcome == want {
+			return true, fmt.Sprintf("outcome=%s", s.Outcome)
+		}
+		return false, fmt.Sprintf("outcome=%s, want %s", s.Outcome, want)
+
+	case "no_propose_plan":
+		n := countTool(tools, "propose_plan")
+		if n == 0 {
+			return true, "propose_plan not called"
+		}
+		return false, fmt.Sprintf("propose_plan called %d time(s)", n)
+
+	case "proposes_plan":
+		// P1 plan-always: propose_plan called >= 1 time.
+		n := countTool(tools, "propose_plan")
+		if n >= 1 {
+			return true, fmt.Sprintf("propose_plan called %d time(s)", n)
+		}
+		return false, "propose_plan never called (plan-always requires >= 1)"
+
+	case "proposes_plan_once":
+		n := countTool(tools, "propose_plan")
+		if n == 1 {
+			return true, "propose_plan called once"
+		}
+		return false, fmt.Sprintf("propose_plan called %d time(s), want 1", n)
+
+	case "no_duplicate_proposal":
+		n := countTool(tools, "propose_plan")
+		if n <= 1 {
+			return true, fmt.Sprintf("propose_plan called %d time(s)", n)
+		}
+		return false, fmt.Sprintf("propose_plan called %d time(s), want <= 1", n)
+
+	case "plan_before_run":
+		// P1 ordering gate: the first `run` call's global index in the
+		// transcript is strictly greater than the first `propose_plan`
+		// index. Both indices are over the flat tool-call list (across all
+		// messages, in order).
+		planIdx, runIdx := -1, -1
+		for i, name := range tools {
+			if name == "propose_plan" && planIdx == -1 {
+				planIdx = i
+			}
+			if name == "run" && runIdx == -1 {
+				runIdx = i
+			}
+		}
+		if runIdx == -1 {
+			return true, "run never called (ordering trivially satisfied)"
+		}
+		if planIdx == -1 {
+			return false, "run called but propose_plan never called"
+		}
+		if planIdx < runIdx {
+			return true, fmt.Sprintf("propose_plan at index %d before run at index %d", planIdx, runIdx)
+		}
+		return false, fmt.Sprintf("run at index %d before propose_plan at index %d", runIdx, planIdx)
+
+	case "plan_generations":
+		// P2 iteration: counts distinct `generation` values in
+		// session_plan_steps. 1 = single sub-task, 2 = one follow-up
+		// sub-task, etc. Requires the plan endpoint to return generation
+		// values; the eval fetches /sessions/{id}/plan and passes it via
+		// the transcript's PlanSteps field.
+		want := toInt(a.Value)
+		gens := t.distinctGenerations()
+		if gens == want {
+			return true, fmt.Sprintf("%d plan generation(s)", gens)
+		}
+		return false, fmt.Sprintf("%d plan generation(s), want %d", gens, want)
+
+	case "writes_back":
+		n := countTool(tools, "update_entity_attributes") + countTool(tools, "create_relationship")
+		if n > 0 {
+			return true, fmt.Sprintf("%d writeback call(s)", n)
+		}
+		return false, "no update_entity_attributes or create_relationship calls"
+
+	case "max_tool_calls":
+		max := toInt(a.Value)
+		if t.toolCallCount() <= max {
+			return true, fmt.Sprintf("%d tool calls (<= %d)", t.toolCallCount(), max)
+		}
+		return false, fmt.Sprintf("%d tool calls, want <= %d", t.toolCallCount(), max)
+
+	case "max_run_calls":
+		max := toInt(a.Value)
+		n := countTool(tools, "run")
+		if n <= max {
+			return true, fmt.Sprintf("%d run calls (<= %d)", n, max)
+		}
+		return false, fmt.Sprintf("%d run calls, want <= %d", n, max)
+
+	case "no_run":
+		n := countTool(tools, "run")
+		if n == 0 {
+			return true, "run not called"
+		}
+		return false, fmt.Sprintf("run called %d time(s)", n)
+
+	case "calls_tool":
+		want, _ := a.Value.(string)
+		n := countTool(tools, want)
+		if n > 0 {
+			return true, fmt.Sprintf("%s called %d time(s)", want, n)
+		}
+		return false, fmt.Sprintf("%s not called", want)
+
+	case "no_duplicate_complete":
+		n := countTool(tools, "complete_task")
+		if n <= 1 {
+			return true, fmt.Sprintf("complete_task called %d time(s)", n)
+		}
+		return false, fmt.Sprintf("complete_task called %d time(s), want <= 1", n)
+
+	default:
+		return false, fmt.Sprintf("unknown assertion kind: %s", a.Kind)
+	}
+}
+
+func countTool(names []string, name string) int {
+	n := 0
+	for _, x := range names {
+		if x == name {
+			n++
+		}
+	}
+	return n
+}
+
+func toInt(v any) int {
+	switch x := v.(type) {
+	case int:
+		return x
+	case int64:
+		return int(x)
+	case float64:
+		return int(x)
+	}
+	return 0
+}

cmd/nomos/eval/sse.go

@@ -0,0 +1,52 @@
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"io"
+	"strings"
+)
+
+// sseReader parses a text/event-stream into a sequence of JSON events.
+// Each event is one or more "data: " lines; the lines are concatenated
+// and parsed as a single JSON object. Blank lines separate events.
+type sseReader struct {
+	r *bufio.Reader
+}
+
+func newSSEReader(r io.Reader) *sseReader {
+	return &sseReader{r: bufio.NewReader(r)}
+}
+
+func (s *sseReader) next() (map[string]any, error) {
+	var data strings.Builder
+	for {
+		line, err := s.r.ReadString('\n')
+		if err != nil {
+			if err == io.EOF && data.Len() > 0 {
+				return parseEvent(data.String())
+			}
+			return nil, err
+		}
+		line = strings.TrimRight(line, "\r\n")
+		if line == "" {
+			if data.Len() > 0 {
+				return parseEvent(data.String())
+			}
+			continue // blank line, no event buffered yet
+		}
+		if strings.HasPrefix(line, "data: ") {
+			data.WriteString(strings.TrimPrefix(line, "data: "))
+		} else if strings.HasPrefix(line, "data:") {
+			data.WriteString(strings.TrimPrefix(line, "data:"))
+		}
+	}
+}
+
+func parseEvent(s string) (map[string]any, error) {
+	var ev map[string]any
+	if err := json.Unmarshal([]byte(s), &ev); err != nil {
+		return nil, err
+	}
+	return ev, nil
+}

cmd/nomos/main.go

@@ -11,10 +11,15 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"strconv"
 	"strings"
 	"sync"
 	"syscall"
 	"time"
+
+	"github.com/dtoro/oikos/internal/safego"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
 )
 
 func main() {
@@ -26,6 +31,10 @@ func main() {
 	if mcpURL == "" {
 		mcpURL = "http://localhost:8090/mcp"
 	}
+	// api's combinedAuth requires a bearer token on every request (no
+	// dev-open bypass — plans/2026-07-12-wails-desktop-app.md 0.4); this is
+	// the same shared secret api validates against (OIKOS_MCP_BEARER_TOKEN).
+	mcpToken := os.Getenv("OIKOS_MCP_BEARER_TOKEN")
 
 	agentSlug := os.Getenv("NOMOS_AGENT_SLUG")
 	if agentSlug == "" {
@@ -42,10 +51,19 @@ func main() {
 		ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
 		defer cancel()
 
-		client, err := newMCPClient(mcpURL)
-		if err != nil {
+		// One MCP client PER SESSION, not one shared client for the whole
+		// process — see mcpClientPool's doc comment. A dedicated client is
+		// created lazily on each session's first tool call.
+		clientPool := newMCPClientPool(mcpURL, mcpToken)
+		// Prove connectivity at startup the same way the old single-client
+		// constructor did, so a misconfigured/unreachable MCP endpoint still
+		// fails fast on boot instead of only on the first real chat. Doesn't
+		// reuse the pool (nothing to key it by yet) — just a throwaway probe.
+		if probe, err := newMCPClient(mcpURL, mcpToken); err != nil {
 			slog.Error("nomos: mcp connect", "url", mcpURL, "error", err)
 			os.Exit(1)
+		} else {
+			probe.close()
 		}
 
 		st, err := newStore(ctx, databaseURL)
@@ -57,19 +75,57 @@ func main() {
 			defer st.close()
 		}
 
-		nAgent, err := newAgent(ctx, client, st, agentSlug)
+		nAgent, err := newAgent(ctx, clientPool, st, agentSlug)
 		if err != nil {
 			slog.Error("nomos: agent init", "error", err)
 			os.Exit(1)
 		}
 
+		// Event-driven auto-continuation: feed finished async executions back
+		// into the agent so an approved plan runs to completion (and recovers
+		// from failures) without the operator ticking it forward each step.
+		safego.Go("nomos:continuation-worker", func() { nAgent.runContinuationWorker(ctx) })
+
+		// Idle sweep for stalled goal-bearing tasks (fix 2+3 of
+		// plans/2026-07-11-task-completion-safety-net.md) — a coarser,
+		// slower-ticking counterpart to the continuation worker above.
+		safego.Go("nomos:idle-sweep-worker", func() { nAgent.runIdleSweepWorker(ctx) })
+
+		safego.Go("nomos:mcp-pool-sweeper", func() {
+			ticker := time.NewTicker(5 * time.Minute)
+			defer ticker.Stop()
+			for {
+				select {
+				case <-ctx.Done():
+					return
+				case <-ticker.C:
+					clientPool.sweep()
+				}
+			}
+		})
+
+		// Stale execution sweep: cancels non-terminal executions older than
+		// 10 minutes (orphaned by MCP timeouts — see cleanupStaleExecutions).
+		safego.Go("nomos:stale-execution-sweeper", func() {
+			ticker := time.NewTicker(5 * time.Minute)
+			defer ticker.Stop()
+			for {
+				select {
+				case <-ctx.Done():
+					return
+				case <-ticker.C:
+					st.cleanupStaleExecutions(ctx, 10*time.Minute)
+				}
+			}
+		})
+
 		mux := http.NewServeMux()
 		mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
 			w.WriteHeader(200)
 			w.Write([]byte("ok"))
 		})
 		mux.HandleFunc("/query", func(w http.ResponseWriter, r *http.Request) {
-			handleQuery(w, r, client, agentSlug, mcpURL)
+			handleQuery(w, r, clientPool, agentSlug, mcpURL)
 		})
 		mux.HandleFunc("/chat", func(w http.ResponseWriter, r *http.Request) {
 			handleChat(w, r, nAgent, st)
@@ -78,7 +134,7 @@ func main() {
 			handleSessionsList(w, r, st)
 		})
 		mux.HandleFunc("/sessions/", func(w http.ResponseWriter, r *http.Request) {
-			handleSessionDetail(w, r, st)
+			handleSessionDetail(w, r, st, nAgent)
 		})
 
 		addr := os.Getenv("NOMOS_LISTEN")
@@ -87,17 +143,17 @@ func main() {
 		}
 
 		srv := &http.Server{Addr: addr, Handler: mux}
-		go func() {
+		safego.Go("nomos:http-server", func() {
 			slog.Info("nomos: gateway listening", "addr", addr, "mcp", mcpURL, "db", databaseURL != "")
 			if err := srv.ListenAndServe(); err != http.ErrServerClosed {
 				slog.Error("nomos: serve", "error", err)
 			}
-		}()
+		})
 
 		<-ctx.Done()
 		slog.Info("nomos: shutting down")
 		srv.Shutdown(context.Background())
-		client.close()
+		clientPool.closeAll()
 
 	default:
 		fmt.Fprintf(os.Stderr, "unknown command: %s\n", os.Args[1])
@@ -111,6 +167,147 @@ func sseEvent(w http.ResponseWriter, flusher http.Flusher, event agentEvent) {
 	flusher.Flush()
 }
 
+// runChatTurn is the shared core of an operator-initiated turn: insert an
+// assistant placeholder, run a.chat with incremental persistence (so whatever
+// happened before an abort is never lost), finalize the row, and derive a
+// title. It is agnostic to the transport: `sink` receives every agent event
+// for delivery (SSE for a live handleChat, a no-op for a queued turn that has
+// no client attached — the frontend learns about those via the poller + the
+// status-driven "working" signal). The caller MUST already hold the session's
+// turn-gate permit.
+func (a *agent) runChatTurn(pctx, ctx context.Context, sessionID, message string, sink func(agentEvent)) {
+	toolCalls := []map[string]any{}
+	// P3: accumulate per-iteration reasoning instead of overwriting with the
+	// final `text` event (see the original inline comment in handleChat).
+	var textParts []string
+	var thinkingParts []string
+	var finalText string
+	var finalThinking string
+
+	placeholder, _ := json.Marshal(map[string]any{"role": "assistant", "text": ""})
+	msgID, err := a.store.insertMessageReturningID(pctx, sessionID, "assistant", placeholder)
+	if err != nil {
+		slog.Error("nomos: chat placeholder insert failed", "session", sessionID, "error", err)
+	}
+	persist := func() {
+		if msgID == uuid.Nil {
+			return
+		}
+		body, _ := json.Marshal(map[string]any{
+			"role":       "assistant",
+			"text":       finalText,
+			"thinking":   finalThinking,
+			"tool_calls": toolCalls,
+		})
+		a.store.updateMessage(pctx, msgID, body)
+	}
+
+	a.chat(ctx, sessionID, message, func(ev agentEvent) {
+		if ev.Type == "tool_use" || ev.Type == "tool_result" {
+			if m, ok := ev.Data.(map[string]any); ok {
+				m["type"] = ev.Type
+				// One entry per tool call: tool_use creates it, tool_result
+				// merges the result into the same entry (matched by id).
+				id, _ := m["id"].(string)
+				if id != "" && ev.Type == "tool_result" {
+					for _, existing := range toolCalls {
+						if eID, _ := existing["id"].(string); eID == id {
+							for k, v := range m {
+								existing[k] = v
+							}
+							break
+						}
+					}
+				} else {
+					toolCalls = append(toolCalls, m)
+				}
+			}
+			persist() // live: survives even if the client disconnects right after
+		}
+		if ev.Type == "text" {
+			if t, ok := ev.Data.(string); ok && t != "" {
+				if ev.IsThinking {
+					thinkingParts = append(thinkingParts, t)
+					finalThinking = strings.Join(thinkingParts, "\n\n")
+				} else {
+					textParts = append(textParts, t)
+					finalText = strings.Join(textParts, "\n\n")
+				}
+				persist()
+			}
+		}
+		sink(ev)
+	})
+
+	// B.6: if the turn ended with no text and no tool calls (the model
+	// empty-response'd and all retries failed), delete the placeholder row
+	// instead of persisting an empty bubble.
+	if finalText == "" && len(toolCalls) == 0 && msgID != uuid.Nil {
+		a.store.deleteMessage(pctx, msgID)
+	} else {
+		persist() // final state — same row, updated one last time
+	}
+
+	// Title: prefer the goal once set; else the first assistant answer.
+	if finalText != "" && sessionID != "ephemeral" {
+		var goalTitle string
+		if sess, gerr := a.store.getSession(pctx, sessionID); gerr == nil && sess.Goal != "" {
+			goalTitle = truncate(sess.Goal, 120)
+		}
+		title := goalTitle
+		if title == "" {
+			title = truncate(finalText, 80)
+		}
+		if title != "" {
+			a.store.updateSessionTitle(pctx, sessionID, title)
+		}
+	}
+}
+
+// drainAcquireWait is how long drainQueued blocks for a busy gate before
+// re-queuing and deferring to the holder's own release-drain. A package var so
+// tests can shorten it; in production it just needs to outlast the brief
+// release→drain handoff window.
+var drainAcquireWait = 5 * time.Second
+
+// drainQueued runs every queued operator message for a session as its own turn,
+// one at a time, under the turn gate. Called (in a goroutine) whenever a turn
+// releases the gate — from handleChat (live) and resumeSession (background) —
+// so a message queued while the agent was busy is acted on as soon as it's
+// free, without the operator re-sending. See messagequeue.go (plan 2026-08-03
+// F2).
+//
+// Each queued turn is persisted incrementally and has no SSE client (the
+// browser detached after receiving the `queued` event); the frontend sees the
+// result via the 3s poller and the status-driven "working" indicator.
+func (a *agent) drainQueued(ctx context.Context, sessionID string) {
+	for {
+		msg, ok := a.queue.dequeue(sessionID)
+		if !ok {
+			return
+		}
+		// Block briefly for the gate. If a live turn grabbed it first, put the
+		// message back — that turn's release will drain it again. Never stack.
+		if !a.gate.acquire(sessionID, drainAcquireWait) {
+			a.queue.requeueFront(sessionID, msg)
+			return
+		}
+		slog.Info("nomos: running queued operator message", "session", sessionID)
+		pctx := context.Background()
+		// Run the turn inside a per-iteration closure so the gate release is
+		// deferred to the end of THIS turn (and runs even if runChatTurn
+		// panics — safego recovers the panic at the goroutine boundary, so a
+		// non-deferred release would be skipped and the session's permit held
+		// forever, deadlocking all future turns). A bare `defer release` in
+		// the loop would be wrong too: Go defers run at function exit, not
+		// iteration exit, so the gate would stay held across iterations.
+		func() {
+			defer a.gate.release(sessionID)
+			a.runChatTurn(pctx, ctx, sessionID, msg, func(agentEvent) {})
+		}()
+	}
+}
+
 func handleChat(w http.ResponseWriter, r *http.Request, a *agent, st *store) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", 405)
@@ -125,11 +322,40 @@ func handleChat(w http.ResponseWriter, r *http.Request, a *agent, st *store) {
 		http.Error(w, "bad request: "+err.Error(), 400)
 		return
 	}
-	if req.Message == "" {
+	if req.Message == "" && req.SessionID == "" {
 		http.Error(w, "message is required", 400)
 		return
 	}
 
+	// Empty message with an existing session = reconnect/resume. This path is
+	// defensive now — the frontend (post F2) recovers a dropped SSE via the
+	// poller + terminal task.status clearing, and no longer POSTs empty
+	// messages. If a client ever does, route into resumeSession so the agent
+	// reports current state — but SKIP a terminal session (done/failed/
+	// abandoned): there's nothing to resume, and running a "report state"
+	// turn there is just a spare turn the operator never asked for (P2.1).
+	if req.Message == "" && req.SessionID != "" {
+		if sess, err := st.getSession(context.Background(), req.SessionID); err == nil {
+			switch sess.Status {
+			case "done", "failed", "abandoned":
+				slog.Info("nomos: reconnect skipped — session already terminal", "session", req.SessionID, "status", sess.Status)
+				w.WriteHeader(202)
+				return
+			}
+		}
+		slog.Info("nomos: reconnect", "session", req.SessionID)
+		safego.Go("nomos:reconnect:"+req.SessionID, func() {
+			base := "[System: the operator's connection was re-established. The task may have progressed in the background.]"
+			note := st.enrichResumeNote(context.Background(), req.SessionID, base)
+			a.resumeSession(context.Background(), req.SessionID, note)
+		})
+		// Return 202 so the frontend doesn't try to consume an SSE stream
+		// from this POST — resumeSession writes to the DB directly and
+		// the poller picks it up.
+		w.WriteHeader(202)
+		return
+	}
+
 	flusher, ok := w.(http.Flusher)
 	if !ok {
 		http.Error(w, "streaming not supported", 500)
@@ -139,14 +365,38 @@ func handleChat(w http.ResponseWriter, r *http.Request, a *agent, st *store) {
 	w.Header().Set("Content-Type", "text/event-stream")
 	w.Header().Set("Cache-Control", "no-cache")
 	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("X-Accel-Buffering", "no") // disable proxy buffering
 	w.WriteHeader(200)
 
+	// All writes to w (events + the keepalive comment below) go through one
+	// mutex: http.ResponseWriter is NOT safe for concurrent use, and the
+	// keepalive ticker runs alongside the turn's event sink (plan 2026-08-03
+	// F3). Without this, interleaved writes corrupt the SSE stream.
+	var writeMu sync.Mutex
+	writeEvent := func(ev agentEvent) {
+		writeMu.Lock()
+		defer writeMu.Unlock()
+		sseEvent(w, flusher, ev)
+	}
+
 	ctx := r.Context()
 	sessionID := req.SessionID
 
+	// pctx (persistence context) is deliberately context.Background(), not
+	// ctx/r.Context(), for every DB write in this handler — ctx cancels the
+	// instant the client disconnects (Stop button, tab close, network blip),
+	// and a write made with an already-cancelled context fails. Before this
+	// fix, the assistant message was only ever saved ONCE, at the very end,
+	// using ctx — so a disconnect mid-turn silently lost the ENTIRE turn's
+	// tool-call history from the persisted transcript, even though real work
+	// (executions launched, knowledge written) had already happened
+	// server-side. The agent's own work (a.chat below) still correctly stops
+	// when ctx cancels — this only changes what happens to persistence.
+	pctx := context.Background()
+
 	if sessionID == "" {
 		title := truncate(req.Message, 80)
-		sess, err := st.createSession(ctx, title)
+		sess, err := st.createSession(pctx, title)
 		if err != nil {
 			slog.Error("nomos: create session", "error", err)
 			sessionID = "ephemeral"
@@ -154,38 +404,91 @@ func handleChat(w http.ResponseWriter, r *http.Request, a *agent, st *store) {
 			sessionID = sess.ID
 		}
 	} else {
-		st.touchSession(ctx, sessionID)
+		// P2 iteration: if the operator sends a follow-up on a session
+		// that already reached a terminal state (done/failed), reopen it
+		// so a new sub-task can be framed (set_goal → propose_plan →
+		// execute). reopenSession marks the prior plan's steps as
+		// `replaced` (proposePlan ignores those) and clears outcome/
+		// summary. Without this, propose_plan refuses the follow-up with
+		// errPlanInFlight because the prior steps are all `done`. If the
+		// session is still active, reopen is a no-op — the follow-up is
+		// just a continuation of in-flight work.
+		st.reopenSession(pctx, sessionID)
+		st.touchSession(pctx, sessionID)
 	}
 
 	slog.Info("nomos: chat", "session", sessionID, "message", truncate(req.Message, 100))
 
 	userMsg, _ := json.Marshal(map[string]any{"role": "user", "text": req.Message})
-	st.saveMessage(ctx, sessionID, "user", userMsg)
+	st.saveMessage(pctx, sessionID, "user", userMsg)
 
-	sseEvent(w, flusher, agentEvent{Type: "session", Data: sessionID, SessionID: sessionID})
+	// If this task has a pending operator question, the incoming message IS the
+	// answer — close it so the panel clears. No separate resume needed: this
+	// chat turn is the resume, and the agent sees the question + answer in its
+	// replayed history.
+	if qid := st.openQuestionID(pctx, sessionID); qid != "" {
+		st.answerQuestion(pctx, sessionID, qid, req.Message)
+	}
 
-	toolCalls := []map[string]any{}
-	var finalText string
+	writeEvent(agentEvent{Type: "session", Data: sessionID, SessionID: sessionID})
 
-	a.chat(ctx, sessionID, req.Message, func(ev agentEvent) {
-		if ev.Type == "tool_use" || ev.Type == "tool_result" {
-			if m, ok := ev.Data.(map[string]any); ok {
-				m["type"] = ev.Type
-				toolCalls = append(toolCalls, m)
+	// F1/F2 (plan 2026-08-03): serialize turns per session. The user message is
+	// already persisted above, so it is never lost. Wait briefly for a finishing
+	// background turn; if one is still running after that, QUEUE this message
+	// (don't reject it) and tell the client so it shows a "queued" state. The
+	// in-flight turn's release drains the queue (drainQueued) and runs it as a
+	// real turn server-side. This never stacks concurrent turns — the gate still
+	// guarantees one in-flight turn per session.
+	const turnWait = 5 * time.Second
+	if !a.gate.acquire(sessionID, turnWait) {
+		a.queue.enqueue(sessionID, req.Message)
+		slog.Info("nomos: turn already active, queued operator message", "session", sessionID)
+		writeEvent(agentEvent{Type: "queued", Data: sessionID, SessionID: sessionID})
+		writeEvent(agentEvent{Type: "done", Data: map[string]any{
+			"session_id": sessionID,
+			"queued":     true,
+		}, SessionID: sessionID})
+		return
+	}
+	defer func() {
+		a.gate.release(sessionID)
+		// Run any message that was queued while this turn held the gate. In a
+		// goroutine so the HTTP response finishes without waiting on the next
+		// turn; the queued turn has no SSE client of its own.
+		safego.Go("nomos:drain:"+sessionID, func() { a.drainQueued(context.Background(), sessionID) })
+	}()
+
+	// F3 (plan 2026-08-03): keep the SSE alive during long turns. A turn can
+	// run for many minutes (provisioning chains, deep research); the model
+	// often takes 20-40s between tool iterations, and with nothing flushed in
+	// that gap a proxy/browser idle timeout silently closes the stream. The
+	// client then sees streaming=false while the server keeps working — the
+	// "I can't tell it's working" desync. An SSE comment line (":keepalive") is
+	// ignored by EventSource but resets idle timers.
+	keepDone := make(chan struct{})
+	go func() {
+		t := time.NewTicker(12 * time.Second)
+		defer t.Stop()
+		for {
+			select {
+			case <-keepDone:
+				return
+			case <-t.C:
+				writeMu.Lock()
+				fmt.Fprintf(w, ":keepalive\n\n")
+				flusher.Flush()
+				writeMu.Unlock()
 			}
 		}
-		if ev.Type == "text" {
-			finalText, _ = ev.Data.(string)
-		}
-		sseEvent(w, flusher, ev)
+	}()
+	// Defer the close (not a statement after runChatTurn) so the goroutine
+	// exits even if runChatTurn panics — net/http recovers handler panics, so
+	// a non-deferred close would be skipped and the ticker would keep writing
+	// to a dead ResponseWriter forever.
+	defer close(keepDone)
+	a.runChatTurn(pctx, ctx, sessionID, req.Message, func(ev agentEvent) {
+		writeEvent(ev)
 	})
-
-	assistantMsg, _ := json.Marshal(map[string]any{
-		"role":       "assistant",
-		"text":       finalText,
-		"tool_calls": toolCalls,
-	})
-	st.saveMessage(ctx, sessionID, "assistant", assistantMsg)
 }
 
 func handleSessionsList(w http.ResponseWriter, r *http.Request, st *store) {
@@ -199,37 +502,204 @@ func handleSessionsList(w http.ResponseWriter, r *http.Request, st *store) {
 		return
 	}
 
-	sessions, err := st.listSessions(r.Context())
+	// P2.8 (2026-07-20): filtering + pagination. The audit script in
+	// .agents/skills/session-review/SKILL.md slices `.sessions[:10]`
+	// client-side; "show me partial sessions touching lxc:rclone"
+	// required fetching the full list and filtering in JS. Push the
+	// filters into SQL so the audit becomes a single `curl | jq`.
+	// Supported query params (all optional, composable):
+	//   ?outcome=partial|success|failure       — exact match on outcome
+	//   ?status=active|done|failed|executing   — exact match on status
+	//   ?entity_id=<uuid>                      — exact match on entity_id
+	//   ?since=<RFC3339 or duration>           — last_active_at >= ...
+	//   ?blocker=<reason>                      — exact match on blocker
+	//   ?limit=<int>                           — default 50, max 200
+	//   ?cursor=<iso timestamp>                — last_active_at < cursor (page back)
+	q := r.URL.Query()
+	limit := 50
+	if v := q.Get("limit"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 && n <= 200 {
+			limit = n
+		}
+	}
+	sessions, err := st.listSessionsFiltered(r.Context(), listFilter{
+		Outcome:  q.Get("outcome"),
+		Status:   q.Get("status"),
+		EntityID: q.Get("entity_id"),
+		Blocker:  q.Get("blocker"),
+		Since:    q.Get("since"),
+		Cursor:   q.Get("cursor"),
+		Limit:    limit,
+	})
 	if err != nil {
 		http.Error(w, err.Error(), 500)
 		return
 	}
+	// Next-page cursor: the oldest last_active_at in this page. The next
+	// request passes it as ?cursor=... to get the page before it. Empty
+	// when the list is exhausted.
+	var nextCursor string
+	if len(sessions) > 0 {
+		oldest := sessions[len(sessions)-1].LastActiveAt
+		nextCursor = oldest.UTC().Format(time.RFC3339Nano)
+		if len(sessions) < limit {
+			nextCursor = "" // last page
+		}
+	}
 	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{"sessions": sessions})
+	json.NewEncoder(w).Encode(map[string]any{
+		"sessions":    sessions,
+		"next_cursor": nextCursor,
+		"limit":       limit,
+	})
 }
 
-func handleSessionDetail(w http.ResponseWriter, r *http.Request, st *store) {
+func handleSessionDetail(w http.ResponseWriter, r *http.Request, st *store, a *agent) {
 	if st == nil {
 		http.Error(w, "not found", 404)
 		return
 	}
 
-	id := strings.TrimPrefix(r.URL.Path, "/sessions/")
+	rest := strings.TrimPrefix(r.URL.Path, "/sessions/")
+	parts := strings.Split(rest, "/")
+	id := parts[0]
 	if id == "" {
 		http.Error(w, "session id required", 400)
 		return
 	}
 
-	messages, err := st.getMessages(r.Context(), id)
-	if err != nil {
+	// POST /sessions/{id}/questions/{qid}/answer — the operator answers a
+	// pinned question from the context panel; resume the agent with the answer.
+	if len(parts) == 4 && parts[1] == "questions" && parts[3] == "answer" {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", 405)
+			return
+		}
+		handleAnswerQuestion(w, r, st, a, id, parts[2])
+		return
+	}
+
+	// POST /sessions/{id}/resume — the operator asks the agent to continue.
+	if len(parts) == 2 && parts[1] == "resume" && r.Method == http.MethodPost {
+		base := "[System: the operator wants you to continue. Pick up where you left off — execute the next step of the plan, diagnose and fix any failures, or report progress if everything is done.]"
+		note := st.enrichResumeNote(context.Background(), id, base)
+		safego.Go("nomos:resume-session", func() { a.resumeSession(context.Background(), id, note) })
+		w.WriteHeader(202)
+		return
+	}
+
+	// GET /sessions/{id}/plan and /sessions/{id}/questions — REST hydration for
+	// the context panel when it first opens a task; live events carry deltas
+	// from there.
+	// GET /sessions/{id}/tool_calls — flat view of every tool call in the
+	// session, without the two-level message-shell nesting. The audit at
+	// plans/2026-07-20-session-review-ten-sessions.md P2.10 had to write
+	// Python to walk messages[].content.tool_calls[]; this endpoint makes
+	// it a single `curl | jq`.
+	if len(parts) == 2 && r.Method == http.MethodGet {
+		switch parts[1] {
+		case "plan":
+			all := r.URL.Query().Has("all") && r.URL.Query().Get("all") != "0" && r.URL.Query().Get("all") != "false"
+			steps, err := st.getPlanSteps(r.Context(), id, all)
+			if err != nil {
+				http.Error(w, err.Error(), 500)
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(map[string]any{"steps": steps})
+			return
+		case "questions":
+			questions, err := st.getQuestions(r.Context(), id)
+			if err != nil {
+				http.Error(w, err.Error(), 500)
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(map[string]any{"questions": questions})
+			return
+		case "tool_calls":
+			calls, err := st.getSessionToolCalls(r.Context(), id)
+			if err != nil {
+				http.Error(w, err.Error(), 500)
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(map[string]any{"session_id": id, "tool_calls": calls})
+			return
+		}
+	}
+
+	switch r.Method {
+	case http.MethodDelete:
+		if err := st.deleteSession(r.Context(), id); err != nil {
+			http.Error(w, err.Error(), 500)
+			return
+		}
+		w.WriteHeader(204)
+
+	case http.MethodGet:
+		// P2.7 (2026-07-20): return BOTH session metadata and messages
+		// from GET /sessions/{id}. Previously this endpoint returned only
+		// {session_id, messages} — the operator had to merge with the
+		// /sessions list view to get title/goal/outcome. The eval harness
+		// at cmd/nomos/eval/main.go:302-303 already carries a comment
+		// about this leaky abstraction. The session field carries the
+		// full metadata: title, goal, outcome, summary, blocker,
+		// pending_approvals, message_count, tool_call_count, etc. The
+		// messages field is unchanged. Clients that only read
+		// `messages` keep working.
+		sess, err := st.getSession(r.Context(), id)
+		if err != nil {
+			if err == pgx.ErrNoRows {
+				http.Error(w, "session not found", 404)
+				return
+			}
+			http.Error(w, err.Error(), 500)
+			return
+		}
+		messages, err := st.getMessages(r.Context(), id)
+		if err != nil {
+			http.Error(w, err.Error(), 500)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"session_id": id,
+			"session":    sess,
+			"messages":   messages,
+		})
+
+	default:
+		http.Error(w, "method not allowed", 405)
+	}
+}
+
+// handleAnswerQuestion records the operator's answer to a pinned question and
+// resumes the agent in the background with that answer injected. Returns 202 —
+// the agent's response lands via the normal message-polling path, not this POST.
+func handleAnswerQuestion(w http.ResponseWriter, r *http.Request, st *store, a *agent, sessionID, questionID string) {
+	var req struct {
+		Answer string `json:"answer"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil || strings.TrimSpace(req.Answer) == "" {
+		http.Error(w, "answer is required", 400)
+		return
+	}
+	prompt, _, _ := st.getQuestion(r.Context(), questionID)
+	if err := st.answerQuestion(r.Context(), sessionID, questionID, req.Answer); err != nil {
 		http.Error(w, err.Error(), 500)
 		return
 	}
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{"session_id": id, "messages": messages})
+	if a != nil {
+		base := fmt.Sprintf("[System: the operator answered your question %q with: %q. "+
+			"Continue the task from here — do not re-ask.]", prompt, req.Answer)
+		note := st.enrichResumeNote(context.Background(), sessionID, base)
+		safego.Go("nomos:resume-session", func() { a.resumeSession(context.Background(), sessionID, note) })
+	}
+	w.WriteHeader(202)
 }
 
-func handleQuery(w http.ResponseWriter, r *http.Request, client *mcpClient, agentSlug, mcpURL string) {
+func handleQuery(w http.ResponseWriter, r *http.Request, pool *mcpClientPool, agentSlug, mcpURL string) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", 405)
 		return
@@ -245,6 +715,16 @@ func handleQuery(w http.ResponseWriter, r *http.Request, client *mcpClient, agen
 		return
 	}
 
+	// The structured /query endpoint is stateless/session-less — "query" is a
+	// fixed pool key (not a real session id) so repeated calls reuse one
+	// dedicated connection instead of paying a fresh MCP handshake every time,
+	// while still never sharing a connection with an actual chat task.
+	client, err := pool.get("query")
+	if err != nil {
+		http.Error(w, "mcp unavailable: "+err.Error(), 502)
+		return
+	}
+
 	start := time.Now()
 
 	if req.Tool != "" {
@@ -315,16 +795,30 @@ func truncate(s string, n int) string {
 
 type mcpClient struct {
 	baseURL   string
+	token     string // OIKOS_MCP_BEARER_TOKEN — api's combinedAuth requires it on every request (no dev-open bypass)
 	sessionID string
 	http      *http.Client
 	nextID    int
-	mu        sync.Mutex // MCP is one stateful session; serialize concurrent calls
+	mu        sync.Mutex // this client is one stateful MCP session; serialize ITS OWN calls
+
+	// toolsCache holds the last tools/list result. The tool list is static
+	// for the lifetime of one MCP connection — it only changes when the api
+	// process (re)registers tools, i.e. on a restart, which this client
+	// already detects and reacts to via reconnectLocked. Without this,
+	// buildTools (called at the start of EVERY chat turn, including every
+	// auto-continuation resume) paid a full tools/list round-trip every
+	// single time for a list that's almost always identical to the last one.
+	// Guarded separately from mu (not reused) so a cache check never
+	// contends with an in-flight doRequest call for a different method.
+	toolsMu    sync.Mutex
+	toolsCache []toolDef
 }
 
-func newMCPClient(baseURL string) (*mcpClient, error) {
+func newMCPClient(baseURL, token string) (*mcpClient, error) {
 	c := &mcpClient{
 		baseURL: baseURL,
-		http:    &http.Client{Timeout: 30 * time.Second},
+		token:   token,
+		http:    &http.Client{Timeout: 120 * time.Second},
 	}
 
 	resp, err := c.doRequest("initialize", map[string]any{
@@ -378,6 +872,12 @@ func (c *mcpClient) doRequest(method string, params map[string]any) (*mcpJSONRPC
 // reconnectLocked re-initializes the MCP session. The caller must hold c.mu.
 func (c *mcpClient) reconnectLocked() error {
 	c.sessionID = ""
+	// A reconnect means the api process was restarted (or forgot us) — its
+	// tool registration may have changed, so the cached list is no longer
+	// trustworthy.
+	c.toolsMu.Lock()
+	c.toolsCache = nil
+	c.toolsMu.Unlock()
 	resp, err := c.send("initialize", map[string]any{
 		"protocolVersion": "2024-11-05",
 		"capabilities":    map[string]any{},
@@ -414,6 +914,9 @@ func (c *mcpClient) send(method string, params map[string]any) (*mcpJSONRPCRespo
 	if c.sessionID != "" {
 		req.Header.Set("Mcp-Session-Id", c.sessionID)
 	}
+	if c.token != "" {
+		req.Header.Set("Authorization", "Bearer "+c.token)
+	}
 
 	resp, err := c.http.Do(req)
 	if err != nil {
@@ -518,3 +1021,107 @@ func (c *mcpClient) listTools() ([]string, error) {
 
 func (c *mcpClient) close() {
 }
+
+// ─── Per-session MCP client pool ────────────────────────────────────────
+//
+// A single shared mcpClient serializes EVERY tool call across EVERY
+// concurrently-running task through one mutex (see mcpClient.mu) — `run`
+// executes its SSH command synchronously inside that lock and is capped at
+// up to 10 minutes, so one task mid-`run` stalled every other task's tool
+// calls, even trivial reads, behind it. The MCP *server* has no per-
+// connection state to protect (newServer in internal/mcp/server.go returns
+// one shared *mcp.Server instance whose tool handlers close only over the DB
+// pool, which is already safe for concurrent use) — the mutex existed purely
+// because the *client* reused one stateful transport session, not because
+// the server needed it. Giving each task's own session its own client
+// removes the cross-task serialization entirely: a task's own tool calls
+// stay sequential (which they already are — the agent loop calls tools one
+// at a time within a turn), but no longer block anyone else's.
+type mcpClientPool struct {
+	baseURL string
+	token   string
+	mu      sync.Mutex
+	clients map[string]*pooledMCPClient
+}
+
+type pooledMCPClient struct {
+	client   *mcpClient
+	lastUsed time.Time
+}
+
+func newMCPClientPool(baseURL, token string) *mcpClientPool {
+	return &mcpClientPool{baseURL: baseURL, token: token, clients: make(map[string]*pooledMCPClient)}
+}
+
+// get returns the client for sessionID, creating and initializing one (a
+// real MCP handshake) on first use. Session ids that don't identify a real
+// persisted conversation ("" / "ephemeral", the no-DB-store path; "query",
+// the structured /query endpoint) still get exactly one dedicated,
+// reused client each via the same map — just keyed on a fixed string instead
+// of a real session id — so that traffic doesn't pay a fresh handshake per
+// request while still never sharing a connection with an actual task.
+func (p *mcpClientPool) get(sessionID string) (*mcpClient, error) {
+	key := sessionID
+	if key == "" {
+		key = "ephemeral"
+	}
+
+	p.mu.Lock()
+	if pc, ok := p.clients[key]; ok {
+		pc.lastUsed = time.Now()
+		p.mu.Unlock()
+		return pc.client, nil
+	}
+	p.mu.Unlock()
+
+	// Initialize outside the lock — it's a network round-trip, and holding
+	// the pool mutex for it would serialize unrelated sessions' first calls
+	// behind each other, undermining the whole point of this pool.
+	c, err := newMCPClient(p.baseURL, p.token)
+	if err != nil {
+		return nil, err
+	}
+
+	p.mu.Lock()
+	// Another goroutine may have created one for the same key while we were
+	// initializing (two of this session's tool calls racing on a cold
+	// start); keep whichever won, close out the loser's connection (a no-op
+	// today, but future-proof if mcpClient.close ever does real teardown).
+	if existing, ok := p.clients[key]; ok {
+		p.mu.Unlock()
+		c.close()
+		return existing.client, nil
+	}
+	p.clients[key] = &pooledMCPClient{client: c, lastUsed: time.Now()}
+	p.mu.Unlock()
+	return c, nil
+}
+
+// mcpClientIdleTimeout is how long an idle session's MCP client is kept
+// before eviction — long enough to outlive a single slow `run` (capped at 10
+// minutes server-side) plus normal think-time between a task's tool calls,
+// short enough not to accumulate one abandoned connection per finished task
+// forever.
+const mcpClientIdleTimeout = 20 * time.Minute
+
+// sweep evicts clients idle past mcpClientIdleTimeout. Call on a ticker.
+func (p *mcpClientPool) sweep() {
+	cutoff := time.Now().Add(-mcpClientIdleTimeout)
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	for key, pc := range p.clients {
+		if pc.lastUsed.Before(cutoff) {
+			pc.client.close()
+			delete(p.clients, key)
+		}
+	}
+}
+
+func (p *mcpClientPool) closeAll() {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	for key, pc := range p.clients {
+		pc.client.close()
+		delete(p.clients, key)
+	}
+}

cmd/nomos/messagequeue.go

@@ -0,0 +1,82 @@
+package main
+
+import (
+	"log/slog"
+	"sync"
+)
+
+// maxQueuedPerSession caps a session's queue. A held turn plus unbounded
+// enqueues would grow memory without limit; an operator nudging a long
+// autonomous turn realistically queues only a handful, so a generous cap is
+// pure insurance. Overflow drops the newest enqueue and logs (the message is
+// already persisted in the DB by handleChat before enqueue, so it isn't lost
+// from the transcript — it just won't auto-run).
+const maxQueuedPerSession = 20
+
+// messageQueue holds operator messages that arrived while a turn was already
+// running for a session. Plan 2026-08-03 (F2): instead of rejecting the
+// operator's message with "Nomos is still finishing a previous step… send it
+// again", the message is queued and auto-run when the in-flight turn releases
+// the session's turn-gate permit.
+//
+// The queue only schedules WHEN a turn runs, not WHETHER the message is stored
+// — handleChat persists the user message before acquiring the gate, so a queued
+// message is already in the transcript; this just makes sure a turn eventually
+// acts on it.
+//
+// Draining is strictly one-at-a-time under the turn gate (see drainQueued in
+// main.go), so this cannot stack concurrent turns — the exact hazard the gate
+// itself exists to prevent. Background resumeSession callers never touch this
+// queue; they keep their non-blocking skip.
+type messageQueue struct {
+	mu    sync.Mutex
+	queue map[string][]string
+}
+
+func newMessageQueue() *messageQueue {
+	return &messageQueue{queue: map[string][]string{}}
+}
+
+// enqueue appends a message to the back of the session's FIFO. Returns false
+// (and logs) if the session is already at maxQueuedPerSession — the caller's
+// message is already persisted in the DB, so this only skips auto-running it.
+func (q *messageQueue) enqueue(sessionID, msg string) bool {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	if len(q.queue[sessionID]) >= maxQueuedPerSession {
+		slog.Warn("nomos: message queue full; dropping auto-run for operator message", "session", sessionID, "cap", maxQueuedPerSession)
+		return false
+	}
+	q.queue[sessionID] = append(q.queue[sessionID], msg)
+	return true
+}
+
+// dequeue pops the next message from the front of the session's FIFO. Returns
+// ok=false when empty.
+func (q *messageQueue) dequeue(sessionID string) (string, bool) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	xs := q.queue[sessionID]
+	if len(xs) == 0 {
+		return "", false
+	}
+	m := xs[0]
+	q.queue[sessionID] = xs[1:]
+	return m, true
+}
+
+// requeueFront pushes a message back to the front — used when a drainer popped
+// a message but lost the race for the gate to a live turn; that turn's own
+// release will drain it again.
+func (q *messageQueue) requeueFront(sessionID, msg string) {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	q.queue[sessionID] = append([]string{msg}, q.queue[sessionID]...)
+}
+
+// peek reports the queued depth for a session (test/diagnostic helper).
+func (q *messageQueue) peek(sessionID string) int {
+	q.mu.Lock()
+	defer q.mu.Unlock()
+	return len(q.queue[sessionID])
+}

cmd/nomos/messagequeue_test.go

@@ -0,0 +1,142 @@
+package main
+
+import (
+	"context"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestMessageQueue_FIFO(t *testing.T) {
+	q := newMessageQueue()
+	q.enqueue("s", "first")
+	q.enqueue("s", "second")
+	q.enqueue("s", "third")
+
+	want := []string{"first", "second", "third"}
+	for _, w := range want {
+		got, ok := q.dequeue("s")
+		if !ok || got != w {
+			t.Fatalf("dequeue = %q,%v want %q,true", got, ok, w)
+		}
+	}
+	if _, ok := q.dequeue("s"); ok {
+		t.Fatal("dequeue on drained queue should return ok=false")
+	}
+}
+
+func TestMessageQueue_RequeueFront(t *testing.T) {
+	q := newMessageQueue()
+	q.enqueue("s", "a")
+	q.enqueue("s", "b")
+	// Pop "a", then push it back to the front; "a" must come out before "b".
+	a, _ := q.dequeue("s")
+	q.requeueFront("s", a)
+	got, _ := q.dequeue("s")
+	if got != "a" {
+		t.Fatalf("after requeueFront, dequeue = %q want %q", got, "a")
+	}
+	got2, _ := q.dequeue("s")
+	if got2 != "b" {
+		t.Fatalf("next dequeue = %q want %q", got2, "b")
+	}
+}
+
+func TestMessageQueue_IsolatedPerSession(t *testing.T) {
+	q := newMessageQueue()
+	q.enqueue("s1", "one")
+	q.enqueue("s2", "two")
+	if got, _ := q.dequeue("s1"); got != "one" {
+		t.Fatalf("s1 = %q want one", got)
+	}
+	if got, _ := q.dequeue("s2"); got != "two" {
+		t.Fatalf("s2 = %q want two", got)
+	}
+	if q.peek("s1") != 0 || q.peek("s2") != 0 {
+		t.Fatal("both sessions should be drained")
+	}
+}
+
+func TestMessageQueue_Concurrent(t *testing.T) {
+	q := newMessageQueue()
+	const n = maxQueuedPerSession // stay under the cap so every enqueue lands
+	var wg sync.WaitGroup
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			q.enqueue("s", "m")
+		}(i)
+	}
+	wg.Wait()
+	if q.peek("s") != n {
+		t.Fatalf("peek = %d want %d (all enqueues must be counted)", q.peek("s"), n)
+	}
+	seen := 0
+	for {
+		if _, ok := q.dequeue("s"); !ok {
+			break
+		}
+		seen++
+	}
+	if seen != n {
+		t.Fatalf("drained %d want %d", seen, n)
+	}
+}
+
+func TestMessageQueue_CapsOverflow(t *testing.T) {
+	q := newMessageQueue()
+	for i := 0; i < maxQueuedPerSession; i++ {
+		if !q.enqueue("s", "m") {
+			t.Fatalf("enqueue #%d within cap should succeed", i)
+		}
+	}
+	if q.enqueue("s", "overflow") {
+		t.Fatal("enqueue past the cap should return false (dropped)")
+	}
+	if got := q.peek("s"); got != maxQueuedPerSession {
+		t.Fatalf("peek = %d want %d (overflow must not append)", got, maxQueuedPerSession)
+	}
+}
+
+// drainQueued on an empty queue must be a no-op: it returns immediately and
+// never touches the gate (so the session stays free for the next turn).
+func TestDrainQueued_NoOpOnEmpty(t *testing.T) {
+	a := &agent{gate: newTurnGate(), queue: newMessageQueue()}
+	a.drainQueued(context.Background(), "s")
+	if !a.gate.acquire("s", 0) {
+		t.Fatal("gate should be free after a no-op drain (drain must not hold it)")
+	}
+	a.gate.release("s")
+}
+
+// With a queued message but the gate held by another turn, drainQueued must
+// re-queue the message and return WITHOUT running a turn (no store/provider → a
+// real run would panic). This is the "never stack" property: a busy gate
+// defers to the holder's own release-drain.
+func TestDrainQueued_RequeuesWhenBusy(t *testing.T) {
+	prev := drainAcquireWait
+	drainAcquireWait = 10 * time.Millisecond
+	t.Cleanup(func() { drainAcquireWait = prev })
+
+	a := &agent{gate: newTurnGate(), queue: newMessageQueue()}
+	if !a.gate.acquire("s", 0) {
+		t.Fatal("precondition: hold the gate")
+	}
+	a.queue.enqueue("s", "queued-msg")
+
+	done := make(chan struct{})
+	go func() {
+		a.drainQueued(context.Background(), "s") // must not panic; must requeue
+		close(done)
+	}()
+	select {
+	case <-done:
+	case <-time.After(time.Second):
+		t.Fatal("drainQueued did not return promptly while the gate was busy")
+	}
+	if got := a.queue.peek("s"); got != 1 {
+		t.Fatalf("message should be re-queued while busy; peek = %d want 1", got)
+	}
+	a.gate.release("s")
+}

cmd/nomos/retrycap.go

@@ -0,0 +1,170 @@
+package main
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"strings"
+	"sync"
+)
+
+// maxRunRetries is the per-turn cap on identical failing `run` tool calls.
+// After this many failures with the same (target, command) key, the agent
+// loop refuses to dispatch the call again and instead surfaces a directive
+// to investigate *why* (ps/strace/lsof) or escalate to the operator.
+//
+// Background: session 1e9c7691 (2026-07-18) retried the same
+// `chown :10000 /mnt/media_local && chmod 2775 …` ~20 times across direct
+// runs, SSH-hop-via-hubris, wrapping in a shell script, and bare `echo test`
+// sanity checks. Each retry piled up another zombie process on the target
+// (knfsd was holding a kernel lock on the exported directory). The agent
+// only investigated *why* after the operator explicitly asked
+// "the command just keeps running?" — see
+// plans/2026-07-18-session-review-three-sessions.md P0.1.
+const maxRunRetries = 3
+
+// runRetryTracker deduplicates failing `run` calls within a single chat
+// turn (chatWith invocation). It is NOT persisted across turns — the cap
+// is per-turn, so a fresh turn after the operator responds can retry once
+// more. The intent is to break a tight retry loop within one turn, not to
+// permanently block the agent from ever attempting the operation again.
+//
+// Threading: the agent loop is single-goroutine per turn, but the tracker
+// is guarded by a mutex so future callers (e.g. concurrent tool dispatch)
+// stay safe. The mutex is uncontended on the current hot path.
+type runRetryTracker struct {
+	mu     sync.Mutex
+	counts map[string]int
+}
+
+func newRunRetryTracker() *runRetryTracker {
+	return &runRetryTracker{counts: make(map[string]int)}
+}
+
+// runFailureKey is the dedup key for "this is the same command against the
+// same target." Whitespace is collapsed so trivial reformatting
+// (newlines vs spaces, trailing whitespace) doesn't escape the cap. The
+// purpose field is intentionally NOT part of the key: the agent often
+// rephrases purpose between retries while issuing the same command.
+func runFailureKey(target, command string) string {
+	collapsed := strings.Join(strings.Fields(command), " ")
+	target = strings.TrimSpace(target)
+	h := sha256.Sum256([]byte(target + "\x00" + collapsed))
+	return hex.EncodeToString(h[:])
+}
+
+// recordFailure increments the failure count for the given key and returns
+// the new count. The caller should check `count > maxRunRetries` BEFORE
+// dispatching to decide whether to skip the call.
+func (r *runRetryTracker) recordFailure(key string) int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.counts[key]++
+	return r.counts[key]
+}
+
+// failures returns the current failure count for a key (0 if unseen).
+func (r *runRetryTracker) failures(key string) int {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.counts[key]
+}
+
+// isRunFailure reports whether a `run` tool call's outcome should count
+// as a failure for retry-cap purposes. A call counts as failed when:
+//   - the dispatch itself errored (callErr != nil), OR
+//   - the result text starts with "run on <target>: ERROR" — the
+//     shape classifyAndGate/sshExec produce when SSH or the command fails.
+//
+// Approvals queued ("requires approval") do NOT count as failures: they
+// are pending operator action, not a command execution failure. A read
+// of the existing code paths (classifyAndGate in internal/mcp/server.go)
+// confirms the "ERROR" prefix is the stable failure signature for `run`.
+//
+// The resultText parameter is the MCP tool's RAW text result (not JSON-
+// re-encoded): when classifyAndGate returns a textResult like
+// "run on host:strong: ERROR ...", the MCP client unwraps it back to a
+// plain Go string (see mcpClient.callTool). The caller should pass that
+// raw string, not json.Marshal's output (which would quote-wrap it).
+func isRunFailure(toolName string, resultText string, callErr error) bool {
+	if callErr != nil {
+		return true
+	}
+	if toolName != "run" {
+		return false
+	}
+	// "run on host:strong: ERROR ..." or "run on lxc:caddy: ERROR ..."
+	// Both shapes start with "run on ".
+	if !strings.HasPrefix(resultText, "run on ") {
+		return false
+	}
+	return strings.Contains(resultText, ": ERROR")
+}
+
+// runResultText extracts the raw text from a `run` tool's result value as
+// returned by mcpClient.callTool — typically a Go string, but may also be
+// a []string (multi-content result) or other JSON-decoded shape. Returns
+// "" for shapes we don't recognize. Used by the retry-cap path so
+// isRunFailure receives the un-quoted text form (see its doc comment).
+func runResultText(result any) string {
+	switch v := result.(type) {
+	case string:
+		return v
+	case []string:
+		if len(v) > 0 {
+			return v[0]
+		}
+	case []any:
+		var b strings.Builder
+		for _, e := range v {
+			if s, ok := e.(string); ok {
+				b.WriteString(s)
+			}
+		}
+		return b.String()
+	}
+	return ""
+}
+
+// runRetryDirective is the synthetic tool result returned to the model
+// when the retry cap is hit, in place of dispatching the call again. It
+// directs the agent to investigate *why* the command keeps failing before
+// retrying, or to surface the blocker to the operator.
+func runRetryDirective(target, command string, failures int) string {
+	return "Refused: this `run` against " + target + " has failed " +
+		itoa(failures) + " times this turn — retry cap hit. The command:\n  " +
+		command + "\nis almost certainly blocked by something on the target " +
+		"(a hung process, a kernel lock, an unexported FS, a stuck SSH " +
+		"session, …) — NOT a transient gateway issue. Do NOT retry with " +
+		"different routing or quoting. Instead, BEFORE calling `run` again, " +
+		"investigate *why* the command hangs: e.g. `ps aux | grep <cmd>`, " +
+		"`lsof <path>`, `strace -f -p <pid>` or `strace -f <cmd>`, " +
+		"`mount | grep <path>`, `dmesg | tail`. If you find a structural " +
+		"blocker (e.g. a kernel lock on an exported NFS directory → " +
+		"unexport → mutate → re-export), say so to the operator and fix it " +
+		"with a different command. If you genuinely cannot diagnose, " +
+		"surface the blocker to the operator with what you've tried — do " +
+		"not just retry the same command."
+}
+
+// itoa is a tiny strconv.Itoa to keep this file dependency-free.
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var buf [20]byte
+	i := len(buf)
+	for n > 0 {
+		i--
+		buf[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		buf[i] = '-'
+	}
+	return string(buf[i:])
+}

cmd/nomos/retrycap_test.go

@@ -0,0 +1,129 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestRunFailureKey_StableAcrossWhitespace(t *testing.T) {
+	cases := []struct{ a, b string }{
+		{"chown :10000 /mnt/media_local && chmod 2775 /mnt/media_local",
+			"chown :10000 /mnt/media_local  &&  chmod 2775 /mnt/media_local"},
+		{"chown :10000 /mnt/media_local\n&& chmod 2775 /mnt/media_local",
+			"chown :10000 /mnt/media_local && chmod 2775 /mnt/media_local"},
+		{"chown :10000 /mnt/media_local && chmod 2775 /mnt/media_local ",
+			"  chown :10000 /mnt/media_local && chmod 2775 /mnt/media_local"},
+	}
+	for i, c := range cases {
+		ka := runFailureKey("host:strong", c.a)
+		kb := runFailureKey("host:strong", c.b)
+		if ka != kb {
+			t.Errorf("case %d: keys differ for whitespace-equivalent commands:\n  a=%q\n  b=%q", i, c.a, c.b)
+		}
+	}
+}
+
+func TestRunFailureKey_DiffersByTarget(t *testing.T) {
+	a := runFailureKey("host:strong", "echo hi")
+	b := runFailureKey("host:hubris", "echo hi")
+	if a == b {
+		t.Error("keys should differ when target differs")
+	}
+}
+
+func TestRunFailureKey_DiffersByCommand(t *testing.T) {
+	a := runFailureKey("host:strong", "echo hi")
+	b := runFailureKey("host:strong", "echo bye")
+	if a == b {
+		t.Error("keys should differ when command differs")
+	}
+}
+
+func TestRunRetryTracker_CountsAndCaps(t *testing.T) {
+	r := newRunRetryTracker()
+	key := runFailureKey("host:strong", "chown :10000 /mnt/media_local")
+	for i := 1; i <= maxRunRetries; i++ {
+		if got := r.recordFailure(key); got != i {
+			t.Errorf("recordFailure #%d = %d, want %d", i, got, i)
+		}
+	}
+	// At the cap, failures() should report maxRunRetries, and the next
+	// identical call should be refused by the agent loop (failures() >=
+	// maxRunRetries).
+	if got := r.failures(key); got != maxRunRetries {
+		t.Errorf("failures = %d, want %d", got, maxRunRetries)
+	}
+	if r.failures(key) < maxRunRetries {
+		t.Errorf("cap should be enforced at maxRunRetries=%d", maxRunRetries)
+	}
+}
+
+func TestRunRetryTracker_PerTurnIsolation(t *testing.T) {
+	// Different keys don't interfere.
+	r := newRunRetryTracker()
+	k1 := runFailureKey("host:strong", "echo a")
+	k2 := runFailureKey("host:strong", "echo b")
+	r.recordFailure(k1)
+	r.recordFailure(k1)
+	if got := r.failures(k2); got != 0 {
+		t.Errorf("k2 failures = %d, want 0 (keys are isolated)", got)
+	}
+}
+
+func TestIsRunFailure(t *testing.T) {
+	cases := []struct {
+		desc    string
+		tool    string
+		result  string
+		callErr error
+		want    bool
+	}{
+		{"run with ERROR prefix", "run", "run on host:strong: ERROR ssh: signal: killed", nil, true},
+		{"run with exit error", "run", "run on lxc:caddy: ERROR exit status 1", nil, true},
+		{"run success (read-only auto)", "run", "run on host:strong (read_only, auto): hello", nil, false},
+		{"run success (assent window)", "run", "run on host:strong (config_mutation, auto via assent window): done", nil, false},
+		{"run queued for approval", "run", "run on host:strong requires approval (risk: config_mutation) — execution 019f4930 queued. Present the command and purpose to the operator and wait; do not re-request.", nil, false},
+		{"non-run tool", "get_entity", "lxc list result", nil, false},
+		{"callErr set (dispatch failure)", "run", "", errFake{}, true},
+		{"callErr set on non-run tool", "get_entity", "some result", errFake{}, true}, // callErr trumps name
+	}
+	for i, c := range cases {
+		got := isRunFailure(c.tool, c.result, c.callErr)
+		if got != c.want {
+			t.Errorf("case %d (%s): isRunFailure = %v, want %v", i, c.desc, got, c.want)
+		}
+	}
+}
+
+type errFake struct{}
+
+func (errFake) Error() string { return "fake dispatch error" }
+
+func TestRunRetryDirective_Content(t *testing.T) {
+	d := runRetryDirective("host:strong", "chown :10000 /mnt/media_local", 3)
+	for _, want := range []string{
+		"Refused:",
+		"host:strong",
+		"3 times",
+		"retry cap hit",
+		"Do NOT retry",
+		"strace",
+		"ps aux",
+		"lsof",
+		"surface the blocker",
+	} {
+		if !strings.Contains(d, want) {
+			t.Errorf("directive missing %q; got:\n%s", want, d)
+		}
+	}
+}
+
+func TestItoa(t *testing.T) {
+	cases := map[int]string{0: "0", 1: "1", 9: "9", 10: "10", 42: "42",
+		100: "100", -1: "-1", -42: "-42"}
+	for in, want := range cases {
+		if got := itoa(in); got != want {
+			t.Errorf("itoa(%d) = %q, want %q", in, got, want)
+		}
+	}
+}

cmd/nomos/store_test.go

@@ -0,0 +1,511 @@
+package main
+
+// Integration tests against a real Postgres, mirroring
+// internal/db/integration_test.go's pattern: guarded by
+// OIKOS_TEST_DATABASE_URL (skipped when unset), throwaway database per run,
+// full migrations applied, dropped on cleanup. Run with:
+//
+//   docker compose up -d postgres
+//   OIKOS_TEST_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disable" go test ./cmd/nomos/
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"math/rand"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/dtoro/oikos/internal/db"
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5"
+)
+
+// newTestStore creates a throwaway, fully-migrated database and returns a
+// *store connected to it, cleaned up (including a matching task:<session>
+// entity type in the ontology, needed by createTaskEntity/proposePlan tests)
+// via t.Cleanup.
+func newTestStore(t *testing.T) *store {
+	t.Helper()
+	baseURL := os.Getenv("OIKOS_TEST_DATABASE_URL")
+	if baseURL == "" {
+		t.Skip("OIKOS_TEST_DATABASE_URL not set — skipping integration test")
+	}
+	ctx := context.Background()
+
+	admin, err := pgx.Connect(ctx, baseURL)
+	if err != nil {
+		t.Fatalf("connect admin: %v", err)
+	}
+	dbName := fmt.Sprintf("oikos_test_nomos_%08x", rand.Int63())
+	if _, err := admin.Exec(ctx, "CREATE DATABASE "+dbName); err != nil {
+		admin.Close(ctx)
+		t.Fatalf("create test db: %v", err)
+	}
+	admin.Close(ctx)
+
+	testURL := swapTestDatabase(baseURL, dbName)
+	pool, err := db.New(ctx, testURL)
+	if err != nil {
+		t.Fatalf("connect test db: %v", err)
+	}
+	t.Cleanup(func() {
+		pool.Close()
+		admin, err := pgx.Connect(ctx, baseURL)
+		if err == nil {
+			admin.Exec(ctx, "DROP DATABASE IF EXISTS "+dbName+" WITH (FORCE)")
+			admin.Close(ctx)
+		}
+	})
+	if err := pool.Migrate(ctx); err != nil {
+		t.Fatalf("migrate: %v", err)
+	}
+
+	// session_plan_steps/session_questions tests don't need the ontology
+	// seed, but createTaskEntity's INSERT INTO entities (type='task') has an
+	// FK to entity_types — seed the minimal rows it needs directly rather
+	// than pulling in the full seeds/ontology.yaml ingest path.
+	if _, err := pool.Exec(ctx, `
+		INSERT INTO entity_types (name, domain, layer) VALUES ('entity', 'meta', 'meta')
+		ON CONFLICT DO NOTHING;
+		INSERT INTO entity_types (name, parent_type, domain, layer) VALUES ('task', 'entity', 'cognition', 'cognition')
+		ON CONFLICT DO NOTHING;`); err != nil {
+		t.Fatalf("seed minimal ontology: %v", err)
+	}
+
+	return &store{pool: pool.Pool}
+}
+
+func swapTestDatabase(url, dbName string) string {
+	qi := strings.Index(url, "?")
+	params, base := "", url
+	if qi >= 0 {
+		params = url[qi:]
+		base = url[:qi]
+	}
+	si := strings.LastIndex(base, "/")
+	return base[:si+1] + dbName + params
+}
+
+// TestGetRecentMessages_Truncation is the concrete proof for fix A2 of
+// plans/2026-07-11-nomos-agent-code-review.md: chatWith used to replay a
+// session's ENTIRE history on every turn with no bound. getRecentMessages
+// caps that; this test checks both sides — under the limit, nothing is
+// dropped and truncated=false; over it, only the most recent `limit` come
+// back, in chronological order, with truncated=true.
+func TestGetRecentMessages_Truncation(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	sess, err := s.createSession(ctx, "history window test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+
+	const total = 35
+	const limit = 30
+	for i := 0; i < total; i++ {
+		role := "user"
+		if i%2 == 1 {
+			role = "assistant"
+		}
+		body := fmt.Appendf(nil, `{"role":%q,"text":"msg-%d"}`, role, i)
+		if err := s.saveMessage(ctx, sess.ID, role, body); err != nil {
+			t.Fatalf("saveMessage %d: %v", i, err)
+		}
+	}
+
+	msgs, truncated, err := s.getRecentMessages(ctx, sess.ID, limit)
+	if err != nil {
+		t.Fatalf("getRecentMessages: %v", err)
+	}
+	if !truncated {
+		t.Errorf("truncated = false, want true (%d messages > limit %d)", total, limit)
+	}
+	if len(msgs) != limit {
+		t.Fatalf("got %d messages, want %d", len(msgs), limit)
+	}
+	// Chronological order: the oldest of the RETAINED messages should be the
+	// (total-limit)-th one saved (msg-5, since msg-0..4 were dropped), and
+	// the last should be the most recently saved (msg-34).
+	wantFirst := fmt.Sprintf("msg-%d", total-limit)
+	wantLast := fmt.Sprintf("msg-%d", total-1)
+	if got := extractText(msgs[0].Content); got != wantFirst {
+		t.Errorf("first retained message = %q, want %q", got, wantFirst)
+	}
+	if got := extractText(msgs[len(msgs)-1].Content); got != wantLast {
+		t.Errorf("last retained message = %q, want %q", got, wantLast)
+	}
+
+	// Under the limit: nothing dropped.
+	sess2, err := s.createSession(ctx, "small session")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	for i := 0; i < 5; i++ {
+		body := fmt.Appendf(nil, `{"role":"user","text":"msg-%d"}`, i)
+		if err := s.saveMessage(ctx, sess2.ID, "user", body); err != nil {
+			t.Fatalf("saveMessage: %v", err)
+		}
+	}
+	msgs2, truncated2, err := s.getRecentMessages(ctx, sess2.ID, limit)
+	if err != nil {
+		t.Fatalf("getRecentMessages (small): %v", err)
+	}
+	if truncated2 {
+		t.Errorf("truncated = true for a 5-message session under a %d limit, want false", limit)
+	}
+	if len(msgs2) != 5 {
+		t.Errorf("got %d messages, want 5", len(msgs2))
+	}
+}
+
+// TestProposePlan_RefuseInFlight is the concrete proof for the plan-drift
+// fix (2026-07-14, "plan added twice in the sidebar"): proposePlan must
+// REPLACE the step list only while every existing step is still 'pending'
+// (a genuine pre-execution revision), and REFUSE the call once any step has
+// started. The prior append-mode safety net (commit 5384499) preserved
+// history but duplicated the plan in the sidebar when the agent re-proposed
+// on "proceed". Refusing is the correct default — the agent must advance
+// with update_plan_step + run.
+func TestProposePlan_RefuseInFlight(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	sess, err := s.createSession(ctx, "plan refuse test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+
+	// First call: no steps exist yet — must persist as-is (replace mode,
+	// trivially: nothing to replace).
+	out1, err := s.proposePlan(ctx, sess.ID, []planStepInput{{Title: "Step A"}})
+	if err != nil {
+		t.Fatalf("proposePlan #1: %v", err)
+	}
+	if len(out1) != 1 || out1[0]["seq"] != 1 {
+		t.Fatalf("proposePlan #1 = %+v, want one step at seq 1", out1)
+	}
+	if out1[0]["generation"] != 1 {
+		t.Fatalf("proposePlan #1 generation = %v, want 1", out1[0]["generation"])
+	}
+
+	// Mark step 1 as started.
+	if err := s.updatePlanStep(ctx, sess.ID, 1, "running", "", ""); err != nil {
+		t.Fatalf("updatePlanStep: %v", err)
+	}
+
+	// Second call, simulating a model that re-proposes mid-flight (the
+	// operator-reported "proceed" bug): since step 1 has left 'pending',
+	// this MUST refuse with errPlanInFlight, not append or replace.
+	_, err = s.proposePlan(ctx, sess.ID, []planStepInput{{Title: "Step B"}})
+	if !errors.Is(err, errPlanInFlight) {
+		t.Fatalf("proposePlan #2: err = %v, want errPlanInFlight (refuse mid-flight re-proposal)", err)
+	}
+
+	// The original step 1 must be untouched — not erased, not appended to.
+	steps, err := s.getPlanSteps(ctx, sess.ID, false)
+	if err != nil {
+		t.Fatalf("getPlanSteps: %v", err)
+	}
+	if len(steps) != 1 {
+		t.Fatalf("got %d persisted steps, want 1 (refused call must not mutate the plan)", len(steps))
+	}
+	if steps[0].Title != "Step A" || steps[0].Status != "running" {
+		t.Errorf("step 1 = %+v, want Step A still running (refused call must not touch it)", steps[0])
+	}
+
+	// Third call BEFORE anything runs on a fresh session: every step is
+	// still pending, so this must REPLACE (mark the prior plan `replaced`),
+	// not refuse. The new plan becomes generation 2.
+	sess2, err := s.createSession(ctx, "plan replace test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	if _, err := s.proposePlan(ctx, sess2.ID, []planStepInput{{Title: "Original"}}); err != nil {
+		t.Fatalf("proposePlan (initial): %v", err)
+	}
+	if _, err := s.proposePlan(ctx, sess2.ID, []planStepInput{{Title: "Revised"}}); err != nil {
+		t.Fatalf("proposePlan (revise before execution): %v", err)
+	}
+	// Default (current generation) view: only the revised step.
+	revisedSteps, err := s.getPlanSteps(ctx, sess2.ID, false)
+	if err != nil {
+		t.Fatalf("getPlanSteps: %v", err)
+	}
+	if len(revisedSteps) != 1 || revisedSteps[0].Title != "Revised" {
+		t.Fatalf("got %+v, want a single 'Revised' step (current-generation view)", revisedSteps)
+	}
+	if revisedSteps[0].Seq != 1 {
+		t.Fatalf("revised step seq = %d, want 1 (seq is generation-relative, resets to 1..N)", revisedSteps[0].Seq)
+	}
+	if revisedSteps[0].Generation != 2 {
+		t.Fatalf("revised step generation = %d, want 2 (prior pending plan is replaced, not deleted, so the counter increments)", revisedSteps[0].Generation)
+	}
+	// all=true audit view: both generations, the original marked `replaced`.
+	allSteps, err := s.getPlanSteps(ctx, sess2.ID, true)
+	if err != nil {
+		t.Fatalf("getPlanSteps(all): %v", err)
+	}
+	if len(allSteps) != 2 {
+		t.Fatalf("all=true got %d steps, want 2 (Original replaced gen1 + Revised gen2)", len(allSteps))
+	}
+	if allSteps[0].Title != "Original" || allSteps[0].Status != "replaced" || allSteps[0].Generation != 1 {
+		t.Errorf("gen1 step = %+v, want Original/replaced/gen1", allSteps[0])
+	}
+	if allSteps[1].Title != "Revised" || allSteps[1].Generation != 2 || allSteps[1].Seq != 1 {
+		t.Errorf("gen2 step = %+v, want Revised/gen2/seq1", allSteps[1])
+	}
+}
+
+// TestUpdatePlanStep_GenerationRelative is the P0.1 regression proof: after a
+// re-plan, update_plan_step(seq=N) — using the 1-based number the model
+// naturally carries — must address the CURRENT generation and never resurrect
+// a superseded generation's `replaced` row. Before the fix, seq was globally
+// increasing across generations, so seq=1 after a re-plan flipped the gen-1
+// `replaced` step back to `running`/`done` while the real gen-2 work went
+// unrecorded.
+func TestUpdatePlanStep_GenerationRelative(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	sess, err := s.createSession(ctx, "gen-relative seq test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	// Generation 1: two steps.
+	if _, err := s.proposePlan(ctx, sess.ID, []planStepInput{{Title: "A"}, {Title: "B"}}); err != nil {
+		t.Fatalf("proposePlan #1: %v", err)
+	}
+	// Re-plan: setGoal marks the gen-1 plan `replaced`, proposePlan starts gen 2.
+	if err := s.setGoal(ctx, sess.ID, "follow-up sub-task"); err != nil {
+		t.Fatalf("setGoal: %v", err)
+	}
+	if _, err := s.proposePlan(ctx, sess.ID, []planStepInput{{Title: "C"}, {Title: "D"}}); err != nil {
+		t.Fatalf("proposePlan #2: %v", err)
+	}
+
+	// The model addresses the new plan with 1-based seq. seq=1 must hit
+	// gen-2 "C", leaving gen-1 "A" (replaced) untouched.
+	if err := s.updatePlanStep(ctx, sess.ID, 1, "running", "", ""); err != nil {
+		t.Fatalf("updatePlanStep(seq=1, running): %v", err)
+	}
+	if err := s.updatePlanStep(ctx, sess.ID, 1, "done", "", ""); err != nil {
+		t.Fatalf("updatePlanStep(seq=1, done): %v", err)
+	}
+
+	all, err := s.getPlanSteps(ctx, sess.ID, true)
+	if err != nil {
+		t.Fatalf("getPlanSteps(all): %v", err)
+	}
+	byTitle := map[string]planStep{}
+	for _, st := range all {
+		byTitle[st.Title] = st
+	}
+	// gen-1 steps stay `replaced` — NOT resurrected to running/done.
+	if byTitle["A"].Status != "replaced" || byTitle["A"].Generation != 1 {
+		t.Errorf("A = %+v, want replaced/gen1 (a superseded row must never be touched)", byTitle["A"])
+	}
+	if byTitle["B"].Status != "replaced" || byTitle["B"].Generation != 1 {
+		t.Errorf("B = %+v, want replaced/gen1", byTitle["B"])
+	}
+	// gen-2 seq=1 advanced; seq=2 untouched.
+	if byTitle["C"].Status != "done" || byTitle["C"].Generation != 2 || byTitle["C"].Seq != 1 {
+		t.Errorf("C = %+v, want done/gen2/seq1 (the 1-based update must address the current generation)", byTitle["C"])
+	}
+	if byTitle["D"].Status != "pending" || byTitle["D"].Seq != 2 {
+		t.Errorf("D = %+v, want pending/seq2", byTitle["D"])
+	}
+
+	// Out-of-range seq must be refused (no current-gen step there).
+	if err := s.updatePlanStep(ctx, sess.ID, 99, "running", "", ""); !errors.Is(err, errPlanStepNotFound) {
+		t.Fatalf("updatePlanStep(seq=99) err = %v, want errPlanStepNotFound", err)
+	}
+}
+
+// TestCompleteTask_AutoCloseEmitsEvents is the P1.1 regression proof:
+// completeTask's bulk auto-close of in-flight steps must emit one
+// plan.step.finished event per closed step (so the live panel converges
+// instead of freezing on "running" after the task completes) and must stamp
+// started_at so no closed step is left un-timestamped (P0.1 fix 5).
+func TestCompleteTask_AutoCloseEmitsEvents(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	sess, err := s.createSession(ctx, "auto-close events test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	if _, err := s.proposePlan(ctx, sess.ID, []planStepInput{{Title: "A"}, {Title: "B"}}); err != nil {
+		t.Fatalf("proposePlan: %v", err)
+	}
+	// A is running, B still pending at completion time.
+	if err := s.updatePlanStep(ctx, sess.ID, 1, "running", "", ""); err != nil {
+		t.Fatalf("updatePlanStep(1, running): %v", err)
+	}
+	if err := s.completeTask(ctx, sess.ID, "success", "done"); err != nil {
+		t.Fatalf("completeTask: %v", err)
+	}
+
+	// Every auto-closed step should now carry both a started_at and a
+	// finished_at (no NULL-started `done` step).
+	steps, err := s.getPlanSteps(ctx, sess.ID, true)
+	if err != nil {
+		t.Fatalf("getPlanSteps: %v", err)
+	}
+	for _, st := range steps {
+		if st.Status == "done" && st.StartedAt == nil {
+			t.Errorf("step %q done but started_at is NULL (P0.1 fix 5: stamp it)", st.Title)
+		}
+	}
+
+	// Exactly two plan.step.finished events — one per closed step (A and B).
+	var finished int
+	if err := s.pool.QueryRow(ctx,
+		`SELECT COUNT(*) FROM events WHERE type = 'plan.step.finished' AND correlation_id = $1`,
+		sess.ID).Scan(&finished); err != nil {
+		t.Fatalf("count events: %v", err)
+	}
+	if finished != 2 {
+		t.Fatalf("plan.step.finished events = %d, want 2 (one per auto-closed step)", finished)
+	}
+}
+
+// TestHadDiscoveryAndWriteback is the store-level proof for D.1 (refuse
+// complete_task when discovery ran without writeback). hadDiscovery must
+// report true only after a successful `run` call; hadEntityWriteback must
+// report true only after a successful update_entity_attributes or
+// create_relationship call. The D.1 gate in tasks.go combines these: refuse
+// success when hadDiscovery && !hadEntityWriteback.
+func TestHadDiscoveryAndWriteback(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	sess, err := s.createSession(ctx, "discovery test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+
+	// Before any tool calls: no discovery, no writeback.
+	if s.hadDiscovery(ctx, sess.ID) {
+		t.Fatal("hadDiscovery = true before any tool calls, want false")
+	}
+	if s.hadEntityWriteback(ctx, sess.ID) {
+		t.Fatal("hadEntityWriteback = true before any tool calls, want false")
+	}
+
+	// A `run` call (discovery) — should set hadDiscovery, not hadEntityWriteback.
+	agentID := uuid.New()
+	s.logActivity(ctx, agentID, sess.ID, "run", nil, "", "uptime output", 100, true, "corr-1", 0)
+	if !s.hadDiscovery(ctx, sess.ID) {
+		t.Fatal("hadDiscovery = false after a successful run call, want true")
+	}
+	if s.hadEntityWriteback(ctx, sess.ID) {
+		t.Fatal("hadEntityWriteback = true after only a run call, want false")
+	}
+
+	// A failed run call should NOT count as discovery (no facts learned).
+	sess2, err := s.createSession(ctx, "failed discovery test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	s.logActivity(ctx, agentID, sess2.ID, "run", nil, "", "ssh timeout", 100, false, "corr-2", 0)
+	if s.hadDiscovery(ctx, sess2.ID) {
+		t.Fatal("hadDiscovery = true after a failed run call, want false (no facts learned)")
+	}
+
+	// A get_entity call should NOT count as discovery (DB lookup, not live state).
+	sess3, err := s.createSession(ctx, "lookup test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	s.logActivity(ctx, agentID, sess3.ID, "get_entity", nil, "", "entity row", 10, true, "corr-3", 0)
+	if s.hadDiscovery(ctx, sess3.ID) {
+		t.Fatal("hadDiscovery = true after get_entity, want false (DB lookups are not discovery)")
+	}
+
+	// update_entity_attributes sets hadEntityWriteback.
+	sess4, err := s.createSession(ctx, "writeback test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+	s.logActivity(ctx, agentID, sess4.ID, "update_entity_attributes", nil, "", "ok", 10, true, "corr-4", 0)
+	if !s.hadEntityWriteback(ctx, sess4.ID) {
+		t.Fatal("hadEntityWriteback = false after update_entity_attributes, want true")
+	}
+	// And the discovery+writeback combination (the conv3 scenario).
+	s.logActivity(ctx, agentID, sess4.ID, "run", nil, "", "apt-get update output", 100, true, "corr-5", 0)
+	if !s.hadDiscovery(ctx, sess4.ID) {
+		t.Fatal("hadDiscovery = false after run+writeback, want true")
+	}
+	if !s.hadEntityWriteback(ctx, sess4.ID) {
+		t.Fatal("hadEntityWriteback = false after run+writeback, want true")
+	}
+}
+
+// TestSetGoal_SupersessionEvent is the store-level proof for P1.4 from
+// plans/2026-07-18-session-review-three-sessions.md: when setGoal is called
+// and a non-empty prior goal already exists with a DIFFERENT value, a
+// task.superseded event must be emitted (so the audit trail records the
+// pivot — the row's goal column will be overwritten, losing the prior intent
+// without this event). When the goal is identical OR no prior goal exists,
+// no supersession event is emitted.
+//
+// Background: session 55927f0a had two set_goal calls; the first was
+// implicitly abandoned when the operator said "lets just keep ludo-library
+// then." Without the event, the prior goal silently disappeared.
+func TestSetGoal_SupersededEvent(t *testing.T) {
+	s := newTestStore(t)
+	ctx := context.Background()
+
+	sess, err := s.createSession(ctx, "goal pivot test")
+	if err != nil {
+		t.Fatalf("createSession: %v", err)
+	}
+
+	// First set_goal — no prior, no supersession event expected.
+	if err := s.setGoal(ctx, sess.ID, "Fix sabnzbd download folder to use ludo-lvm"); err != nil {
+		t.Fatalf("setGoal #1: %v", err)
+	}
+	if n := countEvents(ctx, s, sess.ID, "task.superseded"); n != 0 {
+		t.Errorf("after first set_goal: %d task.superseded events, want 0", n)
+	}
+
+	// Second set_goal with a DIFFERENT goal — supersession event expected.
+	if err := s.setGoal(ctx, sess.ID, "Add NFS export of ludo-lvm to ZimaOS"); err != nil {
+		t.Fatalf("setGoal #2: %v", err)
+	}
+	if n := countEvents(ctx, s, sess.ID, "task.superseded"); n != 1 {
+		t.Errorf("after second set_goal with a different goal: %d task.superseded events, want 1", n)
+	}
+
+	// Third set_goal with the SAME goal as the second — no new supersession
+	// event (idempotent: same goal is a no-op, not a pivot).
+	if err := s.setGoal(ctx, sess.ID, "Add NFS export of ludo-lvm to ZimaOS"); err != nil {
+		t.Fatalf("setGoal #3: %v", err)
+	}
+	if n := countEvents(ctx, s, sess.ID, "task.superseded"); n != 1 {
+		t.Errorf("after third set_goal with same goal as second: %d task.superseded events, want 1 (no new pivot)", n)
+	}
+
+	// The session's current goal must be the latest one set.
+	got, err := s.getSession(ctx, sess.ID)
+	if err != nil {
+		t.Fatalf("getSession: %v", err)
+	}
+	if got.Goal != "Add NFS export of ludo-lvm to ZimaOS" {
+		t.Errorf("session goal = %q, want the second (latest) goal", got.Goal)
+	}
+}
+
+// countEvents counts observability events of the given type correlated to
+// the given session. Used by TestSetGoal_SupersededEvent to assert the
+// task.superseded audit-trail signal was emitted.
+func countEvents(ctx context.Context, s *store, sessionID, eventType string) int {
+	var n int
+	s.pool.QueryRow(ctx,
+		`SELECT COUNT(*) FROM events WHERE correlation_id = $1 AND type = $2`,
+		sessionID, eventType).Scan(&n)
+	return n
+}

cmd/nomos/tasks.go

@@ -0,0 +1,508 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log/slog"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// Task tools are nomos-LOCAL, not MCP tools. They are session-scoped, and the
+// shared MCP server (api:8090/mcp) has no session id — so these are handled
+// in-process by nomos, which knows the session/task and holds the store.
+// buildTools appends these to the model's tool list; the agent loop routes a
+// call whose name isTaskTool to handleTaskTool instead of the MCP client.
+//
+// Phase 3 ships complete_task; set_goal / propose_plan / update_plan_step /
+// ask_operator land in later phases through the same mechanism.
+
+func taskToolDefs() []toolDef {
+	return []toolDef{
+		{
+			Name: "set_goal",
+			Description: "State the goal of this task in one sentence, as early as you " +
+				"can. This is what the task is trying to achieve (e.g. 'Deploy TypeType " +
+				"as an LXC on strong'); it heads the task on the board and the context " +
+				"panel. Call it once you understand what the operator wants.",
+			InputSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"goal": map[string]any{"type": "string", "description": "The task's goal, one sentence."},
+				},
+				"required": []string{"goal"},
+			},
+		},
+		{
+			Name: "propose_plan",
+			Description: "Propose the full ordered plan for this task. Call ONCE, before any " +
+				"execution, with EVERY step end-to-end (not one step at a time). FIRST step: " +
+				"research (prior knowledge, relations, blast radius). If your plan runs `run` " +
+				"against any target, include a LAST step: write back " +
+				"(update_entity_attributes + create_relationship + upsert_knowledge) — if you " +
+				"omit it, one is auto-appended. After this call: STOP and wait for operator " +
+				"approval (approval vocabulary: approved, yes, go, proceed, continue, ok, " +
+				"go ahead). Once a step has started (running/done/...), this tool REFUSES " +
+				"further calls — advance with update_plan_step + run instead. Re-propose only " +
+				"if the operator explicitly asks you to revise the whole plan. complete_task " +
+				"with outcome=success is REFUSED if you ran `run` but didn't call " +
+				"update_entity_attributes/create_relationship — write back before completing.",
+			InputSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"steps": map[string]any{
+						"type":        "array",
+						"description": "Ordered steps, first to last.",
+						"items": map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"title":       map[string]any{"type": "string", "description": "Short imperative step title (e.g. 'Create the LXC')."},
+								"detail":      map[string]any{"type": "string", "description": "Optional one-line detail."},
+								"target_slug": map[string]any{"type": "string", "description": "Optional entity slug this step acts on (e.g. lxc:typetype)."},
+							},
+							"required": []string{"title"},
+						},
+					},
+				},
+				"required": []string{"steps"},
+			},
+		},
+		{
+			Name: "update_plan_step",
+			Description: "Advance a plan step as you work it. Set status to 'running' when " +
+				"you start it (pass execution_id if the step queued a gated action, so " +
+				"the board can auto-close it when that finishes), then 'done' / 'failed' " +
+				"/ 'skipped' / 'blocked' when it resolves. Keeps the operator's progress " +
+				"view honest.",
+			InputSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"seq":          map[string]any{"type": "integer", "description": "1-based step number from propose_plan."},
+					"status":       map[string]any{"type": "string", "enum": []string{"running", "done", "failed", "skipped", "blocked"}, "description": "New status for the step."},
+					"execution_id": map[string]any{"type": "string", "description": "Optional execution UUID this step is running, so it auto-closes on completion."},
+				},
+				"required": []string{"seq", "status"},
+			},
+		},
+		{
+			Name: "ask_operator",
+			Description: "Ask the operator a question when you hit a real decision only " +
+				"they can make — an ambiguous target, a trade-off, missing information, " +
+				"or a destructive choice not already approved. This pins a structured " +
+				"question card in the context panel (with your options and the entities " +
+				"involved) and PAUSES the task until they answer; their answer resumes " +
+				"you automatically. Do NOT use it for things you can determine yourself " +
+				"with tools — only for genuine decisions.",
+			InputSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"prompt": map[string]any{"type": "string", "description": "The question, stated plainly."},
+					"why":    map[string]any{"type": "string", "description": "Why you're asking / what's at stake."},
+					"options": map[string]any{
+						"type": "array", "items": map[string]any{"type": "string"},
+						"description": "The choices, if it's a pick-one decision.",
+					},
+					"context_entities": map[string]any{
+						"type": "array", "items": map[string]any{"type": "string"},
+						"description": "Entity slugs relevant to the decision (shown as chips).",
+					},
+				},
+				"required": []string{"prompt"},
+			},
+		},
+		{
+			Name: "complete_task",
+			Description: "Mark the current task finished. Call this once the goal is " +
+				"verified done — or when you've genuinely failed or only partially " +
+				"succeeded. Sets the task's outcome and a one-line summary shown on the " +
+				"task board. Record what you learned with upsert_knowledge BEFORE " +
+				"completing, so future tasks on the same entities benefit.",
+			InputSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"outcome": map[string]any{
+						"type":        "string",
+						"enum":        []string{"success", "failure", "partial"},
+						"description": "Did the task achieve its goal?",
+					},
+					"summary": map[string]any{
+						"type":        "string",
+						"description": "One line describing the result (shown on the task card).",
+					},
+				},
+				"required": []string{"outcome", "summary"},
+			},
+		},
+	}
+}
+
+// toInt coerces a JSON tool-arg number (float64 after unmarshal) to int.
+func toInt(v any) int {
+	switch n := v.(type) {
+	case float64:
+		return int(n)
+	case int:
+		return n
+	default:
+		return 0
+	}
+}
+
+// toStringSlice coerces a JSON tool-arg array to a non-empty []string.
+func toStringSlice(v any) []string {
+	arr, ok := v.([]any)
+	if !ok {
+		return nil
+	}
+	out := make([]string, 0, len(arr))
+	for _, e := range arr {
+		if s, ok := e.(string); ok && strings.TrimSpace(s) != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
+// handleTaskTool executes a nomos-local task tool. Returns (result, true) if it
+// handled the call, or (nil, false) if name is not a local task tool (so the
+// caller forwards it to the MCP client).
+func (a *agent) handleTaskTool(ctx context.Context, sessionID, name string, args map[string]any) (any, bool) {
+	switch name {
+	case "set_goal":
+		goal, _ := args["goal"].(string)
+		if strings.TrimSpace(goal) == "" {
+			return "error: set_goal needs a goal", true
+		}
+		if err := a.store.setGoal(ctx, sessionID, goal); err != nil {
+			return fmt.Sprintf("error setting goal: %v", err), true
+		}
+		// P1: the plan window is NOT opened here. Opening it on set_goal
+		// meant any config_mutation `run` auto-executed with zero operator
+		// approval, before a plan was even proposed (let alone approved) —
+		// a safety regression confirmed live in session d0d562e0. The
+		// window is now opened only when the operator approves a plan
+		// (chat-assent grant or explicit approval in agent.go), which is
+		// what the SOUL.md "approve the plan, not each step" model actually
+		// describes. set_goal records the goal + flips status to executing
+		// and nothing more.
+		response := "Goal set: " + goal + ". NEXT: pre-plan with read-only tools (search_knowledge, get_entity, list_lxcs, get_relations), then propose_plan (mandatory — even read-only tasks need a one-step plan; the run handler refuses without one). After propose_plan: if all steps are read-only, execute immediately (no approval needed). If any step is config_mutation/destructive, stop and wait for operator approval."
+		// P1.3 (2026-07-20): surface prior partial/failed sessions for the
+		// same problem so the agent can pick up the thread instead of
+		// rediscovering it. Three rclone sessions (a51e2086, 8acea2e3,
+		// cb8c8a4a) all bounced off the classifier because each new session
+		// started from scratch. The agent gets a hint with the prior
+		// goal + summary; if it looks related, search_knowledge or open
+		// the prior session's transcript (GET /sessions/{id}) before
+		// re-planning. See plans/2026-07-20-session-review-ten-sessions.md.
+		prior, _ := a.store.recentPartialSessions(ctx, sessionID, 24*time.Hour)
+		if len(prior) > 0 {
+			var b strings.Builder
+			b.WriteString("\n\nNOTE — recent unfinished sessions (last 24h, outcome=partial/failed):")
+			for i, p := range prior {
+				if i >= 5 {
+					b.WriteString(fmt.Sprintf("\n  ...and %d more", len(prior)-5))
+					break
+				}
+				sum := p.Summary
+				if sum == "" {
+					sum = "(no summary)"
+				}
+				if len(sum) > 200 {
+					sum = sum[:200] + "..."
+				}
+				b.WriteString(fmt.Sprintf("\n  - %s (sid %s, outcome=%s): %s",
+					p.Goal, p.ID[:8], p.Outcome, sum))
+			}
+			b.WriteString("\nIf any of these looks like the same problem, search_knowledge for the prior investigation or read it via GET /sessions/{id} before re-planning — don't rediscover what was already learned.")
+			response += b.String()
+		}
+		return response, true
+
+	case "propose_plan":
+		raw, _ := args["steps"].([]any)
+		var steps []planStepInput
+		for _, r := range raw {
+			m, ok := r.(map[string]any)
+			if !ok {
+				continue
+			}
+			title, _ := m["title"].(string)
+			if strings.TrimSpace(title) == "" {
+				continue
+			}
+			detail, _ := m["detail"].(string)
+			target, _ := m["target_slug"].(string)
+			steps = append(steps, planStepInput{Title: title, Detail: detail, TargetSlug: target})
+		}
+		if len(steps) == 0 {
+			return "error: propose_plan needs at least one step with a title", true
+		}
+		// D.2: auto-append a writeback step if the agent didn't include one.
+		// The agent consistently writes vague last steps ("record findings")
+		// and then skips update_entity_attributes entirely (the #1 cause of
+		// knowledge-graph drift). Appending an explicit writeback step makes
+		// the seq-order enforcement (5.6) require it to be completed last,
+		// and D.1's complete_task gate enforces the actual calls. Together
+		// they close the loop structurally — neither relies on the agent
+		// reading SOUL.md. The match is broadened past the literal tool
+		// names so a natural-language step ("Write back: update entity
+		// attributes…") isn't doubled by an auto-appended duplicate (P1.2).
+		hasWritebackStep := false
+		for _, st := range steps {
+			t := strings.ToLower(st.Title + " " + st.Detail)
+			if strings.Contains(t, "update_entity_attributes") ||
+				strings.Contains(t, "create_relationship") ||
+				strings.Contains(t, "upsert_knowledge") ||
+				strings.Contains(t, "write back") ||
+				strings.Contains(t, "writeback") {
+				hasWritebackStep = true
+				break
+			}
+		}
+		appendedNote := ""
+		if !hasWritebackStep {
+			steps = append(steps, planStepInput{
+				Title:  "Write back: update_entity_attributes + create_relationship + upsert_knowledge",
+				Detail: "Call update_entity_attributes for every entity you ran against (versions, states, counts, timestamps). Call create_relationship for any edge you discovered. Then upsert_knowledge about the affected entities (pass `about` as an array).",
+			})
+			appendedNote = fmt.Sprintf(" (appended a writeback step — your plan didn't include one; step %d)", len(steps))
+		}
+		persisted, err := a.store.proposePlan(ctx, sessionID, steps)
+		if err != nil {
+			if errors.Is(err, errPlanInFlight) {
+				// The plan is already in flight — refuse the re-proposal.
+				// The agent must advance the existing plan with
+				// update_plan_step + run. This is the structural fix for
+				// the "plan added twice" sidebar drift the operator
+				// reported: instead of appending (which duplicated) or
+				// wiping (which lost progress), we refuse and direct.
+				return "Plan already in flight — refusing duplicate proposal. Steps exist and at least one has started (running/done/...). To advance: call update_plan_step(seq=K, status=\"running\") then run(...) for step K's target, then update_plan_step(seq=K, status=\"done\"). Do not call propose_plan again. Re-propose only if the operator explicitly asks you to revise the whole plan (the session is reopened on a follow-up — prior steps are marked `replaced` and a fresh generation is started), and say so in your reply before calling it.", true
+			}
+			return fmt.Sprintf("error proposing plan: %v", err), true
+		}
+		// The writeback step is now always present (D.2 auto-appends it if
+		// the agent forgot), so the old advisory nudge is replaced by the
+		// structural gate: D.1 refuses complete_task without the actual
+		// update_entity_attributes/create_relationship calls. Enumerate the
+		// step seqs so the model knows exactly which numbers to address with
+		// update_plan_step (seq is 1-based within this plan — the addressing
+		// key, not a global counter).
+		var seqs strings.Builder
+		for i, p := range persisted {
+			if i > 0 {
+				seqs.WriteString("; ")
+			}
+			title := fmt.Sprint(p["title"])
+			fmt.Fprintf(&seqs, "%v=%s", p["seq"], title)
+		}
+		result := fmt.Sprintf("Plan set (%d steps): %s.%s Address them with update_plan_step(seq=N). If all steps are read-only, execute now — call update_plan_step(running) + run for each step, no approval needed. If any step is config_mutation/destructive, STOP and wait for operator approval (\"approved\", \"yes\", \"go\", \"proceed\", \"continue\", \"ok\", \"go ahead\"). Do not call propose_plan again.", len(persisted), seqs.String(), appendedNote)
+		return result, true
+
+	case "update_plan_step":
+		seq := toInt(args["seq"])
+		status, _ := args["status"].(string)
+		execID, _ := args["execution_id"].(string)
+		if seq <= 0 || status == "" {
+			return "error: update_plan_step needs seq (>=1) and status", true
+		}
+		reason, _ := args["replaced_reason"].(string)
+		if err := a.store.updatePlanStep(ctx, sessionID, seq, status, execID, reason); err != nil {
+			if errors.Is(err, errPlanStepNotFound) {
+				// The seq doesn't address a step in the CURRENT plan — most
+				// often a stale 1-based number the model carried across a
+				// re-plan, or an out-of-range seq. seq is generation-relative
+				// (1..N within the latest propose_plan), so a superseded
+				// generation's row is never touched (P0.1 fix 3). Direct the
+				// model instead of silently no-op'ing.
+				return fmt.Sprintf("Step %d is not in the current plan. seq is 1-based within your latest propose_plan (a re-plan resets it to 1..N, so an old step number no longer applies). The plan was not changed. Re-address with the correct 1-based seq, or if you've lost track, re-read the plan.", seq), true
+			}
+			return fmt.Sprintf("error updating step %d: %v", seq, err), true
+		}
+		return fmt.Sprintf("Step %d → %s. (Advance with update_plan_step + run; do not re-propose.)", seq, status), true
+
+	case "ask_operator":
+		prompt, _ := args["prompt"].(string)
+		if strings.TrimSpace(prompt) == "" {
+			return "error: ask_operator needs a prompt", true
+		}
+		qctx := map[string]any{}
+		if why, _ := args["why"].(string); strings.TrimSpace(why) != "" {
+			qctx["why"] = why
+		}
+		if opts := toStringSlice(args["options"]); len(opts) > 0 {
+			qctx["options"] = opts
+		}
+		if ents := toStringSlice(args["context_entities"]); len(ents) > 0 {
+			qctx["entities"] = ents
+		}
+		if _, err := a.store.askOperator(ctx, sessionID, prompt, qctx); err != nil {
+			return fmt.Sprintf("error posting question: %v", err), true
+		}
+		return "Question posted to the operator; the task is paused until they answer. " +
+			"Do not continue or call more tools — end your turn now and wait for their answer.", true
+
+	case "complete_task":
+		outcome, _ := args["outcome"].(string)
+		summary, _ := args["summary"].(string)
+		switch outcome {
+		case "":
+			outcome = "success" // no outcome given at all — assume success, the common case
+		case "success", "failure", "partial":
+			// valid, use as-is
+		default:
+			// The tool schema declares an enum, but a weaker model (or a
+			// typo) can still send anything — an unrecognized value used to
+			// persist as-is, silently, with only "failure" special-cased
+			// (store.completeTask derives status='failed' from it; anything
+			// else became status='done' regardless of what the value
+			// actually said). Default to "partial" rather than silently
+			// treating an unrecognized value as "success" — safer to
+			// under-claim than over-claim a task's outcome.
+			slog.Warn("nomos: complete_task got an unrecognized outcome, defaulting to partial",
+				"session", sessionID, "outcome", outcome)
+			outcome = "partial"
+		}
+		// D.1: refuse success when discovery ran but no writeback followed.
+		// The prior advisory warning (below) was ignorable — the agent
+		// saw it and ended the task anyway. This gate fires BEFORE
+		// completeTask runs, so the session stays in 'executing' state
+		// and the agent must call update_entity_attributes/create_relationship
+		// then retry complete_task. Only blocks `success`; an explicit
+		// `failure` or `partial` is allowed through (the agent is
+		// acknowledging it didn't finish — no reason to force writeback).
+		if outcome == "success" && a.store.hadDiscovery(ctx, sessionID) && !a.store.hadEntityWriteback(ctx, sessionID) {
+			return "Refused: this session ran `run` against live targets (discovery) but did not call update_entity_attributes or create_relationship to persist what you learned. The knowledge graph will drift if you complete without writeback. Call update_entity_attributes for each entity you ran against (versions, states, counts, timestamps), and create_relationship for any edge you discovered, then call complete_task again. Outcome is held at 'executing' until you do.", true
+		}
+		// D.2: refuse success when the goal mentions a reachability/uptime
+		// check but no verification was done. The agent can't claim "X is
+		// reachable" based on a shell command alone — the proxy (Caddy) can
+		// return 200 for a terminal page (ttyd) or fallback while the actual
+		// dashboard is still down. Must call ping_service or run a successful
+		// curl before claiming success.
+		if outcome == "success" && a.store.hadDiscovery(ctx, sessionID) {
+			goal := a.store.sessionGoal(ctx, sessionID)
+			if mentionsReachability(goal) && !a.store.hadRecentVerification(ctx, sessionID) {
+				return "Refused: the goal involves a reachability or uptime check (\"make X reachable\", \"get X up\", etc.), but no ping_service call or successful curl/HTTP request against the target was detected. Caddy can return 200 for a terminal or fallback page while the actual service is still down — you must verify the service itself, not just the proxy. Call ping_service(target) or run a curl against the actual service URL, then call complete_task again. Outcome held until verified.", true
+			}
+		}
+		if err := a.store.completeTask(ctx, sessionID, outcome, summary); err != nil {
+			if errors.Is(err, errTaskAlreadyComplete) {
+				return "Task is already complete. Do not call complete_task again. If the operator pointed out a UI/sidebar inconsistency, fix it with update_plan_step (reconcile step states) or summarize the panel in your reply — do not re-execute the work.", true
+			}
+			return fmt.Sprintf("error completing task: %v", err), true
+		}
+		result := fmt.Sprintf("Task marked %s: %s", outcome, summary)
+		if !a.store.hadEntityWriteback(ctx, sessionID) {
+			result += "\n\n⚠️ No entity attributes or relationships were updated in this session. Call update_entity_attributes and create_relationship to persist what you learned about entities before the next session starts from scratch."
+		}
+		return result, true
+	default:
+		return nil, false
+	}
+}
+
+// reachabilityPatterns matches goal text that involves making something
+// reachable/accessible/working. Used by complete_task to surface a soft
+// warning when the session goal was about reachability but no verification
+// occurred before marking success.
+var reachabilityPatterns = []*regexp.Regexp{
+	regexp.MustCompile(`(?i)https?://[^\s]+`),
+	regexp.MustCompile(`(?i)\.hubris\.net\w+`),
+	regexp.MustCompile(`(?i)(un)?reachable`),
+	regexp.MustCompile(`(?i)(not?\s+)?(accessible|reachable|responding|resolving)`),
+	regexp.MustCompile(`(?i)diagnose\s+why`),
+	regexp.MustCompile(`(?i)(fix|restore|bring\s+back).*(accessible|reachable|online)`),
+}
+
+func mentionsReachability(goal string) bool {
+	for _, p := range reachabilityPatterns {
+		if p.MatchString(goal) {
+			return true
+		}
+	}
+	return false
+}
+
+// autoCompleteTrivialTask is the case-1 fix from
+// plans/2026-07-11-task-completion-safety-net.md: a session that never
+// called set_goal never framed itself as a structured task, so a turn that
+// ends with a plain-text answer and no further tool calls IS the task
+// ending — but the model consistently skips complete_task for exactly this
+// case (confirmed live: 43/50 production sessions were a single trivial
+// Q&A exchange, none of which ever reached a terminal status). Rather than
+// leave agent_sessions.status stuck at its creation-time default forever,
+// close it out mechanically here: no judgment call needed, since SOUL.md
+// already treats a one-shot answered question as done by definition.
+func (a *agent) autoCompleteTrivialTask(ctx context.Context, sessionID, responseText string) {
+	summary := strings.TrimSpace(responseText)
+	summary = strings.SplitN(summary, "\n", 2)[0] // first line only — the board shows one line
+	const maxLen = 120
+	if len(summary) > maxLen {
+		summary = summary[:maxLen] + "…"
+	}
+	if summary == "" {
+		summary = "Answered without further action needed."
+	}
+	if err := a.store.completeTask(ctx, sessionID, "success", summary); err != nil {
+		slog.Error("nomos: auto-complete trivial task failed", "session", sessionID, "error", err)
+	}
+}
+
+// autoCompleteIfPlanDone is the structural safety net for "the agent did the
+// work but forgot to call complete_task" — the #1 remaining model reliability
+// gap after D.1's writeback gate. After a turn ends, if the session has a goal,
+// the agent never called complete_task this turn, and either (a) all plan
+// steps are terminal OR (b) the agent did discovery (ran `run`), auto-complete.
+// Path (b) catches the common case where the agent skips update_plan_step
+// bookkeeping but still does the actual work — the D.1 gate already enforces
+// writeback before `complete_task`, so if the agent forgot to complete at all,
+// we close it out mechanically. If writeback happened → success; if not →
+// partial (honest: work was done but knowledge graph wasn't updated).
+func (a *agent) autoCompleteIfPlanDone(ctx context.Context, sessionID, responseText string) {
+	if a.store == nil || sessionID == "" || sessionID == "ephemeral" {
+		return
+	}
+	sess, err := a.store.getSession(ctx, sessionID)
+	if err != nil || sess.Status != "executing" {
+		return
+	}
+	// Don't auto-complete if there are pending approvals — the agent is
+	// blocked waiting for the operator, not done. Auto-completing here
+	// would close the session and the operator's approval would land on a
+	// dead task. Confirmed in eval: agent hits P5 approval gate, turn
+	// ends, auto-complete fires incorrectly because the approval-queue
+	// `run` responses were logged as success=true in agent_activity.
+	if a.store.hasPendingApprovals(ctx, sessionID) {
+		return
+	}
+	discovery := a.store.hadDiscovery(ctx, sessionID)
+	writeback := a.store.hadEntityWriteback(ctx, sessionID)
+	// (a) all plan steps terminal, OR (b) agent did discovery (ran `run`).
+	shouldComplete := a.store.allPlanStepsTerminal(ctx, sessionID)
+	if !shouldComplete && discovery {
+		shouldComplete = true
+	}
+	if !shouldComplete {
+		return
+	}
+	outcome := "success"
+	if discovery && !writeback {
+		outcome = "partial" // honest: work done, knowledge graph not updated
+	}
+	summary := strings.TrimSpace(responseText)
+	summary = strings.SplitN(summary, "\n", 2)[0]
+	const maxLen = 120
+	if len(summary) > maxLen {
+		summary = summary[:maxLen] + "…"
+	}
+	if summary == "" {
+		summary = "All plan steps completed."
+	}
+	if err := a.store.completeTask(ctx, sessionID, outcome, summary); err != nil {
+		slog.Error("nomos: auto-complete plan-done task failed", "session", sessionID, "error", err)
+	} else {
+		slog.Info("nomos: auto-completed task — agent didn't call complete_task", "session", sessionID, "outcome", outcome)
+	}
+}

cmd/nomos/turngate.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"sync"
+	"time"
+)
+
+// turnGate enforces at most one in-flight agent turn per session.
+//
+// Why this exists (plan 2026-08-03, F1): handleChat runs a turn in the HTTP
+// request goroutine, and every "resume" path (the empty-message reconnect,
+// the auto-continuation worker, the idle sweep, answer-question, the /resume
+// endpoint) launches ANOTHER goroutine running a full turn. Nothing prevented
+// two turns for the SAME session at once, so a network blip that triggered a
+// reconnect would spawn a duplicate resumeSession while the original turn was
+// still alive — their tool calls interleaved on the wire and in the persisted
+// transcript, which is the root cause behind the "parallel/nesting/sequence
+// is off" and "task didn't end / flaky" reports.
+//
+// Model: one permit (buffered-1 channel seeded with a single token) per
+// session id. Acquiring consumes the token; releasing puts it back.
+//   - Background/best-effort callers (resumeSession and everything it backs)
+//     use a non-blocking acquire and SKIP when busy — a duplicate nudge while a
+//     turn is already running adds nothing, and the continuation/idle tickers
+//     will retry on their own.
+//   - The live chat path (an operator message) waits briefly for a finishing
+//     background turn, then bails with an actionable error if still busy — see
+//     handleChat.
+//
+// The permits map grows one entry per session id seen. For this single-agent
+// homelab process that set is small and bounded by real sessions; cleanup is
+// intentionally omitted (a sweep would race with acquire/release and the
+// memory is negligible).
+type turnGate struct {
+	mu      sync.Mutex
+	permits map[string]chan struct{}
+}
+
+func newTurnGate() *turnGate {
+	return &turnGate{permits: make(map[string]chan struct{})}
+}
+
+// permit returns the single token-channel for sessionID, creating and seeding
+// it on first use. Creation is guarded so two concurrent first-callers for the
+// same id share one channel.
+func (g *turnGate) permit(sessionID string) chan struct{} {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	ch, ok := g.permits[sessionID]
+	if !ok {
+		ch = make(chan struct{}, 1)
+		ch <- struct{}{}
+		g.permits[sessionID] = ch
+	}
+	return ch
+}
+
+// acquire takes the session's permit. With wait <= 0 it is non-blocking
+// (returns false immediately if a turn is active). With wait > 0 it blocks up
+// to wait for the permit, returning false on timeout. Every true return MUST
+// be paired with exactly one release.
+func (g *turnGate) acquire(sessionID string, wait time.Duration) bool {
+	ch := g.permit(sessionID)
+	if wait <= 0 {
+		select {
+		case <-ch:
+			return true
+		default:
+			return false
+		}
+	}
+	t := time.NewTimer(wait)
+	defer t.Stop()
+	select {
+	case <-ch:
+		return true
+	case <-t.C:
+		return false
+	}
+}
+
+// release returns the session's permit. Idempotent: a release with no matching
+// acquire (or a double release) is a no-op rather than a blocking send.
+func (g *turnGate) release(sessionID string) {
+	ch := g.permit(sessionID)
+	select {
+	case ch <- struct{}{}:
+	default:
+	}
+}

cmd/nomos/turngate_test.go

@@ -0,0 +1,114 @@
+package main
+
+import (
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func TestTurnGate_NonBlockingSkipsWhenBusy(t *testing.T) {
+	g := newTurnGate()
+	if !g.acquire("s1", 0) {
+		t.Fatal("first non-blocking acquire should succeed on a free session")
+	}
+	// A second non-blocking acquire (a background resume) must skip, not queue.
+	if g.acquire("s1", 0) {
+		t.Fatal("second non-blocking acquire should fail while a turn is active")
+	}
+	// A different session is independent.
+	if !g.acquire("s2", 0) {
+		t.Fatal("acquire on a different session should succeed")
+	}
+	g.release("s2")
+	g.release("s1")
+	// After release, the session is free again.
+	if !g.acquire("s1", 0) {
+		t.Fatal("acquire should succeed again after release")
+	}
+	g.release("s1")
+}
+
+func TestTurnGate_BlockingAcquireWaitsForRelease(t *testing.T) {
+	g := newTurnGate()
+	if !g.acquire("s1", 0) {
+		t.Fatal("first acquire should succeed")
+	}
+
+	got := make(chan bool, 1)
+	go func() { got <- g.acquire("s1", 2*time.Second) }()
+
+	select {
+	case <-got:
+		t.Fatal("blocking acquire should wait, not return before release")
+	case <-time.After(50 * time.Millisecond):
+		// expected: still waiting
+	}
+
+	g.release("s1")
+	select {
+	case ok := <-got:
+		if !ok {
+			t.Fatal("blocking acquire should succeed after release")
+		}
+	case <-time.After(time.Second):
+		t.Fatal("blocking acquire did not return after release")
+	}
+	g.release("s1")
+}
+
+func TestTurnGate_BlockingAcquireTimesOut(t *testing.T) {
+	g := newTurnGate()
+	g.acquire("s1", 0) // hold the permit
+
+	start := time.Now()
+	if g.acquire("s1", 60*time.Millisecond) {
+		t.Fatal("acquire should time out while permit is held")
+	}
+	if elapsed := time.Since(start); elapsed < 50*time.Millisecond {
+		t.Fatalf("acquire returned too fast (%v); expected to wait ~60ms", elapsed)
+	}
+	g.release("s1")
+}
+
+// TestTurnGate_SingleFlightConcurrent is the core F1 guarantee: many concurrent
+// background acquirers on the SAME session, exactly one runs at a time. This is
+// the property that prevents two turns interleaving tool calls.
+func TestTurnGate_SingleFlightConcurrent(t *testing.T) {
+	g := newTurnGate()
+	const n = 50
+	var inFlight, maxInFlight int64
+	var runs int64
+	var wg sync.WaitGroup
+	wg.Add(n)
+	start := make(chan struct{})
+	for i := 0; i < n; i++ {
+		go func() {
+			defer wg.Done()
+			<-start
+			if !g.acquire("shared", 0) { // background-style: skip if busy
+				return
+			}
+			defer g.release("shared")
+			cur := atomic.AddInt64(&inFlight, 1)
+			for {
+				m := atomic.LoadInt64(&maxInFlight)
+				if cur <= m || atomic.CompareAndSwapInt64(&maxInFlight, m, cur) {
+					break
+				}
+			}
+			atomic.AddInt64(&runs, 1)
+			time.Sleep(2 * time.Millisecond)
+			atomic.AddInt64(&inFlight, -1)
+		}()
+	}
+	close(start)
+	wg.Wait()
+
+	if maxInFlight != 1 {
+		t.Fatalf("max in-flight turns = %d, want 1 (turns must not overlap)", maxInFlight)
+	}
+	if runs == 0 {
+		t.Fatal("expected at least one turn to run")
+	}
+}

cmd/oikos/main.go

@@ -1,17 +1,14 @@
 package main
 
 import (
-	"bytes"
 	"context"
 	"fmt"
-	"io"
 	"log/slog"
 	"net/http"
 	"os"
 	"os/signal"
 	"strings"
 	"syscall"
-	"time"
 
 	"github.com/dtoro/oikos/internal/config"
 	"github.com/dtoro/oikos/internal/db"
@@ -21,50 +18,9 @@ import (
 	"github.com/dtoro/oikos/internal/observability"
 	"github.com/dtoro/oikos/internal/scheduler"
 	"github.com/dtoro/oikos/internal/secrets"
-	"github.com/dtoro/oikos/web"
 	"github.com/jackc/pgx/v5"
 )
 
-// uiHandler serves the control-room SPA from assets embedded at build time
-// (web/embed.go), with SPA fallback to index.html. Requests arrive as /ui/*;
-// the /ui prefix is stripped to index into the embedded dist/ tree. Files are
-// written via http.ServeContent (not http.FileServer) to avoid its
-// index.html -> "./" canonical redirect, which loops for /ui/.
-func uiHandler() http.Handler {
-	dist, err := web.DistFS()
-	if err != nil {
-		slog.Warn("ui: embedded assets unavailable", "error", err)
-		return http.NotFoundHandler()
-	}
-	serve := func(w http.ResponseWriter, r *http.Request, name string) bool {
-		f, err := dist.Open(name)
-		if err != nil {
-			return false
-		}
-		defer f.Close()
-		data, err := io.ReadAll(f)
-		if err != nil {
-			return false
-		}
-		http.ServeContent(w, r, name, time.Time{}, bytes.NewReader(data))
-		return true
-	}
-	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		name := strings.TrimPrefix(strings.TrimPrefix(r.URL.Path, "/ui"), "/")
-		if name == "" {
-			name = "index.html"
-		}
-		if serve(w, r, name) {
-			return
-		}
-		// SPA fallback: serve index.html for unknown client-side routes.
-		if serve(w, r, "index.html") {
-			return
-		}
-		http.NotFound(w, r)
-	})
-}
-
 var schedulerRunner = scheduler.RunnerForMain()
 var notifierRunner = notifier.RunnerForMain()
 
@@ -129,7 +85,7 @@ func main() {
 		go notifierRunner(ctx, pool, cfg)
 
 		slog.Info("all: starting api with scheduler + notifier in background")
-		if err := httpapi.ListenAndServe(ctx, pool, cfg, uiHandler()); err != nil {
+		if err := httpapi.ListenAndServe(ctx, pool, cfg); err != nil {
 			slog.Error("api failed", "error", err)
 			os.Exit(1)
 		}
@@ -308,7 +264,7 @@ func runAPI(ctx context.Context, cfg config.Config) error {
 		return fmt.Errorf("migrations: %w", err)
 	}
 
-	err = httpapi.ListenAndServe(ctx, pool, cfg, uiHandler())
+	err = httpapi.ListenAndServe(ctx, pool, cfg)
 	if err == http.ErrServerClosed {
 		return nil
 	}

cmd/webhook/main.go

@@ -0,0 +1,96 @@
+package main
+
+import (
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/exec"
+	"time"
+
+	"github.com/dtoro/oikos/internal/safego"
+)
+
+func main() {
+	port := os.Getenv("WEBHOOK_LISTEN")
+	if port == "" {
+		port = ":9797"
+	}
+
+	secret := os.Getenv("WEBHOOK_HMAC_SECRET")
+	if secret == "" {
+		fmt.Fprintln(os.Stderr, "WEBHOOK_HMAC_SECRET must be set")
+		os.Exit(1)
+	}
+
+	repoDir := os.Getenv("WEBHOOK_REPO_DIR")
+	if repoDir == "" {
+		repoDir = os.Getenv("HOME") + "/Projects/oikos"
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/deploy", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", 405)
+			return
+		}
+
+		body, err := io.ReadAll(r.Body)
+		if err != nil {
+			http.Error(w, "read body failed", 400)
+			return
+		}
+
+		sigHex := r.Header.Get("X-Hub-Signature-256")
+		if sigHex == "" {
+			http.Error(w, "missing signature", 401)
+			return
+		}
+
+		mac := hmac.New(sha256.New, []byte(secret))
+		mac.Write(body)
+		expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
+
+		if !hmac.Equal([]byte(sigHex), []byte(expected)) {
+			slog.Warn("webhook: invalid signature")
+			http.Error(w, "invalid signature", 401)
+			return
+		}
+
+		slog.Info("webhook: deploy triggered")
+		w.WriteHeader(http.StatusAccepted)
+		w.Write([]byte(`{"status":"deploy started"}`))
+
+		safego.Go("webhook:deploy", func() {
+			cmd := exec.Command(repoDir + "/scripts/deploy.sh")
+			cmd.Dir = repoDir
+			cmd.Env = append(os.Environ(),
+				"REPO_DIR="+repoDir,
+				"PROFILE=full",
+			)
+			cmd.Stdout = os.Stdout
+			cmd.Stderr = os.Stderr
+			start := time.Now()
+			if err := cmd.Run(); err != nil {
+				slog.Error("webhook: deploy failed", "error", err, "duration", time.Since(start))
+				return
+			}
+			slog.Info("webhook: deploy succeeded", "duration", time.Since(start))
+		})
+	})
+
+	mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(200)
+		w.Write([]byte("ok"))
+	})
+
+	slog.Info("webhook: listening", "port", port)
+	if err := http.ListenAndServe(port, mux); err != nil {
+		slog.Error("webhook: serve failed", "error", err)
+		os.Exit(1)
+	}
+}

compose/caddy/Caddyfile.oikos

@@ -1,35 +1,59 @@
-# Caddy reverse-proxy snippet for Oikos — Phase 6 cutover
-# Lives in dtoro/caddy-conf repo; auto-deploys to caddy (LXC 121).
-# Replaces the old MCP server on apps/105 with the Docker stack on mac-mini.
+# Caddy reverse-proxy snippet for Oikos — Phase 6 cutover, updated for the
+# client/server split (plans/2026-07-12-wails-desktop-app.md, Phase 0).
+# Lives in dtoro/caddy-conf repo; auto-deploys to caddy (LXC 121). THIS COPY
+# IS A REFERENCE, NOT DEPLOYED FROM HERE — keep it in sync manually.
+#
+# The SPA is no longer embedded in the oikos binary; it's built and served
+# by its own container (compose/web/Dockerfile, docker-compose.yml's `web`
+# service, mac-mini:8091) rather than as static files read off local disk —
+# see that service's comment for why. Every API/MCP/agent route now requires
+# a bearer token in all cases (api's dev-open bypass was removed) —
+# non-browser clients (Wails, curl, a future mobile client) can't complete
+# Authentik's browser-session login, so those routes bypass `import
+# authentik` the same way the enrollment endpoint always has and rely on
+# api's own combinedAuth instead. See the Wails plan's "Plan review"
+# section, gap 1.
+#
+# mac-mini and the LXC subnet are routed, so these target its direct LAN IP
+# rather than the mesh (netbird) hostname.
 
-# Oikos REST API (operator) — enrollment endpoint bypasses Authentik
 oikos.hubris.network {
     tls {
         dns ionos {env.IONOS_AUTH_API_TOKEN}
     }
-    @enroll path /api/v1/clients/enroll
+    @enroll path /api/v1/clients/enroll /oidc-callback
     handle @enroll {
-        reverse_proxy <mac-mini-mesh-ip>:8090
+        reverse_proxy 192.168.178.182:8090
     }
-    # Nomos agent, same-origin for the control-room UI (EventSource/fetch can't
-    # set cross-origin auth headers). Authentik gates it; handle_path strips
-    # the /agent prefix so /agent/chat -> nomos /chat.
-    handle_path /agent/* {
-        import authentik
-        reverse_proxy <mac-mini-mesh-ip>:8092
+    # Bearer-token clients — api's combinedAuth (internal/httpapi/server.go)
+    # is the real gate for all three; Authentik would just reject non-browser
+    # callers before they ever get there. /agent/* now goes through api's own
+    # (auth'd) proxy mount rather than straight to nomos:8092, so it's
+    # covered by the same check as /api/v1/* and /mcp.
+    @api path /api/v1/* /mcp /agent/*
+    handle @api {
+        reverse_proxy 192.168.178.182:8090
     }
+    # Everything else: the static SPA shell, served by the `web` container.
+    # No sensitive data lives here — real enforcement is the bearer-token
+    # check above — Authentik is just a first line of defense against
+    # anonymous crawlers finding the bundle.
     handle {
         import authentik
-        reverse_proxy <mac-mini-mesh-ip>:8090
+        reverse_proxy 192.168.178.182:8091
     }
 }
 
-# Oikos MCP endpoint (agents) — no auth required
+# Oikos MCP endpoint (agents) — bearer token required (api's combinedAuth),
+# no separate gate here.
 mcp.hubris.network {
-    reverse_proxy <mac-mini-mesh-ip>:8090
+    reverse_proxy 192.168.178.182:8090
 }
 
-# Nomos gateway (workstation access) — formerly hermes.hubris.network
+# Nomos's own gateway (workstation access) — still has NO auth of its own
+# (C1, plans/2026-07-11-nomos-agent-code-review.md, still open). Anyone who
+# can reach this host can talk to nomos directly, bypassing api entirely.
+# Not fixed by the client/server split — tracked separately.
 nomos.hubris.network {
-    reverse_proxy <mac-mini-mesh-ip>:8092
+    reverse_proxy 192.168.178.182:8092
 }

compose/nomos/Dockerfile

@@ -19,7 +19,7 @@ COPY nomos/ /app/nomos/
 ENV NOMOS_MCP_URL=http://api:8090/mcp
 ENV NOMOS_AGENT_SLUG=agent:nomos
 ENV NOMOS_LISTEN=:8092
-ENV NOMOS_MODEL=deepseek/deepseek-v4-flash
+ENV NOMOS_MODEL=deepseek/deepseek-v4-pro
 
 EXPOSE 8092
 

compose/oikos/Dockerfile

@@ -1,14 +1,7 @@
-# Multi-stage Dockerfile for Oikos (ADR 0001: single binary)
-# Stage 1: build web UI
-FROM node:22-alpine AS ui-builder
-
-WORKDIR /web
-COPY web/package.json web/package-lock.json ./
-RUN npm ci
-COPY web/ ./
-RUN npm run build
-
-# Stage 2: build Go binary
+# Dockerfile for Oikos API server. The SPA is no longer embedded (see
+# plans/2026-07-12-wails-desktop-app.md 0.1) — it's built and deployed
+# separately as static files (see `make ui` / `make deploy-ui`).
+# Stage 1: build Go binary
 FROM golang:1.26-alpine AS builder
 
 RUN apk add --no-cache git ca-certificates
@@ -18,8 +11,6 @@ COPY go.mod go.sum ./
 RUN go mod download
 
 COPY . .
-# Bring in the built SPA so //go:embed all:dist (web/embed.go) has real assets.
-COPY --from=ui-builder /web/dist ./web/dist
 
 RUN CGO_ENABLED=0 go build -o /oikos -tags timetzdata -ldflags="-s -w" ./cmd/oikos
 
@@ -31,6 +22,5 @@ RUN apk add --no-cache ca-certificates openssh-client-default
 COPY --from=builder /oikos /oikos
 COPY --from=builder /build/seeds /seeds
 COPY --from=builder /build/migrations /migrations
-# web/dist is embedded in the binary (web/embed.go) — no runtime copy needed.
 
 ENTRYPOINT ["/oikos"]

compose/web/Caddyfile

@@ -0,0 +1,27 @@
+:80 {
+	root * /srv
+
+	# /wails/runtime.js is injected by the Wails desktop wrapper, which serves
+	# the same dist/ from its own asset handler. In a browser it does not
+	# exist, and the SPA fallback below answered it with index.html — so the
+	# browser parsed "<!doctype html>" as JavaScript and threw
+	# "SyntaxError: expected expression, got '<'" on every page load.
+	# Return a real 404 instead: the tag fails quietly, and the desktop app is
+	# unaffected because it never reaches this server.
+	handle /wails/* {
+		error 404
+	}
+
+	# Same reasoning for any other asset: a missing .js/.css/.map answered with
+	# HTML is always a confusing parse error rather than an honest 404. Only
+	# real routes should fall through to the SPA.
+	@asset path_regexp \.(js|mjs|css|map|json|png|jpg|svg|ico|woff2?)$
+	handle @asset {
+		file_server
+	}
+
+	handle {
+		file_server
+		try_files {path} /index.html
+	}
+}

compose/web/Dockerfile

@@ -0,0 +1,19 @@
+# Dockerfile for the oikos control-room SPA. Built separately from the
+# oikos binary (compose/oikos/Dockerfile) — see docker-compose.yml's `web`
+# service. The outer production Caddy (caddy-conf repo, LXC 121) handles
+# Authentik + splits /api/*, /mcp, /agent/* off to the api service; this
+# container only serves static files with SPA-fallback routing.
+
+FROM node:22-alpine AS builder
+
+WORKDIR /build/web
+COPY web/package.json web/package-lock.json ./
+RUN npm ci
+COPY VERSION ./
+COPY web/ ./
+RUN npm run build
+
+FROM caddy:2-alpine
+
+COPY --from=builder /build/web/dist /srv
+COPY compose/web/Caddyfile /etc/caddy/Caddyfile

docker-compose.yml

@@ -1,10 +1,17 @@
 # Docker Compose for Oikos development
 # Usage: docker compose up -d postgres  (just the DB)
 #        make dev                     (full dev stack)
+#
+# The SPA isn't embedded in the oikos binary (see
+# plans/2026-07-12-wails-desktop-app.md 0.1/0.6) but it IS part of this
+# stack as its own `web` service (compose/web/Dockerfile), so it deploys
+# through the same push-to-main pipeline as everything else. `npm run dev`
+# in web/ is still the fast local-iteration path.
 
 services:
   postgres:
     image: timescale/timescaledb:2.17.2-pg16
+    restart: unless-stopped
     environment:
       POSTGRES_DB: oikos
       POSTGRES_USER: oikos
@@ -51,6 +58,7 @@ services:
     build:
       context: .
       dockerfile: compose/oikos/Dockerfile
+    restart: unless-stopped
     profiles: ["dev", "full"]
     depends_on:
       seed:
@@ -60,6 +68,12 @@ services:
       OIKOS_API_LISTEN: ":8090"
       OIKOS_ENV: dev
       OIKOS_DEBUG: "true"
+      # No dev-open auth bypass (plans/2026-07-12-wails-desktop-app.md 0.4) —
+      # every request needs this token. nomos uses the same value to call
+      # back into api's /mcp and /api/v1/approvals/*/decision.
+      OIKOS_MCP_BEARER_TOKEN: ${OIKOS_MCP_BEARER_TOKEN:-dev-token}
+      OIKOS_OIDC_ISSUER: ${OIKOS_OIDC_ISSUER:-https://auth.hubris.network/application/o/oikos/}
+      OIKOS_OIDC_CLIENT_ID: ${OIKOS_OIDC_CLIENT_ID:-otkHBSueHJsYtOHstL6rn5izeGgyOsavp1qA1hod}
       OIKOS_NOMOS_AGENT_SLUG: ${OIKOS_NOMOS_AGENT_SLUG:-agent:nomos}
       NOMOS_PROXY_URL: http://nomos:8092
     volumes:
@@ -69,12 +83,25 @@ services:
     command: ["api"]
     stop_signal: SIGTERM
     stop_grace_period: 30s
+    # Exists so nomos can wait for the API to actually answer rather than just
+    # for its container to exist — see nomos's depends_on below. wget is
+    # BusyBox's, already in the alpine runtime image, so this adds no
+    # dependency. /healthz pings the DB, so "healthy" means genuinely ready.
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "-", "http://127.0.0.1:8090/healthz"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      # Migrations and seed run before this container, but the first bind can
+      # still take a moment; failures inside the start period don't count.
+      start_period: 10s
 
   # Scheduler (Phase 3) — observe loop
   scheduler:
     build:
       context: .
       dockerfile: compose/oikos/Dockerfile
+    restart: unless-stopped
     profiles: ["dev", "full"]
     depends_on:
       seed:
@@ -98,6 +125,7 @@ services:
     build:
       context: .
       dockerfile: compose/oikos/Dockerfile
+    restart: unless-stopped
     profiles: ["dev", "full"]
     depends_on:
       seed:
@@ -119,24 +147,48 @@ services:
     build:
       context: .
       dockerfile: compose/nomos/Dockerfile
+    restart: unless-stopped
     profiles: ["full"]
     depends_on:
       api:
-        condition: service_started
+        # service_started only waits for the container to exist, so nomos came
+        # up while the API was still binding :8090, failed its MCP initialize,
+        # exited 1, and crash-looped for ~25s on every single deploy. It always
+        # recovered, which is exactly why it went unnoticed. service_healthy
+        # waits for the API to actually answer.
+        condition: service_healthy
     environment:
       NOMOS_MCP_URL: http://api:8090/mcp
       NOMOS_AGENT_SLUG: agent:nomos
       OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
-      NOMOS_MODEL: ${NOMOS_MODEL:-deepseek/deepseek-v4-flash}
+      NOMOS_MODEL: ${NOMOS_MODEL:-deepseek/deepseek-v4-pro}
       DATABASE_URL: postgres://oikos:${OIKOS_DB_PASSWORD:-oikos_dev}@postgres:5432/oikos?sslmode=disable
+      # Must match api's OIKOS_MCP_BEARER_TOKEN above — api's combinedAuth
+      # rejects every request without it now (no dev-open bypass).
+      OIKOS_MCP_BEARER_TOKEN: ${OIKOS_MCP_BEARER_TOKEN:-dev-token}
     ports:
       - "8092:8092"
     stop_signal: SIGTERM
     stop_grace_period: 10s
 
+  # Control-room SPA — static build served behind Caddy. The outer
+  # production Caddy (caddy-conf repo, LXC 121) splits /api/*, /mcp,
+  # /agent/* off to api:8090 and sends everything else here; this
+  # container only serves static files with SPA-fallback routing.
+  web:
+    build:
+      context: .
+      dockerfile: compose/web/Dockerfile
+    restart: unless-stopped
+    profiles: ["dev", "full"]
+    ports:
+      - "8091:80"
+    stop_signal: SIGTERM
+
   # Redis (required by Infisical — Phase 5)
   redis:
     image: redis:7-alpine
+    restart: unless-stopped
     profiles: ["infisical", "full"]
     volumes:
       - redis-data:/data
@@ -149,6 +201,7 @@ services:
   # Infisical self-hosted (Phase 5 secrets management)
   infisical:
     image: infisical/infisical:latest
+    restart: unless-stopped
     profiles: ["infisical", "full"]
     depends_on:
       postgres:

docs/adr/0012-hermes-oikos-interactions.md

@@ -234,9 +234,33 @@ sequenceDiagram
 
 ---
 
-**2026-07-08 — renamed to Nomos.** The Hermes agent gateway was renamed to
+**2026-07-08 — renamed to Nomos.**
 Nomos (from *oikonomos*, the steward of the oikos) under the
 [Nomos resident agent plan](../../plans/2026-07-08-nomos-resident-agent.md),
+
+### Hermes MCP client setup
+
+To connect a Hermes Agent instance to oikos as a native MCP client, add to
+`~/.hermes/config.yaml`:
+
+```yaml
+mcp_servers:
+  oikos:
+    url: "https://mcp.hubris.network/mcp"
+    headers:
+      Authorization: "Bearer <OIKOS_MCP_BEARER_TOKEN>"
+    timeout: 180
+```
+
+Run `/reload-mcp` in-session or restart Hermes. Tools appear as
+`mcp__oikos__*`.
+
+**Caveat:** Hermes stores the bearer token in plaintext in `config.yaml` —
+it does not support `${VAR}` interpolation in MCP server headers. Ensure
+`security.redact_secrets: true` (default) so the token value is stripped
+from tool output and logs. File an upstream feature request at
+https://github.com/NousResearch/hermes-agent/issues for env-var
+interpolation support.
 N0 milestone. The gateway binary (`cmd/nomos`), Docker service, DB slug
 (`agent:nomos`), and all referencing docs were updated. All architectural
 principles in this ADR remain unchanged.

docs/adr/0013-signal-triggers.md

@@ -1,4 +1,7 @@
-# Signal Trigger Architecture
+# ADR 0013 — Signal trigger architecture
+
+**Status:** Accepted
+**Date:** 2026-07-08
 
 ## Overview
 

docs/adr/0014-entity-model.md

@@ -1,6 +1,6 @@
-# Oikos Entity Model — Types, Relationships & Interactions
+# ADR 0014 — Entity model: types, relationships & interactions
 
-**Status:** Adopted
+**Status:** Accepted
 **Date:** 2026-07-08
 **Scope:** Full inventory of every entity type, relationship, state machine, and
 cognition pipeline — with clear markers for what is **code-real** vs **schema-only**.

docs/adr/0015-api-bearer-auth-client-server-split.md

@@ -0,0 +1,62 @@
+# ADR 0015 — Bearer-token auth for every route + client/server split
+
+Status: accepted (2026-07-12) · Plan: plans/2026-07-12-wails-desktop-app.md, Phase 0
+
+## Context
+The control-room SPA was embedded in the `oikos` binary (`go:embed`,
+ADR 0001) and served at `/ui/*`. `combinedAuth` (`internal/httpapi/server.go`)
+opened a dev-open bypass — no credential required at all — whenever
+`OIKOS_ENV=dev` and no static token/OIDC issuer was configured. That was
+true not just in local dev but in the actual mac-mini production deploy:
+`docker-compose.yml`'s `api` service hardcoded `OIKOS_ENV: dev` with no
+token set, so every route (`/api/v1/*`, `/mcp`, and an `/agent` reverse-proxy
+mount to nomos that had never been wrapped in `combinedAuth` at all) was
+reachable unauthenticated from anywhere on the mesh/LAN. A planned Wails
+desktop client and any future non-browser client can't rely on same-origin
+requests or a dev-open bypass; they need the SPA to be a standalone,
+CORS-capable client that authenticates over HTTP like any other caller.
+
+## Decision
+- Delete the SPA embed (`web/embed.go`, the `/ui/*` routes). `web/` is a
+  standalone static build, deployed separately (`make ui` / `make
+  deploy-ui`), served at `/` by Caddy with SPA fallback.
+- Remove the dev-open bypass entirely. Every route requires a valid
+  static bearer token (`OIKOS_API_TOKEN` / `OIKOS_MCP_BEARER_TOKEN`) or an
+  OIDC JWT, with two narrow exceptions: `/healthz` (liveness) and
+  `POST /api/v1/clients/enroll` (IP-gated in the handler instead).
+  `GET /api/v1/events/stream` additionally accepts the token as a
+  `?token=` query param, since `EventSource` can't set custom headers.
+- Add CORS (`github.com/go-chi/cors`, `OIKOS_CORS_ORIGIN`, default `*`) so a
+  cross-origin SPA (Vite dev server, a future Wails webview) can reach the
+  API. No `AllowCredentials` — auth is a header, not a cookie, so
+  credentialed CORS mode isn't needed and the two don't combine safely with
+  a wildcard origin.
+- Wrap the previously-unauthenticated `/agent` proxy mount in the same
+  `combinedAuth` middleware as every other route.
+- `cmd/nomos` becomes an authenticated client of `api`: it now sends
+  `Authorization: Bearer $OIKOS_MCP_BEARER_TOKEN` on its own outbound calls
+  (MCP + the chat-assent approval-decision endpoint), which it never did
+  before — dev-open covered for it until now.
+- The SPA gets a runtime config module (`web/src/lib/config.ts`) and a
+  first-launch `Config.svelte` screen: server URL + token, stored in
+  `localStorage`, injected into every `fetch()` via a shared
+  `fetchWithAuth` wrapper. Resolved fresh per request (not cached at
+  module-load time), so the same build works same-origin or cross-origin
+  without a rebuild.
+
+## Consequences
+- Closing dev-open was a live security fix, not just future-proofing —
+  verified post-deploy that unauthenticated requests to production now 401.
+- Nomos's *own* HTTP gateway (`cmd/nomos`, port 8092) still has no auth of
+  its own — out of scope here, tracked separately
+  (plans/2026-07-11-nomos-agent-code-review.md, finding C1).
+- Production Caddy (`dtoro/caddy-conf`, not this repo) does not yet expose
+  `oikos.hubris.network` at all, so the interaction between Authentik
+  forward-auth and bearer-token clients (a non-browser client can't
+  complete a browser SSO redirect) is unresolved — needs an `@enroll`-style
+  bypass for `/api/v1/*`/`/mcp`/`/agent/*` before public exposure. This
+  repo's `compose/caddy/Caddyfile.oikos` (a reference copy, not deployed
+  from here) has the bypass; the real config does not yet.
+- There is one shared bearer secret for all agents/clients, not per-client
+  tokens — acceptable for the current fleet size, revisit if per-client
+  revocation becomes necessary.

docs/adr/README.md

@@ -5,7 +5,7 @@ after acceptance — superseding decisions get a new ADR that links back.
 Statuses: proposed | accepted | superseded-by-NNNN.
 
 | ADR | Title |
-|---|---|---|
+|---|---|
 | [0001](0001-go-single-binary.md) | Go with single-binary role packaging |
 | [0002](0002-postgres-timescale-only-datastore.md) | PostgreSQL + TimescaleDB as the only datastore |
 | [0003](0003-db-native-ontology-yaml-seeds.md) | DB-native ontology with YAML seed manifests |
@@ -16,7 +16,8 @@ Statuses: proposed | accepted | superseded-by-NNNN.
 | [0008](0008-forward-only-migrations.md) | Forward-only migrations |
 | [0009](0009-sse-over-websocket.md) | SSE over WebSocket for the event stream |
 | [0010](0010-infisical-with-sops-fallback.md) | Infisical secrets with SOPS DR fallback |
-| [0011](0011-client-lifecycle-flows.md) | Client lifecycle flows — enrollment, bootstrap, sync |
-| [0012](0012-hermes-oikos-interactions.md) | Hermes–Oikos interactions — agent/OS contract |
-| [0013](0013-signal-triggers.md) | Signal triggers — host health checks via scheduler |
+| [0011](0011-client-lifecycle-flows.md) | Client lifecycle sequence diagrams |
+| [0012](0012-hermes-oikos-interactions.md) | Hermes/Oikos interaction architecture |
+| [0013](0013-signal-triggers.md) | Signal trigger architecture |
 | [0014](0014-entity-model.md) | Entity model — types, relationships, state machines, OODA loop |
+| [0015](0015-api-bearer-auth-client-server-split.md) | Bearer-token auth for every route + client/server split |

docs/index.md

@@ -0,0 +1,17 @@
+# Docs
+
+Long-form reference material for the Oikos platform. Operational state and
+topology live in the DB (seeded from `seeds/`); these docs cover decisions,
+procedures, and the system model.
+
+| Path | Contents |
+| ---- | -------- |
+| [adr/](adr/README.md) | Architecture Decision Records (numbered, append-only) |
+| [mbse/](mbse/README.md) | Model-Based Systems Engineering views of the platform |
+| [mascot/](mascot/README.md) | MBSE subsystem model for the desktop mascot (planned) |
+| [operations/](operations/README.md) | Operator runbooks (deploy, rollback, recovery) |
+
+For agent orientation see [AGENTS.md](../AGENTS.md); for the operating model
+see [.agents/OIKOS.md](../.agents/OIKOS.md); for development see
+[CONTRIBUTING.md](../CONTRIBUTING.md). Design plans live in
+[plans/](../plans/), not here.

docs/mascot/README.md

@@ -0,0 +1,371 @@
+# Oikos — Desktop Mascot Subsystem Model
+
+> Companion to [the platform Model](../mbse/README.md) and
+> [the Framework](../mbse/framework.md). This document is a **subsystem
+> Model** in Holt's sense — it conforms to the same Framework (Ontology +
+> Viewpoints, Markdown + Mermaid Notation) rather than restating it, scoped
+> to a single not-yet-built subsystem of the `web` component: the desktop
+> mascot ("Cluck"), a pixel-art chicken that lives on the desktop shell.
+> Where the platform-wide Views in [../mbse/README.md](../mbse/README.md)
+> and the component View for `web/src` in
+> [../mbse/components.md](../mbse/components.md#5-web-control-room) speak
+> at the level of "the SPA," this document goes one layer deeper into one
+> feature of it — the same relationship [components.md](../mbse/components.md)
+> has to [README.md](../mbse/README.md), applied recursively.
+
+**Status of this Model:** the subsystem it describes is **implemented**
+in `web/src/lib/mascot/` and `web/public/mascot/` (as of 2026-07-20).
+Views below are marked **Implemented** where the code matches; a small
+number of requirements (distinct adult art, a true round radial menu)
+remain **Planned** as polish items. The corresponding implementation plan
+is [plans/2026-07-20-desktop-mascot.md](../../plans/2026-07-20-desktop-mascot.md),
+which carries a deviation note at the top covering the changes made
+during implementation (hatch-on-naming, PNG-sheet art, button-column
+radial menu, 60fps loop), and the physics audit/follow-up is
+[plans/2026-07-20-mascot-physics-audit.md](../../plans/2026-07-20-mascot-physics-audit.md).
+
+## Views in this model
+
+| # | View | Concern it addresses |
+|---|---|---|
+| [1](#1-mission--system-context) | Mission & System Context | Why a mascot, and what is it never allowed to do? |
+| [2](#2-requirements) | Requirements | What must it do, traced from the original request? |
+| [3](#3-structural-view) | Structural View | What modules make it up, and which are the extension points? |
+| [4](#4-behavioral-view) | Behavioral View | How does it move, live, and react, moment to moment? |
+| [5](#5-interfaces-view) | Interfaces View | What does it read from the rest of the system, and how does it persist itself? |
+| [6](#6-extension-guide) | Extension Guide | How does a future engineer add an animation, behavior, menu action, or reaction? |
+| [7](#7-verification-view) | Verification View | How will we know it works, once built? |
+
+## 1. Mission & System Context
+
+**Stakeholders:** the operator (delight, ambient awareness of system
+state without opening a window); future engineers extending the mascot's
+behaviors/reactions/menu.
+
+**Mission:** give the desktop shell a persistent, living presence that
+makes background system activity legible at a glance — a chat streaming,
+a knowledge-graph write, a critical signal — without requiring a window to
+be open, while doubling as a lightweight tamagotchi for its own sake
+(delight is a legitimate requirement here, not a side effect).
+
+**Boundary — what the mascot is, and is not:**
+
+- It is a **purely client-side, read-only observer**. It subscribes to
+  existing `web` stores (chat, activity, events, dashboard summary) the
+  same way any other UI component does.
+- It **never calls a mutating API endpoint** and is not a new actuation
+  path — it has no relationship to the `run` gate, `Execution`, or
+  `Approval` entities described in [the platform Ontology](../mbse/ontology.md).
+  Its only "mutation" is its own tamagotchi state, stored client-side.
+- It is scoped entirely inside the `web` component
+  ([../mbse/components.md §5](../mbse/components.md#5-web-control-room));
+  it introduces no new backend surface, no new MCP tool, no new REST route.
+
+```mermaid
+flowchart TB
+    subgraph SURFACE["Desktop shell surface (Desktop.svelte)"]
+        ICONS["Icon layer\nz-0"]
+        LAUNCH["Task launcher\nz-10"]
+        WIN["WindowLayer\nz-40"]
+        MASCOT["MascotLayer\nz-45\n(this subsystem)"]
+        MENU["Desktop context menu\nz-50"]
+    end
+
+    MASCOT -->|subscribes, read-only| EVENTS["stores/events.ts\nliveEvents (SSE)"]
+    MASCOT -->|subscribes, read-only| CHAT["stores/chat.ts\nstreaming"]
+    MASCOT -->|subscribes, read-only| ACTIVITY["stores/activity.ts\nactivityLog"]
+    MASCOT -->|subscribes, read-only| CONTEXT["stores/context.ts\nsummary"]
+    MASCOT -->|reads/writes| LS["localStorage\noikos-mascot"]
+
+    style MASCOT fill:#fff3e0,stroke:#e65100
+```
+
+## 2. Requirements
+
+Traced from the original feature request. Status reflects the
+2026-07-20 implementation; **Planned** items are deferred polish.
+
+| ID | Statement | Source | Status |
+|---|---|---|---|
+| MASC-1 | The mascot SHALL render as pixel-art from bundled 16x16 PNG sprite sheets (chicken + egg packs), not code-drawn string grids | User request (relaxed from "code-drawn" during implementation — see plan deviation note) | Implemented |
+| MASC-2 | The mascot SHALL roam the desktop surface autonomously, walking along the ground (surface bottom, above the taskbar, OR the top edge of any non-minimized window beneath it) under gravity | User request + design decision | Implemented |
+| MASC-3 | The mascot SHALL be draggable with the mouse; releasing it mid-air SHALL trigger a flutter-fall back to the ground | User request + design decision | Implemented |
+| MASC-4 | Right-clicking the mascot SHALL open an interaction menu supporting nested submenus; rendered as a rounded-button column (relaxed from "round/Sims-style" — see plan deviation note) | User request | Implemented |
+| MASC-5 | The mascot SHALL have a tamagotchi lifecycle: egg → chick → adult, with a user-assignable name; the egg → chick transition fires on first naming, not on a timed incubation | User request | Implemented |
+| MASC-6 | The mascot's stage, name, and stats SHALL persist across reloads | User request (implied by "tamagotchi") | Implemented |
+| MASC-7 | The mascot SHALL have idle states (autonomous behavior when untouched) and interactive states (drag, click, menu) | User request | Implemented |
+| MASC-8 | The mascot SHALL react visibly to real application activity: chat streaming, knowledge-graph writes, critical signals | User request ("aware of its environment... feels alive and connected") | Implemented |
+| MASC-9 | Animations, behaviors, menu actions, and reactions SHALL each be defined in a single data-driven registry, so a new one can be added without touching the engine code | User request ("easily expansible") | Implemented |
+| MASC-10 (NFR) | The mascot's game loop SHALL run via `setTimeout`, not `requestAnimationFrame`, matching the repo's existing [`GraphBackground.svelte`](../../web/src/lib/components/GraphBackground.svelte) convention (rAF suspends in some hidden-tab embeddings); runs at ~60fps (relaxed from 30fps for smoother drag/fall — see plan deviation note) | Codebase convention | Implemented |
+| MASC-11 (NFR) | The mascot SHALL never write to the API; all mutation is local (localStorage) | Design decision, this document §1 | Implemented |
+| MASC-12 (NFR) | Persistence writes SHALL be debounced (~300ms), never per animation frame | Codebase convention ([`stores/windows.ts`](../../web/src/lib/stores/windows.ts) wmkit persist) | Implemented |
+
+## 3. Structural View
+
+**Stakeholders:** an engineer implementing or extending the mascot.
+**Why this View earns its place:** MASC-9 (extensibility) is only real if
+the module boundaries actually separate data (registries) from engine
+code; this View is the check that they do.
+
+```mermaid
+classDiagram
+    class types_ts {
+        <<module>>
+        PixelGrid
+        AnimName
+        MascotStage
+        BehaviorId
+        Stimulus
+        RadialAction
+    }
+    class palette_ts {
+        <<module, registry>>
+        PALETTE: char to CSS color
+    }
+    class sprites_ts {
+        <<module, registry>>
+        SPRITES: Stage to AnimName to AnimDef
+        resolveAnim(stage, name)
+    }
+    class render_ts {
+        <<module, stateless>>
+        drawFrame(ctx, grid, palette, flip)
+    }
+    class state_svelte_ts {
+        <<module, runes>>
+        MascotModel state
+        grantXp() feed() pet() setName()
+        tickLifecycle() advanceStageIfReady()
+        persist (debounced, oikos-mascot)
+    }
+    class behavior_ts {
+        <<module, registry>>
+        BEHAVIORS: BehaviorId to BehaviorDef
+        stepMascot(rt, model, now, dt)
+    }
+    class stimuli_ts {
+        <<module, registry>>
+        REACTIONS: id to ReactionDef
+        attachStimuli(emit)
+    }
+    class actions_ts {
+        <<module, registry>>
+        MASCOT_ACTIONS: RadialAction tree
+        registerMascotAction()
+    }
+    class Mascot_svelte {
+        <<component>>
+        canvas render loop 30fps
+        pointer drag/click/contextmenu
+    }
+    class MascotLayer_svelte {
+        <<component>>
+        z-45 absolute overlay
+        hosts Mascot + RadialMenu + bubble
+    }
+    class RadialMenu_svelte {
+        <<component>>
+        z-60 fixed, nested rings
+    }
+    class NameDialog_svelte {
+        <<component>>
+    }
+
+    sprites_ts --> palette_ts : indexes
+    sprites_ts --> types_ts : uses
+    Mascot_svelte --> render_ts : draws frames
+    Mascot_svelte --> sprites_ts : resolves anim
+    Mascot_svelte --> behavior_ts : steps FSM
+    Mascot_svelte --> state_svelte_ts : reads/mutates model
+    MascotLayer_svelte --> Mascot_svelte : hosts
+    MascotLayer_svelte --> RadialMenu_svelte : hosts, on contextmenu
+    MascotLayer_svelte --> stimuli_ts : attaches on mount
+    MascotLayer_svelte --> NameDialog_svelte : hosts, on hatch/rename
+    RadialMenu_svelte --> actions_ts : renders tree
+    stimuli_ts --> behavior_ts : forceBehavior(react)
+```
+
+**The four extension registries** (MASC-9's concrete answer — see also
+[§6 Extension Guide](#6-extension-guide)): `SPRITES` (animations),
+`BEHAVIORS` (autonomous states), `MASCOT_ACTIONS` (radial menu tree),
+`REACTIONS` (environment stimuli). Each is plain data; the engine
+(`behavior.ts`'s `stepMascot`, `Mascot.svelte`'s loop, `RadialMenu.svelte`'s
+renderer) is generic over whatever the registry currently contains.
+
+**Mount point:** two lines in
+[`Desktop.svelte`](../../web/src/lib/components/desktop-shell/Desktop.svelte) —
+`<MascotLayer />` rendered inside the surface `<div>` (the `relative
+min-h-0 flex-1 overflow-hidden` element), after `<WindowLayer />`, so its
+`absolute inset-0` shares the surface's coordinate space and its ground
+line is exactly the surface's bottom edge (= the taskbar's top edge).
+
+## 4. Behavioral View
+
+**Stakeholders:** an engineer reasoning about "what does the mascot do
+right now, and why." **Why this View earns its place:** a mascot with an
+implicit, ad-hoc state machine is unmaintainable the moment a second
+behavior or reaction is added; this View is the state machine made
+explicit before any of it is coded.
+
+### 4.1 Behavior FSM (moment-to-moment autonomy)
+
+```mermaid
+stateDiagram-v2
+    [*] --> egg
+    egg --> chick : first naming submitted\n(forceHatch: hatchProgress=1)
+
+    state chick_and_adult_behaviors {
+        [*] --> idle
+        idle --> wander : weighted random pick\non behaviorUntil expiry
+        wander --> idle
+        idle --> peck : weighted random pick
+        peck --> idle
+        idle --> hop : weighted random pick
+        hop --> idle : touchdown\n(off-edge mid-hop hands to falling)
+        idle --> sleep : weighted random pick
+        sleep --> idle
+        wander --> falling : y below ground\n(off a dragged edge, etc.)
+        idle --> dragged : pointerdown + move\npast 5px threshold
+        wander --> dragged : pointerdown + move
+        sleep --> dragged : pointerdown + move\n(interrupts sleep)
+        dragged --> falling : pointerup, released mid-air\n(toss velocity from pointer history)
+        falling --> falling : hard impact\n(one diminished bounce)
+        falling --> land : y reaches ground\n(sideways momentum -> skid)
+        land --> idle
+        [*] --> react : stimulus dispatched\n(priority/cooldown gated)
+        react --> idle : durationMs elapsed,\nreturns to prior-or-idle
+    }
+
+    chick --> adult : xp reaches ADULT_XP\n(advanceStageIfReady)
+```
+
+`dragged` always wins over any autonomous behavior; `sleep` is broken only
+by a reaction whose `ReactionDef.interruptsSleep` is true (§4.3) or by a
+drag. Weighted-random idle selection (`weight` field in `BehaviorDef`)
+picks the next autonomous behavior only when the current one's `next()`
+returns null past `behaviorUntil` — see
+[plans/2026-07-20-desktop-mascot.md](../../plans/2026-07-20-desktop-mascot.md)
+for the concrete weights.
+
+**Physics feel (implemented 2026-07-20, second pass):** the fall is a
+losing attempt at flight, not a drop — wing-beat impulses on a
+speed-scaled, jittered flap cycle (panic flapping) shave the descent;
+falls faster than terminal velocity (hard downward tosses) decay back
+under drag instead of clamping; hard impacts bounce once, squash via a
+damped-spring render layer scaled by impact speed, and poof a burst of
+feather pixels; sideways momentum becomes a friction skid on touchdown
+and ricochets off the surface's side bounds mid-fall; the sprite
+stretches along its motion in the air and tilts into horizontal velocity
+(fall, drag, and skid); walking bobs at step frequency. All of it is
+tuning in `behavior.ts` plus the pure render layer in `Mascot.svelte`'s
+`updateJuice()` — no new assets, no new states beyond `hop`.
+
+### 4.2 Tamagotchi lifecycle (long-lived state)
+
+```mermaid
+stateDiagram-v2
+    [*] --> egg : first load,\ndefaultModel()
+    egg --> chick : first naming submitted\n(forceHatch sets hatchProgress=1)\n+ NameDialog shown
+    chick --> adult : xp >= ADULT_XP (200)
+    adult --> [*]
+```
+
+This is a separate state machine from §4.1: §4.1 governs frame-to-frame
+motion/animation, §4.2 governs the tamagotchi's slow-moving `MascotModel`
+(persisted, ticked ~1x/sec via `tickLifecycle`, not every frame). The
+egg → chick transition fires on first naming, not on a timed incubation
+— see the deviation note in
+[plans/2026-07-20-desktop-mascot.md](../../plans/2026-07-20-desktop-mascot.md).
+
+### 4.3 Example sequence — an environment stimulus becomes a visible reaction
+
+```mermaid
+sequenceDiagram
+    participant SSE as stores/events.ts (SSE)
+    participant Stim as stimuli.ts attachStimuli
+    participant Layer as MascotLayer.svelte (emit callback)
+    participant FSM as behavior.ts
+    participant Mascot as Mascot.svelte (canvas)
+
+    SSE->>Stim: liveEvents updates,\nnew head event severity=critical
+    Stim->>Stim: check REACTIONS['alarmed']\ncooldown + priority
+    Stim->>Layer: emit(reaction)
+    Layer->>Layer: if model.stage === 'egg': drop\n(egg isn't "alive" yet)
+    Layer->>FSM: forceBehavior(rt, 'react', {anim, durationMs})
+    FSM->>FSM: interrupts current behavior\n(even sleep, interruptsSleep=true)
+    FSM->>Mascot: rt.behavior = 'react', rt.anim = 'react-alarm'
+    Mascot->>Mascot: next ~60fps tick draws\nreact-alarm frame + bubble
+    Note over FSM: after durationMs,\nnext() returns to idle
+```
+
+**Egg-stage suppression:** MascotLayer's `emit` callback drops any
+reaction when `model.stage === 'egg'`. The egg isn't "alive" yet (no
+name, no hatched chick to react), so stimulus events are silently
+ignored until the egg hatches — this keeps the egg calm during the
+naming dialog rather than playing alarm animations behind it.
+
+## 5. Interfaces View
+
+**Stakeholders:** an engineer wiring a new store into the mascot's
+awareness, or auditing what it depends on.
+
+| Interface | Direction | Shape | Notes |
+|---|---|---|---|
+| [`stores/events.ts`](../../web/src/lib/stores/events.ts) `liveEvents` | consumed | `Writable<OikosEvent[]>`, newest-first, ref-counted via `subscribeEvents()` | `OikosEvent.type` families: `approval.*`, `signal.*`, `execution.*`, `health.changed`; `severity: 'info'\|'warning'\|'critical'` |
+| [`stores/chat.ts`](../../web/src/lib/stores/chat.ts) `streaming` | consumed | `Writable<boolean>` | false→true edge triggers the `thinking` reaction, held while true |
+| [`stores/activity.ts`](../../web/src/lib/stores/activity.ts) `activityLog` | consumed | derived `Readable<ActivityEntry[]>`, **recomputed wholesale** on every emission — not append-only | new entries with `type === 'knowledge'` detected by diffing entry `id`s between emissions, not by treating it as a stream |
+| [`stores/context.ts`](../../web/src/lib/stores/context.ts) `summary` | consumed | `Writable<DashboardSummary\|null>` | ambient state (open signal counts via `openSignalCount(summary)`) |
+| `localStorage['oikos-mascot']` | owned | `MascotModel` JSON, `{ version: 1, stage, name, hatchProgress, happiness, xp, hatchedAt, lastPos: {x}, lastSeen }` (hatchProgress is binary 0/1: 0 until first naming, 1 after) | debounced write (~300ms, mirrors [`stores/windows.ts`](../../web/src/lib/stores/windows.ts) wmkit persist) + `beforeunload` flush; `version` field reserved for a future `migrate()`; multi-tab is last-writer-wins (accepted, documented, not solved) |
+| [`Desktop.svelte`](../../web/src/lib/components/desktop-shell/Desktop.svelte) mount | owned | `<MascotLayer />`, 2-line insertion | see §3 |
+
+No interface in this table is a write path to the Oikos API — consistent
+with §1's boundary statement (MASC-11).
+
+## 6. Extension Guide
+
+**Stakeholders:** a future engineer adding one new animation, behavior,
+menu action, or reaction — this is the Viewpoint 4's "why" made concrete
+as a recipe rather than prose (mirrors [../mbse/framework.md §7](../mbse/framework.md)'s
+Process Set treatment).
+
+| To add a... | Touch only | Nothing else changes because |
+|---|---|---|
+| **Animation** | Add the name to the `AnimName` union in `types.ts`; add frames to `SPRITES[stage]` in `sprites.ts` | `resolveAnim()` and the renderer are generic over the registry |
+| **Behavior** | Add the id to `BehaviorId`; add one `BehaviorDef` entry to `BEHAVIORS` in `behavior.ts` | `stepMascot()` and the weighted-random idle selector consume `BEHAVIORS` generically |
+| **Radial menu action** | Add a `RadialAction` node to `MASCOT_ACTIONS` in `actions.ts` (or call `registerMascotAction()`), optionally nested under `children` | `RadialMenu.svelte` renders whatever tree it's given, including nesting depth |
+| **Environment reaction** | Add a `ReactionDef` to `REACTIONS` in `stimuli.ts`; wire one `store subscription -> predicate -> emit(reaction)` block inside `attachStimuli()` | priority/cooldown/interrupt dispatch logic in `attachStimuli()` is generic over `REACTIONS` |
+
+## 7. Verification View
+
+**Stakeholders:** whoever implements this subsystem and needs to know
+when it's actually done, not just compiled.
+
+Manual browser checklist (no automated test harness planned for v1 — see
+[plans/2026-07-20-desktop-mascot.md](../../plans/2026-07-20-desktop-mascot.md)
+for the same list in implementation-order context):
+
+- Egg renders grounded at the surface bottom, wiggles gently while the
+  name dialog is open, and survives a reload at the same x (confirm
+  `oikos-mascot` is debounced — no writes fire from mere walking, only
+  from discrete transitions).
+- Dragging the egg up and releasing triggers a flutter-fall with no
+  tunneling below the taskbar; dragging past the surface edges clamps.
+- A fresh egg (no name) opens the name dialog on mount; submitting it
+  hatches to chick; the name persists across reload. The debug "Force
+  hatch" action does the same without prompting.
+- Chick wanders and flips sprite at surface edges, pecks, sleeps
+  autonomously; a plain click (no drag) triggers a pet/hop reaction.
+- Right-clicking the chicken opens the radial menu centered on it, without
+  triggering the desktop's own right-click menu; a nested submenu (Feed)
+  opens correctly; Escape pops one level then closes; an outside click
+  closes it; the menu stays fully visible when the chicken is near a
+  screen edge or corner.
+- With one or more windows open (including a maximized one), the chicken
+  visibly walks above them without breaking window drag/resize/close.
+- Starting a chat and observing it stream triggers the `thinking` reaction
+  for the duration; a simulated knowledge-graph write triggers `eureka`
+  once per cooldown window; a simulated critical signal triggers `alarmed`
+  even while the chicken is asleep.
+- Resizing the browser viewport re-grounds and re-clamps the chicken.
+- Both the Terracotta and Carbon themes keep the pixel-art palette legible.
+- `npm run build` passes with no new errors.

docs/mbse/components.md

@@ -0,0 +1,685 @@
+# Oikos — Component Views
+
+> Companion to [the Model](README.md) and [the Framework](framework.md).
+> Where README.md's nine Views cut across the whole system by *concern*
+> (requirements, behavior, risk...), this document cuts across it by
+> *component* — one View per running part of the System, going one layer
+> deeper into its own internal structure than the whole-system Views do.
+> Per [framework.md](framework.md) §4, each section below is still a View
+> and must still answer Holt's three questions; they're stated once per
+> section rather than as a separate table, since here the Stakeholder is
+> almost always the same ("an engineer about to change this component")
+> and the Notation is the same (prose + Mermaid) throughout.
+
+**How to use this alongside the other two documents:** if you're deciding
+*whether something belongs in the Model*, read [framework.md](framework.md).
+If you're asking *what does the system do and why*, read
+[README.md](README.md). If you're about to **change code in a specific
+package** and want to know its internal shape, its own state, and what's
+already known to be broken or dormant inside it before you touch it, read
+the relevant section here.
+
+## Contents
+
+| Component | Path | Status |
+|---|---|---|
+| [1. oikos api](#1-oikos-api) | `internal/httpapi`, `internal/mcp`, `internal/policy` | ✅ live — the decision/execution gate |
+| [2. oikos scheduler](#2-oikos-scheduler) | `internal/scheduler`, `internal/checkdefaults` | ✅ live — the observe loop |
+| [3. oikos notifier](#3-oikos-notifier) | `internal/notifier` | ✅ live — approval delivery |
+| [4. nomos](#4-nomos-agent-gateway) | `cmd/nomos` | ✅ live — the agent, unauthenticated gateway |
+| [5. web control room](#5-web-control-room) | `web/src` | ✅ live — standalone SPA |
+| [6. PostgreSQL/TimescaleDB](#6-postgresqltimescaledb) | `migrations/`, `seeds/` | ✅ live — the System's own source of truth |
+| [7. Dormant components](#7-dormant-components) | `internal/actuator`, `internal/learning` | 🔴 compiled, never started |
+| [8. Auxiliary components](#8-auxiliary-components) | `cmd/webhook`, `cmd/desktop` | ✅ live — deploy + packaging, not decision logic |
+| [9. web control room — App architecture](#9-web-control-room--app-architecture) | `web/src/lib/apps.ts`, `web/src/lib/stores/windows.ts`, `web/src/lib/stores/docked.ts`, `web/src/lib/components/desktop-shell/` | ✅ live — the OS + Apps shell contract |
+
+---
+
+## 1. oikos api
+
+**Stakeholders:** engineers extending the MCP tool surface, the `run` gate,
+or REST endpoints; anyone debugging why a specific command was or wasn't
+classified the way they expected. **Why this View earns its place:** this
+is the single component where the highest-consequence findings in
+[Risk & Safety](README.md#8-risk--safety) live — extending it without
+knowing its internal shape is how the kill-switch gap and the
+two-classifiers problem happened in the first place.
+
+### oikos api — Internal structure
+
+| File | Lines | Role |
+|---|---|---|
+| `internal/httpapi/server.go` | 842 | `NewHandler` (routing entry, L75), `combinedAuth` (L229), OIDC JWKS discovery/fetch/validate (L337-524), `GetActor` (L526), OIDC config/token/callback handlers (L575-712), `ListenAndServe` (L811) |
+| `internal/httpapi/impl.go` | 1,639 | Entity CRUD, lifecycle transitions + preconditions (per [ADR-0014](../adr/0014-entity-model.md)) |
+| `internal/httpapi/phase3.go` | 2,627 | Executions, approvals (`DecideApproval`), `sshExec`, `executeApprovedAction`, autonomy-settings read/write endpoints — the **largest single file in the component** |
+| `internal/httpapi/sse.go` | 366 | `LISTEN/NOTIFY` fan-out, ring-buffer replay |
+| `internal/httpapi/activity.go` | 215 | `agent_activity` read endpoints |
+| `internal/httpapi/knowledge.go` | 286 | Knowledge search/content endpoints |
+| `internal/httpapi/dashboard.go` | 172 | `dashboard/summary` |
+| `internal/httpapi/learning_view.go` | 129 | `learning/timeline`, `learning/trend` |
+| `internal/httpapi/problem.go` | 71 | RFC 9457 `problem+json` error envelope |
+| `internal/httpapi/default_checks.go` | 13 | Thin wrapper calling `internal/checkdefaults` on entity creation |
+| `internal/mcp/server.go` | 1,691 | All 33 MCP tool registrations (`get_entity` at L76 through `list_my_secrets` at L753), `sshExec` (L1031), `resolveExecTarget` (L1223), **`classifyAndGate`** (L1264-1417) |
+| `internal/policy/command.go` | 174 | `ClassifyCommand` (L108) — the **live** classifier, `computeCommandRisk` (L127), `allSegmentsReadOnly` (L157), `riskRank` (L26) |
+| `internal/policy/classify.go` | 157 | `ClassifySignal` (L46) — **dead code, zero callers** (see [Roadmap §9.2](README.md#92-code-real--dead-code--schema-only-matrix)) |
+
+### oikos api — internal call structure: the `run` gate, by file
+
+README.md's [§3.3](README.md#3-functional-architecture) shows the *decision
+logic* of the `run` gate. This shows the *code path* — which file hands off
+to which — because they're not the same question: the decision flowchart
+tells you what happens, this tells you where to go fix it.
+
+```mermaid
+flowchart LR
+    MCP["mcp/server.go\nrun tool handler, L366"] --> GATE["mcp/server.go\nclassifyAndGate, L1264"]
+    GATE --> RESOLVE["mcp/server.go\nresolveExecTarget, L1223"]
+    GATE --> CLASSIFY["policy/command.go\nClassifyCommand, L108"]
+    CLASSIFY --> RISK["policy/command.go\ncomputeCommandRisk, L127\nallSegmentsReadOnly, L157"]
+    GATE -->|read_only or window open| EXEC["mcp/server.go\nsshExec, L1031"]
+    GATE -->|otherwise| APPROVAL["phase3.go\ncreateApproval"]
+    APPROVAL -->|operator decides| DECIDE["phase3.go\nDecideApproval"]
+    DECIDE --> EXEC2["phase3.go\nsshExec\n(separate implementation)"]
+
+    style CLASSIFY fill:#e8f5e9,stroke:#2e7d32
+    style EXEC fill:#fff3e0,stroke:#e65100
+    style EXEC2 fill:#fff3e0,stroke:#e65100
+```
+
+The two orange boxes are the same finding stated visually: `mcp/server.go`
+and `phase3.go` each have **their own `sshExec`**, independently written,
+not sharing an implementation. Fix one path's SSH handling and the other is
+untouched — verified during the Roadmap audit, not assumed.
+
+### oikos api — Interfaces this component owns
+
+Full catalogs live in [README.md §5](README.md#5-interfaces-icd) (33 MCP
+tools, REST groups, SSE event types) — not repeated here. What's specific
+to *this* component's internal ownership: `internal/mcp/server.go` owns
+every MCP tool; `internal/httpapi/{impl,phase3,sse,activity,knowledge,
+dashboard,learning_view}.go` own the REST surface between them, split by
+resource area rather than by file size; `internal/policy/command.go` is a
+pure function library with no HTTP surface of its own, called only from
+`classifyAndGate`.
+
+### oikos api — Status and known issues
+
+All of the following are detailed with evidence in
+[Roadmap & Traceability](README.md#9-roadmap--traceability) and
+[Risk & Safety](README.md#8-risk--safety) — cross-referenced here so an
+engineer opening this specific package sees them before making a change,
+not after:
+
+- `policy.ClassifySignal` (in this component) is dead code; the schema it
+  reads (`autonomy_settings.global.auto_act`, `never_auto_act.*`) is
+  therefore not enforced by anything in the live request path — [§8.1](README.md#81-the-kill-switch-gap-verified-most-important-finding-in-this-model).
+- `notifier.VerifyApprovalToken` (a different component, §3 below) is dead;
+  `phase3.go:DecideApproval` reimplements token verification inline instead
+  of calling it.
+- `domain.Execution`'s state constants are descriptive only — `phase3.go`
+  writes ad-hoc SQL string statuses that don't map 1:1 onto them.
+- SSH host key verification is disabled (`InsecureIgnoreHostKey`) on the
+  actuation path — open gap B4.
+
+---
+
+## 2. oikos scheduler
+
+**Stakeholders:** engineers adding a new probe kind or debugging why a
+signal did or didn't fire. **Why this View earns its place:** the
+scheduler is the only component that runs unattended on a fixed interval
+with no operator or agent triggering it — its failure modes look different
+from every request-driven component above.
+
+### oikos scheduler — Internal structure
+
+| File | Lines | Role |
+|---|---|---|
+| `internal/scheduler/scheduler.go` | 761 | Everything — no sub-packages |
+| `internal/scheduler/init.go` | 13 | `RunnerForMain()` — the only thing `cmd/oikos`'s `scheduler` role calls |
+| `internal/checkdefaults/defaults.go` | — | `ForEntityType` (L60-123), `Ensure` (L144-204), `DefaultInterval` (L133-142) — default check provisioning on entity creation |
+
+Key functions inside `scheduler.go`: `Run` (L36-64, the tick loop, default
+30s), `runCheckPass` (L67-94, loads `check_defs`, dispatches with a
+10-worker `errgroup` limit), `runCheck` (L104-186), `executeCheck` (L237-254,
+the kind dispatcher), `resolveSignal` (L206-225), `evaluateSeverity`
+(L737-760), `staleSweep` (L286-333, 3× fastest interval / 5 min floor).
+
+### oikos scheduler — behavior specific to this component: the probe dispatch
+
+```mermaid
+flowchart TB
+    TICK["Run tick, every 30s"] --> LOAD["ListEnabledCheckDefs"]
+    LOAD --> DISPATCH["executeCheck: dispatch by kind"]
+    DISPATCH --> HTTP["checkHTTP, L336"]
+    DISPATCH --> TCP["checkTCP, L393"]
+    DISPATCH --> DISK["checkDisk, L424"]
+    DISPATCH --> CERT["checkCertExpiry, L474"]
+    DISPATCH --> PING["checkPing, L545"]
+    DISPATCH --> SSH["checkSSHScript, L613"]
+    HTTP & TCP & DISK & CERT & PING & SSH --> RESULT["checkResult struct\nhealth, signalKind, evidence, metrics"]
+    RESULT -->|healthy| RESOLVE["resolveSignal\nraw SQL, bypasses Signal.CanTransition"]
+    RESULT -->|unhealthy| UPSERT["UpsertSignal\ndedup by target+kind"]
+    RESULT --> METRICS["INSERT metric_samples"]
+    RESULT --> STATUS["UpsertEntityStatus"]
+```
+
+`checkSSHScript` (L613-724) is the odd one out: it shells out to the system
+`ssh` binary directly (`BatchMode=yes`, `StrictHostKeyChecking=no`) rather
+than using a Go SSH library, restricted to scripts matching
+`^[a-z][a-z0-9_-]+\.sh$` at a fixed path `/opt/oikos/checks/<script>`. The
+18 scripts it can run (`cpu_check.sh`, `disk_usage_check.sh`,
+`docker_health_check.sh`, `zfs_check.sh`, …) live in `checks/` in this repo
+and are auto-deployed to every enrolled client by `tools/setup-checks.sh`
+(per AGENTS.md §8) — this component's actual probe logic is split between
+Go code here and shell scripts version-controlled elsewhere in the repo.
+
+### oikos scheduler — Interfaces this component owns
+
+No external API — this is the one component with no inbound interface at
+all, only outbound: SSH to the fleet (probes), and writes to
+`metric_samples`/`signals`/`entity_status`/`events` that every other
+component reads. It is a pure producer.
+
+### oikos scheduler — Status and known issues
+
+- Never calls `policy.ClassifySignal` — signals it raises sit as
+  `state='raised'` with no automatic classification; whatever consumes
+  them downstream (the agent, the console) does its own interpretation.
+- `resolveSignal` updates `raised → resolved` via raw SQL, bypassing the
+  one enforced state machine in the domain layer
+  (`domain.Signal.CanTransition`) — the specific transition happens to be
+  legal today, but nothing would stop a future change from making it not.
+
+---
+
+## 3. oikos notifier
+
+**Stakeholders:** engineers debugging a missed or duplicate Matrix alert,
+or extending the approval-delivery mechanism to a new channel.
+**Why this View earns its place:** this is the one component whose entire
+job is bridging an asynchronous human decision into the same-shaped
+synchronous decision every other component expects — worth understanding
+in isolation before assuming "approval" means one simple thing.
+
+### oikos notifier — Internal structure
+
+All in `internal/notifier/notifier.go` (305 lines, one file, no
+sub-packages): `Run` (L25-47, two tickers — 15s for pending approvals, 30s
+for reaction polling), `processPendingApprovals` (L65-115, generates the
+token/hash lazily on first pass), `generateApprovalToken` (L275-283,
+HMAC-SHA256 over approval ID + nanosecond timestamp), `hashToken`
+(L302-305, only the hash is stored), `sendMatrixAlert` (L231-272),
+`pollReactions`/`checkReaction` (L118-201), `callDecideApproval`
+(L204-228), `VerifyApprovalToken` (L286-300, **dead code**).
+
+### oikos notifier — Behavior specific to this component
+
+The full sequence (Matrix + console paths converging on one decision
+endpoint) is in [README.md §6.4](README.md#64-sequence--the-run-primitive-end-to-end).
+Specific to this component in isolation: it never calls into
+`internal/httpapi` directly except through one HTTP call
+(`callDecideApproval`, an ordinary client request to
+`POST /api/v1/approvals/{id}/decision`) — the notifier and the API process
+communicate **only through the database and one HTTP endpoint**, never
+through shared Go state, which is why the header comment in `notifier.go`
+calls this a "DB rendezvous pattern."
+
+### oikos notifier — Interfaces this component owns
+
+Outbound only: the Matrix client-server API
+(`PUT /rooms/.../send/m.room.message`, `GET /relations/.../m.annotation`)
+and one outbound call to the API's own approval-decision endpoint. No
+inbound interface — nothing calls into the notifier process.
+
+### oikos notifier — Status and known issues
+
+- `VerifyApprovalToken` is dead code; `phase3.go:DecideApproval` (a
+  different component, §1 above) reimplements the same hash-compare logic
+  inline rather than calling it — a single source of truth for token
+  verification does not currently exist.
+- Open gap A2: `alert_sent_at` is written *after* the send attempt, so a
+  failed UPDATE re-sends the alert on the next poll; no dedup beyond that,
+  and reaction-polling API calls are unbounded.
+
+---
+
+## 4. nomos (agent gateway)
+
+**Stakeholders:** engineers changing agent behavior, adding a task tool, or
+investigating a stuck/duplicated task. **Why this View earns its place:**
+this is the largest component by line count (4,681 lines across six files)
+and the one with the most active recent bug-fix history
+(`plans/2026-07-11-nomos-agent-code-review.md`,
+`plans/done/2026-07-14-post-fix-session-remainders.md`) — its internal
+shape is not obvious from outside.
+
+### nomos — Internal structure
+
+| File | Lines | Role |
+|---|---|---|
+| `cmd/nomos/main.go` | 914 | Gateway HTTP server (`:8092`), `/query`/`/chat`/`/sessions` routes, the hand-rolled Streamable-HTTP MCP client (`mcpClient`, per-session pooled) |
+| `cmd/nomos/store.go` | 1,472 | Persistence — sessions, messages, `logActivity` |
+| `cmd/nomos/agent.go` | 861 | The agentic loop itself; model config (L62-120); `maxIterations = 40` (L24, a **hard-coded constant**, not read from `nomos/config.yaml`'s `max_iterations: 15` — the two disagree, see status below) |
+| `cmd/nomos/tasks.go` | 416 | The five nomos-local task tools: `set_goal`, `propose_plan`, `update_plan_step`, `ask_operator`, `complete_task` — handled in-process, never forwarded to `internal/mcp` |
+| `cmd/nomos/continue.go` | 347 | The auto-continuation worker — polls `nomos_plan_executions` |
+| `cmd/nomos/assent.go` | 183 | `isAssent`/`isTypedConfirmation` — regex word-boundary matching (fixed 2026-07-11 after a false-positive bug where "yesterday" matched "yes") |
+
+### nomos — Behavior specific to this component
+
+The Task lifecycle and auto-continuation sequences are in
+[README.md §3.4](README.md#34-functional-flow--the-task-lifecycle-f3f4f5-packaged-for-a-human)
+and [§6.5](README.md#65-sequence--plan-auto-continuation-the-system-is-the-event-loop).
+Specific to this component: the LLM sees a **union of two tool sources** —
+the 33 tools fetched live from `api`'s `/mcp` endpoint via `tools/list`,
+plus the 5 local task tools in `tasks.go` — and `agent.go`'s per-call
+routing decides in-process versus forwarded with no visible seam to the
+model itself. A hidden `_session_id` is injected into forwarded calls on
+the wire (never in the model-visible arguments) so `internal/mcp/server.go`
+can scope assent/destructive windows per task.
+
+### nomos — Interfaces this component owns
+
+| Route | Auth |
+|---|---|
+| `GET /healthz` | none |
+| `POST /query` (structured tool call or a pointer to `/chat`) | **none** |
+| `POST /chat` (SSE, the real agentic loop) | **none** |
+| `GET/POST /sessions`, `/sessions/{id}` | **none** |
+
+This entire interface is unauthenticated — full detail in
+[README.md §5.4](README.md#54-nomos-http-interface-cmdnomos-port-8092).
+Outbound: a pooled MCP client to `api`, and chat completions to OpenRouter
+(`data_collection: deny` pinned, default model `deepseek/deepseek-v4-pro`).
+
+### nomos — Status and known issues
+
+- **C1, the most consequential open gap involving this component**: zero
+  authentication on the entire gateway, including the ability to grant
+  chat-assent approvals with no credential check. Explicitly deferred by
+  operator instruction, not an oversight — see
+  [README.md §8.4](README.md#84-known-open-security-gaps).
+- `nomos/config.yaml`'s `max_iterations: 15` does not match the enforced
+  Go constant (`40`) — one of the two is stale.
+- Dual `agent_activity` logging: both this component's `store.logActivity`
+  and `internal/mcp/server.go`'s `withActivityLogging` (a different
+  component) log the same forwarded tool call. Not confirmed whether this
+  is an intentional two-sided audit trail or accidental duplication.
+
+---
+
+## 5. web control room
+
+**Stakeholders:** the operator, directly; engineers changing the UI's data
+model or adding a page. **Why this View earns its place:** this is the only
+component with no server-side logic of its own — understanding it means
+understanding what it *doesn't* do (it is not the system of record for
+anything) as much as what it does.
+
+### web control room — Internal structure
+
+Nine pages under `web/src/pages/` (Svelte 5, hash-based routing, no router
+library):
+
+| Page | Lines | Shows |
+|---|---|---|
+| `Overview.svelte` | 262 | Task dashboard — fleet/health/signal summary cards, the task list, entry point for launching a new chat |
+| `Chat.svelte` | 410 | The conversation UI — streaming, `TaskContextPanel`, tool-call rendering, inline approvals |
+| `Ops.svelte` | 240 | Approvals queue, recent activity/execution feed, approve/deny/cancel |
+| `Signals.svelte` | 171 | Alert/signal triage — severity filter, ack/resolve/mute |
+| `KnowledgeBase.svelte` | 263 | Entity browser — force-directed graph view and table view |
+| `Knowledge.svelte` | 186 | Free-text knowledge search |
+| `Learning.svelte` | 174 | Pattern/skill telemetry — the one page whose backing data source
+(`internal/learning`) is dormant per §7 below, so this page currently shows
+whatever accumulated before the engine stopped being called, not a live
+feed |
+| `Config.svelte` | 202 | Auth/connection screen — static bearer token or OIDC login |
+| `EntityDetail.svelte` | 7 | Thin wrapper, deep-link target |
+
+Shared logic under `web/src/lib/`: `config.ts` (`fetchWithAuth`, the single
+wrapper every API call goes through), `oidc.ts`, `api.ts`, `tasks.ts`,
+`stores/events.ts` (the always-on SSE connection), plus task-specific
+components (`TaskContextPanel.svelte`, `GoalHeader.svelte`,
+`PlanProgress.svelte`, `OperatorQuestion.svelte`, `SessionGraph.svelte`).
+
+### web control room — Behavior specific to this component
+
+Two data-flow patterns, not one: most pages fetch REST on mount and
+re-fetch on a relevant SSE event; `Chat.svelte`'s `TaskContextPanel` is
+driven by the **always-on global event stream**
+(`web/src/lib/stores/events.ts`), not the per-turn chat SSE connection —
+deliberately, so the live context panel stays populated during
+server-side auto-continuation (§4 above) when no chat turn is actually
+open, and survives a tab reload.
+
+### web control room — Interfaces this component owns
+
+None inbound — it is a pure consumer of `internal/httpapi`'s REST and SSE
+interfaces (full catalog: [README.md §5](README.md#5-interfaces-icd)).
+`fetchWithAuth` resolves config per request rather than at import time, so
+the same build works same-origin (production, Vite dev proxy) or
+cross-origin (the Wails desktop webview, §8).
+
+### web control room — Status and known issues
+
+Standalone deploy, versioned and released independently of the `oikos`
+binary — see [README.md §4.5](README.md#45-build--release-artifacts) for
+why "deployed" means two different release cadences depending on whether
+you mean the container or the desktop app. The shell-level architecture
+(window manager, app registry, docked layer) is documented separately as
+[§9 below](#9-web-control-room--app-architecture); this section covers
+the page-level concerns, §9 covers the OS + Apps contract the pages hang
+off.
+
+---
+
+## 6. PostgreSQL/TimescaleDB
+
+**Stakeholders:** anyone writing a migration, or reasoning about what
+"the system's source of truth" actually means (see
+[framework.md §2](framework.md#2-the-goal--system-and-model-made-concrete)
+for why that phrase needs disambiguating from the engineering Model).
+**Why this View earns its place:** every other component in this document
+either reads from or writes to this one; it is the only component every
+other component has in common.
+
+### PostgreSQL/TimescaleDB — Internal structure
+
+20 forward-only, idempotent migrations
+(`001_ontology.up.sql` … `020_session_reliability.up.sql`,
+[ADR-0008](../adr/0008-forward-only-migrations.md)). Four TimescaleDB
+hypertables, all created in `006_observability.up.sql`:
+`metric_samples`, `audit_log`, `events`, `agent_activity` — each with
+continuous aggregates and retention policies.
+
+The recurring structural pattern across this schema, per
+[ADR-0014](../adr/0014-entity-model.md) §7: **dual entities** —
+`check_defs`, `signals`, `classifications`, `executions`, `feedback`,
+`patterns`, `skills`, `approvals`, `knowledge_entities`, and (as of
+migration 018) `agent_sessions`-as-`task` all have an
+`entity_id UUID PK REFERENCES entities(id)`, meaning every specialized row
+is simultaneously a node in the general entity graph — this is what lets
+`get_relations`/`get_blast_radius` work uniformly over signals, tasks, and
+infrastructure alike without a special case for each.
+
+Partial unique indexes provide snapshot semantics without an application-
+level lock: `relationships` (current edges only), `signals` (one open
+signal per entity+kind), `patterns` (one per type+action).
+
+### PostgreSQL/TimescaleDB — Behavior specific to this component
+
+`008_event_notify.up.sql`'s `pg_notify` trigger on `events` INSERT is the
+entire mechanism behind [README.md's SSE interface](README.md#55-server-sent-events-internalhttpapissego)
+— the database, not the API process, is what decides an event happened;
+the API process is just a fan-out listener.
+
+### PostgreSQL/TimescaleDB — Interfaces this component owns
+
+Every Go component in this document connects directly (via `sqlc`-generated
+queries, `internal/db`) — there is no ORM abstraction layer and no
+component-specific access restriction beyond what each service's own
+Postgres role grants (notably: the learning engine's DB role has no grants
+on governance/autonomy tables, per
+[ADR-0006](../adr/0006-learning-proposal-only.md) — a structural guarantee
+that would matter the moment §7's dormant learning engine is wired back in).
+`seeds/*.yaml` + `oikos seed`/`oikos export` form the bootstrap/DR
+interface — the database can be regenerated from seeds, and seeds can be
+regenerated from the database.
+
+### PostgreSQL/TimescaleDB — Status and known issues
+
+A shared-Postgres single point of failure across every service is a
+documented residual risk in [ADR-0007](../adr/0007-threat-model.md), not a
+newly discovered one.
+
+---
+
+## 7. Dormant components
+
+**Stakeholders:** anyone deciding whether to revive auto-act, or tempted to
+extend `internal/actuator`/`internal/learning` believing them to be the
+live implementation. **Why this View earns its place:** these are the two
+components most likely to mislead an engineer navigating by package name —
+both are substantial, well-written, and compile cleanly into the `oikos`
+binary, and neither runs.
+
+### Dormant components — Internal structure
+
+| File | Lines | Role, and why it's dormant |
+|---|---|---|
+| `internal/actuator/actuator.go` | 505 | `Run` (L24-41, 10s ticker), `processAutoActSignals`, kill-switch checks (L47, L69 — `getAutonomySetting` for `global.auto_act` and `never_auto_act.<slug>`), a real circuit breaker (L156-202, threshold + cooldown), advisory locking (L87-99) — **but the executor itself is a hardcoded stub**, `{"success": true, "message": "stub execution"}` (L124-137), and `Run()` is never called by `cmd/oikos/main.go` or any `docker-compose.yml` service |
+| `internal/actuator/ssh.go` | 291 | `ExecuteProcedure` (L126-230) — a fully-built step-by-step SSH runner with `classifySSHError` (L77-108: network/auth/timeout/remote), per-step timeouts, verify-step semantics. **Zero callers anywhere in the codebase.** |
+| `internal/learning/learning.go` | 183 | `Run` (L20-41, hourly ticker), `extractPatterns` (L45-81), `processGroup` (L83-169, Wilson lower-bound confidence, evidence≥5 ∧ confidence≥0.7 → `validated`, anomaly quarantine at >10 same-key events per pass) — algorithmically faithful to [ADR-0006](../adr/0006-learning-proposal-only.md), **never started by any process** |
+
+### Why this matters more than "unused code"
+
+`internal/actuator/actuator.go` is where the policy kill-switch
+(`global.auto_act`, `never_auto_act.*`) is actually checked in Go — the
+*only* other place is the dead `policy.ClassifySignal`. Reviving auto-act
+and fixing the kill-switch gap
+([README.md §8.1](README.md#81-the-kill-switch-gap-verified-most-important-finding-in-this-model))
+are, structurally, **the same piece of work** — whoever picks up
+`internal/actuator/actuator.go:47-69` is the person who also resolves
+REQ-DEC-5. This is stated explicitly here because it is not obvious from
+reading the Risk & Safety or Roadmap views in isolation; it only becomes
+visible once you've read this component's code.
+
+### Dormant components — Status and known issues
+
+This entire section *is* the known issue — see
+[README.md §9.1](README.md#91-the-north-star-general-gated-execution)
+("revive auto-act," the one item the `general-gated-execution` plan's own
+header still marks open) and
+[§9.4](README.md#94-suggested-next-steps-informational--not-a-commitment-not-a-plan)
+item 1 and 3 for the two decisions this leaves open: wire these back in, or
+delete them and correct the "Phase 3 — DONE" claim in
+`OIKOS.md`/ADR-0014 that currently overstates what's running.
+
+---
+
+## 8. Auxiliary components
+
+Two small, single-purpose components that support deployment and
+packaging rather than decision logic — given lighter treatment here
+deliberately, since no Stakeholder identified in this document's other
+sections needs their internals to make a change elsewhere.
+
+**`cmd/webhook`** (96 lines, one file) — the Gitea push-to-deploy receiver.
+Verifies `X-Hub-Signature-256` HMAC-SHA256 against `WEBHOOK_HMAC_SECRET`
+using `hmac.Equal`, responds `202` immediately, then runs
+`scripts/deploy.sh` asynchronously. Full deploy sequence:
+[README.md §4.2](README.md#42-deployment-topology-mac-mini-docker-compose)
+and §7.2.
+
+**`cmd/desktop`** (784 lines) — the Wails-wrapped desktop shell. Bundles
+`web/dist` into a native binary, adds an OIDC login flow through a local
+HTTP server + system browser, and a `SaveConfig` bridge the web bundle
+calls when running inside the desktop webview (`web/src/lib/config.ts`'s
+`saveToDesktop()`). Contains no decision logic of its own — it is
+packaging for component 5 (§5 above), not a new component in the
+functional sense.
+
+---
+
+## 9. web control room — App architecture
+
+**Stakeholders:** anyone adding a page, adding a desktop overlay, or
+planning dynamic/third-party app installation. **Why this View earns its
+place:** §5 documents the *pages*; this View documents the *shell* they
+hang off — and the shell is the part whose contract a new app has to
+satisfy. It is also the layer where the "Oikos-as-OS" metaphor
+(desktop, icons, floating windows, a tamagotchi-style resident
+creature) is actually implemented, so the boundary between "Base OS" and
+"App" has to be explicit here or it doesn't exist anywhere.
+
+### App architecture — Internal structure
+
+| File | Role |
+|---|---|
+| `web/src/lib/apps.ts` | The App registry. Two layers: `builtinApps` (static, always installed) + `installedAppIds` (persisted, from the App Store). The public `apps` store is derived (built-in + installed); `appById` is a derived Map. `installApp`/`uninstallApp` mutate the installed set. Window-id helpers (`appWindowId`, `appIdFromWindowId`) unchanged. |
+| `web/src/app-store/catalog.ts` | The installable-app catalog: `AppManifest` (persistable metadata) + `CatalogEntry` (manifest + Lucide icon + dynamic-import loader). Static in Phase 3 (apps ship with the build); Phase 4 swaps this for a fetched `/api/v1/apps` endpoint. Declares `AppPermission` (enforcement is Phase 4). |
+| `web/src/app-store/apps/Notes.svelte` | Demo installable app — a localStorage-backed scratchpad proving the install→icon→window→uninstall lifecycle end-to-end. |
+| `web/src/lib/stores/windows.ts` | The wmkit window manager singleton + the `openAppWindow` / `openEntityWindow` / `openTaskWindow` primitives. `openAppWindow` branches on `docked` (toggles visibility) vs windowed (`wm.open`); resolves the app via `get(appById)`. |
+| `web/src/lib/stores/docked.ts` | Persisted visibility for docked apps. Absent key = visible (default-on); store holds only overrides. Deliberately does **not** import `APPS` — doing so would create a static cycle (`apps.ts` → pages → `windows.ts` → here → `apps.ts`) and fire a TDZ on `APPS` at init. |
+| `web/src/lib/stores/icons.ts` | Desktop icon grid: column/row positions, drag-to-reorder, localStorage persistence. Reactive to the `apps` store — a newly-installed app gets a free cell on the next emission; `resetIconLayout` re-seeds from the live registry, not a static snapshot. |
+| `web/src/lib/components/LazyApp.svelte` | Renders an app's lazily-loaded component (`AppDef.component` is a dynamic-import loader, not the component). Shows the shared spinner while the chunk fetches; used by both WindowLayer and DockedLayer so the loading state is uniform across app kinds. Vite's module cache makes repeat opens resolve from cache. |
+| `web/src/lib/components/desktop-shell/Desktop.svelte` | Full-viewport surface: background, icons, task launcher, `<WindowLayer />`, `<DockedLayer />`, taskbar. Reads `$apps` (the derived store) so installs reflect immediately. |
+| `web/src/lib/components/desktop-shell/WindowLayer.svelte` | Floating-window stack (z-40). Resolves window id → content component; renders shared titlebar chrome. The orphan-close `$effect` is reactive on `$appById` — reinstalling an app revives its persisted window, uninstalling closes it. |
+| `web/src/lib/components/desktop-shell/DockedLayer.svelte` | Docked-app overlay (z-45). Renders `$apps.filter(a => a.docked)` gated on `dockedVisibility`. Replaces the previously-hardcoded `<MascotLayer />`. |
+| `web/src/lib/components/desktop-shell/Taskbar.svelte` | Window buttons + tray. Renders from `wmState.order`; resolves icons via `$appById`. |
+| `web/src/pages/AppStore.svelte` | The App Store — lists the catalog, shows install state, install/uninstall. Installing makes the app appear on the desktop immediately (no reload) via the reactive `apps` store; uninstalling closes any open window for that app via WindowLayer's orphan-close effect. |
+
+### App architecture — The App contract
+
+```typescript
+interface AppDef {
+  id: string                 // unique; window IDs are "app:<id>"
+  title: string              // desktop icon label + window titlebar
+  icon: Component            // Lucide icon (desktop icon + taskbar)
+  component: () => Promise<{ default: Component }>  // dynamic-import loader
+  docked?: boolean           // true = Docked Layer app, no window
+  noIcon?: boolean           // true = registered but no desktop icon
+  width?: number; height?: number; minWidth?: number; minHeight?: number
+                             // required for windowed, forbidden for docked
+  badge?: (s: DashboardSummary | null) => number
+}
+```
+
+`component` is a dynamic-import loader (`() => import('../pages/X.svelte')`),
+not the component itself. Desktop icons render from metadata alone (id,
+title, icon — all static), the component chunk fetches on first window
+open, and Vite code-splits each app into its own chunk (Phase 2). The
+mascot uses the same path — `() => import('./mascot/MascotLayer.svelte')`
+— which also defers the mascot's module graph until after `apps.ts` has
+finished initializing, breaking what would otherwise be a static cycle
+(`apps.ts` → `MascotLayer` → `Mascot.svelte` → `icons.ts` → `apps.ts`).
+
+Two app kinds, picked by one flag:
+
+| Kind | Window | Titlebar | Taskbar | Opened by |
+|---|---|---|---|---|
+| **Windowed** (default) | wmkit floating window | yes | yes | `openAppWindow` → `wm.open` |
+| **Docked** (`docked: true`) | none — renders on the Docked Layer | no | no | `openAppWindow` → `toggleDocked` |
+
+Apps receive **no props** from the shell. They import the OS-service
+surface (below) directly. The shell→app edge is one-way.
+
+### App architecture — The OS-service surface (AppOS)
+
+The stable set of `$lib` exports an App may import. Everything else in
+`$lib` is shell-internal and may change without notice. This is a
+**documentation contract** today (apps are compiled in); it becomes an
+**enforced sandbox boundary** the moment third-party app installation
+(Phase 3 in [the plan](../../plans/2026-07-21-frontend-os-apps-architecture.md)) lands.
+
+| Service | Import |
+|---|---|
+| Open an app window | `openAppWindow(id)` from `$lib/stores/windows` |
+| Open an entity window | `openEntityWindow(slug)` from `$lib/stores/windows` |
+| Open a task window | `openTaskWindow(sessionId, title)` from `$lib/stores/windows` |
+| Dashboard summary | `summary`, `subscribeContext` from `$lib/stores/context` |
+| Live events | `subscribeEvents` from `$lib/stores/events` |
+| Per-session chat / workspace / activity | `chatFor`, `workspaceFor`, `activityLogFor` from `$lib/stores/{chat,workspace,activity}` |
+| REST API | `$lib/api` (generated from OpenAPI, [ADR-0004](../adr/0004-openapi-first.md)) |
+| UI primitives | `$lib/components/ui/*` |
+| Theme | `getTheme`, `setTheme` from `$lib/stores/theme.svelte` |
+
+### App architecture — Content resolution
+
+Window ids are namespaced so the window layer resolves content purely
+from the id, with no extra bookkeeping — which is also why persisted
+windows hydrate correctly across reloads:
+
+| Id shape | Renders |
+|---|---|
+| `app:<id>` | the registry app's component (`appById.get(id).component`) |
+| `session:<id>` | `SessionChatWindow` (per-session chat) |
+| `new-task` | `NewTaskChat` (singleton compose) |
+| bare slug (`type:identifier`) | `EntityDetailContent` (fallback) |
+
+A hydrated `app:<id>` window whose id no longer matches a registry entry
+(an app removed since the layout was persisted) self-closes — the
+orphan-close `$effect` in `WindowLayer.svelte` sweeps it on mount.
+
+### App architecture — Current population
+
+Seven windowed apps + one docked app:
+
+| App | Kind | Badge |
+|---|---|---|
+| `tasks` | windowed | — |
+| `kb` | windowed | — |
+| `ops` | windowed | `approvals_pending` |
+| `signals` | windowed | open signal count |
+| `knowledge` | windowed | — |
+| `learning` | windowed | — |
+| `settings` | windowed | — |
+| `mascot` (Cluck) | **docked** | — |
+
+The mascot is the first docked app and the reason the docked kind
+exists; before this View it was a hardcoded `<MascotLayer />` in
+`Desktop.svelte`, not a registry entry. Its persistent model
+(`web/src/lib/mascot/state.svelte.ts`, localStorage) and sprite cache
+(`sprites.ts`) are module-scoped, so toggling visibility (unmount) and
+restoring (remount) loses no state — this is why `docked` visibility is
+a plain `{#if}` gate rather than a `keepAlive` mechanism.
+
+### App architecture — Designed extension points (documented, not built)
+
+| Extension | Mechanism when built | Trigger |
+|---|---|---|
+| Titlebar actions | `titlebarActions?: Component` on `AppDef`, rendered left of min/max/close | First app that needs one |
+| App-scoped state | `state?: () => Record<string, unknown>` on `AppDef` | First app with cross-mount state that isn't module-scoped |
+| `onRegister` handshake | called with a scoped AppOS capability object | Phase 3 (dynamic install) |
+| Third-party manifests | `AppManifest` JSON + `/api/v1/apps` + permission model | Phase 3 |
+
+Documenting these now prevents the current contract from painting itself
+into a corner; building them now would be speculative. (Lazy-loaded
+components were on this list and shipped in Phase 2 — `component` is now
+`() => Promise<{ default: Component }>` and Vite code-splits each app.)
+
+### App architecture — Status and known issues
+
+Phase 1 (the docked kind, mascot-as-app, the docked visibility store) and
+Phase 2 (lazy component loading — `component` as dynamic-import loader,
+`LazyApp.svelte` for uniform loading state, per-app code-splitting) have
+landed. Open items, by phase:
+
+- **Phase 3 (dynamic install):** the AppOS table above becomes a real
+  injected capability object, not a documentation table; permissions
+  enforced at the store-access boundary; `AppManifest` format +
+  `/api/v1/apps` endpoint + install flow.
+- **Late-registering apps (Phase 3 prerequisite):** `icons.ts:48` builds
+  `appIds` once at module load to validate persisted positions — fine
+  today (all apps are in the static `APPS` array; only their components
+  are lazy), fragile the moment apps register post-load. When dynamic
+  registration lands, revalidate against the live registry, not the
+  import-time snapshot. Likewise `WindowLayer`'s orphan-close `$effect`
+  must be gated on registry-ready so a not-yet-loaded app's persisted
+  window isn't killed on hydration.
+
+The static-cycle trap that bit this View during Phase 1 implementation is
+now resolved by Phase 2's lazy loading — recording it for context:
+
+- `apps.ts` no longer statically imports any page or the mascot (they're
+  all `() => import(...)`), so there's no static edge from `apps.ts` into
+  the mascot/page module graph to cycle through `icons.ts` back to `APPS`.
+  The earlier `LazyMascot.svelte` wrapper (Phase 1's cycle break) was
+  deleted in Phase 2 — the lazy loader in the registry replaces it.
+  `docked.ts` still must not import `APPS` (it's reached from `apps.ts`'s
+  graph via `windows.ts`), and doesn't — defaults are implicit
+  (absent key = visible).
+
+---
+
+## Keeping this document current
+
+The same discipline as README.md's closing note applies here, scoped to
+components: when a file listed in a "Internal structure" table is renamed,
+split, or gains a new responsibility, update that row. When a "Status and
+known issues" bullet is resolved, remove it — and check whether removing it
+also resolves an entry in
+[README.md §9](README.md#9-roadmap--traceability), since most of the
+findings here were first surfaced there and are repeated in this document
+for proximity to the code, not because they're independently tracked in
+two places.

docs/mbse/framework.md

@@ -0,0 +1,414 @@
+# Oikos — MBSE Framework, Ontology & Viewpoints
+
+> Companion to [the system Model](README.md). Where `README.md` **is** the
+> Model — the populated Views — this document is the **Framework**: the
+> template those Views were built from. It follows Jon Holt, *Systems
+> Engineering Demystified* (2nd ed., 2023), Ch. 2, "Model-Based Systems
+> Engineering," almost to the letter — the terms below (Model, View,
+> Viewpoint, Notation, Ontology, Framework, Process Set, Compliance) are
+> Holt's, not a paraphrase, because the whole point of adopting an Ontology
+> is to stop each document inventing its own vocabulary.
+
+> **Holt's core claim, stated once so it doesn't need restating per
+> section:** *"When the Ontology and the Viewpoints are put together, they
+> form what is known as a Framework. A Framework is created as a template,
+> or blueprint, for a complete Model."* (Ch. 2, p. 40). Ontology is, in
+> Holt's words, "arguably the single most important part of MBSE as all of
+> the other elements that make up MBSE are ultimately traceable back to the
+> Ontology" (p. 40).
+
+## 1. MBSE in a Slide — applied to Oikos
+
+Holt's book converges the whole chapter into one diagram known across the
+Systems Engineering community as "MBSE in a slide" (Holt & Perry, 2019),
+extended with Implementation and Compliance. Below is that same structure
+with every box filled in for this specific repository, not left generic.
+
+```mermaid
+flowchart TB
+    subgraph APPROACH["APPROACH \n what must be produced, and how"]
+        FW["Framework \n Ontology + Viewpoints \n = this document"]
+        PS["Process Set \n ADRs, plans, this repo's\nreview/CI conventions"]
+    end
+
+    subgraph GOAL["GOAL \n why any of this exists"]
+        SYS["System \n the hubris homelab,\ngoverned by Oikos"]
+        MDL["Model \n README.md \n the nine Views"]
+    end
+
+    subgraph VIS["VISUALIZATION \n how it is communicated"]
+        NOT["Notation \n Markdown + Mermaid"]
+        DIA["Diagrams \n flowchart, stateDiagram,\nsequenceDiagram, classDiagram"]
+    end
+
+    subgraph IMPL["IMPLEMENTATION"]
+        TOOL["Tools \n git, a Markdown renderer,\nMermaid; no dedicated\nSysML tool"]
+    end
+
+    subgraph COMP["COMPLIANCE"]
+        BP["Best Practice \n ISO 42010 viewpoint and view\nterminology, informally aligned,\nnot certified"]
+    end
+
+    FW --> MDL
+    PS --> MDL
+    MDL --> SYS
+    NOT --> DIA
+    DIA --> MDL
+    TOOL --> NOT
+    TOOL --> FW
+    BP --> PS
+    BP --> FW
+```
+
+| Holt's concept | Generic definition (Ch. 2) | Oikos instantiation |
+|---|---|---|
+| **System** | The thing Systems Engineering exists to develop | The **hubris homelab** — hosts, LXCs, VMs, services, network — *and* the Oikos control plane that governs it. See note below on the reflexive boundary. |
+| **Model** | The abstraction of the System; the single source of truth for engineering knowledge about it | [README.md](README.md) — the nine-View system model |
+| **View** | A validated collection of information within the Model | Each of README.md's nine numbered sections |
+| **Viewpoint** | The template for a View — the stored answers to *which Stakeholders, why, what information* | §4 of this document — the Viewpoint catalog |
+| **Ontology** | The domain-specific language every Viewpoint's content is expressed in | §3 of this document, and — distinctively for this system — literally implemented in code as `seeds/ontology.yaml` |
+| **Notation** | The spoken/visual language used to communicate a View | Markdown prose + Mermaid diagrams (flowchart, stateDiagram-v2, sequenceDiagram, classDiagram) |
+| **Diagram** | One rendering of a View through a Notation's lens | Each Mermaid block in README.md |
+| **Framework** | Ontology + Viewpoints, together | This document |
+| **Process Set** | The steps for developing and using the Framework — the "how" | This repo's ADR process ([docs/adr/](../adr/)), design-doc process (`plans/`), and the research-then-write method used to build README.md (see its own header note on verified vs. per-research-pass findings) |
+| **Tool** | What implements the Notation and the Framework | Git + a Markdown/Mermaid renderer for the Notation; no dedicated MBSE tool enforces the Framework — see §6 for the honest gap this leaves |
+| **Compliance** | Demonstrating the approach meets external best practice | §5 |
+
+**On the System's boundary being reflexive.** Most MBSE textbook examples
+model a System that is wholly separate from the engineering process
+describing it (a car, a radar). Oikos is not: the System being modeled
+*is* an autonomous control system, and the Model describing it (this
+documentation) sits outside a boundary that the System itself polices with
+its own internal "model" — the Postgres database, which
+[ADR-0003](../adr/0003-db-native-ontology-yaml-seeds.md) calls the runtime
+single source of truth. These are two different, non-competing uses of
+"model": the **engineering Model** (this doc set) is Holt's sense — a
+human-facing abstraction for realizing the System successfully. The
+**runtime database** is an operational sense — the System's own record of
+its current state, which the engineering Model *describes* but does not
+*replace*. Conflating the two would suggest this documentation is
+authoritative over live state, which it explicitly is not — README.md's
+own verification discipline (verified vs. per-research-pass) exists
+precisely because the engineering Model can drift from what the database
+and code actually do.
+
+## 2. The Goal — System and Model, made concrete
+
+**The System**, enumerated (this is "taking all the components of the
+system," per Holt's instruction that a valid View must be traceable to
+real Stakeholders and real information — not an abstract diagram):
+
+| Component | Role |
+|---|---|
+| `oikos api` (`internal/httpapi`, `internal/mcp`) | REST + MCP server, the decision/execution gate |
+| `oikos scheduler` (`internal/scheduler`) | Observe loop — probes, signals |
+| `oikos notifier` (`internal/notifier`) | Approval delivery — Matrix, token issuance |
+| `nomos` (`cmd/nomos`) | The AI agent — MCP client, task/plan orchestration |
+| `web` (Svelte 5 SPA) | Control-room UI |
+| PostgreSQL/TimescaleDB | The System's own runtime source of truth |
+| The managed fleet | Hosts, LXCs, VMs, services under Oikos's governance |
+| `internal/actuator`, `internal/learning` | Compiled into the System, **not** currently part of its running behavior — see README.md §9.2 |
+
+**The Model** is [README.md](README.md) in full: nine Views (Mission,
+Requirements, Functional Architecture, Physical Architecture, Interfaces,
+Behavior, Verification & Validation, Risk & Safety, Roadmap &
+Traceability). Per Holt's consistency test (p. 35): *"If there is a set of
+Views where each View is consistent with all other Views, then it is a
+Model. If there is a set of Views where each View is not consistent with
+all other Views, then it is data."* README.md's own cross-referencing
+(§8.1's kill-switch finding surfaced in §2's requirement, §3's function
+table, and §9's roadmap alike) is what keeps it a Model rather than nine
+unrelated documents.
+
+## 3. The Ontology — Oikos's domain-specific language
+
+Holt's Ontology has two jobs: it is the vocabulary every Viewpoint's
+content must be expressed in, and it is what makes Views from different
+parts of the Model comparable rather than coincidentally similar-looking.
+Oikos needs this at two levels, and — unusually for a Holt-style
+exercise — one of them was **already built in code**, not invented for
+this documentation pass.
+
+### 3.1 Layer A — the SE meta-ontology (concepts used to talk *about* the Model)
+
+This is the vocabulary this Framework document and README.md are written
+in. It is Holt's own vocabulary, restated as a concept diagram rather than
+prose, per his own example in the book (a Need Description View "visualized
+using UML Notation — specifically, a Diagram known as the class diagram,
+where each need is represented as a UML class," p. 38):
+
+```mermaid
+classDiagram
+    class System
+    class Model {
+      +isSingleSourceOfTruth bool
+    }
+    class View {
+      +stakeholders
+      +value
+      +information
+    }
+    class Viewpoint {
+      +stakeholderQuestion
+      +valueQuestion
+      +informationQuestion
+    }
+    class Notation
+    class Diagram
+    class Ontology
+    class Framework
+    class ProcessSet
+    class Stakeholder
+
+    Model "1" --> "1" System : abstracts
+    Model "1" o-- "many" View : is made up of
+    View ..|> Viewpoint : conforms to
+    View "1" --> "1..many" Diagram : visualized through
+    Diagram "many" --> "1" Notation : belongs to
+    Viewpoint "many" --> "1" Ontology : traces terminology to
+    Framework "1" o-- "1" Ontology : contains
+    Framework "1" o-- "many" Viewpoint : contains
+    Stakeholder "many" --> "many" Viewpoint : interested in
+```
+
+### 3.2 Layer B — the Oikos domain ontology (the concepts inside the Views)
+
+This is the part that already exists as running code, not something this
+documentation pass invented: `seeds/ontology.yaml` (952 lines, ingested by
+migration `001_ontology.up.sql` into the `entity_types`/`relationship_types`
+tables) *is* Holt's Ontology for this System — a machine-enforced
+domain-specific language that every Signal, Execution, Approval, and Task
+discussed anywhere in the Model traces back to. The full treatment — all 60
+entity types, the complete 47-relationship catalog (verified directly
+against the seed file; [ADR-0014](../adr/0014-entity-model.md) §1/§4
+records an earlier 2026-07-08 snapshot of 56 types and 34 relationships,
+since grown), and all six registered lifecycle state machines — is
+[ontology.md](ontology.md), Viewpoint 11 below. What follows here is the
+condensed version, sufficient only to make this section's point:
+
+```mermaid
+classDiagram
+    class Entity {
+      +UUID id
+      +string slug
+      +string type
+      +string state
+    }
+    class ComputeEntity
+    class Network
+    class Container
+    class Service
+    class Agent
+    class Signal {
+      +string kind
+      +string severity
+      +string state
+    }
+    class Classification {
+      +string riskClass
+      +string route
+    }
+    class Execution {
+      +string status
+    }
+    class Approval {
+      +string status
+    }
+    class Pattern {
+      +float confidence
+      +string status
+    }
+    class Skill
+    class Task {
+      +string goal
+      +string status
+      +string outcome
+    }
+    class KnowledgeEntity
+
+    Entity <|-- ComputeEntity
+    Entity <|-- Network
+    Entity <|-- Container
+    Entity <|-- Service
+    Entity <|-- Agent
+    Entity <|-- Signal
+    Entity <|-- Classification
+    Entity <|-- Execution
+    Entity <|-- Approval
+    Entity <|-- Pattern
+    Entity <|-- Skill
+    Entity <|-- Task
+    Entity <|-- KnowledgeEntity
+
+    Signal "many" --> "1" Entity : about
+    Classification "1" --> "1" Signal : classifies
+    Classification "1" --> "1" Execution : precedes
+    Execution "many" --> "1" Entity : targets
+    Execution "many" --> "1" Agent : performs
+    Approval "1" --> "1" Execution : decides
+    Task "1" --> "many" Execution : requests via run
+    Task "many" --> "many" Entity : involves
+    KnowledgeEntity "many" --> "many" Entity : about
+    KnowledgeEntity "many" --> "1" Task : outcome_of
+    Pattern "1" --> "many" Execution : informed_by
+```
+
+**This is the elegant accident worth naming plainly:** Oikos was not built
+by someone following Holt's method, yet its own architecture independently
+arrived at "the domain concepts are an Ontology, ingested once, and
+everything else traces back to it" — `seeds/ontology.yaml` → DB tables →
+every entity, signal, execution, and relationship in the system. That is
+Holt's Ontology principle, implemented as infrastructure rather than as a
+documentation artifact. The gap is not that the Ontology is missing; it's
+that, until this document, nothing had stated the correspondence between
+"the ontology" as oikos's engineers already use the word and "the Ontology"
+as Holt's MBSE method uses it. They are the same thing, at the domain
+layer.
+
+### 3.3 Where Layer A and Layer B meet
+
+Layer A (SE meta-ontology) is what makes README.md's Views *disciplined* —
+each one answers Holt's three questions (§4 below). Layer B (the Oikos
+domain ontology) is what makes README.md's Views *say the same thing
+consistently* — "risk class," "entity," "signal," and "execution" mean one
+thing throughout the whole Model because they mean one thing in
+`seeds/ontology.yaml`, not because nine separately-written documents
+happened to agree.
+
+## 4. The Viewpoint Catalog — the Framework's template for Views
+
+Per Holt (p. 39-40), a Viewpoint stores the answers to three questions —
+*which Stakeholders, why (what value), what information* — plus a fourth,
+*what Notation* — so that every View built from it is automatically
+consistent. Below is that template applied retroactively to each of
+README.md's nine Views, which is itself a useful audit: a View that can't
+honestly answer these four questions is not a valid View by Holt's own
+test (p. 35), and is a candidate for removal.
+
+| Viewpoint | Which Stakeholders (§1.2) | Why — what value | What information | Notation |
+|---|---|---|---|---|
+| **1. Mission & Context** | Operator; future engineers/agents onboarding | Establishes why design choices elsewhere aren't arbitrary; sets the system boundary so later Views don't have to re-litigate scope | Mission statement, stakeholder table, mission drivers, boundary diagram, operational concept | Prose + flowchart |
+| **2. Requirements** | Operator; anyone implementing against a requirement | Traces every "the system shall" back to a source and forward to an implementation status, so intent and reality can be compared | Requirement ID, statement, source, status, organized by OODA phase + NFRs | Structured table |
+| **3. Functional Architecture** | Engineers extending decision/execution logic | Prevents the single most expensive mistake in this codebase — extending the wrong package because it has the right name | Function decomposition, function-to-component allocation (expected vs. actual owner), the `run` gate flow, the Task lifecycle | flowchart + allocation table |
+| **4. Physical Architecture** | Operator deploying/debugging the stack; on-call | Answers "what is actually running and where" independent of what the code *could* do | Component block diagram, deployment topology, trust zones, external couplings | flowchart |
+| **5. Interfaces (ICD)** | Anyone integrating a new MCP client, or reading/writing the API | A single place to find every tool/route/event without reading source | MCP tool catalog, REST groups, SSE event types, auth model | Tables |
+| **6. Behavior** | Engineers reasoning about a specific flow (an approval, a task) end to end | State machines and sequences are where "is this actually enforced" questions get answered, not functional prose | Signal/Execution/Approval state machines, `run`-gate sequence, auto-continuation sequence, Task sequence | stateDiagram-v2 + sequenceDiagram |
+| **7. Verification & Validation** | Operator deciding whether to trust a change; anyone auditing test coverage | Distinguishes "we checked this" from "we assume this" | CI pipeline, evals, health checks as continuous verification, deploy/rollback, explicit list of what's *not* covered | Prose + flowchart |
+| **8. Risk & Safety** | Operator; anyone reasoning about blast radius of agent autonomy | The single highest-consequence question this Model answers: what actually stops a bad action | Kill-switch gap finding, defense-in-depth layers, threat model, known open gaps, what's structurally guaranteed | Prose + tables |
+| **9. Roadmap & Traceability** | Operator planning what to fix next; future documentation maintainers | The authoritative status matrix every other View's ✅/⚠/❌ marker derives from | North-star status, code-real/dead-code/schema-only matrix, doc/code divergences, suggested next steps | Tables |
+| **10. Component** *(repeating Viewpoint — one View per component)* | An engineer about to change a specific package | Prevents extending the wrong implementation of something that exists twice (§9.2's dead-code/live-code pairs), or missing a known issue local to that package | Internal structure (files, key functions, file:line), behavior specific to that component, interfaces it owns, known issues — instantiated once per component in [components.md](components.md) | flowchart + tables |
+| **11. Ontology** *(repeating Viewpoint — one View per ontology facet)* | An engineer adding/changing an entity or relationship type; anyone checking whether a term used elsewhere in the Model traces back to something real | Is the check against Holt's own biggest MBSE risk (p. 35) applied to the Ontology itself — prevents treating the domain vocabulary as informal prose when it's actually a machine-enforced schema with real transition gates | Entity type hierarchy, relationship catalog, lifecycle state machines with their `requires:` gates, concrete population — instantiated as four Views in [ontology.md](ontology.md) | graph + stateDiagram-v2 + tables |
+
+**Three things this table makes visible that weren't visible before:**
+
+1. Every Viewpoint's "why" is stated in terms of a **decision or mistake it
+   prevents**, not merely a topic it covers — closer to Holt's requirement
+   that a View "must add value" (p. 35) than a topic-based table of
+   contents would be.
+2. Viewpoints 10 and 11 are structurally different from 1-9: each is a
+   **repeating Viewpoint** — one template, instantiated multiple times.
+   Viewpoint 10 produces eight Views, once per component
+   ([components.md](components.md)); Viewpoint 11 produces four, once per
+   ontology facet ([ontology.md](ontology.md)). Holt's method doesn't
+   forbid this; a Viewpoint is a template, and nothing says a template can
+   only be used once.
+3. There is still no Viewpoint in this catalog for "document every class
+   exhaustively regardless of whether anyone asked" — Viewpoints 10 and 11
+   are scoped to named, narrow Stakeholder questions ("an engineer about to
+   change this component," "an engineer adding a new type"), not a blanket
+   documentation mandate.
+   Per Holt's own worked example (the Need Description View, p. 38-39), a
+   collection of information that can't name an interested Stakeholder is
+   not a View; it would just be generated documentation nobody reads,
+   which is the exact failure mode Holt calls out as the biggest risk in
+   adopting MBSE (p. 35).
+
+## 5. Compliance
+
+Holt names three categories of best-practice source (p. 46) a Framework
+can be checked against. Being direct about which apply here and which
+don't, rather than implying certification that doesn't exist:
+
+| Category | Holt's examples | Oikos's position |
+|---|---|---|
+| **Process-based standards** (how work is done) | ISO 15288 | Not formally adopted. This repo's own process conventions (ADRs, `plans/`, PR review) are the de facto Process Set — informally rigorous, not standards-mapped. |
+| **Framework-based standards** (what information is produced) | ISO 42010, MODAF, DoDAF, NAF, UAF, Zachman | **Informally aligned, not certified.** This Framework borrows ISO 42010's Viewpoint/View vocabulary (which Holt's own method is built on) but has not been checked against the standard's actual conformance clauses. Say this plainly rather than imply an audit that hasn't happened. |
+| **Application-based standards** (domain-specific: safety, security, usability) | — | Partially present in spirit: [Risk & Safety](README.md#8-risk--safety) documents a real threat model and known gaps, but there is no adopted external security standard (e.g., no formal threat-modeling framework like STRIDE was used — the threat model in ADR-0007 is bespoke). |
+
+The honest summary: this Framework's compliance posture is **methodological
+alignment with ISO 42010's core idea (Stakeholders → concerns → Viewpoints
+→ Views), not standards certification.** Claiming more than that would
+itself violate the documentation set's own governing discipline (state
+verified findings as verified, not aspirational ones as achieved).
+
+## 6. Tools — Implementation, and its honest limit
+
+Holt is specific that a good MBSE tool does two things: it *implements the
+Notation* (enforces SysML's syntax/semantics the way a word processor
+enforces spelling) and it *implements the Framework* (has the Ontology and
+Viewpoints "programmed into it" as a profile, p. 44-45).
+
+Neither is true here, and it matters to say so:
+
+- **Notation tooling**: Markdown + Mermaid, rendered by GitHub/a Markdown
+  viewer. Mermaid's flowchart/stateDiagram/sequenceDiagram/classDiagram
+  grammars are enforced (a malformed diagram fails to render — as
+  happened once already in this documentation effort and was fixed), but
+  there is no semantic check that, say, a state machine diagram in
+  [§6](README.md#6-behavior) actually matches the Go code's real
+  transitions. That check was done by hand, once, for this pass — it will
+  drift the moment the code changes and nobody re-verifies it.
+- **Framework tooling**: there is no tool with this Ontology or these
+  Viewpoints "programmed in." Nothing prevents a future edit to README.md
+  from adding a View that fails Holt's three-question test, or from
+  introducing a term that doesn't trace back to `seeds/ontology.yaml`.
+  The only enforcement mechanism is a human (or an agent) re-reading this
+  Framework document before extending the Model — which is precisely why
+  this document needed to exist as a separate, explicit artifact rather
+  than staying implicit in how README.md happened to get organized.
+
+## 7. Process Set — how this Framework is developed and used
+
+Holt separates Framework (what) from Process Set (how) specifically so
+that different projects can share one Framework under different levels of
+rigor (p. 41-42). For this repository, the Process Set is:
+
+1. **Establishing a new Viewpoint**: propose it here in §4, answering all
+   four questions before writing the View it justifies. If it can't answer
+   them, per Holt's own rule (p. 35), it doesn't get written.
+2. **Extending the Ontology**: changes to `seeds/ontology.yaml` are the
+   authoritative act — this document's §3.2 is a description of that file,
+   not an independent source, and must be re-derived from it if it drifts.
+3. **Updating a View**: per README.md's own closing section ("Keeping this
+   model current"), a code change updates the View whose Viewpoint claims
+   that information, and — if it resolves or introduces a finding in
+   [§9 Roadmap & Traceability](README.md#9-roadmap--traceability) — that
+   matrix is updated in the same pass.
+4. **Compliance review**: informal, human-in-the-loop (§5) — there is no
+   scheduled re-audit; drift is caught opportunistically, the same way the
+   kill-switch gap in [§8.1](README.md#81-the-kill-switch-gap-verified-most-important-finding-in-this-model)
+   was caught by direct verification during a documentation pass rather
+   than by a standing process designed to catch it.
+
+## 8. Relationship between this Framework and the Model
+
+```mermaid
+flowchart LR
+    ONT["Ontology \n seeds and ADR-0014"] --> FW["Framework \n this document"]
+    VP["Viewpoint catalog \n Section 4 of this document"] --> FW
+    FW --> MDL["Model \n README.md, Viewpoints 1 to 9"]
+    FW --> CV["Model \n components.md, Viewpoint 10\nrepeated per component"]
+    FW --> OV["Model \n ontology.md, Viewpoint 11\nrepeated per ontology facet"]
+    MDL --> V1["View 1..9"]
+    CV --> V2["View 10a..10h"]
+    OV --> V3["View 11a..11d"]
+```
+
+Read [README.md](README.md) for the Model's concern-based Views,
+[components.md](components.md) for its component-based Views, and
+[ontology.md](ontology.md) for the Ontology's own full treatment (the
+sketch in §3 above is deliberately condensed). Read this document when you
+are deciding whether a new View belongs in any of the three, when a term in
+the Model feels like it's drifted from what `seeds/ontology.yaml` actually
+defines, or when onboarding someone who needs to understand not just *what
+the system is* but *why this documentation is shaped the way it is*.

docs/mbse/ontology.md

@@ -0,0 +1,444 @@
+# Oikos — Ontology Views
+
+> Companion to [the Framework](framework.md), [the Model](README.md), and
+> [the Component Views](components.md). Holt calls Ontology "arguably the
+> single most important part of MBSE, as all of the other elements that
+> make up MBSE are ultimately traceable back to [it]" (*Systems Engineering
+> Demystified*, 2nd ed., Ch. 2, p. 40). [framework.md §3](framework.md#3-the-ontology--oikoss-domain-specific-language)
+> sketched this in condensed form (13 classes) to make one point: Oikos's
+> domain ontology already exists as running code, not documentation. This
+> document is the fuller treatment that sketch promised — a repeating
+> Viewpoint (registered as Viewpoint 11 in
+> [framework.md §4](framework.md#4-the-viewpoint-catalog--the-frameworks-template-for-views)),
+> instantiated as four Views below.
+
+**Every fact in this document was read directly from `seeds/ontology.yaml`
+during this pass** (not carried over from ADR-0014's summary, though it is
+cross-checked against it) — where the two disagree, that disagreement is
+itself reported as a finding, not silently reconciled.
+
+**Stakeholders for all four Views below:** engineers adding a new entity or
+relationship type, anyone reasoning about whether a lifecycle transition is
+actually gated or just documented, and anyone deciding whether a term used
+elsewhere in this documentation set means what they think it means.
+**Why they earn their place:** every Viewpoint in
+[framework.md §4](framework.md#4-the-viewpoint-catalog--the-frameworks-template-for-views)
+"traces terminology to the Ontology" (§3.1 of that document) — these four
+Views are where that tracing actually terminates. **Notation:** tables
+(the source data), Mermaid `graph`/`stateDiagram-v2` (the structure).
+
+## Contents
+
+| View | Answers |
+|---|---|
+| [11a. Entity Type Hierarchy](#11a-entity-type-hierarchy) | What can exist, and how is it classified? |
+| [11b. Relationship Catalog](#11b-relationship-catalog) | How can two entities be connected, and with what multiplicity? |
+| [11c. Lifecycle State Machines](#11c-lifecycle-state-machines) | What states can a governed entity be in, and what gates each transition? |
+| [11d. Concrete Population](#11d-concrete-population) | What's actually instantiated, versus merely possible? |
+
+---
+
+## 11a. Entity Type Hierarchy
+
+60 entity types, 5 abstract (cannot be instantiated directly — they exist
+only as polymorphic relationship endpoints and `is-a` parents), organized
+by `domain:` (8 values) and `layer:` (4 values: meta, infrastructure,
+governance, cognition).
+
+| Layer | Domains it contains | Entity type count |
+|---|---|---|
+| `meta` | meta | 1 (`entity`, the abstract root) |
+| `infrastructure` | physical, compute, network, storage, software, external | 40 |
+| `governance` | identity | 7 |
+| `cognition` | cognition | 12 |
+
+| Domain | Count | Abstract types in this domain |
+|---|---|---|
+| compute | 11 | `compute-entity`, `machine`, `container` |
+| network | 10 | `network` |
+| cognition | 12 | *(none)* |
+| identity | 7 | *(none)* |
+| software | 7 | *(none)* |
+| external | 4 | *(none)* |
+| storage | 4 | *(none)* |
+| physical | 4 | *(none)* |
+| meta | 1 | `entity` |
+
+One 60-node diagram doesn't fit on a screen and, worse, tempts you to fall
+back on subgraph grouping instead of explicit edges for the flatter
+domains — which is what an earlier version of this section did: most leaf
+types were boxed together visually but had no drawn `-->` from `entity` at
+all. Split by domain instead, every type below has an explicit parent
+edge — nothing is implied by proximity alone.
+
+### Layer overview
+
+```mermaid
+graph TD
+    entity["entity — abstract root\nlayer: meta"] --> INFRA["infrastructure layer\n40 types — physical, compute, network,\nstorage, software, external"]
+    entity --> GOV["governance layer\n7 types — identity domain"]
+    entity --> COG["cognition layer\n12 types"]
+```
+
+### Domain: physical (4 types, all flat)
+
+```mermaid
+graph TD
+    entity["entity"] --> site
+    entity --> ups
+    entity --> sensor
+    entity --> peripheral
+```
+
+### Domain: compute (11 types — the deepest nesting in the Ontology)
+
+```mermaid
+graph TD
+    entity["entity"] --> ce["compute-entity — abstract"]
+    entity --> hypervisor
+    ce --> machine["machine — abstract"]
+    ce --> vm
+    ce --> container["container — abstract"]
+    machine --> proxmoxhost["proxmox-host"]
+    machine --> standalone["standalone-server"]
+    machine --> workstation
+    machine --> appliance
+    container --> lxc
+    container --> dockercontainer["docker-container"]
+```
+
+### Domain: network (10 types)
+
+```mermaid
+graph TD
+    entity["entity"] --> net["network — abstract"]
+    entity --> netiface["network-interface"]
+    entity --> dnszone["dns-zone"]
+    entity --> dnsrecord["dns-record"]
+    entity --> ingress["ingress-route"]
+    entity --> certificate
+    entity --> firewallrule["firewall-rule"]
+    net --> lan
+    net --> mesh
+    net --> vlan
+```
+
+### Domain: storage (4 types, all flat)
+
+```mermaid
+graph TD
+    entity["entity"] --> storagepool["storage-pool"]
+    entity --> volume
+    entity --> backuptarget["backup-target"]
+    entity --> dataset
+```
+
+`storage-pool`/`volume`/`dataset` look like they should nest (a pool
+*contains* volumes, a volume *holds* datasets) — they don't, in the type
+hierarchy. That containment is a **relationship** (`contains`,
+`holds-dataset`, [§11b](#11b-relationship-catalog)), not an `is-a` parent.
+Worth stating plainly since the two are easy to conflate: `parent:` says
+"this is a kind of that"; a relationship says "this instance is connected
+to that instance." Storage is the domain where the difference is most
+visible.
+
+### Domain: software (7 types, all flat)
+
+```mermaid
+graph TD
+    entity["entity"] --> service
+    entity --> application
+    entity --> configrepo["config-repo"]
+    entity --> deploypipeline["deploy-pipeline"]
+    entity --> packageset["package-set"]
+    entity --> cluster
+    entity --> composestack["compose-stack"]
+```
+
+### Domain: external (4 types, all flat)
+
+```mermaid
+graph TD
+    entity["entity"] --> domainreg["domain-registration"]
+    entity --> cloudservice["cloud-service"]
+    entity --> isplink["isp-link"]
+    entity --> vendordep["vendor-dependency"]
+```
+
+### Domain: identity (governance layer, 7 types, all flat)
+
+```mermaid
+graph TD
+    entity["entity"] --> person
+    entity --> agent
+    entity --> idp["identity-provider"]
+    entity --> account
+    entity --> secret
+    entity --> key
+    entity --> accessgrant["access-grant"]
+```
+
+### Domain: cognition (12 types, all flat — the domain the agent's own logic runs on)
+
+```mermaid
+graph TD
+    entity["entity"] --> check
+    entity --> signal
+    entity --> classification
+    entity --> execution
+    entity --> feedback
+    entity --> pattern
+    entity --> skill
+    entity --> approval
+    entity --> document
+    entity --> runbook
+    entity --> investigation
+    entity --> task["task — added after ADR-0014"]
+```
+
+Every one of the 60 types above is a direct or indirect child of `entity`;
+none is disconnected. The full flat list — every type with its exact
+`parent:` — lives in `seeds/ontology.yaml` directly; reproducing all 60
+rows as a table here would duplicate this section rather than clarify it.
+
+**Finding: `task` is new since ADR-0014.** ADR-0014 (2026-07-08) documents
+56 entity types under a hierarchy diagram that does not include `task` —
+four fewer than the 60 verified here, meaning more than just `task` was
+added in the interim (`task` accounts for one of the four) —
+[README.md §1.5](README.md#15-operational-concept--the-ooda-loop) and
+[framework.md §2](framework.md#2-the-goal--system-and-model-made-concrete)
+both describe the Task model as a 2026-07-11 addition
+(`plans/done/2026-07-11-goal-oriented-chat-control-panel.md`), after
+ADR-0014 was written. `task` is now entity type #60, `domain: cognition`,
+`layer: cognition`, described in the seed as *"A goal-structured unit of
+agent work — one chat/session elevated to a task with a plan, lifecycle
+status, and outcome."* This is exactly what Holt's Ontology principle
+predicts: a new concept in the Model
+([the Task lifecycle View](README.md#34-functional-flow--the-task-lifecycle-f3f4f5-packaged-for-a-human))
+required a new term in the Ontology before it could be modeled
+consistently — and the term was in fact added, not left implicit.
+
+## 11b. Relationship Catalog
+
+**47 relationship types**, each with a fixed `source → target` type pair
+and a cardinality. This is the complete, current catalog — not the
+5 illustrative example-graphs ADR-0014 used to gesture at a smaller set.
+
+**Finding: this catalog has grown since ADR-0014.** ADR-0014 (2026-07-08)
+titles its equivalent section "The Edge Catalog (34 edges)." Verified
+directly against `seeds/ontology.yaml` during this pass: **47** relationship
+types exist today — 13 more than ADR-0014 recorded. This is expected drift
+over an 8-day span of active development (the Task model alone plausibly
+added `involves`; `part-of` supports the `compose-stack` grouping), not a
+documentation error — ADR-0014 is a point-in-time record and is not edited
+after acceptance, per this repo's own convention
+([docs/adr/README.md](../adr/README.md)). It is reported here so nobody
+treats ADR-0014's count as current.
+
+| Relationship | Source → Target | Cardinality |
+|---|---|---|
+| `hosts` | machine → compute-entity | one-to-many |
+| `runs-hypervisor` | machine → hypervisor | one-to-one |
+| `member-of` | proxmox-host → cluster | many-to-one |
+| `part-of` | docker-container → compose-stack | many-to-one |
+| `provides` | compute-entity → service | one-to-many |
+| `runs` | service → application | one-to-many |
+| `configured-by` | entity → config-repo | many-to-one |
+| `deploys-to` | deploy-pipeline → entity | many-to-one |
+| `routes-to` | ingress-route → service | many-to-one |
+| `secured-by` | ingress-route → identity-provider | many-to-one |
+| `uses-certificate` | ingress-route → certificate | many-to-one |
+| `authenticates-via` | service → identity-provider | many-to-one |
+| `in-zone` | dns-record → dns-zone | many-to-one |
+| `resolves-to` | dns-record → entity | many-to-one |
+| `depends-on` | service → service | many-to-many |
+| `connects-via` | compute-entity → network | many-to-many |
+| `has-interface` | compute-entity → network-interface | one-to-many |
+| `interface-on` | network-interface → network | many-to-one |
+| `mounts` | compute-entity → volume | many-to-many |
+| `stores-on` | compute-entity → storage-pool | many-to-many |
+| `contains` | storage-pool → volume | one-to-many |
+| `holds-dataset` | volume → dataset | one-to-many |
+| `backs-up-to` | entity → backup-target | many-to-many |
+| `powered-by` | machine → ups | many-to-one |
+| `located-at` | machine → site | many-to-one |
+| `registered-with` | domain-registration → vendor-dependency | many-to-one |
+| `owns` | person → agent | one-to-many |
+| `authenticates` | identity-provider → person | one-to-many |
+| `holds-grant` | agent → access-grant | one-to-many |
+| `grants` | access-grant → secret | many-to-one |
+| `can-decrypt` | compute-entity → secret | many-to-many |
+| `checks` | check → entity | many-to-one |
+| `raises` | check → signal | one-to-many |
+| `about` | entity → entity | many-to-many |
+| `classifies` | classification → signal | many-to-one |
+| `precedes` | classification → execution | one-to-one |
+| `targets` | execution → entity | many-to-one |
+| `requires-approval` | execution → approval | one-to-one |
+| `performs` | agent → execution | one-to-many |
+| `decides` | person → approval | one-to-many |
+| `produces` | execution → feedback | one-to-one |
+| `contributes-to` | feedback → pattern | many-to-many |
+| `informs` | pattern → skill | many-to-one |
+| `guides` | skill → classification | one-to-many |
+| `documents` | document → entity | many-to-one |
+| `involves` | task → entity | many-to-many |
+| `procedure-for` | runbook → entity | many-to-many |
+
+Grouped by theme, the same 47 rows read as five coherent sub-ontologies —
+this is the grouping ADR-0014 used, now complete rather than illustrative:
+
+```mermaid
+graph LR
+    subgraph Cognition["Cognition — the OODA edges"]
+        CK["check"] -->|raises| SG["signal"]
+        CK -->|checks| EN["entity"]
+        CL["classification"] -->|classifies| SG
+        CL -->|precedes| EX["execution"]
+        EX -->|targets| EN
+        EX -->|requires-approval| AP["approval"]
+        AG["agent"] -->|performs| EX
+        PR["person"] -->|decides| AP
+        EX -->|produces| FB["feedback"]
+        FB -->|contributes-to| PT["pattern"]
+        PT -->|informs| SK["skill"]
+        SK -->|guides| CL
+        TK["task"] -->|involves| EN
+        DC["document"] -->|documents| EN
+        RB["runbook"] -->|procedure-for| EN
+    end
+```
+
+```mermaid
+graph LR
+    subgraph Governance["Governance — identity and access"]
+        P["person"] -->|owns| A["agent"]
+        IDP["identity-provider"] -->|authenticates| P
+        A -->|holds-grant| AG["access-grant"]
+        AG -->|grants| S["secret"]
+        CE["compute-entity"] -->|can-decrypt| S
+    end
+```
+
+The remaining three groups (Infrastructure Topology, Network, Service
+Dependencies) are unchanged in shape from
+[ADR-0014 §4](../adr/0014-entity-model.md) — that ADR's diagrams for those
+three are still an accurate illustrative subset of the table above; only
+the Cognition and Governance groups gained new edges (`involves`,
+`part-of`) worth re-drawing.
+
+## 11c. Lifecycle State Machines
+
+Six lifecycles are formally registered in `seeds/ontology.yaml`'s
+`lifecycles:` block, each a named state machine with `states`,
+`default_state`, `terminal_states`, and per-transition `requires:` — named
+checks that [internal/ontology](../../internal/ontology) implements in Go.
+This is the mechanism, not just the diagram: a transition without a
+satisfied `requires:` check is refused at the code level, for these six
+types.
+
+**Refinement to README.md's Behavior view.** The `execution` lifecycle as
+registered here has **13 states**, including a `verifying` state distinct
+from `executing`, and a recovery transition `timed_out → verifying`
+("check if the command completed anyway" — the seed's own comment).
+[README.md §6.2](README.md#62-execution-state-machine--schema-defined-convention-enforced)'s
+Execution state diagram previously omitted `verifying` as a separate
+state and has been corrected there to match; the diagram below is the
+ontology-accurate version and the two now agree.
+
+```mermaid
+stateDiagram-v2
+    [*] --> proposed
+    proposed --> approved: operator-approval
+    proposed --> auto_approved: autonomy-allows
+    proposed --> denied
+    approved --> executing: approval-token-valid
+    approved --> expired: approval-ttl-elapsed
+    auto_approved --> executing
+    executing --> verified: verification-passed
+    executing --> failed
+    executing --> timed_out
+    executing --> cancelled: operator-abort
+    timed_out --> verifying: check if it finished anyway
+    verifying --> verified: verification-passed
+    verifying --> failed
+    failed --> rolled_back: rollback-procedure-exists
+    failed --> rollback_failed
+    verified --> [*]
+    denied --> [*]
+    expired --> [*]
+    cancelled --> [*]
+    rolled_back --> [*]
+    rollback_failed --> [*]
+```
+
+The other five, with their `requires:` gates named explicitly (abbreviated
+where a transition has no requirement):
+
+| Lifecycle | States | Terminal | Notable gated transition |
+|---|---|---|---|
+| `infrastructure` | planned, provisioning, active, migrating, failed, deprecated, destroyed | destroyed | `deprecated → destroyed` requires **five** checks at once: `backups-verified`, `secrets-revoked-and-rekeyed`, `ingress-and-dns-removed`, `no-inbound-edges`, `archaeology-entry` — the strictest single transition in the entire Ontology |
+| `signal` | raised, acknowledged, acting, muted, resolved, failed | resolved | `acknowledged → acting` requires `classification-exists` — the formal link between Orient and Decide, real in the Ontology even though [Roadmap §9.2](README.md#92-code-real--dead-code--schema-only-matrix) finds the classifier that would create that classification is dead code |
+| `approval` | pending, approved, denied, expired, revoked | denied, expired, revoked | `pending → approved` requires `token-verified`; `approved → revoked` requires `not-yet-executing` — you cannot revoke an approval whose action has already started |
+| `pattern` | hypothesized, validated, active, deprecated, invalidated | deprecated, invalidated | `hypothesized → validated` requires `evidence-count-5plus` **and** `confidence-0.7plus` jointly — matches [ADR-0006](../adr/0006-learning-proposal-only.md)'s Wilson-bound description exactly; `validated → active` requires `operator-approval`, annotated in the seed itself as *"S4: never automatic"* |
+| `skill` | drafted, tested, active, refined, failed, deprecated | deprecated | `tested → active` and `refined → active` both require `operator-approval` — a skill can be authored and tested autonomously but never self-promotes to active |
+
+**Finding: `task` has no registered lifecycle.** The `task` entity type
+(§11a) has a real, documented behavior —
+[README.md §3.4](README.md#34-functional-flow--the-task-lifecycle-f3f4f5-packaged-for-a-human)
+shows `planning → awaiting_approval → executing ⇄ awaiting_input → done`/`failed`
+as a state diagram, and it is enforced in application code (the
+`agent_sessions.status` column, checked in `cmd/nomos`). But
+`seeds/ontology.yaml`'s `lifecycles:` block registers only the six
+machines above — there is no `task:` entry alongside `infrastructure`,
+`signal`, `execution`, `approval`, `pattern`, `skill`. Practically: the
+five other governed types get their transition-gating for free from the
+shared `internal/ontology` machinery (per named `requires:` checks); the
+Task lifecycle is instead hand-coded in `cmd/nomos`'s Go logic, a
+structurally different (and unaudited-by-the-shared-mechanism) enforcement
+path for what is, in every other respect, a first-class Ontology citizen.
+This is a gap worth a deliberate decision — register `task` formally, or
+document explicitly that Task's lifecycle is intentionally
+application-layer rather than Ontology-layer — not an oversight this
+document is fixing by writing it down.
+
+## 11d. Concrete Population
+
+What's actually instantiated versus merely possible in the type system —
+per [ADR-0014](../adr/0014-entity-model.md) §1, **not independently
+re-counted against the live database during this pass** (that would
+require DB access this documentation effort didn't use; the figures below
+are ADR-0014's, dated 2026-07-08, and should be treated as illustrative of
+shape rather than a current census):
+
+| Type | Count (as of ADR-0014) | Examples |
+|---|---|---|
+| `lxc` | 19 | jellyfin, caddy, dns, gitea, nextcloud, matrix |
+| `service` | 25 | caddy, authentik, dns, jellyfin, paperless, matrix |
+| `ingress-route` | 21 | `*.hubris.network` |
+| `config-repo` | 6 | caddy-conf, gitea-customizations, mule-image |
+| `proxmox-host` | 2 | hubris, strong |
+| `workstation` | 2 | mac-mini, republic-laptop |
+| `standalone-server` | 1 | netbird-vps |
+| `vm` | 2 | zimaos, haos |
+| `storage-pool` | 3 | local-lvm-hubris, library-hubris, ludo-lvm |
+| `volume` | 2 | library, media-local |
+
+**Why this View matters despite being the least current one here:** it is
+the check against over-abstraction Holt warns about (p. 35) — an Ontology
+with 60 types and 47 relationships is only worth having if real entities
+actually populate a meaningful fraction of it. 88 active entities across
+roughly a dozen concrete types (out of 55 non-abstract types) is a
+reasonable population for a homelab of this size; a future re-audit of this
+specific View is a cheap, well-scoped follow-up (query `entities GROUP BY
+type`) that this pass explicitly did not do, rather than silently assuming
+ADR-0014's numbers still hold.
+
+## Keeping this document current
+
+Re-derive §11a-11c directly from `seeds/ontology.yaml` whenever it changes
+— these three Views are transcriptions of that file's structure, not
+independent judgment, so they go stale the moment the file changes and
+nobody re-runs the extraction. §11d is the one View here that was already
+known to be a point-in-time snapshot when written; re-verify it against
+live DB state before relying on it for a capacity or audit decision.

docs/operations/README.md

@@ -0,0 +1,18 @@
+# Operations runbooks
+
+Step-by-step procedures for operating the homelab. These complement the
+agent-facing skill files in [`.agents/skills/`](../../.agents/skills/) (which
+are machine-actionable) and the deploy scripts in
+[`scripts/`](../../scripts/) (which are executable).
+
+| Runbook | Scope |
+| ------- | ----- |
+| [rollback.md](rollback.md) | Rollback a deploy: checkout SHA + pg_restore |
+
+For the deploy pipeline itself see
+[`scripts/deploy.sh`](../../scripts/deploy.sh), the watchdog at
+[`scripts/watchdog.sh`](../../scripts/watchdog.sh), and the cutover checklist
+at [`scripts/cutover-checklist.md`](../../scripts/cutover-checklist.md). The
+risk classification for any mutation is defined in
+[`seeds/policy.yaml`](../../seeds/policy.yaml) — run `oikos` MCP `preflight`
+to check the class before acting.

evals/golden.yaml

@@ -0,0 +1,55 @@
+# Golden conversation evals for the nomos agent.
+# Run: go run ./cmd/nomos/eval -gateway http://localhost:8092 -manifest evals/*.yaml
+#
+# Each conversation costs real OpenRouter credits (~$0.01–0.05). The runner
+# sends the prompt, waits for the turn to finish, optionally sends a followup,
+# and scores assertions against the final persisted transcript.
+#
+# These are STRUCTURAL assertions only — tool-call sequences, plan steps,
+# writeback, completion. Text quality is model-dependent and not scored.
+
+# --- eval 1: trivial read-only task (degenerate case) ---
+- name: trivial_readonly
+  prompt: "What is the state of lxc:dns? One line, no plan needed."
+  assertions:
+    - kind: completes
+    - kind: no_propose_plan       # trivial — no ceremony
+    - kind: max_tool_calls
+      value: 5                    # get_entity + complete_task + maybe one more
+    - kind: no_run                # read-only, no `run` needed
+
+# --- eval 2: the operator's original bug — plan + proceed ---
+- name: plan_advances_on_proceed
+  prompt: "Check the uptime of lxc:gitea. Plan it out, propose the plan, then wait for my approval before running anything."
+  followup: "proceed with the rest"
+  assertions:
+    - kind: completes
+    - kind: proposes_plan_once    # propose_plan called exactly once
+    - kind: no_duplicate_proposal # the original bug: re-propose on "proceed"
+    - kind: writes_back           # ran `run` → must update_entity_attributes (D.1)
+    - kind: no_duplicate_complete # C.1 — complete_task called at most once
+
+# --- eval 3: UI complaint should not re-execute (C.2) ---
+- name: ui_complaint_no_rerun
+  prompt: "Check the uptime of lxc:dns. Plan it out and wait for my approval."
+  followup: "go ahead"
+  assertions:
+    - kind: completes
+    - kind: proposes_plan_once
+    - kind: writes_back
+# (The followup "go ahead" is approval, not a UI complaint — we'd test the
+#  complaint path separately with a second followup, but that needs the
+#  session to stay open after completion, which the runner doesn't support yet.
+#  For now this validates the approval-vocabulary path.)
+
+# --- eval 4: knowledge preferred over fleet re-execution (E.1) ---
+# A same-day fleet audit knowledge entry exists in the DB. The agent should
+# search_knowledge first and NOT run `run` against 20 LXCs.
+- name: knowledge_preferred_over_rerun
+  prompt: "Give me an overview of what needs updating across the homelab, categorize by criticality. There may be a recent audit already."
+  assertions:
+    - kind: completes
+    - kind: calls_tool
+      value: search_knowledge      # E.1 — must check the knowledge base first
+    - kind: max_run_calls
+      value: 4                     # NOT 20+ — a targeted refresh only

evals/iteration-followup.yaml

@@ -0,0 +1,18 @@
+# P5 eval: iteration. A read-only task completes; the follow-up asks the
+# agent to act on what it found (a config_mutation). The second followup
+# is the approval ("go ahead") so the plan can execute. Asserts the session
+# reopens, a second plan generation is created, and the agent completes
+# both sub-tasks.
+- name: iteration-followup
+  prompt: "Check the live systemd timer on lxc:rclone — when did the last backup to Proton Drive actually run, and when is the next one scheduled? Inspect the actual service state, don't just read the DB."
+  followups:
+    - "The repos folder failed last time. Reset the failed service and re-run the backup."
+    - "go ahead"
+  assertions:
+    - kind: completes
+    - kind: plan_generations
+      value: 2
+    - kind: proposes_plan
+    - kind: writes_back
+    - kind: max_run_calls
+      value: 40

evals/iteration-readonly.yaml

@@ -0,0 +1,17 @@
+# P5 eval: two read-only sub-tasks back-to-back. The follow-up is also
+# read-only (no approval needed) so the agent can execute immediately after
+# proposing the second plan. Asserts the session reopens and a second plan
+# generation is created.
+- name: iteration-readonly
+  prompt: "Check the live systemd timer on lxc:rclone — when did the last backup to Proton Drive actually run, and when is the next one scheduled?"
+  followups:
+    - "Now check the uptime of lxc:dns."
+  assertions:
+    - kind: completes
+    - kind: plan_generations
+      value: 2
+    - kind: proposes_plan
+    - kind: calls_tool
+      value: run
+    - kind: max_run_calls
+      value: 6

evals/no-plan-no-run.yaml

@@ -0,0 +1,10 @@
+# P5 eval: a pure-DB Q&A that calls NO run. This is the ONLY remaining
+# carve-out from plan-first: a task that never touches a live target via
+# `run` doesn't need propose_plan (the gate only fires on run). Asserts
+# the agent answers directly and completes without ceremony.
+- name: no-plan-no-run
+  prompt: "List all LXC containers and their current health."
+  assertions:
+    - kind: completes
+    - kind: no_run
+    - kind: no_propose_plan

evals/plan-always-readonly.yaml

@@ -0,0 +1,14 @@
+# P5 eval: a read-only question that requires live inspection (not just DB
+# lookup). Asserts the plan-first gate works: the agent must propose_plan
+# before run, even for a trivial read-only task.
+- name: plan-always-readonly
+  prompt: "Check the live systemd timer on lxc:rclone — when did the last backup to Proton Drive actually run, and when is the next one scheduled? Inspect the actual service state, don't just read the DB."
+  assertions:
+    - kind: completes
+    - kind: proposes_plan
+    - kind: plan_before_run
+    - kind: calls_tool
+      value: run
+    - kind: writes_back
+    - kind: max_run_calls
+      value: 6

go.mod

@@ -5,6 +5,7 @@ go 1.26.3
 require (
 	github.com/getkin/kin-openapi v0.140.0
 	github.com/go-chi/chi/v5 v5.3.1
+	github.com/go-chi/cors v1.2.2
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/google/jsonschema-go v0.4.3
 	github.com/google/uuid v1.6.0
@@ -13,6 +14,8 @@ require (
 	github.com/modelcontextprotocol/go-sdk v1.6.1
 	github.com/oapi-codegen/runtime v1.4.2
 	github.com/openai/openai-go v1.12.0
+	github.com/wailsapp/wails/v3 v3.0.0-alpha2.117
+	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/crypto v0.53.0
 	golang.org/x/sync v0.21.0
 	golang.org/x/sys v0.46.0
@@ -24,6 +27,7 @@ require (
 	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
 	cloud.google.com/go/compute/metadata v0.9.0 // indirect
 	cloud.google.com/go/iam v1.1.11 // indirect
+	github.com/adrg/xdg v0.5.3 // indirect
 	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
 	github.com/aws/aws-sdk-go-v2 v1.27.2 // indirect
 	github.com/aws/aws-sdk-go-v2/config v1.27.18 // indirect
@@ -39,12 +43,16 @@ require (
 	github.com/aws/aws-sdk-go-v2/service/sts v1.28.12 // indirect
 	github.com/aws/smithy-go v1.20.2 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/coder/websocket v1.8.14 // indirect
+	github.com/danieljoos/wincred v1.2.3 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-ole/go-ole v1.3.0 // indirect
 	github.com/go-openapi/jsonpointer v0.22.5 // indirect
 	github.com/go-openapi/swag/jsonname v0.25.5 // indirect
 	github.com/go-resty/resty/v2 v2.13.1 // indirect
+	github.com/godbus/dbus/v5 v5.2.2 // indirect
 	github.com/gofrs/flock v0.8.1 // indirect
 	github.com/google/s2a-go v0.1.9 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.3.11 // indirect
@@ -53,6 +61,9 @@ require (
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.2 // indirect
+	github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/oasdiff/yaml v0.1.0 // indirect
 	github.com/oasdiff/yaml3 v0.0.13 // indirect
 	github.com/oracle/oci-go-sdk/v65 v65.95.2 // indirect

go.sum

@@ -7,6 +7,8 @@ cloud.google.com/go/compute/metadata v0.9.0/go.mod h1:E0bWwX5wTnLPedCKqk3pJmVgCB
 cloud.google.com/go/iam v1.1.11 h1:0mQ8UKSfdHLut6pH9FM3bI55KWR46ketn0PuXleDyxw=
 cloud.google.com/go/iam v1.1.11/go.mod h1:biXoiLWYIKntto2joP+62sd9uW5EpkZmKIvfNcTWlnQ=
 github.com/RaveNoX/go-jsoncommentstrip v1.0.0/go.mod h1:78ihd09MekBnJnxpICcwzCMzGrKSKYe4AqU6PDYYpjk=
+github.com/adrg/xdg v0.5.3 h1:xRnxJXne7+oWDatRhR1JLnvuccuIeCoBu2rtuLqQB78=
+github.com/adrg/xdg v0.5.3/go.mod h1:nlTsY+NNiCBGCK2tpm09vRqfVzrc2fLmXGpBLF0zlTQ=
 github.com/apapsch/go-jsonmerge/v2 v2.0.0 h1:axGnT1gRIfimI7gJifB699GoE/oq+F2MU7Dml6nw9rQ=
 github.com/apapsch/go-jsonmerge/v2 v2.0.0/go.mod h1:lvDnEdqiQrp0O42VQGgmlKpxL1AP2+08jFMw88y4klk=
 github.com/aws/aws-sdk-go-v2 v1.27.2 h1:pLsTXqX93rimAOZG2FIYraDQstZaaGVVN4tNw65v0h8=
@@ -40,12 +42,16 @@ github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UF
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cncf/xds/go v0.0.0-20251210132809-ee656c7534f5 h1:6xNmx7iTtyBRev0+D/Tv1FZd4SCg8axKApyNyRsAt/w=
 github.com/cncf/xds/go v0.0.0-20251210132809-ee656c7534f5/go.mod h1:KdCmV+x/BuvyMxRnYBlmVaq4OLiKW6iRQfvC62cvdkI=
+github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
+github.com/coder/websocket v1.8.14/go.mod h1:NX3SzP+inril6yawo5CQXx8+fk145lPDC6pumgx0mVg=
 github.com/coreos/go-systemd/v22 v22.3.2/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
+github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
-github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
+github.com/dlclark/regexp2 v1.11.5 h1:Q/sSnsKerHeCkc/jSTNq1oCm7KiVgUMZRDUoRu0JQZQ=
+github.com/dlclark/regexp2 v1.11.5/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/envoyproxy/go-control-plane v0.14.0 h1:hbG2kr4RuFj222B6+7T83thSPqLjwBIfQawTkC++2HA=
 github.com/envoyproxy/go-control-plane/envoy v1.36.0 h1:yg/JjO5E7ubRyKX3m07GF3reDNEnfOboJ0QySbH736g=
 github.com/envoyproxy/go-control-plane/envoy v1.36.0/go.mod h1:ty89S1YCCVruQAm9OtKeEkQLTb+Lkz0k8v9W0Oxsv98=
@@ -57,11 +63,17 @@ github.com/getkin/kin-openapi v0.140.0 h1:JFn675aXRFjyiZKa/BFWploGldQlI0gobp4J5k
 github.com/getkin/kin-openapi v0.140.0/go.mod h1:lISrB64F0CPcuDJ3LdtPTMJBY8VENjR9wJBdrcT6J3g=
 github.com/go-chi/chi/v5 v5.3.1 h1:3j4HZLGZQ3JpMCrPJF/Jl3mYJfWLKBfNJ6quurUGCf8=
 github.com/go-chi/chi/v5 v5.3.1/go.mod h1:R+tYY2hNuVUUjxoPtqUdgBqevM9s9njzkTLutVsOCto=
+github.com/go-chi/cors v1.2.2 h1:Jmey33TE+b+rB7fT8MUy1u0I4L+NARQlK6LhzKPSyQE=
+github.com/go-chi/cors v1.2.2/go.mod h1:sSbTewc+6wYHBBCW7ytsFSn836hqM7JxpglAy2Vzc58=
+github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e h1:Lf/gRkoycfOBPa42vU2bbgPurFong6zXeFtPoxholzU=
+github.com/go-json-experiment/json v0.0.0-20251027170946-4849db3c2f7e/go.mod h1:uNVvRXArCGbZ508SxYYTC5v1JWoz2voff5pm25jU1Ok=
 github.com/go-logr/logr v1.2.2/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
 github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
 github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
 github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
 github.com/go-openapi/jsonpointer v0.22.5 h1:8on/0Yp4uTb9f4XvTrM2+1CPrV05QPZXu+rvu2o9jcA=
 github.com/go-openapi/jsonpointer v0.22.5/go.mod h1:gyUR3sCvGSWchA2sUBJGluYMbe1zazrYWIkWPjjMUY0=
 github.com/go-openapi/swag/jsonname v0.25.5 h1:8p150i44rv/Drip4vWI3kGi9+4W9TdI3US3uUYSFhSo=
@@ -71,6 +83,8 @@ github.com/go-openapi/testify/v2 v2.4.0/go.mod h1:HCPmvFFnheKK2BuwSA0TbbdxJ3I16p
 github.com/go-resty/resty/v2 v2.13.1 h1:x+LHXBI2nMB1vqndymf26quycC4aggYJ7DECYbiz03g=
 github.com/go-resty/resty/v2 v2.13.1/go.mod h1:GznXlLxkq6Nh4sU59rPmUw3VtgpO3aS96ORAI6Q7d+0=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
+github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
 github.com/gofrs/flock v0.8.1 h1:+gYjHKf32LDeiEEFhQaotPbLuUXjY5ZqxKgXy7n59aw=
 github.com/gofrs/flock v0.8.1/go.mod h1:F1TvTiK9OcQqauNUHlbJvyl9Qa1QvF/gOUDKA14jxHU=
 github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
@@ -101,11 +115,19 @@ github.com/jackc/pgx/v5 v5.10.0 h1:VhSvgU2jSli8o3AqIEOTJr7rZwAEUVo4E4XhR94Zfr0=
 github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
 github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
 github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1 h1:njuLRcjAuMKr7kI3D85AXWkw6/+v9PwtV6M6o11sWHQ=
+github.com/jchv/go-winloader v0.0.0-20250406163304-c1995be93bd1/go.mod h1:alcuEEnZsY1WQsagKhZDsoPCRoOijYqhZvPwLG0kzVs=
 github.com/juju/gnuflag v0.0.0-20171113085948-2ce1bb71843d/go.mod h1:2PavIy+JPciBPrBUjwbNvtwB6RQlve+hkpll6QSNmOE=
 github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/matryer/is v1.4.1 h1:55ehd8zaGABKLXQUe2awZ99BD/PTc2ls+KV/dXphgEQ=
+github.com/matryer/is v1.4.1/go.mod h1:8I/i5uYgLzgsgEloJE1U6xx5HkBQpAZvepWuujKwMRU=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/modelcontextprotocol/go-sdk v1.6.1 h1:0zOSupjKUxPKSocPT1Wtago+mUHU2/uZ4xSOY0FGReU=
 github.com/modelcontextprotocol/go-sdk v1.6.1/go.mod h1:kzm3kzFL1/+AziGOE0nUs3gvPoNxMCvkxokMkuFapXQ=
 github.com/oapi-codegen/nullable v1.1.0 h1:eAh8JVc5430VtYVnq00Hrbpag9PFRGWLjxR1/3KntMs=
@@ -142,6 +164,8 @@ github.com/spkg/bom v0.0.0-20160624110644-59b7046e48ad/go.mod h1:qLr4V1qq6nMqFKk
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
 github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
@@ -159,12 +183,16 @@ github.com/tidwall/pretty v1.2.1 h1:qjsOFOWWQl+N3RsoF5/ssm1pHmJJwhjlSbZ51I6wMl4=
 github.com/tidwall/pretty v1.2.1/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
 github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
+github.com/wailsapp/wails/v3 v3.0.0-alpha2.117 h1:udyjqPG3AIgkod5QDR/WblCkpV8R86BFPSrsWxSyt5Y=
+github.com/wailsapp/wails/v3 v3.0.0-alpha2.117/go.mod h1:74WH2FScMsgucZvHHvv7eOefDXCm/CjuIxqhhZgPhKg=
 github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
 github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
 github.com/yuin/goldmark v1.4.0/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
+github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
 go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
 go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
 go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.61.0 h1:q4XOmH/0opmeuJtPsbFNivyl7bCt7yRBbeEm2sC/XtQ=
@@ -214,13 +242,16 @@ golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
 golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200810151505-1b9f1253b3ed/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20210809222454-d867a43fc93e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.1.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=

internal/actuator/circuit_breaker_test.go

@@ -0,0 +1,109 @@
+package actuator
+
+import (
+	"testing"
+	"time"
+)
+
+func TestNewCircuitBreakerDefaults(t *testing.T) {
+	cb := newCircuitBreaker(0, 0)
+	if cb.threshold != 3 {
+		t.Errorf("threshold = %d, want 3", cb.threshold)
+	}
+	if cb.cooldownS != 300 {
+		t.Errorf("cooldownS = %d, want 300", cb.cooldownS)
+	}
+
+	cb = newCircuitBreaker(5, 60)
+	if cb.threshold != 5 {
+		t.Errorf("threshold = %d, want 5", cb.threshold)
+	}
+	if cb.cooldownS != 60 {
+		t.Errorf("cooldownS = %d, want 60", cb.cooldownS)
+	}
+}
+
+func TestCircuitBreakerIsOpenFresh(t *testing.T) {
+	cb := newCircuitBreaker(3, 60)
+	if cb.isOpen("host:A") {
+		t.Errorf("fresh circuit should be closed, got open")
+	}
+}
+
+func TestCircuitBreakerOpensAtThreshold(t *testing.T) {
+	cb := newCircuitBreaker(3, 60)
+	// threshold-1 failures → still closed
+	cb.recordFailure("host:A")
+	cb.recordFailure("host:A")
+	if cb.isOpen("host:A") {
+		t.Fatalf("circuit should be closed after threshold-1 failures")
+	}
+	// one more → open
+	cb.recordFailure("host:A")
+	if !cb.isOpen("host:A") {
+		t.Fatalf("circuit should be open after threshold failures")
+	}
+}
+
+func TestCircuitBreakerClosesAfterCooldown(t *testing.T) {
+	cb := newCircuitBreaker(1, 60)
+	// Force open
+	cb.recordFailure("host:A")
+	if !cb.isOpen("host:A") {
+		t.Fatalf("circuit should be open")
+	}
+	// Manipulate the cooldown timestamp to the past to simulate expiry.
+	cb.mu.Lock()
+	cb.cooldowns["host:A"] = time.Now().Add(-1 * time.Second)
+	cb.mu.Unlock()
+
+	if cb.isOpen("host:A") {
+		t.Fatalf("circuit should be closed after cooldown expired")
+	}
+	// Failure count should have been reset by isOpen.
+	cb.mu.Lock()
+	got := cb.failures["host:A"]
+	cb.mu.Unlock()
+	if got != 0 {
+		t.Errorf("failure count after cooldown reset = %d, want 0", got)
+	}
+}
+
+func TestCircuitBreakerRecordSuccessResets(t *testing.T) {
+	cb := newCircuitBreaker(3, 60)
+	cb.recordFailure("host:A")
+	cb.recordFailure("host:A")
+
+	cb.recordSuccess("host:A")
+
+	cb.mu.Lock()
+	got := cb.failures["host:A"]
+	cb.mu.Unlock()
+	if got != 0 {
+		t.Errorf("failure count after success = %d, want 0", got)
+	}
+	if cb.isOpen("host:A") {
+		t.Errorf("circuit should be closed after success reset")
+	}
+}
+
+func TestCircuitBreakerPerTargetIsolation(t *testing.T) {
+	cb := newCircuitBreaker(2, 60)
+	cb.recordFailure("host:A")
+	cb.recordFailure("host:A") // host:A now at threshold → open
+
+	if !cb.isOpen("host:A") {
+		t.Fatalf("host:A should be open")
+	}
+	if cb.isOpen("host:B") {
+		t.Errorf("host:B should be closed (isolated from host:A)")
+	}
+
+	// host:B has no failures recorded
+	cb.mu.Lock()
+	gotB := cb.failures["host:B"]
+	cb.mu.Unlock()
+	if gotB != 0 {
+		t.Errorf("host:B failure count = %d, want 0", gotB)
+	}
+}

internal/actuator/ssh_test.go

@@ -0,0 +1,151 @@
+package actuator
+
+import (
+	"context"
+	"errors"
+	"net"
+	"testing"
+	"time"
+
+	"golang.org/x/crypto/ssh"
+)
+
+func TestSSHErrorClassString(t *testing.T) {
+	cases := []struct {
+		class SSHErrorClass
+		want  string
+	}{
+		{SSHErrorNetwork, "network"},
+		{SSHErrorAuth, "auth"},
+		{SSHErrorTimeout, "timed_out"},
+		{SSHErrorRemote, "remote"},
+		{SSHErrorOther, "other"},
+		{SSHErrorClass(999), "unknown"},
+	}
+	for _, c := range cases {
+		if got := c.class.String(); got != c.want {
+			t.Errorf("SSHErrorClass(%d).String() = %q, want %q", c.class, got, c.want)
+		}
+	}
+}
+
+// timeoutNetErr is a custom net.Error implementation for testing.
+type timeoutNetErr struct {
+	timeout bool
+	msg     string
+}
+
+func (e *timeoutNetErr) Error() string   { return e.msg }
+func (e *timeoutNetErr) Timeout() bool   { return e.timeout }
+func (e *timeoutNetErr) Temporary() bool { return false }
+
+func TestClassifySSHError(t *testing.T) {
+	// ssh.ExitError fields are unexported, but classifySSHError only checks
+	// for the type via errors.As, so the zero value is sufficient.
+	exitErr := &ssh.ExitError{}
+
+	cases := []struct {
+		name string
+		err  error
+		want SSHErrorClass
+	}{
+		{"nil", nil, SSHErrorOther},
+		{"deadline exceeded", context.DeadlineExceeded, SSHErrorTimeout},
+		{"net error timeout true", &timeoutNetErr{timeout: true, msg: "i/o timeout"}, SSHErrorNetwork},
+		{"net error timeout false", &timeoutNetErr{timeout: false, msg: "connection refused"}, SSHErrorNetwork},
+		{"unable to authenticate", errors.New("unable to authenticate, no supported methods remain"), SSHErrorAuth},
+		{"no supported methods remain", errors.New("no supported methods remain (server sent publickey)"), SSHErrorAuth},
+		{"ssh handshake failed", errors.New("ssh: handshake failed: read tcp -> eof"), SSHErrorAuth},
+		{"publickey", errors.New("publickey denied"), SSHErrorAuth},
+		{"permission denied", errors.New("permission denied (publickey)"), SSHErrorAuth},
+		{"exit error", exitErr, SSHErrorRemote},
+		{"generic error", errors.New("something went wrong"), SSHErrorOther},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := classifySSHError(c.err); got != c.want {
+				t.Errorf("classifySSHError(%v) = %v, want %v", c.err, got, c.want)
+			}
+		})
+	}
+}
+
+func TestParseProcedure(t *testing.T) {
+	cases := []struct {
+		name    string
+		data    []byte
+		wantErr bool
+		wantLen int
+	}{
+		{
+			name:    "valid with steps",
+			data:    []byte(`{"steps":[{"runner":"shell","command":"echo hi"}]}`),
+			wantErr: false,
+			wantLen: 1,
+		},
+		{
+			name:    "invalid json",
+			data:    []byte(`{not json`),
+			wantErr: true,
+		},
+		{
+			name:    "empty bytes",
+			data:    []byte{},
+			wantErr: true,
+		},
+		{
+			name:    "valid no steps key",
+			data:    []byte(`{"foo":"bar"}`),
+			wantErr: false,
+			wantLen: 0,
+		},
+		{
+			name:    "valid with extra fields",
+			data:    []byte(`{"extra":"ignored","steps":[{"runner":"verify","command":"true"}],"more":123}`),
+			wantErr: false,
+			wantLen: 1,
+		},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			proc, err := ParseProcedure(c.data)
+			if c.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got nil (proc=%+v)", proc)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if len(proc.Steps) != c.wantLen {
+				t.Errorf("got %d steps, want %d", len(proc.Steps), c.wantLen)
+			}
+		})
+	}
+}
+
+func TestSetDefaultSSHTimeout(t *testing.T) {
+	mu.Lock()
+	orig := defaultSSHTimeout
+	mu.Unlock()
+	defer func() {
+		mu.Lock()
+		defaultSSHTimeout = orig
+		mu.Unlock()
+	}()
+
+	newTimeout := 42 * time.Second
+	SetDefaultSSHTimeout(newTimeout)
+
+	mu.Lock()
+	got := defaultSSHTimeout
+	mu.Unlock()
+
+	if got != newTimeout {
+		t.Errorf("defaultSSHTimeout = %v, want %v", got, newTimeout)
+	}
+}
+
+// Ensure timeoutNetErr satisfies net.Error at compile time.
+var _ net.Error = (*timeoutNetErr)(nil)

internal/audit/audit.go

@@ -0,0 +1,133 @@
+// Package audit produces read-only drift reports over the knowledge graph and
+// monitoring state. It is the shared engine behind the
+// /api/v1/audit/drift endpoint and the audit_knowledge_graph MCP tool.
+//
+// It surfaces the structural gaps an operator otherwise discovers only by
+// accident: orphan check entities, checks targeting retired entities, probes
+// stuck down/unknown, unmonitored declared types, and live edges pointing at
+// destroyed/deprecated targets. Live-infra discovery (pct/docker/certs) is a
+// follow-up that needs host-hop execution; these categories are pure DB
+// queries, so the report is cheap, safe to run unattended, and testable.
+package audit
+
+import (
+	"context"
+
+	"github.com/dtoro/oikos/internal/db"
+)
+
+// Finding is one drift item the operator should look at.
+type Finding struct {
+	Category         string   `json:"category"`
+	Severity         string   `json:"severity"` // info | warning | critical
+	Count            int      `json:"count"`
+	Entities         []string `json:"entities"`
+	Evidence         string   `json:"evidence"`
+	SuggestedRunbook string   `json:"suggested_runbook"`
+}
+
+// Summary tallies findings by category.
+type Summary struct {
+	TotalFindings int            `json:"total_findings"`
+	ByCategory    map[string]int `json:"by_category"`
+}
+
+// Report runs every drift check and returns the findings plus a summary.
+func Report(ctx context.Context, pool *db.Pool) ([]Finding, Summary) {
+	specs := []struct {
+		finding Finding
+		query   string
+	}{
+		{
+			Finding{Category: "orphan_checks", Severity: "warning",
+				Evidence:         "check entities with truncated/random slugs (legacy shortSlug bug), no live target",
+				SuggestedRunbook: "scripts/cleanup-orphan-checks.sh"},
+			`SELECT e.slug FROM entities e
+			 WHERE e.type = 'check'
+			   AND e.slug ~ '^check:(ping|ssh-script|disk):[0-9a-f]{8}$'`,
+		},
+		{
+			Finding{Category: "dead_checks", Severity: "warning",
+				Evidence:         "enabled check_defs whose target entity is deprecated/destroyed",
+				SuggestedRunbook: "lifecycle-deprecate-node / lifecycle-destroy-node"},
+			`SELECT e.slug FROM check_defs cd
+			 JOIN entities e ON e.id = cd.entity_id
+			 JOIN entities tgt ON tgt.id = cd.target_id
+			 WHERE cd.enabled AND tgt.state IN ('deprecated','destroyed')`,
+		},
+		{
+			Finding{Category: "down_checks", Severity: "critical",
+				Evidence:         "enabled checks reporting health=down",
+				SuggestedRunbook: "service-health-check"},
+			`SELECT e.slug FROM check_defs cd JOIN entities e ON e.id = cd.entity_id
+			 WHERE cd.enabled AND cd.last_health = 'down'`,
+		},
+		{
+			Finding{Category: "unknown_checks", Severity: "warning",
+				Evidence:         "enabled checks that ran but reported health=unknown (likely misconfigured probe)",
+				SuggestedRunbook: "knowledge-graph-audit"},
+			`SELECT e.slug FROM check_defs cd JOIN entities e ON e.id = cd.entity_id
+			 WHERE cd.enabled AND cd.last_health = 'unknown'`,
+		},
+		{
+			Finding{Category: "unmonitored", Severity: "warning",
+				Evidence:         "active entities whose type declares monitoring but have no enabled check_def",
+				SuggestedRunbook: "knowledge-graph-audit"},
+			`SELECT DISTINCT e.slug FROM signals sg
+			 JOIN entities e ON e.id = sg.target_entity_id
+			 WHERE sg.kind = 'unmonitored' AND sg.state IN ('raised','acknowledged','acting')`,
+		},
+		{
+			Finding{Category: "dangling_edges", Severity: "warning",
+				Evidence:         "live relationships (hosts/provides/mounts) pointing at destroyed/deprecated targets",
+				SuggestedRunbook: "lifecycle-destroy-node"},
+			`SELECT src.slug || ' -' || r.type || '-> ' || tgt.slug FROM relationships r
+			 JOIN entities src ON src.id = r.source_id
+			 JOIN entities tgt ON tgt.id = r.target_id
+			 WHERE r.valid_to IS NULL
+			   AND src.state NOT IN ('destroyed','deprecated')
+			   AND tgt.state IN ('destroyed','deprecated')`,
+		},
+		{
+			Finding{Category: "polluted_attrs", Severity: "warning",
+				Evidence:         "routing-critical attributes carrying prose (breaks resolution) — e.g. host='hubris (confirmed via pct…')",
+				SuggestedRunbook: "knowledge-graph-audit"},
+			`SELECT slug || ': host=' || (attributes->>'host') FROM entities
+			 WHERE attributes->>'host' IS NOT NULL
+			   AND (attributes->>'host') ~ '[ (]'`,
+		},
+	}
+
+	findings := make([]Finding, 0, len(specs))
+	summary := Summary{ByCategory: map[string]int{}}
+	for _, sp := range specs {
+		f := runFinding(ctx, pool, sp.finding, sp.query)
+		findings = append(findings, f)
+		summary.TotalFindings += f.Count
+		summary.ByCategory[f.Category] = f.Count
+	}
+	return findings, summary
+}
+
+const entityCap = 50
+
+// runFinding runs a single-column slug query and folds the rows into a Finding.
+func runFinding(ctx context.Context, pool *db.Pool, f Finding, query string) Finding {
+	rows, err := pool.Query(ctx, query)
+	if err != nil {
+		f.Evidence = f.Evidence + " (query error: " + err.Error() + ")"
+		return f
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var slug string
+		if err := rows.Scan(&slug); err != nil {
+			continue
+		}
+		f.Count++
+		if len(f.Entities) < entityCap {
+			f.Entities = append(f.Entities, slug)
+		}
+	}
+	return f
+}

internal/audit/audit_test.go

@@ -0,0 +1,69 @@
+package audit
+
+import (
+	"context"
+	"testing"
+
+	"github.com/dtoro/oikos/internal/db"
+	"github.com/google/uuid"
+)
+
+// Integration tests against a real Postgres, guarded by
+// OIKOS_TEST_DATABASE_URL (same convention as internal/scheduler).
+
+func newAuditPool(t *testing.T) *db.Pool {
+	t.Helper()
+	base := getenvOrDefault("OIKOS_TEST_DATABASE_URL", "")
+	if base == "" {
+		t.Skip("OIKOS_TEST_DATABASE_URL not set — skipping integration test")
+	}
+	return createTestDB(t, base)
+}
+
+func TestReportFlagsOrphanAndDeadAndDown(t *testing.T) {
+	pool := newAuditPool(t)
+	ctx := context.Background()
+
+	// An orphan check entity (truncated random slug, the legacy bug shape).
+	mustExec(t, pool, ctx, `INSERT INTO entities (id, slug, type, name, state, attributes, version, created_at, updated_at)
+		VALUES ($1,'check:ssh-script:0d31fdd1','check','check:ssh-script:0d31fdd1','active','{}'::jsonb,1,now(),now())`, uuid.New())
+
+	// An active entity + a check_def on it stuck down.
+	target := uuid.New()
+	mustExec(t, pool, ctx, `INSERT INTO entities (id, slug, type, name, state, attributes, version, created_at, updated_at)
+		VALUES ($1,'service:demo','service','demo','active','{}'::jsonb,1,now(),now())`, target)
+	checkE := uuid.New()
+	mustExec(t, pool, ctx, `INSERT INTO entities (id, slug, type, name, state, attributes, version, created_at, updated_at)
+		VALUES ($1,'check:http:service:demo:0','check','c','active','{}'::jsonb,1,now(),now())`, checkE)
+	mustExec(t, pool, ctx, `INSERT INTO check_defs (entity_id, target_id, target_type, kind, config, interval_s, timeout_s, enabled, last_run_at, last_health)
+		VALUES ($1,$2,'service','http','{}'::jsonb,60,30,true,now(),'down')`, checkE, target)
+
+	// A deprecated entity still carrying an enabled check (dead_checks).
+	dep := uuid.New()
+	mustExec(t, pool, ctx, `INSERT INTO entities (id, slug, type, name, state, attributes, version, created_at, updated_at)
+		VALUES ($1,'service:old','service','old','deprecated','{}'::jsonb,1,now(),now())`, dep)
+	depCheck := uuid.New()
+	mustExec(t, pool, ctx, `INSERT INTO entities (id, slug, type, name, state, attributes, version, created_at, updated_at)
+		VALUES ($1,'check:http:service:old:0','check','c','active','{}'::jsonb,1,now(),now())`, depCheck)
+	mustExec(t, pool, ctx, `INSERT INTO check_defs (entity_id, target_id, target_type, kind, config, interval_s, timeout_s, enabled, last_run_at)
+		VALUES ($1,$2,'service','http','{}'::jsonb,60,30,true,now())`, depCheck, dep)
+
+	findings, summary := Report(ctx, pool)
+
+	byCat := map[string]int{}
+	for _, f := range findings {
+		byCat[f.Category] = f.Count
+	}
+	if byCat["orphan_checks"] < 1 {
+		t.Errorf("orphan_checks = %d, want >=1", byCat["orphan_checks"])
+	}
+	if byCat["down_checks"] < 1 {
+		t.Errorf("down_checks = %d, want >=1", byCat["down_checks"])
+	}
+	if byCat["dead_checks"] < 1 {
+		t.Errorf("dead_checks = %d, want >=1", byCat["dead_checks"])
+	}
+	if summary.TotalFindings < 3 {
+		t.Errorf("TotalFindings = %d, want >=3", summary.TotalFindings)
+	}
+}