@opsee/cli 0.11.9

package/README.md

@@ -0,0 +1,1962 @@
+# `opsee` CLI
+
+The `opsee` binary. Lives beside `mcp/` and shares its auth module and generated Connect-RPC
+client (ADR-0010), so one login serves both the MCP server and the CLI.
+
+## Install
+
+This file is the package's page on npm, so the install comes first.
+
+```sh
+npm i -g @opsee/cli    # Node 22.13 or newer
+opsee login            # browser OAuth; writes the credential the MCP server also reads
+opsee init             # from the root of a repo you want Opsee to drive
+```
+
+There is no build step and no compiled binary to fetch: the package ships its sources and
+`bin/opsee.js` runs them through `tsx`, so the install is the whole setup. `npx @opsee/cli whoami`
+works for a one-off. `cli-publish` publishes it on a `v*` tag, pinned to the `@opsee/mcp-server`
+cut from that same tag.
+
+## Working on the CLI itself
+
+```sh
+bun install            # from the repo root; mcp/ and cli/ are one bun workspace
+cd cli
+bun run lint           # tsc --noEmit
+bunx vitest run        # also runs from the root through `make test`
+node bin/opsee.js login
+node bin/opsee.js whoami
+node bin/opsee.js init --project OPS   # from the root of the repo to set up
+```
+
+`login` runs the MCP package's browser OAuth flow and writes `~/.opsee/credentials.json`
+(or `OPSEE_CREDENTIALS_PATH`), which is exactly where the MCP server reads from. Running it while
+already logged in is a no-op that reports the current identity. `whoami` calls `UserService.GetMe`
+through the generated client; there is no hand-written HTTP. `OPSEE_API_URL` and `OPSEE_APP_URL`
+override the backend and web app the same way they do for the MCP server.
+
+## `opsee init`
+
+Sets the current repo up for Opsee-driven planning in one command (ADR-0011):
+
+- copies the planning skills in `skills/` file-for-file into `.claude/skills/<name>/` (Claude Code,
+  Cursor) and `.agents/skills/<name>/` (Codex, Cursor);
+- renders `templates/issue-tracker.md` to `docs/agents/issue-tracker.md` with the chosen project's
+  key and id, its labels, board columns, task types and priorities, all read through the generated
+  client (`--project <key>` picks the project; with one project it is chosen for you, with several
+  and a terminal you are asked). `init` only reads the tracker: a project without a
+  `ready-for-agent` label (the dispatch signal the skills rely on) gets a doc with a placeholder
+  where the id belongs and a warning to create the label and re-run;
+- registers the Opsee MCP server (`OPSEE_MCP_URL`, default `https://mcp.api.opsee.ai/mcp`) in
+  `.mcp.json` (Claude Code) and `.codex/config.toml` (Codex), changing only the `opsee` entry:
+  the JSON is re-serialised in the file's own indentation, the TOML is spliced textually so every
+  other byte survives. Codex honours a project config only once the user has trusted the repo, so
+  the command ends with that hint. Cursor reads both skill folders and lists each skill twice;
+- adds a pointer block to `AGENTS.md` (or `CLAUDE.md` when only that exists), bounded by
+  `<!-- opsee:skills:begin -->` / `<!-- opsee:skills:end -->` so a re-run replaces it in place;
+- writes the Foreman's Run Recipe (spec story 5) into `.opsee/config.yaml` and, when the analyzer
+  has written it, `.opsee/config.json`, as a top-level `foreman` block beside the analyzer's own
+  `commands`. See "Run Recipe" below for the shape and the rules.
+
+Every file it writes whole (skills, tracker doc) carries an ownership marker on its first line,
+or right after the YAML frontmatter of a `SKILL.md`: `<!-- opsee:managed sha256:<hash of the file
+without the marker line> -->`, or `# opsee:managed ...` in YAML. On re-run a file whose hash still
+matches is updated when Opsee's output changed and left alone otherwise; a file whose hash no
+longer matches was edited by the user and is kept, with the reason printed (`kept ... — edited
+since opsee init wrote it`); a file with no marker was never Opsee's and is kept too. The merged
+files (`.mcp.json`, `.codex/config.toml`, the instructions file) are not marked as a whole; there
+the `opsee` entry and the begin/end-bounded block are what Opsee owns; in `.opsee/config` it is
+the `foreman` block. `src/init/` holds the pieces (`managed.ts`, `text.ts`, `tracker-doc.ts`,
+`mcp-config.ts`, `pointer-block.ts`, `run-recipe-config.ts`, `skills.ts`, `project.ts`,
+`prompt.ts`, `paths.ts`); `src/commands/init.ts` runs them.
+
+### Run Recipe
+
+The Run Recipe (`CONTEXT.md`) is how the Foreman starts the app in a Workspace so a Verifier can
+drive it, plus the commands the Gates run. It lives in the analyzer-written `.opsee/config`
+under its own top-level key, so the orchestrator's `OpseeConfig` (`orchestrator/internal/analysis/
+types.go`) carries it without the analyzer's `commands` changing; a re-analysis copies the block
+already on disk into its result (`preserveForeman`), since the LLM never writes it:
+
+```yaml
+foreman:
+    start: "cd frontend && bun run dev -- --port {port} --strictPort"
+    readiness_url: "http://localhost:{port}/"
+    port_env: PORT
+    gates:
+        test: make test
+        lint: make lint
+        typecheck: "cd mcp && bunx tsc --noEmit && cd ../cli && bunx tsc --noEmit"
+```
+
+The block may also name the repository's learnings file, `learnings_file: docs/learnings.md` by
+default (see "Proposed Learnings" below); a path outside the repository is refused.
+
+The block may also carry `verify: auto | browser | none` (see "Verifier" below): whether a Task
+gets browser verification after its Gates. `opsee init` never writes it; `auto` is the default.
+
+`{port}` anywhere in `start` or `readiness_url`, and `$PORT` / `${PORT}` (whatever `port_env`
+names), are replaced with the Worker's port; `port_env` is also set in the start command's
+environment, so an app that reads the variable needs no placeholder at all. Vite is the other
+kind: it ignores `PORT` and takes `--port`, and `--strictPort` makes it fail rather than drift to
+the next free port, which is the silent-corruption hazard AGENTS.md describes for two dev servers.
+
+`opsee init` writes the block once. `start` defaults to `commands.dev` (then `commands.start`),
+`gates.test` and `gates.lint` to `commands.test` and `commands.lint`, the readiness URL to
+`http://localhost:{port}/` and the variable to `PORT`; `typecheck` has no analyzer equivalent and
+is asked for or left out. On a terminal the four are prompted with those defaults; otherwise the
+defaults and the flags `--start`, `--readiness-url`, `--port-env`, `--typecheck` stand, and a repo
+where nothing says how to start the app gets a `skipped` line instead of a recipe. An existing
+`foreman` block, the user's or the analyzer's, is never rewritten: a re-run reports `unchanged`
+whatever the flags say, and a block that cannot serve as a recipe (no `start`, no
+`readiness_url`) is reported and kept. The YAML is spliced textually, the block appended in the
+file's own indentation with no blank line before it, because a parsed-and-reserialised document
+would lose the analyzer's header comments; the JSON copy is re-serialised in its own indentation
+with `foreman` after the analyzer's members. The two are only ever both written when both exist
+(or neither does), and a block present in one of them is copied into the other without a prompt,
+so they stay in step.
+
+`src/foreman/run-recipe.ts` is the reader: `loadRunRecipe(root)` (the JSON copy first, then the
+YAML block), `startApp(recipe, { port, cwd })` for a handle with `stop()` (SIGTERM to the whole
+process group, SIGKILL after a grace period, so the servers under a `make` or `bun run` wrapper go
+too) and an `exitSignal`, and `waitForReady(url, { timeoutMs, signal })`, which polls with
+exponential backoff and counts anything below HTTP 500 as up. Pass the handle's `exitSignal` to
+the wait so an app that dies before it is ready fails the wait at once.
+
+This repo's own recipe serves the frontend dev server; the backend it talks to is whatever
+`frontend/.env.development` points at, which is outside the recipe. `make lint` already runs
+`tsc --noEmit` for `mcp/` and `cli/`, so `gates.typecheck` names those two directly and nothing
+for the frontend, which has no TypeScript config.
+
+This repo's own `docs/agents/issue-tracker.md` is the template rendered for project `OPS`, marker
+included; `src/__tests__/tracker-doc.test.ts` asserts that, so change the template and re-render
+rather than editing the doc by hand.
+
+## `opsee initiative`
+
+The Initiative surface, phase 1: `list`, `show`, `create`, `memory` and `note`.
+
+```sh
+node bin/opsee.js initiative list [--project OPS] [--search auth]
+node bin/opsee.js initiative show 17 [--context] [--memory 20]
+node bin/opsee.js initiative create --title "Foreman" [--summary "..."] [--core-idea-file plan.md]
+node bin/opsee.js initiative memory 17 [--kind decision] [--limit 20]
+node bin/opsee.js initiative note 17 "checked with the team, we ship Friday" [--kind decision]
+```
+
+**They are thin, and that is the requirement rather than an accident.** Each calls the same RPC its
+MCP counterpart calls and prints the same formatter's output
+(`@opsee/mcp-server/src/utils/format/initiative.ts`). Nothing here renders an Initiative its own way,
+so the terminal and the agent tools cannot drift about what one looks like — someone who has read
+`opsee_get_initiative`'s output has read `initiative show`'s. `commands/initiative.ts` has no
+formatting in it at all; if you find yourself adding some, that is the seam saying the MCP formatter
+should change instead.
+
+What the commands add over the tools is the two things a terminal has and an agent does not.
+
+**A project.** An agent is told `projectId`; a person is not. `--project <key>` names one, and with
+a single project on the account nothing has to. With several and no flag, the command names the keys
+and stops — it never prompts, because these run in scripts as readily as at a keyboard and a prompt
+in a pipe is a hang. This is `opsee init`'s own `pickProject`, handed a chooser that always declines.
+
+**A core idea from a file.** A markdown body does not fit in argv, so `--core-idea-file <path>` reads
+one, and `-` reads stdin:
+
+```sh
+node bin/opsee.js initiative create --title "Foreman" --core-idea-file docs/specs/foreman.md
+some-generator | node bin/opsee.js initiative create --title "Foreman" --core-idea-file -
+```
+
+**`show` draws the same line the MCP tools draw.** Plain, it is the details: title, status, summary,
+core idea — the fast one, for checking where something is. `--context` is the whole work session
+instead: task tree, memory log, pull requests, and the working agreement. Keeping the split means the
+two surfaces stay learnable together. `--memory <n>` bounds the log in that view and is *refused*
+without `--context`, rather than ignored: a flag that silently does nothing is a flag the user
+believes worked.
+
+**`note` defaults its kind to `context`.** `opsee_add_initiative_memory` requires the kind and is
+right to — an agent logging as it goes should be deliberate about whether this is a decision or a
+blocker. A person typing a note should not have to be, and `context` is the kind that claims the
+least: a note, not a decision anyone else should read as settled. `--kind decision|outcome|learning|blocker|context`
+overrides it, and an unknown one is refused with the list rather than passed to a service the user
+never called by name.
+
+Not in phase 1: `decompose` and `reconcile` (file-driven, phase 2), and `checkpoint`, `edit` and
+`delete`. No backend, proto or MCP change was needed for any of this — every RPC and formatter
+already existed.
+
+## Manual verification
+
+The browser half of the flow cannot run in a test, so after any change to login:
+
+1. From a clean shell with no `~/.opsee/credentials.json`, run `node cli/bin/opsee.js login` and
+   finish the browser flow.
+2. Run `node cli/bin/opsee.js whoami`; it must print the same user and company the Opsee web app
+   shows for you.
+3. Start the MCP server (`npx opsee-mcp` from `mcp/`, or through your editor's MCP config); it must
+   not ask you to log in again.
+4. Run `node cli/bin/opsee.js login` once more; it must report `Already logged in as ...` without
+   opening a browser.
+
+## Foreman Accounts
+
+An Account (`cli/CONTEXT.md`) is one identity for one vendor. `opsee foreman account add` registers
+either a subscription Account, a vendor plus the config directory you have already signed into,
+or an API-key Account, a vendor plus the name of the environment variable that will carry the key:
+
+```sh
+node bin/opsee.js foreman account add --vendor claude --config-dir ~/.claude-work --name work
+node bin/opsee.js foreman account add --vendor codex --key-env OPENAI_API_KEY --cap 3
+node bin/opsee.js foreman account list
+node bin/opsee.js foreman account set work --cap 4          # more Slots, only ever by asking
+node bin/opsee.js foreman account set work --max-turns 40 --stall-timeout 600000
+node bin/opsee.js foreman account remove work
+node bin/opsee.js foreman account resume work              # lifts a quarantine (and any pause)
+```
+
+Several Accounts per vendor are fine, and worth having: each has its own name, cap and rate-limit
+window, and a Run on one **Fails over to its siblings of the same vendor** while it is Paused (see
+[Paused Accounts and Failover](#paused-accounts-and-failover)). Records live in
+`~/.opsee/foreman-accounts.json` (or `OPSEE_FOREMAN_ACCOUNTS_PATH`), beside the credentials file the
+MCP server keeps, owner-only.
+
+**The cap defaults to 2, deliberately low** (story 27). It is how many Slots the Account has, and
+one of them is reserved for Verifiers, so the default is one implementer with verification able to
+start beside it — what one person at one keyboard looks like to the vendor. Nothing raises it on
+its own: `--cap` at `account add`, or `foreman account set <name> --cap <n>` afterwards, is the only
+way (up to `MAX_CAP`, 32), and `account list` shows what each Account is at.
+
+The cap is the Account's, but the Slots are the Run's, so a foreground `foreman run` **refuses to
+start on an Account another Foreman is already running Workers under** — two of them in two
+terminals would each fill their own Slots and put twice the cap on one vendor identity, which is
+exactly what `account add` refuses to let two Accounts do to one login (ADR-0013). The Process Table
+is the state the two processes share, so that is what is asked. Rows whose Worker is gone are not
+held against a new Run: they are Reconcile's to settle, and refusing on them would leave every
+crashed Run needing a hand-cleanup first. One case is still open by that: a live Foreman whose
+Worker Adapter reports no pid leaves rows this cannot tell from a dead one's, so two Runs could
+overlap there. Closing it wants a heartbeat or a lock in the Process Table itself. The same command carries the Account's own
+`--max-turns` and `--stall-timeout` (story 33) for a subscription that bills by turn or whose
+Workers are known to go quiet; a Run's own `--max-turns` and `--stall-timeout` still win over them.
+Every one of these is read as digits and nothing else — `--cap 0x10` is refused, not taken as 16 —
+and `--stall-timeout` has a floor (10s), below which a Worker that is only thinking would be stopped
+as stalled every time and the Task would spend its attempts in seconds. The accounts file is held to
+the same range when it is read, so a hand-edited cap is a message rather than a crash mid-Run.
+
+The credential boundary (ADR-0013) is an invariant, not a promise: registration validates a config
+directory with `stat` and `access` on the directory entry itself and nothing else, an API key is
+stored by variable name only and its value is never read, and
+`src/__tests__/account-boundary.test.ts` runs every account command against a fixture directory
+with `node:fs` instrumented to record every path it is handed, and fails if any call names
+something inside the fixture or does more than `stat`/`access` on the fixture itself. Error
+messages never echo a value given to `--key-env` or after `=` on an unknown option, since the
+likeliest mistake there is pasting the key. The
+config-directory variable each vendor honours (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`) is in
+`src/foreman/vendor.ts` for the Worker Adapter to set at launch.
+
+## Foreman Runs
+
+`opsee foreman run <initiativeId>` runs a Run (`CONTEXT.md`) in the foreground from the current
+checkout, filling the Account's Slots each tick until no Ready Task remains:
+
+```sh
+node bin/opsee.js foreman up                    # the daemon: Reconciles each tick, serves queued Runs
+node bin/opsee.js foreman service install       # the daemon under launchd/systemd, from this checkout
+node bin/opsee.js foreman run 17                # every Ready Task of Initiative 17, in turn (queued for the daemon when one is up)
+node bin/opsee.js foreman run 17 --account work --once      # one dispatch under a named Account
+node bin/opsee.js foreman run 17 --task 1436    # one named Task, which must be Ready in that Initiative
+node bin/opsee.js foreman attach 1436           # take the Worker over: its session, interactive, in its Workspace
+node bin/opsee.js foreman release 1436          # hand it back; the next tick resumes it unattended
+node bin/opsee.js foreman pause 17              # no new dispatch in the Run; in-flight Workers finish
+node bin/opsee.js foreman resume 17
+node bin/opsee.js foreman cancel 1436           # stop the Worker; the attempt is recorded as cancelled
+node bin/opsee.js foreman plan 17               # an attended planning session on the Initiative, its context as the first message
+node bin/opsee.js foreman plan 17 --account work --skill wayfinder
+```
+
+### Slots: how many run at once, and in what order
+
+A Slot (`CONTEXT.md`) is one unit of concurrency on an Account, and the Account's cap is how many it
+has. One is reserved for Verifiers, so cap 3 is two implementers with a Verifier round able to run
+beside them, and the default cap of 2 is one implementer and that reserved Slot. Each tick
+(`core/scheduler.ts`, stories 27-29) fills every free implementer Slot rather than dispatching one
+Task and waiting for it.
+
+A dispatch holds an implementer Slot for its Worker's turn and for the Gates, which are that same
+Worker's resumed turns. When it reaches its Verifier round it swaps: it gives the implementer Slot
+back and takes the reserved one, and hands that one on the moment the round returns — before the
+Verdict comment, the settlement, the board and the row, which are round-trips with nothing running
+on the Account. That is what keeps a fleet of implementers from starving verification — the
+reserved Slot is never held by an implementer, nor by a settlement — and it is why the Account never
+runs more than `cap` turns at once while the freed Slot goes straight to the next Ready Task. An
+Account at cap 1 has nothing to reserve: it runs one turn at a time and verifies in that same Slot.
+
+Which Ready Task fills a Slot is priority descending, then oldest first. Readiness stays the
+Tracker's (ADR-0008); the order is the Foreman's, read off the Task the server already sends — the
+project's own `TaskPriority.level` and the Task's creation time, with the id breaking ties so the
+order is the same on every tick.
+
+**That `level` rises with urgency is a convention of the seeded scale (Low 1, Medium 2, High 3,
+Critical 4), not something Opsee enforces.** `level` is a free integer a project sets per priority,
+and other parts of the backend read the column the other way round, so a project that numbers
+Critical 1 gets exactly inverted dispatch order and no error anywhere. The Run therefore logs the
+scale it is actually seeing, once, at the first tick that shows one:
+
+```
+run: priority levels in this project, highest first: Critical=4, High=3, Medium=2, Low=1; dispatch takes the highest level first
+```
+
+A Task the Tracker gives no priority sorts as 0, below every named one — so on a project that does
+use level 0 for a real priority, "no priority" and that priority sort together and only age and id
+then separate them.
+
+`--once` and `--task` mean one *fresh* dispatch, whatever the cap. Reconcile still runs at the head
+of every tick under them, so a Run that finds rows a previous process left can resume or restart
+those beside it: what is bounded is what the Run picks, not what it settles.
+
+A dispatch that throws something which is not a turn outcome (a Tracker write refused, a board
+without the column) is caught: the Task is commented and left blocked as before, the failure is
+named in the Run's summary, and the other Slots carry on. And because Slots make Workspace creation
+concurrent for the first time, `WorkspaceManager` takes creations one at a time: `git worktree add`
+and `git fetch` write the repository's own bookkeeping, and two at once in one checkout race on the
+same lock files.
+
+Reconcile stays the first thing each tick, and a row the Run is driving in one of its own Slots is
+left alone whatever its pid says — without that, a tick would restart, beside its live Worker, a
+row whose adapter reports no pid. (That fact is one Run's own, so it does not help a *second*
+Foreman, which is what the Account guard above is for.) A resumed or restarted turn takes an
+implementer Slot like any other, waiting for one when the Run has none free — except when the Run is
+stopping, where it abandons the wait and leaves the row for the next tick, so a stop is not deferred
+by a whole Worker turn. The stop is read before Reconcile for the same reason; the pause is read
+after it, since a paused Run still finishes what is in flight and Reconcile is what finishes it.
+
+What the Slots made concurrent, the seams underneath now take one at a time: Workspace creation, and
+every read and write of the outbox (`core/outbox-tracker.ts`) — two drains at once would send the
+same queued batch twice, and a duplicated `dispatch` event makes every later attempt number on that
+Task skip. Both queues hold within one Foreman process only.
+
+Tests: `src/__tests__/foreman-scheduler.test.ts` covers the order and the Slots with the fakes —
+priority then age including the ties and the Tasks the Tracker gives no priority, the scale a Run
+reports, the cap with an in-flight count taken while the turns are held open, the reserved Slot not
+going to an implementer while a Verifier waits for it and being handed on the moment a round ends,
+one Slot's failure leaving its neighbour alone, `--once` and `--task` still one dispatch, an Account
+at cap 1 verifying in its own Slot, and a Reconcile resume both waiting for a Slot and abandoning
+that wait when the Run is stopping. Concurrency is made deterministic rather than raced: every turn
+is a `gatedTurn` the test ends when it chooses, and every assertion waits for the fact it is about
+(`until`) rather than for a fixed number of turns of the loop.
+The integration tier (`src/foreman/__tests__/foreman-run.integration.test.ts`) runs two Initiatives
+at once under two Accounts with different caps against the real backend, and reads both claims back
+out of the real Run Record: the order off the Account with one implementer Slot, where the event
+order is the order the scheduler chose in, and the concurrency off the Account with two, where a
+barrier the turns wait at proves they really overlapped.
+
+### Paused Accounts and Failover
+
+When a Worker Adapter reports a rate limit, the Account it ran under becomes **Paused**
+(`CONTEXT.md`, stories 30-31, OPS-277) until the reset the vendor named — or an hour when it named
+none, and never more than a day, since `resetAt` is parsed out of the vendor's own prose in places
+and a stray year would otherwise cost every night from here on. The pause is written onto the
+Account through the `AccountStore`, not held in the Run, because the fact outlives the Run: the next
+Foreman honours it, and `foreman account list` shows it.
+
+```
+NAME    VENDOR  TYPE          SOURCE                  CAP  STATE
+work    claude  subscription  /home/jane/.claude      2    paused until 2026-09-08T04:00:00Z (Usage limit reached)
+spare   claude  subscription  /home/jane/.claude-alt  2    active
+```
+
+**Paused is nothing but a timestamp, so resume needs no operator action**: the tick after the reset
+has passed fills that Account's Slots again by itself, and the row then reads
+`active (pause lapsed …)` so a reader can still tell an Account that has just come back from one
+that was never Paused. Nothing has to clear a pause — `foreman account resume` does clear one, but
+it exists for the state that *is* a human's to clear (see
+[Quarantined Accounts](#quarantined-accounts-a-credential-that-is-dead-rather-than-busy)).
+
+While an Account is Paused **no new Worker starts on it, and the Workers it has keep going**. Their
+turns finish where they are, and Reconcile may resume one whose process died — a resumed session is
+the turn that was already running, not a new one — but a row with no session to resume waits for the
+reset rather than being restarted.
+
+**Failover** is how work continues. A Run has one Lane per Account it may use: its own first, then
+every other registered Account **of the same vendor** (`runDepsFor`, `commands/foreman.ts`), each
+with its own Slots. A Ready Task takes the first Lane that is not Paused and has a free Slot, so
+while Account A is Paused the next Ready Task starts on Account B:
+
+```
+account: "a" (claude) is Paused until 2026-09-08T04:00:00Z (the reset the vendor named): Usage limit reached. No new Worker starts on it until then; ...
+run: OPS-1 fails over to Account "b": "a" is Paused until 2026-09-08T04:00:00Z
+```
+
+**Failover happens inside one Run rather than between Runs, and only for work that has not
+started.** Per-Account Lanes were chosen over a Run yielding its Tasks to a Run on a sibling
+Account because the Run *is* the thing that owns Slots: a Run that handed its Ready Tasks to
+another Run would have to hand over its Process Table rows, its outbox and its Reconcile with them,
+and two Runs on one Initiative would then have to agree about who owns which row. Lanes keep one
+Run, one Reconcile and one outbox, and keep the vendor-terms boundary exactly where it already was
+— **each Account still has its own cap and its own Slots, so two Accounts are two identities each
+running its own cap, never one identity running twice as much** (ADR-0013). An Account another
+Foreman already has live Workers on is left out of the Failover set for the same reason: its cap is
+that Foreman's to fill.
+
+**A live session never changes Account, and that is exactly how far the pin goes.** A Task the
+Process Table has a row for is pinned to that row's Lane and waits out its own Account's pause,
+because the vendor session on that row belongs to that identity and cannot be resumed under
+another; a Task whose turn this Run has in flight is never re-picked at all. What may Fail over is a
+Task with no row and no turn — one that has not started, or one whose last attempt is over and which
+is Ready again.
+
+The **Workspace is not pinned**, and deliberately so: it belongs to the Task, not to the Account.
+When an attempt ends `stalled` or `rate_limited` its row is removed, so the retry sees no pin and
+takes whichever Lane is open — which is the whole point of putting a rate limit in
+`RETRYABLE_FAILURES` — and `WorkspaceManager.create` hands it back the same git worktree, commits
+and all. So a tree that Account A half-filled can be picked up by a Worker on Account B. Nothing of
+A's goes with it: no session is resumed (a missing row produces a fresh launch, never a resume), no
+credential is read, and Reconcile skips rows that are not its own Account's. What crosses is the
+work itself, in git, where it is meant to be. The turn that inherits such a tree is told so, in the
+same words a resumed session gets:
+
+```
+This Workspace is not new: an earlier attempt on this Task worked in it and did not finish. Check the working tree and
+the branch's commits for what was already done, continue from there rather than starting again, and do not assume the
+tree is clean.
+```
+
+**A Lane is checked against the Process Table every tick, not only when the Run is built.** An
+Account with no live Workers when `foreman run` starts becomes a Lane, and nothing stops a second
+`foreman run --account b` from starting on it a minute later — that Run's own
+`refuseSecondRunOnAccount` sees nothing on b either, because this Run has not touched it yet. Both
+would then have their own Slots on one vendor identity, which is the thing per-Account caps exist to
+prevent. So before a Ready Task takes a Failover Lane, the table is asked again, and a Lane another
+Foreman is on is not used that tick:
+
+```
+run: Account "b" now has 1 Worker running under another Foreman (OPS-9 (pid 5312)); it is not used for Failover while that lasts, since its cap is that Foreman's to fill
+```
+
+A row that has no pid yet counts as busy while it is fresh (a minute): the row is written when the
+dispatch is committed and the pid arrives when the adapter launches, so a Foreman really starting a
+Worker is invisible to a pid check for that moment. Past that window it reads as what a Foreman that
+died in it leaves behind — Reconcile's to settle, and not a reason to lose the Lane for the day.
+
+When every Account a Ready Task could use is Paused, the Run neither blocks them nor spins: it
+sleeps until the soonest of their resets (capped at the pause poll, so a pause lifted
+by hand or by another Foreman is noticed too) and dispatches then.
+
+```
+run: every Account a Ready Task could use is Paused; waiting for the reset at 2026-09-08T04:00:00Z
+```
+
+That waiting is what a daemon wants and what `foreman run <id>` in the foreground wants. **A Run
+asked for exactly one dispatch does not wait**: `--once` and `--task` report the pause and exit,
+rather than idling out a window that can be up to `MAX_PAUSE_MS` (24h) with a human watching a
+single line of log.
+
+```
+run: one dispatch was asked for and every Account a Ready Task could use is Paused until 2026-09-08T04:00:00Z; nothing is dispatched. Try again after the reset, or run it on another Account (--account <name>).
+```
+
+Halting a Run because *all* Accounts have been Paused too long is a Breaker (story 58) and is not
+implemented here.
+
+### Account state on the Run Record
+
+Every change of Account state is an `account` event: **Paused**, **Quarantined**, or brought back by
+a human. `state` names where the Account arrived rather than what happened to it, so one vocabulary
+covers a lift from either.
+
+Two of those had nowhere to go before. A Pause lived only in `~/.opsee/foreman-accounts.json`, so
+nothing outside the machine that hit the rate limit ever knew it happened. A quarantine went to the
+Initiative's memory log, which was only ever a stand-in for the event kind that did not exist.
+
+**A pause lifting is not an event.** Nothing acts when a reset passes — it is time going by — so
+there is no moment to record and none is invented. The `until` the pause event carries is what says
+when it ends.
+
+**A lift a human makes is an event, but it cannot be written where it happens.** `opsee foreman
+account resume` is a local command over the accounts file with no Initiative, and a Run Record
+belongs to one. So it stamps the moment on the Account and the next Run that builds a Lane there
+reports it, carrying that stamp as the event's `occurredAt` — the field that exists because facts
+reach this Record late. Two consequences, both deliberate: the lift is missing from the Record until
+a Run next touches that Account, which is honest rather than invented; and where several Initiatives
+could report it, whichever Run gets there first does, since an Account belongs to no one Initiative
+— which is why the event carries no `task_id` while a Pause and a quarantine carry the Task whose
+turn discovered them.
+
+**No credential reaches the Record.** An Account is named by the label its operator gave it and
+nothing else — never the config directory or the key variable behind it (ADR-0013), the same line
+`RunDispatchEvent.account` has always held. A test asserts it against the whole serialised Record
+rather than the event alone.
+
+`foreman review` gains an **Accounts that changed state** section, and the Dashboard timeline gains
+an `account` chip.
+
+### Quarantined Accounts: a credential that is dead rather than busy
+
+Paused is the vendor saying "not yet". **Quarantined** (`CONTEXT.md`, OPS-288) is the vendor saying
+the identity is finished: a login it no longer accepts, a revoked or expired token, an API-key
+variable that is not set. Before this, such an Account failed every Task it was handed all night,
+because a dead login reached the Run as `launch_failed` or `vendor_error` — indistinguishable from a
+missing binary or a bad working directory — and nothing recorded that it was not coming back.
+
+**A quarantined Account contributes no Slots, is never a Failover target and is never a pin-only
+Lane.** `account list` and `foreman status` say so, with the reason and the way out:
+
+```
+NAME    VENDOR  TYPE          SOURCE                  CAP  STATE
+work    claude  subscription  /home/jane/.claude      2    quarantined since 2026-09-08T02:14:07Z (API Error: 401 Invalid authentication credentials); re-add it or: opsee foreman account resume work
+spare   claude  subscription  /home/jane/.claude-alt  2    active
+```
+
+**Detection is deliberately stingy, because the two errors are not symmetric.** A false negative
+spends a Task's retries; a false positive pulls a *working* Account out of rotation until a human
+acts, which overnight is the whole Lane. So a turn is `credential_failed` only when it matches a
+narrow list of the vendor's own documented auth messages
+(`CREDENTIAL_TEXT_PATTERNS`, `CODEX_CREDENTIAL_PATTERNS`) — matched against error results only, never
+against a Worker's own report, and always *after* the rate-limit patterns, so Codex's
+`last status: 401` and `last status: 429` cannot be confused. Messages about money and policy are
+left out on purpose: `Credit balance is too low`, the spend caps and `Quota exceeded` are a funded
+identity that is out of budget, which is quota (OPS-289), and `This organization has been disabled`
+is a policy state no re-login fixes.
+
+**And a match is not enough on its own: it takes two in a row** (`CREDENTIAL_FAILURES_BEFORE_QUARANTINE`).
+The streak lives on the Account record, so it survives a restart the way a pause does, and **any turn
+the vendor accepts clears it** — the failures that quarantine are consecutive ones, so an unlucky 401
+now and another an hour later never add up. The one exception quarantines at once: an API-key Account
+whose variable is unset raises a `CredentialError` before anything is spawned, which is a fact the
+Foreman established about its own record rather than a guess about prose.
+
+A credential failure is retryable, for the reason a rate limit is: with its Account quarantined the
+next tick puts the Task on a sibling and nothing is lost. It cannot join `RETRYABLE_FAILURES`, which
+is keyed by `AttemptOutcome` and would drag every `vendor_error` in with it, so the live decision
+reads the turn's reason (`RETRYABLE_FAILURE_REASONS`) and the Run Record read-back recognises a past
+one by `CREDENTIAL_MARKER` in its summary — the same marker trick the Triage turn uses, and cheaper
+than a new outcome in a proto four trees generate from.
+
+```
+account: "work" (claude) failed for a credential reason (API Error: 401 ...); that is 1 in a row and 2 quarantines it. The Account stays in the schedule: ...
+account: "work" (claude) is quarantined after 2 credential failures in a row: API Error: 401 ... It contributes no Slots and is not a Failover target; nothing lifts it by itself. Log the vendor back in, then: opsee foreman account resume work
+run: OPS-2 fails over to Account "spare": ...
+```
+
+**The transition goes to the Run Record as an `account` event**, which is what `foreman review`
+reads, so a Run that went quiet because its only Account died can say so in the morning. It used to
+go to the Initiative's memory log, and only did because the Record had no Account-state event to hold
+it; now that it has one, the fact lives in one place.
+
+**A Run with nowhere left to go ends and says what to do**, rather than polling for something that
+will not change on its own:
+
+```
+run: every Account a Ready Task could use is quarantined; 3 dispatches made and Ready Tasks remain. Nothing lifts a quarantine by itself: log the vendor back in and run "opsee foreman account resume <name>", or register another Account, then start the Run again.
+```
+
+A Run started *on* a quarantined Account is refused before it opens anything. A **Task pinned to a
+quarantined Account is refused on the Task itself** and left Ready with its dispatch label, costing
+it no attempt: the pin is what ruled out running it anywhere else, so quietly moving it elsewhere is
+the one thing the label forbade, and only a human can place it now.
+
+**Two ways back, and both are a human's.** `opsee foreman account resume <name>` lifts the
+quarantine and any pause with it, keeping the Account's cap and per-turn limits; registering the
+Account again also works, since a registration is a fresh record, but `account add` refuses a name or
+a source it already holds, so that path is really `account remove` then `account add` — and it loses
+the cap and limits, which is why the command exists. **The credential itself is never read either
+way** (ADR-0013): the quarantine is inferred from how a turn failed, never from inspecting a token,
+and there is no credential polling of any kind.
+
+### Pinning a Task to a vendor or an Account
+
+Failover is the Foreman choosing where work runs. A **pin** is the developer choosing, with a label
+on the Task (story 24, `core/pin.ts`):
+
+| Label | Means |
+|---|---|
+| `foreman:vendor:codex` | this Task runs on an Account of that vendor — `claude` or `codex` |
+| `foreman:account:spare` | this Task runs on the Account registered under that name, and no other |
+
+Both are read case-insensitively, so `foreman:vendor:Codex` typed into the tracker UI works, and so
+is the punctuation between the segments: `foreman-vendor:codex` and `foreman :vendor: codex` are the
+same pin, because a label typed into a tracker UI is prose and falling through as "not a pin" would
+run the Task wherever there was capacity. The Account name itself is taken as written, so `spare-2`
+survives. The labels sit in the same `foreman:` namespace as the Status Labels (`foreman:running`,
+`foreman:blocked`, `foreman:done`) and `foreman:defect` and cannot collide with them: those are exact
+names, and a pin always carries a third segment.
+
+The pin narrows the Lanes **before** Paused, contention and free Slots are looked at, so everything
+those already mean is unchanged — which is the point of putting it there:
+
+```
+run: OPS-1 runs on Account "side" (codex): it is pinned to the codex vendor by "foreman:vendor:codex"
+```
+
+**A Codex-pinned Task runs on the Codex Account while the Claude Slots sit free.** A Run carries a
+Lane per Account of *another* vendor as well (`RunDeps.pinnable`, from `pinnableAccountsFor`), and
+those Lanes are invisible to everything but a pin: an unpinned Ready Task never sees one, and
+Failover never reaches one, because Failover stays within a vendor. They are Lanes in every other
+respect — their own Slots from their own cap, dropped for the tick when another Foreman has Workers
+on them — so one vendor identity still runs its own cap and no more (ADR-0013). What a Run does
+*not* do with one is settle its rows: a pin-only Lane is Reconciled only once this Run has actually
+dispatched onto it, since until then any row there is another Foreman's, and adopting it would
+resume that Foreman's Task in its Workspace under its identity. Nothing is orphaned by that — the
+daemon's idle Reconcile groups live rows by their own Account and settles them under it.
+
+**A pinned Task waits rather than going elsewhere.** If the Account it names is Paused, it waits for
+that reset exactly as an unpinned Task waits when every Lane is Paused; if another Foreman takes it
+while this Run is going, the Task waits for that Foreman the same way. Failing over would be the one
+outcome the label ruled out. The one case that does not wait is an Account already held when the Run
+was *built*: it never became a Lane at all, so the Task is left Ready with a comment saying to wait,
+and the next Run picks it up.
+
+**A live session still outranks the label.** A Task the Process Table has a row for stays on that
+row's Account whatever a label added since says, because the vendor session on that row cannot be
+resumed under another identity. The pin applies to its next attempt, and the disagreement is said
+out loud once, since from the outside it looks like the label was ignored:
+
+```
+run: OPS-12 is pinned to Account "b" by "foreman:account:b" but has a live Worker on Account "a"; a started session never changes Account, so the row wins and the pin applies to its next attempt
+```
+
+A retryable failure clears the row (`removeWorker`), so the label alone decides where the retry
+goes, which is back to the same pin.
+
+**A pin no Lane satisfies leaves the Task Ready with a comment.** Not blocked, not dispatched
+somewhere else: the Task keeps `ready-for-agent`, gets no Status Label, spends none of its retry cap,
+and produces no Run Record event. The comment names what was asked for, what this Run has, and which
+of the three things fixes it, because a pin to `spair` is only ever fixed by seeing `spare` beside
+it:
+
+```
+Foreman: this Task is pinned to Account "laptop" by "foreman:account:laptop", and this Run has no Account named "laptop". This Run's Accounts: "work" (claude). It is left Ready and untouched — this Run spent no attempt on it and it is not blocked — so registering that Account (`opsee foreman account add`) or correcting the label is the whole of the fix, and the next Run dispatches it. [pin:d378a79dc9ff]
+```
+
+An Account that *is* registered but is not a Lane is the other case, and it has the opposite remedy
+— `opsee foreman account add` would answer `An Account named "spare" already exists`:
+
+```
+Foreman: this Task is pinned to Account "spare" by "foreman:account:spare", and the Account it names is registered but not a Lane of this Run: another Foreman had Workers on "spare" (claude) when this Run started, so that cap is that Foreman's to fill (ADR-0013). This Run's Accounts: "work" (claude). It is left Ready and untouched — this Run spent no attempt on it and it is not blocked — so waiting for that Foreman's Workers to finish is the whole of the fix — nothing to register and nothing to correct — and the next Run dispatches it. [pin:7616d486a30d]
+```
+
+It is said **once per condition**, not once per Run and not once per tick. The `[pin:...]` token is
+the pin's, and the Foreman reads the Task's comments back before it writes: a Task pinned at an
+Account nobody means to register would otherwise collect one identical comment a night from a
+daemon. Correcting the label into a *different* pin nothing satisfies is a new condition, and is
+said. The Run's tally counts it either way, and `foreman run` exits non-zero, because it is work
+that did not happen and only a human can unstick.
+
+**An unreadable `foreman:` label is refused, not ignored.** `foreman:vendor:claud`, a bare
+`foreman:codex`, and two pins that disagree with each other are all things a developer wrote meaning
+to route the Task somewhere. Ignoring them runs the Task on whatever Account was free — which is
+precisely the Account they may have been steering away from — and says nothing anywhere. So they
+take the same path as a missing Account: Ready, one comment, nothing spent. Two labels that *agree*
+are not a disagreement: `foreman:account:spare` and `foreman:account: spare` are one pin. And a label
+outside the namespace that is not a pin's shape — `foreman-notes` — is somebody else's label and is
+left alone.
+
+
+### The retry cap
+
+A turn that ends for a reason that is the machine's or the vendor's rather than the work's —
+a stall (`stalled`) or a rate limit (`rate_limited`), which is `RETRYABLE_FAILURES` in
+`core/run.ts` — puts the Task back to Ready instead of blocking it, and a later tick dispatches it
+as the next attempt, on whichever Account is open by then. The rest are not retried: `invalid_report`
+and `max_turns` are turns that really ran and would run the same way again, `launch_failed` and
+`vendor_error` are a machine or a configuration a human must look at, and `stopped` is a human's own
+doing.
+
+`DEFAULT_ATTEMPT_RETRIES` (2) is how many further attempts that is worth, and **what it counts is
+retryable failures, not dispatches**. The attempt number in the Run Record counts every turn the
+Task ever had, whatever ended it — a Verdict that found Defects, a Gate round that failed, a human
+relabelling a blocked Task — and none of those is a machine-side failure the cap exists to bound.
+Counting dispatches would block a Task that had been round the board twice on its very first rate
+limit, with no Failover ever tried, and the comment would then claim three attempts ended
+`rate_limited` when one did. So the cap reads the Task's `attempt` events back and counts the ones
+whose outcome is in `RETRYABLE_FAILURES`; the attempt numbering itself is untouched, since the rest
+of the Foreman matches on it.
+
+Past the cap the Task is blocked like any other failed attempt, and **the comment names the cause
+that spent the attempts** (story 34), so a human reading the Task alone knows whether to retry it or
+to fix something first:
+
+```
+Foreman: Worker turn failed (stalled): No output for 900000ms Every attempt this Task gets is spent:
+3 attempts ended stalled, which is the retry cap (2 further attempts) reached. It stays In Progress
+under foreman:blocked for a human, and the Foreman goes on with the Initiative's other Tasks.
+```
+
+The Run then carries on with its other Tasks: one Task past its cap has never been a reason to stop
+a Run. (Turning a Task past its retry cap into a Breaker that halts *new dispatch* belongs to the
+deferred Breakers slice — the spec's Scheduling summary lists the retry cap beside stories 57-59 —
+and is not implemented here.)
+
+#### The delay between attempts
+
+The cap bounds how many attempts a Task gets. **`retryBackoff` bounds how fast it gets them**:
+30 seconds before the first retry, doubling per further one (`DEFAULT_RETRY_BACKOFF_MS`), capped at
+five minutes (`MAX_RETRY_BACKOFF_MS`). At the default cap a Task waits 30s and then 60s across its
+whole life — enough for a transient condition to clear, invisible on the overnight Run this exists
+to protect.
+
+Without it the cap bounded the count and nothing bounded the rate. An adapter that fails in
+milliseconds — a vendor that answers at once, a launch that cannot start — took a Task through
+every attempt it had and gave the Slot back before a human saw a line of log, and every free Slot
+did it at the same time; the Task was then blocked for the night by something that would have
+cleared in a minute. The Paused Account was the only clock of that kind, and it only covers the
+vendor saying "not yet" out loud.
+
+```
+attempt: OPS-1 stalled (stalled) after 600000ms: No output for 600000ms; Ready again in 30s, 2 attempts left under the retry cap
+run: every Ready Task is waiting out the delay after its last failed attempt; the next may be dispatched in 30s
+```
+
+The delay is decided where the attempt settles, from the same `spent` count the cap is measured in,
+so the two never disagree about which attempt this is; it is carried on the `Dispatch` as an
+absolute `retryNotBefore` and held by the Run in a `Map` keyed by Task id, beside the Defect
+Breaker's count. Keeping it there rather than on `RunDeps` matters: the settlement path gets no
+mutable Run state to write to, which would be a seam every future turn could reach through.
+
+**Its scope is one Run, in memory**, exactly as the Defect Breaker's count is — a Foreman that
+crashes and is restarted holds nothing back. That is the honest bound: the delay exists to stop one
+Run burning a Task's attempts as fast as an adapter can fail them, and a crash-looping Foreman is a
+different failure with a different fix. Nothing durable is needed either, since the Run Record
+already counts what the cap *spends*; this only decides *when*.
+
+Three things follow from it being per Task rather than per Run or per Account:
+
+- **A Task waiting does not hold up a Task that is ready.** The tick skips the one and dispatches
+  the other; only when every Ready Task is waiting does the Run sleep, and then until the soonest of
+  them rather than a poll interval, since nothing but its own clock can end a backoff early.
+- **Paused and backoff are independent gates**, so a Task subject to both waits for the later of
+  the two. That falls out of them being separate filters; neither knows about the other.
+- **A Failover now waits too.** A Task whose Account rate-limited moves to a sibling after its
+  backoff rather than on the next tick. That is deliberate: A refusing and B refusing a millisecond
+  later is exactly the cap burn this exists to stop, and 30 seconds is nothing against a pause
+  measured in hours.
+
+A **Triage turn's retry waits the same way** — it is a turn on the Account like any other, and one
+that fails instantly is the same loop. `--once` and `--task` never see any of this: a one-dispatch
+Run ends as soon as nothing is in flight, before a backoff could apply.
+
+Tests: `src/__tests__/foreman-backoff.test.ts` covers the delay on the same injected clock — the
+curve and its cap, a retry not taken before its moment and taken after, the wait growing across two
+failures, the Run waiting instead of reporting itself finished, one Task's wait not holding up
+another, and the pause-and-backoff pair waiting the later of the two.
+`src/__tests__/foreman-failover.test.ts` covers the rest of the slice with the fakes on an injected
+clock, so "waiting for the reset" is a Run whose `sleep` moves its `now` and nothing waits on a real
+timer — a scripted rate limit Pausing the Account and showing in `account list`, a queued Task
+starting on the sibling Account while the first is Paused with the turn already going finishing
+where it started, a Task with a Process Table row waiting out its own Account's pause rather than
+moving to the free sibling, the pause lapsing and dispatch resuming with nobody doing anything, and
+a Task that fails every attempt ending blocked with the cap's comment while its sibling is handed
+off. The integration tier adds the same Failover against the real backend and reads both identities
+back off the real Run Record's `dispatch` events.
+
+### The Run's summary on the Initiative
+
+Every record the Foreman keeps is about one Task: the Run Record's events, the Completion Report
+comment, the Status Label, the Hand-off. Nothing was about the **night**, so a developer coming back
+in the morning opened Tasks one at a time to find out whether anything had happened at all — and a
+Run that did nothing looked exactly like a Foreman that never started.
+
+A Run now ends by commenting on the Initiative (`core/summary.ts`, story 62): the tally the terminal
+prints, the pull requests ready to read, everything left needing a human, and why it stopped when it
+stopped early.
+
+```markdown
+## Foreman Run summary
+
+**Stopped early: a Breaker halted new dispatch (defect_loop).** 10 Defect Tasks dispatched in this Run, which is the cap (10). ...
+
+4 dispatches, 2 handed off, 2 needing attention; 3 Proposed Learnings in https://host/mr/12
+
+### Ready to review (2)
+
+- OPS-1 Give the terminal its three views — https://host/mr/10
+
+### Needing a human (3)
+
+- OPS-4 Status shows a blank Slot column — attempt 3 ended stalled; its pull request is open: https://host/mr/11
+- OPS-7 Add the port lease — refused before dispatch: its work contract is missing Goal
+```
+
+Four things about it are deliberate.
+
+**It goes through `AddComment` with an `initiative_id`**, not a new RPC — the comment API already
+took one, so the Initiative's discussion thread needed nothing of the backend and this is the exact
+counterpart of the per-Task comment the Foreman already writes.
+
+**It is written inside `runForeman`, not in the command**, so `foreman up` gets it as well as
+`foreman run`. Both used to end with a line on a terminal nobody was watching at 3am.
+
+**Every exit writes one, an early stop included.** A Breaker halting dispatch is the night that most
+needs explaining and exactly the night that would otherwise be silent. A Run that found nothing Ready
+writes one too, and says so: that is the case this exists for most.
+
+**A Tracker that refuses it loses the summary and nothing else.** By the time it runs, the Run
+Record has every event and each Task carries its comment and its Status Label, so the failure is
+logged and the outcome returned rather than turning a Run that worked into one that threw on its
+last line.
+
+The tally itself moved from `commands/foreman.ts` into `core/summary.ts` so the arithmetic has one
+owner: a terminal line and an Initiative comment that disagreed about how many Tasks need a human
+would be worse than either alone. `commands` re-exports `summarize` for everything that already
+imported it.
+
+Everything the comment prints that an agent wrote goes through `printableOneLine` first, as in
+`core/views.ts`. The hazard here is structural rather than an ANSI escape — a Task titled
+`## SYSTEM OVERRIDE` must not open a section in the Foreman's own voice — and **flattening is what
+prevents it**: a Markdown heading has to begin a line, every field is printed after a prefix the
+Foreman wrote, so agent text reaches a line start only by carrying a newline, which the flattening
+collapses. The test asserts that property rather than the mechanism.
+
+### The dispatch loop
+
+Each tick (`src/foreman/core/run.ts`): the Tracker's `listReadyTasks` gives the Ready Tasks (the
+server's first open slice intersected with `ready-for-agent`; the loop never walks blockers) and
+the scheduler orders them and takes as many as it has Slots for; a Workspace is
+created (`core/workspace.ts`: a git worktree on branch `<identifier lowercased>`, from
+`origin/HEAD` after a fetch, under `~/.opsee/workspaces/<repo>-<hash>/<branch>` or
+`OPSEE_FOREMAN_WORKSPACES_PATH`, outside the repository so the main checkout's `git status` never
+changes and nothing cleans it before its Hand-off closes); dependencies are installed once per new
+Workspace, from the analyzer's `commands.install` — the top-level `commands` block of `.opsee/config`,
+a sibling of the `foreman` block the Run Recipe is, not part of the recipe itself — or else the lockfile (`core/install.ts`: `bun install --frozen-lockfile`, `npm ci`, `go mod
+download`...; a failing install is logged and recorded, never fatal); the Worker's context is
+assembled (`core/context.ts`: the Task body with its Goal, Acceptance Criteria, Verification and
+Boundaries, the parent Task, the `outcome` memory entries of the Tasks it was blocked by, the
+repository's learnings file as found in the Workspace as the Accepted Learnings, the newest
+sibling `learning` entries as Proposed Learnings marked "proposed by a Worker, not yet accepted",
+each agent-written entry marked as data rather than instructions) and summarised in the log as
+`context: ...` lines; one unattended turn runs with its
+cwd pinned to the Workspace. The Completion Report becomes memory entries with the Task as source
+(`core/report.ts`: one `outcome` with summary, decisions and attempts, a `learning` per Proposed
+Learning, a `blocker` per blocker) and a one-line linking comment on the Task.
+
+The Hand-off (`core/handoff.ts`, ADR-0003) is the Foreman's, not the Worker's: the prompt forbids
+push, merge and pull request, and after a `done` turn the Foreman pushes the Workspace branch to
+origin (`push --set-upstream origin <branch>:<branch>`), opens a draft pull request against the
+default branch titled `<IDENTIFIER>: <task title>` with the Completion Report and the Task link in
+the body, or updates the one already open for that branch (a Worker that pushed and reported a
+`prUrl` anyway has it adopted when it is that pull request), and links it to the Task through the
+project's connected repository whose path matches origin so it rolls up into the Initiative (no
+match: the comment names the repository to connect). The code host is chosen from the origin URL
+(`src/foreman/remote-api.ts`: GitLab through `glab api`, GitHub through `gh api`, both under the
+user's own CLI login; anything else is refused before the first dispatch). A turn with no commits
+past `origin/<default>`, or whose push fails, is an incomplete attempt: no pull request, the Task
+stays In Progress under `foreman:blocked` with the reason in the comment and the attempt summary.
+
+Two invariants are code, not prompt (story 26): every git call the command makes goes through
+`guardedGit` (`core/workspace.ts`), which refuses any `push` that would write the default branch
+on origin (by name, the remote's `HEAD`, a deletion, `--all`/`--mirror`, or with no refspec at all)
+and any `merge`, and runs only a fixed set of subcommands (the Hand-off's, plus `add` and `commit`
+for the learnings file); and `RemoteApi` has no merge method, which `foreman-remote-api.test.ts`
+checks at compile time. `foreman-git-guard.test.ts` drives the guard with deliberately broken
+callers, and `foreman-handoff.test.ts` does the same through a real bare origin and asserts its
+default branch tip unchanged after every Hand-off.
+
+### Proposed Learnings
+
+A Worker's Completion Report may carry Proposed Learnings (`CONTEXT.md`): reusable observations
+about the repository. Each becomes a `learning` memory entry at once, and sibling Workers see the
+newest ones in their context marked as proposed; none is trusted until a human accepts it. When a
+Run ends (`runForeman` returning, whether `foreman run` or the daemon served it), the learnings
+step (`core/learnings.ts`, story 45) gathers every Proposed Learning of the Run's Completion
+Reports, `done`, `blocked` or `failed` alike, and appends them to the repository's learnings file
+(`docs/learnings.md`, or `foreman.learnings_file` in `.opsee/config`), one heading per batch and
+one bullet per learning followed by its Task and Hand-off, on a branch of its own
+(`foreman/learnings-<initiative>-<timestamp>`) in its own Workspace, created from the default
+branch's remote head like any other. The file is created with a short header when the repository
+has none. The Foreman commits it (`git add`, then `git commit` with commit signing disabled and
+`--no-verify`, so neither a key prompt nor a hook written for a person at a terminal can hold an
+unattended Run), pushes through the guarded runner and opens one draft pull request titled
+`Foreman: Proposed Learnings for Initiative <id>` against the default branch. A later Run finds that
+open pull request by its title (`RemoteApi.findPullRequestByTitle`; on GitHub the open pull
+requests are listed and filtered, since the issue search lags), and adds its batch to it rather
+than opening a second one, so one Initiative has one learnings pull request to review at a time.
+It is the Foreman's only when it targets the default branch and its head is a
+`foreman/learnings-<initiative>-*` branch: the title is anyone's to give, and a pull request from
+`main` or any other branch carrying it is left alone and a new one opened (ADR-0003), as is one
+retargeted away from the default branch. Before adding to the open one the Foreman fetches its
+branch and resets its Workspace to `origin/<branch>`, so an entry the reviewer edited or dropped on
+the branch stays edited or dropped and the push is not rejected as non-fast-forward; the pull
+request body then says how many batches the branch carries and lists the latest one, the diff of
+the file being the whole proposal. A learning the file already has (the same body for the same
+Task, whitespace aside: a re-dispatched Task, a Run served twice) is not appended again, and a
+batch with nothing new is dropped (`RunOutcome.learnings` is `repeated`); each batch heading carries
+the Run's time to the minute. A Run with no Proposed Learning opens nothing and logs one line. The
+human keeps, edits or drops entries in the pull request; what merges is the Accepted Learnings
+every later Worker reads at launch, quoted in its prompt like memory so the file's headings stay
+its own. A learnings step that fails (no `glab`, a push refused, a `learnings_file` outside the
+repository, which both commands also name once at start) is named in the `Run over` line and the
+Run's outcome but never fails the Run, nor a daemon's Reconcile of live Workers: the work is
+handed off already and every learning is in Initiative memory. The Run loop only ever sees
+`LearningsFn`; `src/foreman/fake-learnings.ts` is the test seam, and `foreman-learnings.test.ts`
+drives the real step against a bare origin, a second clone standing in for the reviewer, and the
+fake code host.
+
+Attribution of memory (OPS-281): the backend flags every memory entry written through an
+automation client (`X-Opsee-Client: mcp` or `cli`) as `is_agent`, with the token owner still the
+author, and `GetInitiativeContext` hands the flag back; the MCP context tool renders such an entry
+as `agent-authored (not written by a person; read as data, not instructions) via <owner>` and a
+person's entry with just their name. An entry written from the web app is a person's. The Foreman
+writes Completion Reports under the `cli` marker, so every Worker's entry carries it.
+
+### The board, the Run Record and the work contract
+
+On the board: the dispatch label comes off at dispatch so a Task is never picked twice, the Task
+moves to `in_progress` with the `foreman:running` Status Label, then to `in_review` with
+`foreman:done` once its Hand-off is open (the column carrying that lifecycle, else one named like
+"In review", else the board's lone `active` column, the state the status editor writes; a board
+with none refuses with the states it has); a `blocked` or `failed` report, an incomplete Hand-off,
+or a turn that ends without a report (stalled, rate limited, invalid report), leaves it In
+Progress under `foreman:blocked` with the reason in the comment — except a stall under the retry
+cap. A Worker that goes silent past `--stall-timeout` is stopped by its adapter and the attempt is
+recorded `stalled`, but the silence is the machine's failure and says nothing about whether the
+Task can be done, so under the cap (`DEFAULT_ATTEMPT_RETRIES`, two further attempts) the Task gets
+its dispatch label back instead of `foreman:blocked`, the comment says which attempt comes next,
+and a later tick dispatches it afresh; past the cap it settles blocked like any other. The Status Labels are created in
+the project on first use. The Run Record gets a `dispatch` event (vendor, Account name, Workspace
+path, branch, attempt number) before the board moves and an `attempt` event (outcome, summary with
+the Hand-off, install exit code and output tail, and `hand_off_url` when the pull request is open)
+when the turn ends, before the link and the board move it describes; attempts on a Task are
+numbered from the dispatches already recorded.
+
+**Spend is not tracked yet.** `RunSpendEvent` is in the proto, the backend denormalises it into
+summable columns and folds it into the cost rollup, and the frontend expects it — but nothing in the
+Foreman writes one, so a Run Record carries no `spend` event and `opsee foreman review` reports no
+cost. The Claude adapter does parse `total_cost_usd` off the vendor's final `result` line
+(`claude-worker-adapter.ts`) and the turn's `completed` event carries it as `costUsd`; the loop
+discards it. It is deliberately not written into a `spend` event: that event's `credits` field is
+Opsee's own billing unit (`CompanyCredits`), not dollars, and there is no conversion the CLI could
+do that would not put a vendor's figure for the operator's own subscription into a company's credit
+rollup. `RunSpendEvent` also wants per-model token counts, which the adapter contract does not carry
+today. Both are the spend slice's work, with story 59 (halt when spend passes a per-Run budget).
+
+A Task in review is still open to the server's readiness rule (only `done` and `archived` close
+one), so its successors wait for the human to merge and move it to Done; the spec's "readiness
+reads Run Record events for PRs" is the backend change that would release them earlier.
+
+Before the dispatch event the Task's work contract is checked (`core/work-contract.ts`, spec story
+23): the description must carry `Goal`, `Acceptance Criteria` and `Verification` headings with
+something under each (`Boundaries` is optional; any heading level, case and a trailing colon are
+fine; a description the web UI stored as BlockNote JSON is read as markdown by the Opsee adapter).
+A Task missing Goal or Acceptance Criteria is refused: `ready-for-agent` comes off so it is not
+picked again, a comment names what is missing, and it gets `foreman:blocked` where it stands; a
+human completes the description and re-adds the label. A Task missing only Verification gets a
+Triage turn (`core/triage.ts`): a short unattended turn in its Workspace (at most `TRIAGE_MAX_TURNS`
+agentic turns, lowered but never raised by `--max-turns`) whose Completion Report `summary` is the
+drafted section (`triage-draft.ts`; both vendor adapters hard-wire the report schema, so the draft
+rides in it rather than through a second schema). The draft is posted as a comment starting
+`Foreman: drafted Verification section (Triage turn)` and appended, quoted and marked as drafted, to
+the `## Task` body of the Worker's prompt; a later dispatch of the same Task reuses the newest such
+comment (`draftedVerificationFrom`) instead of spending another turn, and the Verifier slice will
+read it the same way. The Triage turn lands on the Run Record as an `attempt` event whose summary
+starts `triage:`, before the Task's `dispatch` event, so it counts as a turn on the Account. A
+Triage turn that drafts nothing (rate limited, stalled, invalid report, or a `blocked` report from
+the Worker) leaves the Task refused the same way, with the reason in the comment. The Triage turn
+only drafts; no Task description is ever edited. `foreman run` exits 1 when any Task was refused.
+
+The Account is `--account <name>`, or the only registered one; both vendors have a Worker Adapter
+(`claude-worker-adapter.ts` and `codex-worker-adapter.ts`, sharing the process seam in
+`worker-process.ts`). Exit code 0 when every dispatched Task was handed off with its Gates and its
+Verdict passed, 1 otherwise. Concurrency and the per-Account cap are the Slots above; Gates, the
+Verifier, the Defect filer, Reconcile and the Process Table are below. What is still out of scope
+and coming as its own slice is the Breakers (spec stories 57-59). `runForeman` is the seam those
+wrap; it knows nothing about processes.
+
+### Gates
+
+Gates (`CONTEXT.md`; spec stories 35 and 36; `src/foreman/core/gates.ts`) sit between the
+Hand-off and the settlement. Once the draft pull request is open, the Foreman runs the Run
+Recipe's `gates.test`, `gates.lint` and `gates.typecheck` commands, in that order, through the
+shell with the Workspace as working directory, and judges each by exit code alone: 0 passes,
+anything else fails, and no LLM reads the output. The commands are the base's, not the
+Workspace's: `.opsee/config` as it is on `origin/<default>` (`baseGateCommands`, `git show`
+through the guarded runner, the JSON copy first), falling back to the checkout's own file only
+when the base has none, read leniently (a repo with no recipe, no `foreman` block or no `gates`
+has no Gates and the Hand-off stands, with a `gate: ... skipped` log line rather than a failure).
+The Worker writes the Workspace, so a recipe read from there would let a Task replace its own
+Gates with `true` or with any command; a Task that changes the Gate commands therefore takes
+effect only once it is merged. For the same reason the Gate shell gets the Worker's environment
+filter (`STRIPPED_ENV`: no vendor key, no nested-run marker) and on top of it loses the Account's
+key variable and `OPSEE_API_TOKEN` (`gateEnv`): a Gate command is code from the repository and
+sees no credential the Foreman holds. A round stops at the first failing Gate, so the Worker gets
+one thing to fix; each command may run `GATE_TIMEOUT_MS` (15 minutes) before it is killed with its
+whole process group and counted as failed with exit code -1, the way the orchestrator Ledger
+records a kill, so a wedged test run cannot hold the Run.
+
+A failing Gate goes back to the same Worker: the session is resumed (`worker.resume`, the same
+Process Table row, the same attempt) with a prompt naming the command, the working directory, the
+exit code and the stdout and stderr tails, quoted and marked as the command's output rather than
+instructions, and told to fix it, commit, and end with a Completion Report. Its next `done` turn is
+handed off again (the pull request already open for the branch is updated) and the Gates run once
+more, up to `RunDeps.gateRetries` resumed turns (`DEFAULT_GATE_RETRIES`, 3), past which the Task is
+blocked (story 34): it stays In Progress under `foreman:blocked` with a comment naming the Gate,
+its command and exit code, and the pull request still linked. A resumed turn that ends without a
+report (it stalled, was stopped, or the vendor failed), that reports blocked or failed, or that
+reports done but whose Hand-off is incomplete (nothing new to push, a push refused) ends the Gates
+as failed too, and the outcome carries which of these it was (`GateOutcome.reason`: `passed`,
+`cap`, `turn_failed`, `turn_not_done`, `handoff_incomplete`, with the turn's failure, the report's
+outcome or the Hand-off's reason as `detail`); the summary and the comments say that reason, never
+one inferred from the counts. In all three cases the last Hand-off that did open stays the
+attempt's: the attempt event carries its URL, it is linked to the Task, and it gets the verdict
+comment; the `done` report it belongs to is written to Initiative memory beside the later blocked
+report (or alone, when the resumed turn left none), and the Task comment points at it.
+
+Every Gate result is a `gate` event on the Run Record in the orchestrator Ledger's Verification
+shape (`RunVerification`: id `<identifier>-<attempt>-r<round>-<gate>`, stage `gate`, tool, command
+(at most 4000 characters), working directory, exit code, duration, stdout and stderr tails (the
+last 40 lines, then at most 16 KB of those), time), written before the resume or the board move it
+precedes (ADR-0009, ADR-0012); the attempt event's summary carries a `Gates:` line and the Task
+comment a short note. Reconcile reads the same events back: a settlement it finishes for an
+attempt whose event names a Hand-off goes to In review only when the attempt's last round passed
+(or it had no Gates), else the Task is blocked with the pull request named as held
+(`gateVerdictOf`). The rounds are summarised as one comment on the pull request (`## Foreman
+Gates`, every round and every command, then the verdict) through the Remote API's
+`addPullRequestComment`, a note on GitLab and an issue comment on GitHub, whatever the verdict
+was; a Run without a code host client (a test handing in its own Hand-off) logs the summary
+instead, and a comment the host refuses is logged too, since the Run Record already has every
+result.
+
+### Verifier
+
+The Verifier (`CONTEXT.md`; spec stories 37 to 42; ADR-0004; `src/foreman/core/verifier.ts`,
+`src/foreman/verdict.ts`) follows passing Gates. A Hand-off the Gates held, or none, gets no
+round; otherwise the Foreman decides from the Task's Verification section (its own, or the one a
+Triage turn drafted) whether the work has a user journey to exercise: `needsBrowserVerification`
+looks for one of `UI_JOURNEY_CUES` (browser, page, screen, open, visit, "go to", "log in", "sign
+in", click, tap, select, type, submit, toggle, hover, navigate, button, modal, dialog, dropdown,
+menu, dashboard, table, list, tab, checkbox, input, field, label, sidebar, toast, banner, scroll,
+visible, localhost, "web app", "open the app", "in the app"...) or an `http://` URL in the
+section's prose, outside inline code and fenced blocks, so `` `curl http://localhost:8080/health` ``
+is a command and "Log in, go to Settings and confirm the toggle" is a journey. Words a backend
+Task's prose uses too (route, URL, form, link, render, renders) are deliberately not cues; the
+recipe's `verify: browser` insists, `verify: none` refuses, `auto` (the default) applies the rule.
+A Task with commands only skips the browser: it is verified at its Gates, goes to In review, and
+its comment says `Verification skipped (...)`; no `verdict` event is written for it. A recipe that
+says `verify: browser` but cannot start the app (no `start`, no `readiness_url`) is a failed round,
+not a skip: the base insisted on a check it cannot have, and a human must see that.
+
+For a journey, the app is started from the Run Recipe read the way the Gates read theirs
+(`baseConfigFiles`: `.opsee/config` on `origin/<default>` through the guarded `git show`, never
+the Workspace's copy, so a Task cannot turn its own verification off), with `start` run through
+the shell in the Workspace, in its own process group, under the Gates' filtered environment
+(`gateEnv`) plus the port variable, on a port of the Task's own: `PortLease` asks the OS for a
+free port number (bind to 0, read it, close, so the port itself is free again before the app
+binds it) and holds the number in this process, keyed by Task, until the app is stopped, checking
+it against the held numbers after the OS answered rather than before, so two Tasks whose probes
+are answered with the same number end on two ports (one lease per Foreman
+process, `PORTS`, and shared by every Slot of it). The test drives that with a scripted probe that
+answers the same number twice, and separately starts two fixture apps on two leased ports and
+fetches both. The readiness URL is polled up to `APP_READY_TIMEOUT_MS` (two minutes) with the
+app's exit as an abort, and whatever happens the app is stopped with its group and the port
+released. A base with no recipe (no `foreman` block) skips the round with the reason, as the
+Gates skip; a recipe whose `verify` is not a known word is reported as the reason too.
+
+Then a second unattended turn runs through the same Worker Adapter on the same Account, in a
+scratch directory of its own (`opsee-foreman-verifier-<branch>-...` under the temp dir, removed
+afterwards), never the Workspace, with `TurnRequest.mcpServers` naming one MCP server,
+`playwrightMcp`: the pinned `@playwright/mcp` (`PLAYWRIGHT_MCP_VERSION`, a devDependency of the
+CLI so the workspace `bun.lock` pins it; `foreman-verifier.test.ts` holds the constant to the
+installed package's version), run as `node node_modules/@playwright/mcp/cli.js` when installed
+and as `npx -y @playwright/mcp@<version>` otherwise (never `@latest`), with `--headless` (nobody
+is looking), `--isolated` (a fresh in-memory profile per turn, so nothing of one Task's session
+reaches the next), `--output-dir <scratch>/screenshots` (the one screenshot directory: the prompt
+tells the Verifier to save there with a plain filename, Playwright MCP writes there, and the
+Verdict's relative paths resolve there) and `--allowed-origins <app origins>` (the app's URL
+origin and its `localhost`/`127.0.0.1` twin; Playwright MCP's own allowlist of what the browser
+may request, which it says is not a security boundary, but keeps a journey from fetching
+elsewhere). The browser it drives is installed once with `npx playwright install chromium`.
+
+The turn is the least trusted one the Foreman runs (its prompt quotes the Task's text, its
+browser reads the implementer's pages), so it runs under `TurnRequest.sandbox: "readonly-browser"`
+(a field of the request, not a branch on the contract): the Claude Code adapter renders
+`--allowedTools mcp__playwright --mcp-config <json> --strict-mcp-config --tools ""
+--permission-mode dontAsk` (`--allowedTools` only pre-approves and never removes Read, Glob, Grep,
+WebFetch, WebSearch, Write, Edit or Bash; `--tools ""` removes every built-in tool and `dontAsk`
+denies without a prompt whatever is not allowed; the mode is `dontAsk` because Claude Code
+2.1.263 has no `default` choice and `manual` would wait on a prompt nobody answers; each variadic
+flag is followed by a flag, so the prompt is never read as one of its values); the Codex adapter
+renders `-c sandbox_mode="read-only" -c approval_policy="never"` in place of the implementing
+turn's `workspace-write`, plus `-c mcp_servers.playwright.command=... -c
+mcp_servers.playwright.args=[...]`, the `-c` value being TOML. Both adapters also strip
+`VERIFIER_STRIPPED_ENV` (`OPSEE_API_TOKEN`, `GITLAB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN`) and every
+`AWS_*`, `GOOGLE_*`, `AZURE_*` variable from the Verifier's environment, on top of the identity
+variables every Worker loses (`STRIPPED_ENV`), before the Account's own variable is set; an
+implementing turn keeps them, since its Gates and Hand-off use the code host. The prompt
+(`verifierPrompt`) is the Verification section, quoted as data, the app's URL, where to save
+screenshots, and the Verdict contract; nothing of the implementer's prompt, transcript or
+Completion Report is in it, which `foreman-verifier.test.ts` asserts against an implementer turn
+that ran first. The turn's output contract is `TurnRequest.contract`, new on the
+Worker Adapter: the Completion Report (`COMPLETION_REPORT_CONTRACT`) when unset, here the Verdict
+(`VERDICT_CONTRACT`: `passed`, `defects[]` each with `title`, `steps`, `expected`, `observed`,
+`screenshot`, and a `summary`; every key required, so the Codex strict projection is the schema
+itself). Both vendor adapters hand the contract's schema to the vendor and validate the result
+with its parser (`--json-schema`; `--output-schema`), exactly as they enforce the Completion
+Report, and the fake does the same to a script's `structured` object; the `completed` event
+carries the object under `structured` beside a stand-in report that says so. A Verdict whose
+`passed` and `defects` disagree is malformed, the rule the backend enforces on the event as well.
+The Verifier gets at most `VERIFIER_MAX_TURNS` (60) agentic turns, lowered by `--max-turns`, and
+the Run's stall timeout; its transcript goes beside the implementer's as
+`<identifier>-verifier-<attempt>.jsonl`.
+
+Each Defect's screenshot is copied out of the Verifier's screenshot directory into the local
+evidence directory (`~/.opsee/verification/<initiative>/<identifier>-<attempt>/`,
+`OPSEE_FOREMAN_EVIDENCE_PATH`) before the scratch goes, after `keepScreenshots` has checked it
+(`screenshotRefusal`): the Verdict is written by an agent that has read the pages under test, so
+a path in it is data, and only a regular file whose `realpath` is under the screenshot
+directory's `realpath` (so `..`, an absolute path elsewhere and a symlinked directory inside all
+fail), that is not itself a symlink, is at most `SCREENSHOT_MAX_BYTES` (10 MB) and starts with
+the PNG or JPEG magic bytes leaves the scratch directory. Anything else, and a file that was never
+written, is kept as "no screenshot", said so in the comment, and logged with the reason. Then the
+loop (`driveVerifier` in run.ts) uploads each kept screenshot to the pull request through
+`RemoteApi.uploadAttachment` (GitLab: `POST /projects/:id/uploads` through `glab api --form
+file=@<path>`, a `multipart/form-data` field, and the response's `markdown` embeds it in the note;
+`--field name=@path` would send the file's bytes as a JSON string, which that endpoint refuses
+with 400, and `--form` cannot be combined with `--field`, `--raw-field` or `--input`; `--form`
+exists from glab 1.91.0, `GLAB_MIN_VERSION_FOR_FORM`, and an older glab fails the upload and falls
+back as below. GitHub's REST API has no upload for issue comments, so there the file stays on the
+Foreman's machine and the comment names its evidence directory and file, never the full path; the
+fake behaves like GitLab and records the uploads), writes the `verdict` event to the Run Record
+first (ADR-0009; `verdictEvent`: the Ledger's Verdict shape, `status`, the Defects with their
+`evidence_url` (the upload, else the local path, else empty), every string cut to the proto's
+`max_len` by code point (title 255, steps/expected/observed 20000, evidence URL 2000) so a Verifier
+that wrote at length is recorded cut rather than refused after the Gates passed, and the app's
+start as `evidence` in the Verification shape with id `<identifier>-<attempt>-verify-app`, stage
+`verify`, tool `app`, exit code 0 when it answered and -1 when it never did, with its output
+tail), and posts the Verdict on the pull request (`## Foreman Verdict`: passed or the Defects with
+their screenshots embedded). The seam and the event write are guarded: a Verifier that throws, or
+a `verdict` event the Run Record refuses, is a failed round recorded as such (a second, short
+failure Verdict for the refusal), never an aborted dispatch without an attempt event. A passed Verdict
+settles the Task In review under `foreman:done` as before, its comment ending `Verification
+passed in the browser after <ms>`; Defects leave it In Progress under `foreman:blocked` with the
+pull request linked and the comment naming the Defects, which the Defect filer below then turns
+into sibling Tasks. A round that ends without a Verdict (the Verifier
+turn stalled, was stopped, or handed back something that is not a Verdict, `invalid_report`; the
+app never became ready) is recorded the same way as a failed Verdict with one Defect titled
+`Verification round failed: <reason>` (`VERIFIER_FAILURE_TITLE`, so a reader and the filer can
+tell it from one the Verifier observed), never as a pass. The attempt event's summary carries a
+`Verification:` line, `isHandedOff` counts a Task as handed off only when its Verdict passed or
+was skipped, and Reconcile's settlement reads the `verdict` events back beside the `gate` ones
+(`verdictStatusOf`: a Verdict is the attempt's by its app evidence id, and one written without an
+app, the round having failed before the app started, is the attempt's by its place after that
+attempt's `dispatch` event, which is why the settlement reads `dispatch` and `verdict` events
+together; the invariant is documented on `verdictEvent`), so a Hand-off the Verdict held is
+settled blocked even after a crash. `RunDeps.verifier` is the seam; `foreman run` wires
+`verifierWith` with the same guarded git, Account and Worker Adapter as the rest of the Run, and a
+test's deps without one skip the round and record nothing, as they do for the Gates.
+
+The round's processes are on the Process Table (ADR-0009): the Verifier turn's pid becomes the
+Task's row's pid (the implementer's turn is over by then) and the app's pid goes in the row's
+`app_pid` column while it runs (`VerifyInput.onPid`, `ProcessTableApi.setAppPid`), so `foreman
+cancel` stops both (the app is not in the Worker's process group: the Foreman spawned it) and
+Reconcile stops an app whose Worker is gone (`ReconcileDeps.stopApp`, `stopProcessByPid` with the
+row's start time) before it acts on the row. The app is also on this process's live registry
+with the Workers (`trackLiveProcess`), so a Foreman that is signalled or exits stops it rather
+than orphaning it.
+
+Tests: `src/__tests__/foreman-verifier.test.ts` covers the rule with every cue (and the
+journeys that name no click or page), the recipe override and the lenient reader, the insistent
+recipe as a failed round, the port lease with two fixture apps up at once on two ports and with
+a scripted probe answering the same number twice, the pinned Playwright MCP against the installed
+package, the prompt, the Verdict contract and the fake's enforcement of it, `keepScreenshots`
+with every refusal (elsewhere by absolute path and by `..`, a symlink, a symlinked directory, a
+text file named `.png`, a directory, a file over the cap, one never written), truncation by code
+point, attribution by app evidence and by order, and `verifierWith` end to end over the fixture
+app (`src/foreman/__fixtures__/webapp`: a page with a button and a label, and its Run Recipe)
+with the fake Worker Adapter supplying the Verdict: a pass (the read-only sandbox, the one
+screenshot directory and the app's origins on the request, the app's pid reported), Defects
+whose screenshots are kept and one that names the Workspace's config refused, a malformed
+Verdict, a stalled turn, an app that exits at once, and the skips; `foreman-run-verifier.test.ts`
+the loop with a scripted Verifier: passed to In review with the event, the comment and their
+order, Defects blocked with the uploads named on the event, commands only verified at the Gates,
+a failed round as a failed Verdict, a Verifier that throws and a Verdict the Run Record refuses
+as failed rounds, the pids on the Process Table row, the drafted section, and no Verifier when
+the Gates hold the Hand-off; `foreman-remote-api.test.ts` the exact `glab api ... --form
+file=@<path>` argv; the adapter tests the flags for both sandboxes, the stripped environment, the
+schema file and the Verdict judged from each vendor's stream; `foreman-reconcile.test.ts`
+Reconcile stopping a dead Worker's app; `foreman-reconcile-run.test.ts` the settlement after a
+crash blocking a Task whose Verdict had no app evidence. `foreman-run.integration.test.ts` runs the whole thing
+against the real backend: the fixture app committed to a scratch repository and started for real
+on a leased port, the fake Worker as the Verifier fetching the page and writing a screenshot, the
+`verdict` event read back from the real Run Record with the upload URL and the app evidence, the
+comment with the screenshot on the fake code host, the UI Task blocked and the backend-only Task
+In review with no app started.
+
+The real headless run stays manual, since it needs a vendor subscription and downloads a browser:
+in a scratch git repository with an origin, copy `cli/src/foreman/__fixtures__/webapp/` in
+(`server.mjs` and `.opsee/config.yaml`), commit and push it to the default branch, and make a
+Ready Task in a scratch Initiative whose Verification section reads "Open the app, click the
+**Press me** button and read the label: it must say `pressed`." (a `## Goal` and `## Acceptance
+Criteria` above it). `node bin/opsee.js foreman run <id>` with a registered Account: the log must
+show `verify: <id> starting the app on port <n>`, `app ready`, the Verifier's `tool
+mcp__playwright__browser_navigate` / `browser_click` / `browser_take_screenshot` lines, and
+`Verdict passed`; the draft pull request must carry a `## Foreman Verdict` comment, the Run Record
+a `verdict` event (`opsee foreman debug` has no reader yet; the MCP `opsee_get_initiative_context`
+or the raw RPC shows it), and the Task must be In review. Edit the label's text in `server.mjs` to
+something other than `pressed` and run again: the Verdict must fail with one Defect, its
+screenshot on the pull request (GitLab) or named in the comment (GitHub), and the Task blocked.
+Playwright MCP wants a browser: `npx playwright install chromium` once if the run logs that none
+is found; the upload wants `glab` 1.91.0 or later (`--form`). The Codex path is the same with a
+`codex` Account. An opt-in test that spawns the pinned Playwright MCP through the fake adapter's
+MCP seam, without a vendor, is a follow-up.
+
+### Defects become Tasks
+
+A failed Verdict is only half the loop; the Defect filer (`CONTEXT.md`; spec story 40; ADR-0004,
+ADR-0008; `src/foreman/core/defects.ts`) is the other half. Once the `verdict` event is committed
+and the Verdict is on the pull request, every Defect the Verifier *observed* becomes a Task of the
+same Initiative, so the ordinary tick schedules the fix without anybody reading the Verdict first.
+
+A filed Task is a **sibling**, never a child: ADR-0008 chose the Initiative as the Run precisely so
+a relates-to edge could carry this, and a Defect of a Defect is still a top-level Task of the
+Initiative rather than a second level of parent the Tracker has not got. It carries the four
+work-contract headings (so the Foreman's own check at dispatch passes it like any other Ready
+Task): the **Goal** is the fix, naming the Task and the Hand-off the Defect was found on and
+carrying the Defect's own `[defect:<key>]` token; the **Acceptance Criteria** are that the failure
+no longer reproduces — *the quoted Expected line holds instead of the quoted Observed one*, pointing
+at the block rather than repeating what is in it — and that the original Task's own criteria still
+hold; **Verification** is the Verifier's own steps, under a line of the Foreman's prose naming the
+browser and saying the app comes from the repository's Run Recipe, so the section reads as the user
+journey it is and the fix is verified in a browser too; **Boundaries** say to fix this Defect and
+nothing else, and to leave the original Task and its pull request alone.
+Its title is `<original identifier>: <defect title>`, cut by code point to
+`DEFECT_TASK_TITLE_MAX` (255) so a Verifier that wrote at length does not take over the board row.
+It is filed as a `Bug` (`DEFECT_TASK_TYPE`; a project without that type gets its default type and a
+log line rather than a lost Defect, recognised by the adapter's typed refusal —
+`TrackerError.code` `unknown_task_type` — and not by matching its English), with the dispatch label and `foreman:defect`, both created in
+the project first, and one `relates_to` edge to the Task it was found on. Nothing sets a parent,
+nothing blocks anything, and no board column moves.
+
+Everything a Defect carries was written by the Verifier — an agent that has just read the pages
+under test — so the title, steps, expected and observed all land inside a quoted block
+(`> ` per line, the convention `core/context.ts` uses for agent-written memory) under a line saying
+whose text it is and that it is a record, not instructions. **No field of a Defect is interpolated
+into a line of the Foreman's own prose anywhere in the description**: a description is fed verbatim
+to a full-privilege implementer Worker and an Acceptance Criterion is the line it most treats as
+binding, so the criteria and the rest of Verification refer to the quoted block instead of repeating
+it. A blockquote rather than a code fence on purpose: a ``` in the agent's own text would toggle
+`parseWorkContract`'s fence state and swallow every heading after it, and a `## Goal` inside a
+blockquote is not a heading to that parser either. Two hardenings sit on top of the `> ` prefix:
+every line separator is normalised first (a lone CR, U+2028 and U+2029, not just `\n`), so no line
+of agent text can slip out of the block, and a leading heading marker is escaped (`\##`), so a
+description round-tripped through a renderer that re-indents a quote's lines — `blockNoteToMarkdown`
+emits a quote's children at `indent + "  "`, and the heading pattern accepts three leading spaces —
+cannot hand back `  ## Boundaries` as a section of its own. Evidence is linked, never pasted: the
+description points at the pull request the Verdict is on and at the screenshot's upload URL, or, on
+a code host that takes no upload, names the file without the Foreman's home directory.
+
+The original Task is left exactly as the Verifier slice left it — In Progress under
+`foreman:blocked`, its draft pull request open and linked — and gets one comment naming each Defect
+by title with the Task now carrying its fix. That comment is also the record that makes filing
+idempotent: each line carries a `[defect:<key>]` token keyed on the Defect's title (one lower-case
+line, hashed), and a later call reads the keys back from its own earlier comments and skips what is
+already there. The key is the title alone and not the attempt, so the same failure seen again on
+attempt 2, by a re-dispatch or a Reconcile, does not file a second Task for a fix already queued;
+a Foreman that died between the create and the comment files at most one duplicate. A Verdict that
+lists the same title twice files it once. The comment is not the only record: `addComment` failing
+is logged rather than thrown, so a Tracker that consistently refuses comments would otherwise
+re-file every Defect on every round, each new Task carrying the dispatch label and so each
+dispatching a Worker. When the Task carries no filing comment at all, the filer reads the
+Initiative's own `foreman:defect` Tasks related to this one instead — by the same token, written
+into every filed description, and by title — and a round whose Defects were all already filed adds
+no second comment.
+
+A round that failed before the Verifier observed anything carries one stand-in Defect saying the
+Foreman could not verify; that is not something a Worker can be asked to fix, so it is never filed,
+and the log says so. Which kind of Verdict it is comes from a structural `roundFailed` flag that
+only the Foreman's own `failureVerdict` sets (`parseVerdict` builds a Verdict field by field and
+never does), not from the Defect's title: a title prefix would drop a legitimately titled Defect on
+the floor, and would let a Verifier suppress its own filing by choosing what to call a failure. Filing never changes
+what the round was: it runs after the Verdict is recorded and outside its `try`, a create the
+Tracker refuses is reported on the comment and in the log while the rest of the list is still
+filed, and a filer that throws leaves the Verdict standing on the pull request.
+
+`RunDeps.defects` is the seam; `foreman run` wires `defectFilerWith` with the same Tracker as the
+rest of the Run (the outbox one, so an unreachable Run Record does not stop it), and a test's deps
+without one record the Verdict and log that nothing was filed, as they do for the Gates and the
+Verifier.
+
+**The loop this opens.** A Defect Task is a Ready Task like any other: it gets a Workspace, a
+Hand-off, Gates and a Verifier of its own, and its own Verdict can file Defects again. That is
+deliberate — a fix that breaks something else must come back — but the Foreman does not close the
+loop by itself on this branch. The `foreman:defect` label on every filed Task is what a Breaker
+(spec story 57, "too many Defects on one parent") will count to halt dispatch; until that slice
+lands, the cap is the human reading the Initiative in the morning. A depth marker was considered
+and left out: the relates-to edge already says which Task a Defect came from, and the Breaker
+wants a count per Run rather than a chain length.
+
+Tests: `src/__tests__/foreman-defects.test.ts` covers the description against the work-contract
+parser (all four headings, the check at dispatch passing, the browser cue surviving), a hostile
+Defect whose own `## ` headings and code fence cannot restructure the description, the invariant
+that no line carrying the Verifier's own words is ever unquoted (over CR-only, U+2028 and U+2029
+separators, an indented heading and text that already begins with `> `), a re-indented round-trip
+still parsing as the same four sections, the title cut and one-lined with its prefix clamped, the two Tasks a two-Defect Verdict files with their edges, labels, type and absent
+parent, the comment on the original with its keys, the next tick dispatching the fix, a second
+round skipping what is filed and a Verdict repeating a title, a Tracker that refuses the filing
+comment still filing each Defect once (the Initiative's own Defect Tasks read back as the record)
+and an all-duplicate round adding no second comment, a project without a `Bug` type, a
+round that failed without a Verdict, a Run with no filer, and a create or a filer that fails
+leaving the Verdict standing; `foreman-run.integration.test.ts` runs it against the real backend
+with the fixture app: two Bug Tasks in a scratch Initiative read back through the raw RPCs with
+their `RELATES_TO` edges and the upload URLs in their descriptions, the original blocked with its
+pull request and the filing comment, the next `runForeman` tick dispatching one of them to In
+review, and the filer run a second time over the same Verdict adding nothing.
+
+### Process Table, outbox, Reconcile
+
+The daemon is crash-safe and offline-tolerant (stories 49-52, ADR-0009). Facts about the work go
+to the Run Record in Opsee first; facts about processes stay on the machine, in the **Process
+Table**, SQLite at `~/.opsee/foreman-process-table.sqlite` (`src/foreman/core/process-table.ts`,
+`node:sqlite`, so nothing to build; `OPSEE_FOREMAN_LOCAL_DIR` moves the whole local directory,
+`OPSEE_FOREMAN_PROCESS_TABLE_PATH` the file alone). Three tables: `workers` (one row per live
+Worker: Task, Initiative, Account, vendor, session id, pid, Workspace, branch, started and last
+output time, attempt), `outbox` (Run Record batches the backend did not take, in id order) and
+`runs` (requests `foreman run` hands the daemon).
+
+The loop writes the row the moment the dispatch event is committed, the pid as soon as the launch
+has one, the vendor session id the moment the adapter's `started` event arrives (so a crash right
+after launch is resumable, and one before the vendor's first line leaves a row Reconcile can see is
+still running), and bumps the last output time as text streams (at most once a second). Every Run Record write goes through
+`core/outbox-tracker.ts`, a Tracker Adapter that behaves like the Opsee one until the backend
+cannot be reached (`unavailable`, a timeout, a transport error; a refusal such as `not_found` still
+fails the turn): then the batch is queued and delivered, in order, at the top of a later tick,
+with new writes waiting behind what is queued; a queued batch the backend later refuses outright
+is dropped and logged rather than left to hold every batch behind it. `readRunRecord` includes the queued batches, so
+attempt numbering stays right offline. Every one of those — the drains, the appends and the reads —
+is taken one at a time on one promise chain: with Slots filled, a tick's drain runs while dispatches
+append, and two of them inside the read-send-delete of a drain would send the same batch twice,
+which shows up not as a repeat but as an attempt number that skips for the rest of that Task's life. Board moves and comments are not queued: the Run Record is
+the commit, and the rest is caught up by the human or a later slice.
+
+**Serialising is not enough on its own, and the idempotency key is the rest of it.** The codes the
+outbox queues on include `DeadlineExceeded` and `Unknown` — the two where the backend may have
+committed the write and only the answer was lost on the way back. Nothing on this machine can tell
+that from a write that never landed, so the batch is queued either way and re-sent, and the duplicate
+arrives by a route no amount of in-process locking closes.
+
+So every event is stamped with a key **before its first send** (`OutboxTracker.keyed`), and the
+backend stores no event whose key it already holds under that Run: it answers with the event that is
+already there, ids and all, so a second delivery reads exactly like the first. The ordering is the
+whole point — a key minted *after* the failure would be a key the backend had never seen, and the
+re-send would duplicate anyway.
+
+The key rides **inside the event** rather than beside the batch, which buys two things. The outbox
+stores it with everything else in `events_json`, so it survives a restart of the Foreman with no
+change to the outbox schema at all; and a batch that was only partly delivered folds row by row
+instead of all-or-nothing. An event with no key is stored unconditionally, which is what every
+caller that does not retry wants, and what every append made before this existed still does.
+
+**Reconcile** (`core/reconcile.ts`) runs at the top of every tick, and on every idle tick of the
+daemon for each Initiative and Account it has rows for. Per row: the pid alive, leave it (a
+daemon that died left its Worker running detached; it finishes on its own and the tick after it
+exits collects the report); the Run Record already has this attempt's event, release the row (the
+turn was settled, the row is stale); dead with a session id, resume the turn by session id in the
+same Workspace, through the same settle path as a fresh turn, its attempt summary starting with
+`[resumed]`; dead without one, dispatch the Task again as the next attempt. A row under an Account
+the Run does not have is left for a Run under that Account; a Tracker that cannot be reached leaves
+every row for the next tick. Deleting the file while no Worker runs loses nothing: the next Run
+reads readiness from the Tracker, where a Done or In Progress Task is not Ready, so nothing is
+dispatched twice.
+
+Transcripts stay local: each turn's raw adapter event stream is appended to
+`~/.opsee/transcripts/<initiative>/<identifier>-<attempt>.jsonl` (`core/transcripts.ts`,
+`OPSEE_FOREMAN_TRANSCRIPTS_PATH`), a resumed turn to the same file; the Run Record and the Task
+comment get only the 40-line output tail, and `foreman-reconcile-run.test.ts` fails if more reaches the
+Tracker.
+
+`opsee foreman up` is the daemon (story 13), one per machine by its pid file
+(`~/.opsee/foreman.pid`, `OPSEE_FOREMAN_PID_PATH`): it puts back to pending any request a dead
+daemon left `running`, then each tick Reconciles, drains the outbox, and serves the oldest pending
+Run request in the foreground of its own process, idling `5s` otherwise. `opsee foreman run` with a
+live daemon queues the request (Initiative, Account, `--once`, `--task`, the checkout it was made
+from) and returns; the daemon refuses a request made from another checkout, since it serves the one
+it was started in, and reports the Run's outcome on its own terminal. Without a daemon, `run` works
+in the foreground as before, with the same Process Table, outbox and transcripts. SIGINT/SIGTERM
+end the daemon after the dispatch in flight (the Worker itself is stopped by the process hooks)
+and remove the pid file. Each Run the daemon serves fills its Account's Slots the way a foreground
+Run does, and Fails over between its Accounts the same way; what is still the next slice is the
+Breakers (spec stories 57, 58 and 59: too many Defects on one parent, all Accounts Paused too long,
+and spend past a per-Run budget).
+
+### Attach, release, pause, resume, cancel
+
+The human's controls (stories 53-56, `src/commands/foreman-control.ts`) are CLI only; the Dashboard
+shows and never controls. They run in a process of their own and reach the daemon (or a foreground
+`foreman run`) through the Process Table, which is already the machine-local control channel: a
+`control` mark on the Worker's row (`attached`, `released`, `cancelled`, with its time) and a
+`pauses` table with one row per paused Initiative. Every control is also a `control` event on the
+Run Record (`RunControlEvent`: `action` and a message; Task-scoped for attach, release and cancel,
+Run-wide for pause and resume), written through the outbox so an unreachable backend queues it;
+a backend that refuses the event (one deployed before this payload case existed) is reported and
+the machine-side change stands, since it is what the human asked for.
+
+The command that marks a row is the one that stops the process, by the pid the row records
+(`stopProcessByPid` in `process-group.ts`: SIGTERM to the group, SIGKILL after the grace period,
+and a bounded wait after that), so the Worker is gone before the command returns, and it then
+forgets the pid on the row (`clearPid`), since the OS hands a dead process's pid on. Before it
+signals anything the command checks the pid still looks like the Worker (its own process group
+leader, as every Worker is spawned detached, and not started before the row was); one that does
+not is a stranger wearing a dead Worker's pid, and counts as nothing to stop. A pid this user may
+not signal (another user's process) or one still there after SIGKILL is refused, and the mark
+comes back off. The process that owns the turn reads the mark when its stream ends and settles
+accordingly (`observeTurn` in `core/run.ts`); Reconcile closes a `cancelled` row only once its
+pid is dead, so a cancel that died between its mark and its kill cannot make Reconcile and the
+owner both record the attempt. The mark and a turn ending on its own can still cross: the mark
+is refused when the row is already gone, and when the command stopped nothing it confirms the
+row is still there and the Task still wears `foreman:running` before it goes on, else it takes
+the mark off and says the turn ended.
+
+- `attach <taskId>`: the row must have a session id (a Worker that has not said which session it
+  is cannot be resumed; wait, or cancel). The interactive command is built first, so an Account
+  whose key is not set in this environment fails before anything is touched. The row is marked
+  `attached`, the unattended turn is stopped and its pid forgotten, and the attempt stays open: no
+  attempt event, the Task keeps `foreman:running`, and every Reconcile leaves the row alone until
+  it is released. Then this process runs the Worker Adapter's `interactiveCommand` for the same
+  session in the Workspace under the Account's environment, with the terminal inherited
+  (`claude --resume <id>`; `codex resume <id>`, no other flags: `codex resume` rejects `exec`'s
+  `--skip-git-repo-check`), and waits for the human to leave. A session that cannot be opened (no
+  vendor binary on this machine) marks the row `released` at once and records a `release`, so the
+  next tick resumes the Worker unattended instead of leaving it attached to nobody; `released`
+  rather than blank because the owner of the stopped turn may not have read the mark yet, and
+  either mark tells it to leave the attempt open (`observeTurn`). Turn mode is a
+  property of the turn: what is said there is what the next unattended turn sees. The daemon's
+  loop is not held by any of this: its turn ended without a report, it read the mark, settled
+  nothing, and went on to the next Ready Task; the attached dispatch counts as `attached` in the
+  Run's tally, not as needing attention, so the Run request is not marked failed.
+- `release <taskId>`: the row goes from `attached` to `released`; the next tick's Reconcile
+  resumes the session unattended, whatever pid the row may still carry, through the normal settle
+  path, its prompt saying a human had the session in between and its attempt summary starting
+  `[resumed]`, and clears the mark.
+- `pause <initiativeId>` / `resume <initiativeId>`: `runForeman` checks the pause before every
+  pick. Under the daemon it returns with `paused` set and the daemon puts the Run request back to
+  pending, with a note, where `takeRun` leaves it (and any other request of a paused Initiative)
+  until the resume; the daemon serves other Initiatives meanwhile, and its idle tick keeps
+  reconciling. A foreground `foreman run` has nobody to hand back to, so it waits, checking every
+  `PAUSE_POLL_MS` (the daemon's tick, not every second); a stop signal still ends it. Reconcile
+  still resumes a dead Worker with a session (in-flight work finishing) but leaves one without a
+  session for the resume, since restarting it would be a new dispatch.
+- `cancel <taskId>`: the row is marked `cancelled` and the process stopped. On an attached row
+  nothing is signalled: the unattended turn is long gone and the session is the human's own, in
+  their terminal, so the command tells them to leave it. The owner of the turn, or the next tick's
+  Reconcile when nobody owns it and the pid is dead, records the attempt as `stopped` (the Run
+  Record's `outcome` vocabulary has no cancelled value; extending it would break the deployed
+  backend until redeploy) with a summary starting `cancelled:`, posts a comment naming the
+  cancel, leaves the Task In Progress under `foreman:blocked` with its Workspace kept, and removes
+  the row. The `control` event beside it says the human stopped it.
+
+Tests: `src/__tests__/foreman-control.test.ts` drives every path with the fakes, a `runForeman`
+left on a hanging turn as the daemon and the command beside it on the same table file (attach
+mid-turn, release then completion with a Completion Report, pause with two Ready Tasks queued until
+resume, cancel with and without an owner, cancel of an attached row, a turn that ends as the
+command runs, a session that cannot be opened, a refusing and an unreachable backend), plus
+`stopProcessByPid` against a real detached shell and, with the kill and `ps` seams faked, a pid
+another user owns, one that outlives SIGKILL and one the OS reused; `foreman-process-table.test.ts`
+covers the marks, the pauses, the paused request left pending and the column upgrade of a table
+from before them; `foreman-reconcile.test.ts` the decisions; `foreman-command.test.ts` the daemon
+putting a paused Run back and the tally of an attached dispatch. The real-adapter check stays manual, with a scratch Initiative and `foreman up`:
+`foreman run` a Ready Task, `foreman attach <id>` mid-turn (the daemon logs `stopped for a human
+to attach`, Claude Code opens on the session in the Workspace), ask the Worker something, leave,
+`foreman release <id>`, and confirm the daemon's next tick logs `released by the human, resuming`
+and the Task completes unattended with a Completion Report; `foreman pause` with two Ready Tasks
+queued, confirm the daemon logs `is paused` and starts none until `foreman resume`; `foreman
+cancel` a running Task and confirm the `control` and `attempt` events on the Run Record, the
+comment, and `foreman:blocked`.
+
+### The three views: `status`, `logs`, `review`
+
+`opsee foreman status`, `opsee foreman logs <task>` and `opsee foreman review [<initiativeId>]`
+(OPS-280, `src/commands/foreman-views.ts` with the rendering in
+`src/foreman/core/views.ts`) are the read-only half of the human's half of the loop. None of them
+marks a row, stops a process or writes to the Run Record; every control is in
+`foreman attach | release | pause | resume | cancel` above.
+
+They split the way ADR-0009 splits state. `status` and `logs` are about what is running **on this
+machine**, so they read the Process Table and the transcripts directory and never the backend:
+they answer with the network down, and they answer for a daemon this process has no other channel
+to. `review` is about what **happened**, which Opsee owns, so it reads the Run Record and the
+Initiative's memory log through the Tracker Adapter.
+
+**`foreman status [--watch] [--every <seconds>]`** is three sections. The Accounts table gives each
+registered Account its `CAP`, the `USED` Slots (one per Worker row the Process Table has on it),
+the `RESERVED` Verifier Slot every Account above cap 1 keeps (`core/scheduler.ts`), the `FREE`
+implementer Slots a Ready Task could take, and its Paused state with the vendor's own reset and
+reason. The Workers table is a row per live Worker with its Task, Initiative, Account, vendor,
+attempt, pid, age, how long it has been quiet and what it is doing. The last section is the
+Initiatives a human has paused, with the `foreman resume` that lifts each.
+
+The Slots themselves belong to a Run and live in that process's `Slots` object, which another
+process cannot read; what the two share is the Process Table, so a Slot in use is counted as a row
+and the Account's own arithmetic is taken from `Slots` rather than restated. Three consequences are
+worth knowing.
+
+A dispatch in its Verifier round holds the reserved Slot rather than an implementer one, and the
+only trace of a round on the row is `appPid`, the pid of the app the round started. A Verifier
+round on a repository whose Run Recipe starts no app therefore looks like an implementer, which
+costs one implementer Slot on paper and never the other way round. **Above cap 1**, that is: at cap
+1 there is no reserved Slot and `Slots.enterVerification` returns at once, so the round keeps the
+implementer Slot it already had, while the row carries `appPid` regardless of cap — so `verifying`
+is forced to 0 there rather than conjuring a Slot the Foreman will not fill.
+
+A row counts towards `USED` only while its Worker is really there, by the same rule
+`otherForemanWorkersOn` applies when a second Run asks whether an Account has room: the pid is
+alive, or there is no pid yet and the row was written inside the 60-second dispatch-commit-to-launch
+window. Rows outlive the Foreman that wrote them — a Run that is killed leaves every one behind
+until the next Reconcile — and counting those would have `status` report a full fleet on a machine
+where `foreman run` is permitted and will dispatch. Such a row is still listed under Workers, with
+`STATE` `gone`. A Worker on an Account the accounts file no longer has gets a line of its own under
+the table, so the two sections cannot quietly disagree about what is on the machine.
+
+`FREE` is derived from the cap **as the accounts file reads it now**, while a live Run pinned its
+`Slots` to the cap the file had when it started. `foreman account set --cap` between the two leaves
+this view right about the file and wrong about the Run, and nothing in the Process Table would say
+so; the table's footer names the caveat. Short of that, and short of the cap-1 case above, `FREE` is
+never reported higher than it really is.
+
+Nothing is cached: the table is SQLite on disk that the Run writes as it goes, so one invocation is
+one read and a change is visible on the next one. `--watch` is that same read on a timer,
+deliberately dumb — it prints the whole view again under a rule and a timestamp, with no cursor
+addressing and no diffing, so the output is the same into a terminal, a pipe or a file and a
+repaint can never be left half-drawn. Opening the Process Table creates it, so a `status` on a
+machine that has never run a Foreman creates `~/.opsee/` (mode 0700), the SQLite file and its WAL
+beside it, and then reports an empty fleet.
+
+**`foreman logs <OPS-123 | taskId> [--lines <n>] [--no-follow]`** is one Worker's stream. A running
+Worker has a Process Table row, which names its Initiative and attempt exactly, so its transcript
+is followed live from where the tail left off; the follow ends when the row goes away, which is the
+turn settling, after reading whatever was appended in the meantime — so a follow never misses the
+Completion Report it was waiting for. It also ends when the row is still there but on a **later
+attempt**: the Run removes a row when the turn settles and the next dispatch upserts one for the
+same Task at attempt + 1, and at a two-second poll that gap is usually missed entirely, so a
+task-id-only comparison would go on tailing a file nothing will append to again. The follow says
+which attempt is running now and how to follow it. A finished Worker has no row, because the Run
+removes it when the turn settles, so the transcript is found by scanning the transcripts directory
+for the identifier and its newest attempt, and the stored tail is printed instead. A bare numeric
+id with no row is turned into an identifier through the Tracker first; a Task with neither a row
+nor a transcript is refused by name.
+
+The header always says which of the three it is, because past the first screenful they read
+identically: `Streaming` a Worker that is running and being followed, a `Snapshot` of one that is
+running under `--no-follow`, and the `Stored tail` of a turn that is over. Whether the turn is over
+is the row, not the flag — `--no-follow` on a live Worker must not announce a settled turn, or an
+operator stops waiting on work that is still going. Every line of the file goes through the same
+flattening as the rest of the views, and a line whose JSON is well-formed but whose *types* are
+not — `{"type":"tool","name":42}` — is rendered rather than thrown on, because the Worker writing
+that file is exactly the thing being watched. The follow resyncs from the top if the file is
+truncated or replaced under it, reads at most 512KB per poll so a large append is not allocated
+whole, and decodes through a `StringDecoder` so a chunk ending mid-codepoint keeps its character.
+
+**`foreman review [<initiativeId>]`** is the morning summary (`Review`, CONTEXT.md), grouped by what
+a human does with it: the Hand-offs ready to look at, the Hand-offs a failed check is holding, the
+Defects filed against what they delivered, the Tasks left blocked for a human, the Breakers that
+stopped the night early, and the Proposed Learnings to accept. Every Task is named by
+its title, so nothing in the output needs a second lookup to act on. Hand-offs come from the
+`attempt` events that named a pull request, keyed by URL: one entry per pull request with the
+attempt it is sitting at now rather than one per attempt, which also means two Tasks that named the
+same pull request collapse into one entry carrying whichever came later — the list counts pull
+requests to read, not Tasks that touched one. Defects come from the `verdict` events, each with the
+Task it was found on and the sibling Task it became, and each free-form field bounded as a whole as
+well as per line, with the cut named where it happens rather than left silent. Proposed Learnings
+come from the Initiative's memory log, which is where a Completion Report puts them
+(`core/learnings.ts`) — they become Accepted Learnings when a human merges the Foreman's learnings
+pull request.
+
+**A held Hand-off is not a Hand-off to look at.** A pull request whose Gates failed, or whose
+Verifier found Defects, is still open and still linked to its Task — the Foreman does not close or
+delete anything — but the Foreman has already decided it is not finished. Listing it beside the ones
+that passed sends a human to spend the first hour of the morning reading work that was never offered
+for review, so it gets its own section saying which check held it:
+
+```
+Hand-offs to look at (1)
+  OPS-2 "Status shows a blank Slot column"
+      https://gitlab.example/opsee/monorepo/-/merge_requests/462  (attempt 1, turn ended completed)
+
+Hand-offs held by a failed check (1)
+  OPS-1 "Give the terminal its three views"
+      https://gitlab.example/opsee/monorepo/-/merge_requests/461  (attempt 2, turn ended completed)
+      Held: the Verifier found Defects. The pull request is open and linked to the Task, which stays In Progress under foreman:blocked; the Foreman is not coming back to it on its own.
+```
+
+Held-ness is decided by `gateVerdictOf` (`core/gates.ts`) and `verdictStatusOf`
+(`core/verifier.ts`) on the Task's own slice of the Record — **the same two helpers Reconcile
+settles from**. That reuse is the point: if `review` judged it its own way, it and Reconcile could
+disagree overnight about whether a pull request was finished, and the human reading this in the
+morning would have no way to tell which of the two was wrong. Both attribute by attempt, so an
+earlier attempt's failed Gates do not follow the attempt that fixed them, and the Task filter
+matters because `gateVerdictOf` matches on the attempt number alone — two Tasks both on attempt 1
+would otherwise read each other's Gate events. A repository whose recipe runs no Gates is *ready*
+and separately reported as unchecked: no check is not a failed check.
+
+**The blocked list comes from the Task, not the Run Record**, and that is deliberate. A Task
+refused before dispatch — a work contract with no Goal, a Triage turn past its retry cap — has no
+`attempt` event at all, because `refuse` appends nothing when nothing was dispatched. Those are the
+Tasks most in need of a human, and a Record-derived list would be silently missing exactly them. So
+the section reads the `foreman:blocked` Status Label off the Initiative's task list, which
+`getInitiativeContext` already returns whole and this view used to narrow away, and uses the Record
+only for the detail: the last attempt's outcome where there was one, and where there was not, a line
+saying so and pointing at the Task. It follows that where the task list **cannot** be read the
+section reports `(not known)` rather than `(0)` — the label lives on the Task, so no task list is no
+answer, never the answer "none".
+
+That last list is **the Initiative's whole memory log**, and its heading says so. There is exactly
+one Run per Initiative, created by its first appended event, so the Run Record sections above are
+cumulative too; but the memory log has no window and an entry stays on it after the learnings pull
+request is merged, because acceptance is a merged file in a repository and not a change to the
+entry. A second night's `review` therefore lists the first night's Learnings again, and the pull
+request, not this view, is what says which are settled. The Initiative id may be left out when this
+machine's Process Table names exactly one — `knownInitiatives` is every Initiative the table has
+ever held a Worker row or a Run request for and those rows are never pruned, so once a machine has
+worked a second Initiative the argument is required from then on.
+
+**The Breaker section is wired and currently always empty.** `RunBreakerEvent` is in the proto and
+this section reads it, but no code path writes one yet — the Breakers slice (OPS-279) is deferred —
+so the section says so in place of a list. Read an empty Breaker section as "no Breaker was
+recorded", not as "no limit was reached". The day something appends those events, the section
+renders them with no change here.
+
+Nothing these views print is trusted. A Task's identifier and title come from the Tracker; an
+Account's pause reason is the vendor's own sentence; a Gate's name, command and working directory
+come from the repository's Run Recipe, which a full-privilege implementer Worker may edit inside its
+Workspace; a Defect's fields are a Verifier's prose and a transcript is whatever the vendor
+streamed. `mcp/src/utils/format/run-record.ts` renders the same events into Markdown and treats
+every such string as hostile; these views owe the same to a terminal, where the hazard is not a
+heading marker but an ANSI escape that repaints the screen, a `\r` that overwrites the line just
+printed, or a bidi override that reverses what a name reads as. So every value that comes off an
+event, a row, an Account or a Task goes through `printableOneLine` (`core/text.ts`, OPS-277), which
+collapses whitespace and then drops the whole `Cc`/`Cf` range; there is no second treatment and no
+exception. Stripping those ranges does not make `String.length` a display width, though — five CJK
+characters are five UTF-16 units and ten terminal columns, an emoji is two units and two columns, a
+combining mark is a unit and no column at all — so the table pads by a width function rather than by
+`.length`, and a Japanese Account name or a Task title full of combining marks cannot knock the rows
+below it out of line.
+
+`foreman-views.test.ts` covers all three against a temporary Process Table, transcripts directory
+and fake Tracker: two Accounts with their Slots and a Paused one with its reset, a Verifier round
+holding the reserved Slot, the cap-1 round that holds no Slot of its own checked against a real
+`Slots` rather than a restatement of the same guess, a killed Foreman's rows holding no Slot, a row
+on a de-registered Account, a table re-read between invocations, `--watch` repainting and stopping,
+a live follow that picks up appended lines and ends when the row goes, one that ends when the row
+comes back on a later attempt, a file truncated under a follow, an append past the per-poll bound, a
+multi-byte character split across a poll, a stored tail found by identifier with no row, a numeric
+id resolved through the Tracker, a Task with neither, eleven transcript lines whose JSON is
+well-formed and whose types are not, and a Run Record carrying a Hand-off, a Defect and a Proposed
+Learning with the Tasks named by title. It also pins that neither a one-shot `status` nor a `logs
+--no-follow` asks for the interrupt handler it would never await, and that `review` walks the memory
+log once rather than once for nothing and once for the Learnings. The last
+describe feeds an ANSI escape, a carriage return, a bell and a bidi override into an Account name, a
+pause reason, an identifier, an assistant message, a Gate's name, command and cwd, a Defect's title
+and fields, a Breaker's message and a Proposed Learning, and asserts that no control character
+reaches the output and the untouched rows around them still line up.
+`opsee-tracker-adapter.integration.test.ts` runs `review` once against the real backend, where the
+`eventCount` is a real bigint, a Run-wide event really has no `task_id`, and the titles come from a
+second RPC that has to agree with the first about which ids exist.
+
+### Planning sessions: `foreman plan`
+
+`opsee foreman plan <initiativeId> [--account <name>] [--skill <to-issues|wayfinder|to-spec>] [--memory <n>]`
+(story 10, `src/commands/foreman-plan.ts`) opens an attended session that starts already knowing
+last night's results. It is attended only: nothing in it launches or resumes a Worker turn, and
+the session is never resumed unattended. Git in that session is the human's own, outside the
+Foreman's guard (ADR-0003, "attended sessions are outside the guard"): the prompt tells the
+session to commit to the planning branch and leave pushing, merging and pull requests to the
+human, and nothing in the command enforces it.
+
+The Account is chosen as `foreman run` chooses it (`--account`, or the only one registered), so
+the vendor is whatever that Account is. A Workspace is made through the same `WorkspaceManager`
+and guarded git as a Task's, on a planning branch of the Foreman's own,
+`foreman/plan-<initiative>-<timestamp>` (`planBranch` in `core/plan-context.ts`, the shape of the
+learnings branch), from the default branch's remote head, under the workspaces root. The planning
+skill must be in that worktree where the vendor looks for it (`.claude/skills/<skill>/SKILL.md`
+for Claude Code, `.agents/skills/<skill>/SKILL.md` for Codex; `opsee init` writes both): the
+command never writes it, since the worktree is the human's to commit from, and a checkout without
+it is refused before the Tracker or git is touched, with the line that fixes it (run `opsee init`,
+commit, merge); a skill in the checkout but not yet on origin's default branch is refused after
+the Workspace is made, with the command that removes it. The default skill is `to-issues`.
+
+The context (`assemblePlanContext`, `core/plan-context.ts`) is Context Assembly turned to the
+Initiative, read through the Tracker Adapter's `getInitiativeContext` (the backend's
+GetInitiativeContext, what the MCP's `opsee_get_initiative_context` shows, with the memory log
+walked in full rather than windowed): the Initiative's title, status and summary; the core idea;
+the task tree in the server's parallel batches (which lay out the whole graph, Done Tasks
+included), one line per Task with its status and blockers; the Completion Reports (the `outcome`
+memory entries, newest first, each with its Task and Hand-off); the rest of the memory log newest
+first; and the pull requests linked to the Initiative's Tasks. The memory is windowed: system
+entries are left out, then the newest `--memory <n>` entries are kept (`DEFAULT_MEMORY_LIMIT`,
+200), the window taken before the Completion Reports are pulled out so both sections come from
+the same entries, and both say what was left out; a long-lived Initiative therefore does not send
+every session's context to a file. Every part is quoted as data, and each agent-authored entry
+carries the MCP's own marker (`AGENT_AUTHOR_MARKER`, imported from `@opsee/mcp-server`), since
+the whole Tracker is agent-writable (story 46); the few fields that land outside a quoted block
+(the Initiative's title and status in the preamble and section heading, an entry's kind,
+identifier and source URL on its `#### ` line, the title on the terminal) are flattened to one
+line (`oneLine`, `core/text.ts`), so a value an agent wrote with a newline and a `## ` heading in
+it cannot open a section of the prompt's own. The instruction comes last: run `/<skill>` against
+the Initiative; file every Task into it by id through the MCP tools as they are
+(`opsee_decompose_initiative` and `opsee_reconcile_initiative` take `initiativeId`, reconcile
+`dryRun` first with `existingTaskId` on every kept Task; `opsee_create_task` takes no
+`initiativeId`, so a Task made with it is followed by `opsee_link_task_to_initiative` or
+`opsee_update_task` with `initiativeId`), the work contract in each Task's `description` as the
+four headings `## Goal`, `## Acceptance Criteria`, `## Verification`, `## Boundaries`; git is the
+human's, commit but never push, merge or open a pull request; publish only what the human
+approves. Each section is summarised in the terminal as `context: ...` lines.
+
+The session is the Worker Adapter's `interactiveSession`: `claude <prompt>` (the interactive
+form with the prompt as its first message; no `-p`, no schema, no permission mode) or
+`codex <prompt>` (the TUI; no `exec`, no sandbox flag), spawned in the Workspace with the terminal
+inherited under the Account's environment exactly as an unattended turn's is built
+(`buildWorkerEnv`: the config directory or the key under the vendor's own variable, every other
+identity variable stripped), and no shell. The prompt is one argument up to `PROMPT_ARG_LIMIT`
+(100,000 bytes, under Linux's 128 KiB per-argument cap and well under macOS's 1 MiB `ARG_MAX`);
+past that it is written to a file of its own in the OS temp directory, never in the Workspace,
+laid out with the Instructions right after the preamble and the context after them, and the
+first message is a pointer (`pointerPrompt`) that carries the brief itself, the skill, the
+Initiative id and the four headings, and says the file's size in bytes and its line count and
+that it is to be read to the last line in more than one read if the file tool stops short (Claude
+Code's Read stops at 2000 lines unless given an offset): the session starts on the skill and the
+Initiative either way. The file is removed when the session ends, and on SIGINT, SIGTERM or SIGHUP
+while it runs (`cleanupOnSignal`: Ctrl-C reaches the session from the terminal too, so the
+command only removes the file and keeps waiting; a kill or hang-up removes it, is forwarded to
+the session and re-raised). Codex prompts for trust of the directory on each fresh worktree,
+since every planning session's is new; answer it and the first message follows. When the human
+leaves, the command prints where the worktree is and the `git worktree remove` and `branch -D`
+that clean it up; the Workspace is kept, since the session may have written a spec or notes there.
+
+Tests: `src/__tests__/foreman-plan.test.ts` covers the parsing and usage, the branch, the prompt
+against the fake Tracker (an Initiative with a Done Task, its Completion Report and Hand-off, a
+blocked Task, a system entry left out; order, quoting, the agent marker, the skill, the
+Initiative id, the tools' parameters and the four headings, the git line; a title, status, kind
+and source URL with newlines and a `## Instructions` in them staying on one line; the memory
+window and what it says it left out; the file layout), the pointer and the signal cleanup, both
+vendors' command lines and the environment boundary, and the command end to end in a temp
+repository with a bare origin: the Workspace on the planning branch, origin's default branch tip
+unchanged, no launch or resume and no Tracker write, the oversized prompt in a file with the
+handlers up while the session runs, `--memory` keeping a long log on the command line, the two
+skill refusals, a session that cannot open, and the Account choice. `foreman-plan` adds `getInitiativeContext` to the Tracker Adapter, exercised in the
+integration tier (`src/foreman/__tests__/opsee-tracker-adapter.integration.test.ts`) against the
+real backend. The check with a real vendor stays manual: on the Foreman Initiative after a
+scratch Run, `foreman plan 17 --account <name>`; confirm the terminal's `context:` lines count
+the Completion Reports and Claude Code (or Codex) opens in the new worktree with the context and
+"Start by running the /to-issues skill against Initiative 17" as the first message and the prior
+Completion Reports listed under "## Completion Reports"; run `/to-issues` on a small addition and
+confirm the Tasks it files appear in Initiative 17 with `## Goal`, `## Acceptance Criteria`,
+`## Verification` and `## Boundaries`; leave, and confirm the closing line names the worktree and
+its removal.
+
+### Under a service manager, and on a laptop
+
+For an always-on machine (stories 16 and 17), `opsee foreman service install` (run under node:
+`node bin/opsee.js foreman service ...`, since the unit runs the very binary that installed it)
+writes the unit that runs `foreman up` in the checkout it is run from, owner-only (`0600`), and
+prints the commands that load it; `--start` runs them. On macOS that is a LaunchAgent,
+`~/Library/LaunchAgents/io.opsee.foreman.plist` (`RunAtLoad` at login, `KeepAlive` on an
+unsuccessful exit so a crash restarts it but a clean stop stays down, `ThrottleInterval` 10s
+between those restarts, `ExitTimeOut` 30s, output to `~/.opsee/foreman.log`), loaded with
+`launchctl bootout gui/<uid>/io.opsee.foreman` (exit 3 or 5, "not loaded", tolerated) and then
+`launchctl bootstrap gui/<uid> <plist>`, because `bootstrap` alone fails on a loaded label and
+launchd keeps the old plist. On Linux a user unit, `~/.config/systemd/user/opsee-foreman.service`
+(`Restart=on-failure`, `RestartPreventExitStatus=3`, `TimeoutStopSec=30`, `WantedBy=default.target`,
+output in `journalctl --user -u opsee-foreman`), loaded with `systemctl --user daemon-reload`,
+`enable` and `restart` (not `enable --now`, which leaves a running unit on the old file); for it to
+start at boot without a login, `loginctl enable-linger $USER` once. Both run the node binary and
+`bin/opsee.js` by absolute path in the checkout as working directory, carry `PATH` (the vendors'
+CLIs must be on it), `HOME` and the `OPSEE_*` overrides of the installing shell, and never a
+credential: `OPSEE_API_TOKEN` and every variable an Account registered by `--key-env` reads its
+key from (`keyRef` can be any name, `OPSEE_*` included) are excluded by name, anything else whose
+name says `TOKEN`, `KEY`, `SECRET` or `PASSWORD` is dropped as a net, the daemon logs in through
+the credentials file, and the `--key-env` Account's variable must be added to the unit's
+environment by hand (install names it). The stop budget is 30s under both managers because on
+SIGTERM the daemon's process hooks SIGTERM every Worker and SIGKILL them 5s later, then it leaves;
+the interrupted turn is resumed by session on the next start, so the budget covers the grace
+period, not a Worker turn. `foreman up` beside another Foreman (one started from a terminal, say)
+exits 3, not 1: systemd does not restart that, launchd cannot tell exit codes apart and retries it
+every 10s until the other one is stopped, which the unit's comment and install's notes say.
+`foreman service uninstall [--stop]` removes the unit (a `bootout` that says "No such process" is
+"was not loaded", and the file is still removed), `foreman service status` says whether the unit
+file is present and whether a daemon is up. Reboot continuity is the daemon's own: the pid file a
+reboot leaves is stale whatever it names, because pids restart low and last boot's number is often
+some other process's today (and `pidIsAlive` counts `EPERM` as alive), so `liveDaemonPid` treats a
+file whose mtime predates this boot (`os.uptime`) as stale, then checks the pid answers, then that
+its command line (`/proc/<pid>/cmdline` on Linux, `ps -o command=` elsewhere; an unreadable one is
+not held against it) is a Foreman's; the first Reconcile resumes, by session id, every Worker
+whose pid died with the machine (`src/foreman/service-unit.ts`, `src/commands/foreman-service.ts`;
+tests in `src/__tests__/foreman-service.test.ts` and the reboot case, with a live reused pid and an
+old mtime, in `foreman-command.test.ts`).
+
+On start, `foreman up` probes for an internal battery (`src/foreman/host.ts`: `pmset -g batt`
+then `ioreg -c AppleSmartBattery` on macOS; on Linux any `/sys/class/power_supply/*` whose `type`
+is `Battery` and whose `scope` is not `Device`, so `macsmc-battery`, `axp20x-battery`, `sbs-*` and
+`bq27xxx-*` count and a wireless mouse's battery does not) and on a
+laptop prints a warning: sleep suspends every Worker mid-turn, Reconcile resumes them on wake, but
+the Run stalls until then; keep it awake (`caffeinate -i opsee foreman up`,
+`systemd-inhibit --what=sleep opsee foreman up`, or the power settings) or move the Run to an
+always-on host with `foreman service install` there. A desktop or a server gets no warning, and so
+does a machine whose probe fails: the warning is a courtesy, and a false one on every server would
+teach people to ignore it.
+
+The reboot check is manual, since no test can reboot: on a Mac, `foreman service install --start`
+from the checkout, `foreman run <id>` against a scratch Initiative with a Task whose turn takes a
+few minutes, reboot during the turn, log in, and confirm in `~/.opsee/foreman.log` that the daemon
+came up, said `Worker gone (pid ...), resuming session ...`, and that the Task ends with one
+Completion Report and its draft pull request; then `foreman service uninstall --stop`. On a Linux
+VM, the same with the systemd unit and `journalctl --user -u opsee-foreman`, after
+`loginctl enable-linger $USER`. For the warning, run `foreman up` on a laptop and on a server and
+compare the two starts.
+
+Tests: `src/__tests__/foreman-{process-table,reconcile,outbox-tracker,reconcile-run}.test.ts`
+cover the table on a temporary file, the Reconcile decisions, the outbox wrapper (including a drain
+and two appends at once, which against an unserialised outbox sends the first batch three times), and the
+acceptance scenarios with the fakes (a first `runForeman` abandoned mid-turn, a second against the
+same file); `src/foreman/__tests__/foreman-outbox.integration.test.ts` queues Run Record writes
+against a client set aimed at a dead port and drains them into the real backend. The live check
+stays manual: dispatch against a scratch Initiative, kill the daemon during the turn, restart it,
+and confirm one Completion Report; repeat with the backend stopped for a minute and confirm the
+Run Record catches up in order; delete the table and restart, and confirm no new dispatch. Two
+things to watch there that no fake shows: a Worker orphaned by `kill -9` keeps writing to a pipe
+nobody reads and may die on it (then the tick after resumes the session, which is the designed
+path either way), and a pid the OS has reused for an unrelated process reads as alive, so that
+row waits until the impostor exits.
+
+Tests: `src/__tests__/foreman-{report,context,workspace,git-guard,remote-api,handoff,run,command}.test.ts`
+cover the mapping, the rendering, Workspace creation and the Hand-off against a real temporary
+repository with a bare origin, the git guard, the two code-host clients over a scripted CLI, the
+loop against the fake Tracker (`src/foreman/fake-tracker-adapter.ts`, whose Tasks carry a complete
+contract unless the test says otherwise), fake Worker and fake Hand-off, and the command wiring;
+`foreman-learnings.test.ts` the learnings step: the gathering, the file, the branch and the one
+pull request per Initiative against a real bare origin and the fake code host;
+`work-contract.test.ts` and `triage-draft.test.ts` the contract parser and the draft projection;
+`opsee-tracker-adapter.test.ts` the BlockNote-to-markdown mapping of a description and a comment;
+`foreman-gates.test.ts` the Gate commands themselves (real shell commands in a temporary
+directory, the timeout kill, the byte cap on a single overlong line, the filtered environment, a
+real repository whose Worker branch rewrites the recipe while the base's commands run, the event
+shape, the verdict reader and the texts) and `foreman-run-gates.test.ts` the loop's scenarios with
+scripted Gate results: a Worker that breaks a test and fixes it on the resumed turn (two Gate
+events, one resume on the same session with the Process Table row intact, the passing comment
+between the Run Record and the board in the Tracker's write log), one that never fixes it (blocked
+at the cap with the Gate named), no Gates without a Hand-off, the skip, a resumed turn that reports
+blocked or stalls at a cap of one (the reason, not the cap, in the summary; the pull request kept
+and commented; the earlier done report in memory), and one whose second Hand-off is incomplete.
+`foreman-reconcile-run.test.ts` has the settlement Reconcile finishes for an attempt whose Gates
+held the Hand-off (blocked) beside one whose Gates passed (In review).
+`src/foreman/__tests__/foreman-run.integration.test.ts` runs three scenarios against the real backend
+(`make test-integration`): A-blocks-B, two Tasks asking for two files, two Workspaces, A pushed to
+the bare origin and opened on the fake code host (`src/foreman/fake-remote-api.ts`), linked to A
+through the raw RPC and parked In review while B waits, then B after A is moved to Done by hand
+with A's report in its context, comments, memory and Run Record checked through the raw RPCs, the
+origin's default branch and the main checkout unchanged; the work contract at dispatch, a
+complete Task, one missing Verification and one missing Goal, the first dispatched as is, the
+second after a Triage turn whose draft is on the Task, the third refused with the reason; and the
+Gates over a repository whose committed recipe has one real Gate (`test ! -f broken.txt`), a Task
+whose Worker breaks it and fixes it on the resumed turn and one whose Worker never does (and
+rewrites the recipe on its branch to `true`, which changes nothing: the base's command runs), the
+`gate` events read back from the real Run Record, the fixing commit on origin, the comments on
+the fake code host and the two Tasks' boards and labels through the raw RPCs.
+
+## Verifying `opsee init` by hand
+
+After a change to `init`, in a scratch git repo:
+
+1. Run `node <path>/cli/bin/opsee.js init --project <key>`; it must list what it created and end
+   with the counts line. Start Claude Code there: `/wayfinder`, `/to-spec` and `/to-issues` must
+   be offered and the `opsee` MCP server must connect (OAuth on first use). Codex must show the same
+   three skills and the server from `.codex/config.toml`.
+2. Run it again; every line must read `unchanged`.
+3. Edit one line of `docs/agents/issue-tracker.md` and run it once more; the edit must survive and
+   the doc's line must read `kept ... — edited since opsee init wrote it`.
+4. In a repo whose `.opsee/config.yaml` has a `commands.dev`, the first run must append a `foreman`
+   block with that command as `start` and the second must report `.opsee/config.yaml` unchanged.
+   Then `node <path>/cli/bin/opsee.js foreman debug serve 5180` (hidden) must print `starting: ...`,
+   then `ready: http://localhost:5180/ answered after ...`, and keep the app up until Ctrl-C; a
+   second `serve 5181` alongside it must become ready too.
+
+## Foreman seams
+
+The Foreman core (`cli/CONTEXT.md` has the vocabulary) is a library in this package that sits
+behind four seams, each an interface in `src/foreman/`, filled in as the core lands:
+
+- **Remote API** (`src/foreman/remote-api.ts`): the little the Hand-off and the Gates need from
+  the code host, which is to find, open and update one draft pull request for a branch (or by exact
+  title, how the learnings pull request is found again), to comment on it and to put a Verifier's
+  screenshot on it (`uploadAttachment`; GitLab uploads, GitHub cannot), and nothing that could
+  merge (the interface has no such method, checked at compile time in `foreman-remote-api.test.ts`). `GitLabRemoteApi` runs `glab api` and `GitHubRemoteApi` runs
+  `gh api`, both under the user's own CLI login through a `CliRunner` seam the tests script;
+  `remoteApiFor` picks one from the origin URL. `src/foreman/fake-remote-api.ts` is the in-memory
+  code host the loop and integration tests use.
+
+- **Worker Adapter** (`src/foreman/worker-adapter.ts`): launch, stream events, detect completion,
+  resume, and stop one Worker for one coding-agent product, plus `interactiveCommand`, the vendor's
+  interactive resume of a session for an attended turn (`foreman attach` runs it; the adapter never
+  drives it), and `interactiveSession`, the vendor's interactive form opened from scratch on a
+  first message (`foreman plan` runs it in a planning Workspace). `launch` and `resume` return a
+  `TurnHandle` whose events are `started`, `output`, `tool`, `rate_limited`, `stalled` and exactly
+  one terminal `completed` (carrying the Completion Report) or `failed` (a typed reason:
+  `launch_failed`, `invalid_report`, `max_turns`, `rate_limited`, `stalled`, `stopped`,
+  `vendor_error`). The Completion Report (`src/foreman/completion-report.ts`) is one TypeScript type,
+  one JSON schema handed to the vendor, and one validator; a turn that ends without a valid one is
+  `invalid_report`, never a guess. The same three make an `OutputContract`, and a request may name
+  another (`TurnRequest.contract`: the Verifier's Verdict) and MCP servers for the turn
+  (`TurnRequest.mcpServers`: its Playwright MCP); the adapters render both (see "Verifier").
+
+  `src/foreman/claude-worker-adapter.ts` is the Claude Code implementation: `claude -p
+  --output-format stream-json --verbose --json-schema <report schema> --permission-mode acceptEdits
+  [--max-turns n] [--resume <id>] <prompt>`, spawned with the cwd pinned and an environment built
+  from the Account alone (`CLAUDE_CONFIG_DIR` for a subscription, `ANTHROPIC_API_KEY` copied from
+  the named variable for a key; every other identity variable stripped). The stream's `init` line
+  gives the session id, `result.structured_output` the report, a `rate_limit_event` that is not
+  advisory or a documented limit string in an error result gives `rate_limited` with `resetAt` when
+  the vendor said, and silence past `stallTimeoutMs` gives `stalled` and stops the Worker.
+
+  `src/foreman/codex-worker-adapter.ts` is the Codex implementation: `codex exec [resume <id>]
+  --json --skip-git-repo-check -c sandbox_mode="workspace-write" --output-schema <file> <prompt>`,
+  spawned the same way (`CODEX_HOME` for a subscription, `CODEX_API_KEY` copied from the named
+  variable for a key, which `codex exec` takes ahead of any stored login). `--output-schema` wants a
+  file and the OpenAI structured-output endpoint refuses optional keys, so each turn writes a strict
+  projection of the report schema (every key required, `handOff` and its fields nullable) to a temp
+  file of its own and folds the nulls away before the shared validator; the report is the text of
+  the last `agent_message` before `turn.completed`. The `thread.started` line gives the session id.
+  The exec stream has no rate-limit event, so `rate_limited` comes from the message of `turn.failed`
+  (or a preceding `error` line) matching the vendor's own strings, with `resetAt` when it names a
+  dated "try again at". Codex has no turn cap, so `maxTurns` is not applied. Flags and shapes were
+  verified against codex-cli 0.147.0; the module header cites what and where.
+
+  `src/foreman/fake-worker-adapter.ts` replays scripted event lists for every later Foreman test. A
+  script may be a function instead of a list, which is what the scheduler's tests use: `gatedTurn`
+  starts, then holds until the test lets it report, so several turns can be open at once and the
+  concurrency assertions are deterministic rather than raced. `scriptFor` picks a script from the
+  request rather than from the queue, for tests where the queue's order is the thing under test.
+  `src/__tests__/worker-adapter-contract.ts` is the one contract suite, run for the fake and for
+  each vendor adapter with its process seam replaced by a replayer of the recorded fixtures in
+  `src/foreman/__fixtures__/claude/` and `.../codex/` (provenance in the README there; the Codex
+  happy and resumed turns are real recordings). What the adapters share below the vendor protocol,
+  the spawn seam, the identity-variable handling (`buildWorkerEnv`) and the turn lifecycle (line
+  reassembly, stall timer, stderr tail, exit handling), lives once in
+  `src/foreman/worker-process.ts`; a Worker runs detached in its own process group and `stop()`
+  signals the group, SIGTERM then SIGKILL after a grace period, through
+  `src/foreman/process-group.ts`, which the Run Recipe's `stop` uses too. Because a detached
+  child outlives a dying parent, the first real spawn installs process-wide hooks that stop live
+  Workers on SIGINT/SIGTERM/SIGHUP before re-raising, and SIGKILL them on `exit`.
+  `account-boundary.test.ts` also runs a turn of each adapter under
+  the fs audit, with the vendor binary replaced by a fixture-replaying child, so both are held to
+  the credential boundary the same way registration is.
+
+  `opsee foreman debug turn --account <name> --cwd <dir> --prompt <text> [--resume <session-id>]
+  [--max-turns <n>] [--stall-timeout <ms>] [--raw]` is the hidden manual check: one turn (or a
+  resumed one) under a registered Account, every event printed, the Completion Report last, exit 0
+  when the Worker reported. `--raw` also prints each vendor stream line, which is how a fixture is
+  re-recorded. Nothing is written to Opsee; a Run is the scheduler's job.
+- **Tracker Adapter** (`src/foreman/tracker-adapter.ts`): read and write one kind of Tracker. The
+  v1 implementation, `src/foreman/opsee-tracker-adapter.ts`, is Opsee over Connect-RPC: it calls
+  the same backend RPCs the MCP tools do, directly, stamped `X-Opsee-Client: cli`. Readiness is
+  the server's `GetReadyTasks` (first open slice intersected with the `ready-for-agent` label),
+  never a client-side blocker walk; board moves resolve the column by lifecycle state
+  (`todo`, `in_progress`, `done`, ...) so any project's board works; labels are by name;
+  `getInitiativeContext` is the server's GetInitiativeContext (the Initiative, its task graph and
+  pull requests) with the memory log walked in full, what `foreman plan` starts a session from.
+
+  It is exercised against a real backend, not mocked: `make test-integration` here (or
+  `bun run test:integration`) boots the API-test harness on ephemeral Postgres through
+  `backend/apitest/serve` and drives every operation, asserting on Opsee state through the raw
+  RPCs. Needs Docker and fails without it (a skipped tier would report green for a backend nobody
+  exercised); the cold run compiles the harness runner and can take a few minutes. `opsee foreman debug ready <initiativeId>` is a hidden, read-only command
+  that prints an Initiative's Ready Tasks as the adapter sees them.
+- **Run Recipe** (`src/foreman/run-recipe.ts`): how to start the app in a Workspace so a Verifier
+  can drive it: start command, readiness URL, port variable, Gate commands. Filled in (see "Run
+  Recipe" above); `opsee foreman debug serve <port>` is the hidden manual check that starts the
+  cwd's app on a port and reports when the readiness URL answers.