Supervisor: observe and operate the factory from inside usine

Read issue #785 for the OpenAPI document and #776 for role bindings before slice 4. Slice 1 adds a ledger entity with GET/POST /api/ledger and notes on existing operator actions; acceptance is importing the operator notebook as entries readable from the UI. The code locations are not given except apps/web and docs/screenshots/<issue>/ folders.

A light PRD. Today an operator outside usine (a person, or an agent session on the owner's laptop) reads the desk, the journal, pull requests, CI and the registry, decides what to approve, merge, retry or split, and keeps the reasons in a notebook. usine has the facts for most of that work and none of the place for it. This issue describes the layer that moves it inside: a ledger, policies, analysis read models, a tool surface for models, and a supervisor agent, each useful on its own and in this order.

Evidence from one day of operation (2026-10-30)

What the external operator did, from the session log:

• Read: the desk, journalctl, 20 pull request diffs, review findings, CI and release runs, the npm registry, GitHub rate limits, the ChatGPT plan window.
• Decided with a rule that could be code: resolve a review that stopped on a merge conflict and schedule the rebase (twice); reset a review cycle budget because the previous round found a P0 that is now fixed (three times); ask for screenshots when a UI pull request had none (twice); notice that the first webhook delivery poll failed every ten seconds and nobody read it for an hour (#770); misread an idle-upgrade drain as a scheduler hang because the pending upgrade and the deferred runs were not in the same view (#783).
• Decided with judgment: five review rounds on #794 were the same class of finding, so split the scope; a backlog triage of 18 issues against main (3 closed, 5 parked with specifications, 7 filed); which recovery to use when a release job failed on GitHub's side.
• Remembered: a ledger file with decisions pending for the owner, reasons for each reset, what to check after each restart, and the queue order. Nothing in usine holds that.
• Escalated to the owner: UI merges, scope decisions, a quota at 80%, the stable release.

Roughly: the reading is all data usine has; half of the deciding is policy; the rest is where a model earns its place; the remembering has no home; the escalations are a role boundary.

Goals

1. An operator, human or model, can read the state of the factory in one place with the questions already answered: what waits on whom, why a run waits, what failed and in which class, how many review rounds a pull request has had, what the credential pools have left.
2. Rule-based operations run as policies inside usine without a model call.
3. A model can act on the factory only through the operator API, as a member with scoped rights, with every action attributed and revertable.
4. Decisions, their reasons and the watch items live in usine, not in a chat or a file.
5. The owner can talk to that state: ask "what needs me", "why is #794 on its fifth review", and say "merge it", from the UI or from an agent on a laptop.

Non-goals

• No autonomous merging. A merge stays a member action with the member's identity.
• No second model-calling path. The supervisor uses the same model access as the agents (see the dependency below).
• No new UI framework. The conversation surface reuses the read models and the operator API.

Concepts

Ledger. A configuration-like entity with revisions: entries of kind decision (pending for a member, with the options and the blocking fact), action (something only a member can do, with the ready command), watch (a fact to re-check after an event, such as "after the next restart, confirm the deliveries poll has no warnings"), and note (a reason attached to an operator action: why a budget was reset, why a run was retried). Entries reference items, runs, pull requests, revisions. The operator UI shows the ledger on the overview; the API reads and writes it; operator actions can carry a note.

Policies. Small rules evaluated on events, no model. First set, each from the evidence above:

• A review that stopped on a merge conflict does not count as a review round; its failure entry is resolved when the rebase starts.
• A cycle budget is extended once when the last round found a P0 or P1 that the next push addressed (the finding's file and symbol appear in the diff).
• A pull request that changes apps/web and has no docs/screenshots/<issue>/ folder is sent back for screenshots before review-passed, with the standard request.
• A pending idle upgrade with runs deferred for more than ten minutes raises a Needs attention entry (part of #783 shipped the display; this is the policy).
• A repeating warning in the journal (the same message more than N times in M minutes) raises a Needs attention entry with the first and last occurrence.
• Five review rounds on one pull request raises a decision entry for a member: continue, split, or stop.

Analysis read models. Projections the desk does not have today: attempts by failure class over a period; review rounds per pull request with the finding grades and the files they point at; cost and tokens per item, per loop and per pool; time from label to merge with the loop hand-offs; recurring findings across pull requests (same file, same class). These are what a person uses to see where agents fail and what to change in a persona or a loop.

Tool surface. An MCP server generated from the operator API's OpenAPI document (#785), one tool per operation, schemas and permission requirements taken from the document, so there is no second definition to drift. It authenticates as a member with a scoped instance token (#776): a supervisor token gets approve, retry, resolve, reset budgets, move lanes, edit loops and agents, read everything; it does not get merge, delete, or member management. The same server serves the owner from Claude Code or Codex on a laptop with the owner's token.

Supervisor agent. A loop like the others, with a persona and a scoped token, triggered by events, not by polling: a run failed, a review posted findings, a pull request reached its Nth round, the backlog changed, an owner asked a question. It reads the read models and the ledger, writes ledger entries (a decision for the owner, a note on an action it took, a watch item), and acts through the tool surface within its scope. It explains before it acts, in the ledger, so the owner can read why.

Conversation. A chat surface in the operator UI and over the API, backed by the supervisor persona with the asking member's token (not the supervisor's), so "merge it" merges as the member. Answers come from the read models and the ledger; the model formats and reasons, it does not hold state.

Slices, in order

1. Ledger entity and API (medium): schema, revisions, GET/POST /api/ledger, notes on existing operator actions (approve, retry, resolve, reset, cancel), overview section listing pending decisions and actions. Acceptance: the operator's current notebook can be imported as ledger entries and read back from the UI.
2. Analysis read models (medium): the five projections above, each with an endpoint and a page or a section. Acceptance: the questions in the evidence section answer from the UI without the journal.
3. Policies, first set (medium): the six rules above as event-driven policies with tests, each raising a Needs attention entry or taking the bounded action, each writing a ledger note. Acceptance: replaying the 2026-10-30 event log triggers each policy where the operator acted by hand.
4. MCP server from the OpenAPI document (small to medium, after #776): generated tools, member token, permission filtering by scope, a smoke test that lists tools and approves a run in a test instance. Acceptance: the owner operates a test instance from Claude Code through the server with a scoped token and sees the actions attributed.
5. Supervisor loop (large): persona, event triggers, ledger writes, bounded actions through the tool surface, escalation entries. Acceptance: on a replay of the day, the supervisor resolves the conflict stops, extends the budgets with the right reasons, requests the missing screenshots, raises the drain and the repeating warning, and proposes the split on the fifth round, with no merge and no scope change of its own.
6. Conversation surface (medium): UI panel and API, member token, the read models and ledger as context. Acceptance: "what needs me" lists the pending ledger entries; "merge #794" performs the merge as the member after the usual checks.

Dependencies and related decisions

• #776 roles, role bindings and token scopes: the supervisor's authority is a role; slice 4 waits for it.
• #785 OpenAPI document: slice 4 generates from it; endpoints added by slices 1 and 2 extend it.
• Model access as one component: today the Pi parent calls providers from inside the orchestrator with Pi's credential store while the children go through the gateway, so the parent cannot use the Claude subscription and a supervisor would inherit the same limit. A research issue should evaluate a single ModelAccess port (owned by the gateway process, every model call goes through it, pools and rate windows enforced there) and, separately, a parent that is a Claude Code or Codex session instead of Pi. The supervisor runs on whatever that port offers.
• The ADRs that record today's choices (0005 Pi parent, 0013 pools, 0021 parent pool, 0027 gateway) get amendments when these land; they record why, they do not gate.

Open questions

• Does the ledger live in the configuration store (revisions, import and export) or in the runtime store (events)? Decisions and actions look like configuration; notes on actions look like events. The first slice should pick one and say why.
• How much of the policies' thresholds is configuration (supervisor: block) versus code? Start with code and constants, move to configuration when a second instance needs different values.
• The supervisor's own cost: it must not become a second quota sink. Event-triggered invocations with a per-day budget, policies without a model call, and the conversation on the member's token.