omp-conductor 0.15.9 → 0.15.11

package/src/commands/restart.ts

@@ -0,0 +1,76 @@
+/**
+ * `restart` — drain the fleet by default, then restart keeping the running daemon's port and project unless a flag overrides them.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { setPaused } from "../daemon.ts";
+import { restartDaemon, type RestartResult } from "../lifecycle.ts";
+import { DEFAULT_DEPS, drainAndRestart, type UpgradeDeps } from "../upgrade.ts";
+
+export async function restartCommand(ctx: CommandContext): Promise<void> {
+if (ctx.argv.includes("--now")) {
+  // Inherit the running daemon's port and project: a restart that quietly
+  // moved to the default port would leave every existing health check
+  // pointing at nothing. When the unit owns the live pid, restartDaemon
+  // goes through systemctl so the replacement stays supervised; a failed
+  // installed unit is reset and started through systemd the same way and
+  // is never replaced by an unmanaged daemon. Success is only reported
+  // after the manager is proven to own the reported pid.
+  const { previous, record, via } = await restartDaemon({
+    port: ctx.portFlag(),
+    project: ctx.projectFlag,
+  });
+  if (previous !== undefined) {
+    process.stdout.write(
+      `stopped — pid ${previous.pid}${via === "systemctl" ? " (via systemctl)" : ""}\n`,
+    );
+  }
+  process.stdout.write(
+    `started — pid ${record.pid}, /healthz on :${record.port}` +
+      `${record.project === undefined ? "" : `, project ${record.project}`}` +
+      `${via === "systemctl" ? " (via systemctl)" : ""}\nlog ${record.logFile}\n`,
+  );
+  return;
+}
+
+// Default: drain the fleet before restarting — pause new claims, wait for
+// live workers to reach 0/N (bounded by --timeout), restart, then restore
+// the prior dispatch state. A timed-out drain restarts nothing and leaves
+// dispatch paused, so it is safe to run while the daemon is wedged.
+const timeoutRaw = ctx.flag("timeout");
+const timeoutSeconds =
+  timeoutRaw === undefined ? 1800 : Number.parseInt(timeoutRaw, 10);
+const timeoutMs = (Number.isNaN(timeoutSeconds) ? 1800 : timeoutSeconds) * 1000;
+let result!: RestartResult;
+const deps: UpgradeDeps = {
+  ...DEFAULT_DEPS,
+  setPaused: (v, project) =>
+    setPaused(v, { source: "restart", reason: "restart, draining" }, project),
+  restartDaemon: async () => {
+    result = await restartDaemon({
+      port: ctx.portFlag(),
+      project: ctx.projectFlag,
+    });
+  },
+};
+try {
+  await drainAndRestart(deps, { project: ctx.projectFlag, timeoutMs });
+} catch (err) {
+  process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  process.exit(1);
+}
+if (result.previous !== undefined) {
+  process.stdout.write(
+    `stopped — pid ${result.previous.pid}${result.via === "systemctl" ? " (via systemctl)" : ""}\n`,
+  );
+}
+process.stdout.write(
+  `started — pid ${result.record.pid}, /healthz on :${result.record.port}` +
+    `${result.record.project === undefined ? "" : `, project ${result.record.project}`}` +
+    `${result.via === "systemctl" ? " (via systemctl)" : ""}\nlog ${result.record.logFile}\n`,
+);
+}

package/src/commands/resume.ts

@@ -0,0 +1,58 @@
+/**
+ * `resume` — clear pause and any pane-recovery pin. Does NOT re-arm.
+ *
+ * A running daemon is woken over its loopback control port so the resumed
+ * project is dispatched on a pass that starts immediately instead of after
+ * the five-minute tick (#380); when no daemon is alive there is nothing to
+ * wake and the output says so rather than implying an immediate pass happened.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { armState, clearPaneHaltIfResolvable, releaseHold } from "../fleet.ts";
+import { livingDaemon } from "../lifecycle.ts";
+
+/** Wakes a running daemon, returning the human line that states what happened.
+ *  State-only clients (no live daemon) get an honest fallback rather than an
+ *  error: the hold is already cleared and the next pass or daemon start
+ *  claims without this poke. */
+async function wakeDaemon(projectName: string): Promise<string> {
+  const daemon = livingDaemon();
+  if (daemon === undefined) {
+    return "daemon not running — claiming starts when the daemon next starts or ticks";
+  }
+  let response: Response;
+  try {
+    response = await fetch(`http://127.0.0.1:${daemon.port}/wake`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ project: projectName }),
+    });
+  } catch {
+    return "daemon wake failed — daemon unreachable; the next scheduled pass will claim";
+  }
+  if (!response.ok) {
+    return `daemon wake failed (HTTP ${response.status}); the next scheduled pass will claim`;
+  }
+  return "daemon dispatch loop woken — claiming starts on an immediate pass";
+}
+
+export async function resumeCommand(ctx: CommandContext): Promise<void> {
+for (const project of ctx.targetProjects()) {
+  releaseHold(project.name);
+  const pin = clearPaneHaltIfResolvable(project.name);
+  const arm = armState(project.name);
+  process.stdout.write(
+    `resumed — claiming allowed — ${await wakeDaemon(project.name)}\n` +
+      (pin.wasHalted
+        ? `pane recovery pin cleared — ${pin.path}\n`
+        : "no pane recovery pin to clear\n") +
+      (arm.armed
+        ? `ticks remain armed — marker ${arm.path}\n`
+        : "ticks stay disarmed — run `omp-conductor arm`\n"),
+  );
+}
+}

