1.What is the Loop Room?

The Loop Room is the AI operations brain — a standalone service that watches every automated loop, agent, and wiki in the estate and answers four questions the moment you open it: what ran overnight, what it changed, what broke, and what is waiting on you. It monitors the Hermes crons, the six wikis, the trial ledger, the QMD retrieval index, Wingman's task pipeline, and the knowledge writeback flywheel; it measures everything against baselines; it raises flags when something drifts; and it auto-fixes the mechanical class of problems itself, queuing only the judgement class for a human. Health is always computed, never asserted — a loop that reports "ok" over an empty output directory shows red.

2.Architecture overview

Primary truth stays in the estate's own files — registry.yaml, the flag-queue JSONL, the trial ledger markdown, the wikis themselves. The Loop Room's SQLite database (data/looproom.db) holds only derived state: it is safe to delete, and the collectors rebuild it from sources.

The data plane

registry.yaml ─────────── declared truth: loops, emits→consumed_by contracts,
     │                    wikis, baseline metrics
     ▼
Hermes crons ──▶ collectors (read-only) ──▶ SQLite (derived) ──▶ Dashboard SPA
estate files      cron · artefact · flag        looproom.db        Board · Loops ·
portal.db         log · trial · signal ·           │               Trials · Flags ·
qmd status        wingman · qmd · race ·           └──▶ SSE ──▶    Wikis · Map ·
workspaces        writeback · wiki                 /api/events     Decisions

The flag lifecycle

collector detects drift
     │  append_flag() — one live flag per (stream, target)
     ▼
