omp-conductor 0.19.1 → 0.19.3

package/REFERENCE.md

@@ -2225,7 +2225,7 @@ Field notes:
 | `tracker.repo` | `owner/repo`. `tracker.kind` may be omitted; `"github"` is the only accepted value. |
 | `queueLabel` | The one label meaning "a human has signed this off as agent-ready". Matched exactly, case-sensitively. |
 | `release.versionFile` | Optional, per repo: a repo-relative JSON file with a top-level string `version`, such as `omp/package.json`. Declares that tags must match the version already landed on the live default branch. A delegated `git-tag` for such a repo requires delegated `version-bump-pr` too; otherwise config loading fails with the missing preparation path instead of granting an impossible release. Absolute paths and `..` are refused. |
-| `groomBelow` | Optional; default `4`. Routable candidates below this count make the orchestrator's tick prompt say the queue is running low and to groom it (Duty 2). An integer ≥ 1; anything else degrades to the default. |
+| `groomBelow` | Optional; default `4`. Routable candidates below this count make the orchestrator's tick prompt say the queue is running low and to groom it (Duty 2). An integer ≥ 1, or the literal `"always"` (#988) — groom on demand every tick while any ungroomed, unrefused, unparked candidate exists, whatever the queue volume. Anything else fails the config load. |
 | `stateLabels` | Optional; defaults to `agent:in-progress`, `agent:blocked`, `agent:failed`. |
 | `routing.labelPrefix` | Optional; defaults to `repo:`. |
 | `routing.repos` | At least one entry, or nothing can be routed. `name` defaults to the map key, `defaultBranch` to `main`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.19.1",
+  "version": "0.19.3",
   "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.",
@@ -29,7 +29,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "check": "tsc --noEmit && bun run src/check-trailing-newlines.ts",
+    "check": "tsc --noEmit && bun run src/check-trailing-newlines.ts && bun run src/check-browser-js.ts",
     "test": "bun test",
     "schema": "bun run src/generate-schema.ts"
   },

package/schema/config.schema.json

@@ -171,7 +171,19 @@
             "type": "string",
             "minLength": 1
           },