package/src/commands/setup.ts

@@ -0,0 +1,93 @@
+/**
+ * `setup` — interview, then write config.json, the labels, the briefs and the * staged host files behind one confirm.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig, resolveCaps } from "../config.ts";
+import { AMEND_AREA_IDS, type AmendAreaId } from "../setup.ts";
+import { runGraphInstall, runHostInstall } from "../setup-install.ts";
+import { DEFAULT_PROBES, NO_PROBES, setup } from "../setup-wizard.ts";
+import { telegramStateDir } from "../fleet.ts";
+import { terminalUi } from "../wizard-ui.ts";
+
+/**
+ * The setup verb's own usage, printed for `setup --help` / `setup -h` before
+ * any UI, config read, probe or area parsing. Areas come from `AMEND_AREA_IDS`
+ * rather than a second copy, so an added amend area appears both here and in
+ * the shared `USAGE` with no third spelling to keep in sync.
+ */
+const SETUP_USAGE = `omp-conductor setup — interview, then write config.json, the labels, the briefs
+and the staged host files behind one confirm.
+
+usage:
+  omp-conductor setup [area] [--no-ai] [--project NAME]
+
+  Bare setup runs the full interview — or, when the project already exists,
+  asks which area to amend. Naming an area positionally skips that chooser and
+  amends only that area.
+
+amend areas:
+  ${AMEND_AREA_IDS.join(", ")}
+
+flags:
+  --project NAME   the project to configure or amend
+  --no-ai          ask every question, propose nothing (no AI repo reads)`;
+
+export async function setupCommand(ctx: CommandContext): Promise<void> {
+// Help first, and only in the first trailing position: a help request
+// must never open a UI, read config, probe GitHub or pause dispatch.
+// `setup bogus --help` still rejects `bogus` as an unknown area, and
+// `setup caps --help` still names `caps` as the governing argument.
+if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+  process.stdout.write(`${SETUP_USAGE}\n`);
+  return;
+}
+const sub = ctx.argv[1];
+const positional = sub !== undefined && !sub.startsWith("--") ? sub : undefined;
+// The terminal surface owns stdin for whichever path runs, and is released
+// in a finally: a throw with readline still attached leaves the operator's
+// shell without an echo.
+const ui = terminalUi();
+try {
+  // `host` and `graph` are install subcommands, checked BEFORE the amend
+  // areas. They are not areas — routing them through the area validation
+  // is how `setup host` came to exit 2 as an "unknown setup area".
+  if (positional === "host" || positional === "graph") {
+    const cfg = loadConfig();
+    const project = findProject(cfg, ctx.projectFlag);
+    const outcome =
+      positional === "host"
+        ? await runHostInstall(project, resolveCaps(project, cfg.defaults), telegramStateDir(), ui)
+        : await runGraphInstall(project, ui, {
+            noSeed: ctx.argv.includes("--no-seed"),
+            print: ctx.argv.includes("--print"),
+          });
+    // `staged` is a success on a host that has no systemd: the files are
+    // real, only the enable step is impossible.
+    if (outcome.kind === "refused" || outcome.kind === "failed") process.exit(1);
+    return;
+  }
+  let area: AmendAreaId | undefined;
+  if (positional !== undefined) {
+    if (!(AMEND_AREA_IDS as readonly string[]).includes(positional)) {
+      process.stderr.write(
+        `omp-conductor: unknown setup argument "${positional}" — ` +
+          `install subcommands are host, graph; amend areas are ${AMEND_AREA_IDS.join(", ")}\n`,
+      );
+      process.exit(2);
+    }
+    area = positional as AmendAreaId;
+  }
+  // `--no-ai` is the interview with its reading half removed: every question
+  // is still asked, nothing is proposed. For a host with no omp peer, a
+  // private repo no probe can clone, or an operator who would rather type the
+  // gates than review a model's reading of their CI.
+  await setup(ui, ctx.projectFlag, area, ctx.argv.includes("--no-ai") ? NO_PROBES : DEFAULT_PROBES);
+} finally {
+  ui.close();
+}
+}

