nomos+web: streaming, provider routing, event gap-fill, embedded UI; fix approval FK & session context

Agent (cmd/nomos):
- Stream LLM tokens via NewStreaming; emit text_delta then final text.
- OpenRouter provider routing: data_collection=deny (ZDR) + require_parameters;
  NOMOS_PROVIDER_SORT opt-in; Exacto via model suffix.
- Multi-turn: reload session history into context; UI passes session id.
- Fix agent_activity logging (agent_id/session_id) and mcpClient data race.

Events (live control-room feed):
- approval.created (mcp), approval.decided (api), execution.completed/failed
  (approved-action path), signal.raised/resolved + health.changed (scheduler,
  transition-gated).

Fixes:
- createApproval FK violation (reuse execution entity) — the agent's only
  write path; log the previously-swallowed errors.

Web UI:
- Embed web/dist via //go:embed (single binary); Dockerfile builds SPA into
  the Go stage; committed .gitkeep placeholder keeps backend-only builds green.
- Caddy: Authentik-gated /agent/* -> nomos so the UI reaches the agent
  same-origin in production.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.agents/NOMOS.md

@@ -1,4 +1,4 @@
-# HERMES.md — Agent persona for homelab clients
+# 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
@@ -32,8 +32,8 @@ approval flow, ontology).
 
 | Agent | Loading mechanism |
 |-------|------------------|
-| **Hermes** | `tools/setup-hermes-soul.sh` (auto-setup) → provisions `~/.hermes/SOUL.md` from this file |
-| **Goose** | `.goosehints` symlink at `~/.config/goose/.goosehints` → `/opt/homelab-context/HERMES.md` |
+| **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
@@ -87,10 +87,10 @@ Caveman templates live at `~/templates/`:
 ls ~/bin/caveman_wrapper.sh && echo "caveman ready"
 ```
 
-## Important note for Hermes agents
+## Important note for Nomos agents
 
-If you are reading this as a Hermes agent, your SOUL.md was auto-provisioned
-by `tools/setup-hermes-soul.sh`. This file is the canonical original — you
+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-hermes-soul.sh
+    bash /opt/homelab-context/tools/setup-nomos-soul.sh

.agents/OIKOS.md

@@ -137,13 +137,13 @@ in the Go binary.
 - Go packages: `internal/scheduler/`, `internal/actuator/`,
   `internal/learning/`, `internal/notifier/`, `internal/policy/`.
 
-**Phase 4 — Agent / Hermes (DONE):**
-- Standalone Hermes MCP client binary (`cmd/hermes`) with gateway mode
+**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.
-- `hermes/` directory with config, SOUL.md, homelab-ops skill.
-- Hermes Docker service in `docker-compose.yml` (profile: full).
-- Go packages: `cmd/hermes/`, `compose/hermes/`.
+- `nomos/` directory with config, SOUL.md, homelab-ops skill.
+- Nomos Docker service in `docker-compose.yml` (profile: full).
+- Go packages: `cmd/nomos/`, `compose/nomos/`.
 
 **Phase 5 — Secrets / Infisical (DONE):**
 - `internal/secrets/`: backend abstraction (Manager) with primary
@@ -159,7 +159,7 @@ in the Go binary.
   lint, test, docker build).
 - Deploy: `scripts/deploy.sh` (git pull → docker build → compose up →
   health check), SHA-tagged images, rolling restart.
-- Caddy config: `compose/caddy/Caddyfile.oikos` (oikos/mcp/hermes →
+- Caddy config: `compose/caddy/Caddyfile.oikos` (oikos/mcp/nomos →
   mac-mini mesh :8090/:8092).
 - Watchdog: `scripts/watchdog.sh` (2min cron, Matrix alert on failure).
 - Verification: `scripts/verify-phase6.sh` (14/14 checks pass).
@@ -168,7 +168,7 @@ in the Go binary.
 
 **Current deployment:**
 - **Production**: Docker stack on mac-mini (`--profile full`: postgres, api,
-  scheduler, notifier, hermes). Deployed 2026-07-07 with full knowledge seed.
+  scheduler, notifier, nomos). Deployed 2026-07-07 with full knowledge seed.
   The Python MCP server and secrets-issuance on apps/105 have been stopped
   (see `scripts/cutover-checklist.md`).
 

.agents/dev/CONTRIBUTING.md

@@ -9,7 +9,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/hermes/main.go         Hermes MCP client gateway (standalone binary)
+cmd/nomos/main.go          Nomos MCP client gateway (standalone binary, formerly Hermes)
 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.)
@@ -31,10 +31,10 @@ api/codegen.yaml            oapi-codegen config → generates internal/httpapi/g
 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), hermes/ (distroless).
+compose/                    Dockerfiles. oikos/ (multi-stage), nomos/ (distroless).
                              Caddy config at compose/caddy/Caddyfile.oikos.
 scripts/                     Deploy, rollback, watchdog, verification, cutover checklist.
-hermes/                      Hermes config.yaml, SOUL.md, skills.
+nomos/                       Nomos config.yaml, SOUL.md, skills.
 .agents/                     Agent instruction files, domains, shared conventions, skills.
 plans/                       Design documents. active/ + done/.
 docs/adr/                    Architecture decision records. Numbered, prefix-sorted.

.agents/operations/agent-enrollment.md

@@ -6,8 +6,8 @@ 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.
 
 > Onboarding a Nous-Hermes-powered Goose agent on top of standard enrollment?
-> See [hermes-agent.md](hermes-agent.md). It uses the same `bootstrap.sh`
-> with an additional `--with-hermes` flag.
+> 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.
@@ -354,9 +354,9 @@ 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-05-31 — cross-link to hermes-agent.md
-Added a sibling page covering Nous-Hermes-on-Goose enrollment ([hermes-agent.md](hermes-agent.md)) and noted it at the top of this page. The Hermes flow extends `bootstrap.sh` with `--with-hermes` and `homelab client add` with the same flag; it does not change the underlying enrollment steps documented here.
+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-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.

.agents/operations/commands.md

@@ -14,7 +14,7 @@ Run from the [hubris host](../../archive/knowledge/hosts/hubris.md) as root. Whe
 | `pvesm status` | Storage pools status |
 | `pvesh get /nodes --output-format json` | Node summary as JSON |
 | `pvesh get /nodes/hubris/lxc/<id>/status/current` | Live container status |
-| `pvesh get /cluster/resources --type vm --output-format json` | Bulk per-LXC CPU/mem/disk (used by the `homelab-health-watchdog` Hermes cron — see [monitoring](../../archive/knowledge/infrastructure/monitoring.md); the old `claudio-monitor` this once fed is deprecated) |
+| `pvesh get /cluster/resources --type vm --output-format json` | Bulk per-LXC CPU/mem/disk (used by the `homelab-health-watchdog` Nomos cron — see [monitoring](../../archive/knowledge/infrastructure/monitoring.md); the old `claudio-monitor` this once fed is deprecated) |
 | `pveversion` | PVE version |
 | `journalctl -u pve-cluster -n 100` | PVE service logs |
 
@@ -77,7 +77,7 @@ See [OIKOS.md](../OIKOS.md) for the operating model. Quick reference:
 | `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 Hermes, or the Oikos Console's `/approvals` page) |
+| `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 |
 
 Oikos Console (read-mostly dashboard): `oikos.hubris.network` once deployed — see [oikos/console/deploy/README.md](../../archive/oikos-cards/).

.agents/operations/nomos-agent.md

@@ -1,4 +1,4 @@
-# Hermes agent — Nous-Hermes-powered Goose sessions on a homelab client
+# 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
@@ -8,13 +8,13 @@ of standard client enrollment (see [agent-enrollment.md](agent-enrollment.md))
 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 Nous Hermes
+- 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/HERMES.md`, symlinked as Goose's global
+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
@@ -23,7 +23,7 @@ The persona is `/opt/homelab-context/HERMES.md`, symlinked as Goose's global
 | --- | --- |
 | 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-hermes` |
+| 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
 
@@ -33,37 +33,37 @@ homelab client add new-machine
 
 # 2. Join new-machine to Netbird (setup-key or OIDC).
 
-# 3. On new-machine: bootstrap with --with-hermes.
+# 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-hermes
+sudo HOMELAB_GITEA_TOKEN=$TOKEN bash /tmp/bootstrap.sh --with-mcp --with-nomos
 
-# 4. Back on hubris: finalize the age pubkey AND grant the Hermes secret.
+# 4. Back on hubris: finalize the age pubkey AND grant the Nomos secret.
 homelab client add new-machine \
   --finalize-pubkey age1... \
-  --with-hermes
+  --with-nomos
 
 # 5. Wait ≤5 min for sync, then on new-machine:
-hermes "what LXCs are running?"
+nomos "what LXCs are running?"
 ```
 
-The bootstrap `--with-hermes` flag does five things, all idempotent:
+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/hermes` → `/usr/local/bin/hermes`.
-3. Symlinks `/opt/homelab-context/HERMES.md` → `/root/HERMES.md` (Linux) or
-   `/etc/HERMES.md` (macOS) for `cat`-as-operator convenience.
+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` → HERMES.md, so the persona is
+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-hermes`, the encrypted file
+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):
 
@@ -75,19 +75,19 @@ git -C /opt/homelab-context commit -m 'openrouter-api-key: seed real key'
 git -C /opt/homelab-context push
 ```
 
-Until this step happens, `hermes …` exits with `openrouter-api-key.yaml still
+Until this step happens, `nomos …` exits with `openrouter-api-key.yaml still
 contains the placeholder`. Subsequent enrollees get the real key automatically
-via `--with-hermes` (which adds them as a sops recipient on
+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-hermes` and you want to add it later:
+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-hermes
+homelab client add <host> --finalize-pubkey "$PUBKEY" --with-nomos
 ```
 
 `--finalize-pubkey` is required by the existing flow even when the pubkey is
@@ -101,12 +101,12 @@ re-run; only the secret recipient list changed.
 ```bash
 homelab whoami                                # standard enrollment OK
 homelab secret openrouter-api-key | head -c 8 # decrypts (prints `api_key:`)
-which goose && which hermes                   # binaries present
+which goose && which nomos                     # binaries present
 goose info -v                                  # provider/model wiring sane
-hermes "what LXCs are running?"                # interactive Goose session
+nomos "what LXCs are running?"                  # interactive Goose session
 
 # Non-interactive smoke test:
-echo "List the homelab MCP tools you have available" | hermes
+echo "List the homelab MCP tools you have available" | nomos
 ```
 
 ## Configuration
@@ -135,9 +135,9 @@ extensions:
 Override via env on a single bootstrap run:
 
 ```bash
-HOMELAB_HERMES_MODEL=nousresearch/hermes-3-llama-3.1-405b \
-HOMELAB_HERMES_MCP_URI=https://mcp.hubris.network/mcp \
-  sudo bash /tmp/bootstrap.sh --with-hermes
+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
@@ -156,22 +156,22 @@ every tool call, use `approve`. See
 
 | Symptom | Cause | Fix |
 | --- | --- | --- |
-| `hermes: 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-hermes` from hubris |
-| `hermes: 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 `hermes` 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. |
+| `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-hermes`; the symlink step is at the end of the install block. If still missing, `ln -sfn ~/.local/bin/goose /usr/local/bin/goose` manually. |
+| `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
-  Hermes flow assumes is done.
-- [`HERMES.md`](../HERMES.md) — the persona the Hermes agent reads on every
+  Nomos flow assumes is done.
+- [`NOMOS.md`](../NOMOS.md) — the persona the Nomos agent reads on every
   session start (via `~/.config/goose/.goosehints`).
-- [`bin/hermes`](../../bin/hermes) — the wrapper that decrypts the OpenRouter key
+- [`bin/nomos`](../../bin/nomos) — the wrapper that decrypts the OpenRouter key
   and execs `goose session`.
-- [`bootstrap.sh`](../../bootstrap.sh) — the `--with-hermes` flag's install block.
+- [`bootstrap.sh`](../../bootstrap.sh) — the `--with-nomos` flag's install block.
 
 ## Follow-ups
 
@@ -182,7 +182,7 @@ every tool call, use `approve`. See
    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 Hermes
+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.
@@ -204,7 +204,7 @@ 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 Hermes-on-Goose onboarding flow added in the same commit as
-`bootstrap.sh --with-hermes`, `bin/hermes`, the sops rule for
-`secrets/openrouter-api-key.yaml`, and the `homelab client add --with-hermes`
+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/caveman.md

@@ -30,4 +30,4 @@ Code/commits/PRs: write normal. "stop caveman" or "normal mode": revert. Level p
 ---
 
 Source: https://github.com/JuliusBrussee/caveman
-Copy to `~/.hermes/skills/` for Hermes Agent, or `~/.claude/projects/<name>/SKILL.md` for Claude Code.
+Copy to `~/.nomos/skills/` for Nomos agent, or `~/.claude/projects/<name>/SKILL.md` for Claude Code.

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

@@ -26,7 +26,7 @@ the full walkthrough; this runbook is the risk/lifecycle framing.
    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-hermes` to also
+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>

.gitignore

@@ -5,9 +5,9 @@ __pycache__/
 # Regenerated every scheduler run; ephemeral health-probe cache.
 oikos/state.json
 
-# Compiled binaries (Go rewrite — bin/oikos, bin/hermes)
+# Compiled binaries (Go rewrite — bin/oikos, bin/nomos)
 bin/oikos
-bin/hermes
+bin/nomos
 oikos/oikos
 
 # Legacy Python oikos (superseded by cmd/oikos Go binary — Phase 1-6 rewrite).
@@ -17,3 +17,10 @@ oikos/oikos
 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/node_modules/

.sops.yaml

@@ -86,11 +86,11 @@ creation_rules:
       age1z62ff2ak9zj5ctcvaxwyyhedwjvlwgm2dkn9nk3wrwk8fkavcpmsqwc2vs
 
   - path_regex: archive/secrets-sops-backupopenrouter-api-key\.yaml$
-    # OpenRouter API key consumed by the `hermes` wrapper (bin/hermes) when
+    # OpenRouter API key consumed by the `nomos` wrapper (bin/nomos) when
     # spawning a Goose session. Recipients are any host that should run a
-    # Nous-Hermes agent. Add a host's age_pubkey here, then
+    # Nomos agent. Add a host's age_pubkey here, then
     # `sops updatekeys -y secrets/openrouter-api-key.yaml`.
-    # See operations/hermes-agent.md.
+    # See operations/nomos-agent.md.
     age: >-
       age1xkklkvnk5z0fsnh6cfgv70hy9ksfy8rdprwerzw4yk3p4p7cxcqs2yvpz6,
       age1vf8h7s8mqsn2q5eadgpdupsj4mwn8zguc77d85ws3xj40sl9rgksx2rxw6,

AGENTS.md

@@ -124,9 +124,9 @@ per the DB-as-source-of-truth plan.
 
 ## 5. Acting on the homelab
 
-- **Read state**: use MCP tools. Hermes (the AI agent) is the primary
+- **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): Hermes calls `request_execution`
+- **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).
@@ -152,10 +152,10 @@ 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`.
-- **Hermes agent persona** (`tools/setup-hermes-soul.sh`): Provisions
-  `~/.hermes/SOUL.md` from `HERMES.md` on Hermes agents. This ensures every
-  Hermes agent follows the canonical homelab persona (token efficiency, source
-  of truth hierarchy). No-op on non-Hermes agents.
+- **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.
 
 To add a new auto-setup, create `tools/<name>.setup.sh` in the repo,
 commit and push. All enrolled clients pick it up within 5 minutes.

CLIENTS.md

@@ -41,7 +41,7 @@ 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-hermes   # install Goose + Hermes
+curl ... | sudo bash -s -- --with-nomos     # install Goose + Nomos
 ```
 
 This calls `POST /api/v1/clients/enroll` on the Oikos API, which:
@@ -56,7 +56,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, hermes-soul)
+- `/opt/homelab/tools/` — tooling scripts (caveman, nomos-soul)
 - `/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

@@ -28,7 +28,7 @@ make build
 
 ```
 cmd/oikos/          Single-binary entry point
-cmd/hermes/         Hermes MCP client gateway
+cmd/nomos/          Nomos MCP client gateway
 internal/           All Go packages
   httpapi/          REST + MCP server (OpenAPI-generated)
   mcp/              MCP tool implementations
@@ -47,7 +47,7 @@ migrations/         Forward-only SQL migrations (TimescaleDB)
 seeds/              Bootstrap YAML: ontology, inventory, policy, knowledge
 compose/            Dockerfiles + Caddy config
 scripts/            Deploy, watchdog, rollback
-hermes/             Hermes config, persona, skills
+nomos/              Nomos config, persona, skills
 .agents/            Agent instruction files + skills
 plans/              Design documents
 docs/adr/           Architecture decision records

README.md

@@ -1,8 +1,8 @@
 # Oikos
 
 Agentic homelab operating system written in Go. Single binary (`cmd/oikos`),
-Docker-deployed on mac-mini, with a standalone Hermes MCP agent gateway
-(`cmd/hermes`). Manages the **hubris** Proxmox homelab autonomously — observes
+Docker-deployed on mac-mini, with a standalone Nomos MCP agent gateway
+(`cmd/nomos`). Manages the **hubris** Proxmox homelab autonomously — observes
 state, classifies actions against policy, executes approved procedures over SSH,
 learns from outcomes, and escalates when uncertain.
 
@@ -16,7 +16,7 @@ learns from outcomes, and escalates when uncertain.
 # Dev stack (postgres + api + scheduler + notifier)
 docker compose --profile dev up -d
 
-# Full stack (adds Hermes agent gateway)
+# Full stack (adds Nomos agent gateway)
 docker compose --profile full up -d
 
 # Build standalone binary
@@ -33,7 +33,7 @@ OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disa
                   ┌──────────────────────────────────┐
                   │         mac-mini (Docker)         │
                   │                                   │
-  Workstation ─── │  hermes (8092) ──MCP── api (8090) │
+  Workstation ─── │  nomos (8092) ──MCP── api (8090) │
   (mesh)          │    MCP gateway      REST + MCP    │
                   │                                   │
                   │  scheduler ── notifier ── postgres │
@@ -46,7 +46,7 @@ OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disa
 | `oikos api` | 8090 | REST API + MCP server (15 tools) |
 | `oikos scheduler` | — | Probe runner, signal lifecycle, metrics |
 | `oikos notifier` | — | Approval tokens, Matrix alerts |
-| `hermes serve` | 8092 | MCP client gateway, query routing |
+| `nomos serve` | 8092 | MCP client gateway, query routing |
 
 ## Phases
 
@@ -55,7 +55,7 @@ OIKOS_DATABASE_URL="postgres://oikos:oikos_dev@localhost:5432/oikos?sslmode=disa
 | 1 — Ontology + DB | ✅ | TimescaleDB, migrations, seeds, blast_radius |
 | 2 — API | ✅ | OpenAPI-first REST + MCP, auth, SSE, audit |
 | 3 — Control loop | ✅ | Scheduler, actuator, learning, classifier, notifier |
-| 4 — Hermes agent | ✅ | Standalone MCP client gateway, agent activity |
+| 4 — Nomos agent | ✅ | Standalone MCP client gateway, agent activity |
 | 5 — Secrets | ✅ | Infisical backend + SOPS fallback, rotation runbooks |
 | 6 — Deploy | ✅ | CI pipeline, cutover checklist, watchdog, rollback |
 
@@ -71,7 +71,7 @@ curl http://localhost:8090/api/v1/health                  # fleet health
 curl http://localhost:8090/api/v1/agent-activity          # agent log
 ```
 
-### Hermes queries
+### Nomos queries
 
 ```bash
 # Structured tool call
@@ -101,7 +101,7 @@ oikos secret migrate  # SOPS → Infisical
 
 ```
 cmd/oikos/          Go entry point — single binary
-cmd/hermes/         Hermes MCP client gateway
+cmd/nomos/          Nomos MCP client gateway
 internal/           Go packages (httpapi, mcp, scheduler, actuator, learning,
                     notifier, policy, secrets, db, config, ontology, domain,
                     knowledge)
@@ -110,7 +110,7 @@ migrations/         Forward-only SQL migrations (TimescaleDB)
 seeds/              Bootstrap YAML (ontology, inventory, policy, knowledge)
 compose/            Dockerfiles + Caddy config
 scripts/            Deploy, watchdog, verification, rollback
-hermes/             Hermes config, persona, skills
+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)

bootstrap.sh

@@ -3,7 +3,7 @@
 #
 # 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, hermes-soul) from the raw Gitea URL. Enrolls via the Oikos API
+# (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.
 #
@@ -11,7 +11,7 @@
 #   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-hermes        # install Goose + Hermes
+#   curl ... | sudo bash -s -- --with-nomos        # install Goose + Nomos
 #   curl ... | sudo bash -s -- --dry-run            # show what would happen
 #
 # Prerequisites:
@@ -28,11 +28,11 @@ 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}"
-HERMES_MCP_URI="${HOMELAB_HERMES_MCP_URI:-https://mcp.hubris.network/mcp}"
-HERMES_MODEL="${HOMELAB_HERMES_MODEL:-nousresearch/hermes-4-405b}"
+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_HERMES=0
+WITH_NOMOS=0
 DRY_RUN=0
 
 GITEA_TOKEN="${HOMELAB_GITEA_TOKEN:-}"
@@ -79,7 +79,7 @@ detect_mesh_ip() {
 while [ $# -gt 0 ]; do
     case "$1" in
         --with-mcp)       WITH_MCP=1 ;;
-        --with-hermes)    WITH_HERMES=1 ;;
+        --with-nomos)    WITH_NOMOS=1 ;;
         --dry-run)        DRY_RUN=1 ;;
         --gitea-token)    GITEA_TOKEN="$2"; shift ;;
         --gitea-user)     GITEA_USER="$2"; shift ;;
@@ -148,7 +148,7 @@ done
 
 # ── fetch tools ──────────────────────────────────────────────────────
 log "fetching tools..."
-for tool in setup-caveman.sh setup-hermes-soul.sh caveman.js caveman_wrapper.sh post-pull.sh; do
+for tool in setup-caveman.sh setup-nomos-soul.sh caveman.js caveman_wrapper.sh post-pull.sh; do
     url="$REPO_RAW_URL/tools/${tool}"
     dest="$CLONE_DIR/tools/${tool}"
     dry mkdir -p "$(dirname "$dest")"
@@ -319,15 +319,15 @@ if [ "$WITH_MCP" -eq 1 ]; then
     log "  + MCP wired to $MCP_URL"
 fi
 
-# ── --with-hermes: install Goose + Hermes wrapper ────────────────────
-if [ "$WITH_HERMES" -eq 1 ]; then
-    log "installing Hermes agent..."
+# ── --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 Hermes persona
-    cp "$CLONE_DIR/HERMES.md" "$CLONE_DIR/.agents/HERMES.md" 2>/dev/null || true
-    log "  + Hermes agent 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 ────────────────────────────────────────────

cmd/hermes/main.go

@@ -1,341 +0,0 @@
-package main
-
-import (
-	"bufio"
-	"bytes"
-	"context"
-	"encoding/json"
-	"fmt"
-	"log/slog"
-	"net/http"
-	"os"
-	"os/signal"
-	"strings"
-	"syscall"
-	"time"
-)
-
-func main() {
-	if len(os.Args) < 2 {
-		fmt.Fprintln(os.Stderr, "usage: hermes serve")
-		os.Exit(1)
-	}
-
-	mcpURL := os.Getenv("HERMES_MCP_URL")
-	if mcpURL == "" {
-		mcpURL = "http://localhost:8090/mcp"
-	}
-
-	agentSlug := os.Getenv("HERMES_AGENT_SLUG")
-	if agentSlug == "" {
-		agentSlug = "agent:hermes"
-	}
-
-	switch os.Args[1] {
-	case "serve":
-		ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
-		defer cancel()
-
-		client, err := newMCPClient(mcpURL)
-		if err != nil {
-			slog.Error("hermes: mcp connect", "url", mcpURL, "error", err)
-			os.Exit(1)
-		}
-
-		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)
-		})
-
-		addr := os.Getenv("HERMES_LISTEN")
-		if addr == "" {
-			addr = ":8092"
-		}
-
-		srv := &http.Server{Addr: addr, Handler: mux}
-		go func() {
-			slog.Info("hermes: gateway listening", "addr", addr, "mcp", mcpURL)
-			if err := srv.ListenAndServe(); err != http.ErrServerClosed {
-				slog.Error("hermes: serve", "error", err)
-			}
-		}()
-
-		<-ctx.Done()
-		slog.Info("hermes: shutting down")
-		srv.Shutdown(context.Background())
-		client.close()
-
-	default:
-		fmt.Fprintf(os.Stderr, "unknown command: %s\n", os.Args[1])
-		os.Exit(1)
-	}
-}
-
-// handleQuery maps structured queries to MCP tool calls.
-func handleQuery(w http.ResponseWriter, r *http.Request, client *mcpClient, agentSlug, mcpURL string) {
-	if r.Method != http.MethodPost {
-		http.Error(w, "method not allowed", 405)
-		return
-	}
-
-	var req struct {
-		Query string `json:"query"`
-		Tool  string `json:"tool"`
-		Args  map[string]any `json:"args"`
-	}
-	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-		http.Error(w, "bad request: "+err.Error(), 400)
-		return
-	}
-
-	start := time.Now()
-	var result any
-	var err error
-
-	// Direct tool call (structured)
-	if req.Tool != "" {
-		result, err = client.callTool(req.Tool, req.Args)
-	} else {
-		// Natural-language-ish query routing
-		q := strings.ToLower(req.Query)
-		result, err = routeQuery(client, q, agentSlug)
-	}
-
-	duration := time.Since(start).Milliseconds()
-
-	if err != nil {
-		slog.Error("hermes: query failed", "query", req.Query, "error", err)
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]any{
-			"error":       err.Error(),
-			"elapsed_ms":  duration,
-			"agent_slug":  agentSlug,
-		})
-		return
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{
-		"result":      result,
-		"elapsed_ms":  duration,
-		"agent_slug":  agentSlug,
-		"mcp_url":     mcpURL,
-	})
-}
-
-// routeQuery maps natural-language-style queries to MCP tool calls.
-func routeQuery(client *mcpClient, query, agentSlug string) (any, error) {
-	switch {
-	case strings.Contains(query, "depends on") || strings.Contains(query, "depend on"):
-		entity := extractEntity(query)
-		if entity == "" {
-			return nil, fmt.Errorf("no entity found in query: %s", query)
-		}
-		return client.callTool("get_blast_radius", map[string]any{
-			"entity_id": entity,
-		})
-
-	case strings.Contains(query, "what is") || strings.Contains(query, "describe"):
-		entity := extractEntity(query)
-		if entity == "" {
-			entity = query
-		}
-		return client.callTool("get_entity", map[string]any{
-			"slug_or_id": entity,
-		})
-
-	case strings.Contains(query, "health") || strings.Contains(query, "status"):
-		return client.callTool("get_health_summary", map[string]any{})
-
-	case strings.Contains(query, "restart") || strings.Contains(query, "reload"):
-		entity := extractEntity(query)
-		if entity == "" {
-			return nil, fmt.Errorf("no entity found in query: %s", query)
-		}
-		return client.callTool("request_execution", map[string]any{
-			"target": entity,
-			"action": "restart",
-		})
-
-	case strings.Contains(query, "what can you do") || strings.Contains(query, "help"):
-		return client.callTool("tools/list", nil)
-
-	default:
-		return client.callTool("get_health_summary", map[string]any{})
-	}
-}
-
-// extractEntity guesses an entity slug from a query.
-func extractEntity(query string) string {
-	for _, slug := range []string{"authentik", "caddy", "vaultwarden", "gitea", "immich"} {
-		if strings.Contains(query, slug) {
-			return "service:" + slug
-		}
-	}
-	if strings.Contains(query, "mac-mini") {
-		return "host:mac-mini"
-	}
-	if strings.Contains(query, "hubris") {
-		return "host:hubris"
-	}
-	return ""
-}
-
-// ─── MCP Streamable HTTP client ────────────────────────────────────────
-
-type mcpClient struct {
-	baseURL    string
-	sessionID  string
-	http       *http.Client
-	nextID     int
-}
-
-func newMCPClient(baseURL string) (*mcpClient, error) {
-	c := &mcpClient{
-		baseURL: baseURL,
-		http:    &http.Client{Timeout: 30 * time.Second},
-	}
-
-	// Initialize session
-	resp, err := c.doRequest("initialize", map[string]any{
-		"protocolVersion": "2024-11-05",
-		"capabilities":    map[string]any{},
-		"clientInfo":      map[string]any{"name": "hermes", "version": "2.0"},
-	})
-	if err != nil {
-		return nil, fmt.Errorf("initialize: %w", err)
-	}
-	if resp.sessionID == "" {
-		return nil, fmt.Errorf("no session ID in initialize response")
-	}
-	c.sessionID = resp.sessionID
-
-	// Send initialized notification
-	c.doRequest("notifications/initialized", map[string]any{})
-
-	slog.Info("hermes: mcp connected", "session", c.sessionID[:16]+"...")
-	return c, nil
-}
-
-type mcpJSONRPCResponse struct {
-	sessionID string
-	Result    json.RawMessage `json:"result"`
-	Error     json.RawMessage `json:"error"`
-}
-
-func (c *mcpClient) doRequest(method string, params map[string]any) (*mcpJSONRPCResponse, error) {
-	c.nextID++
-	body, _ := json.Marshal(map[string]any{
-		"jsonrpc": "2.0",
-		"method":  method,
-		"params":  params,
-		"id":      c.nextID,
-	})
-
-	req, err := http.NewRequest(http.MethodPost, c.baseURL, bytes.NewReader(body))
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Accept", "application/json, text/event-stream")
-	if c.sessionID != "" {
-		req.Header.Set("Mcp-Session-Id", c.sessionID)
-	}
-
-	resp, err := c.http.Do(req)
-	if err != nil {
-		return nil, err
-	}
-	defer resp.Body.Close()
-
-	result := &mcpJSONRPCResponse{}
-	result.sessionID = resp.Header.Get("Mcp-Session-Id")
-
-	// Parse SSE stream: "event: message\ndata: <json>\n\n"
-	scanner := bufio.NewScanner(resp.Body)
-	for scanner.Scan() {
-		line := scanner.Text()
-		if strings.HasPrefix(line, "data: ") {
-			data := line[6:]
-			if err := json.Unmarshal([]byte(data), result); err != nil {
-				return nil, fmt.Errorf("parse response: %w", err)
-			}
-		}
-	}
-
-	if result.Error != nil {
-		return nil, fmt.Errorf("rpc error: %s", string(result.Error))
-	}
-
-	if result.sessionID != "" {
-		c.sessionID = result.sessionID
-	}
-
-	return result, nil
-}
-
-func (c *mcpClient) callTool(name string, args map[string]any) (any, error) {
-	resp, err := c.doRequest("tools/call", map[string]any{
-		"name":      name,
-		"arguments": args,
-	})
-	if err != nil {
-		return nil, err
-	}
-
-	// Parse MCP content: { "content": [{ "type": "text", "text": "..." }] }
-	var toolResult struct {
-		Content []struct {
-			Type string `json:"type"`
-			Text string `json:"text"`
-		} `json:"content"`
-	}
-	if err := json.Unmarshal(resp.Result, &toolResult); err != nil {
-		return string(resp.Result), nil
-	}
-
-	var texts []string
-	for _, c := range toolResult.Content {
-		if c.Type == "text" {
-			// Try to parse as JSON for structured display
-			var parsed any
-			if json.Unmarshal([]byte(c.Text), &parsed) == nil {
-				return parsed, nil
-			}
-			texts = append(texts, c.Text)
-		}
-	}
-	if len(texts) == 1 {
-		return texts[0], nil
-	}
-	return texts, nil
-}
-
-func (c *mcpClient) listTools() ([]string, error) {
-	resp, err := c.doRequest("tools/list", map[string]any{})
-	if err != nil {
-		return nil, err
-	}
-	var tr struct {
-		Tools []struct {
-			Name        string `json:"name"`
-			Description string `json:"description"`
-		} `json:"tools"`
-	}
-	if err := json.Unmarshal(resp.Result, &tr); err != nil {
-		return nil, err
-	}
-	var names []string
-	for _, t := range tr.Tools {
-		names = append(names, t.Name)
-	}
-	return names, nil
-}
-
-func (c *mcpClient) close() {
-	// MCP sessions are ephemeral; no explicit close needed
-}

cmd/nomos/agent.go

@@ -0,0 +1,295 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"os"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/openai/openai-go"
+	"github.com/openai/openai-go/option"
+	"github.com/openai/openai-go/shared"
+)
+
+const maxIterations = 15
+
+type agent struct {
+	client   *mcpClient
+	system   string
+	provider *openai.Client
+	model    string
+	store    *store
+	agentID  uuid.UUID
+	reqOpts  []option.RequestOption
+}
+
+func newAgent(ctx context.Context, mcpClient *mcpClient, 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"
+	}
+
+	provider := openai.NewClient(
+		option.WithBaseURL("https://openrouter.ai/api/v1"),
+		option.WithAPIKey(apiKey),
+	)
+
+	agentID := st.resolveAgentID(ctx, agentSlug)
+	if agentID == uuid.Nil {
+		slog.Warn("nomos: agent entity not found; tool-call activity will not be logged", "slug", agentSlug)
+	}
+
+	// OpenRouter provider routing. data_collection=deny pins to zero-data-
+	// retention providers (privacy: conversations + tool results transit
+	// OpenRouter); require_parameters ensures the routed provider actually
+	// supports tool calling. NOMOS_PROVIDER_SORT (price|throughput|latency)
+	// and Exacto tool-accuracy routing are opt-in — the latter via a model
+	// suffix in NOMOS_MODEL (e.g. "deepseek/deepseek-v4-flash:exacto"), so an
+	// unsupported value never silently breaks the confirmed routing below.
+	providerRouting := map[string]any{
+		"data_collection":    "deny",
+		"require_parameters": true,
+	}
+	if sort := os.Getenv("NOMOS_PROVIDER_SORT"); sort != "" {
+		providerRouting["sort"] = sort
+	}
+	reqOpts := []option.RequestOption{option.WithJSONSet("provider", providerRouting)}
+
+	return &agent{
+		client:   mcpClient,
+		system:   system,
+		provider: &provider,
+		model:    model,
+		store:    st,
+		agentID:  agentID,
+		reqOpts:  reqOpts,
+	}, nil
+}
+
+func loadSoul() string {
+	paths := []string{"/app/nomos/SOUL.md", "nomos/SOUL.md"}
+	for _, p := range paths {
+		if data, err := os.ReadFile(p); err == nil {
+			return string(data)
+		}
+	}
+	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.`
+}
+
+type toolDef struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	InputSchema map[string]any `json:"inputSchema"`
+}
+
+type agentEvent struct {
+	Type       string `json:"type"`
+	Data       any    `json:"data,omitempty"`
+	SessionID  string `json:"session_id,omitempty"`
+	Iteration  int    `json:"iteration,omitempty"`
+}
+
+func (a *agent) chat(ctx context.Context, sessionID, message string, emit func(agentEvent)) {
+	correlationID := uuid.New().String()
+
+	tools, err := a.buildTools()
+	if err != nil {
+		emit(agentEvent{Type: "error", Data: fmt.Sprintf("build tools: %v", err), SessionID: sessionID})
+		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.
+	// Intermediate tool_use/tool_result pairs are not replayed (their ids
+	// must match exactly or the API rejects them); prior final answers carry
+	// the salient context. Ephemeral sessions (no store) fall back to the
+	// single incoming message.
+	messages := []openai.ChatCompletionMessageParamUnion{openai.SystemMessage(a.system)}
+	history, _ := a.store.getMessages(ctx, sessionID)
+	for _, m := range history {
+		text := extractText(m.Content)
+		switch m.Role {
+		case "user":
+			messages = append(messages, openai.UserMessage(text))
+		case "assistant":
+			if text != "" {
+				messages = append(messages, openai.AssistantMessage(text))
+			}
+		}
+	}
+	if len(history) == 0 {
+		messages = append(messages, openai.UserMessage(message))
+	}
+
+	for i := 0; i < maxIterations; i++ {
+		params := openai.ChatCompletionNewParams{
+			Model:    openai.ChatModel(a.model),
+			Messages: messages,
+			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})
+				}
+			}
+		}
+		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
+		}
+
+		msg := acc.Choices[0].Message
+
+		if len(msg.ToolCalls) == 0 {
+			emit(agentEvent{Type: "text", Data: msg.Content, SessionID: sessionID})
+			emit(agentEvent{Type: "done", Data: map[string]any{
+				"session_id":     sessionID,
+				"usage":          acc.Usage,
+				"correlation_id": correlationID,
+				"iterations":     i + 1,
+			}, SessionID: sessionID})
+			return
+		}
+
+		slog.Info("nomos: tool calls", "count", len(msg.ToolCalls), "iter", i+1, "correlation", correlationID)
+
+		messages = append(messages, msg.ToParam())
+
+		for _, tc := range msg.ToolCalls {
+			var args map[string]any
+			if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil {
+				args = map[string]any{}
+			}
+
+			emit(agentEvent{
+				Type:      "tool_use",
+				Data:      map[string]any{"name": tc.Function.Name, "args": args, "id": tc.ID},
+				SessionID: sessionID,
+				Iteration: i + 1,
+			})
+
+			start := time.Now()
+			result, callErr := a.client.callTool(tc.Function.Name, args)
+			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)
+
+				emit(agentEvent{
+					Type:      "tool_result",
+					Data:      map[string]any{"name": tc.Function.Name, "error": callErr.Error(), "id": tc.ID},
+					SessionID: sessionID,
+					Iteration: i + 1,
+				})
+				messages = append(messages, openai.ToolMessage(callErr.Error(), tc.ID))
+				slog.Error("nomos: tool error", "tool", tc.Function.Name, "error", callErr, "ms", elapsed)
+				continue
+			}
+
+			resultJSON, _ := json.Marshal(result)
+			a.store.logActivity(ctx, a.agentID, sessionID, tc.Function.Name, inputStr, string(resultJSON), elapsed, true, correlationID)
+
+			emit(agentEvent{
+				Type:      "tool_result",
+				Data:      map[string]any{"name": tc.Function.Name, "result": result, "id": tc.ID},
+				SessionID: sessionID,
+				Iteration: i + 1,
+			})
+			messages = append(messages, openai.ToolMessage(string(resultJSON), tc.ID))
+			slog.Info("nomos: tool success", "tool", tc.Function.Name, "ms", elapsed)
+		}
+	}
+
+	emit(agentEvent{Type: "text", Data: "Agent loop: max iterations reached without final answer.", SessionID: sessionID})
+	emit(agentEvent{Type: "done", Data: map[string]any{
+		"session_id":     sessionID,
+		"correlation_id": correlationID,
+		"iterations":     maxIterations,
+	}, SessionID: sessionID})
+}
+
+// extractText pulls the "text" field from a persisted message's JSONB content.
+func extractText(content json.RawMessage) string {
+	var m struct {
+		Text string `json:"text"`
+	}
+	if err := json.Unmarshal(content, &m); err != nil {
+		return ""
+	}
+	return m.Text
+}
+
+func (a *agent) buildTools() ([]openai.ChatCompletionToolParam, error) {
+	defs, err := a.client.listToolsFull()
+	if err != nil {
+		return nil, err
+	}
+
+	var tools []openai.ChatCompletionToolParam
+	for _, d := range defs {
+		params := shared.FunctionParameters(d.InputSchema)
+		if params == nil {
+			params = shared.FunctionParameters{"type": "object", "properties": map[string]any{}}
+		}
+
+		tools = append(tools, openai.ChatCompletionToolParam{
+			Type: "function",
+			Function: shared.FunctionDefinitionParam{
+				Name:        d.Name,
+				Description: openai.String(d.Description),
+				Parameters:  params,
+			},
+		})
+	}
+	return tools, nil
+}
+
+func (c *mcpClient) listToolsFull() ([]toolDef, error) {
+	resp, err := c.doRequest("tools/list", map[string]any{})
+	if err != nil {
+		return nil, err
+	}
+	var tr struct {
+		Tools []struct {
+			Name        string         `json:"name"`
+			Description string         `json:"description"`
+			InputSchema map[string]any `json:"inputSchema"`
+		} `json:"tools"`
+	}
+	if err := json.Unmarshal(resp.Result, &tr); err != nil {
+		return nil, err
+	}
+	out := make([]toolDef, len(tr.Tools))
+	for i, t := range tr.Tools {
+		out[i] = toolDef{
+			Name:        t.Name,
+			Description: t.Description,
+			InputSchema: t.InputSchema,
+		}
+	}
+	return out, nil
+}

cmd/nomos/main.go

@@ -0,0 +1,463 @@
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		fmt.Fprintln(os.Stderr, "usage: nomos serve")
+		os.Exit(1)
+	}
+	mcpURL := os.Getenv("NOMOS_MCP_URL")
+	if mcpURL == "" {
+		mcpURL = "http://localhost:8090/mcp"
+	}
+
+	agentSlug := os.Getenv("NOMOS_AGENT_SLUG")
+	if agentSlug == "" {
+		agentSlug = "agent:nomos"
+	}
+
+	databaseURL := os.Getenv("DATABASE_URL")
+	if databaseURL == "" {
+		databaseURL = os.Getenv("OIKOS_DATABASE_URL")
+	}
+
+	switch os.Args[1] {
+	case "serve":
+		ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
+		defer cancel()
+
+		client, err := newMCPClient(mcpURL)
+		if err != nil {
+			slog.Error("nomos: mcp connect", "url", mcpURL, "error", err)
+			os.Exit(1)
+		}
+
+		st, err := newStore(ctx, databaseURL)
+		if err != nil {
+			slog.Error("nomos: db connect", "error", err)
+			os.Exit(1)
+		}
+		if st != nil {
+			defer st.close()
+		}
+
+		nAgent, err := newAgent(ctx, client, st, agentSlug)
+		if err != nil {
+			slog.Error("nomos: agent init", "error", err)
+			os.Exit(1)
+		}
+
+		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)
+		})
+		mux.HandleFunc("/chat", func(w http.ResponseWriter, r *http.Request) {
+			handleChat(w, r, nAgent, st)
+		})
+		mux.HandleFunc("/sessions", func(w http.ResponseWriter, r *http.Request) {
+			handleSessionsList(w, r, st)
+		})
+		mux.HandleFunc("/sessions/", func(w http.ResponseWriter, r *http.Request) {
+			handleSessionDetail(w, r, st)
+		})
+
+		addr := os.Getenv("NOMOS_LISTEN")
+		if addr == "" {
+			addr = ":8092"
+		}
+
+		srv := &http.Server{Addr: addr, Handler: mux}
+		go 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()
+
+	default:
+		fmt.Fprintf(os.Stderr, "unknown command: %s\n", os.Args[1])
+		os.Exit(1)
+	}
+}
+
+func sseEvent(w http.ResponseWriter, flusher http.Flusher, event agentEvent) {
+	data, _ := json.Marshal(event)
+	fmt.Fprintf(w, "data: %s\n\n", data)
+	flusher.Flush()
+}
+
+func handleChat(w http.ResponseWriter, r *http.Request, a *agent, st *store) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", 405)
+		return
+	}
+
+	var req struct {
+		SessionID string `json:"session_id"`
+		Message   string `json:"message"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "bad request: "+err.Error(), 400)
+		return
+	}
+	if req.Message == "" {
+		http.Error(w, "message is required", 400)
+		return
+	}
+
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "streaming not supported", 500)
+		return
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.WriteHeader(200)
+
+	ctx := r.Context()
+	sessionID := req.SessionID
+
+	if sessionID == "" {
+		title := truncate(req.Message, 80)
+		sess, err := st.createSession(ctx, title)
+		if err != nil {
+			slog.Error("nomos: create session", "error", err)
+			sessionID = "ephemeral"
+		} else {
+			sessionID = sess.ID
+		}
+	} else {
+		st.touchSession(ctx, 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)
+
+	sseEvent(w, flusher, agentEvent{Type: "session", Data: sessionID, SessionID: sessionID})
+
+	toolCalls := []map[string]any{}
+	var finalText string
+
+	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)
+			}
+		}
+		if ev.Type == "text" {
+			finalText, _ = ev.Data.(string)
+		}
+		sseEvent(w, flusher, 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) {
+	if st == nil {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{"sessions": []any{}})
+		return
+	}
+
+	if r.Method == http.MethodOptions {
+		return
+	}
+
+	sessions, err := st.listSessions(r.Context())
+	if err != nil {
+		http.Error(w, err.Error(), 500)
+		return
+	}
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{"sessions": sessions})
+}
+
+func handleSessionDetail(w http.ResponseWriter, r *http.Request, st *store) {
+	if st == nil {
+		http.Error(w, "not found", 404)
+		return
+	}
+
+	id := strings.TrimPrefix(r.URL.Path, "/sessions/")
+	if id == "" {
+		http.Error(w, "session id required", 400)
+		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, "messages": messages})
+}
+
+func handleQuery(w http.ResponseWriter, r *http.Request, client *mcpClient, agentSlug, mcpURL string) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", 405)
+		return
+	}
+
+	var req struct {
+		Query string         `json:"query"`
+		Tool  string         `json:"tool"`
+		Args  map[string]any `json:"args"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, "bad request: "+err.Error(), 400)
+		return
+	}
+
+	start := time.Now()
+
+	if req.Tool != "" {
+		result, err := client.callTool(req.Tool, req.Args)
+		duration := time.Since(start).Milliseconds()
+		if err != nil {
+			slog.Error("nomos: query failed", "tool", req.Tool, "error", err)
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(map[string]any{
+				"error":      err.Error(),
+				"elapsed_ms": duration,
+				"agent_slug": agentSlug,
+			})
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"result":     result,
+			"elapsed_ms": duration,
+			"agent_slug": agentSlug,
+			"mcp_url":    mcpURL,
+		})
+		return
+	}
+
+	if req.Query != "" {
+		if strings.Contains(strings.ToLower(req.Query), "what can you do") ||
+			strings.Contains(strings.ToLower(req.Query), "help") {
+
+			tools, err := client.listTools()
+			duration := time.Since(start).Milliseconds()
+			if err != nil {
+				w.Header().Set("Content-Type", "application/json")
+				json.NewEncoder(w).Encode(map[string]any{
+					"error":      err.Error(),
+					"elapsed_ms": duration,
+				})
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(map[string]any{
+				"message":    "natural language queries belong to /chat. Use structured /query with 'tool' for direct MCP calls.",
+				"tools":      tools,
+				"elapsed_ms": duration,
+			})
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"message":    "natural language queries belong to /chat. Use structured /query with 'tool' for direct MCP calls.",
+			"elapsed_ms": time.Since(start).Milliseconds(),
+		})
+		return
+	}
+
+	http.Error(w, "either 'tool' or 'query' required", 400)
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}
+
+// ─── MCP Streamable HTTP client ────────────────────────────────────────
+
+type mcpClient struct {
+	baseURL   string
+	sessionID string
+	http      *http.Client
+	nextID    int
+	mu        sync.Mutex // MCP is one stateful session; serialize concurrent calls
+}
+
+func newMCPClient(baseURL string) (*mcpClient, error) {
+	c := &mcpClient{
+		baseURL: baseURL,
+		http:    &http.Client{Timeout: 30 * time.Second},
+	}
+
+	resp, err := c.doRequest("initialize", map[string]any{
+		"protocolVersion": "2024-11-05",
+		"capabilities":    map[string]any{},
+		"clientInfo":      map[string]any{"name": "nomos", "version": "2.0"},
+	})
+	if err != nil {
+		return nil, fmt.Errorf("initialize: %w", err)
+	}
+	if resp.sessionID == "" {
+		return nil, fmt.Errorf("no session ID in initialize response")
+	}
+	c.sessionID = resp.sessionID
+
+	c.doRequest("notifications/initialized", map[string]any{})
+
+	slog.Info("nomos: mcp connected", "session", c.sessionID[:16]+"...")
+	return c, nil
+}
+
+type mcpJSONRPCResponse struct {
+	sessionID string
+	Result    json.RawMessage `json:"result"`
+	Error     json.RawMessage `json:"error"`
+}
+
+func (c *mcpClient) doRequest(method string, params map[string]any) (*mcpJSONRPCResponse, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.nextID++
+	body, _ := json.Marshal(map[string]any{
+		"jsonrpc": "2.0",
+		"method":  method,
+		"params":  params,
+		"id":      c.nextID,
+	})
+
+	req, err := http.NewRequest(http.MethodPost, c.baseURL, bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "application/json, text/event-stream")
+	if c.sessionID != "" {
+		req.Header.Set("Mcp-Session-Id", c.sessionID)
+	}
+
+	resp, err := c.http.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	result := &mcpJSONRPCResponse{}
+	result.sessionID = resp.Header.Get("Mcp-Session-Id")
+
+	scanner := bufio.NewScanner(resp.Body)
+	for scanner.Scan() {
+		line := scanner.Text()
+		if strings.HasPrefix(line, "data: ") {
+			data := line[6:]
+			if err := json.Unmarshal([]byte(data), result); err != nil {
+				return nil, fmt.Errorf("parse response: %w", err)
+			}
+		}
+	}
+
+	if result.Error != nil {
+		return nil, fmt.Errorf("rpc error: %s", string(result.Error))
+	}
+
+	if result.sessionID != "" {
+		c.sessionID = result.sessionID
+	}
+
+	return result, nil
+}
+
+func (c *mcpClient) callTool(name string, args map[string]any) (any, error) {
+	resp, err := c.doRequest("tools/call", map[string]any{
+		"name":      name,
+		"arguments": args,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	var toolResult struct {
+		Content []struct {
+			Type string `json:"type"`
+			Text string `json:"text"`
+		} `json:"content"`
+	}
+	if err := json.Unmarshal(resp.Result, &toolResult); err != nil {
+		return string(resp.Result), nil
+	}
+
+	var texts []string
+	for _, c := range toolResult.Content {
+		if c.Type == "text" {
+			var parsed any
+			if json.Unmarshal([]byte(c.Text), &parsed) == nil {
+				return parsed, nil
+			}
+			texts = append(texts, c.Text)
+		}
+	}
+	if len(texts) == 1 {
+		return texts[0], nil
+	}
+	return texts, nil
+}
+
+func (c *mcpClient) listTools() ([]string, error) {
+	resp, err := c.doRequest("tools/list", map[string]any{})
+	if err != nil {
+		return nil, err
+	}
+	var tr struct {
+		Tools []struct {
+			Name        string `json:"name"`
+			Description string `json:"description"`
+		} `json:"tools"`
+	}
+	if err := json.Unmarshal(resp.Result, &tr); err != nil {
+		return nil, err
+	}
+	var names []string
+	for _, t := range tr.Tools {
+		names = append(names, t.Name)
+	}
+	return names, nil
+}
+
+func (c *mcpClient) close() {
+}

cmd/nomos/store.go

@@ -0,0 +1,156 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+type store struct {
+	pool *pgxpool.Pool
+}
+
+func newStore(ctx context.Context, databaseURL string) (*store, error) {
+	if databaseURL == "" {
+		return nil, nil
+	}
+	pool, err := pgxpool.New(ctx, databaseURL)
+	if err != nil {
+		return nil, fmt.Errorf("connect db: %w", err)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		return nil, fmt.Errorf("ping db: %w", err)
+	}
+	return &store{pool: pool}, nil
+}
+
+func (s *store) close() {
+	if s.pool != nil {
+		s.pool.Close()
+	}
+}
+
+type session struct {
+	ID           string    `json:"id"`
+	Title        string    `json:"title"`
+	Actor        string    `json:"actor"`
+	CreatedAt    time.Time `json:"created_at"`
+	LastActiveAt time.Time `json:"last_active_at"`
+}
+
+type message struct {
+	ID        string          `json:"id"`
+	SessionID string          `json:"session_id"`
+	Role      string          `json:"role"`
+	Content   json.RawMessage `json:"content"`
+	CreatedAt time.Time       `json:"created_at"`
+}
+
+func (s *store) createSession(ctx context.Context, title string) (*session, error) {
+	if s == nil {
+		return &session{ID: "ephemeral", Title: title, Actor: "agent:nomos"}, nil
+	}
+	var id string
+	err := s.pool.QueryRow(ctx,
+		`INSERT INTO agent_sessions (title, actor) VALUES ($1, 'agent:nomos') RETURNING id`,
+		title).Scan(&id)
+	if err != nil {
+		return nil, err
+	}
+	return &session{ID: id, Title: title, Actor: "agent:nomos", CreatedAt: time.Now(), LastActiveAt: time.Now()}, nil
+}
+
+func (s *store) saveMessage(ctx context.Context, sessionID, role string, content json.RawMessage) error {
+	if s == nil {
+		return nil
+	}
+	_, err := s.pool.Exec(ctx,
+		`INSERT INTO agent_messages (session_id, role, content) VALUES ($1, $2, $3)`,
+		sessionID, role, content)
+	return err
+}
+
+func (s *store) touchSession(ctx context.Context, id string) {
+	if s != nil {
+		s.pool.Exec(ctx, `UPDATE agent_sessions SET last_active_at=now() WHERE id=$1`, id)
+	}
+}
+
+func (s *store) listSessions(ctx context.Context) ([]session, error) {
+	if s == nil {
+		return nil, nil
+	}
+	rows, err := s.pool.Query(ctx,
+		`SELECT id, title, actor, created_at, last_active_at FROM agent_sessions ORDER BY last_active_at DESC LIMIT 50`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []session
+	for rows.Next() {
+		var sess session
+		if err := rows.Scan(&sess.ID, &sess.Title, &sess.Actor, &sess.CreatedAt, &sess.LastActiveAt); err != nil {
+			return nil, err
+		}
+		out = append(out, sess)
+	}
+	return out, rows.Err()
+}
+
+func (s *store) getMessages(ctx context.Context, sessionID string) ([]message, error) {
+	if s == nil {
+		return nil, nil
+	}
+	rows, err := s.pool.Query(ctx,
+		`SELECT id, session_id, role, content, created_at FROM agent_messages WHERE session_id=$1 ORDER BY created_at ASC`,
+		sessionID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var out []message
+	for rows.Next() {
+		var m message
+		if err := rows.Scan(&m.ID, &m.SessionID, &m.Role, &m.Content, &m.CreatedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, m)
+	}
+	return out, rows.Err()
+}
+
+// resolveAgentID looks up the UUID of the agent entity (e.g. "agent:nomos").
+// Returns uuid.Nil if the store is absent or the slug is unknown.
+func (s *store) resolveAgentID(ctx context.Context, slug string) uuid.UUID {
+	if s == nil {
+		return uuid.Nil
+	}
+	var id uuid.UUID
+	if err := s.pool.QueryRow(ctx, `SELECT id FROM entities WHERE slug = $1`, slug).Scan(&id); err != nil {
+		return uuid.Nil
+	}
+	return id
+}
+
+// logActivity records a tool call. agent_id is the agent entity UUID and is
+// NOT NULL in the schema, so we skip logging when it can't be resolved.
+// The (nullable) session_id column carries the conversation id.
+func (s *store) logActivity(ctx context.Context, agentID uuid.UUID, sessionID, toolName, inputSummary, outputSummary string, durationMs int, success bool, correlationID string) {
+	if s == nil || agentID == uuid.Nil {
+		return
+	}
+	s.pool.Exec(ctx, `
+		INSERT INTO agent_activity
+		    (agent_id, session_id, activity_type, tool_name, input_summary, output_summary,
+		     duration_ms, success, correlation_id)
+		VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+		agentID, sessionID, "tool_call", toolName, inputSummary, outputSummary,
+		durationMs, success, correlationID)
+}

cmd/oikos/main.go

@@ -4,13 +4,12 @@ import (
 	"context"
 	"fmt"
 	"log/slog"
+	"net/http"
 	"os"
 	"os/signal"
 	"strings"
 	"syscall"
 
-	"net/http"
-
 	"github.com/dtoro/oikos/internal/config"
 	"github.com/dtoro/oikos/internal/db"
 	"github.com/dtoro/oikos/internal/httpapi"
@@ -19,9 +18,42 @@ 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.
+func uiHandler() http.Handler {
+	dist, err := web.DistFS()
+	if err != nil {
+		slog.Warn("ui: embedded assets unavailable", "error", err)
+		return http.NotFoundHandler()
+	}
+	fileServer := http.FileServer(http.FS(dist))
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		path := strings.TrimPrefix(strings.TrimPrefix(r.URL.Path, "/ui"), "/")
+		if path == "" {
+			path = "index.html"
+		}
+		if f, err := dist.Open(path); err == nil {
+			f.Close()
+			r.URL.Path = "/" + path
+			fileServer.ServeHTTP(w, r)
+			return
+		}
+		// SPA fallback: serve index.html for unknown client-side routes.
+		if f, err := dist.Open("index.html"); err == nil {
+			f.Close()
+			r.URL.Path = "/index.html"
+			fileServer.ServeHTTP(w, r)
+			return
+		}
+		http.NotFound(w, r)
+	})
+}
+
 var schedulerRunner = scheduler.RunnerForMain()
 var notifierRunner = notifier.RunnerForMain()
 
@@ -86,7 +118,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); err != nil {
+		if err := httpapi.ListenAndServe(ctx, pool, cfg, uiHandler()); err != nil {
 			slog.Error("api failed", "error", err)
 			os.Exit(1)
 		}
@@ -120,7 +152,7 @@ Roles:
   knowledge  Convert wiki to knowledge seed (one-shot)
   version    Print version info
 
-The operator interface is Hermes (MCP agent) — no CLI needed.
+The operator interface is Nomos (MCP agent) — no CLI needed.
 Environment:
   OIKOS_DATABASE_URL    Postgres connection string
   OIKOS_API_LISTEN      API listen address (default :8090)
@@ -265,7 +297,7 @@ func runAPI(ctx context.Context, cfg config.Config) error {
 		return fmt.Errorf("migrations: %w", err)
 	}
 
-	err = httpapi.ListenAndServe(ctx, pool, cfg)
+	err = httpapi.ListenAndServe(ctx, pool, cfg, uiHandler())
 	if err == http.ErrServerClosed {
 		return nil
 	}

compose/caddy/Caddyfile.oikos

@@ -11,18 +11,25 @@ oikos.hubris.network {
     handle @enroll {
         reverse_proxy <mac-mini-mesh-ip>: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
+    }
     handle {
         import authentik
         reverse_proxy <mac-mini-mesh-ip>:8090
     }
 }
 
-# Oikos MCP endpoint (Hermes agents) — no auth required
+# Oikos MCP endpoint (agents) — no auth required
 mcp.hubris.network {
     reverse_proxy <mac-mini-mesh-ip>:8090
 }
 
-# Hermes gateway (workstation access)
-hermes.hubris.network {
+# Nomos gateway (workstation access) — formerly hermes.hubris.network
+nomos.hubris.network {
     reverse_proxy <mac-mini-mesh-ip>:8092
 }

compose/hermes/Dockerfile

@@ -1,25 +0,0 @@
-# Hermes agent container — standalone MCP client gateway (Phase 4)
-FROM golang:1.26-alpine AS builder
-
-RUN apk add --no-cache git ca-certificates
-
-WORKDIR /build
-COPY go.mod go.sum ./
-RUN go mod download
-
-COPY . .
-
-RUN CGO_ENABLED=0 go build -o /hermes -tags timetzdata -ldflags="-s -w" ./cmd/hermes
-
-FROM gcr.io/distroless/static:nonroot
-
-COPY --from=builder /hermes /hermes
-COPY hermes/ /app/hermes/
-
-ENV HERMES_MCP_URL=http://api:8090/mcp
-ENV HERMES_AGENT_SLUG=agent:hermes
-ENV HERMES_LISTEN=:8092
-
-EXPOSE 8092
-
-ENTRYPOINT ["/hermes", "serve"]

compose/nomos/Dockerfile

@@ -0,0 +1,26 @@
+# Nomos agent container — standalone MCP client gateway (Phase 4)
+FROM golang:1.26-alpine AS builder
+
+RUN apk add --no-cache git ca-certificates
+
+WORKDIR /build
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+RUN CGO_ENABLED=0 go build -o /nomos -tags timetzdata -ldflags="-s -w" ./cmd/nomos
+
+FROM gcr.io/distroless/static:nonroot
+
+COPY --from=builder /nomos /nomos
+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
+
+EXPOSE 8092
+
+ENTRYPOINT ["/nomos", "serve"]

compose/oikos/Dockerfile

@@ -1,4 +1,14 @@
 # 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
 FROM golang:1.26-alpine AS builder
 
 RUN apk add --no-cache git ca-certificates
@@ -8,6 +18,8 @@ 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
 
@@ -17,5 +29,6 @@ FROM gcr.io/distroless/static:nonroot
 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"]

docker-compose.yml

@@ -60,7 +60,8 @@ services:
       OIKOS_API_LISTEN: ":8090"
       OIKOS_ENV: dev
       OIKOS_DEBUG: "true"
-      OIKOS_HERMES_AGENT_SLUG: ${OIKOS_HERMES_AGENT_SLUG:-agent:hermes}
+      OIKOS_NOMOS_AGENT_SLUG: ${OIKOS_NOMOS_AGENT_SLUG:-agent:nomos}
+      NOMOS_PROXY_URL: http://nomos:8092
     volumes:
       - ${OIKOS_SSH_KEY_PATH:-~/.ssh/id_ed25519}:/etc/oikos/ssh_key:ro
     ports:
@@ -107,18 +108,21 @@ services:
     stop_signal: SIGTERM
     stop_grace_period: 30s
 
-  # Hermes agent gateway (Phase 4) — mesh-published :8092
-  hermes:
+  # Nomos agent gateway (Phase 4) — mesh-published :8092
+  nomos:
     build:
       context: .
-      dockerfile: compose/hermes/Dockerfile
+      dockerfile: compose/nomos/Dockerfile
     profiles: ["full"]
     depends_on:
       api:
         condition: service_started
     environment:
-      HERMES_MCP_URL: http://api:8090/mcp
-      HERMES_AGENT_SLUG: agent:hermes
+      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}
+      DATABASE_URL: postgres://oikos:${OIKOS_DB_PASSWORD:-oikos_dev}@postgres:5432/oikos?sslmode=disable
     ports:
       - "8092:8092"
     stop_signal: SIGTERM

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

@@ -231,3 +231,12 @@ sequenceDiagram
 - **The DB is the single source of truth.** All state transitions,
   audit entries, and event emissions go through Postgres. The scheduler,
   actuator, notifier, and API all read/write the same tables.
+
+---
+
+**2026-07-08 — renamed to Nomos.** The Hermes agent gateway was renamed to
+Nomos (from *oikonomos*, the steward of the oikos) under the
+[Nomos resident agent plan](../../plans/2026-07-08-nomos-resident-agent.md),
+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/operations/rollback.md

@@ -70,7 +70,7 @@ curl http://localhost:8090/healthz
 # Entity count matches
 curl -s http://localhost:8090/api/v1/entities?limit=1 | jq '.items | length'
 
-# MCP tools working (via Hermes)
+# MCP tools working (via Nomos)
 curl -s http://localhost:8092/query -d '{"tool":"get_health_summary"}'
 ```
 

go.mod

@@ -8,11 +8,14 @@ require (
 	github.com/golang-jwt/jwt/v5 v5.3.1
 	github.com/google/jsonschema-go v0.4.3
 	github.com/google/uuid v1.6.0
+	github.com/infisical/go-sdk v0.8.0
 	github.com/jackc/pgx/v5 v5.10.0
 	github.com/modelcontextprotocol/go-sdk v1.6.1
 	github.com/oapi-codegen/runtime v1.4.2
+	github.com/openai/openai-go v1.12.0
 	golang.org/x/crypto v0.53.0
 	golang.org/x/sync v0.21.0
+	golang.org/x/sys v0.46.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -47,7 +50,6 @@ require (
 	github.com/googleapis/enterprise-certificate-proxy v0.3.11 // indirect
 	github.com/googleapis/gax-go/v2 v2.17.0 // indirect
 	github.com/hashicorp/golang-lru/v2 v2.0.7 // indirect
-	github.com/infisical/go-sdk v0.8.0 // indirect
 	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
@@ -60,6 +62,10 @@ require (
 	github.com/segmentio/asm v1.1.3 // indirect
 	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/sony/gobreaker v0.5.0 // indirect
+	github.com/tidwall/gjson v1.14.4 // indirect
+	github.com/tidwall/match v1.1.1 // indirect
+	github.com/tidwall/pretty v1.2.1 // indirect
+	github.com/tidwall/sjson v1.2.5 // indirect
 	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
@@ -70,7 +76,6 @@ require (
 	go.opentelemetry.io/otel/trace v1.39.0 // indirect
 	golang.org/x/net v0.55.0 // indirect
 	golang.org/x/oauth2 v0.35.0 // indirect
-	golang.org/x/sys v0.46.0 // indirect
 	golang.org/x/text v0.38.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/api v0.267.0 // indirect

go.sum

@@ -38,12 +38,19 @@ github.com/aws/smithy-go v1.20.2/go.mod h1:krry+ya/rV9RDcV/Q16kpu6ypI4K2czasz0NC
 github.com/bmatcuk/doublestar v1.1.1/go.mod h1:UD6OnuiIn0yFxxA2le/rnRU1G4RaI4UvFv1sNto9p6w=
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 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/coreos/go-systemd/v22 v22.3.2/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
 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/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=
+github.com/envoyproxy/protoc-gen-validate v1.3.0 h1:TvGH1wof4H33rezVKWSpqKz5NXWg5VPuZ0uONDT6eb4=
+github.com/envoyproxy/protoc-gen-validate v1.3.0/go.mod h1:HvYl7zwPa5mffgyeTUHA9zHIH36nmrm7oCbo4YKoSWA=
 github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
 github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
 github.com/getkin/kin-openapi v0.140.0 h1:JFn675aXRFjyiZKa/BFWploGldQlI0gobp4J5k0EZ2g=
@@ -68,6 +75,8 @@ 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=
 github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
 github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
 github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
@@ -93,8 +102,8 @@ github.com/jackc/pgx/v5 v5.10.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QII
 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/juju/gnuflag v0.0.0-20171113085948-2ce1bb71843d/go.mod h1:2PavIy+JPciBPrBUjwbNvtwB6RQlve+hkpll6QSNmOE=
-github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0=
-github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk=
+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/modelcontextprotocol/go-sdk v1.6.1 h1:0zOSupjKUxPKSocPT1Wtago+mUHU2/uZ4xSOY0FGReU=
@@ -107,9 +116,13 @@ github.com/oasdiff/yaml v0.1.0 h1:0bqZjfKc/8S9urj4JuwepX41WX9EoA6ifhU3SV06cXg=
 github.com/oasdiff/yaml v0.1.0/go.mod h1:kOlRmMdL2X3vucLCEQO5u61SU22RysnfXvcttrZA1O0=
 github.com/oasdiff/yaml3 v0.0.13 h1:06svmvOHOVBqF81+sY2EUScvUI/iS/vl2VIeUUxZQwg=
 github.com/oasdiff/yaml3 v0.0.13/go.mod h1:y5+oSEHCPT/DGrS++Wc/479ERge0zTFxaF8PbGKcg2o=
+github.com/openai/openai-go v1.12.0 h1:NBQCnXzqOTv5wsgNC36PrFEiskGfO5wccfCWDo9S1U0=
+github.com/openai/openai-go v1.12.0/go.mod h1:g461MYGXEXBVdV5SaR/5tNzNbSfwTBBefwc+LlDCK0Y=
 github.com/oracle/oci-go-sdk/v65 v65.95.2 h1:0HJ0AgpLydp/DtvYrF2d4str2BjXOVAeNbuW7E07g94=
 github.com/oracle/oci-go-sdk/v65 v65.95.2/go.mod h1:u6XRPsw9tPziBh76K7GrrRXPa8P8W3BQeqJ6ZZt9VLA=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 h1:GFCKgmp0tecUJ0sJuv4pzYCqS9+RGSn52M3FUwPs+uo=
+github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10/go.mod h1:t/avpk3KcrXxUnYOhZhMXJlSEyie6gQbtLq5NM3loB8=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rogpeppe/go-internal v1.15.0 h1:D0RCU5rMAp+SpgkiNdrjfJ+LX4J1M32V2NeCY7EJ6hc=
@@ -136,6 +149,16 @@ github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tidwall/gjson v1.14.2/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/gjson v1.14.4 h1:uo0p8EbA09J7RQaflQ1aBRffTR7xedD2bcIVSYxLnkM=
+github.com/tidwall/gjson v1.14.4/go.mod h1:/wbyibRr2FHMks5tjHJ5F8dMZh3AcwJEMf5vlfC0lxk=
+github.com/tidwall/match v1.1.1 h1:+Ho715JplO36QYgwN9PGYNhgZvoUSc9X2c80KVTi+GA=
+github.com/tidwall/match v1.1.1/go.mod h1:eRSPERbgtNPcGhD8UCthc6PmLEQXEWd3PRB5JTxsfmM=
+github.com/tidwall/pretty v1.2.0/go.mod h1:ITEVvHYasfjBbM0u2Pg8T2nJnzm8xPwvNhhsoaGGjNU=
+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/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=
@@ -152,6 +175,10 @@ go.opentelemetry.io/otel v1.39.0 h1:8yPrr/S0ND9QEfTfdP9V+SiwT4E0G7Y5MO7p85nis48=
 go.opentelemetry.io/otel v1.39.0/go.mod h1:kLlFTywNWrFyEdH0oj2xK0bFYZtHRYUdv1NklR/tgc8=
 go.opentelemetry.io/otel/metric v1.39.0 h1:d1UzonvEZriVfpNKEVmHXbdf909uGTOQjA0HF0Ls5Q0=
 go.opentelemetry.io/otel/metric v1.39.0/go.mod h1:jrZSWL33sD7bBxg1xjrqyDjnuzTUB0x1nBERXd7Ftcs=
+go.opentelemetry.io/otel/sdk v1.39.0 h1:nMLYcjVsvdui1B/4FRkwjzoRVsMK8uL/cj0OyhKzt18=
+go.opentelemetry.io/otel/sdk v1.39.0/go.mod h1:vDojkC4/jsTJsE+kh+LXYQlbL8CgrEcwmt1ENZszdJE=
+go.opentelemetry.io/otel/sdk/metric v1.39.0 h1:cXMVVFVgsIf2YL6QkRF4Urbr/aMInf+2WKg+sEJTtB8=
+go.opentelemetry.io/otel/sdk/metric v1.39.0/go.mod h1:xq9HEVH7qeX69/JnwEfp6fVq5wosJsY1mt4lLfYdVew=
 go.opentelemetry.io/otel/trace v1.39.0 h1:2d2vfpEDmCJ5zVYz7ijaJdOF59xLomrvj7bjt6/qCJI=
 go.opentelemetry.io/otel/trace v1.39.0/go.mod h1:88w4/PnZSazkGzz/w84VHpQafiU4EtqqlVdxWy+rNOA=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
@@ -232,8 +259,12 @@ golang.org/x/tools v0.45.0/go.mod h1:LuUGqqaXcXMEFEruIVJVm5mgDD8vww/z/SR1gQ4uE/0
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
+gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
 google.golang.org/api v0.267.0 h1:w+vfWPMPYeRs8qH1aYYsFX68jMls5acWl/jocfLomwE=
 google.golang.org/api v0.267.0/go.mod h1:Jzc0+ZfLnyvXma3UtaTl023TdhZu6OMBP9tJ+0EmFD0=
+google.golang.org/genproto v0.0.0-20260128011058-8636f8732409 h1:VQZ/yAbAtjkHgH80teYd2em3xtIkkHd7ZhqfH2N9CsM=
+google.golang.org/genproto v0.0.0-20260128011058-8636f8732409/go.mod h1:rxKD3IEILWEu3P44seeNOAwZN4SaoKaQ/2eTg4mM6EM=
 google.golang.org/genproto/googleapis/api v0.0.0-20260128011058-8636f8732409 h1:merA0rdPeUV3YIIfHHcH4qBkiQAc1nfCKSI7lB4cV2M=
 google.golang.org/genproto/googleapis/api v0.0.0-20260128011058-8636f8732409/go.mod h1:fl8J1IvUjCilwZzQowmw2b7HQB2eAuYBabMXzWurF+I=
 google.golang.org/genproto/googleapis/rpc v0.0.0-20260203192932-546029d2fa20 h1:Jr5R2J6F6qWyzINc+4AM8t5pfUz6beZpHp678GNrMbE=

hermes/config.yaml

@@ -1,33 +0,0 @@
-# Hermes agent config — standalone MCP client gateway (Phase 4)
-
-mcp:
-  endpoint: ${HERMES_MCP_URL}?session_id=${HERMES_SESSION_ID}
-  transport: streamable_http
-
-server:
-  listen: ${HERMES_LISTEN}
-  mesh_only: true
-
-agent:
-  name: hermes
-  slug: ${HERMES_AGENT_SLUG}
-
-query_routing:
-  # Maps natural-language query patterns to MCP tools
-  - pattern: "depends on"
-    tool: get_blast_radius
-    entity_param: entity_id
-  - pattern: "restart"
-    tool: request_execution
-    action: restart
-  - pattern: "health"
-    tool: get_health_summary
-  - pattern: "what is"
-    tool: get_entity
-    entity_param: slug_or_id
-  - pattern: "recent events"
-    tool: get_event_timeline
-  - pattern: "signals"
-    tool: get_signal_history
-  - pattern: "patterns"
-    tool: get_patterns

internal/config/config.go

@@ -20,7 +20,7 @@ type Config struct {
 
 	// Auth (Phase 2: static bearer tokens + OIDC JWT)
 	APIToken       string // operator/CI bearer token for the REST API
-	MCPBearerToken string // shared secret for Hermes→API MCP calls
+	MCPBearerToken string // shared secret for Nomos→API MCP calls
 	OIDCIssuer     string // OIDC issuer URL for JWT validation (e.g. https://authentik.example.com/application/o/oikos/)
 	OIDCClientID   string // OIDC client ID (aud claim expected in JWT)
 
@@ -54,9 +54,9 @@ type Config struct {
 	// Approval HMAC secret (Phase 3)
 	ApprovalHMACSecret string
 
-	// Hermes agent entity ID (Phase 4)
-	HermesAgentID   string
-	HermesAgentSlug string
+	// Nomos agent entity ID (Phase 4)
+	NomosAgentID   string
+	NomosAgentSlug string
 
 	// Infisical (Phase 5)
 	InfisicalSiteURL      string
@@ -151,11 +151,11 @@ func FromEnv() Config {
 	if v := os.Getenv("OIKOS_APPROVAL_HMAC_SECRET"); v != "" {
 		c.ApprovalHMACSecret = v
 	}
-	if v := os.Getenv("OIKOS_HERMES_AGENT_ID"); v != "" {
-		c.HermesAgentID = v
+	if v := os.Getenv("OIKOS_NOMOS_AGENT_ID"); v != "" {
+		c.NomosAgentID = v
 	}
-	if v := os.Getenv("OIKOS_HERMES_AGENT_SLUG"); v != "" {
-		c.HermesAgentSlug = v
+	if v := os.Getenv("OIKOS_NOMOS_AGENT_SLUG"); v != "" {
+		c.NomosAgentSlug = v
 	}
 
 	// Phase 5: Infisical secrets

internal/httpapi/api_test.go

@@ -93,7 +93,7 @@ func newTestHandler(t *testing.T, cfg config.Config) http.Handler {
 		}
 	}
 
-	return NewHandler(handlerCtx, pool, cfg)
+	return NewHandler(handlerCtx, pool, cfg, nil)
 }
 
 func get(t *testing.T, h http.Handler, path string, headers map[string]string) (*httptest.ResponseRecorder, map[string]any) {

internal/httpapi/phase3.go

@@ -122,6 +122,16 @@ func resolveHostSSH(ctx context.Context, pool *db.Pool, entitySlug string) (stri
 
 // executeApprovedAction runs a gated action after operator approval.
 // Runs in a background goroutine to not block the HTTP response.
+// emitExecutionEvent records an execution lifecycle event for SSE fan-out so
+// the control room can watch approved actions run to completion live.
+func emitExecutionEvent(ctx context.Context, pool *db.Pool, execID uuid.UUID, status string, detail map[string]any) {
+	severity := "info"
+	if status == "failed" {
+		severity = "warning"
+	}
+	_ = observability.Event(ctx, sqlcgen.New(pool), "execution."+status, &execID, severity, "actuator", "", detail)
+}
+
 func executeApprovedAction(ctx context.Context, pool *db.Pool, execID uuid.UUID, targetSlug string, actionStr string) {
 	slog.Info("httpapi: executing approved action", "execution_id", execID, "target", targetSlug, "action", actionStr)
 
@@ -130,6 +140,7 @@ func executeApprovedAction(ctx context.Context, pool *db.Pool, execID uuid.UUID,
 		slog.Error("httpapi: resolve host for approved execution", "error", err, "target", targetSlug)
 		pool.Exec(ctx, `UPDATE executions SET status='failed', result=$2::jsonb WHERE entity_id=$1`,
 			execID, fmt.Sprintf(`{"error":"%s"}`, err.Error()))
+		emitExecutionEvent(ctx, pool, execID, "failed", map[string]any{"target": targetSlug, "error": err.Error()})
 		return
 	}
 
@@ -186,6 +197,10 @@ func executeApprovedAction(ctx context.Context, pool *db.Pool, execID uuid.UUID,
 	pool.Exec(ctx, `UPDATE executions SET status=$2, result=$3::jsonb, duration_ms=$4, verified=$5, started_at=$6, completed_at=$7 WHERE entity_id=$1`,
 		execID, status, result, durationMs, verified, startedAt, time.Now())
 
+	emitExecutionEvent(ctx, pool, execID, status, map[string]any{
+		"action": action, "target": targetSlug, "duration_ms": durationMs,
+	})
+
 	slog.Info("httpapi: approved action executed",
 		"execution_id", execID, "action", action, "status", status, "duration_ms", durationMs)
 }
@@ -947,6 +962,12 @@ func (s *Server) DecideApproval(ctx context.Context, req gen.DecideApprovalReque
 		return nil, auditErr
 	}
 
+	// Emit for SSE fan-out (in-tx; NOTIFY fires post-commit).
+	if evErr := observability.Event(ctx, q, "approval.decided", &id, "info", "api", "",
+		map[string]any{"decision": status, "actor": actor}); evErr != nil {
+		return nil, evErr
+	}
+
 	// On approve: execute the linked gated command.
 	if status == "approved" {
 		var execID, targetID uuid.UUID

internal/httpapi/server.go

@@ -15,6 +15,9 @@ import (
 	"log/slog"
 	"math/big"
 	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
 	"strings"
 	"sync"
 	"time"
@@ -66,7 +69,7 @@ type secretsBackend interface {
 // holds a dedicated pooled connection for LISTEN. Callers MUST cancel ctx
 // before closing the pool — otherwise the held connection never releases
 // and pool.Close() deadlocks.
-func NewHandler(ctx context.Context, pool *db.Pool, cfg config.Config) http.Handler {
+func NewHandler(ctx context.Context, pool *db.Pool, cfg config.Config, uiHandler http.Handler) http.Handler {
 	s := &Server{
 		pool:      pool,
 		cfg:       cfg,
@@ -137,16 +140,34 @@ func NewHandler(ctx context.Context, pool *db.Pool, cfg config.Config) http.Hand
 	r.With(combinedAuth(cfg)).Get("/api/v1/events/stream", s.serveSSE)
 
 	// Mount MCP at /mcp (plan R3-10)
-	hermesAgentID := uuid.Nil
-	if cfg.HermesAgentID != "" {
-		if id, err := uuid.Parse(cfg.HermesAgentID); err == nil {
-			hermesAgentID = id
+	nomosAgentID := uuid.Nil
+	if cfg.NomosAgentID != "" {
+		if id, err := uuid.Parse(cfg.NomosAgentID); err == nil {
+			nomosAgentID = id
 		}
 	}
-	if hermesAgentID == uuid.Nil && cfg.HermesAgentSlug != "" {
-		_ = pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", cfg.HermesAgentSlug).Scan(&hermesAgentID)
+	if nomosAgentID == uuid.Nil && cfg.NomosAgentSlug != "" {
+		_ = pool.QueryRow(ctx, "SELECT id FROM entities WHERE slug = $1", cfg.NomosAgentSlug).Scan(&nomosAgentID)
+	}
+	r.With(combinedAuth(cfg)).Handle("/mcp", mcphandler.NewHandler(pool, cfg.MCPBearerToken, nomosAgentID))
+
+	r.Get("/ui/*", func(w http.ResponseWriter, req *http.Request) {
+		if uiHandler != nil {
+			uiHandler.ServeHTTP(w, req)
+		}
+	})
+	r.Get("/ui", func(w http.ResponseWriter, req *http.Request) {
+		http.Redirect(w, req, "/ui/", http.StatusMovedPermanently)
+	})
+	r.Get("/", func(w http.ResponseWriter, req *http.Request) {
+		http.Redirect(w, req, "/ui/", http.StatusMovedPermanently)
+	})
+
+	if nomosURL := os.Getenv("NOMOS_PROXY_URL"); nomosURL != "" {
+		target, _ := url.Parse(nomosURL)
+		proxy := httputil.NewSingleHostReverseProxy(target)
+		r.Mount("/agent", http.StripPrefix("/agent", proxy))
 	}
-	r.With(combinedAuth(cfg)).Handle("/mcp", mcphandler.NewHandler(pool, cfg.MCPBearerToken, hermesAgentID))
 
 	return r
 }
@@ -484,10 +505,10 @@ func requestLogger(next http.Handler) http.Handler {
 
 // ListenAndServe runs the API server with graceful shutdown on ctx cancel
 // (SG4): stop accepting, drain in-flight for up to 30s, then exit.
-func ListenAndServe(ctx context.Context, pool *db.Pool, cfg config.Config) error {
+func ListenAndServe(ctx context.Context, pool *db.Pool, cfg config.Config, uiHandler http.Handler) error {
 	srv := &http.Server{
 		Addr:              cfg.APIListen,
-		Handler:           NewHandler(ctx, pool, cfg),
+		Handler:           NewHandler(ctx, pool, cfg, uiHandler),
 		ReadHeaderTimeout: 10 * time.Second,
 	}
 

internal/mcp/server.go

@@ -14,6 +14,8 @@ import (
 	"time"
 
 	"github.com/dtoro/oikos/internal/db"
+	"github.com/dtoro/oikos/internal/db/sqlcgen"
+	"github.com/dtoro/oikos/internal/observability"
 	"github.com/google/jsonschema-go/jsonschema"
 	"github.com/google/uuid"
 	"github.com/modelcontextprotocol/go-sdk/mcp"
@@ -37,7 +39,7 @@ func objSchema(props ...prop) *jsonschema.Schema {
 }
 
 // NewHandler creates an http.Handler that serves the Oikos MCP server.
-// agentID is the Hermes agent entity UUID; tool calls are logged to agent_activity.
+// agentID is the Nomos agent entity UUID; tool calls are logged to agent_activity.
 func NewHandler(pool *db.Pool, token string, agentID uuid.UUID) http.Handler {
 	s := newServer(pool, agentID)
 	handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
@@ -258,7 +260,7 @@ func newServer(pool *db.Pool, agentID uuid.UUID) *mcp.Server {
 			nStr(args["status"])), nil
 	})
 
-	register(&mcp.Tool{Name: "request_execution", Description: "Request a gated execution (Hermes-only mutation path). Supported actions: restart, systemctl, pct_exec, apt_upgrade.",
+	register(&mcp.Tool{Name: "request_execution", Description: "Request a gated execution (agent-only mutation path). Supported actions: restart, systemctl, pct_exec, apt_upgrade.",
 		InputSchema: objSchema(
 			prop{"target", "string", "Target entity slug (e.g. lxc:caddy)"},
 			prop{"action", "string", "Action: restart, systemctl, pct_exec, apt_upgrade"},
@@ -968,13 +970,27 @@ func resolveHost(ctx context.Context, pool *db.Pool, entitySlug string) (hostIP
 }
 
 func createApproval(ctx context.Context, pool *db.Pool, execID, targetID uuid.UUID, action, params, riskClass string) {
-	approvalID, _ := uuid.NewV7()
 	payload := fmt.Sprintf(`{"action":"%s","params":"%s","execution_id":"%s"}`, action, params, execID)
-	pool.Exec(ctx, `
+	// approvals.entity_id is PK + FK to entities(id). Reuse the execution's
+	// entity (already inserted by request_execution) so the FK is satisfied —
+	// a fresh UUID here had no matching entities row, so the INSERT silently
+	// failed, orphaning the execution and never alerting the operator. One
+	// execution maps to at most one approval, so the 1:1 identity holds.
+	if _, err := pool.Exec(ctx, `
 		INSERT INTO approvals (entity_id, subject_entity_id, action, risk_class,
 			kind, payload, status, expires_at, created_at)
 		VALUES ($1, $2, $3, $4, 'execution', $5::jsonb, 'pending',
 			now() + interval '1 hour', now())`,
-		approvalID, targetID, action, riskClass, payload)
-	pool.Exec(ctx, `UPDATE executions SET approval_id = $2 WHERE entity_id = $1`, execID, approvalID)
+		execID, targetID, action, riskClass, payload); err != nil {
+		slog.Error("createApproval: insert approval", "error", err, "execution", execID)
+		return
+	}
+	if _, err := pool.Exec(ctx, `UPDATE executions SET approval_id = $1 WHERE entity_id = $1`, execID); err != nil {
+		slog.Error("createApproval: link approval to execution", "error", err, "execution", execID)
+	}
+
+	// Emit for SSE fan-out — the operator-facing moment: an agent-requested
+	// gated action is now awaiting a decision.
+	_ = observability.Event(ctx, sqlcgen.New(pool), "approval.created", &execID, "warning", "mcp", "",
+		map[string]any{"action": action, "params": params, "risk_class": riskClass})
 }

internal/scheduler/scheduler.go

@@ -16,6 +16,7 @@ import (
 	"github.com/dtoro/oikos/internal/config"
 	"github.com/dtoro/oikos/internal/db"
 	"github.com/dtoro/oikos/internal/db/sqlcgen"
+	"github.com/dtoro/oikos/internal/observability"
 	"github.com/google/uuid"
 	"golang.org/x/sync/errgroup"
 	"golang.org/x/sys/unix"
@@ -98,6 +99,8 @@ func runCheck(ctx context.Context, pool *db.Pool, cd sqlcgen.ListEnabledCheckDef
 			"entity", cd.EntitySlug, "kind", cd.Kind, "error", checkErr)
 	}
 
+	prevHealth := currentHealth(ctx, pool, cd.EntityID)
+
 	if signalKind == "" || health == "healthy" {
 		// Recovery: resolve any open signal for this check
 		resolveSignal(ctx, pool, cd.EntityID, cd.EntitySlug)
@@ -108,6 +111,10 @@ func runCheck(ctx context.Context, pool *db.Pool, cd sqlcgen.ListEnabledCheckDef
 			LastCheckAt: &[]time.Time{time.Now()}[0],
 			Details:     []byte(`{}`),
 		})
+		if prevHealth != "" && prevHealth != "healthy" {
+			emitSchedulerEvent(ctx, pool, "health.changed", cd.EntityID, "info",
+				map[string]any{"slug": cd.EntitySlug, "from": prevHealth, "to": "healthy"})
+		}
 		return
 	}
 
@@ -140,17 +147,47 @@ func runCheck(ctx context.Context, pool *db.Pool, cd sqlcgen.ListEnabledCheckDef
 		Details:     []byte(`{}`),
 	})
 	_ = sig // used for flap detection below
+
+	// Emit only on transition into failure so a persistently-down entity
+	// doesn't flood the stream every tick.
+	if prevHealth == "" || prevHealth == "healthy" {
+		emitSchedulerEvent(ctx, pool, "signal.raised", cd.EntityID, severity,
+			map[string]any{"slug": cd.EntitySlug, "kind": signalKind, "evidence": evidence})
+	}
+	if prevHealth != health {
+		emitSchedulerEvent(ctx, pool, "health.changed", cd.EntityID, severity,
+			map[string]any{"slug": cd.EntitySlug, "from": prevHealth, "to": health})
+	}
+}
+
+// currentHealth reads the last recorded health for an entity, or "" if none.
+func currentHealth(ctx context.Context, pool *db.Pool, entityID uuid.UUID) string {
+	var health string
+	if err := pool.QueryRow(ctx,
+		`SELECT health FROM entity_status WHERE entity_id = $1`, entityID).Scan(&health); err != nil {
+		return ""
+	}
+	return health
+}
+
+// emitSchedulerEvent records a scheduler-sourced event for SSE fan-out.
+func emitSchedulerEvent(ctx context.Context, pool *db.Pool, eventType string, entityID uuid.UUID, severity string, data map[string]any) {
+	_ = observability.Event(ctx, sqlcgen.New(pool), eventType, &entityID, severity, "scheduler", "", data)
 }
 
 // resolveSignal resolves any open signal for the given check entity.
 func resolveSignal(ctx context.Context, pool *db.Pool, entityID uuid.UUID, slug string) {
 	q := sqlcgen.New(pool)
 	// Check if there's an open signal on this entity
-	_, err := pool.Exec(ctx, `UPDATE signals SET state = 'resolved', updated_at = now()
+	tag, err := pool.Exec(ctx, `UPDATE signals SET state = 'resolved', updated_at = now()
 		WHERE entity_id = $1 AND state = 'raised'`, entityID)
 	if err != nil {
 		return
 	}
+	if tag.RowsAffected() > 0 {
+		emitSchedulerEvent(ctx, pool, "signal.resolved", entityID, "info",
+			map[string]any{"slug": slug})
+	}
 	_ = q.UpsertEntityStatus(ctx, sqlcgen.UpsertEntityStatusParams{
 		EntityID:    entityID,
 		Health:      "healthy",

inventory.yaml

@@ -511,7 +511,7 @@ hosts:
       192.168.8.0/24. Re-enroll in mesh as a follow-up if off-LAN access
       to this host itself (not just its future guests) is needed.
     - First step of the planned library-SSD migration — see
-      .hermes/plans/2026-06-03_110000-library-ssd-migration-to-ludo-mini.md
+      .nomos/plans/2026-06-03_110000-library-ssd-migration-to-ludo-mini.md
       (filename kept as-is, it's a historical planning doc). Only Phase 1
       (Proxmox install + cluster join) is done; no physical
       drive move, service migration, or GPU passthrough has happened yet.
@@ -555,7 +555,7 @@ archaeology:
     kind: lxc
     pve_id: 123
     destroyed: 2026-06-04
-    reason: replaced by Hermes Agent on mac-mini; monitoring moved to homelab-health-watchdog cron
+    reason: replaced by Nomos Agent on mac-mini; monitoring moved to homelab-health-watchdog cron
   plato:
     kind: lxc
     pve_id: 126

migrations/014_rename_agent_hermes_to_nomos.up.sql

@@ -0,0 +1,18 @@
+-- 014_rename_agent_hermes_to_nomos.up.sql
+-- Rename the Hermes agent entity to Nomos (N0 milestone).
+-- Identity-preserving: the UUID, relationships, and audit history survive.
+-- The matching seed upsert will no-op because it upserts by slug.
+
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM entities WHERE slug = 'agent:hermes') THEN
+        UPDATE entities
+        SET slug = 'agent:nomos',
+            name = 'nomos',
+            attributes = jsonb_set(attributes, '{name}', '"nomos"'),
+            updated_at = now()
+        WHERE slug = 'agent:hermes'
+          AND NOT EXISTS (SELECT 1 FROM entities WHERE slug = 'agent:nomos');
+    END IF;
+END
+$$;

migrations/015_agent_sessions.up.sql

@@ -0,0 +1,25 @@
+-- 015_agent_sessions.up.sql
+-- Nomos agent sessions: persist conversations across restarts.
+-- agent_messages stores the full message history (JSONB).
+-- agent_activity is joined via correlation_id for tool-call tracing.
+
+CREATE TABLE IF NOT EXISTS agent_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    title TEXT NOT NULL DEFAULT '',
+    actor TEXT NOT NULL DEFAULT 'agent:nomos',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    last_active_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS agent_messages (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id UUID NOT NULL REFERENCES agent_sessions(id) ON DELETE CASCADE,
+    role TEXT NOT NULL,
+    content JSONB NOT NULL DEFAULT '{}',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_messages_session
+    ON agent_messages(session_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_active
+    ON agent_sessions(last_active_at DESC);

nomos/SOUL.md

@@ -1,7 +1,7 @@
-# SOUL.md — Hermes agent persona (Phase 4, container runtime)
+# SOUL.md — Nomos agent persona (Phase 4, container runtime)
 
-You are **Hermes**, the homelab AI agent running in a Docker container on
-mac-mini. You operate in **gateway mode** on mesh-only port 8092.
+You are **Nomos** (from *oikonomos*, the steward of the oikos), the homelab
+AI agent running in a Docker container on mac-mini. You operate on port 8092.
 
 ## Source of truth
 
@@ -45,6 +45,6 @@ describing state, be concise — the operator reads your output in Matrix.
 
 ## Skills
 
-Skills live in `/app/hermes/skills/`. Load a skill when its description
+Skills live in `/app/nomos/skills/`. Load a skill when its description
 matches the task. The `homelab-ops` skill covers:
 - Health checks, signal triage, pattern validation, and escalation flow.

nomos/config.yaml

@@ -0,0 +1,18 @@
+# Nomos agent config — LLM-backed resident agent (Phase 4)
+
+mcp:
+  endpoint: ${NOMOS_MCP_URL}?session_id=${NOMOS_SESSION_ID}
+  transport: streamable_http
+
+server:
+  listen: ${NOMOS_LISTEN}
+  mesh_only: true
+
+agent:
+  name: nomos
+  slug: ${NOMOS_AGENT_SLUG}
+
+llm:
+  provider: openrouter
+  model: ${NOMOS_MODEL}
+  max_iterations: 15

nomos/skills/homelab-ops/SKILL.md

@@ -6,7 +6,7 @@
 
 ## Overview
 
-Standard operating procedures for the Hermes agent managing the hubris
+Standard operating procedures for the Nomos agent managing the hubris
 homelab. All mutations route through `request_execution` → Oikos policy
 gating → actuator (SSH).
 
@@ -41,5 +41,8 @@ gating → actuator (SSH).
 
 ## Changelog
 
+### 2026-07-08 — rename to Nomos
+Agent renamed from Hermes to Nomos (N0 milestone).
+
 ### 2026-07-07 — initial Phase 4 skill
-Baseline homelab operations skill for Hermes container.
+Baseline homelab operations skill for Nomos container.

plans/2026-07-08-nomos-resident-agent.md

@@ -1,6 +1,6 @@
 # 2026-07-08 — Nomos resident agent (renames Hermes)
 
-**Status:** Planned
+**Status:** In Progress — N0-N3 complete 2026-07-08
 
 ## Goal
 

plans/index.md

@@ -12,7 +12,7 @@ went sideways, open an investigation.
 | 2026-07-08 | [Plan vs implementation cross-reference](2026-07-08-plan-implementation-audit.md) | Planned |
 | 2026-07-08 | [Oikos gaps, broken things, and improvements](2026-07-08-oikos-gaps-and-improvements.md) | Planned |
 | 2026-07-08 | [Control room web UI](2026-07-08-control-room-webui.md) | Planned |
-| 2026-07-08 | [Nomos resident agent (renames Hermes)](2026-07-08-nomos-resident-agent.md) | Planned |
+| 2026-07-08 | [Nomos resident agent (renames Hermes)](2026-07-08-nomos-resident-agent.md) | In Progress |
 
 ## Done
 

scripts/cutover-checklist.md

@@ -6,7 +6,7 @@ Status: [x] = done, [ ] = pending
 
 - [x] **Backup**: `pg_dump oikos > backups/pre-cutover-20260707.sql` (145K)
 - [x] **CI green**: pushed to main, `.gitea/workflows/ci.yml` exists
-- [x] **Deploy test**: Docker stack running with api + scheduler + notifier + hermes
+- [x] **Deploy test**: Docker stack running with api + scheduler + notifier + nomos
 - [x] **Caddy config**: `compose/caddy/Caddyfile.oikos` pushed to `dtoro/caddy-conf` (ed20908). Auto-deploys to caddy (121).
 - [x] **DNS**: `oikos.hubris.network` already resolves to 192.168.8.175 (mac-mini mesh)
 - [x] **Secrets**: Infisical bootstrapped + migration complete 2026-07-07. All 11 SOPS secrets migrated to Infisical (oikos project, dev env). Machine identity `oikos-api` has RW access verified via Go SDK. ENCRYPTION_KEY must be 32-char raw string (docs incorrect). SOPS fallback preserved for DR. secrets-issuance decommissioned — stopped/disabled on apps/105; superseded by Infisical.
@@ -23,7 +23,7 @@ Status: [x] = done, [ ] = pending
 ## Post-cutover verification
 
 - [x] **./scripts/verify-phase6.sh** — all 14 checks pass
-- [x] **Hermes query**: `curl http://localhost:8092/query -d '{"query":"fleet health"}'` → HTTP 200
+- [x] **Nomos query**: `curl http://localhost:8092/query -d '{"query":"fleet health"}'` → HTTP 200
 - [x] **Agent activity**: `curl http://localhost:8090/api/v1/agent-activity` → returns data
 - [x] **Scheduler ticking**: 30s ticks logged
 - [x] **Notifier polling**: running

scripts/verify-phase6.sh

@@ -27,7 +27,7 @@ check "4. Scheduler: check pass"             "http://localhost:8090/api/v1/check
 check "5. Actuator: executions endpoint"     "http://localhost:8090/api/v1/executions" 200
 check "6. Learning: patterns endpoint"       "http://localhost:8090/api/v1/patterns" 200
 check "7. Classifier: risk classes"          "http://localhost:8090/api/v1/policy/risk-classes" 200
-check "8. Hermes: gateway health"            "http://localhost:8092/healthz" 200
+check "8. Nomos: gateway health"            "http://localhost:8092/healthz" 200
 check "9. Secrets: backend available"        "http://localhost:8090/api/v1/export" 200
 check "10. Deploy: events endpoint"          "http://localhost:8090/api/v1/events" 200
 check "11. Knowledge: content search"        "http://localhost:8090/healthz" 200

seeds/inventory.yaml

@@ -325,7 +325,7 @@ entities:
      attributes: {matrix_id: "@dtoro:avispero"}}
   - {slug: "idp:authentik", type: identity-provider, name: authentik,
      attributes: {issuer: "https://auth.hubris.network", auth_mode: both}}
-  - {slug: "agent:hermes", type: agent, name: hermes,
+  - {slug: "agent:nomos", type: agent, name: nomos,
       state: active,
       attributes: {gateway_port: 8092, session_mode: smart_approve, note: "Phase 4 — Docker gateway mode"}}
   - {slug: "agent:oikos", type: agent, name: oikos,
@@ -334,7 +334,7 @@ entities:
 
   # ─── Archaeology (state: destroyed — kept for "what happened to X?") ─
   - {slug: "lxc:claudio-bot", type: lxc, name: claudio-bot, state: destroyed,
-     attributes: {pve_id: 123, destroyed: "2026-06-04", reason: "replaced by Hermes Agent on mac-mini"}}
+     attributes: {pve_id: 123, destroyed: "2026-06-04", reason: "replaced by Nomos Agent on mac-mini"}}
   - {slug: "lxc:plato", type: lxc, name: plato, state: destroyed,
      attributes: {pve_id: 126, destroyed: "2026-06-28", reason: "notes workspace decommissioned; data at /mnt/library/documents/plato"}}
   - {slug: "lxc:mule-photos-new", type: lxc, name: mule-photos-new, state: destroyed,
@@ -538,5 +538,5 @@ relationships:
   - {source: "lxc:rclone", target: "backup:proton-drive", type: backs-up-to}
 
   # ─── Governance ────────────────────────────────────────────────────
-  - {source: "person:dtoro", target: "agent:hermes", type: owns}
+  - {source: "person:dtoro", target: "agent:nomos", type: owns}
   - {source: "person:dtoro", target: "agent:oikos", type: owns}

seeds/ontology.yaml

@@ -531,7 +531,7 @@ entity_types:
     domain: identity
     layer: governance
     lifecycle: infrastructure   # agents are deployed/retired like infrastructure
-    description: Software agent actor (Hermes, the Oikos control loop).
+    description: Software agent actor (Nomos, the Oikos control loop).
     attributes:
       type: object
       properties:

tools/setup-hermes-soul.sh

@@ -1,14 +0,0 @@
-#!/usr/bin/env bash
-# setup-hermes-soul.sh — provision Hermes agent persona.
-# Copies ~/.hermes/SOUL.md from hermes/SOUL.md. No-op on non-Hermes agents.
-set -euo pipefail
-
-CLONE_DIR="${HOMELAB_CONTEXT_DIR:-/opt/homelab}"
-
-if [ -f "$CLONE_DIR/hermes/SOUL.md" ]; then
-    mkdir -p "$HOME/.hermes"
-    cp "$CLONE_DIR/hermes/SOUL.md" "$HOME/.hermes/SOUL.md"
-    echo "[setup-hermes-soul] SOUL.md provisioned"
-else
-    echo "[setup-hermes-soul] no hermes/SOUL.md found; skipping"
-fi

tools/setup-nomos-soul.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# setup-nomos-soul.sh — provision Nomos agent persona.
+# Copies ~/.nomos/SOUL.md from nomos/SOUL.md. No-op on non-Nomos agents.
+set -euo pipefail
+
+CLONE_DIR="${HOMELAB_CONTEXT_DIR:-/opt/homelab}"
+
+if [ -f "$CLONE_DIR/nomos/SOUL.md" ]; then
+    mkdir -p "$HOME/.nomos"
+    cp "$CLONE_DIR/nomos/SOUL.md" "$HOME/.nomos/SOUL.md"
+    echo "[setup-nomos-soul] SOUL.md provisioned"
+else
+    echo "[setup-nomos-soul] no nomos/SOUL.md found; skipping"
+fi

web/embed.go

@@ -0,0 +1,21 @@
+// Package web embeds the compiled control-room SPA (web/dist) into the oikos
+// binary, preserving the single-binary deployment (ADR-0001). The dist tree is
+// produced by `npm run build` (or the Docker ui-builder stage); a committed
+// web/dist/.gitkeep keeps a backend-only `go build` green when the UI has not
+// been built.
+package web
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:dist
+var dist embed.FS
+
+// DistFS returns the built SPA rooted at dist/. When the UI has not been built
+// (only the .gitkeep placeholder is present), Open("index.html") will fail and
+// the caller serves a 404 — the binary still starts.
+func DistFS() (fs.FS, error) {
+	return fs.Sub(dist, "dist")
+}

web/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Oikos — Control Room</title>
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>🏠</text></svg>" />
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

web/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "oikos-web",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && touch dist/.gitkeep",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "@tsconfig/svelte": "^5.0.0",
+    "svelte": "^5.0.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0"
+  }
+}

web/src/App.svelte

@@ -0,0 +1,155 @@
+<script lang="ts">
+  import Chat from '$lib/../pages/Chat.svelte'
+  import Sessions from '$lib/../pages/Sessions.svelte'
+  import { newChat } from '$lib/stores/chat'
+  import { onMount } from 'svelte'
+  import { slide } from 'svelte/transition'
+
+  let page = $state('chat')
+  let drawerOpen = $state(false)
+
+  onMount(() => {
+    function sync() {
+      page = location.hash.slice(2) || 'chat'
+    }
+    sync()
+    window.addEventListener('hashchange', sync)
+    return () => window.removeEventListener('hashchange', sync)
+  })
+
+  function navigate(p: string) {
+    location.hash = '#/' + p
+  }
+</script>
+
+<div class="app">
+  <nav class="sidebar">
+    <div class="logo">Oikos</div>
+    <button class="nav-btn" onclick={() => { newChat(); navigate('chat') }}>
+      <span class="nav-icon">✚</span>
+      <span>New</span>
+    </button>
+    <button class="nav-btn" class:active={page === 'chat'} onclick={() => navigate('chat')}>
+      <span class="nav-icon">💬</span>
+      <span>Chat</span>
+    </button>
+    <button class="nav-btn" class:active={page === 'sessions'} onclick={() => navigate('sessions')}>
+      <span class="nav-icon">📋</span>
+      <span>Sessions</span>
+    </button>
+
+    <div class="spacer"></div>
+
+    <button class="drawer-toggle" onclick={() => drawerOpen = !drawerOpen}>
+      Chat {drawerOpen ? '▼' : '▲'}
+    </button>
+  </nav>
+
+  <main class="main">
+    {#if page === 'chat'}
+      <Chat />
+    {:else if page === 'sessions'}
+      <Sessions />
+    {:else}
+      <Chat />
+    {/if}
+  </main>
+
+  {#if drawerOpen}
+    <aside class="drawer" transition:slide={{ axis: 'x' }}>
+      <Chat />
+    </aside>
+  {/if}
+</div>
+
+<style>
+  .app {
+    display: flex;
+    height: 100vh;
+    overflow: hidden;
+  }
+
+  .sidebar {
+    width: 56px;
+    background: var(--bg-surface);
+    border-right: 1px solid var(--border);
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 0.75rem 0;
+    gap: 0.5rem;
+  }
+
+  .logo {
+    font-size: 1.25rem;
+    font-weight: 700;
+    color: var(--accent-blue);
+    margin-bottom: 0.5rem;
+    user-select: none;
+  }
+
+  .nav-btn {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 2px;
+    padding: 0.5rem;
+    border: none;
+    background: none;
+    color: var(--text-muted);
+    font-family: inherit;
+    font-size: 0.625rem;
+    cursor: pointer;
+    border-radius: 6px;
+    width: 44px;
+    transition: background 0.15s, color 0.15s;
+  }
+
+  .nav-btn:hover {
+    background: var(--bg-hover);
+    color: var(--text);
+  }
+
+  .nav-btn.active {
+    background: var(--bg-active);
+    color: var(--accent-blue);
+  }
+
+  .nav-icon {
+    font-size: 1rem;
+  }
+
+  .spacer {
+    flex: 1;
+  }
+
+  .drawer-toggle {
+    border: none;
+    background: none;
+    color: var(--text-muted);
+    font-family: inherit;
+    font-size: 0.625rem;
+    cursor: pointer;
+    padding: 0.5rem;
+  }
+
+  .drawer-toggle:hover {
+    color: var(--text);
+  }
+
+  .main {
+    flex: 1;
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+  }
+
+  .drawer {
+    width: 380px;
+    border-left: 1px solid var(--border);
+    background: var(--bg);
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+  }
+</style>

web/src/app.css

@@ -0,0 +1,62 @@
+:root {
+  --bg: #0d1117;
+  --bg-surface: #161b22;
+  --bg-deeper: #0a0e13;
+  --bg-hover: #21262d;
+  --bg-active: #292e36;
+  --border: #30363d;
+  --text: #e6edf3;
+  --text-muted: #8b949e;
+  --accent-blue: #58a6ff;
+  --accent-green: #3fb950;
+  --accent-red: #f85149;
+  --accent-orange: #d29922;
+  --font-mono: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
+}
+
+*, *::before, *::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html, body {
+  height: 100%;
+  background: var(--bg);
+  color: var(--text);
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  font-size: 14px;
+  line-height: 1.4;
+  -webkit-font-smoothing: antialiased;
+}
+
+#app {
+  height: 100%;
+}
+
+::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--border);
+  border-radius: 3px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--text-muted);
+}
+
+a {
+  color: var(--accent-blue);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}

web/src/lib/api.ts

@@ -0,0 +1,92 @@
+const BASE = '/agent'
+
+export interface Session {
+  id: string
+  title: string
+  actor: string
+  created_at: string
+  last_active_at: string
+}
+
+export interface Message {
+  id: string
+  session_id: string
+  role: string
+  content: any
+  created_at: string
+}
+
+export async function fetchSessions(): Promise<Session[]> {
+  const res = await fetch(`${BASE}/sessions`)
+  if (!res.ok) return []
+  const data = await res.json()
+  return data.sessions ?? []
+}
+
+export async function fetchMessages(sessionId: string): Promise<Message[]> {
+  const res = await fetch(`${BASE}/sessions/${sessionId}`)
+  if (!res.ok) return []
+  const data = await res.json()
+  return data.messages ?? []
+}
+
+export interface ChatEvent {
+  type: string
+  data: any
+  session_id?: string
+  iteration?: number
+}
+
+export function streamChat(
+  message: string,
+  sessionId: string | null,
+  onEvent: (ev: ChatEvent) => void,
+  onError: (err: string) => void,
+  onDone: () => void
+): AbortController {
+  const controller = new AbortController()
+
+  fetch(`${BASE}/chat`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ message, session_id: sessionId ?? undefined }),
+    signal: controller.signal
+  }).then(async (res) => {
+    if (!res.ok) {
+      onError(`HTTP ${res.status}`)
+      return
+    }
+    const reader = res.body?.getReader()
+    if (!reader) {
+      onError('no response body')
+      return
+    }
+    const decoder = new TextDecoder()
+    let buffer = ''
+
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      const lines = buffer.split('\n')
+      buffer = lines.pop() ?? ''
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          try {
+            const ev: ChatEvent = JSON.parse(line.slice(6))
+            onEvent(ev)
+          } catch {
+            // skip malformed
+          }
+        }
+      }
+    }
+  }).catch((err) => {
+    onError(err.message)
+  }).finally(() => {
+    onDone()
+  })
+
+  return controller
+}

web/src/lib/stores/chat.ts

@@ -0,0 +1,162 @@
+import { writable, get } from 'svelte/store'
+import { streamChat, fetchSessions, fetchMessages } from '$lib/api'
+import type { ChatEvent, Session, Message } from '$lib/api'
+
+export interface ChatMessage {
+  id: string
+  role: 'user' | 'assistant'
+  text: string
+  tools: ToolCallResult[]
+}
+
+export interface ToolCallResult {
+  type: 'tool_use' | 'tool_result'
+  name: string
+  id?: string
+  args?: any
+  result?: any
+  error?: string
+}
+
+function mid(): string {
+  return crypto.randomUUID()
+}
+
+export const messages = writable<ChatMessage[]>([])
+export const streaming = writable(false)
+export const currentSession = writable<string | null>(null)
+export const sessions = writable<Session[]>([])
+export const sessionMessages = writable<Message[]>([])
+export const error = writable<string | null>(null)
+
+let activeController: AbortController | null = null
+
+export async function loadSessions() {
+  const list = await fetchSessions()
+  sessions.set(list)
+}
+
+export async function loadSessionMessages(sessionId: string) {
+  currentSession.set(sessionId)
+  const msgs = await fetchMessages(sessionId)
+  sessionMessages.set(msgs)
+  const chatMsgs: ChatMessage[] = msgs.map((m) => ({
+    id: m.id,
+    role: m.role as 'user' | 'assistant',
+    text: m.content?.text ?? (typeof m.content === 'string' ? m.content : ''),
+    tools: m.content?.tool_calls ?? []
+  }))
+  messages.set(chatMsgs)
+}
+
+export function sendMessage(text: string) {
+  error.set(null)
+  streaming.set(true)
+
+  const userMsg: ChatMessage = {
+    id: mid(),
+    role: 'user',
+    text,
+    tools: []
+  }
+  messages.update((ms) => [...ms, userMsg])
+
+  const assistantMsg: ChatMessage = {
+    id: mid(),
+    role: 'assistant',
+    text: '',
+    tools: []
+  }
+  messages.update((ms) => [...ms, assistantMsg])
+
+  let activeTools: Map<string, ToolCallResult> = new Map()
+
+  activeController = streamChat(
+    text,
+    get(currentSession), // continue the active session so the agent keeps context
+    (ev: ChatEvent) => {
+      if (ev.type === 'session') {
+        currentSession.set(ev.data)
+      } else if (ev.type === 'tool_use') {
+        const tr: ToolCallResult = {
+          type: 'tool_use',
+          name: ev.data.name,
+          id: ev.data.id,
+          args: ev.data.args
+        }
+        activeTools.set(ev.data.id, tr)
+        messages.update((ms) => {
+          const last = ms[ms.length - 1]
+          if (last && last.role === 'assistant') {
+            last.tools = [...last.tools, tr]
+          }
+          return [...ms]
+        })
+      } else if (ev.type === 'tool_result') {
+        const existing = activeTools.get(ev.data.id)
+        if (existing) {
+          const updated: ToolCallResult = {
+            ...existing,
+            type: 'tool_result',
+            result: ev.data.result,
+            error: ev.data.error
+          }
+          activeTools.set(ev.data.id, updated)
+          messages.update((ms) => {
+            const last = ms[ms.length - 1]
+            if (last && last.role === 'assistant') {
+              last.tools = last.tools.map((t) =>
+                t.id === ev.data.id ? updated : t
+              )
+            }
+            return [...ms]
+          })
+        }
+      } else if (ev.type === 'text_delta') {
+        messages.update((ms) => {
+          const last = ms[ms.length - 1]
+          if (last && last.role === 'assistant') {
+            last.text += ev.data
+          }
+          return [...ms]
+        })
+      } else if (ev.type === 'text') {
+        // Final authoritative content for the turn; replaces accumulated deltas.
+        messages.update((ms) => {
+          const last = ms[ms.length - 1]
+          if (last && last.role === 'assistant') {
+            last.text = ev.data
+          }
+          return [...ms]
+        })
+      } else if (ev.type === 'done') {
+        currentSession.set(ev.data?.session_id ?? ev.session_id)
+      } else if (ev.type === 'error') {
+        error.set(ev.data)
+      }
+    },
+    (err: string) => {
+      error.set(err)
+    },
+    () => {
+      streaming.set(false)
+      activeController = null
+      loadSessions()
+    }
+  )
+}
+
+export function newChat() {
+  cancelStream()
+  currentSession.set(null)
+  messages.set([])
+  error.set(null)
+}
+
+export function cancelStream() {
+  if (activeController) {
+    activeController.abort()
+    activeController = null
+    streaming.set(false)
+  }
+}

web/src/main.ts

@@ -0,0 +1,6 @@
+import { mount } from 'svelte'
+import App from './App.svelte'
+import './app.css'
+
+const app = mount(App, { target: document.getElementById('app')! })
+export default app

web/src/pages/Chat.svelte

@@ -0,0 +1,263 @@
+<script lang="ts">
+  import { messages, streaming, sendMessage, cancelStream, error } from '$lib/stores/chat'
+  import { fly } from 'svelte/transition'
+
+  let input = ''
+  let messagesEnd: HTMLDivElement
+  $: $messages, $streaming, setTimeout(() => messagesEnd?.scrollIntoView({ behavior: 'smooth' }), 50)
+
+  function handleSubmit(e: Event) {
+    e.preventDefault()
+    const text = input.trim()
+    if (!text || $streaming) return
+    input = ''
+    sendMessage(text)
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    if (e.key === 'Enter' && !e.shiftKey) {
+      e.preventDefault()
+      handleSubmit(e)
+    }
+  }
+</script>
+
+<div class="chat">
+  <div class="messages">
+    {#each $messages as msg (msg.id)}
+      <div class="message {msg.role}">
+        <div class="role">{msg.role === 'user' ? 'You' : 'Nomos'}</div>
+        {#if msg.text}
+          <div class="text">{msg.text}</div>
+        {/if}
+        {#each msg.tools as tool (tool.id)}
+          <div class="tool-chip" class:tool-use={tool.type === 'tool_use'} class:tool-result={tool.type === 'tool_result'}>
+            <div class="tool-header" transition:fly={{ y: 4, duration: 150 }}>
+              <span class="tool-icon">{tool.type === 'tool_use' ? '⚙' : '✓'}</span>
+              <span class="tool-name">{tool.name}</span>
+            </div>
+            {#if tool.type === 'tool_use' && tool.args}
+              <div class="tool-body">
+                <pre>{JSON.stringify(tool.args, null, 2)}</pre>
+              </div>
+            {/if}
+            {#if tool.type === 'tool_result'}
+              <div class="tool-body">
+                {#if tool.error}
+                  <pre class="error">{tool.error}</pre>
+                {:else}
+                  <pre>{JSON.stringify(tool.result, null, 2)}</pre>
+                {/if}
+              </div>
+            {/if}
+          </div>
+        {/each}
+        {#if !msg.text && msg.tools.length === 0 && msg.role === 'assistant'}
+          <div class="thinking">Thinking<span class="dots"></span></div>
+        {/if}
+      </div>
+    {/each}
+    <div bind:this={messagesEnd}></div>
+  </div>
+
+  {#if $error}
+    <div class="error-banner" transition:fly={{ y: 8, duration: 200 }}>
+      {$error}
+    </div>
+  {/if}
+
+  <form class="input-bar" onsubmit={handleSubmit}>
+    <textarea
+      bind:value={input}
+      onkeydown={handleKeydown}
+      placeholder="Ask Nomos anything..."
+      rows={2}
+      disabled={$streaming}
+    ></textarea>
+    {#if $streaming}
+      <button type="button" class="stop" onclick={cancelStream}>■</button>
+    {:else}
+      <button type="submit" disabled={!input.trim()}>→</button>
+    {/if}
+  </form>
+</div>
+
+<style>
+  .chat {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+    max-width: 720px;
+    margin: 0 auto;
+  }
+
+  .messages {
+    flex: 1;
+    overflow-y: auto;
+    padding: 1rem;
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+  }
+
+  .message {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+
+  .message.user {
+    align-items: flex-end;
+  }
+
+  .message.assistant {
+    align-items: flex-start;
+  }
+
+  .role {
+    font-size: 0.75rem;
+    color: var(--text-muted);
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+  }
+
+  .text {
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 0.75rem 1rem;
+    max-width: 100%;
+    line-height: 1.5;
+    white-space: pre-wrap;
+  }
+
+  .thinking {
+    color: var(--text-muted);
+    font-style: italic;
+    padding: 0.5rem;
+  }
+
+  .dots::after {
+    content: '';
+    animation: dots 1.5s steps(4, end) infinite;
+  }
+
+  @keyframes dots {
+    0% { content: ''; }
+    25% { content: '.'; }
+    50% { content: '..'; }
+    75% { content: '...'; }
+  }
+
+  .tool-chip {
+    margin-top: 0.25rem;
+    border-radius: 6px;
+    border: 1px solid var(--border);
+    overflow: hidden;
+    font-size: 0.8125rem;
+    width: 100%;
+  }
+
+  .tool-chip.tool-use {
+    border-left: 3px solid var(--accent-blue);
+  }
+
+  .tool-chip.tool-result {
+    border-left: 3px solid var(--accent-green);
+  }
+
+  .tool-header {
+    display: flex;
+    align-items: center;
+    gap: 0.375rem;
+    padding: 0.375rem 0.5rem;
+    background: var(--bg-surface);
+  }
+
+  .tool-icon {
+    font-size: 0.75rem;
+  }
+
+  .tool-name {
+    font-weight: 600;
+    font-family: var(--font-mono);
+    font-size: 0.8125rem;
+  }
+
+  .tool-body {
+    padding: 0.5rem;
+    background: var(--bg-deeper);
+    max-height: 200px;
+    overflow-y: auto;
+  }
+
+  .tool-body pre {
+    margin: 0;
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    white-space: pre-wrap;
+    word-break: break-all;
+  }
+
+  .tool-body pre.error {
+    color: var(--accent-red);
+  }
+
+  .error-banner {
+    background: var(--accent-red);
+    color: white;
+    padding: 0.5rem 1rem;
+    font-size: 0.8125rem;
+    text-align: center;
+  }
+
+  .input-bar {
+    display: flex;
+    gap: 0.5rem;
+    padding: 1rem;
+    border-top: 1px solid var(--border);
+    background: var(--bg-surface);
+  }
+
+  .input-bar textarea {
+    flex: 1;
+    background: var(--bg-deeper);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    color: var(--text);
+    padding: 0.625rem 0.75rem;
+    font-family: inherit;
+    font-size: 0.875rem;
+    resize: none;
+    outline: none;
+  }
+
+  .input-bar textarea:focus {
+    border-color: var(--accent-blue);
+  }
+
+  .input-bar button {
+    width: 40px;
+    height: 40px;
+    border-radius: 8px;
+    border: none;
+    background: var(--accent-blue);
+    color: white;
+    font-size: 1.25rem;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    align-self: flex-end;
+    transition: opacity 0.15s;
+  }
+
+  .input-bar button:disabled {
+    opacity: 0.3;
+    cursor: default;
+  }
+
+  .input-bar button.stop {
+    background: var(--accent-red);
+  }
+</style>

web/src/pages/Sessions.svelte

@@ -0,0 +1,90 @@
+<script lang="ts">
+  import { sessions, loadSessions, loadSessionMessages, messages, currentSession } from '$lib/stores/chat'
+  import { onMount } from 'svelte'
+
+  onMount(() => {
+    loadSessions()
+  })
+</script>
+
+<div class="sessions-page">
+  <h2>Sessions</h2>
+  <div class="session-list">
+    {#each $sessions as session (session.id)}
+      <button
+        class="session-card"
+        class:active={$currentSession === session.id}
+        onclick={() => loadSessionMessages(session.id)}
+      >
+        <div class="session-title">{session.title || 'Untitled'}</div>
+        <div class="session-meta">
+          {new Date(session.last_active_at).toLocaleString()}
+        </div>
+      </button>
+    {:else}
+      <div class="empty">No sessions yet. Start chatting with Nomos.</div>
+    {/each}
+  </div>
+</div>
+
+<style>
+  .sessions-page {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 2rem 1rem;
+  }
+
+  h2 {
+    font-size: 1.125rem;
+    font-weight: 600;
+    margin-bottom: 1rem;
+    color: var(--text);
+  }
+
+  .session-list {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+  }
+
+  .session-card {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 0.75rem 1rem;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    cursor: pointer;
+    color: var(--text);
+    font-family: inherit;
+    font-size: 0.875rem;
+    text-align: left;
+    transition: border-color 0.15s;
+  }
+
+  .session-card:hover {
+    border-color: var(--accent-blue);
+  }
+
+  .session-card.active {
+    border-color: var(--accent-blue);
+    background: var(--bg-hover);
+  }
+
+  .session-title {
+    font-weight: 500;
+  }
+
+  .session-meta {
+    font-size: 0.75rem;
+    color: var(--text-muted);
+  }
+
+  .empty {
+    color: var(--text-muted);
+    font-size: 0.875rem;
+    padding: 2rem 0;
+    text-align: center;
+  }
+</style>

web/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "paths": {
+      "$lib/*": ["./src/lib/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"]
+}

web/vite.config.ts

@@ -0,0 +1,20 @@
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [svelte()],
+  base: '/ui/',
+  resolve: {
+    alias: { $lib: '/src/lib' }
+  },
+  build: {
+    outDir: 'dist',
+    emptyOutDir: true
+  },
+  server: {
+    proxy: {
+      '/api': 'http://localhost:8090',
+      '/agent': 'http://localhost:8092'
+    }
+  }
+})