-          "groomBelow": {},
+          "groomBelow": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "string",
+                "const": "always"
+              }
+            ]
+          },
           "stateLabels": {
             "type": "object",
             "properties": {

package/src/arm-challenge.ts

@@ -156,6 +156,30 @@ function challengeHash(code: string): string {
   return createHash("sha256").update(code).digest("hex");
 }
 
+/**
+ * The state key of a whole-fleet ceremony (#991): one challenge that arms every
+ * configured project on a single matching reply.
+ *
+ * A NUL byte, so it can never collide with a project name — `encodeProjectKey`
+ * escapes it to hex, and no configured project can produce the same file. The
+ * empty string was unavailable: that is already the key of a legacy unstamped
+ * config, and a fleet record must not shadow one.
+ */
+export const FLEET_ARM_KEY = "\u0000fleet";
+
+/**
+ * Whether a token looks like a challenge code at all.
+ *
+ * This is what makes a reply answerable without knowing any code: the codes are
+ * `FLEET-` plus hex (see `makeChallengeCode`), so a token of that shape is an
+ * arming attempt whether or not it matches, while ordinary chat is left alone.
+ * Only the shape is inspected — the token itself is never hashed against
+ * anything but a pending record, never logged, and never echoed.
+ */
+export function looksLikeChallengeCode(token: string): boolean {
+  return /^FLEET-[0-9A-Fa-f]{4,32}$/.test(token);
+}
+
 /**
  * Acknowledgement files outliving their transaction — a crash between the
  * adapter's write and the host's settle — are inert by construction: no
@@ -225,26 +249,78 @@ export function recordArmChallenge(
  * host settle all fail closed without touching anyone else's handshake, and
  * two projects acknowledging concurrently cannot clobber each other.
  */
-export function acknowledgeArmReply(project: string | undefined, replyText: string, now: number): boolean {
-  const pending = readPendingFor(projectKey(project));
-  if (pending === undefined) return false;
-  if (now >= pending.expiresAt) return false;
+/**
+ * What an inbound reply was, so the adapter can answer it (#991).
+ *
+ * Before this, a non-matching or expired code was simply ignored: the waiter
+ * kept waiting and the operator had no idea they had been heard. The fastest
+ * way to be sure you held the current code was to scroll the chat, which is
+ * exactly the work conductor-owned verification was supposed to end.
+ *
+ * - `matched` — an active proof; the acknowledgement is written.
+ * - `expired` — a code that hashes to a pending record whose window has closed.
+ * - `unknown` — a challenge-shaped token that matches nothing readable here.
+ * - `none` — no challenge-shaped token at all: ordinary chat, answer nothing.
+ */
+export type ArmReplyVerdict = "matched" | "expired" | "unknown" | "none";
+
+/**
+ * Classify one inbound reply against this session's own records, writing the
+ * acknowledgement on a match.
+ *
+ * Two records are consulted and no others: this project's, and the fleet-wide
+ * one (#991). That bound is the non-disclosure property — a reply that matches
+ * nothing here can never reveal that a *different* project has a live
+ * challenge, because no other project's record is ever read.
+ *
+ * Fail-closed ordering is unchanged: the project's own active challenge wins,
+ * then the fleet ceremony, and an expired record is never a proof.
+ */
+export function classifyArmReply(
+  project: string | undefined,
+  replyText: string,
+  now: number,
+): ArmReplyVerdict {
   // Challenge codes contain no whitespace, so tokenising on whitespace never
   // splits one; empty replies simply yield no token.
-  const targetHash = pending.hash;
-  let matched = false;
-  for (const token of replyText.trim().split(/\s+/)) {
-    if (token.length > 0 && challengeHash(token) === targetHash) {
-      matched = true;
-      break;
+  const tokens = replyText.trim().split(/\s+/).filter((token) => token.length > 0);
+  if (tokens.length === 0) return "none";
+  const candidates = [readPendingFor(projectKey(project)), readPendingFor(FLEET_ARM_KEY)].filter(
+    (pending): pending is PendingChallenge => pending !== undefined,
+  );
+
+  let expired = false;
+  for (const token of tokens) {
+    const hash = challengeHash(token);
+    for (const pending of candidates) {
+      if (pending.hash !== hash) continue;
+      if (now >= pending.expiresAt) {
+        // Keep looking: a fresh record for the same code is a proof, and only
+        // an exhausted search may conclude "expired".
+        expired = true;
+        continue;
+      }
+      // Keyed by the challenge id, so replays overwrite the one record the
+      // single live waiter consumes; a stale id's file can never be created
+      // here.
+      const record: ArmAcknowledgement = { challengeId: pending.id, acknowledgedAt: now };
+      writeFileAtomic(ackPath(pending.id), `${JSON.stringify(record)}\n`);
+      return "matched";
     }
   }
-  if (!matched) return false;
-  // Keyed by the challenge id, so replays overwrite the one record the single
-  // live waiter consumes; a stale id's file can never be created here.
-  const record: ArmAcknowledgement = { challengeId: pending.id, acknowledgedAt: now };
-  writeFileAtomic(ackPath(pending.id), `${JSON.stringify(record)}\n`);
-  return true;
+  if (expired) return "expired";
+  // Shape only, and only to decide whether the operator gets an answer. A token
+  // that is not challenge-shaped is ordinary chat.
+  return tokens.some((token) => looksLikeChallengeCode(token)) ? "unknown" : "none";
+}
+
+/**
+ * The inbound adapter's acknowledgement (conductor #614), kept as the boolean
+ * the availability gate already reads. {@link classifyArmReply} is the same
+ * pass with the non-matching cases named.
+ */
+export function acknowledgeArmReply(project: string | undefined, replyText: string, now: number): boolean {
+  return classifyArmReply(project, replyText, now) === "matched";
 }
 
 /** The acknowledgement record for one exact challenge id, or undefined. */

package/src/board.ts

@@ -14,6 +14,7 @@ import type { FleetLayers, TelegramHealth } from "./status-render.ts";
 import { probeCodeGraph, DEFAULT_DEPS, type CodeGraphHealth } from "./graph-health.ts";
 import { healthCheck, livingDaemon } from "./lifecycle.ts";
 import type { WorkerPausePhase } from "./worker.ts";
+import type { WorkerPauseView } from "./fleet.ts";
 import { dbPath, openStore } from "./store.ts";
 import { formatTranscriptLine } from "./transcript.ts";
 import { makeTracker } from "./tracker/github.ts";
@@ -31,6 +32,8 @@ import type {
 } from "./types.ts";
 
 const REFRESH_MS = 1_000;
+/** How long an armed pause confirmation stays valid (#997). */
+const PAUSE_CONFIRM_MS = 8_000;
 const HEALTH_REFRESH_MS = 10_000;
 /** Base cadence for the tracker label read, and the ceiling the idle backoff
  *  in {@link nextLabelDelayMs} doubles toward. Separate from the health gate
@@ -141,7 +144,7 @@ export interface BoardHealth {
 
 interface BoardHealthProbe {
   health: BoardHealth;
-  pausedPhases: ReadonlyMap<number, WorkerPausePhase>;
+  pausedPhases: ReadonlyMap<number, WorkerPauseView>;
 }
 
 /**
@@ -191,7 +194,7 @@ export interface BoardSnapshot {
   project: ProjectConfig;
   status: StatusSnapshot;
   health: BoardHealth;
-  pausedPhases: ReadonlyMap<number, WorkerPausePhase>;
+  pausedPhases: ReadonlyMap<number, WorkerPauseView>;
   labels: BoardLabels;
   /** Live re-verification of pushed rows (#173): run id → what the tracker says
    *  the PR looks like now. Rendered as a `now:` suffix on the card. */
@@ -570,7 +573,7 @@ function normalizeCursor(snapshot: BoardSnapshot, cursor: BoardCursor): void {
 function runCardLines(run: RunRecord, snapshot: BoardSnapshot, lane: BoardLane): string[] {
   const endedAt = run.endedAt ?? snapshot.now;
   const duration = humanDuration(endedAt - run.startedAt);
-  const phase = lane === "running" ? snapshot.pausedPhases.get(run.issue) : undefined;
+  const phase = lane === "running" ? snapshot.pausedPhases.get(run.issue)?.phase : undefined;
   const pausePrefix = phase === "paused" ? "⏸ PAUSED " : phase === "pausing" ? "… pausing " : "";
   const lines = [
     // The class, when the sweep has attached one and nothing has recovered it
@@ -833,7 +836,7 @@ function renderDetail(snapshot: BoardSnapshot, cursor: BoardCursor, width: numbe
   // #173: a blocked/failed run whose label is gone is the reason this card is
   // parked; the header says so rather than presenting the state as current.
   const stateShown = isLastRun(run, snapshot.labels) ? `last run: ${run.state}` : run.state;
-  const pausePhase = snapshot.pausedPhases.get(run.issue);
+  const pausePhase = snapshot.pausedPhases.get(run.issue)?.phase;
   const metadata = [
     styledCell(` RUN #${run.issue}  ${run.repo}  ${stateShown} `, width, `${BOLD}${REVERSE}`),
     ...(pausePhase === undefined
@@ -869,7 +872,7 @@ function renderHelp(width: number, height: number): string[] {
     "↑/↓ or k/j   select card",
     "Enter         inspect/follow transcript",
     "u             unblock selected blocked, failed or orphaned issue",
-    "space         pause/resume selected worker",
+    "space         pause/resume selected worker (asks for a confirming press)",
     "i             open selected issue",
     "p             open selected pull request",
     "r             refresh health now",
@@ -964,7 +967,7 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealthProb
     pausedPhases:
       daemon === "ok"
         ? workerPhasesFromHealthz(health?.body, project.name)
-        : new Map<number, WorkerPausePhase>(),
+        : new Map<number, WorkerPauseView>(),
   };
 }
 
@@ -1065,6 +1068,31 @@ async function unblock(project: ProjectConfig, issue: number): Promise<string> {
   return summarizeUnblockOutput(issue, stdout);
 }
 
+/**
+ * What one spacebar press on a RUNNING card does (#997): the first press only
+ * arms the toggle and says so; the confirming second press on the same card,
+ * within {@link PAUSE_CONFIRM_MS}, performs it. Pure, so the gate itself is
+ * provable: an unconfirmed press must change nothing but the armed state —
+ * one stray spacebar parked a live worker for 14 minutes on 2026-08-23.
+ */
+export function pauseKeyDecision(
+  pending: { issue: number; at: number } | undefined,
+  issue: number,
+  phase: WorkerPausePhase | undefined,
+  now: number,
+):
+  | { kind: "confirm"; pending: undefined }
+  | { kind: "arm"; pending: { issue: number; at: number }; notice: string } {
+  if (pending?.issue === issue && now - pending.at <= PAUSE_CONFIRM_MS) {
+    return { kind: "confirm", pending: undefined };
+  }
+  return {
+    kind: "arm",
+    pending: { issue, at: now },
+    notice: `press space again to confirm ${phase === "paused" ? "resume" : "pause"} of #${issue}`,
+  };
+}
+
 async function toggleWorkerPause(
   project: ProjectConfig,
   issue: number,
@@ -1083,7 +1111,7 @@ async function toggleWorkerPause(
       {
         method: "PUT",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ project: project.name }),
+        body: JSON.stringify({ project: project.name, source: "board" }),
       },
     );
     const payload = (await response.json()) as { error?: unknown; phase?: unknown };
@@ -1267,6 +1295,8 @@ export async function runBoard(projectName?: string): Promise<void> {
   ]);
   let health = healthProbe.health;
   let pausedPhases = healthProbe.pausedPhases;
+  // An armed-but-unconfirmed pause toggle (#997): issue and arm time.
+  let pendingPause: { issue: number; at: number } | undefined;
   let healthAt = Date.now();
   let healthRefresh: Promise<void> | undefined;
   // The tracker read is gated separately from health and the plan allowance:
@@ -1400,6 +1430,9 @@ export async function runBoard(projectName?: string): Promise<void> {
       });
       const name = key.name ?? key.sequence;
       if (name === "refresh" || name === "resize") continue;
+      // #997: an armed pause confirmation survives only until the next
+      // keypress — anything but the confirming space disarms it.
+      if (name !== "space") pendingPause = undefined;
       // Past this point the key came from a person, not the refresh timer:
       // someone watching the board gets the base cadence back immediately.
       labelDelay = LABEL_REFRESH_MS;
@@ -1479,11 +1512,19 @@ export async function runBoard(projectName?: string): Promise<void> {
       if (name === "space") {
         const lane = COLUMN_DEFS[cursor.column]?.key;
         if (card === undefined || card.kind !== "run" || lane !== "running") {
+          pendingPause = undefined;
           notice = "pause/resume is available for RUNNING cards";
         } else {
           const issue = cardIssue(card);
-          notice = await toggleWorkerPause(project, issue, pausedPhases.get(issue));
-          healthAt = 0;
+          const phase = pausedPhases.get(issue)?.phase;
+          const decision = pauseKeyDecision(pendingPause, issue, phase, Date.now());
+          pendingPause = decision.pending;
+          if (decision.kind === "confirm") {
+            notice = await toggleWorkerPause(project, issue, phase);
+            healthAt = 0;
+          } else {
+            notice = decision.notice;
+          }
         }
         continue;
       }

package/src/check-browser-js.ts

@@ -0,0 +1,72 @@
+/**
+ * Gate: every browser script this package serves must parse.
+ *
+ * Run via `bun run check` from the package root, beside the trailing-newline
+ * gate. `tsc` never sees `src/dashboard/app.js` — it is plain browser JS,
+ * shipped as an asset and loaded by a `<script>` tag — and no test executes
+ * it, so nothing in the pipeline had an opinion about whether it was even
+ * syntactically valid.
+ *
+ * It was not. 0.19.0 shipped an `app.js` carrying four `__omp_shell("…")`
+ * fragments where `!answer.ok` and `!confirmDestructive(` should have been:
+ * the authoring session wrote the file through a Python eval path, whose
+ * IPython-style `!cmd` shell escape rewrote every line that began with `!`.
+ * A single SyntaxError takes the whole script with it, so the dashboard
+ * rendered its static `<h1>` and nothing else — no token prompt, no fleet —
+ * and looked, from the outside, like an auth or data problem (#981).
+ *
+ * A parse is the whole check. It is not a linter and has no opinion about
+ * style: it asks the one question a served script must answer yes to.
+ */
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Tracked browser scripts, repo-root-relative. */
+export const BROWSER_SCRIPTS: readonly string[] = ["omp/src/dashboard/app.js"];
+
+/**
+ * The parse error for one script, or null when it parses. Uses Bun's own
+ * transpiler: a full parse of the source, without executing a line of it (the
+ * script drives a DOM this process does not have).
+ */
+export function parseFailure(source: string, path: string): string | null {
+  try {
+    new Bun.Transpiler({ loader: "js", target: "browser" }).transformSync(source);
+    return null;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return `${path}: ${message.split("\n")[0]}`;
+  }
+}
+
+/** One violation line per unparseable script, so a run names every offender. */
+export function findViolations(
+  paths: readonly string[],
+  read: (path: string) => string,
+): string[] {
+  const violations: string[] = [];
+  for (const path of paths) {
+    const failure = parseFailure(read(path), path);
+    if (failure !== null) violations.push(failure);
+  }
+  return violations;
+}
+
+function repoRoot(): string {
+  return execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+}
+
+if (import.meta.main) {
+  const root = repoRoot();
+  const violations = findViolations(BROWSER_SCRIPTS, (path) =>
+    readFileSync(join(root, path), "utf8"),
+  );
+  if (violations.length > 0) {
+    for (const violation of violations) console.error(violation);
+    console.error(`browser script gate: ${violations.length} script(s) do not parse`);
+    process.exit(1);
+  }
+  console.log("browser script gate: ok");
+}

package/src/cli.ts

@@ -12,6 +12,7 @@ import { loadConfig } from "./config.ts";
 import { COMMAND_MANIFEST, renderUsage, type CommandManifestEntry } from "./command-manifest.ts";
 import { armCommand } from "./commands/arm.ts";
 import { boardCommand } from "./commands/board.ts";
+import { companionCommand } from "./commands/companion.ts";
 import { briefUpgradeCommand } from "./commands/brief-upgrade.ts";
 import { daemonCommand } from "./commands/daemon.ts";
 import { dashboardCommand } from "./commands/dashboard.ts";
@@ -278,6 +279,7 @@ export function commandHandlers(ctx: CommandContext): Record<string, CommandHand
     doctor: () => doctorCommand(ctx),
     ledger: () => ledgerCommand(ctx),
     board: () => boardCommand(ctx),
+    companion: () => companionCommand(ctx),
     dashboard: () => dashboardCommand(ctx),
     hold: () => holdCommand(ctx),
     drain: () => drainCommand(ctx),

package/src/command-manifest.ts

@@ -156,6 +156,16 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     usage: ["board [--project NAME] [--json]"],
     flags: [project(), toggle("--json", "print the stable board JSON shape")],
   },
+  {
+    name: "companion",
+    description: "render the recovery companion pane's decisions and watches view",
+    scope: "project",
+    usage: ["companion decisions [--project NAME] [--once]"],
+    flags: [
+      project(),
+      toggle("--once", "draw one frame and exit instead of holding the pane"),
+    ],
+  },
   {
     name: "dashboard",
     description: "serve the read-only browser dashboard",

package/src/commands/arm.ts

@@ -7,11 +7,39 @@
  */
 
 import type { CommandContext } from "./context.ts";
-import { armTicks } from "../fleet.ts";
+import { armFleet, armTicks } from "../fleet.ts";
 import { withProgress } from "../ui/progress.ts";
 
 export async function armCommand(ctx: CommandContext): Promise<void> {
-for (const project of ctx.targetProjects()) {
+const targets = ctx.targetProjects();
+// One ceremony for the whole fleet (#991). Two projects used to mean two
+// sequential handshakes with two codes in one chat, though nothing about the
+// fleet's state differed between them. `arm --project X` is untouched: it is
+// still exactly one project, one challenge, one marker.
+if (ctx.projectFlag === undefined && targets.length > 1) {
+  const r = await withProgress(
+    "arm: verifying one arming proof for the fleet…",
+    "Arming proof verified",
+    () =>
+      armFleet(
+        targets.map((project) => project.name),
+        { progress: (line) => process.stdout.write(`${line}\n`) },
+      ),
+    { plainMessage: true },
+  );
+  process.stdout.write(
+    `ARMED — one inbound round-trip proved with owner ${r.owner}; ticks are now live for ${String(r.armed.length)} project(s).\n` +
+      r.armed
+        .map(
+          (project) =>
+            `  ${project.project}: marker ${project.path}${project.alreadyArmed ? " (replaced previous marker)" : ""}`,
+        )
+        .join("\n") +
+      "\n",
+  );
+  return;
+}
+for (const project of targets) {
   // 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.

package/src/commands/companion.ts

@@ -0,0 +1,103 @@
+/**
+ * `omp-conductor companion decisions` — the recovery companion pane's own
+ * renderer (#994).
+ *
+ * Why a command and not `watch '<one-shot>'`, which is what recovery used to
+ * spin up: `watch` re-forks its argument every interval, and the
+ * foreground-process transition that produces made herdr repaint the pane —
+ * a flash every 60 seconds, reported live during a fleet restart. Measured at
+ * the time: exactly one full erase at startup in both `watch` and `watch -c`,
+ * ~610 bytes for three renders, and zero ANSI bytes in the command's own
+ * output. So neither `watch`'s drawing nor `-c` was the cause; the re-fork was.
+ * The board pane, a single long-lived process holding its terminal, never
+ * flashed — and this is that shape.
+ *
+ * Two properties are load-bearing:
+ *
+ * - **One process, held.** The pane's foreground stays this process between
+ *   renders, which is exactly what recovery's liveness check reads
+ *   (`foreground_verdict`: a bare shell means the pane is at a prompt and gets
+ *   an `agent start`). A `while`-loop in `sh` would have stopped the flashing
+ *   and broken that, because its foreground process is named `sh`.
+ * - **Redraw in place, only on change.** Cursor-home plus erase-to-end-of-line
+ *   per line, and the leftover tail of a shorter frame erased explicitly. No
+ *   full-screen clear, so there is nothing to see between two identical frames
+ *   — the print-and-sleep loop this lineage started with appended instead, and
+ *   a pane left open overnight was a mile of identical lists.
+ */
+
+import { companionFrame } from "../companion-view.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, openStore } from "../store.ts";
+import type { CommandContext } from "./context.ts";
+
+/** Seconds between reads. The list moves when a human or a condition moves it,
+ *  neither of which is fast; a shorter interval would spend the fleet's
+ *  process budget to display the same frame. */
+export const COMPANION_REFRESH_SECONDS = 60;
+
+/** Cursor to home, and erase from the cursor to the end of the line. Nothing
+ *  clears the whole screen: a full erase is what a reader perceives as a
+ *  flash, and it is unnecessary when every line is overwritten in place. */
+const HOME = "\u001B[H";
+const ERASE_LINE = "\u001B[K";
+const ERASE_BELOW = "\u001B[J";
+
+/** One frame, drawn over whatever the last one left. `previous` is the line
+ *  count of the last frame so a shorter one erases its own leftovers instead of
+ *  leaving stale rows that read as current. */
+export function drawFrame(lines: readonly string[], previous: number): string {
+  const body = lines.map((line) => `${line}${ERASE_LINE}`).join("\n");
+  // A frame that shrank leaves rows below it; erase from the end of the new
+  // content down rather than clearing first, which would flash.
+  return lines.length < previous ? `${HOME}${body}\n${ERASE_BELOW}` : `${HOME}${body}\n`;
+}
+
+export async function companionCommand(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[1];
+  if (sub !== "decisions") {
+    process.stderr.write(
+      `omp-conductor: unknown companion view "${sub ?? ""}" — expected decisions\n`,
+    );
+    process.exit(2);
+  }
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const once = ctx.argv.includes("--once");
+
+  let previous = 0;
+  let stopped = false;
+  const stop = (): void => {
+    stopped = true;
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+
+  while (!stopped) {
+    // Opened per render, closed immediately: a companion pane lives for days,
+    // and a handle held that long across daemon restarts and db snapshots is a
+    // handle to a file that may no longer be the store.
+    const store = openStore(dbPath());
+    let lines: string[];
+    try {
+      lines = companionFrame(store.openDecisions(project.name));
+    } finally {
+      store.close();
+    }
+    process.stdout.write(drawFrame(lines, previous));
+    previous = lines.length;
+    if (once) return;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, COMPANION_REFRESH_SECONDS * 1_000);
+      // Never hold the process open past a signal: the pane is closed by
+      // closing the pane, and a lingering timer would outlive it.
+      timer.unref?.();
+      const poll = setInterval(() => {
+        if (!stopped) return;
+        clearInterval(poll);
+        clearTimeout(timer);
+        resolve();
+      }, 250);
+      poll.unref?.();
+    });
+  }
+}

package/src/commands/context.ts

@@ -81,6 +81,7 @@ export type CommandScope = "project" | "host" | "fleet" | "none";
 export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   // project — exactly one project; findProject demands --project when several
   "brief-upgrade": "project",
+  companion: "project",
   decision: "project",
   drain: "project",
   event: "project",

package/src/commands/worker.ts

@@ -41,6 +41,7 @@ const response = await fetch(
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       project: project.name,
+      source: "cli",
       ...(reason === undefined ? {} : { reason }),
     }),
   },