omp-conductor 0.19.5 → 0.19.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.19.5",
+  "version": "0.19.6",
   "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/cli.ts

@@ -32,6 +32,7 @@ import { reportCommand } from "./commands/report.ts";
 import { releaseCompositionCommand } from "./commands/release-composition.ts";
 import { restartCommand } from "./commands/restart.ts";
 import { restoreDbCommand } from "./commands/restore-db.ts";
+import { snapshotDbCommand } from "./commands/snapshot-db.ts";
 import { resumeCommand } from "./commands/resume.ts";
 import { setupCommand } from "./commands/setup.ts";
 import { startCommand } from "./commands/start.ts";
@@ -300,6 +301,7 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     intake: () => intakeCommand(ctx),
     friction: () => frictionCommand(ctx),
     "restore-db": () => restoreDbCommand(ctx),
+    "snapshot-db": () => snapshotDbCommand(ctx),
     resume: () => resumeCommand(ctx),
     "brief-upgrade": () => briefUpgradeCommand(ctx),
     help: () => helpCommand(USAGE),

package/src/command-help.ts

@@ -6,10 +6,11 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            the project already exists, a chooser of which area to amend. Naming
            an area positionally skips that chooser and amends only that area:
            ${AMEND_AREA_IDS.join(", ")}.
-  upgrade  update the Bun-global CLI, omp plugin, Herdr recovery plugin, and
-           brief as one pinned release. Pauses only new claims, drains live
-           workers, reloads, verifies twice, and restores the prior dispatch
-           state. Run it from a shell outside the target Herdr session.
+  upgrade  discover the installed CLI package root, then update it with the omp
+           plugin, Herdr recovery plugin, and brief as one pinned release.
+           Pauses only new claims, drains live workers, reloads, verifies twice,
+           and restores the prior dispatch state. Run it from a shell outside
+           the target Herdr session.
            --bootstrap SHA --source PATH installs an exact commit instead of a
            published version, for when the installed conductor is what is
            broken: the source must be a checkout AT that sha, the package's own
@@ -66,6 +67,10 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            --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.
+  snapshot-db
+           publish a transaction-consistent conductor.db snapshot with SQLite
+           VACUUM INTO, record it in the durable event ledger, and apply the
+           daemon cadence's bounded retention. Safe while the daemon writes.
   restore-db
            put conductor.db back to a restorable snapshot, replacing the live
            file and dropping stale -wal/-shm sidecars. Refuses while a daemon