flag queue ── ~/ai-ops-wiki/operations/flag-queue/*.jsonl
     │        append-only, one file per stream, last line wins
     ▼
dispatcher (nightly 03:00, or manual run) — POLICY table routes every open flag
     │
     ├─▶ auto-fix ──▶ mutate file ─▶ git commit "loop-room:" ─▶ post-condition
     │                                                          ├ pass → auto_fixed
     │                                                          └ fail → needs_adam + card
     ├─▶ queue    ──▶ decision card (Decisions view) or held backlog
     ├─▶ suppress ──▶ logged reason, no action
     └─▶ no policy ─▶ "unroutable stream" decision card

Running it

In production the service runs under systemd via loop-room.service (Restart=always, 10-second backoff): install with systemctl enable --now loop-room, follow logs with journalctl -u loop-room -f. The database lives at data/looproom.db (WAL mode) and is safe to delete — collectors rebuild it from sources.

The steward tick loop

The steward is a 60-second background loop. On each tick it:

• runs every collector whose cadence is due (5 minutes to 6 hours — see §5); a crashing collector fails soft and never stops the loop;
• sweeps RED loops into loop_failure decision cards (one per loop per day);
• re-verifies executed auto-fix post-conditions once an hour — a fix that looked good and later regressed is flagged, never silently trusted;
• refreshes the Board digest;
• fires the flag dispatcher once per local day, at the first tick after 03:00 (skipped entirely while the kill switch is on).

3.The Board

The Board is the 7-am view: everything from one GET /api/state call, arranged so the whole estate reads in under 30 seconds.

• Digest — one generated paragraph: runs completed in the last 24 hours, failures, red loops, what the dispatcher fixed / queued / suppressed, the flag half-life trend, overdue trial reviews, and whether anything is waiting on you.
• Overnight strip — a chip per loop that ran in the last 26 hours, ordered by run time, plus anything red regardless of schedule — a broken weekly loop must be visible now, not next Sunday. Click a chip to open the loop's detail.
• Needs You — the first eight open decision cards, actionable inline.
• Health tiles — the summary counters (below).
• Baseline sparklines — every measured metric against its review reference line (§10).

Tiles

Colour semantics

• Green — the loop RAN on schedule with status ok and its declared artefact exists and is fresh. All checks pass.
• Amber — degraded: the loop is paused or disabled, or a tile-level threshold has been crossed.
• Red — broken: the run failed, the scheduler did not fire, or it silent-failed — ran "ok" but the artefact is missing or stale. Red loops appear on the overnight strip, get a red ring on the Map, and raise a triage decision card.
• Unknown — not yet observed (first scheduled run still ahead).

Sparklines plot the last 100 samples of each baseline metric. The blue line is the measured value, the blue dot is the latest sample, and the dashed yellow line is the value recorded at the 2026-07-05 review — the reference everything is measured against. Each card states which direction is good (↑ good / ↓ good).

4.Loops view

Every loop declared in registry.yaml, worst health first. The R/P/C dots are the health model: RAN (did the scheduler fire on time, with status ok?), PRODUCED (does the declared artefact exist, fresh within its max_age_hours?), CONSUMED (did emitted streams land in their consumers?). Green means the check passed, red means it failed, grey means the loop declares no contract for that check. Click a row for the loop's detail page: schedule, run history, and its full consumption contract from the registry.

Green vs red: green requires RAN and PRODUCED to pass. Red is one of three deterministic failure states — failed (the run errored), missing (the scheduled slot plus a 30-minute grace period passed with no run evidence), or silent-failed (ran ok but the artefact is absent or older than its contract allows).

Onboarding a new loop is one stanza in registry.yaml: an id, a schedule, an optional artefact glob with a freshness bound, and optional emits → consumed_by contracts. The Map view draws itself from those contracts.

5.Collectors

Collectors are strictly read-only against the systems they observe (the one carve-out: the writer adapters that append flags to the Loop Room's own queue, and the qmd collector's daily index refresh, which maintains a resource the Loop Room owns). Each runs on its own cadence inside the steward tick; any of them can be run immediately with POST /api/collect/{name}.

6.Flags & dispatch

The flag lifecycle

Flags live in append-only JSONL stream files under ~/ai-ops-wiki/operations/flag-queue/ — one file per stream, primary truth on disk, DB rows only a derived index. A flag's current state is the last line carrying its id; transitions are appended, never edited in place. A flag is raised open and terminates in exactly one of four states:

• open → the flag is live and awaiting the next dispatch;
• auto_fixed — the dispatcher's handler fixed it, committed the change, and the post-condition passed;
• queued — routed to a decision card or held in a backlog for a later capability;
• needs_adam — a handler crashed or a post-condition failed; a human must look;
• suppressed — dismissed with a logged reason (from the policy table or the suppress button in the Flags view).

Deduplication keeps the queue honest: nightly loops re-flag the same pages, but the queue holds one live flag per (stream, target), not one per night. Half-life — the median hours from raised to resolved, per stream — is the headline compounding metric. ∞ means a stream has never resolved a flag; the Flags view shows the all-time and 7-day medians with an improving/worsening trend.

POLICY routing

The dispatcher routes every open flag somewhere — nothing terminates in a report. The policy table:

The nightly 03:00 window

The steward fires the dispatcher once per local day, at the first tick after 03:00 — after the dream cycle (01:00) and freshness check (02:00) have raised the night's flags. A paused steward does not burn the day's slot; dispatch resumes the day you resume the steward. You can also trigger it from the Flags view: Run dispatcher (gated, real mutations) or Dry run, which reports exactly what each flag would get — no file writes, no transitions, no cards.

Guardrails

• Global budget — at most 50 auto-fix mutations per day. Once exhausted, each remaining auto-fix becomes a gated decision card instead: approving it runs the same handler, outside the budget.
• Per-stream budgets — the nightly caps in the policy table above.
• Rate limit — at most one mutation per target file per hour.
• Git audit — every mutation is a commit prefixed loop-room: in the repo that owns the file, revertible from the actions table.
• Post-conditions — checked immediately after each fix and re-checked on a later steward tick; failures move the flag to needs_adam and raise a card, never retry blindly.
• Kill switch — the dispatcher refuses outright while paused (§9).

Everything the dispatcher does lands in the action audit trail at the bottom of the Flags view: kind, target, policy (auto vs gated), state, post-condition result, commit hash, and a one-click rollback (git revert — the revert is itself a commit, nothing is lost; the action is then marked rolled_back).

7.Auto-fixes

The auto class is deliberately narrow: small, reversible, verified mechanical fixes only. Each handler is paired with a post-condition, every change is a git commit, and everything can be rolled back from the audit trail.

Outcomes: fixed (change committed, post-condition passed, flag → auto_fixed); no change (nothing mechanical to do, flag → queued with the reason); failed / post-condition failed (flag → needs_adam plus a decision card — the committed change is left in place for you to review, revert, or finish by hand).

An hourly re-verification pass re-checks each passed post-condition exactly once on a later tick. A regression raises an "auto-fix regressed" card and returns the flag to needs_adam — flagged, not retried.

8.Decision cards

Decision cards are the judgement class — everything the system will not do without you. They appear in the Needs You zone on the Board and in the Decisions view, deduplicated by key so nightly re-sweeps never stack duplicates.

Acting on a card

Approving a card executes its writeback — approval is not an acknowledgement, it is the mutation itself. The result (commit hashes, new trial ids, errors) is stored on the card and shown in the resolved ledger, so the audit trail shows exactly what each approval did. Defer keeps the card for later; Reject / Dismiss closes it without acting. A failed or blocked writeback leaves the card open — failures are visible, never swallowed by an "approved" state.

The needs_adam state

needs_adam is the flag state for issues only a human can close: a crashed handler, a failed post-condition, a regression caught by re-verification. These flags sit in their own red-badged group at the top of the Flags view and always arrive with a matching decision card explaining what happened and what to inspect.

9.Kill switch

The kill switch is the toggle at the bottom of the navigation rail (steward active / MUTATIONS PAUSED), also available as POST /api/steward/pause and /resume. It is the single lever that stops the Loop Room changing anything, estate-wide, immediately.

When to use it: whenever an auto-fix misbehaves, a mutation looks wrong and you want to investigate before more land, or you are doing surgery on the wikis and don't want the dispatcher writing underneath you.

While paused:

• Collectors keep observing — health, flags, baselines, and the dashboard all stay live. You never lose visibility.
• The dispatcher refuses — both the nightly slot and the manual button. The daily dispatch slot is not consumed, so dispatch resumes the day you resume.
• Mutating decision approvals are refused — cards stay open rather than executing writebacks.
• Rollback still works — reverting a bad commit is the recovery path, not a new mutation class, so it is allowed even while paused. The digest notes "the kill switch is ON" until you resume.

10.Baselines & sparklines

Baselines are the review's ledger, made continuous. Each metric was recorded once at the 2026-07-05 strategic review; the collectors now sample them on every pass, and the Board draws each one as a sparkline against its dashed yellow review line. The point of the panel is a single question: is the system compounding, or was the review value a high-water mark?

What triggers concern: a "down is good" metric trending up past its review line, an "up is good" metric flat at zero weeks after the loop that feeds it went green, or a sparkline that simply stops — the collector feeding it has gone quiet, which is itself a loop-health problem.

11.Knowledge compounding

The writeback flywheel is the estate's answer to "do the agents make the knowledge base better, or just consume it?" Wingman's writeback system files task knowledge into the wikis as git commits prefixed wingman:, landing only under three generative directories — insights/, research-logs/ and knowledge-captures/ — and emits Glass Box events (knowledge_saved, knowledge_filed, research_logged) into each workspace's events.jsonl. The Loop Room's hourly writeback collector observes all of it, read-only, and turns it into the compounding baselines and two flag streams.

What is tracked

• Writeback velocity — wingman: commits in the last 24 hours, summed across the tcd, ai-ops, personal and hydrastorm wikis (writeback_velocity_24h), plus the accumulated page total (writeback_total) and generative growth in pages/day since the first writeback (wiki_growth_generative).
• Answer filing rate — of the 50 most recent Wingman workspaces, the share whose event log contains knowledge_filed (answer_file_rate): tasks whose answers were filed into a wiki automatically.
• Research logging — the same scan for research_logged (research_log_rate): tasks that recorded their research trail.
• Capsule → wiki sync — user-triggered "save this" captures (knowledge_saved events, counted over 7 days as knowledge_save_count_7d) land under knowledge-captures/ and are counted in the totals like any other generative page.
• Cross-wiki link count — the wiki collector counts namespaced [[ns:path]] links estate-wide (cross_wiki_backlink_count); knowledge that cites across wiki boundaries is compounding, not siloed.

Stall and failure flags

Two conditions are checked against Wingman's writeback_log table on every collector pass. Both raise high-severity flags that the policy table routes straight to decision cards — auto-retrying a broken writeback path would only mask bugs.

• writeback-stalled — five or more tasks completed in the last 72 hours with zero writeback rows: the system is wired but producing nothing. A missing writeback_log table counts as zero rows — that absence is exactly what the flag exists to surface.
• writeback-failures — commits stuck in committed_not_pushed for over 24 hours, grouped per wiki: the local mirror is diverging from its remote.

The Board's Writeback tile goes red while a stalled-writeback decision is open.

The nightly synthesis brief

The nightly-synthesis loop (04:00 daily) reads what the estate learned that day and writes a brief to ~/ai-ops-wiki/synthesis/, emitting synthesis-actions into the decision queue for anything that warrants follow-up. It is monitored like any other loop: an artefact contract of ≤ 26 hours, and the synthesis_brief_presence baseline (days since the last brief) on the Board.

12.API reference

All endpoints are under /api and return {"ok": true, …} on success or {"ok": false, "error": …} on failure.

13.Wikis view

One card per registered wiki, refreshed by the 6-hourly wiki scan and the hourly QMD pass:

• Pages — markdown page count from the filesystem walk.
• Link coverage — the share of pages containing at least one [[link]]. Link identity is the file stem, lowercased.
• Orphans — pages no other page links to, with the top offenders listed under each card so the worst gaps are actionable, not just counted.
• QMD status — indexed file count and when the collection was last updated, from qmd status; "not indexed" for wikis outside QMD.
• Freshness — when the Loop Room last scanned the wiki.

The same wikis appear on the Map as the right-hand column of the estate's dependency graph — blue nodes fed by the crons and the engine, with hover tooltips showing the scan numbers and a click-through back to this view.