package/src/commands/start.ts

@@ -0,0 +1,23 @@
+/**
+ * `start` — start the installed herdr-fleet.service when present, then run the dispatch loop in the background and wait for /healthz.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { startHerdrFleet } from "../fleet.ts";
+import { startDaemon } from "../lifecycle.ts";
+
+export async function startCommand(ctx: CommandContext): Promise<void> {
+const project = ctx.projectFlag;
+const herdr = startHerdrFleet(project);
+const rec = await startDaemon({ port: ctx.portFlag(), project });
+process.stdout.write(
+  `started — pid ${rec.pid}, /healthz on :${rec.port}` +
+    `${rec.project === undefined ? "" : `, project ${rec.project}`}\n` +
+    `herdr ${herdr.kind === "active" ? `active (${herdr.unit})${herdr.recoveryReleased ? "; recovery pin cleared" : ""}` : `unmanaged (${herdr.reason})`}\n` +
+    `log ${rec.logFile}\n`,
+);
+}

package/src/commands/stats.ts

@@ -0,0 +1,131 @@
+/**
+ * `stats` — what the fleet accomplished and at what cost over a window (#282,
+ * legibility 5/5).
+ *
+ * The aggregation lives in ../stats.ts, pure over injected store rows; this
+ * module only parses the flags, reads the local store read-only, and renders
+ * the same report the --json shape carries. Nothing here touches GitHub or any
+ * other network surface: the window, runs, spend and gh-call counts all come
+ * from SQLite on this host.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, openStore, utcDay } from "../store.ts";
+import { computeStats, renderStatsHuman, type StatsWindow } from "../stats.ts";
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const DATE_FORM = /^\d{4}-\d{2}-\d{2}$/;
+const DURATION_FORM = /^(\d{1,3})d$/;
+
+const STATS_USAGE = `omp-conductor stats — what the fleet accomplished and at what cost.
+
+usage:
+  omp-conductor stats [--since 7d|30d|YYYY-MM-DD] [--project NAME] [--json]
+
+Reads only the local store — zero GitHub calls. Over a bounded window it
+reports, per repo and in total: issues merged, issues settled (merged or
+terminally failed/blocked), merge rate, queue-to-merge lead time (median and
+p90, from the first claim of the issue's continuation chain to the tick's
+merge settlement), attempts per merged issue, metered spend per merged issue,
+the failure-class breakdown of everything that did not merge, and the tracked
+GitHub API calls consumed over the window's days.
+
+Continuation chains collapse into one journey: an issue that took six attempts
+is one merged outcome with six runs and one lead time. Runs whose spend reads
+$0.00 — harness telemetry absent (README Limitations) — are counted separately
+as unmetered and never averaged into cost as if they were free.
+
+flags:
+  --since 7d | 30d | YYYY-MM-DD   window start (default 7d)
+  --json                          print the stable report shape {project,
+                                  window, ghCalls, empty, total, repos} — keys
+                                  never move, so a consumer can rely on it
+  --project NAME                  the project to report (required only when
+                                  the config has more than one)
+
+When nothing settled in the window the report says so explicitly ("empty:
+true" in --json) rather than printing zeros that could read as measurements.`;
+
+/** `--since` to a window. The bare date form means from 00:00:00Z of that day;
+ *  the duration form (`7d`) is now minus whole days. Anything else exits 2,
+ *  because silently defaulting a typo'd window would measure the wrong week. */
+function sinceWindow(raw: string, now: number): Pick<StatsWindow, "sinceDay" | "sinceEpochMs"> {
+  const duration = DURATION_FORM.exec(raw);
+  if (duration !== null) {
+    const days = Number(duration[1]);
+    if (days >= 1) {
+      const sinceEpochMs = now - days * DAY_MS;
+      return { sinceEpochMs, sinceDay: utcDay(sinceEpochMs) };
+    }
+  }
+  if (DATE_FORM.test(raw)) {
+    const sinceEpochMs = Date.parse(`${raw}T00:00:00Z`);
+    if (Number.isFinite(sinceEpochMs)) {
+      return { sinceEpochMs, sinceDay: raw };
+    }
+  }
+  process.stderr.write(
+    `omp-conductor: stats --since needs 7d, 30d or YYYY-MM-DD, got "${raw}"\n`,
+  );
+  process.exit(2);
+}
+
+export async function statsCommand(ctx: CommandContext): Promise<void> {
+  // Help first: parsing stops before any config read or store open.
+  if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+    process.stdout.write(`${STATS_USAGE}\n`);
+    return;
+  }
+  // Every remaining token after the verb is accounted for: the flag presence
+  // markers plus the two value flags cli.ts already parsed.
+  const STATS_FLAGS: Record<string, true> = {
+    "--json": true,
+    "--since": true,
+    "--project": true,
+  };
+  for (let i = 1; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    // `--since 7d` and `--since=7d` are both legal — cli.ts's flag helper
+    // accepts the prefixed form, so the scan must too.
+    if (
+      STATS_FLAGS[token] !== true &&
+      !token.startsWith("--since=") &&
+      !token.startsWith("--project=")
+    ) {
+      process.stderr.write(`omp-conductor: stats: unexpected argument "${token}"\n`);
+      process.exit(2);
+    }
+    if (token === "--since" || token === "--project") i += 1;
+  }
+
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const now = Date.now();
+  const rawSince = ctx.flag("since");
+  if (rawSince === undefined && ctx.argv.includes("--since")) {
+    process.stderr.write(`omp-conductor: stats --since needs 7d, 30d or YYYY-MM-DD\n`);
+    process.exit(2);
+  }
+  const window: StatsWindow = {
+    ...sinceWindow(rawSince ?? "7d", now),
+    untilEpochMs: now,
+    untilDay: utcDay(now),
+  };
+  const store = openStore(dbPath());
+  try {
+    const report = computeStats({
+      project: project.name,
+      window,
+      ghCalls: store.ghCallsBetween(window.sinceDay, window.untilDay),
+      runs: store.statsRuns(project.name, window.sinceEpochMs),
+    });
+    process.stdout.write(
+      ctx.argv.includes("--json")
+        ? `${JSON.stringify(report, null, 2)}\n`
+        : renderStatsHuman(report),
+    );
+  } finally {
+    store.close();
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,48 @@
+/**
+ * `status` — layered fleet report: dispatch, ticks, pane, herdr, Telegram target, daemon, caps and active runs.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { stateDir } from "../config.ts";
+import { renderStatus } from "../fleet.ts";
+import { STALL_MARKER_FILE } from "../orchestrator-tick.ts";
+
+/**
+ * The orchestrator half, and the one thing `status` has ever known about the
+ * supervising session: the stall marker its heartbeat writes when its own
+ * prompts stop being consumed (see {@link STALL_MARKER_FILE}).
+ *
+ * The marker is written in the *session's* cwd, which this process has no way
+ * to discover — so this reads the state directory, on the reference deploy's
+ * convention that the orchestrator session runs from exactly there. That makes
+ * the reading one-directional: a line printed here is proof of a wedge, and no
+ * line is proof of nothing at all. On a fleet whose session lives elsewhere the
+ * check is simply inert, which is why it never prints a reassuring "healthy".
+ */
+function stallLine(): string | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(join(stateDir(), STALL_MARKER_FILE), "utf8").trim();
+  } catch {
+    return undefined;
+  }
+  // "<ISO timestamp> <one-line diagnosis>". A file truncated by something else
+  // still gets reported: that the marker exists at all is the news.
+  const cut = raw.indexOf(" ");
+  const since = cut < 0 ? raw : raw.slice(0, cut);
+  const diagnosis = cut < 0 ? "" : ` — ${raw.slice(cut + 1)}`;
+  return `orchestrator   STALLED since ${since === "" ? "an unrecorded time" : since}${diagnosis}`;
+}
+
+export async function statusCommand(ctx: CommandContext): Promise<void> {
+const project = ctx.projectFlag;
+const text = await renderStatus(project);
+const stalled = stallLine();
+process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${stalled}\n`}`);
+}

