omp-conductor 0.15.13 → 0.16.0

package/src/ask.ts

@@ -46,6 +46,26 @@ export const MIN_ASK_TIMEOUT_SECONDS = 60;
 export const MAX_ASK_TIMEOUT_SECONDS = 3_600;
 export const DEFAULT_ASK_TIMEOUT_SECONDS = 300;
 
+/**
+ * The shape ceilings for a decision row's question (#593). A question is the
+ * bare ask an operator reads on a phone — one sentence, the recommendation, the
+ * options — not an essay. On 2026-08-17 three rows opened at 41/22/26 lines and
+ * 2,043/1,168/1,392 characters each, embedding their measurements, timeline and
+ * rationale inline; every one was accepted and every one rendered in full. The
+ * walls are set so a genuine four-option ask fits and an essay does not: the
+ * measured detail belongs in the issue or a separate backdrop, never inline.
+ */
+export const MAX_QUESTION_LINES = 10;
+export const MAX_QUESTION_CHARACTERS = 700;
+
+/**
+ * The result of {@link validateQuestionShape}: fine, or refused with a problem
+ * that names the measured counts and where the overflow belongs.
+ */
+export type QuestionShape =
+  | { ok: true }
+  | { ok: false; problem: string };
+
 /**
  * The suffix a decision row carries when nobody human chose the answer. Fixed
  * wording on purpose — the same reason `types.ts` gives for closed vocabularies
@@ -89,6 +109,29 @@ function isInterruptCategory(value: unknown): value is InterruptCategory {
   return typeof value === "string" && (INTERRUPT_CATEGORIES as readonly string[]).includes(value);
 }
 
+/**
+ * Refuse a question that outgrew the phone-sized decision row. Counts the
+ * trimmed question — the exact text archived on the row — against
+ * {@link MAX_QUESTION_LINES} / {@link MAX_QUESTION_CHARACTERS}, and refuses
+ * rather than truncating: a truncated question reads as complete and has lost
+ * its options, which is strictly worse than a rejection the caller must fix.
+ */
+export function validateQuestionShape(question: string): QuestionShape {
+  const lines = question.split("\n").length;
+  const chars = question.length;
+  if (lines <= MAX_QUESTION_LINES && chars <= MAX_QUESTION_CHARACTERS) {
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    problem:
+      `the question is ${lines} lines / ${chars} characters — over the ${MAX_QUESTION_LINES}-line / ` +
+      `${MAX_QUESTION_CHARACTERS}-character ceiling. Trim it to the bare question the operator must answer; ` +
+      `the measurements and rationale belong in the issue, or as a separate rationale recorded with ` +
+      "`omp-conductor event record`, never inline in the question",
+  };
+}
+
 /**
  * Validate one raw tool call. Strict like the verb arguments: an unknown shape
  * is refused with the reason, never coerced into a default that could hide what
@@ -106,6 +149,10 @@ export function parseAskRequest(raw: unknown): AskParse {
   if (typeof question !== "string" || question.trim().length === 0) {
     return { ok: false, problem: `conductor_ask needs "question": the question you put to the operator` };
   }
+  const shape = validateQuestionShape(question.trim());
+  if (!shape.ok) {
+    return { ok: false, problem: `conductor_ask ${shape.problem}` };
+  }
 
   const onTimeoutRaw = input["on-timeout"];
   if (

package/src/backups.ts

@@ -22,17 +22,21 @@ export function backupTimestamp(): string {
   return new Date().toISOString().replace(/[:.]/g, "-");
 }
 
-/** Publishes `source` under `backupRoot` as `stem`, suffixing on collision. */
-export function copyToUniqueBackup(source: string, backupRoot: string, stem: string): string {
-  mkdirSync(backupRoot, { recursive: true });
-  const temporary = join(backupRoot, `.${stem}.${process.pid}.${randomUUID()}.tmp`);
-  copyFileSync(source, temporary, constants.COPYFILE_EXCL);
+/**
+ * Atomically publish a complete temp file as `stem` under `backupRoot`,
+ * suffixing on collision, then remove the temp. Linking a complete file
+ * publishes without ever overwriting a backup created concurrently at the
+ * same millisecond, and it stays on one filesystem because the temp lives in
+ * the same directory as the destination.
+ *
+ * Shared by {@link copyToUniqueBackup} and the store snapshot path, so every
+ * durable copy under state uses the same temp-then-atomic-publish convention.
+ */
+export function publishTempFile(temporary: string, backupRoot: string, stem: string): string {
   try {
     for (let suffix = 0; ; suffix += 1) {
       const destination = join(backupRoot, suffix === 0 ? stem : `${stem}-${suffix}`);
       try {
-        // Linking a complete temp file publishes the backup atomically without
-        // overwriting a backup created concurrently at the same millisecond.
         linkSync(temporary, destination);
         return destination;
       } catch (err) {
@@ -44,3 +48,11 @@ export function copyToUniqueBackup(source: string, backupRoot: string, stem: str
     unlinkSync(temporary);
   }
 }
+
+/** Publishes `source` under `backupRoot` as `stem`, suffixing on collision. */
+export function copyToUniqueBackup(source: string, backupRoot: string, stem: string): string {
+  mkdirSync(backupRoot, { recursive: true });
+  const temporary = join(backupRoot, `.${stem}.${process.pid}.${randomUUID()}.tmp`);
+  copyFileSync(source, temporary, constants.COPYFILE_EXCL);
+  return publishTempFile(temporary, backupRoot, stem);
+}

package/src/board.ts

@@ -9,9 +9,8 @@ import {
   fleetLayers,
   probeTelegramHealth,
   workerPhasesFromHealthz,
-  type FleetLayers,
-  type TelegramHealth,
 } from "./fleet.ts";
+import type { FleetLayers, TelegramHealth } from "./status-render.ts";
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { healthCheck, livingDaemon } from "./lifecycle.ts";
 import type { WorkerPausePhase } from "./worker.ts";

package/src/briefs/orchestrator.md

@@ -193,6 +193,38 @@ Keep the queue worth draining.
   the one issue whose defect had been traced first landed in 92 of 120 turns.
   Tracing before promoting is your work, once — or it is every worker's work,
   every attempt.
+- **Size every promotion to one budget: 180 turns and 90 minutes of wall clock
+  per attempt — the caps this fleet enforces, not adjectives.** Work that cannot
+  fit in one budget is not one issue: split it before you promote it. "Prefer
+  small slices" is a taste, and taste did not govern 2026-08-16 — #486 hit the
+  cap twice (181/180, then 168/180) before landing, #541 settled at 170/180,
+  #288 was killed at 181/180, and #365 burned the full 90-minute clock. None
+  were worker failures; each was a slice too big when it was promoted,
+  discovered only by spending an attempt.
+- **A cap kill is a size verdict, not a worker verdict — so a second cap kill
+  on one issue is a decomposition defect, not an implementation defect.** The
+  failure classifier already records this signal (#490, #494): a run killed at
+  its ceilings is written `turn-cap-*` or `wall-clock-cap-*`. On the **second**
+  cap kill, decompose, do not re-queue: keep the work the attempts shipped,
+  split the remainder into issues that each fit one budget, and promote those
+  slices. A fresh attempt at the same uncut issue is how a third budget gets
+  spent proving what the second one already proved.
+- **A decomposition has a required output.** When an issue is too big for one
+  budget, do not re-file it smaller and hope. Produce an epic plus children, and
+  give every child, in its body: the files it writes, its acceptance criteria,
+  the one thing most likely to be silently faked, and the commands that prove
+  it. A child missing any of those is not a slice, it is the same issue with a
+  smaller title.
+- **Record the decomposition on the parent, not in a chat turn.** The parent
+  carries the child list, the order they must land in, and one sentence per
+  child saying why it is a separate slice — a shared file lane, a dependency,
+  an operator decision that is still open. That note is what stops the next
+  reader re-litigating a split you already reasoned through, and what tells you
+  which child is claimable now.
+- **Sequence explicitly.** Children that write the same file are one lane and
+  go in order; say so on the parent. A child blocked on an unbuilt capability
+  is named as blocked, with what unblocks it — never promoted in the hope that
+  the capability appears.
 - An issue that has exhausted its attempts is not a retry candidate. Diagnose it,
   split it, or hand it back to a human.
 - **Grooming is throughput-bound, so delegate the finding.** N workers drain the
@@ -458,12 +490,15 @@ Not yours to relax:
 **You never sleep, poll, or wait inside a tick.** No `sleep`, no retry loop, no
 "watch this PR until green" — a tool call that exists to pass time is a tool
 call that blocks your operator's messages. Anything that needs waiting for is
-either a watch (`decision open --resolves-when pr-checks-green:<url>`,
+either a watch (`watch add --resolves-when pr-checks-green:<url>`,
 `pr-mergeable:<url>`, `pr-merged:<url>`, `issue-closed:<n>`,
 `npm-version:<pkg>@<version>`, `rate-limit-reset:github`) or a subagent's
 problem. The harness refuses further tool calls once a turn exceeds its budget
 or an operator message is queued — end the turn and let the next tick act on
-`[CONDITION MET]`.
+`[CONDITION MET]`. A watch is yours alone: it renders under its own "Watches"
+heading, is never offered to your operator to resolve, and has no seven-day
+expiry — so use it for anything you set for yourself, never for a question that
+actually needs an answer.
 
 ## Your verb surface
 
@@ -497,7 +532,7 @@ to land that exact head, then cut the tag.
 | --- | --- | --- |
 | `conductor_pr_status` | always | Nothing to gate: it reads. |
 | `conductor_pr_update_branch` | always | The PR belongs to this project and is open. |
-| `conductor_pr_merge` | `authority.merge` is yours | You are the configured holder; `headSha` still equals the live head *at execution time*; checks green at that same SHA; the project's single merge slot is free. |
+| `conductor_pr_merge` | `authority.merge` is yours | You are the configured holder; `headSha` still equals the live head *at execution time*; checks green at that same SHA; the repo's base is not red-frozen (`base-red-freeze`); the project's single merge slot is free. |
 | `conductor_label` | always | The label is one this project declared. Lifecycle labels (`agent:in-progress`, `agent:blocked`, `agent:failed`) are refused — those stay the dispatcher's, and `omp-conductor unblock` is how you clear them. |
 | `conductor_release` | `authority.release` is yours | You are the configured holder, the shape is granted, the artefact or environment was declared, and the release preconditions hold. `version-bump-pr` is the source-change exception: first call opens only the declared version-file change; a later call re-validates and merges its exact green head through the project's single merge slot. |
 
@@ -524,6 +559,12 @@ Four controls stop different work:
   it needs stopping rather than to run this yourself.
 - **Orchestrator ticks:** `omp-conductor disarm` removes the operator-owned
   `ARMED` marker so ticks skip. It does not pause workers or stop processes.
+- **Lift a base-red freeze:** `omp-conductor unfreeze <repo>` is the operator's
+  sanctioned override for the `base-red-freeze` merge gate — use it only after
+  you judge the base repaired (or the merge warranted anyway). It is
+  ledger-recorded and re-arms automatically if the base is still red. Never
+  bypass a `base-red-freeze` refusal with label surgery or a DB edit; this verb
+  is the one allowed path.
 
 Per-worker pause is not SIGSTOP/SIGCONT, fleet pause, unblock/requeue, or a
 durable restart boundary. Daemon loss still follows the normal salvage and
@@ -547,6 +588,18 @@ to read the refusal instead of retrying in a loop.
 the SHA that produced it. Never work around one: there is no path around it, and
 the attempt is in the ledger.
 
+**A red base freezes merges to that repo (`base-red-freeze`).** When a watched
+merge turns the base branch red, the daemon freezes `conductor_pr_merge` for
+that repo until the base is observed green again — so the next merge cannot land
+on top of a broken base and compound it. The refusal names the suspected culprit
+merge SHA and suggests the revert. Only the frozen repo is gated: sibling repos
+keep merging, and a frozen repo's candidates keep dispatching (workers can still
+build the fix); only merge is held. The freeze lifts by itself on a green
+re-observation, or the operator can lift it early with the sanctioned
+`omp-conductor unfreeze <repo>` — the one allowed path, never label surgery or a
+DB edit, and ledger-recorded. Opening the revert PR stays yours: the daemon only
+freezes and attributes.
+
 **Your file tools are not gated — the workers' are.** Every worker session runs
 under a mechanical worktree gate. Your structured tools are gated by nothing,
 and that is a deliberate operator decision rather than an oversight. What holds
@@ -652,7 +705,12 @@ observable happens: `pr-merged:<url>`, `pr-checks-green:<url>`,
 `pr-mergeable:<url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`,
 `rate-limit-reset:github`. The daemon checks it for you and flags the row as
 `[CONDITION MET — act on this now]` in your tick digest, so a parked question
-wakes up on its own instead of waiting for you to think of it.
+wakes up on its own instead of waiting for you to think of it. A condition
+governs *when* to ask, not *who* answers: a question stays a question under
+`decision open` even when it carries one. Anything you set for yourself — a
+condition you are waiting on, or an instruction the next tick should read — is
+a watch, not a question: open it with `watch add ...` so it renders under
+"Watches" and is never mistaken for an ask aimed at your operator.
 
 **Trust the digest, never your recollection.** Every tick's prompt lists what is
 still open. A question that exists only in your context is gone at the next

package/src/cli.ts

@@ -29,6 +29,7 @@ import { ledgerCommand } from "./commands/ledger.ts";
 import { messageCommand } from "./commands/message.ts";
 import { reportCommand } from "./commands/report.ts";
 import { restartCommand } from "./commands/restart.ts";
+import { restoreDbCommand } from "./commands/restore-db.ts";
 import { resumeCommand } from "./commands/resume.ts";
 import { setupCommand } from "./commands/setup.ts";
 import { startCommand } from "./commands/start.ts";
@@ -37,11 +38,13 @@ import { statusCommand } from "./commands/status.ts";
 import { stopCommand } from "./commands/stop.ts";
 import { tailCommand } from "./commands/tail.ts";
 import { unblockCommand } from "./commands/unblock.ts";
+import { unfreezeCommand } from "./commands/unfreeze.ts";
 import { upgradeInstallCommand } from "./commands/upgrade-install.ts";
 import { upgradeRollbackCommand } from "./commands/upgrade-rollback.ts";
 import { upgradeCommand } from "./commands/upgrade.ts";
 import { verbCommand } from "./commands/verb.ts";
 import { versionCommand } from "./commands/version.ts";
+import { watchCommand } from "./commands/watch.ts";
 import { workerCommand } from "./commands/worker.ts";
 import {
   COMMAND_SCOPES,
@@ -66,6 +69,7 @@ usage:
   omp-conductor status [--project NAME]
   omp-conductor stats [--since 7d|30d|YYYY-MM-DD] [--project NAME] [--json]
   omp-conductor doctor [--project NAME] [--json] [--probe-telegram]
+  omp-conductor restore-db [SNAPSHOT]
   omp-conductor ledger [--issue N] [--limit N] [--project NAME]
   omp-conductor hold [--keep-ticks] [--project NAME | --all]
   omp-conductor arm [--project NAME | --all]
@@ -76,6 +80,7 @@ usage:
   omp-conductor worker resume <issue> [--project NAME]
   omp-conductor worker stop <issue> --reason TEXT [--project NAME]
   omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
+  omp-conductor unfreeze <repo> [--reason TEXT] [--project NAME]
   omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
   omp-conductor daemon [--once] [--port N] [--project NAME]
   omp-conductor resume [--project NAME | --all]
@@ -88,6 +93,8 @@ usage:
   omp-conductor decision resolve <id> --answer TEXT [--project NAME]
   omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
   omp-conductor decision list [--project NAME]
+  omp-conductor watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
+  omp-conductor watch list [--project NAME]
   omp-conductor intake "<text>" [--project NAME]
   omp-conductor intake list [--project NAME]
   omp-conductor intake dismiss <id> [--project NAME]
@@ -154,6 +161,12 @@ usage:
            --probe-telegram sends through the report transport. Exit code 0
            only when nothing failed; --json prints the stable CI shape. Run
            it after install and after every upgrade.
+  restore-db
+           put conductor.db back to a restorable snapshot, replacing the live
+           file and dropping stale -wal/-shm sidecars. Refuses while a daemon
+           is live — restoring under a running daemon is a corruption path.
+           The default source is the newest snapshot in the configured db
+           backup directory; an explicit snapshot path overrides it.
   board    open the live keyboard-driven fleet board. It renders queue holds,
            every run lifecycle stage, recent merges, spend and health; Enter
            follows a selected transcript without leaving the board. --json (or
@@ -248,6 +261,16 @@ usage:
              decision resolve <id> --answer TEXT
              decision withdraw <id> [--reason TEXT]
              decision list
+  watch    set a condition or carry note for the orchestrator itself, with no
+           human in the loop — the same no-sleep surface \`decision open
+           --resolves-when\` used to serve, given its own verb so it never renders
+           as a question put to the operator. \`--resolves-when\` attaches a
+           condition the daemon checks for you; a met watch wakes the next tick
+           with its note, exactly as a met question does, but it is listed under
+           its own heading and never under "Open operator decisions", and it has
+           no seven-day expiry. \`watch list\` shows open watches.
+             watch add --note TEXT [--blocks TEXT] [--resolves-when COND]
+             watch list
   intake   keep a raw idea durably before it becomes anything: record it now
            with \`omp-conductor intake "<text>"\`, list what is still pending,
            dismiss what turned out to be nothing. Backed by the sqlite store,
@@ -469,13 +492,16 @@ const COMMANDS: Record<string, CommandHandler> = {
   extend: () => extendCommand(ctx),
   worker: () => workerCommand(ctx),
   unblock: () => unblockCommand(ctx),
+  unfreeze: () => unfreezeCommand(ctx),
   verb: () => verbCommand(ctx),
   event: () => eventCommand(ctx),
   report: () => reportCommand(ctx),
   message: () => messageCommand(ctx),
   decision: () => decisionCommand(ctx),
+  watch: () => watchCommand(ctx),
   intake: () => intakeCommand(ctx),
   friction: () => frictionCommand(ctx),
+  "restore-db": () => restoreDbCommand(ctx),
   resume: () => resumeCommand(ctx),
   "brief-upgrade": () => briefUpgradeCommand(ctx),
   help: () => helpCommand(USAGE),

package/src/commands/context.ts

@@ -93,11 +93,14 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   stats: "project",
   tail: "project",
   unblock: "project",
+  unfreeze: "project",
   verb: "project",
+  watch: "project",
   worker: "project",
   // host — the shared daemon/package surfaces; never resolves a project
   daemon: "host",
   restart: "host",
+  "restore-db": "host",
   start: "host",
   upgrade: "host",
   "upgrade-install": "host",

package/src/commands/decision.ts

@@ -10,6 +10,7 @@ import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
 import { dbPath, openStore } from "../store.ts";
+import { validateQuestionShape } from "../ask.ts";
 
 export async function decisionCommand(ctx: CommandContext): Promise<void> {
 const sub = ctx.argv[1];
@@ -24,6 +25,11 @@ try {
       );
       process.exit(2);
     }
+    const shape = validateQuestionShape(question);
+    if (!shape.ok) {
+      process.stderr.write(`omp-conductor: decision open: ${shape.problem}\n`);
+      process.exit(2);
+    }
     const condition = ctx.flag("resolves-when")?.trim();
     if (condition !== undefined && parseCondition(condition) === undefined) {
       process.stderr.write(
@@ -76,7 +82,10 @@ try {
   }
 
   if (sub === "list" || sub === undefined) {
-    const open = store.openDecisions(project.name);
+    // Only rows a human must answer. Watches would render identically here and
+    // were the whole reason an operator read the orchestrator's own reminder as
+    // a question aimed at them (#459) — `watch list` shows those.
+    const open = store.openDecisions(project.name).filter((d) => d.kind !== "watch");
     if (open.length === 0) {
       process.stdout.write("no open decisions\n");
       return;

package/src/commands/doctor.ts

@@ -34,6 +34,8 @@ Checks, each one the mechanical version of a past production incident:
   spend telemetry every completed run recording $0.00 means the USD cap cannot
                   fire — $0.00 is not proof of no spend
   timezone        reporting timezones are known IANA zones
+  omp settings    the effective omp settings overlay each project's workers
+                  load, and whether it can be materialised under the session root
   telegram        bot health, and one self-identified probe message
 
 flags:

package/src/commands/message.ts

@@ -19,6 +19,7 @@ import { findProject, loadConfig } from "../config.ts";
 import { deliverOperatorMessage, operatorMessageCategory, type OperatorMessageOutcome } from "../reports.ts";
 import { dbPath, openStore } from "../store.ts";
 import { INTERRUPT_CATEGORIES, type DecisionRecord, type InterruptCategory } from "../types.ts";
+import { validateQuestionShape } from "../ask.ts";
 
 /** The floor's "this needs an answer" marker, as every other classifier reads it. */
 const QUESTION_MARKER = /^\s*QUESTION:\s/i;
@@ -56,10 +57,16 @@ export async function messageCommand(ctx: CommandContext): Promise<void> {
   let outcome: OperatorMessageOutcome;
   try {
     if (isAsk) {
+      const question = body.replace(QUESTION_MARKER, "").trim();
+      const shape = validateQuestionShape(question);
+      if (!shape.ok) {
+        process.stderr.write(`omp-conductor: message: ${shape.problem}\n`);
+        process.exit(2);
+      }
       row = store.createDecision({
         project: project.name,
         // The row archives the question, not the delivery prefix.
-        question: body.replace(QUESTION_MARKER, "").trim(),
+        question,
         ...(blocks === undefined ? {} : { blocks }),
         at: Date.now(),
       });

package/src/commands/restart.ts

@@ -7,7 +7,7 @@
  */
 
 import type { CommandContext } from "./context.ts";
-import { buildStopProvenance } from "../stop-provenance.ts";
+import { buildStopProvenance, liveWorkload, refuseBusyDaemon } from "../stop-provenance.ts";
 import { setPaused } from "../daemon.ts";
 import { restartDaemon, type RestartResult, type StopDelivery } from "../lifecycle.ts";
 import { openStore, dbPath } from "../store.ts";
@@ -16,12 +16,24 @@ import { DEFAULT_DEPS, drainAndRestart, type UpgradeDeps } from "../upgrade.ts";
 export async function restartCommand(ctx: CommandContext): Promise<void> {
 const store = openStore(dbPath());
 try {
+  const forced = ctx.argv.includes("--force");
+  // Refusal (#545), the immediate path only. `restart --now` skips the drain
+  // and replaces the running daemon at once, so it orphans any project's live
+  // workers exactly like `stop`. The default restart is safe rather than
+  // refused: it pauses and drains EVERY configured project before restarting
+  // (resolveScope selects them all, #389), so it cannot orphan a sibling.
+  // `--force` skips the gate — a wedged daemon stays restartable — and the
+  // override is recorded in the provenance.
+  if (ctx.argv.includes("--now") && !forced) {
+    refuseBusyDaemon(liveWorkload(store), { override: false, verb: "restart" });
+  }
   // Provenance (#378): one record naming the request, every configured
   // project with its live-run count, and — via the lifecycle chokepoint — the
   // delivery method used. The shared daemon serves all projects, so a restart
-  // is never silent even when the operator narrows nothing.
+  // is never silent even when the operator narrows nothing. A forced restart
+  // keeps the override visible in the control path, never silent.
   const provenance = buildStopProvenance({
-    controlPath: "cli restart",
+    controlPath: forced ? "cli restart --force" : "cli restart",
     reason: "operator restart",
     scope: "global",
   });

package/src/commands/restore-db.ts

@@ -0,0 +1,146 @@
+/**
+ * `restore-db` — put `conductor.db` back to a restorable snapshot.
+ *
+ * The store is the verb ledger, the decision rows, the run rows and the
+ * material-event ledger (#579); a restore replaces the live file wholesale
+ * from a snapshot the snapshot primitive produced. It refuses to run while a
+ * daemon is live — overwriting the store a live dispatch loop is writing is a
+ * corruption path, and `livingDaemon()` is the existing detect for it — and
+ * replaces the file atomically (temp file in the same directory, then rename),
+ * then drops any stale `-wal`/`-shm` sidecars so the restored database opens
+ * cleanly. The pre-restore `conductor.db-wal`/`-shm` are gone by design: the
+ * old WAL belongs to the file being replaced.
+ */
+
+import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import type { CommandContext } from "./context.ts";
+import { dbBackupDirFor, loadConfig, stateDir } from "../config.ts";
+import { livingDaemon } from "../lifecycle.ts";
+import { DB_SNAPSHOT_STEM, dbPath } from "../store.ts";
+
+const RESTORE_DB_USAGE = `omp-conductor restore-db [SNAPSHOT]
+
+Put conductor.db back to a restorable snapshot, replacing the live file
+wholesale and dropping stale -wal/-shm sidecars so the result opens cleanly.
+
+Refuses to run while a daemon is live — restoring under a running daemon is a
+corruption path, not an interruption. Stop the daemon first
+(\`omp-conductor stop\`).
+
+usage:
+  omp-conductor restore-db               restore the newest snapshot in the
+                                         configured db backup directory
+  omp-conductor restore-db PATH          restore this exact snapshot file
+
+SNAPSHOT is a file the store snapshot primitive produced. A relative PATH is
+resolved against the working directory.
+
+Before restoring, the command verifies the restored database reads cleanly
+(PRAGMA integrity_check) and prints the verb_ledger / decisions / runs counts.`;
+
+/**
+ * The newest snapshot already published under `dir`, by mtime — the default
+ * restore source. Undefined when none exists (a fresh store with no snapshot).
+ */
+function newestSnapshot(dir: string): string | undefined {
+  let names: string[];
+  try {
+    names = readdirSync(dir).filter((name) => name.startsWith(DB_SNAPSHOT_STEM));
+  } catch {
+    return undefined;
+  }
+  if (names.length === 0) return undefined;
+  const withMtime = names
+    .map((name) => ({ name, mtime: statSync(join(dir, name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return join(dir, withMtime[0]!.name);
+}
+
+/** Replace `conductor.db` with `snapshot`, atomically, dropping stale sidecars. */
+function overwriteStoreFrom(snapshot: string): void {
+  const target = dbPath();
+  const temporary = join(stateDir(), `.${DB_SNAPSHOT_STEM}-restore.${process.pid}.${randomUUID()}.tmp`);
+  copyFileSync(snapshot, temporary);
+  renameSync(temporary, target);
+  rmSync(`${target}-wal`, { force: true });
+  rmSync(`${target}-shm`, { force: true });
+}
+
+interface RowsRead {
+  integrity: string;
+  runs: number;
+  decisions: number;
+  verbLedger: number;
+}
+
+/** Read the restored store back — the proof the restore landed cleanly. */
+function readRestoredStore(target: string): RowsRead {
+  const db = new Database(target);
+  try {
+    const integrity = (db.query<{ integrity_check: string }, []>("PRAGMA integrity_check").get() as {
+      integrity_check: string;
+    }).integrity_check;
+    const count = (table: string): number =>
+      (db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
+    return { integrity, runs: count("runs"), decisions: count("decisions"), verbLedger: count("verb_ledger") };
+  } finally {
+    db.close();
+  }
+}
+
+export async function restoreDbCommand(ctx: CommandContext): Promise<void> {
+  // Help first: parsing stops before any config read or liveness check.
+  if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+    process.stdout.write(`${RESTORE_DB_USAGE}\n`);
+    return;
+  }
+  // Host-scoped: the store is one host-wide file, so --project cannot narrow it.
+  if (ctx.projectFlag !== undefined) {
+    process.stderr.write(`omp-conductor: restore-db does not take a project — the store is host-wide\n`);
+    process.exit(2);
+  }
+  const positionals = ctx.argv.slice(1).filter((a) => !a.startsWith("--"));
+  const flags = ctx.argv.slice(1).filter((a) => a.startsWith("--"));
+  if (flags.length > 0) {
+    process.stderr.write(`omp-conductor: restore-db: unexpected argument "${flags[0]}"\n`);
+    process.exit(2);
+  }
+  if (positionals.length > 1) {
+    process.stderr.write(`omp-conductor: restore-db takes at most one snapshot path\n`);
+    process.exit(2);
+  }
+
+  // The corruption-path guard: never restore under a daemon that is writing.
+  const daemon = livingDaemon();
+  if (daemon !== undefined) {
+    throw new Error(
+      `restore-db refuses while a daemon is running (pid ${daemon.pid}) — it would overwrite the store a live dispatch is writing; stop it first (\`omp-conductor stop\`)`,
+    );
+  }
+
+  const cfg = loadConfig();
+  const snapDir = dbBackupDirFor(cfg);
+  const requested = positionals[0];
+  const snapshot = requested === undefined ? newestSnapshot(snapDir) : resolve(requested);
+  if (snapshot === undefined) {
+    throw new Error(
+      `no conductor.db snapshot in ${snapDir} — take one (the snapshot primitive) or pass an explicit snapshot path`,
+    );
+  }
+  if (!existsSync(snapshot)) {
+    throw new Error(`snapshot ${snapshot} does not exist`);
+  }
+
+  overwriteStoreFrom(snapshot);
+  const restored = readRestoredStore(dbPath());
+  const integrityLine =
+    restored.integrity === "ok" ? "integrity ok" : `integrity: ${restored.integrity}`;
+  process.stdout.write(
+    `restored conductor.db from ${snapshot}\n` +
+      `\u2003${integrityLine} · runs ${restored.runs} · decisions ${restored.decisions} · verb_ledger ${restored.verbLedger}\n`,
+  );
+}

package/src/commands/stop.ts

@@ -7,32 +7,41 @@
  */
 
 import type { CommandContext } from "./context.ts";
-import { buildStopProvenance } from "../stop-provenance.ts";
+import { buildStopProvenance, liveWorkload, refuseBusyDaemon } from "../stop-provenance.ts";
 import { hold, pinPaneHalt, stopConductorPane } from "../fleet.ts";
 import { stopDaemon } from "../lifecycle.ts";
 import { openStore, dbPath } from "../store.ts";
 
 export async function stopCommand(ctx: CommandContext): Promise<void> {
 const withPane = ctx.argv.includes("--pane");
-const targets = ctx.targetProjects().map((project) => {
-  // `stop` takes the fleet down, so it always disarms — `--keep-ticks` is a
-  // `hold` affordance. Assert the invariant instead of printing a path that
-  // might not exist.
-  const held = hold(project.name, "halt");
-  if (held.disarmed === undefined) throw new Error("stop must disarm ticks");
-  return {
-    project,
-    hold: { ...held, disarmed: held.disarmed },
-    pin: withPane ? pinPaneHalt(project.name).path : undefined,
-  };
-});
+const forced = ctx.argv.includes("--force");
 const store = openStore(dbPath());
 try {
+  // Refusal (#545): the shared daemon serves every configured project, so a
+  // stop orphans any project's live workers — not just the one named. Refuse
+  // while anything is live, naming project + issues, before any hold/disarm/
+  // pin side-effect, so a refused stop leaves the fleet untouched. `--force`
+  // skips the whole gate (so a wedged daemon stays stoppable even when the
+  // store is unreadable) and the override is recorded in the provenance.
+  if (!forced) refuseBusyDaemon(liveWorkload(store), { override: false, verb: "stop" });
+  const targets = ctx.targetProjects().map((project) => {
+    // `stop` takes the fleet down, so it always disarms — `--keep-ticks` is a
+    // `hold` affordance. Assert the invariant instead of printing a path that
+    // might not exist.
+    const held = hold(project.name, "halt");
+    if (held.disarmed === undefined) throw new Error("stop must disarm ticks");
+    return {
+      project,
+      hold: { ...held, disarmed: held.disarmed },
+      pin: withPane ? pinPaneHalt(project.name).path : undefined,
+    };
+  });
   // Provenance (#378): the shared daemon serves every configured project, so
   // the record names the request's own project (or the global scope) AND every
-  // sibling with its live-run count — no silent cross-project stop.
+  // sibling with its live-run count — no silent cross-project stop. A forced
+  // stop keeps the override visible in the control path, never silent.
   const provenance = buildStopProvenance({
-    controlPath: "cli stop",
+    controlPath: forced ? "cli stop --force" : "cli stop",
     reason: "operator stop",
     scope: targets.length > 1 ? "global" : "project",
     project: targets.length === 1 ? targets[0]!.project.name : undefined,