omp-conductor 0.19.2 → 0.19.4

package/README.md

@@ -386,9 +386,10 @@ message on stderr) on every uncertainty:
 - the tick config does not parse — the agent name would be a guess
 - `herdr agent list` is unreachable, prints nothing, or prints output with no
   explicit `agents` array; only a real `agents: []` means "no agents"
-- an agent row is unreadable — a missing `name`/`pane_id`, or an `agent` field
-  present with a non-string value. An *absent* or `null` `agent` is the sticky
-  claim herdr reports after the agent exits, and stays a normal answer
+- an agent row is unreadable — a missing `pane_id`, a non-string non-null
+  `name`, or an `agent` field present with a non-string value. An absent or
+  `null` `name` is an unnamed pane; an absent or `null` `agent` is the sticky
+  claim herdr reports after the agent exits, and both stay normal answers
 - the configured agent name is not unique, or the claimed pane runs some other agent
 - `pane process-info` fails, or the claim is live `omp` but names no recognizable
   omp foreground PID — "cannot see it" is never reported as "it is stopped"

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.2",
+  "version": "0.19.4",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/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/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 }),
     }),
   },

package/src/companion-view.ts

@@ -0,0 +1,81 @@
+/**
+ * The composed view the recovery companion pane renders (#994).
+ *
+ * Two defects produced this module, and they were one decision:
+ *
+ * - The pane re-forked `watch -c -n 60 '<one-shot>'`, and every 60 seconds the
+ *   foreground-process transition made herdr repaint it — a visible flash. The
+ *   board pane, one long-lived process holding its terminal, never flashed. So
+ *   the fix is a process that persists between renders, which is what
+ *   {@link companionFrame} exists to feed.
+ * - It rendered `decision list` alone, which on this fleet meant a whole pane
+ *   refreshing forever to display `no open decisions` while nine watches, four
+ *   of them `condition:met`, were invisible in it.
+ *
+ * The split is deliberate and this is the only place it is composed: operator
+ * decisions are rare and already interrupt through Telegram when they matter,
+ * while watches are the live state a glanceable pane is *for* — and a met
+ * condition is the one row in either list that wants eyes immediately.
+ *
+ * An empty section is omitted entirely rather than printed with a placeholder.
+ * A pane showing nothing is honest; a pane showing `no open decisions` forever
+ * is the noise the operator objected to.
+ *
+ * `decision list` and `watch list` keep their own contracts untouched — this is
+ * the pane's composition, not those commands' output.
+ */
+
+import type { DecisionRecord } from "./types.ts";
+
+/** The marker that makes an actionable watch findable at a glance. Uppercase
+ *  rather than coloured: the pane inherits whatever palette the terminal has,
+ *  and the flash this module replaced was chased through an ANSI hypothesis. */
+export const MET_MARKER = "[ACT NOW]";
+
+/** The single line shown when neither list has anything. Quiet, and still
+ *  proof the pane is alive rather than blank because something died. */
+export const IDLE_LINE = "nothing open";
+
+/** One row, reduced to what the pane shows. */
+function row(record: DecisionRecord, now: number): string {
+  const ageHours = Math.max(0, Math.round((now - record.askedAt) / 3_600_000));
+  const condition =
+    record.condition === undefined ? "-" : record.conditionMetAt === undefined ? "pending" : "met";
+  const met = condition === "met" ? `${MET_MARKER} ` : "";
+  return `  ${met}${record.id}  ${String(ageHours)}h  blocks:${record.blocks ?? "-"}  condition:${condition}  ${record.question}`;
+}
+
+/**
+ * The frame to draw, as lines.
+ *
+ * Decisions above watches, because only a decision wants an answer. Met
+ * conditions are hoisted to the top of the watch section: the whole reason to
+ * render watches at all is that one of them may be actionable, and a reader who
+ * has to scan nine rows for the one that matters is reading a log, not a board.
+ */
+export function companionFrame(
+  open: readonly DecisionRecord[],
+  now: number = Date.now(),
+): string[] {
+  const decisions = open.filter((d) => d.kind !== "watch");
+  const watches = open.filter((d) => d.kind === "watch");
+  const lines: string[] = [];
+
+  if (decisions.length > 0) {
+    lines.push(`operator decisions (${String(decisions.length)}) — these want an answer`);
+    for (const decision of decisions) lines.push(row(decision, now));
+  }
+
+  if (watches.length > 0) {
+    const met = watches.filter((w) => w.conditionMetAt !== undefined);
+    const pending = watches.filter((w) => w.conditionMetAt === undefined);
+    if (lines.length > 0) lines.push("");
+    lines.push(
+      `watches (${String(watches.length)}) — no answer needed` +
+        (met.length === 0 ? "" : `, ${String(met.length)} to act on now`),
+    );
+    for (const watch of [...met, ...pending]) lines.push(row(watch, now));
+  }
+
+  return lines.length === 0 ? [IDLE_LINE] : lines;
+}

package/src/config-schema.ts

@@ -397,7 +397,13 @@ const projectSchema = z
       })
       .strict(),
     queueLabel: z.string().min(1, "must be a non-empty string — it is the human sign-off gate"),
-    groomBelow: z.unknown().optional(),
+    // The grooming trigger (#988): an integer ≥ 1, or the literal "always" —
+    // groom on demand every tick while ungroomed candidates remain. Unlike the
+    // opaque model selectors below, this field's usable vocabulary is closed,
+    // so the schema states it and a wrong value fails the load with an
+    // authored line instead of silently degrading the fleet's grooming duty
+    // to the default.
+    groomBelow: z.union([z.number().int().min(1), z.literal("always")]).optional(),
     stateLabels: stateLabelsSchema.optional(),
     routing: routingSchema.optional(),
     caps: capsSchema.optional(),

package/src/config.ts

@@ -847,6 +847,9 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   const pathStr = dottedPath(rel);
   const found = (at?: readonly PropertyKey[]): string => FOUND(rawAt(root, at ?? fullPath));
 
+  if (rel.length === 1 && rel[0] === "groomBelow") {
+    return `groomBelow must be an integer ≥ 1 or the literal "always", found ${found()}`;
+  }
   if (rel.length === 1 && rel[0] === "releasePolicy") {
     return `releasePolicy must be an object mapping release shapes (${RELEASE_SHAPE_LIST}) to ${AUTHORITY_HOLDER_LIST}, or the legacy ${LEGACY_RELEASE_POLICY_LIST}, found ${found()}`;
   }
@@ -1195,11 +1198,11 @@ function finalizeProject(
   const label = `project "${name}"`;
   const trackerRepo = ((p["tracker"] as Raw | undefined)?.["repo"]) as string;
 
+  // The zod union already enforced `integer ≥ 1 | "always"`; this only
+  // narrows the type for the assembled ProjectConfig (#988).
   const rawGroomBelow = p["groomBelow"];
   const groomBelow =
-    typeof rawGroomBelow === "number" && Number.isInteger(rawGroomBelow) && rawGroomBelow >= 1
-      ? rawGroomBelow
-      : undefined;
+    rawGroomBelow === "always" ? "always" : typeof rawGroomBelow === "number" ? rawGroomBelow : undefined;
 
   const rawRouting = p["routing"] as Raw | undefined;
   const rawPrefix = rawRouting?.["labelPrefix"];