package/src/commands/stop.ts

@@ -0,0 +1,51 @@
+/**
+ * `stop` — stop the conductor: pause claiming, disarm ticks, then stop the dispatch daemon. Pane stays up unless --pane is passed.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { hold, pinPaneHalt, stopConductorPane } from "../fleet.ts";
+import { stopDaemon } from "../lifecycle.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 stop = await stopDaemon();
+const stopLine =
+  stop.kind === "not-running"
+    ? "daemon was not running"
+    : `daemon stopped — pid ${stop.pid}${stop.via === "systemctl" ? " (via systemctl)" : ""}`;
+for (const target of targets) {
+  if (target.pin !== undefined) {
+    const pane = await stopConductorPane(target.project.name);
+    process.stdout.write(
+      `stopped — claiming paused; ticks disarmed at ${target.hold.disarmed.path}\n` +
+        `${stopLine}\n` +
+        `pane recovery pinned at ${target.pin}\n` +
+        `pane stop: ${pane.stopped} — ${pane.detail}\n` +
+        `  (conductor agent "${pane.agentName}" only — herdr-fleet.service was NOT stopped;\n` +
+        `   resume clears the pin when you want recovery again)\n`,
+    );
+  } else {
+    process.stdout.write(
+      `stopped — claiming paused; ticks disarmed at ${target.hold.disarmed.path}\n` +
+        `${stopLine}\n` +
+        `pane left running (pass --pane to stop the conductor agent and pin recovery)\n`,
+    );
+  }
+}
+}

package/src/commands/tail.ts

@@ -0,0 +1,109 @@
+/**
+ * `tail` — follow the newest run for an issue the way `tail -f` follows a log, finishing once the run has left the live states.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, LIVE_STATES, openStore } from "../store.ts";
+import { formatTranscriptLine } from "../transcript.ts";
+
+/** How often `tail` re-stats the transcript it is following. */
+const TAIL_POLL_MS = 1_000;
+
+/**
+ * How long the transcript must stay unchanged, after its run has left the live
+ * states, before `tail` calls it over. The state flips from the daemon's thread
+ * while the harness may still be flushing its last message, so exiting on the
+ * state alone truncates the ending an operator ran this command to watch.
+ */
+const TAIL_QUIET_MS = 5_000;
+
+/**
+ * Follow one run's transcript the way `tail -f` follows a log.
+ *
+ * Reads from byte zero rather than from the end: attaching to a worker that is
+ * already ten turns in and then showing nothing until turn eleven is not
+ * watching the run. Polls `stat` instead of taking a file watcher because the
+ * transcript is a plain append-only file that may sit on a filesystem where
+ * change events are a polite fiction, and one stat a second costs nothing.
+ *
+ * SIGINT is deliberately left to its default, which is immediate exit. Nothing
+ * here is buffered, and a handler could only add a poll interval of latency to
+ * every Ctrl-C.
+ */
+async function tailRun(project: string, issue: number): Promise<void> {
+  // Read-only in practice: the store is opened WAL with a busy timeout, so this
+  // never contends with the daemon writing the same rows.
+  const store = openStore(dbPath());
+  try {
+    const run = store.latestRun(project, issue);
+    if (run === undefined) throw new Error(`no run recorded for #${issue}`);
+    const path = run.sessionFile;
+    // Claimed but not yet started, or an attempt whose session never opened one.
+    if (path === undefined) throw new Error(`no transcript yet (state: ${run.state})`);
+
+    const fd = openSync(path, "r");
+    try {
+      let offset = 0;
+      let pending = Buffer.alloc(0);
+      let lastChange = Date.now();
+
+      for (;;) {
+        let size = offset;
+        try {
+          size = statSync(path).size;
+        } catch {
+          // A transcript that vanishes mid-follow is not worth crashing over.
+          // The run's own state, below, is what decides when this command ends.
+        }
+        // Shorter than what we have already read means truncated or replaced;
+        // resuming from the old offset would read the middle of another file.
+        if (size < offset) {
+          offset = 0;
+          pending = Buffer.alloc(0);
+        }
+        if (size > offset) {
+          const chunk = Buffer.allocUnsafe(size - offset);
+          const read = readSync(fd, chunk, 0, chunk.length, offset);
+          offset += read;
+          // Split on newlines as bytes, not as text: a UTF-8 sequence straddling
+          // a read boundary would be mangled by decoding each chunk on its own.
+          pending = Buffer.concat([pending, chunk.subarray(0, read)]);
+          for (;;) {
+            const nl = pending.indexOf(0x0a);
+            if (nl < 0) break;
+            const rendered = formatTranscriptLine(pending.subarray(0, nl).toString("utf8"));
+            pending = pending.subarray(nl + 1);
+            if (rendered !== undefined) process.stdout.write(`${rendered}\n`);
+          }
+          if (read > 0) lastChange = Date.now();
+        }
+
+        // Re-read this exact run every poll — not `latestRun`, which would jump
+        // to a retry started meanwhile and report its state against the wrong
+        // transcript. The daemon writes the row from another process, so looking
+        // is the only way to notice the run finished.
+        const state = store.getRun(run.id)?.state ?? run.state;
+        if (!LIVE_STATES.includes(state) && Date.now() - lastChange >= TAIL_QUIET_MS) {
+          process.stdout.write(`run ended: ${state}\n`);
+          return;
+        }
+        await new Promise<void>((resolve) => setTimeout(resolve, TAIL_POLL_MS));
+      }
+    } finally {
+      closeSync(fd);
+    }
+  } finally {
+    store.close();
+  }
+}
+
+export async function tailCommand(ctx: CommandContext): Promise<void> {
+const issue = ctx.issueArg("tail", ctx.argv[1]);
+await tailRun(findProject(loadConfig(), ctx.projectFlag).name, issue);
+}

