omp-conductor 0.2.0 → 0.2.2

package/README.md

@@ -212,6 +212,48 @@ turned on you can also invoke it directly:
 Nothing about the wizard changes: `/conductor setup` on its own remains a
 complete, supported path, and the brief it renders is safe unedited.
 
+### Keeping a brief current
+
+Upgrading the package does not upgrade a brief you are already running, and it is
+worth knowing exactly which half of that sentence is true.
+
+| What | Updates on `omp plugin install`? |
+| --- | --- |
+| `skills/conductor-onboarding/SKILL.md` | Yes. The session reads it from the installed package. |
+| `src/briefs/worker.md` | Yes. It is read per run, so the next worker gets the new text. |
+| `src/briefs/orchestrator.md` | Yes, but it is only a *template*: it is read when the wizard renders a brief. |
+| Your rendered `ORCHESTRATOR.md` | **No.** It was written once and is yours from then on. |
+
+That last row is the point. Once the wizard renders your brief, nothing in this
+package reads it back or rewrites it, so a later version that ships a new protocol
+above the `YOURS TO EDIT` banner is invisible to every fleet already running:
+
+```bash
+omp-conductor brief-upgrade              # report only
+omp-conductor brief-upgrade --apply      # replace the shipped half, keep yours
+```
+
+The banner is what makes this safe. Everything above it belongs to the package and
+everything below it belongs to you, so an upgrade replaces the first and copies the
+second across untouched, keeping the previous file as
+`ORCHESTRATOR.md.bak-<timestamp>`. Three cases where it will not write at all:
+
+- **Your brief has no banner** (hand-written, or predating the split). There is no
+  way to tell which lines are yours, so it lists the sections the template has and
+  yours does not, and leaves the file alone. Retitled sections count as present, so
+  `## Reporting (low noise)` is not reported as a missing `## Reporting`.
+- **No config resolved**, so the template still carries its `{{PLACEHOLDER}}`
+  coordinates. Merging it would write those literals into a live prompt.
+- **Nothing changed.** It says so and exits.
+
+`--file PATH` checks a brief that is not where the wizard would have put it, which
+is the normal case on a dedicated fleet host: the supervising session runs from its
+own directory, and that host may never have configured a dispatch daemon.
+
+A brief with the **Learning loop** section has a second route. The session running
+from it can propose the missing sections itself, as a diff, for you to approve with
+a yes over Telegram, which is the same protocol it uses for any other amendment.
+
 ## Quick start
 
 1. Write a config (see [Configuration](#configuration)) at
@@ -275,10 +317,14 @@ Per tick, for the daemon's project:
    the configured repo names. These are never dispatched.
 5. **Check spend.** If spend since local midnight has reached `dailySpendUsd`, the
    daemon **pauses itself**, pages at Tier 2, and returns.
-6. **Check capacity.** `maxConcurrentWorkers` minus active runs gives the free
-   slots. If none are free, the tick logs and returns.
+6. **Check capacity.** `maxConcurrentWorkers` minus *live* workers (runs in
+   `claimed` or `running`) gives the free slots. A green PR awaiting a human
+   merge occupies its issue but not a slot: its worker is finished, and counting
+   it would let two green PRs stop the fleet. If no slot is free, the tick logs
+   and returns.
 7. **Admit issues** up to the free slots, skipping any issue that already has
-   an active run. An issue that has used `maxAttemptsPerIssue` escalates at Tier 1
+   an active run — including a green PR, so a second attempt can never land on a
+   live PR. An issue that has used `maxAttemptsPerIssue` escalates at Tier 1
    instead of being admitted.
 8. **Dispatch** the admitted issues concurrently.
 
@@ -288,9 +334,9 @@ Then, per admitted issue:
    This ordering is the whole crash-safety story: the label, not the local
    database, is the guard against dispatching the same issue twice. If the process
    dies at any later point, the next daemon sees the label, eligibility filters the
-   issue out, and a human decides what to do with the orphan. A store that is lost
-   can be rebuilt from the tracker; a label that was written too late cannot undo a
-   duplicate PR.
+   issue out, and the orchestrator's drain duty triages the orphan (see below). A
+   store that is lost can be rebuilt from the tracker; a label that was written too
+   late cannot undo a duplicate PR.
 2. Create the run row (`claimed`).
 3. Clear any stale tree for this issue, then add a fresh worktree at
    `<workspaceRoot>/<issue>` cut from the bare mirror at `<mirrorRoot>/<repo>.git`,
@@ -312,6 +358,26 @@ Then, per admitted issue:
    leaves a window in which the issue carries no state label at all, which is
    exactly the shape eligibility reads as fresh work.
 
+### What a restart does to runs that were in flight
+
+A `claimed` or `running` row is a promise that a worker process exists, and a
+daemon that just started knows that promise is broken: its workers died with the
+previous process. At startup — unless another daemon is alive, so a foreground
+`daemon --once` cannot orphan a running daemon's real workers — every such row is
+moved to `orphaned`, with a log line naming the issue, the attempt and the
+worktree. That frees the slots immediately; a fleet must never resume as
+deadlocked as it crashed.
+
+Only the rows change. The issue keeps `agent:in-progress` — the label is the
+crash guard against double-dispatch — and deciding what the dead worker's remains
+are worth is the orchestrator's drain-duty judgement, spelled out in its brief:
+an open green PR goes to the merge path, a dirty tree is reported before anything
+destroys it (uncommitted edits have no other copy; unpushed *commits* are safe on
+the run's branch in the mirror, which a retry deliberately reattaches), and a
+clean orphan has its label released so the next tick re-claims it. Orphaned
+attempts still count toward `maxAttemptsPerIssue`, so a crash loop escalates
+instead of redispatching forever.
+
 ### Branch names
 
 `<type>/<slug>`, where the type is `fix` when any label's last segment (after `:`
@@ -620,6 +686,7 @@ omp-conductor status [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor pause
 omp-conductor resume
+omp-conductor brief-upgrade [--apply] [--file PATH] [--project NAME]
 omp-conductor help
 ```
 
@@ -635,6 +702,9 @@ omp-conductor help
 | `--project NAME` | Pick the project to service. One daemon process serves exactly one project; with several configured projects the name is required. |
 | `pause` | Stop claiming new work. The running daemon notices on its next tick; runs already in flight finish. |
 | `resume` | Allow claiming again. |
+| `brief-upgrade` | Compare a project's `ORCHESTRATOR.md` against the brief this version of the package ships. Reports by default; see [Keeping a brief current](#keeping-a-brief-current). |
+| `--apply` | Only for `brief-upgrade`. Replaces the half above the `YOURS TO EDIT` banner and keeps everything below it, backing the previous file up first. Ignored when the brief cannot be split or the template is unrendered. |
+| `--file PATH` | Only for `brief-upgrade`. Check a brief that is not where the wizard would have put it, on a host that may have no config at all. |
 | `help`, `--help`, `-h` | Print usage. An unknown or missing verb prints it too, and exits `2`. |
 
 Pause is a flag file under the state directory, so it applies to every project and
@@ -720,10 +790,10 @@ Known and deliberate in this version:
   (the orchestrator's) no matter how many workers are running, and no amount of
   `maxConcurrentWorkers` changes that.
 
-  The cap does work. The admission loop (`src/daemon.ts:405-445`) computes
-  `slots = maxConcurrentWorkers - active runs`, admits at most that many issues per
-  tick, and dispatches them together. To see them, read `omp-conductor status`,
-  which lists every active run, or follow `daemon.log`.
+  The cap does work. The admission loop (`src/daemon.ts:410-448`) computes
+  `slots = maxConcurrentWorkers - live workers`, admits at most that many issues
+  per tick, and dispatches them together. To see them, read `omp-conductor
+  status`, which lists every occupied issue, or follow `daemon.log`.
 - **Merges, releases and deploys are human-only, by design.** The conductor
   produces green PRs and stops.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/brief-upgrade.ts

@@ -0,0 +1,242 @@
+/**
+ * Keeping a live `ORCHESTRATOR.md` current with the shipped template.
+ *
+ * The wizard renders the template once and then never touches the file again,
+ * because from that moment it is the operator's. That is the right ownership
+ * rule and it has one consequence nobody notices until months later: every
+ * later improvement to the *shipped* half of the brief — a new duty, a protocol
+ * like the amendment loop — is invisible to every fleet already running. The
+ * package updates; the standing prompt does not.
+ *
+ * This module is the missing half of that story. It never guesses: the brief has
+ * an explicit banner separating the package's text from the operator's, so when
+ * that banner is present the split is exact and the merge is mechanical. When it
+ * is absent — a hand-written brief, or one predating the split — there is no
+ * honest way to know which lines are the operator's, so nothing is rewritten and
+ * the missing sections are reported instead.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+/**
+ * The line that divides the two halves. Matched on this substring rather than
+ * the whole comment banner so a reflowed or re-decorated banner still splits.
+ */
+const EDIT_BANNER = "YOURS TO EDIT";
+
+/**
+ * A brief split into the package's half and the operator's half.
+ *
+ * `shipped` runs to the end of the banner line; `owned` is everything after it.
+ * Concatenating them reproduces the input byte for byte, which is what makes a
+ * merge safe to write back.
+ */
+export interface BriefHalves {
+  shipped: string;
+  owned: string;
+}
+
+/**
+ * Splits on the banner, or returns `undefined` when there is none.
+ *
+ * `undefined` is a real answer, not a failure: it means this brief cannot be
+ * merged mechanically, and every caller is expected to degrade to reporting
+ * rather than to assume a boundary.
+ */
+export function splitBrief(text: string): BriefHalves | undefined {
+  const at = text.indexOf(EDIT_BANNER);
+  if (at < 0) return undefined;
+  // Keep the whole banner line on the shipped side: the operator's half starts
+  // at the first line they own, so a merge never has to reconstruct the banner.
+  const lineEnd = text.indexOf("\n", at);
+  const cut = lineEnd < 0 ? text.length : lineEnd + 1;
+  return { shipped: text.slice(0, cut), owned: text.slice(cut) };
+}
+
+/** A `## Heading` in the shipped half, by its exact text. */
+function headings(text: string): string[] {
+  const out: string[] = [];
+  for (const line of text.split("\n")) {
+    if (line.startsWith("## ")) out.push(line.slice(3).trim());
+  }
+  return out;
+}
+
+/**
+ * The comparable part of a heading: everything before the first dash, colon or
+ * bracket, lowercased.
+ *
+ * Operators retitle sections freely — `## Reporting` becomes `## Reporting (low
+ * noise, evidence-backed)`, `## Duty 1 — drain` becomes `## Duty 1 — the dispatch
+ * loop (run this on every tick)` — and an exact match would report all of those as
+ * absent. Ten reported sections when four are genuinely missing is a list nobody
+ * reads, which is the same as reporting nothing.
+ */
+function topicKey(heading: string): string {
+  const cut = heading.search(/[—–:(-]/u);
+  return (cut < 0 ? heading : heading.slice(0, cut)).trim().toLowerCase();
+}
+
+/**
+ * Shipped sections the live brief has no heading for.
+ *
+ * Matched on {@link topicKey}, so a retitled section counts as present. The
+ * remaining bias is deliberate: this decides what to *offer* for a hand-merge, and
+ * a section reported that the operator already covers costs them one read, while a
+ * new protocol silently counted as present costs them the protocol.
+ */
+export function missingSections(live: string, rendered: string): string[] {
+  const present = new Set(headings(live).map(topicKey));
+  return headings(rendered).filter((h) => !present.has(topicKey(h)));
+}
+
+/** Section bodies from a rendered template, keyed by heading, for reporting. */
+export function sectionText(rendered: string, heading: string): string {
+  const lines = rendered.split("\n");
+  const start = lines.findIndex((l) => l.startsWith("## ") && l.slice(3).trim() === heading);
+  if (start < 0) return "";
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== undefined && line.startsWith("## ")) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n").trimEnd();
+}
+
+/** An unfilled `{{KEY}}` coordinate in a template nobody rendered. */
+const PLACEHOLDER_PATTERN = /\{\{[A-Za-z0-9_]+\}\}/;
+
+/** What a check found, and what a caller may do about it. */
+export type BriefStatus =
+  | { kind: "current" }
+  /** Banner present and the shipped half differs: a merge is exact. */
+  | { kind: "mergeable"; merged: string; liveShipped: string; freshShipped: string }
+  /** No banner, so the boundary is unknown and only reporting is honest. */
+  | { kind: "unsplittable"; missing: string[] }
+  /** Template never rendered, so merging it would write `{{PROJECT}}` into a brief. */
+  | { kind: "unrendered"; missing: string[] };
+
+/**
+ * Compares a live brief against the freshly rendered template.
+ *
+ * `rendered` should come from `renderBriefForProject`, so the coordinates already
+ * match and a diff reflects policy changes rather than substitution noise. A raw
+ * template is accepted — a host that runs only the supervising session has no
+ * config to render from — but it can only ever produce a report.
+ */
+export function checkBrief(live: string, rendered: string): BriefStatus {
+  const liveHalves = splitBrief(live);
+  const freshHalves = splitBrief(rendered);
+
+  // A template without the banner is a packaging error, not an operator problem,
+  // so treat it the same as an unmergeable live brief rather than inventing a cut.
+  if (liveHalves === undefined || freshHalves === undefined) {
+    return { kind: "unsplittable", missing: missingSections(live, rendered) };
+  }
+
+  // Enforced here rather than at each caller: merging an unrendered template would
+  // write `{{PROJECT}}` into a live standing prompt, and a session reading its own
+  // coordinates as a literal placeholder is worse than an out-of-date brief.
+  if (PLACEHOLDER_PATTERN.test(freshHalves.shipped)) {
+    return { kind: "unrendered", missing: missingSections(live, rendered) };
+  }
+
+  if (liveHalves.shipped === freshHalves.shipped) return { kind: "current" };
+
+  return {
+    kind: "mergeable",
+    // The operator's half is carried across untouched. This is the whole safety
+    // property: an upgrade that reformats one of their sections is an upgrade
+    // nobody runs twice.
+    merged: freshHalves.shipped + liveHalves.owned,
+    liveShipped: liveHalves.shipped,
+    freshShipped: freshHalves.shipped,
+  };
+}
+
+/**
+ * Line-level diff of the two shipped halves, for a human to read before saying
+ * yes. Deliberately not a real diff algorithm: the shipped half changes by whole
+ * sections between versions, so listing removed and added lines in order is both
+ * enough to review and impossible to misread as a merge preview.
+ */
+export function shippedDiff(before: string, after: string): string {
+  const old = new Set(before.split("\n"));
+  const now = new Set(after.split("\n"));
+  const lines: string[] = [];
+  for (const line of before.split("\n")) {
+    if (!now.has(line) && line.trim() !== "") lines.push(`- ${line}`);
+  }
+  for (const line of after.split("\n")) {
+    if (!old.has(line) && line.trim() !== "") lines.push(`+ ${line}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Writes the merged brief, leaving the previous one beside it.
+ *
+ * The backup is not optional and not configurable: this file is a standing
+ * prompt an operator may have spent an hour on, and the one thing an upgrade
+ * must never do is be the reason it is gone.
+ */
+export function writeMergedBrief(path: string, merged: string): string {
+  const backup = `${path}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  writeFileSync(backup, readFileSync(path));
+  writeFileSync(path, merged);
+  return backup;
+}
+
+/** The check rendered for a terminal, including what to do next. */
+export function formatBriefStatus(path: string, status: BriefStatus): string {
+  if (status.kind === "current") {
+    return [`brief ${path}`, "", "up to date — its shipped half matches this version of the template."].join("\n");
+  }
+
+  if (status.kind === "mergeable") {
+    return [
+      `brief ${path}`,
+      "",
+      "This version of the package ships a different brief above the YOURS TO EDIT",
+      "banner. Everything below the banner is yours and would be carried across",
+      "unchanged.",
+      "",
+      shippedDiff(status.liveShipped, status.freshShipped),
+      "",
+      "Apply it with:  omp-conductor brief-upgrade --apply",
+      "The previous file is kept beside it as ORCHESTRATOR.md.bak-<timestamp>.",
+    ].join("\n");
+  }
+
+  const lines = [`brief ${path}`, ""];
+  lines.push(
+    ...(status.kind === "unrendered"
+      ? [
+          "The shipped template still carries its {{PLACEHOLDER}} coordinates, because no",
+          "project config resolved on this host. Merging it would write those literals",
+          "into a live standing prompt, so this can only be reported on. Run it with",
+          "--project on a host that has the config to apply an upgrade.",
+        ]
+      : [
+          "This brief has no YOURS TO EDIT banner, so it was written by hand or predates",
+          "the template split. There is no way to tell which lines are yours, so nothing",
+          "will be rewritten automatically.",
+        ]),
+  );
+  if (status.missing.length === 0) {
+    lines.push("", "It already has a heading for every section the template ships.");
+    return lines.join("\n");
+  }
+  lines.push(
+    "",
+    `Sections the shipped template has and this brief does not (${status.missing.length}):`,
+    ...status.missing.map((h) => `  - ${h}`),
+    "",
+    "Merge the ones you want by hand, or ask the session running from this brief to",
+    "propose them through its own amendment protocol.",
+  );
+  return lines.join("\n");
+}

package/src/briefs/orchestrator.md

@@ -54,6 +54,40 @@ For each one, pick exactly one of three outcomes:
 - **It is already done.** The PR is green and waiting on a human merge. Note it,
   with the link, and move on. You do not merge it.
 
+**Then check for orphans.** A worker is a process, and processes die: a daemon
+restart, a host reboot, a kill. The `agent:in-progress` label survives that death
+by design — it is the guard that stops the next tick double-dispatching — but
+nothing removes it, so a dead worker's issue sits "in progress" forever, occupying
+a slot that no longer exists. Compare the in-progress labels against the active
+runs `omp-conductor status` just showed you: **an in-progress issue with no
+matching active run is an orphan.**
+
+For an orphan, inspect what the dead worker left before touching the label. Read
+the issue itself (`gh issue view <n> --json labels` — the label-filtered *list*
+reads GitHub's eventually-consistent search index and lags label writes in both
+directions), then the worktree (`git status --porcelain`, `git log
+origin/main..HEAD`) and any PR. Four cases, checked in this order:
+
+- **An open PR that is green.** That worker finished; it just never got to report.
+  This is the "already done" case above: note it with the link and move on. Never
+  release-and-re-claim it — a fresh worker would duplicate a finished run.
+- **A dirty tree** (uncommitted edits in the worktree). This is the one thing a
+  re-claim destroys: the conductor removes and reattaches worktrees with `--force`
+  on every attempt, and uncommitted edits have no other copy. Do not release the
+  label yet — report what exists and where, and let your operator decide whether
+  it is worth salvaging. Uncommitted edits are work too; "nothing committed" is
+  not "nothing there".
+- **Commits — pushed or not — or a PR that is not green.** Safe either way:
+  pushed work lives on the remote, and unpushed commits live on the run's branch
+  in the mirror, which a re-claim deliberately reattaches so the next worker
+  starts from them. Note what exists and release the label; the attempt counter
+  still bounds a loop of deaths.
+- **Genuinely nothing** (clean tree, no commits, no PR). Release the label and let
+  the next tick re-claim it clean.
+
+Never leave an orphan holding a slot "to be safe": a label nobody is working under
+is not safety, it is a deadlocked fleet that looks busy.
+
 ## Duty 2 — groom
 
 Keep the queue worth draining.
@@ -126,13 +160,32 @@ trigger an amendment:
 The protocol, in order:
 
 1. **Draft the exact replacement.** Quote the lines as they stand, then the lines
-   you propose. A diff, not a description of one.
-2. **Ask, once.** Send it as a single yes/no question over the escalation channel
-   (the `ask` tool — it reaches your operator's Telegram).
+   you propose. A diff, not a description of one. This full text is what you
+   *apply* on a yes — it is not what you send.
+2. **Ask, once — a single yes/no question, written for a phone.** It goes over
+   the escalation channel (the `ask` tool — it reaches your operator's Telegram),
+   and Telegram renders none of your markdown: asterisks and backticks arrive as
+   literal characters, and a pasted section becomes an unreadable wall. So:
+   - Lead with one plain sentence: what changes, and why, in your own words.
+   - Then show only the lines that actually change, compact, under two short
+     labels like "now:" and "proposed:". Never paste whole sections around a
+     two-line change.
+   - Keep the whole proposal readable on one phone screen. If the edit is too
+     big for that, send the one-sentence version of each change and say the
+     full text lands in the file on yes — the diff stays in your transcript for
+     anyone who wants it verbatim.
 3. **On yes, apply it** by editing this file yourself. On no, or on no answer at
    all, drop it and do not re-ask that amendment.
 4. **Log it.** Append one line to **Amendments** at the bottom of this file: the
    date, what triggered it, a one-sentence summary.
+5. **Offer general fixes upstream.** Ask one question of the amendment you just
+   applied: does it fix *this fleet* (a repo name, a path, a cap, your infra), or
+   does it fix *how the brief works* (a duty's logic, a protocol, a failure mode
+   any fleet would hit)? The second kind belongs in the shipped template, or
+   every other operator re-learns it the hard way. Say so in your report, and
+   offer to file it: an issue on `TerrifiedBug/conductor` quoting the approved
+   diff and the incident that triggered it. File it only when your operator says
+   yes — it is their name on the account.
 
 Two limits. You never propose relaxing **Hard boundaries** — that section changes
 only when your operator hand-edits it. And at most one proposal per tick: an

package/src/cli.ts

@@ -5,8 +5,13 @@
  * process lifecycle in ./lifecycle.ts, so the CLI and the `/conductor` plugin
  * cannot drift apart.
  */
+import { readFileSync } from "node:fs";
+import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
+import { findProject, loadConfig } from "./config.ts";
 import { formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
 import { healthCheck, livingDaemon, startDaemon, stopDaemon } from "./lifecycle.ts";
+import { briefPathForProject, renderBriefForProject, shippedBriefTemplate } from "./setup.ts";
+import type { ProjectConfig } from "./types.ts";
 
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
@@ -18,6 +23,7 @@ usage:
   omp-conductor daemon [--once] [--port N] [--project NAME]
   omp-conductor pause
   omp-conductor resume
+  omp-conductor brief-upgrade [--apply] [--file PATH] [--project NAME]
   omp-conductor help
 
   start    run the dispatch loop in the background and wait until it answers
@@ -32,6 +38,14 @@ usage:
            and exits. This is what \`start\` launches.
   pause    stop claiming new work. The running daemon notices on its next tick.
   resume   allow claiming again.
+  brief-upgrade
+           compare a project's ORCHESTRATOR.md against the brief this version of
+           the package ships. Reports by default; --apply replaces the half above
+           the YOURS TO EDIT banner and keeps everything below it, backing the old
+           file up first. --file checks a brief that is not where the wizard would
+           have put it, on a host that may have no config at all. Nothing is
+           written for a brief with no banner, or when no config resolved and the
+           template still carries its {{PLACEHOLDER}} coordinates.
   help     print this text (also --help, -h).
 
 Pause is a flag file under the state directory, so it applies to every project
@@ -159,6 +173,60 @@ try {
       process.stdout.write("resumed — work will be claimed on the next tick\n");
       break;
 
+    case "brief-upgrade": {
+      // `--file` exists because a real fleet's brief is often not where the wizard
+      // would have put it: the supervising session runs from its own directory, and
+      // that host may never have configured a dispatch daemon at all. Without this
+      // the command cannot check the one file it was written for.
+      const override = flag(argv, "file");
+      let project: ProjectConfig | undefined;
+      let path: string;
+      if (override === undefined) {
+        project = findProject(loadConfig(), flag(argv, "project"));
+        path = briefPathForProject(project);
+      } else {
+        path = override;
+        try {
+          project = findProject(loadConfig(), flag(argv, "project"));
+        } catch {
+          // No config here, or several projects and no name given. With an explicit
+          // file we need neither, and refusing would make the command unusable on a
+          // fleet host that runs only the supervising session.
+          project = undefined;
+        }
+      }
+
+      let live: string;
+      try {
+        live = readFileSync(path, "utf8");
+      } catch {
+        process.stderr.write(
+          `omp-conductor: no brief at ${path}` +
+            `${override === undefined ? " — run /conductor setup and say yes to writing ORCHESTRATOR.md." : "."}\n`,
+        );
+        process.exit(1);
+      }
+
+      // With no config there are no coordinates to substitute, so the template is
+      // compared raw. Headings carry no placeholders, so the section-level report is
+      // unaffected; the note below keeps the printed text honest.
+      const status = checkBrief(live, project === undefined ? shippedBriefTemplate() : renderBriefForProject(project));
+      // Report first, always: --apply on a brief with no banner must not be the
+      // command that silently discards an operator's hand-written policy.
+      process.stdout.write(`${formatBriefStatus(path, status)}\n`);
+      if (project === undefined) {
+        process.stdout.write(
+          "\nnote: no conductor config resolved on this host, so the template's\n" +
+            "{{PLACEHOLDER}} coordinates are unsubstituted. Section names are unaffected.\n",
+        );
+      }
+      if (argv.includes("--apply") && status.kind === "mergeable") {
+        const backup = writeMergedBrief(path, status.merged);
+        process.stdout.write(`\napplied — previous brief kept at ${backup}\n`);
+      }
+      break;
+    }
+
     case "help":
     case "--help":
     case "-h":

package/src/daemon.ts

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { configPath, findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { createEscalator } from "./escalate.ts";
+import { livingDaemon } from "./lifecycle.ts";
 import { startOrchestrator } from "./orchestrator.ts";
 import type { OrchestratorHandle } from "./orchestrator.ts";
 import { branchName, route } from "./routing.ts";
@@ -402,16 +403,18 @@ async function tick(d: Deps): Promise<void> {
     return;
   }
 
-  const active = store.activeRuns(project.name);
-  const slots = caps.maxConcurrentWorkers - active.length;
+  // Two different questions, deliberately two queries. Capacity counts worker
+  // *processes*, so a green PR awaiting a human merge must not consume a slot —
+  // two of those would otherwise stop the fleet. The busy set protects *issues*,
+  // so that same green PR must be in it, or a second attempt lands on a live PR.
+  const live = store.liveRuns(project.name);
+  const slots = caps.maxConcurrentWorkers - live.length;
   if (slots <= 0) {
-    log(`at capacity: ${active.length}/${caps.maxConcurrentWorkers} workers`);
+    log(`at capacity: ${live.length}/${caps.maxConcurrentWorkers} workers`);
     return;
   }
 
-  // activeRuns includes pushed-green work that is still waiting on a human
-  // merge, so this also stops a second attempt landing on a live PR.
-  const busy = new Set(active.map((r) => r.issue));
+  const busy = new Set(store.activeRuns(project.name).map((r) => r.issue));
 
   const admitted: { r: Routed; attempt: number }[] = [];
   for (const r of routed) {
@@ -453,7 +456,10 @@ export interface StatusSnapshot {
   stateDir: string;
   paused: boolean;
   caps: Caps;
+  /** Occupied issues: live workers plus green PRs awaiting a human merge. */
   activeRuns: RunRecord[];
+  /** Runs backed by a worker process — the number capacity compares against. */
+  liveWorkers: number;
   runsToday: number;
   spendTodayUsd: number;
 }
@@ -474,6 +480,7 @@ export function statusSnapshot(project?: string): StatusSnapshot {
       paused: isPaused(),
       caps: resolveCaps(p, cfg.defaults),
       activeRuns: store.activeRuns(p.name),
+      liveWorkers: store.liveRuns(p.name).length,
       runsToday: store.runsStartedSince(p.name, since),
       spendTodayUsd: store.spendSince(p.name, since),
     };
@@ -489,7 +496,7 @@ export function formatStatus(s: StatusSnapshot): string {
     `state     ${s.stateDir}`,
     "",
     "caps",
-    `  workers            ${s.activeRuns.length} / ${s.caps.maxConcurrentWorkers}`,
+    `  workers            ${s.liveWorkers} / ${s.caps.maxConcurrentWorkers}`,
     `  issues today       ${s.runsToday}`,
     `  spend today        $${s.spendTodayUsd.toFixed(2)} / $${s.caps.dailySpendUsd.toFixed(2)}`,
     `  worker max turns   ${s.caps.workerMaxTurns}`,
@@ -564,6 +571,38 @@ export function armConductor(): void {
   setPaused(false);
 }
 
+/**
+ * Settles the runs a previous daemon process left in flight.
+ *
+ * A `claimed` or `running` row is a promise that a worker exists in *some*
+ * process. This is called from a freshly started daemon, so when no other
+ * daemon is alive every such row is a worker that died with the previous
+ * process. Left "active", those rows deadlock admission forever: the slot
+ * count reads full while nothing runs, and the fleet looks busy doing nothing
+ * (found live, after a host restart killed two workers mid-run).
+ *
+ * Only the rows change. The issue keeps its in-progress label — that label is
+ * the crash guard against double-dispatch, and deciding what a dead worker's
+ * remains are worth (an open PR? unpushed commits? a dirty tree?) is the
+ * orchestrator's drain-duty judgement, not something to automate here. The
+ * rows also keep counting toward `maxAttemptsPerIssue`, so a loop of deaths
+ * still escalates instead of retrying forever.
+ *
+ * `pushed-green` rows are deliberately left alone: they hold no process — they
+ * are finished work waiting on a human merge, and they must keep occupying the
+ * issue so a second attempt cannot land on a live PR.
+ */
+export function reconcileOrphanedRuns(store: Store, project: string): RunRecord[] {
+  // Live runs only: `pushed-green` holds no process, so it cannot be orphaned by
+  // a process dying — it is finished work waiting on a human merge.
+  const stale = store.liveRuns(project);
+  const endedAt = Date.now();
+  for (const r of stale) {
+    store.updateRun(r.id, { state: "orphaned", endedAt });
+  }
+  return stale;
+}
+
 // ------------------------------------------------------------------- the daemon
 
 export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
@@ -573,6 +612,21 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   const store = openStore(dbPath());
   const tracker = makeTracker(project);
 
+  // Before the first tick, settle what the last process left behind — unless
+  // another daemon is alive (a foreground `daemon --once` beside a running
+  // daemon must not orphan that daemon's real, live workers).
+  const alive = livingDaemon();
+  if (alive === undefined || alive.pid === process.pid) {
+    for (const r of reconcileOrphanedRuns(store, project.name)) {
+      log(
+        `#${r.issue} orphaned by a previous daemon (attempt ${r.attempt}, was ${r.state}, worktree ${r.worktree}) — ` +
+          `slot freed; the ${project.stateLabels.inProgress} label stays until the orchestrator triages what the worker left`,
+      );
+    }
+  } else {
+    log(`skipping orphan reconciliation: daemon pid ${alive.pid} is alive and owns the active runs`);
+  }
+
   // Standing orders. The orchestrator holds none of this file's context, so
   // everything it needs to act — which tracker, which labels, what the fleet
   // does — has to be said once, in words.

package/src/plugin.ts

@@ -10,8 +10,9 @@
  * tested; this file turns answers into questions and back again. The invariant
  * worth protecting is on `setup()` below — nothing is written before the confirm.
  */
-import { existsSync } from "node:fs";
-import { configPath, loadConfig, saveConfig } from "./config.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
+import { configPath, findProject, loadConfig, saveConfig } from "./config.ts";
 import {
   armConductor,
   formatStatus,
@@ -25,12 +26,14 @@ import {
   ORCHESTRATOR_BRIEF_NAME,
   REPORT_SCOPE_CHOICES,
   SETUP_DEFAULTS,
+  briefPathForProject,
   buildConfig,
   checkTokenScopes,
   createMissingLabels,
   detectTelegram,
   orchestratorBriefPath,
   planLabels,
+  renderBriefForProject,
   summarisePlan,
   writeOrchestratorBrief,
   type SetupAnswers,
@@ -100,13 +103,19 @@ const SUBCOMMANDS: Completion[] = [
   { value: "status", label: "status", description: "pause state, caps, active runs, today's usage" },
   { value: "pause", label: "pause", description: "stop claiming new work" },
   { value: "resume", label: "resume", description: "allow claiming again" },
+  {
+    value: "brief-upgrade",
+    label: "brief-upgrade",
+    description: "check ORCHESTRATOR.md against the brief this version ships",
+  },
 ];
 
 const USAGE = [
-  "/conductor setup [project]   create or update a project, then arm after you confirm",
-  "/conductor status [project]  pause state, caps, active runs, today's usage",
-  "/conductor pause             stop claiming new work",
-  "/conductor resume            allow claiming again",
+  "/conductor setup [project]         create or update a project, then arm after you confirm",
+  "/conductor status [project]        pause state, caps, active runs, today's usage",
+  "/conductor pause                   stop claiming new work",
+  "/conductor resume                  allow claiming again",
+  "/conductor brief-upgrade [project] check ORCHESTRATOR.md against the shipped brief",
 ].join("\n");
 
 /**
@@ -588,6 +597,34 @@ export default function conductorPlugin(pi: PluginApi): void {
             ctx.ui.notify("Conductor resumed — work will be claimed on the next tick.", "info");
             break;
 
+          case "brief-upgrade": {
+            const p = findProject(loadConfig(), project);
+            const path = briefPathForProject(p);
+            if (!existsSync(path)) {
+              ctx.ui.notify(
+                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME}.`,
+                "warning",
+              );
+              break;
+            }
+            const status = checkBrief(readFileSync(path, "utf8"), renderBriefForProject(p));
+            ctx.ui.notify(formatBriefStatus(path, status), status.kind === "current" ? "info" : "warning");
+            // Confirmed here rather than applied on sight: this file is a standing
+            // prompt the operator may have spent an hour on, so the diff they just
+            // read is the thing they are agreeing to.
+            if (status.kind === "mergeable") {
+              const apply = await ctx.ui.confirm(
+                "Upgrade the brief?",
+                "Replace the half above the YOURS TO EDIT banner with the one this version ships? Everything below the banner is kept exactly as it is, and the current file is backed up first.",
+              );
+              if (apply) {
+                const backup = writeMergedBrief(path, status.merged);
+                ctx.ui.notify(`Brief upgraded. Previous version kept at ${backup}.`, "info");
+              }
+            }
+            break;
+          }
+
           default:
             ctx.ui.notify(
               `${sub ? `Unknown subcommand "${sub}".` : "Pick a subcommand."}\n\n${USAGE}` +

package/src/setup.ts

@@ -27,6 +27,7 @@ import { configPath, resolveCaps, stateDir } from "./config.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_CAPS,
+  DEFAULT_REPORT_SCOPE,
   type Caps,
   type ConductorConfig,
   type ProjectConfig,
@@ -392,31 +393,55 @@ export function buildConfig(a: SetupAnswers, existing?: ConductorConfig): Conduc
 }
 
 /**
- * Where the operator's own brief lands: beside the worktrees, under the state
+ * Where a configured project's brief lives: beside its worktrees, under the state
  * directory, so it is on the same disk the fleet already owns and survives a
- * reinstall of the package. Derived from the answers rather than fixed, so a
+ * reinstall of the package. Derived from the project rather than fixed, so a
  * project that ever gains a chosen workspace root keeps its brief with it.
  */
-export function orchestratorBriefPath(a: SetupAnswers): string {
-  return join(buildProject(a).workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
+export function briefPathForProject(p: ProjectConfig): string {
+  return join(p.workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
 }
 
 /**
- * The shipped template with this project's real values in it.
+ * The brief template exactly as shipped, placeholders and all.
+ *
+ * Exported for the upgrade check, which has to be able to read the shipped text
+ * on a host that has no config to render it against.
+ */
+export function shippedBriefTemplate(): string {
+  return readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * The shipped template with a configured project's real values in it.
  *
  * Only the coordinates and the chosen scope are substituted: the policy text is
  * left exactly as shipped, because from here on the file is the operator's to
  * edit and nothing in this package reads it back.
+ *
+ * Takes a `ProjectConfig` rather than answers so that a *later* upgrade check can
+ * reproduce the same render from what is on disk, months after the wizard's
+ * answers are gone.
  */
-export function renderOrchestratorBrief(a: SetupAnswers): string {
+export function renderBriefForProject(p: ProjectConfig): string {
   return renderBrief(readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8"), {
-    PROJECT: a.projectName,
-    TRACKER_REPO: a.trackerRepo,
-    QUEUE_LABEL: a.queueLabel,
-    REPORT_SCOPE: a.reportScope,
+    PROJECT: p.name,
+    TRACKER_REPO: p.tracker.repo,
+    QUEUE_LABEL: p.queueLabel,
+    REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
   });
 }
 
+/** Wizard-time path, via the project the answers describe. */
+export function orchestratorBriefPath(a: SetupAnswers): string {
+  return briefPathForProject(buildProject(a));
+}
+
+/** Wizard-time render, via the project the answers describe. */
+export function renderOrchestratorBrief(a: SetupAnswers): string {
+  return renderBriefForProject(buildProject(a));
+}
+
 /**
  * Writes the rendered brief and returns where it went.
  *

package/src/store.ts

@@ -16,12 +16,21 @@ import { dirname } from "node:path";
 import type { RunRecord, RunState, Store } from "./types.ts";
 
 /**
- * States that consume a worker slot. `pushed-green` counts: the branch is
- * pushed and CI is green but nothing is merged, so the worktree, the branch
- * and the issue claim are all still held.
+ * States backed by a worker process. These are what worker capacity counts:
+ * a slot is a process, and only a claimed or running attempt has one.
  */
-const ACTIVE_STATES: readonly RunState[] = ["claimed", "running", "pushed-green"];
+const LIVE_STATES: readonly RunState[] = ["claimed", "running"];
 
+/**
+ * States that keep an *issue* occupied. `pushed-green` belongs here but not in
+ * {@link LIVE_STATES}: its worker is finished and its worktree already removed,
+ * so it must not consume a slot — two green PRs awaiting a human merge would
+ * otherwise stop the whole fleet — but its issue has a live PR that a second
+ * attempt must not land on.
+ */
+const ACTIVE_STATES: readonly RunState[] = [...LIVE_STATES, "pushed-green"];
+
+const LIVE_PLACEHOLDERS = LIVE_STATES.map(() => "?").join(", ");
 const ACTIVE_PLACEHOLDERS = ACTIVE_STATES.map(() => "?").join(", ");
 
 /**
@@ -165,6 +174,11 @@ export function openStore(dbPath: string): Store {
       WHERE project = ? AND state IN (${ACTIVE_PLACEHOLDERS})
       ORDER BY startedAt ASC`,
   );
+  const selectLive = db.query<RunRow, SqlValue[]>(
+    `SELECT * FROM runs
+      WHERE project = ? AND state IN (${LIVE_PLACEHOLDERS})
+      ORDER BY startedAt ASC`,
+  );
   const countAttempts = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs WHERE project = ? AND issue = ?`,
   );
@@ -233,6 +247,10 @@ export function openStore(dbPath: string): Store {
       return selectActive.all(project, ...ACTIVE_STATES).map(toRecord);
     },
 
+    liveRuns(project: string): RunRecord[] {
+      return selectLive.all(project, ...LIVE_STATES).map(toRecord);
+    },
+
     attemptsFor(project: string, issue: number): number {
       return countAttempts.get(project, issue)?.n ?? 0;
     },

package/src/types.ts

@@ -170,7 +170,9 @@ export type RunState =
   | "merged"
   | "blocked"
   | "failed"
-  | "killed";
+  | "killed"
+  /** In flight when its daemon process died; reconciled at the next startup. */
+  | "orphaned";
 
 /**
  * One attempt at one issue. Persisted so a daemon restart can reconcile
@@ -207,7 +209,10 @@ export interface Store {
   createRun(r: Omit<RunRecord, "id">): RunRecord;
   updateRun(id: string, patch: Partial<RunRecord>): void;
   getRun(id: string): RunRecord | undefined;
+  /** Runs whose issue is occupied: a live worker, or a green PR awaiting merge. */
   activeRuns(project: string): RunRecord[];
+  /** Runs backed by a worker process — what capacity counts. Subset of {@link Store.activeRuns}. */
+  liveRuns(project: string): RunRecord[];
   attemptsFor(project: string, issue: number): number;
   runsStartedSince(project: string, sinceEpochMs: number): number;
   spendSince(project: string, sinceEpochMs: number): number;