omp-conductor 0.18.1 → 0.19.0

package/src/briefs/orchestrator.md

@@ -238,11 +238,12 @@ Keep the queue worth draining.
   When the queue is below the grooming trigger, the tick's **bounded to-spec
   batch** block (#777) carries the mechanical contract: it names the launch
   token, the candidates the conductor selected mechanically from the live
-  open-issue snapshot (parked, parent/epic, already-groomed, in-flight,
-  lane/dependency-blocked and dispatched issues were excluded by code, never
-  by your judgement), the exclusions that selection applied, and the item
-  shape. Do exactly what it says — those candidates are the only batch this
-  tick authorizes: render `omp/src/briefs/to-spec.md` for each of them with
+  open-issue snapshot (parked, parent/epic, already-groomed, refused inside
+  their retry cooldown, in-flight, lane/dependency-blocked and dispatched
+  issues were excluded by code, never by your judgement), the exclusions that
+  selection applied, and the item shape. Do exactly what it says — those
+  candidates are the only batch this tick authorizes: render
+  `omp/src/briefs/to-spec.md` for each of them with
   the current source head, launch exactly one `task` batch through the
   `to-spec` agent with the listed items and no substitutes, and persist every
   returned result with the `conductor_to_spec_result` tool. The `tool_call`
@@ -254,18 +255,31 @@ Keep the queue worth draining.
   source/ref/freshness is refused as blocked, never groomed. The quality bar
   above does not move.
 - **Every to-spec agent answers the same return contract**, or its output is
-  refused: the strict schema carries
-  - verdict — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
+  refused: the strict schema carries exactly these fields — the generated task
+  schema and the persistence parser are that one contract, so an extra or
+  missing field is refused as malformed:
+  - `verdict` — `ALREADY DONE` / `PROMOTABLE` / `NEEDS DECOMPOSITION` / `BLOCKED` /
     `NEEDS PRODUCT DECISION`
-  - routing — exactly one repo, or `MULTI` with the split
-  - evidence — the file or symbol proving `ALREADY DONE`, never a title match
-  - entry points — the 3-6 files to change or read first
-  - existing tests covering the behaviour, by path
-  - the one thing most likely to be silently faked
-  - source — where the code was read: the clone/ref and how fresh it is. A
+  - `routing` — exactly one `owner/repo`, or `MULTI`
+  - `routingSplit` — required iff `routing` is `MULTI`: what each slice goes to
+  - `source` — where the code was read: the clone/ref and how fresh it is. A
     scout that cannot reach a source it trusts returns `BLOCKED` and says so;
     silent fallback to an unnamed source is the failure mode of delegated
     research — stale evidence reads exactly like good evidence.
+  - `evidence` — the files/symbols proving the verdict; required for
+    `ALREADY DONE` (the file or symbol that already does the work, never a
+    title match)
+  - `laterWorkInvalidates` — whether later work retired the premise
+  - `laterWorkNote` — what that check searched and found
+  - `entryPoints` — the 3-6 files to change or read first
+  - `existingTests` — existing tests covering the behaviour, by path
+  - `likelySilentFake` — the one thing most likely to be silently faked
+  - `proofCommands` — the focused commands that prove the work
+  - `fileLane` — the files and directories this slice writes
+  - `dependencies` — open prerequisite issue numbers, bare (`875`) or string
+    (`"875"`); `[]` when none
+  - `proposedBrief` — required iff `verdict` is `PROMOTABLE`
+  - `reasonNotToPromote` — required for every other verdict
 - **Disqualifying an issue is a successful grooming outcome.** Measured on this
   package's own fleet: four scouts over sixteen backlog issues promoted four and
   *disqualified six* that looked promotable from their titles — four written

package/src/briefs/to-spec.md

@@ -44,6 +44,9 @@ required field and no extra keys. The fields are:
   the exact ref, and `freshAt` = epoch milliseconds when you actually observed
   it. Conductor refuses results whose source is older than 24 hours or missing
   name/ref/freshAt — an unsourced verdict is not grooming, it is prose.
+- `evidence` — the files/symbols that prove the verdict. Required for
+  `ALREADY DONE`: name the symbol/file that already does the work, never a
+  title match. Welcome on every other verdict.
 - `laterWorkInvalidates` — boolean: did later work (an epic or issue committed
   after this candidate was filed) retire its premise?
 - `laterWorkNote` — what you searched for that check and what you found. Even
@@ -57,8 +60,9 @@ required field and no extra keys. The fields are:
   implementing, and how to prove it is not.
 - `proofCommands` — the focused commands that prove the work, each with its
   `cwd` when it matters.
-- `fileLane` — the files and directories this slice writes; `dependencies` —
-  open prerequisites, `[]` when none.
+- `fileLane` — the files and directories this slice writes.
+- `dependencies` — open prerequisite issue numbers, each a bare number
+  (`875`) or a string (`"875"`); `[]` when none.
 - `proposedBrief` — required iff `verdict` is `PROMOTABLE`: the brief a worker
   would be dispatched with, including the silent fake and the proof commands.
 - `reasonNotToPromote` — required for every other verdict: why this must not

package/src/cli.ts

@@ -9,7 +9,7 @@
  */
 import { userInfo } from "node:os";
 import { loadConfig } from "./config.ts";
-import { COMMAND_MANIFEST, renderUsage } from "./command-manifest.ts";
+import { COMMAND_MANIFEST, renderUsage, type CommandManifestEntry } from "./command-manifest.ts";
 import { armCommand } from "./commands/arm.ts";
 import { boardCommand } from "./commands/board.ts";
 import { briefUpgradeCommand } from "./commands/brief-upgrade.ts";
@@ -28,6 +28,7 @@ import { intakeCommand } from "./commands/intake.ts";
 import { ledgerCommand } from "./commands/ledger.ts";
 import { messageCommand } from "./commands/message.ts";
 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 { resumeCommand } from "./commands/resume.ts";
@@ -40,6 +41,7 @@ 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 { reconcileUnitsCommand } from "./commands/reconcile-units.ts";
 import { upgradeRollbackCommand } from "./commands/upgrade-rollback.ts";
 import { upgradeCommand } from "./commands/upgrade.ts";
 import { verbCommand } from "./commands/verb.ts";
@@ -55,6 +57,104 @@ import {
 
 const USAGE = renderUsage(COMMAND_MANIFEST);
 
+/**
+ * Verbs that define every `--help`/`-h` shape themselves, so the dispatch
+ * gate below must not pre-empt them: `help` and the version aliases print
+ * their own text, `setup` accepts help only as the first trailing token
+ * (`setup bogus --help` must reject `bogus`, never print a help read), and
+ * the hand-rolled usage verbs print help at `argv[1]` or refuse a trailing
+ * unknown token with exit 2 — every one of them already before any side
+ * effect. `intake` and `watch` are deliberately absent: they validate their
+ * tails only after `loadConfig`/`openStore`, so an unconsumed trailing help
+ * must be answered by the gate before the handler can create the store
+ * (#863).
+ */
+const HELP_OWNED_VERBS: Record<string, true> = {
+  "--help": true,
+  "-h": true,
+  help: true,
+  "--version": true,
+  "-V": true,
+  version: true,
+  setup: true,
+  dashboard: true,
+  doctor: true,
+  stats: true,
+  drain: true,
+  "restore-db": true,
+};
+
+/**
+ * `setup`'s install subcommands — the one `setup` shape the wizard does not
+ * safely own: help is recognized only at the first trailing token, so
+ * `setup host --help` would reach the privileged install planner (creating
+ * the state db and staging the host install) instead of printing help. The
+ * dispatch gate answers real help requests in their tail instead.
+ */
+const SETUP_INSTALL_SUBCOMMANDS: Record<string, true> = {
+  host: true,
+  graph: true,
+};
+
+/**
+ * Whether an invocation carries an actual `--help`/`-h` request — a token the
+ * verb's own grammar does not consume. A token immediately after a
+ * value-taking flag is that flag's value (`report --text --help` sends the
+ * literal text "--help", exactly as before), and a bare `--` makes everything
+ * after it positional; only an unconsumed help token is really a request.
+ */
+function helpRequested(argv: readonly string[], entry: CommandManifestEntry): boolean {
+  let consumeNext = false;
+  for (const token of argv.slice(1)) {
+    if (consumeNext) {
+      consumeNext = false;
+      continue;
+    }
+    if (token === "--") {
+      // A bare `--` ends option parsing for a verb whose manifest actually
+      // declares positionals: after it, `--help` is positional data, not a
+      // request. A flag-only verb has no positional grammar for `--` to
+      // protect, so `stop --all -- --help` (#863) must stay a help read.
+      if ((entry.positionals?.length ?? 0) > 0) return false;
+      continue;
+    }
+    if (token === "--help" || token === "-h") return true;
+    // `--flag VALUE` consumes the next token as the flag's value, but
+    // `--flag=VALUE` binds the value inline — so only the split form can
+    // swallow a following `--help`. `stop --project=conductor --help` is a
+    // help read (#863), and `--project conductor --help` must read the next
+    // token as the value, exactly as `report --text --help` sends literal
+    // text. A token without `=` is a separate argument: when it names a
+    // value-taking flag, its value is the next token.
+    consumeNext =
+      token.startsWith("--") &&
+      !token.includes("=") &&
+      entry.flags.some((flag) => flag.name === token && flag.takesValue);
+  }
+  return false;
+}
+
+/**
+ * One verb's usage block from the manifest — what `VERB --help` prints. The
+ * manifest's `details` is that verb's long-form semantics, and rendering it
+ * here is what keeps the generated read complete: the dispatch gate above
+ * answers help for every verb that does not own it, so a verb whose prose
+ * lived only in its own hand-rolled usage string would silently lose it
+ * (#863 — `watch`'s no-answer/auto-withdraw semantics and `intake`'s
+ * durability/groomed no-op semantics).
+ */
+function renderCommandHelp(entry: CommandManifestEntry): string {
+  const lines = [`omp-conductor ${entry.name} — ${entry.description}`, "", "usage:"];
+  for (const usage of entry.usage) lines.push(`  omp-conductor ${usage}`);
+  if (entry.flags.length > 0) {
+    lines.push("", "flags:");
+    const width = Math.max(...entry.flags.map((flag) => flag.name.length));
+    for (const flag of entry.flags) lines.push(`  ${flag.name.padEnd(width)}  ${flag.description}`);
+  }
+  if (entry.details !== undefined) lines.push("", entry.details);
+  return lines.join("\n");
+}
+
 /** Applies both `--port 9000` and `--port=9000`; returns undefined when absent. */
 function flag(argv: string[], name: string): string | undefined {
   const i = argv.indexOf(`--${name}`);
@@ -167,6 +267,7 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     setup: () => setupCommand(ctx),
     upgrade: () => upgradeCommand(ctx),
     "upgrade-install": () => upgradeInstallCommand(ctx),
+    "reconcile-units": () => reconcileUnitsCommand(ctx),
     "upgrade-rollback": () => upgradeRollbackCommand(ctx),
     daemon: () => daemonCommand(ctx),
     start: () => startCommand(ctx),
@@ -186,8 +287,9 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     extend: () => extendCommand(ctx),
     worker: () => workerCommand(ctx),
     unblock: () => unblockCommand(ctx),
-    unfreeze: () => unfreezeCommand(ctx),
+    "release-composition": () => releaseCompositionCommand(ctx),
     verb: () => verbCommand(ctx),
+    unfreeze: () => unfreezeCommand(ctx),
     event: () => eventCommand(ctx),
     report: () => reportCommand(ctx),
     message: () => messageCommand(ctx),
@@ -254,6 +356,29 @@ export async function runCli(argv: string[] = process.argv.slice(2)): Promise<vo
       );
       process.exit(2);
     }
+    // A real `--help`/`-h` (one no declared flag consumes) is a help read and
+    // must never reach a mutating command: `stop --all --help` is how #863
+    // disarmed the fleet. Recognized here — before project-selection
+    // (`targetProjects` is a lazy closure; no config is loaded) and before
+    // handler execution — so a verb that does not validate its own tail can
+    // no longer treat the request as an argument.
+    const entry = cmd === undefined ? undefined : COMMAND_MANIFEST.find((entry) => entry.name === cmd);
+    let help = false;
+    if (entry !== undefined) {
+      if (cmd === "setup") {
+        // `setup` owns its help (only at the first trailing token, which is
+        // what keeps `setup bogus --help` rejecting `bogus`). The install
+        // subcommands are the exception: a help token in their tail must be
+        // answered here, before `loadConfig` and the install plan (#863).
+        help = SETUP_INSTALL_SUBCOMMANDS[argv[1] ?? ""] === true && helpRequested(argv, entry);
+      } else if (HELP_OWNED_VERBS[cmd ?? ""] !== true) {
+        help = helpRequested(argv, entry);
+      }
+    }
+    if (help && entry !== undefined) {
+      process.stdout.write(`${renderCommandHelp(entry)}\n`);
+      return;
+    }
     // A "none"-scope verb does no per-project work, so --project cannot change
     // what it does: refuse it with a reason instead of silently ignoring it.
     if (COMMAND_SCOPES[cmd ?? ""] === "none" && projectFlag !== undefined) {

package/src/command-help.ts

@@ -10,6 +10,11 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            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
+           checks run there first, and a check failure refuses rather than
+           installing a partly verified tree.
   upgrade-install
            the detached executor half of the fleet-installs-itself request:
            the same transaction, journaled per surface, leaving verification
@@ -207,7 +212,10 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
            re-stage the systemd unit and run the install behind one confirm.
            The units are host-global; NAME (or --project NAME) says which
            project's per-project tail (tick config, brief link) to write, and
-           is required on a host with several configured projects.
+           is required on a host with several configured projects. On a Herdr
+           host it restarts the session unit, so it must be run from a shell
+           outside that session: from a pane inside it, it refuses before
+           staging or installing anything.
   setup graph
            set up the code-graph indexes workers query instead of grepping, end
            to end: check prerequisites, clone any missing index-only clone as

package/src/command-manifest.ts

@@ -59,13 +59,15 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     description: "interview, configure the fleet, or install host and graph surfaces",
     scope: "project",
     usage: [
-      "setup [area] [--no-ai] [--answers FILE] [--save-answers FILE] [--project NAME]",
+      "setup [area] [--no-ai] [--answers FILE] [--save-answers FILE] [--resume FILE] [--project NAME]",
       "setup host [NAME] [--project NAME]",
       "setup graph [--no-seed] [--print] [--project NAME]",
     ],
-    details: COMMAND_DETAILS,
     subcommands: [
-      { name: "host", description: "stage and install the host services" },
+      {
+        name: "host",
+        description: "stage and install the host services (run it from a shell outside the Herdr session it restarts)",
+      },
       { name: "graph", description: "install and seed code-graph indexes" },
     ],
     flags: [
@@ -118,7 +120,7 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     name: "upgrade",
     description: "upgrade all installed conductor surfaces as one transaction",
     scope: "host",
-    usage: ["upgrade [--to VERSION] [--project NAME]"],
+    usage: ["upgrade [--to VERSION] [--bootstrap SHA --source PATH] [--project NAME]"],
     flags: [value("--to", "package version to install"), project()],
   },
   {
@@ -135,6 +137,18 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     usage: ["upgrade-rollback"],
     flags: [],
   },
+  {
+    name: "reconcile-units",
+    description: "install the host unit files this version renders (units only)",
+    scope: "host",
+    usage: ["reconcile-units [--yes] [--dry-run] [--protect PATH]... [--project NAME]"],
+    flags: [
+      toggle("--yes", "skip the confirm (the upgrade transaction's own consent)"),
+      toggle("--dry-run", "print what would be installed and run nothing"),
+      value("--protect", "a destination to leave alone (repeatable)"),
+      project(),
+    ],
+  },
   {
     name: "board",
     description: "open the live keyboard-driven fleet board",
@@ -293,6 +307,24 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     flags: [value("--reason", "reason for clearing the freeze"), project()],
     positionals: [{ name: "repo" }],
   },
+  {
+    name: "release-composition",
+    description: "declare, override, complete or cancel the active release",
+    scope: "project",
+    usage: [
+      "release-composition declare --campaign ID [--pr URL ...] [--reason TEXT] [--project NAME]",
+      "release-composition override --pr URL [--reason TEXT] [--project NAME]",
+      "release-composition complete [--reason TEXT] [--project NAME]",
+      "release-composition cancel [--reason TEXT] [--project NAME]",
+      "release-composition status [--project NAME]",
+    ],
+    flags: [
+      value("--campaign", "campaign identifier for the release being assembled"),
+      value("--pr", "full PR URL allowed into (or overridden into) the release"),
+      value("--reason", "reason recorded with the transition"),
+      project(),
+    ],
+  },
   {
     name: "verb",
     description: "run a gated conductor_* verb as the orchestrator",
@@ -418,6 +450,11 @@ 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.`,
     subcommands: [
       { name: "add", description: "record a watch" },
       { name: "list", description: "list open watches" },
@@ -443,6 +480,12 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       "intake dismiss <id> [--project NAME]",
       "intake groomed <id> --issue <url> [--project NAME]",
     ],
+    details: `Captures one raw idea into the local store and prints its id. list shows what
+is still pending (id, age, text), oldest first; dismiss drops one by id. The
+capture is durable — it lives in the sqlite store, not in a session — so it
+survives daemon restarts. The orchestrator files the idea as an issue and then
+marks that provenance with groomed: an id already resolved is a no-op with a
+message, never an error, because ticks retry.`,
     subcommands: [
       { name: "list", description: "list pending intake items" },
       { name: "dismiss", description: "dismiss an intake item" },
@@ -456,7 +499,6 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     description: "print command usage (also --help, -h)",
     scope: "none",
     usage: ["help"],
-    details: COMMAND_HELP_TAIL,
     flags: [],
   },
   {
@@ -480,9 +522,11 @@ export function renderUsage(manifest: readonly CommandManifestEntry[] = COMMAND_
   const commands = manifest.map(
     (command) => `  ${command.name.padEnd(width)}  ${command.description}`,
   );
-  const details = manifest.flatMap((command) =>
-    command.details === undefined ? [] : [...command.details.split("\n"), ""],
-  );
+  // The fleet-wide operator reference, printed once. It is *not* harvested
+  // from `details`: that field is one verb's own long-form help, which
+  // `VERB --help` renders, so collecting it here would print `setup`'s
+  // carrier copy of this very blob and repeat each verb's prose twice.
+  const details = [...COMMAND_DETAILS.split("\n"), "", ...COMMAND_HELP_TAIL.split("\n"), ""];
   return [
     "omp-conductor — dispatch ready issues to omp coding sessions",
     "",

package/src/commands/arm.ts

@@ -1,5 +1,5 @@
 /**
- * `arm` — proof-gated: send a Telegram challenge and write the arm marker only after the reply appears in the orchestrator transcript.
+ * `arm` — proof-gated: send a Telegram challenge and write the arm marker only after the orchestrator's inbound adapter acknowledges the reply in conductor state (#614).
  *
  * 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
@@ -15,10 +15,14 @@ for (const project of ctx.targetProjects()) {
   // Proof-neutral wording: `claim-only` performs no Telegram send, so the
   // progress line cannot promise a challenge that never goes out (#613). The
   // result line names the proof that actually armed it.
+  // The pending-proof heartbeat goes straight to stdout (#861): a challenge
+  // waits on a human for up to five minutes, and `withProgress`'s single step
+  // line cannot say how much of that window is left. Written unconditionally —
+  // a piped or plain-UI run needs it more than a TTY does, not less.
   const r = await withProgress(
     "arm: verifying the arming proof…",
     "Arming proof verified",
-    () => armTicks(project.name),
+    () => armTicks(project.name, { progress: (line) => process.stdout.write(`${line}\n`) }),
     { plainMessage: true },
   );
   process.stdout.write(

package/src/commands/context.ts

@@ -89,6 +89,7 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   intake: "project",
   ledger: "project",
   message: "project",
+  "release-composition": "project",
   report: "project",
   setup: "project", // the wizard and `setup graph` configure one project
   stats: "project",
@@ -106,6 +107,7 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   upgrade: "host",
   "upgrade-install": "host",
   "upgrade-rollback": "host",
+  "reconcile-units": "host",
   // fleet — every project by default, --project narrows
   arm: "fleet",
   board: "fleet",

package/src/commands/intake.ts

@@ -12,21 +12,6 @@ import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { dbPath, openStore } from "../store.ts";
 
-const INTAKE_USAGE = `omp-conductor intake — capture raw ideas durably.
-
-usage:
-  omp-conductor intake "<text>" [--project NAME]
-  omp-conductor intake list [--project NAME]
-  omp-conductor intake dismiss <id> [--project NAME]
-  omp-conductor intake groomed <id> --issue <url> [--project NAME]
-
-Captures one raw idea into the local store and prints its id. list shows what
-is still pending (id, age, text), oldest first; dismiss drops one by id. The
-capture is durable — it lives in the sqlite store, not in a session — so it
-survives daemon restarts. The orchestrator files the idea as an issue and then
-marks that provenance with groomed: an id already resolved is a no-op with a
-message, never an error, because ticks retry.`;
-
 /** Flags the intake surface understands. `--project` is consumed by
  *  {@link CommandContext.projectFlag}; the value token stays in argv. */
 const INTAKE_FLAGS: Record<string, true> = { "--project": true, "--issue": true };
@@ -49,11 +34,11 @@ function assertKnownArgs(ctx: CommandContext, from: number): void {
 }
 
 export async function intakeCommand(ctx: CommandContext): Promise<void> {
+  // `--help`/`-h` never arrives here: the CLI dispatch gate answers a real
+  // help request from the manifest before this handler runs (#863), which is
+  // why the long-form prose lives on the manifest's `details` field rather
+  // than in a usage string this module would print itself.
   const sub = ctx.argv[1];
-  if (sub === "--help" || sub === "-h") {
-    process.stdout.write(INTAKE_USAGE);
-    return;
-  }
   const project = findProject(loadConfig(), ctx.projectFlag);
   const store = openStore(dbPath());
   try {

package/src/commands/message.ts

@@ -101,6 +101,28 @@ export async function messageCommand(ctx: CommandContext): Promise<void> {
   );
 }
 
+/**
+ * A hold reaches nobody now, so it is the wrong path for an answer somebody is
+ * waiting for (#882).
+ *
+ * 2026-08-21T20:48Z: a tick was interrupted by an operator message, the mandated
+ * targetless `telegram_send` failed, and the session fell back to this command.
+ * It behaved correctly — the category was non-bypass, so the answer was held for
+ * the 23:30 digest — and the operator sat waiting in the topic they had written
+ * in. "nothing was sent" was already printed and was already true; what was
+ * missing is that the caller is *mid-conversation* and a live path exists.
+ *
+ * So every hold names it. Conditionally, because this process cannot know
+ * whether an inbound message is waiting: it is a separate process from the
+ * session, and inventing a guess here would either nag every legitimate
+ * digest-only note or, worse, quietly bypass availability policy on a hunch.
+ * The caller knows, and one sentence is enough to make holding a choice rather
+ * than a default.
+ */
+const LIVE_REPLY_HINT =
+  "if you are answering an operator who is waiting now, this is not the path: " +
+  "reply in their own topic with telegram_send (telegram_ask for a choice) — a held notice reaches nobody until then\n";
+
 /** The held-notice line names the future that releases it, in words an
  *  operator can act on: the working-hours window opening, or the daily digest.
  *  The earlier spelling — "the next digest or working-hours catch-up" — read
@@ -118,7 +140,8 @@ function heldLine(
     return (
       `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
       `held until the working-hours window opens${opening})\n` +
-      "nothing was sent; the daemon releases it with the working-hours catch-up when your window opens\n"
+      "nothing was sent; the daemon releases it with the working-hours catch-up when your window opens\n" +
+      LIVE_REPLY_HINT
     );
   }
   const digestAt = project.reporting?.digest.at;
@@ -126,6 +149,7 @@ function heldLine(
   return (
     `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
     `digest-only — held until ${when})\n` +
-    `nothing was sent; the daemon releases it with ${when}\n`
+    `nothing was sent; the daemon releases it with ${when}\n` +
+    LIVE_REPLY_HINT
   );
 }

package/src/commands/reconcile-units.ts

@@ -0,0 +1,104 @@
+/**
+ * `reconcile-units` — install the host unit files this version renders, and
+ * nothing else (#905).
+ *
+ * Scope: `"host"`. The units are host-global (one daemon serves every
+ * configured project), so this verb takes no project and reconciles the shared
+ * destinations. The per-project tail — tick config, brief link — stays
+ * `setup host`'s.
+ *
+ * It exists as its own verb because the render is code, not data: the upgrade
+ * transaction replaces the package underneath itself, so only a freshly
+ * spawned process can render what the new release ships. `upgrade` runs this
+ * verb with `--yes` after its install phase; an operator can run it by hand
+ * any time `doctor` reports `systemd-unit` drift.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig, resolveCaps } from "../config.ts";
+import { telegramStateDir } from "../fleet.ts";
+import {
+  planHostRuntime,
+  RECOVER_SCRIPT_INSTALL_PATH,
+  SYSTEMD_UNIT_DIR,
+  totalConfiguredWorkers,
+} from "../setup-host.ts";
+import {
+  formatUnitReconcile,
+  planUnitReconcile,
+  reconcileUnits,
+  UNIT_RECONCILE_ANSWER_KEY,
+} from "../unit-reconcile.ts";
+import { answersUi } from "../setup-answers.ts";
+import { terminalUi } from "../wizard-ui.ts";
+
+/** Repeatable `--protect PATH`: destinations this run must not overwrite. */
+function protectedPaths(argv: readonly string[]): string[] {
+  const paths: string[] = [];
+  for (const [index, arg] of argv.entries()) {
+    if (arg === "--protect") {
+      const value = argv[index + 1];
+      if (value !== undefined && !value.startsWith("--")) paths.push(value);
+    } else if (arg.startsWith("--protect=")) {
+      paths.push(arg.slice("--protect=".length));
+    }
+  }
+  return paths;
+}
+
+export async function reconcileUnitsCommand(ctx: CommandContext): Promise<void> {
+  const cfg = loadConfig();
+  // The units are host-global. A `--project` narrows only the per-project tail
+  // this verb deliberately does not write, so it is accepted (the recovery
+  // unit encodes one project's name on a single-project host) and ignored
+  // otherwise.
+  const project = ctx.projectFlag === undefined && cfg.projects.length !== 1
+    ? undefined
+    : findProject(cfg, ctx.projectFlag);
+  const plan = planHostRuntime(
+    project,
+    project === undefined ? cfg.defaults : resolveCaps(project, cfg.defaults),
+    telegramStateDir(),
+    undefined,
+    totalConfiguredWorkers(cfg),
+    SYSTEMD_UNIT_DIR,
+    RECOVER_SCRIPT_INSTALL_PATH,
+    cfg.projects.length > 1,
+  );
+  const protect = protectedPaths(ctx.argv);
+  // `--no-refresh` retires without refreshing (#895). The upgrade transaction
+  // uses it when it could not read a pre-install drift baseline: there a
+  // refresh cannot tell the operator's own edits from the upgrade's, but the
+  // retirement is not a comparison against any render and must still happen —
+  // otherwise a host that cannot be baselined keeps its obsolete mount forever.
+  const refresh = ctx.argv.includes("--no-refresh") === false;
+
+  if (ctx.argv.includes("--dry-run")) {
+    const preview = planUnitReconcile(plan, protect, refresh);
+    process.stdout.write(
+      preview.steps.length === 0
+        ? `${formatUnitReconcile({ kind: "current", protectedDrift: preview.protectedDrift, outOfScope: preview.outOfScope })}\n`
+        : `${[
+            "would reconcile:",
+            ...preview.retire.map((path) => `  retire ${path}`),
+            ...preview.refresh.map((d) => `  ${d.installed}  (from ${d.source})`),
+            ...preview.steps.map((s) => `  $ ${s.argv.join(" ")}`),
+          ].join("\n")}\n`,
+    );
+    return;
+  }
+
+  // `--yes` is the non-interactive consent the upgrade transaction carries:
+  // its operator already authorised the upgrade, and the detached installer
+  // has no terminal to prompt on. Interactive runs get the real confirm.
+  const ui = ctx.argv.includes("--yes")
+    ? answersUi({ [UNIT_RECONCILE_ANSWER_KEY]: true })
+    : terminalUi();
+  try {
+    const outcome = await reconcileUnits(plan, ui, { protect, refresh });
+    process.stdout.write(`${formatUnitReconcile(outcome)}\n`);
+    if (outcome.kind === "failed") process.exitCode = 1;
+  } finally {
+    ui.close();
+  }
+}