package/src/commands/unblock.ts

@@ -0,0 +1,39 @@
+/**
+ * `unblock` — clear an issue's blocked and failed labels and restore its queue label so the next tick can claim it again.
+ *
+ * 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
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig, resolveCaps } from "../config.ts";
+import { dbPath, openStore } from "../store.ts";
+import { makeTracker } from "../tracker/github.ts";
+import { formatUnblock, unblockIssue } from "../unblock.ts";
+
+export async function unblockCommand(ctx: CommandContext): Promise<void> {
+const issue = ctx.issueArg("unblock", ctx.argv[1]);
+const cfg = loadConfig();
+const project = findProject(cfg, ctx.projectFlag);
+const store = openStore(dbPath());
+try {
+  const caps = resolveCaps(project, cfg.defaults);
+  const outcome = await unblockIssue(
+    project,
+    makeTracker(project),
+    store,
+    issue,
+    {
+      force: ctx.argv.includes("--force"),
+      requeue: !ctx.argv.includes("--no-requeue"),
+    },
+    caps,
+  );
+  process.stdout.write(`${formatUnblock(issue, outcome, project, caps)}\n`);
+  // A refusal must not read as success to a script or a board keypress.
+  if (outcome.refused !== undefined) process.exitCode = 3;
+} finally {
+  store.close();
+}
+}

package/src/commands/upgrade-install.ts

@@ -0,0 +1,31 @@
+/**
+ * `upgrade-install` — run the upgrade transaction as the detached fleet
+ * installer (#486): the same engine as `upgrade`, with every surface journaled
+ * and the in-process verification and dispatch restore handed to the first
+ * tick of the post-restart daemon.
+ *
+ * This is the command the transient unit spawned by `conductor_install` runs —
+ * a process in the system manager, outside the pane's process tree and the
+ * daemon's cgroup, so the restarts the transaction performs pass it by. It is
+ * not for typing in a pane: like `upgrade`, it refuses to run inside the
+ * target Herdr session, because a process the restart kills cannot verify
+ * what it installed.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { runDetachedUpgrade } from "../upgrade.ts";
+
+export async function upgradeInstallCommand(ctx: CommandContext): Promise<void> {
+const result = await runDetachedUpgrade({
+  version: ctx.flag("to"),
+  project: ctx.projectFlag,
+});
+process.stdout.write(
+  `install complete — awaiting first-tick verification:\n` +
+    `  Bun-global 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` +
+    `  dispatch           paused — the first tick after the restart verifies and restores it\n`,
+);
+}