oikos/plans/2026-07-08-oikos-gaps-and-improvements.md

2026-07-08 — Oikos gaps, broken things, and improvements

Status: Planned

Goal

Full-project review of Oikos from two vantage points — a user interacting through Hermes, and an agent working through the MCP tool surface — with every finding verified against source (file:line), plus a prioritized fix order. This plan is the map; each numbered fix is small enough to land independently.

---

A. Confirmed bugs (verified in source)

A1. Approvals are never created — FK violation, errors swallowed (CRITICAL)

createApproval at internal/mcp/server.go:970 inserts a fresh uuid.NewV7() as approvals.entity_id, but migrations/003_operations.up.sql:41 declares entity_id UUID PRIMARY KEY REFERENCES entities(id). The INSERT always violates the FK, and both pool.Exec errors are discarded.

Net effect: request_execution for systemctl enable/disable or apt_upgrade marks the execution pending_approval (internal/mcp/server.go:311, :366) and tells the agent it's queued, but no approval row exists → the notifier never sends a Matrix alert → the execution is orphaned forever. From the Hermes user's perspective, config mutations silently dead-end while appearing accepted.

Contrast: request_execution (server.go:286) correctly creates a companion entities row for the execution first — approvals just never got the same treatment.

Fix:

• Preferred: migrate approvals to its own id UUID PRIMARY KEY (not FK'd to entities), keeping subject_entity_id as the entity link. Update notifier and DecideApproval queries accordingly.
• Alternative (no migration): create a companion entities row like executions do.
• Either way: check and log every Exec error in createApproval, and verify the UPDATE executions SET approval_id = $2 WHERE entity_id = $1 column semantics (executions is also keyed by entity_id).

A2. Matrix message-flooding vectors (internal/notifier/notifier.go)

• Initial alert is guarded by alert_sent_at (notifier.go:103), but the guard is written after the Matrix send (notifier.go:111). If the UPDATE fails after a successful send, the ticker re-sends every cycle.
• No dedup of approvals by (subject_entity_id, action, payload). Once A1 is fixed, every retried request_execution mints a new approval → one Matrix message each.
• pollReactions (notifier.go:118) issues one Matrix relations GET per pending approval per 30s poll, uncapped — ignored approvals accumulate for their 1h lifetime and multiply API calls. It also re-dispatches decisions for approvals stuck pending (no "already acted" guard if the DecideApproval call errors without flipping status).

Fix: mark-then-send (or transactional outbox) for alert_sent_at; upsert/ dedup open approvals on (subject_entity_id, action, payload); cap + backoff on reaction polling; guard against re-dispatching a decision already in flight.

A3. Hermes "help" is broken + dead code

cmd/hermes/main.go:165 handles "what can you do"/"help" by calling client.callTool("tools/list", nil) — a tools/call for a tool literally named tools/list, which doesn't exist. The correct listTools() helper (main.go:318) is dead code, never called. Fix: wire listTools() in.

A4. resolveHost never returns a per-entity SSH user

internal/mcp/server.go:943 — the named return sshUser is always ""; the per-entity user branch is dead and everything relies on sshExec's global default fallback. Fix: read the SSH user from entity attributes or delete the dead return to make the behavior honest.

A5. queryRows stringifies every column

internal/mcp/server.go:861 renders all values via fmt.Sprintf("%v", ...), so numbers, bools, timestamps, and JSON all reach agents as strings. Fix: type-preserving serialization (pass through pgx-native values into json.Marshal) — improves every read tool at once.

A6. get_state_snapshot description is stale

internal/mcp/server.go:689 still advertises "disk, drift count" — columns removed in commit 3ea43ad. Fix: update the description.

---

B. Security gaps

B1. Enrollment is unauthenticated, with a false comment

internal/httpapi/server.go:97 says "unauthenticated (IP-gated in handler)" but EnrollClient (internal/httpapi/impl.go:1099) performs no IP check at all — the only gate is the target entity being in state planned/provisioning. Caddy's @enroll matcher bypasses Authentik. Anyone reaching oikos.hubris.network who knows (or guesses) a planned slug receives that node's age private key in the HTTP response body.

Fix: enforce a real gate (mesh-CIDR check, one-time enrollment token minted when the entity is created, or both), and stop returning the age private key in the response — have the client fetch it from the secret store.

B2. Fake Infisical credentials returned to enrollees

internal/httpapi/impl.go:1191-1192 returns "inf_client_"+uuid / "inf_secret_"+uuid — random strings wired to nothing. Enrolled clients hold credentials that authenticate against nothing. Fix: implement CreateMachineIdentity in internal/secrets/infisical.go, or return no credentials and document the manual step.

B3. Hermes /query has no auth

hermes/config.yaml:9 sets mesh_only: true but cmd/hermes/main.go never reads or enforces it — it serves any caller on :8092, who can invoke request_execution. Fix: enforce mesh-CIDR (or bearer token) in the handler; fail closed.

B4. SSH host keys not verified

ssh.InsecureIgnoreHostKey() at internal/mcp/server.go:920. Fix: known_hosts pinning (keys are already inventory-managed per node).

B5. list_my_secrets enumerates all node pubkeys

Without caller_pubkey, internal/mcp/server.go:709-720 returns every entity that has an age_pubkey; nothing ties the caller to what it may list. Fix: require caller_pubkey and scope results to the caller's entitlements.

---

C. User perspective (interacting via Hermes)

• routeQuery NLU is hardcoded strings.Contains; extractEntity (cmd/hermes/main.go:173) recognizes only 5 services (authentik, caddy, vaultwarden, gitea, immich) plus mac-mini/hubris. Any other entity → "no entity found", and any unmatched query silently falls back to get_health_summary — wrong answers that look like answers.
• No conversation/session context; no follow-up capability.
• Config mutations appear accepted but silently dead-end (A1).

Recommendation: either make Hermes a real LLM-backed agent loop (Claude API driving the 28 MCP tools) or explicitly scope it as a structured-tool gateway: remove the toy NLU, make the fallback say "I don't understand this query; here are the tools" (via the fixed listTools()), and document that natural language belongs to the calling agent, not the gateway.

---

D. Agent perspective (MCP tooling gaps)

28 tools are registered in internal/mcp/server.go (README says 15, AGENTS.md says 21 — both stale). Missing capabilities:

1. No knowledge write. AGENTS.md tells agents to register knowledge via POST /api/v1/knowledge/{slug}, but there is no MCP tool — MCP-only agents cannot write back what they learn. Add upsert_knowledge.
2. No entity/signal mutation. Create/patch entity, state transitions, and signal ack/resolve/mute all exist in REST (internal/httpapi/impl.go, phase3.go) but not in MCP. Add at least signal ack/resolve/mute and a policy-gated entity attribute patch.
3. No approval visibility. After request_execution returns pending_approval, an agent has no way to check or reference the approval. Add get_approval_status / list_pending_approvals.
4. Execution actions limited to restart | systemctl | pct_exec | apt_upgrade — no deploy/rollback/config-edit path.
5. Architecture/doc mismatch: hermes/SOUL.md claims "no SSH access; all mutations flow through the actuator", but the MCP server runs restart/pct_exec synchronously over SSH from inside the api process (sshExec, server.go:902). Align docs or move execution to the actuator.

---

E. Doc drift / housekeeping

• Tool counts: README 15 / AGENTS.md 21 / actual 28 — regenerate from internal/mcp/server.go (consider a doc-gen make target).
• compose/caddy/Caddyfile.oikos retains literal <mac-mini-mesh-ip> placeholders in all three vhosts.
• .agents/HERMES.md lists "inventory.yaml, inventory.yaml" (duplicate).
• plans/index.md drift: fix-MCP-tools row sat in Active with a broken link after the file moved to done/ (fixed alongside this plan); TRMNL listed active though in done/; Grimmory header says in-progress though in done/; .hermes/plans/ (7 executed plans) missing from disk.
• plans/2026-07-05-oikos-prometheus-lxc.md (~0% done) references deleted oikos/scheduler.py and bin/homelab; LXC 131 collision unresolved.

---

F. Prioritized fix order

1. A1 approval FK + error handling — unblocks the entire approval → Matrix → execution path.
2. A2 notifier flooding guards — this branch's namesake.
3. B1/B2 enrollment security + B3 Hermes auth.
4. D MCP tool additions — approval status first, then knowledge write, then signal ops.
5. C Hermes routing honesty + A3-A6, B4/B5, E drift cleanup.