omp-conductor 0.18.2 → 0.19.0

package/src/ask.ts

@@ -27,7 +27,7 @@
  * decision — nothing here reopens that clock.
  */
 
-import type { DecisionRecord, InterruptCategory, Store } from "./types.ts";
+import type { DecisionRecord, DecisionState, InterruptCategory, Store } from "./types.ts";
 import { INTERRUPT_CATEGORIES } from "./types.ts";
 
 /** The bounded ask tool this package registers on an orchestrator session. */
@@ -373,6 +373,34 @@ export function askParameterSchema(): Record<string, unknown> {
   };
 }
 
+/**
+ * The questionnaire tool's arguments (#947): the spec it belongs to, plus items
+ * that are each exactly one {@link askParameterSchema}. Composed rather than
+ * restated, so an item can never accept something a single ask refuses.
+ */
+export function questionnaireParameterSchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    properties: {
+      "spec-issue": {
+        type: "number",
+        description:
+          "The issue these questions spec out. The answers become that issue's provenance, so a later reader sees why a slice is shaped the way it is instead of re-litigating it.",
+      },
+      items: {
+        type: "array",
+        minItems: 1,
+        maxItems: MAX_QUESTIONNAIRE_ITEMS,
+        description:
+          "The judgement calls only — anything a repo read can answer is your own work, not an operator question. Delivered as one message, answerable in any order, each item resolving independently.",
+        items: askParameterSchema(),
+      },
+    },
+    required: ["spec-issue", "items"],
+    additionalProperties: false,
+  };
+}
+
 /**
  * The ceiling for one ask, in whole seconds. The model may name one, but the
  * enforcement never depends on it: an ask without a `timeoutSeconds` gets the
@@ -411,6 +439,149 @@ export function askMessageFor(request: AskRequest): string {
   return lines.join("\n");
 }
 
+/** The tool name a spec-out questionnaire arrives on (#947). */
+export const QUESTIONNAIRE_TOOL = "conductor_questionnaire";
+
+/** How many items one delivery may carry. A questionnaire longer than this is
+ *  not a questionnaire, it is an interview the operator will abandon halfway —
+ *  and the ceiling that bounds the whole group is one ask's, not one per item. */
+export const MAX_QUESTIONNAIRE_ITEMS = 6;
+
+/**
+ * One spec-out questionnaire (#947): several questions about ONE issue,
+ * delivered together and answerable in any order.
+ *
+ * It is deliberately N {@link AskRequest}s plus a spec binding rather than a
+ * new question shape. Every per-item semantic a spec-out needs — options, a
+ * recommendation, `auto-proceed` versus `park`, the shape ceiling, the
+ * auto-applied marker — already exists and is already tested here; what did not
+ * exist is asking six of them once. Re-deriving those semantics for a
+ * "questionnaire item" would be the same contract in two places, and the second
+ * copy is the one that drifts.
+ */
+export interface QuestionnaireRequest {
+  /** The issue these questions spec out; their answers are its provenance. */
+  specIssue: number;
+  /** The items, in delivery order. Each is an ordinary bounded ask. */
+  items: AskRequest[];
+}
+
+type QuestionnaireParse =
+  | { ok: true; request: QuestionnaireRequest }
+  | { ok: false; problem: string };
+
+/**
+ * Validate one questionnaire call. Strict exactly like {@link parseAskRequest},
+ * and every item is validated through it — including the shape ceiling, which
+ * refuses the **whole group** rather than truncating or dropping one item. A
+ * partially accepted questionnaire would deliver a question set that does not
+ * match the rows behind it, which is the one failure this whole feature exists
+ * to prevent.
+ */
+export function parseQuestionnaireRequest(raw: unknown): QuestionnaireParse {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ok: false, problem: `${QUESTIONNAIRE_TOOL} arguments must be an object` };
+  }
+  const record = raw as Record<string, unknown>;
+  const known = new Set(["spec-issue", "items"]);
+  for (const key of Object.keys(record)) {
+    if (!known.has(key)) {
+      return { ok: false, problem: `unknown argument "${key}" — expected spec-issue and items` };
+    }
+  }
+  const specIssue = record["spec-issue"];
+  if (typeof specIssue !== "number" || !Number.isInteger(specIssue) || specIssue <= 0) {
+    return {
+      ok: false,
+      problem: 'spec-issue must be the issue number these questions spec out — a questionnaire whose answers belong to nothing is chat history, not provenance',
+    };
+  }
+  const items = record["items"];
+  if (!Array.isArray(items) || items.length === 0) {
+    return { ok: false, problem: "items must be a non-empty array of questions" };
+  }
+  if (items.length > MAX_QUESTIONNAIRE_ITEMS) {
+    return {
+      ok: false,
+      problem: `${items.length} items — over the ${MAX_QUESTIONNAIRE_ITEMS}-item ceiling. Ask the judgement calls only; anything a repo read answers is not an operator question`,
+    };
+  }
+  const parsed: AskRequest[] = [];
+  for (const [index, item] of items.entries()) {
+    const one = parseAskRequest(item);
+    if (!one.ok) return { ok: false, problem: `item ${index + 1}: ${one.problem}` };
+    const shape = validateQuestionShape(one.request.question);
+    if (!shape.ok) return { ok: false, problem: `item ${index + 1}: ${shape.problem}` };
+    parsed.push(one.request);
+  }
+  return { ok: true, request: { specIssue, items: parsed } };
+}
+
+/**
+ * The questionnaire exactly as it is delivered: **one** message, its items
+ * numbered so an operator can answer them in any order by naming the number.
+ *
+ * One delivery is the point. N deliveries would be N interrupts for one
+ * decision, which is what the serial workaround already did and why nothing was
+ * ever answered as a set.
+ */
+export function questionnaireMessageFor(request: QuestionnaireRequest): string {
+  const lines = [`QUESTION: ${request.items.length} calls to spec out #${request.specIssue} — answer by number, in any order.`];
+  for (const [index, item] of request.items.entries()) {
+    const parts = [`${index + 1}. ${item.question}`];
+    if (item.options !== undefined && item.options.length > 0) {
+      parts.push(
+        `   options: ${item.options
+          .map((option) => (option.description === undefined ? option.label : `${option.label} — ${option.description}`))
+          .join("; ")}`,
+      );
+    }
+    if (item.recommended !== undefined) parts.push(`   rec: ${item.recommended}`);
+    // Silence is a real outcome, so it is stated per item rather than once for
+    // the group: a questionnaire may legitimately mix "proceed on my
+    // recommendation" with "this one waits for you".
+    parts.push(
+      `   on silence: ${
+        item.onTimeout === "auto-proceed" ? `applies ${item.recommended ?? "the recommendation"}` : "stays open"
+      }`,
+    );
+    lines.push(parts.join("\n"));
+  }
+  return lines.join("\n");
+}
+
+/** What the ceiling did to one still-open item. */
+export type QuestionnaireItemTimeout =
+  | { kind: "auto-applied"; id: string; resolution: string }
+  | { kind: "parked"; id: string };
+
+/**
+ * Apply the ceiling to a questionnaire, per item (#947).
+ *
+ * Pure, and per item on purpose. The group is one delivery but N decisions: an
+ * item the operator answered keeps that answer, an `auto-proceed` item resolves
+ * with the existing auto-applied marker so the record never reads as a human
+ * choice, and a `park` item stays open. Resolving the group atomically — all or
+ * nothing — would discard the answers the operator did give, which is the
+ * second silent fake this feature has to avoid.
+ */
+export function resolveQuestionnaireTimeouts(
+  items: readonly { id: string; request: AskRequest; answered: boolean }[],
+): QuestionnaireItemTimeout[] {
+  const outcomes: QuestionnaireItemTimeout[] = [];
+  for (const item of items) {
+    if (item.answered) continue;
+    if (item.request.onTimeout === "auto-proceed" && item.request.recommended !== undefined) {
+      outcomes.push({ kind: "auto-applied", id: item.id, resolution: autoApplyResolution(item.request.recommended) });
+      continue;
+    }
+    // `park` — and the impossible-by-parse `auto-proceed` with no
+    // recommendation, which parks rather than inventing one.
+    outcomes.push({ kind: "parked", id: item.id });
+  }
+  return outcomes;
+}
+
 /**
  * The interactive surface a bounded ask posts through when one is available
  * (#722): the same Bot API `reply_markup` `telegram_ask` posts, whose taps are
@@ -776,3 +947,119 @@ export async function performAsk(request: AskRequest, deps: AskDeps): Promise<As
 
   return { outcome, decisionId: row.id, text: `${delivered}\n${text}` };
 }
+
+/** What one {@link QUESTIONNAIRE_TOOL} call produced, per item and as text. */
+export interface QuestionnaireResult {
+  /** The minted group id — the handle for `omp-conductor decision` on any item. */
+  groupId: string;
+  items: { id: string; question: string; state: DecisionState; resolution?: string }[];
+  text: string;
+}
+
+/**
+ * Ask one bounded spec-out questionnaire (#947).
+ *
+ * The shape mirrors {@link performAsk} deliberately — rows before delivery, one
+ * bounded wait, per-item timeout policy applied at the ceiling — with two
+ * differences that are the whole feature:
+ *
+ * 1. **One delivery.** The items go out as a single numbered message, so a
+ *    questionnaire costs one interrupt rather than N.
+ * 2. **N independent resolutions.** The wait ends when every item is closed or
+ *    the ceiling elapses, and the ceiling then applies each item's own policy.
+ *    An item the operator answered keeps that answer.
+ *
+ * It uses the durable text path rather than posting N interactive keyboards,
+ * because N posts is exactly the thing it exists not to do. That means a prose
+ * reply is not itself a row resolution — the same contract a degraded single ask
+ * already has — so the result text names the ids and the command that resolves
+ * them.
+ */
+export async function performQuestionnaire(
+  request: QuestionnaireRequest,
+  deps: AskDeps,
+): Promise<QuestionnaireResult> {
+  const now = deps.now ?? Date.now;
+  const wait = deps.wait ?? sleep;
+
+  // Every row durable, in one transaction, BEFORE the delivery: an operator must
+  // never be shown a question that no row is waiting on.
+  const rows = deps.store.createDecisionGroup(
+    request.items.map((item) => ({
+      project: deps.project,
+      question: item.question,
+      ...(item.blocks === undefined ? {} : { blocks: item.blocks }),
+      at: now(),
+    })),
+    request.specIssue,
+  );
+  const groupId = rows[0]!.groupId!;
+
+  const category = request.items[0]!.category ?? "decision-needed";
+  const delivery = await deps.deliver(questionnaireMessageFor(request), category);
+
+  const ceilingSeconds = resolveAskCeilingSeconds(
+    // One ceiling for the group, taken from the shortest item that named one:
+    // the whole point is that a questionnaire cannot wait longer than an ask.
+    request.items.reduce<number | undefined>(
+      (shortest, item) =>
+        item.timeoutSeconds === undefined ? shortest : Math.min(shortest ?? item.timeoutSeconds, item.timeoutSeconds),
+      undefined,
+    ),
+    deps.configuredCeilingSeconds,
+    deps.turnBudgetSeconds ?? DEFAULT_ASK_TIMEOUT_SECONDS,
+  );
+  const deadline = now() + ceilingSeconds * 1_000;
+  for (;;) {
+    const live = deps.store.decisionGroup(groupId);
+    if (live.every((row) => row.state !== "open")) break;
+    if (now() >= deadline) break;
+    await wait(ASK_POLL_MS);
+  }
+
+  // The ceiling, per item. `resolveDecision` refuses a second resolution, so an
+  // answer that landed in the same instant as the deadline is never overwritten.
+  const atCeiling = deps.store.decisionGroup(groupId);
+  for (const outcome of resolveQuestionnaireTimeouts(
+    atCeiling.map((row, index) => ({
+      id: row.id,
+      request: request.items[index]!,
+      answered: row.state !== "open",
+    })),
+  )) {
+    if (outcome.kind === "auto-applied") {
+      deps.store.resolveDecision(outcome.id, "answered", outcome.resolution, now());
+    }
+  }
+
+  const final = deps.store.decisionGroup(groupId);
+  const items = final.map((row) => ({
+    id: row.id,
+    question: row.question,
+    state: row.state,
+    ...(row.resolution === undefined ? {} : { resolution: row.resolution }),
+  }));
+  const open = items.filter((item) => item.state === "open");
+  const deliveryLine =
+    delivery.kind === "sent"
+      ? `The questionnaire went to the operator as one ${delivery.category} message.`
+      : `The questionnaire is durably held (notice ${delivery.noticeId ?? "?"}, ${delivery.category}); the ` +
+        "daemon releases it with the next digest or working-hours catch-up.";
+  const perItem = items
+    .map(
+      (item, index) =>
+        `${index + 1}. ${item.state}${item.resolution === undefined ? "" : ` — ${item.resolution}`} (${item.id})`,
+    )
+    .join("\n");
+  const closing =
+    open.length === 0
+      ? "Every item is resolved. Apply the answers to the spec now."
+      : `${open.length} item(s) stayed open as declared: park the work each one blocks, and note them in your ` +
+        "report. A prose reply does NOT resolve these rows — map it yourself with " +
+        "`omp-conductor decision resolve <id> --answer \"…\"`.";
+  return {
+    groupId,
+    items,
+    text: `${deliveryLine} Ceiling ${ceilingSeconds}s; #${request.specIssue}.\n${perItem}\n${closing}`,
+  };
+}

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`

package/src/cli.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";
@@ -265,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),
@@ -284,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),

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,12 +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]",
     ],
     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: [
@@ -117,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()],
   },
   {
@@ -134,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",
@@ -292,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",

package/src/commands/arm.ts

@@ -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/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();
+  }
+}