@@ -153,6 +158,9 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            sending now and holding, exactly as for a daemon escalation. An
            identical retry is refused only while the earlier handoff is still
            undelivered, and admitted again once it lands (#453).
+           report withdraw removes only an unsent pending report or unassigned
+           held notice, requires a reason, preserves an audit row, and refuses
+           sending/delivered/failed/already-withdrawn handoffs.
   message  deliver one direct Telegram message to this project's own chat and
            forum topic, resolved from config rather than from whichever chat
            last wrote to the session. This is how a locally injected tick
@@ -180,10 +188,12 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
   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
+           as a question put to the operator. The running daemon checks a
+           \`--resolves-when\` condition; an armed or ungated heartbeat wakes the
+           orchestrator tick when one is met. With no daemon the durable row is
+           unmonitored. With ticks disarmed the condition may still be marked met,
+           but no tick can be woken until the heartbeat returns. It is listed
+           under its own heading, never under "Open operator decisions", and has
            no seven-day expiry. \`watch list\` shows open watches; \`watch
            withdraw <id>\` ends one with a recorded reason — the verb that
            creates a watch is the verb that ends it (watches are decision rows,

package/src/command-manifest.ts

@@ -202,6 +202,17 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       toggle("--probe-telegram", "send the self-identified Telegram health probe"),
     ],
   },
+  {
+    name: "snapshot-db",
+    description: "publish a transaction-consistent conductor.db snapshot",
+    scope: "host",
+    usage: ["snapshot-db"],
+    flags: [],
+    details:
+      "Publish one transaction-consistent conductor.db snapshot using SQLite VACUUM INTO, " +
+      "record the action in every configured project's durable event ledger, and apply the " +
+      "daemon cadence's bounded retention. Safe while the daemon is writing.",
+  },
   {
     name: "restore-db",
     description: "restore conductor.db from a safe snapshot",
@@ -403,14 +414,18 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     scope: "project",
     usage: [
       "report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure] [--events IDS] [--notices IDS] [--project NAME]",
+      "report withdraw <id> --reason TEXT [--project NAME]",
     ],
+    subcommands: [{ name: "withdraw", description: "withdraw an unsent report or held notice" }],
     flags: [
       value("--text", "rendered report text"),
       value("--kind", "material, digest, or escalation category"),
       value("--events", "comma-separated event ledger ids"),
       value("--notices", "comma-separated notice ledger ids"),
+      value("--reason", "why a pending handoff is obsolete"),
       project(),
     ],
+    positionals: [{ name: "action" }, { name: "id" }],
   },
   {
     name: "message",
@@ -460,11 +475,13 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       "watch list [--project NAME] [--json]",
       "watch withdraw <id> [--reason TEXT] [--project NAME]",
     ],
-    details: `add records a row the daemon checks for you and the next tick reads, with no
-operator answer needed. list shows open watches, oldest first. withdraw ends
-one with a recorded reason — the verb that creates a watch is the verb that
-ends it. A watch whose PR condition can no longer be observed (the PR merged
-or closed first) is withdrawn by the daemon itself.`,
+    details: `add records a durable row with no operator answer needed. The running daemon
+checks conditions; an armed or ungated heartbeat wakes the orchestrator tick when one is met.
+With no daemon the row is unmonitored. With ticks disarmed the daemon may still mark a
+condition met, but no tick can be woken until the heartbeat returns. list shows open watches,
+oldest first. withdraw ends one with a recorded reason — the verb that creates a watch is the
+verb that ends it. A watch whose PR condition can no longer be observed (the PR merged or
+closed first) is withdrawn by the daemon itself.`,
     subcommands: [
       { name: "add", description: "record a watch" },
       { name: "list", description: "list open watches" },

package/src/commands/context.ts

@@ -104,6 +104,7 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   daemon: "host",
   restart: "host",
   "restore-db": "host",
+  "snapshot-db": "host",
   start: "host",
   upgrade: "host",
   "upgrade-install": "host",

package/src/commands/report.ts

@@ -22,7 +22,70 @@ import {
   type ReportKind,
 } from "../types.ts";
 
+async function withdrawHandoff(ctx: CommandContext): Promise<void> {
+  const id = ctx.argv[2];
+  const reason = ctx.flag("reason")?.trim();
+  if (id === undefined || id.startsWith("--")) {
+    process.stderr.write("omp-conductor: report withdraw needs the report or held-notice id\n");
+    process.exit(2);
+  }
+  if (reason === undefined || reason.length === 0 || reason.startsWith("--")) {
+    process.stderr.write("omp-conductor: report withdraw needs --reason with why the handoff is obsolete\n");
+    process.exit(2);
+  }
+  for (let i = 3; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === "--project" || token === "--reason") {
+      i += 1;
+      continue;
+    }
+    if (token?.startsWith("--project=") || token?.startsWith("--reason=")) continue;
+    process.stderr.write(`omp-conductor: report withdraw: unexpected argument "${token ?? ""}"\n`);
+    process.exit(2);
+  }
+  const sessionRole = process.env[SESSION_ROLE_ENV];
+  if (sessionRole === "worker") {
+    process.stderr.write("omp-conductor: report withdraw is an operator/orchestrator action, not a worker action\n");
+    process.exit(3);
+  }
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const inHerdrPane =
+    process.env["HERDR_ENV"] !== undefined && process.env["HERDR_ENV"] !== "";
+  const actor = sessionRole ?? (inHerdrPane ? "orchestrator" : "operator");
+  const store = openStore(dbPath());
+  try {
+    const result = store.withdrawHandoff(
+      id,
+      project.name,
+      actor,
+      reason,
+      Date.now(),
+    );
+    if (result.kind === "not-found") {
+      process.stderr.write(`omp-conductor: no report or held notice ${id} for ${project.name}\n`);
+      process.exit(1);
+    }
+    if (result.kind === "refused") {
+      process.stderr.write(
+        `omp-conductor: cannot withdraw ${result.target} ${id}: state is ${result.state}; ` +
+          "only an unsent pending report or unassigned held notice may be withdrawn\n",
+      );
+      process.exit(1);
+    }
+    process.stdout.write(
+      `${result.withdrawal.target} ${id} withdrawn for ${project.name} — ${reason}\n`,
+    );
+  } finally {
+    store.close();
+  }
+}
+
+
 export async function reportCommand(ctx: CommandContext): Promise<void> {
+if (ctx.argv[1] === "withdraw") {
+  await withdrawHandoff(ctx);
+  return;
+}
 const rawText = ctx.flag("text");
 const body = rawText?.trim();
 if (body === undefined || body.length === 0 || rawText?.startsWith("--") === true) {

package/src/commands/restore-db.ts

@@ -128,7 +128,7 @@ export async function restoreDbCommand(ctx: CommandContext): Promise<void> {
   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`,
+      `no conductor.db snapshot in ${snapDir} — run \`omp-conductor snapshot-db\` or pass an explicit snapshot path`,
     );
   }
   if (!existsSync(snapshot)) {

package/src/commands/snapshot-db.ts

@@ -0,0 +1,67 @@
+/** `snapshot-db` — publish one transaction-consistent conductor.db snapshot. */
+
+import type { CommandContext } from "./context.ts";
+import { dbBackupDirFor, loadConfig } from "../config.ts";
+import type { Store } from "../types.ts";
+import {
+  DB_SNAPSHOT_RETENTION,
+  dbPath,
+  openStore,
+  pruneDbSnapshots,
+  snapshotDb,
+} from "../store.ts";
+
+export async function snapshotDbCommand(ctx: CommandContext): Promise<void> {
+  if (ctx.projectFlag !== undefined) {
+    process.stderr.write("omp-conductor: snapshot-db does not take a project — the store is host-wide\n");
+    process.exit(2);
+  }
+  if (ctx.argv.length > 1) {
+    process.stderr.write(`omp-conductor: snapshot-db: unexpected argument "${ctx.argv[1]}"\n`);
+    process.exit(2);
+  }
+
+  const cfg = loadConfig();
+  const directory = dbBackupDirFor(cfg);
+  const published = snapshotDb(dbPath(), directory);
+  // Publication is already durable. Print its path before secondary accounting
+  // so a ledger/prune failure cannot turn success into an invisible file.
+  process.stdout.write(`snapshot published: ${published}\n`);
+
+  let store: Store | undefined;
+  try {
+    const opened = openStore(dbPath());
+    store = opened;
+    const now = Date.now();
+    const eventIds = cfg.projects.map((project) =>
+      opened.recordMaterialEvent({
+        project: project.name,
+        category: "db-snapshot",
+        summary: "published manual conductor.db snapshot",
+        evidence: published,
+        occurredAt: now,
+        recordedAt: now,
+      }).id,
+    );
+    process.stdout.write(`ledger events recorded: ${eventIds.join(", ")}\n`);
+  } catch (err) {
+    process.stderr.write(
+      `warning: snapshot published, but its ledger event could not be recorded: ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    );
+  } finally {
+    store?.close();
+  }
+
+  try {
+    const pruned = pruneDbSnapshots(directory, DB_SNAPSHOT_RETENTION);
+    process.stdout.write(`retention ${DB_SNAPSHOT_RETENTION} (${pruned} pruned)\n`);
+  } catch (err) {
+    process.stderr.write(
+      `warning: snapshot published, but retention pruning failed: ${
+        err instanceof Error ? err.message : String(err)
+      }\n`,
+    );
+  }
+}

package/src/commands/upgrade-install.ts

@@ -22,7 +22,7 @@ const result = await runDetachedUpgrade({
 });
 process.stdout.write(
   `install complete — awaiting first-tick verification:\n` +
-    `  Bun-global CLI     omp-conductor@${result.version}\n` +
+    `  omp-conductor CLI omp-conductor@${result.version}\n` +
     `  omp plugin         omp-conductor@${result.version}\n` +
     `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
     `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +

package/src/commands/upgrade.ts

@@ -1,5 +1,5 @@
 /**
- * `upgrade` — update the Bun-global CLI, omp plugin, Herdr recovery plugin and brief as one pinned release.
+ * `upgrade` — update the discovered CLI package, omp plugin, Herdr recovery plugin and brief as one pinned release.
  *
  * Moved out of cli.ts's switch by the per-verb module split (#462);
  * only the case wrapper, the injected `ctx` lookups and the imports
@@ -33,7 +33,7 @@ const result = await upgradeConductor({
 const spec = sha === undefined ? `omp-conductor@${result.version}` : `${result.version} @ ${result.gitHead.slice(0, 12)}`;
 process.stdout.write(
   `${result.alreadyCurrent ? "already current" : sha === undefined ? "upgrade complete" : "bootstrap complete"}:\n` +
-    `  Bun-global CLI     ${spec}\n` +
+    `  omp-conductor CLI ${spec}\n` +
     `  omp plugin         ${spec}\n` +
     `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
     `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +

package/src/commands/verb.ts

@@ -59,6 +59,7 @@ try {
   const reply = await handleVerbCall(
     {
       project: () => findProject(loadConfig(), project.name),
+      projects: () => loadConfig().projects,
       store,
       tracker: makeTracker(project),
       actions: githubVerbActions(project),

package/src/commands/watch.ts

@@ -21,6 +21,7 @@
 import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
+import { watchMonitoringForProject } from "../fleet.ts";
 import { shellQuote } from "../shell.ts";
 import { dbPath, openStore } from "../store.ts";
 
@@ -94,7 +95,12 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
         ...(condition === undefined ? {} : { condition }),
         at: Date.now(),
       });
-      const wake = condition === undefined ? "read by the next tick" : "the daemon wakes the next tick when it is met";
+      const monitoring = watchMonitoringForProject(project.name);
+      const wake = monitoring.monitored
+        ? condition === undefined
+          ? "read by the next tick"
+          : "the daemon checks it and wakes the next available tick when it is met"
+        : `durable but currently unmonitored (${monitoring.reason}); it becomes wake-capable automatically when the daemon and heartbeat are active`;
       // The verb that ends the row names the project it was created in: this
       // command is copied, and on a host with several projects the bare form is
       // ambiguous (#810).
@@ -107,6 +113,7 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
     if (sub === "list" || sub === undefined) {
       assertKnownWatchArgs(ctx, "list", 2);
       const open = store.openDecisions(project.name).filter((d) => d.kind === "watch");
+      const monitoring = watchMonitoringForProject(project.name);
       const now = Date.now();
       const watches = open.map((d) => ({
         id: d.id,
@@ -116,13 +123,18 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
         note: d.question,
       }));
       if (ctx.argv.includes("--json")) {
-        process.stdout.write(`${JSON.stringify({ project: project.name, watches }, null, 2)}\n`);
+        process.stdout.write(`${JSON.stringify({ project: project.name, monitoring, watches }, null, 2)}\n`);
         return;
       }
       if (watches.length === 0) {
         process.stdout.write("no watches\n");
         return;
       }
+      process.stdout.write(
+        monitoring.monitored
+          ? "watch monitoring: active\n"
+          : `watch monitoring: durable, unmonitored (${monitoring.reason})\n`,
+      );
       for (const watch of watches) {
         process.stdout.write(
           `${watch.id}  ${watch.ageHours}h  blocks:${watch.blocks ?? "-"}  ` +

package/src/config.ts

@@ -320,6 +320,23 @@ export function resolveReleaseGrants(p: ProjectConfig): ResolvedGrants {
   return grants;
 }
 
+/** The one install holder shared by every project on this host, or the
+ * per-project evidence explaining why no shared holder exists (#1018). */
+export function resolveSharedInstallAuthority(projects: readonly ProjectConfig[]): {
+  holder?: ResolvedGrants["install"];
+  entries: readonly { project: string; holder: ResolvedGrants["install"] }[];
+} {
+  const entries = projects.map((project) => ({
+    project: project.name,
+    holder: resolveReleaseGrants(project).install,
+  }));
+  const holders = new Set(entries.map((entry) => entry.holder));
+  return {
+    ...(holders.size === 1 ? { holder: entries[0]!.holder } : {}),
+    entries,
+  };
+}
+
 /**
  * The gating conditions for one project, complete (#129).
  *

package/src/daemon.ts

@@ -17,6 +17,7 @@ import {
   loadConfig,
   resolveCaps,
   resolveReleaseGrants,
+  resolveSharedInstallAuthority,
   resolveReview,
   stateDir,
 } from "./config.ts";
@@ -171,6 +172,7 @@ import type {
   DigestBacklog,
   Escalation,
   InterruptCategory,
+  HandoffWithdrawal,
   IssueComment,
   IssueSnapshot,
   PrDiff,
@@ -451,6 +453,7 @@ interface Deps {
 export function verbDeps(d: Pick<Deps, "project" | "store" | "tracker" | "verbActions">): VerbDeps {
   return {
     project: () => findProject(loadConfig(), d.project.name),
+    projects: () => loadConfig().projects,
     store: d.store,
     tracker: d.tracker,
     actions: d.verbActions ?? githubVerbActions(d.project),
@@ -6605,6 +6608,8 @@ export interface StatusSnapshot {
    *  unknown outcome, or written off. An empty list is the only honest way to
    *  say "everything authored this cycle actually went out" (#123). */
   openReports: ReportRecord[];
+  /** Recent successful report/notice withdrawals, newest first. */
+  handoffWithdrawals?: HandoffWithdrawal[];
   /** Ordinary outcomes and deferred escalations not yet associated with an
    * accepted digest report. */
   digestBacklog: DigestBacklog;
@@ -6791,6 +6796,7 @@ export function statusSnapshotFromStore(
     quarantinedRuns: store.quarantinedRuns(p.name),
     turnOverrides: store.listTurnOverrides(p.name),
     openReports: store.openReports(p.name),
+    handoffWithdrawals: store.handoffWithdrawals(p.name),
     digestBacklog: store.digestBacklog(p.name),
     verbLedger: store.verbLedger(p.name, { limit: STATUS_LEDGER_SCAN }),
     liveWorkers: live.length,
@@ -7199,11 +7205,18 @@ interface ProjectRuntime {
   reportPass?: Promise<void>;
 }
 
-function orchestratorStandingOrders(project: ProjectConfig): {
+export function orchestratorStandingOrders(
+  project: ProjectConfig,
+  projects: readonly ProjectConfig[],
+): {
   brief: string;
   releaseGrants: ResolvedGrants;
 } {
-  const releaseGrants = resolveReleaseGrants(project);
+  const installAuthority = resolveSharedInstallAuthority(projects);
+  const releaseGrants = {
+    ...resolveReleaseGrants(project),
+    install: installAuthority.holder ?? "human",
+  };
   const grantedShapes = RELEASE_SHAPES.filter((shape) => releaseGrants[shape] === "orchestrator");
   const deniedShapes = RELEASE_SHAPES.filter((shape) => releaseGrants[shape] !== "orchestrator");
   return {
@@ -7230,6 +7243,13 @@ function orchestratorStandingOrders(project: ProjectConfig): {
           ? "every release and deploy shape is mechanically blocked for you"
           : `you may invoke ${grantedShapes.join(", ")} — and only by the procedure in your POLICY.md`
       }.` + (deniedShapes.length === 0 ? "" : ` Blocked: ${deniedShapes.join(", ")}.`),
+      ...(installAuthority.holder === undefined
+        ? [
+            `Host-global install authority conflicts: ${installAuthority.entries
+              .map((entry) => `${entry.project}=${entry.holder}`)
+              .join(", ")}. Install is blocked.`,
+          ]
+        : []),
       "Handle each escalation below before the next one.",
     ].join("\n"),
   };
@@ -7432,7 +7452,7 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
       log(`skipping orphan reconciliation: daemon pid ${alive.pid} is alive and owns the active runs`);
     }
 
-    const { brief, releaseGrants } = orchestratorStandingOrders(project);
+    const { brief, releaseGrants } = orchestratorStandingOrders(project, cfg.projects);
     let orchestrator: OrchestratorHandle | undefined;
     let orchestratorVerbs: VerbListener | undefined;
     /** First start-failure cause, surfaced by the orchestrator-down incident (#288). */

package/src/doctor.ts

@@ -85,6 +85,7 @@ import {
 import {
   herdrConductorPluginConfigDir,
   planHostRuntime,
+  RECOVER_SERVICE_NAME,
   STAGED_SERVICE_NAME,
   SYSTEMD_UNIT_DIR,
   tickCwdForProject,
@@ -229,6 +230,8 @@ export interface DoctorDeps {
   hasSystemd?: () => boolean;
   /** The installed unit text at an absolute path, or undefined when absent. */
   readUnit?: (path: string) => string | undefined;
+  /** Whether one installed systemd unit is currently failed; undefined when unreadable. */
+  unitFailed?: (name: string) => boolean | undefined;
   /** stat one path; undefined when it does not exist. */
   stat?: (path: string) => Stats | undefined;
   /** uid of a username (`id -u`), or undefined when it cannot be resolved. */
@@ -397,6 +400,18 @@ function defaultReadUnit(path: string): string | undefined {
   }
 }
 
+export function systemdStateFailed(state: string): boolean | undefined {
+  const normalized = state.trim();
+  if (normalized === "") return undefined;
+  return normalized === "failed";
+}
+
+function defaultUnitFailed(name: string): boolean | undefined {
+  const ran = spawnSync("systemctl", ["is-failed", name], { encoding: "utf8" });
+  if (ran.error !== undefined) return undefined;
+  return systemdStateFailed(ran.stdout ?? "");
+}
+
 function defaultStat(path: string): Stats | undefined {
   try {
     return statSync(path);
@@ -660,7 +675,7 @@ function dbBackupProbe(probes: Probes, cfg: ConductorConfig | undefined): Findin
     return warnFinding(
       "db-backup",
       "conductor.db has no snapshot — losing it loses the audit trail with no recovery path",
-      "take a conductor.db snapshot (the daemon's cadence files one; restore-db needs one to restore from)",
+      "run `omp-conductor snapshot-db` (the daemon cadence uses the same SQLite snapshot primitive)",
     );
   }
   const newestMtime = snapshots
@@ -670,7 +685,7 @@ function dbBackupProbe(probes: Probes, cfg: ConductorConfig | undefined): Findin
     return warnFinding(
       "db-backup",
       `conductor.db is newer than every snapshot (${snapshots.length} file(s)) — the newest writes were never snapshot`,
-      "take a fresh conductor.db snapshot so restore-db has the current state",
+      "run `omp-conductor snapshot-db` so restore-db has the current state",
     );
   }
   return passFinding("db-backup", `conductor.db snapshot is fresh (${snapshots.length} file(s))`);
@@ -934,6 +949,22 @@ function recoveryProbe(probes: Probes): Finding {
   );
 }
 
+function recoveryStateProbe(probes: Probes): Finding {
+  const id = "systemd-recovery-state";
+  if (!probes.hasSystemd()) return passFinding(id, "no systemd directory on this host — nothing to check");
+  if (probes.readUnit(join(SYSTEMD_UNIT_DIR, RECOVER_SERVICE_NAME)) === undefined) {
+    return passFinding(id, "recovery unit is not installed — systemd-recovery owns that finding");
+  }
+  const failed = probes.unitFailed(RECOVER_SERVICE_NAME);
+  if (failed === false) return passFinding(id, `${RECOVER_SERVICE_NAME} is not failed`);
+  const fix =
+    `inspect \`systemctl status ${RECOVER_SERVICE_NAME}\` and \`journalctl -u ${RECOVER_SERVICE_NAME}\`; ` +
+    `fix the root cause, then run \`systemctl reset-failed ${RECOVER_SERVICE_NAME}\` and rerun doctor`;
+  return failed === true
+    ? warnFinding(id, `${RECOVER_SERVICE_NAME} is in failed state — its last recovery did not complete`, fix)
+    : warnFinding(id, `${RECOVER_SERVICE_NAME} state could not be read`, fix);
+}
+
 function installedUnitUser(probes: Probes): string | undefined {
   const unit = probes.readUnit(join(SYSTEMD_UNIT_DIR, STAGED_SERVICE_NAME));
   if (unit === undefined) return undefined;
@@ -1713,7 +1744,7 @@ function parseEnvKey(text: string, key: string): string | undefined {
 
 /**
  * Install-surface parity (#904). omp-conductor installs onto three surfaces —
- * the Bun-global CLI/daemon tree, the omp plugin, and the herdr recovery
+ * the discovered CLI package tree, the omp plugin, and the herdr recovery
  * plugin — and only a live `upgrade` invocation ever compared them. On a
  * fleet whose installs are manual they diverge silently: measured on this
  * host on 2026-08-22, the omp plugin sat on the withdrawn 0.18.1 release for
@@ -2002,6 +2033,7 @@ export async function runDoctor(projectName: string | undefined, opts: DoctorDep
   // the first one stands in for the rendering seam.
   findings.push(unitProbe(probes, projects[0], cfg));
   findings.push(recoveryProbe(probes));
+  findings.push(recoveryStateProbe(probes));
   findings.push(ownershipProbe(probes));
   // #541 seam checks, host-global: the live herdr config and the plugin's
   // config.env are single files on the host, not per-project facts.
@@ -2106,6 +2138,7 @@ export function defaultProbes(): Probes {
     repoLabels: defaultRepoLabels,
     hasSystemd: () => existsSync(SYSTEMD_UNIT_DIR),
     readUnit: defaultReadUnit,
+    unitFailed: defaultUnitFailed,
     stat: defaultStat,
     uidOf: defaultUidOf,
     dbIntegrity: defaultDbIntegrity,