omp-conductor 0.18.0 → 0.18.2

package/src/cli.ts

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

package/src/command-help.ts

@@ -87,6 +87,17 @@ export const COMMAND_DETAILS = `  setup    interview, then write config.json, th
   hold     soft stop: pause claiming AND disarm ticks. Daemon and pane stay up.
            This is "stop the conductor overnight" without killing processes.
            Use --all to target every configured project.
+  drain    start, inspect, or cancel the project's self-expiring admission
+           drain — the durable, bounded alternative to queue-label churn
+           before a release. New claims pause while active runs settle, and
+           admission resumes at the absolute deadline on its own, even if the
+           orchestrator dies. start takes --until (an ISO instant or a
+           relative duration such as 90s/45m/2h/1d, always bounded and in the
+           future) and an optional --reason; status reports the active drain's
+           creation time, expiry, reason and remaining active runs; cancel
+           removes it and is idempotent. The drain never touches the pause
+           sentinel, the arm marker, or any queue label — it is a file record,
+           not a timer or a hold.
   arm      proof-gated: send a Telegram challenge and write the arm marker only
            after your reply appears as a user turn in the orchestrator transcript.
            Never auto-armed by resume/hold. Use --all for every project.

package/src/command-manifest.ts

@@ -63,7 +63,6 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       "setup host [NAME] [--project NAME]",
       "setup graph [--no-seed] [--print] [--project NAME]",
     ],
-    details: COMMAND_DETAILS,
     subcommands: [
       { name: "host", description: "stage and install the host services" },
       { name: "graph", description: "install and seed code-graph indexes" },
@@ -205,6 +204,27 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     usage: ["hold [--keep-ticks] [--project NAME | --all]"],
     flags: [toggle("--keep-ticks", "pause claims without disarming ticks"), project(), all()],
   },
+  {
+    name: "drain",
+    description: "start, inspect, or cancel the project's self-expiring admission drain",
+    scope: "project",
+    usage: [
+      "drain start --until ISO|DURATION [--reason TEXT] [--project NAME]",
+      "drain status [--project NAME]",
+      "drain cancel [--project NAME]",
+    ],
+    subcommands: [
+      { name: "start", description: "record a bounded drain intent" },
+      { name: "status", description: "report the drain and its remaining active runs" },
+      { name: "cancel", description: "remove the project's drain" },
+    ],
+    flags: [
+      value("--until", "absolute ISO instant or relative duration (90s, 45m, 2h, 1d)"),
+      value("--reason", "purpose, persisted on the drain record"),
+      project(),
+    ],
+    positionals: [{ name: "action" }],
+  },
   {
     name: "arm",
     description: "prove Telegram delivery and arm scheduled ticks",
@@ -397,6 +417,11 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       "watch list [--project NAME] [--json]",
       "watch withdraw <id> [--reason TEXT] [--project NAME]",
     ],
+    details: `add records a row the daemon checks for you and the next tick reads, with no
+operator answer needed. list shows open watches, oldest first. withdraw ends
+one with a recorded reason — the verb that creates a watch is the verb that
+ends it. A watch whose PR condition can no longer be observed (the PR merged
+or closed first) is withdrawn by the daemon itself.`,
     subcommands: [
       { name: "add", description: "record a watch" },
       { name: "list", description: "list open watches" },
@@ -422,6 +447,12 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
       "intake dismiss <id> [--project NAME]",
       "intake groomed <id> --issue <url> [--project NAME]",
     ],
+    details: `Captures one raw idea into the local store and prints its id. list shows what
+is still pending (id, age, text), oldest first; dismiss drops one by id. The
+capture is durable — it lives in the sqlite store, not in a session — so it
+survives daemon restarts. The orchestrator files the idea as an issue and then
+marks that provenance with groomed: an id already resolved is a no-op with a
+message, never an error, because ticks retry.`,
     subcommands: [
       { name: "list", description: "list pending intake items" },
       { name: "dismiss", description: "dismiss an intake item" },
@@ -435,7 +466,6 @@ export const COMMAND_MANIFEST: readonly CommandManifestEntry[] = [
     description: "print command usage (also --help, -h)",
     scope: "none",
     usage: ["help"],
-    details: COMMAND_HELP_TAIL,
     flags: [],
   },
   {
@@ -459,9 +489,11 @@ export function renderUsage(manifest: readonly CommandManifestEntry[] = COMMAND_
   const commands = manifest.map(
     (command) => `  ${command.name.padEnd(width)}  ${command.description}`,
   );
-  const details = manifest.flatMap((command) =>
-    command.details === undefined ? [] : [...command.details.split("\n"), ""],
-  );
+  // The fleet-wide operator reference, printed once. It is *not* harvested
+  // from `details`: that field is one verb's own long-form help, which
+  // `VERB --help` renders, so collecting it here would print `setup`'s
+  // carrier copy of this very blob and repeat each verb's prose twice.
+  const details = [...COMMAND_DETAILS.split("\n"), "", ...COMMAND_HELP_TAIL.split("\n"), ""];
   return [
     "omp-conductor — dispatch ready issues to omp coding sessions",
     "",
@@ -475,6 +507,7 @@ export function renderUsage(manifest: readonly CommandManifestEntry[] = COMMAND_
     ...details,
     "recipes:",
     "  hold              no claims, no tick sends (inspectable)",
+    "  drain start       bounded release window, self-expiring (no hold)",
     "  stop              hold + stop dispatch daemon",
     "  stop --pane       stop + pin conductor-pane recovery off",
     "  resume            clear pause and pane pin (ticks stay disarmed)",

package/src/commands/arm.ts

@@ -1,5 +1,5 @@
 /**
- * `arm` — proof-gated: send a Telegram challenge and write the arm marker only after the reply appears in the orchestrator transcript.
+ * `arm` — proof-gated: send a Telegram challenge and write the arm marker only after the orchestrator's inbound adapter acknowledges the reply in conductor state (#614).
  *
  * Moved out of cli.ts's switch by the per-verb module split (#462);
  * only the case wrapper, the injected `ctx` lookups and the imports

package/src/commands/context.ts

@@ -82,6 +82,7 @@ export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
   // project — exactly one project; findProject demands --project when several
   "brief-upgrade": "project",
   decision: "project",
+  drain: "project",
   event: "project",
   extend: "project",
   friction: "project",

package/src/commands/drain.ts

@@ -0,0 +1,176 @@
+/**
+ * `drain` — start, inspect, or cancel the project's self-expiring admission fence (#484).
+ *
+ * The bounded drain state machine landed in #776 (`createDrain`/`readDrain`/
+ * `cancelDrain` on daemon.ts, re-exported from fleet.ts); this verb is the
+ * operator surface over it. A drain is the release-window sibling of `hold`:
+ * the same admission boundary — settlement above it, nothing claimed below —
+ * but recorded with an absolute deadline, so admission resumes on its own even
+ * if the orchestrator dies. The only state it touches is the project's drain
+ * record: never the pause sentinel, the arm marker, or any queue label.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { statusSnapshot } from "../daemon.ts";
+import { cancelDrain, createDrain, readDrain } from "../fleet.ts";
+import { dim, ok } from "../ui/style.ts";
+
+const DRAIN_USAGE = `omp-conductor drain — start, inspect, or cancel the project's admission drain.
+
+usage:
+  omp-conductor drain start --until ISO|DURATION [--reason TEXT] [--project NAME]
+  omp-conductor drain status [--project NAME]
+  omp-conductor drain cancel [--project NAME]
+
+A drain is a durable, self-expiring admission fence: new claims pause while
+existing runs settle, and admission resumes automatically at the absolute
+deadline — even if the orchestrator crashes. start replaces any prior drain of
+the project; --until takes an ISO instant or a relative duration (90s, 45m,
+2h, 1d) that must be bounded and in the future. status reports the active
+drain's creation time, absolute expiry, reason, and remaining active runs.
+cancel removes the project's drain and is idempotent. A drain never touches
+the pause sentinel, the arm marker, or any queue label — it is the file record
+that expires on its own.`;
+
+/** The flags each drain subcommand accepts, after the subcommand itself. */
+const DRAIN_FLAGS: Readonly<Record<string, readonly string[]>> = {
+  start: ["--project", "--until", "--reason"],
+  status: ["--project"],
+  cancel: ["--project"],
+};
+
+/** Relative durations accepted by `drain start --until`. */
+const DURATION_RE = /^(\d+)([smhd])$/;
+const DURATION_UNIT_MS: Readonly<Record<string, number>> = {
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/**
+ * `--until` value → epoch-ms deadline, or undefined when the input is not a
+ * bounded expiry. A duration is relative to now; an ISO instant is absolute.
+ * Both forms must land on a finite safe-integer timestamp — the same bound
+ * `createDrain` persists as an absolute ISO instant, so a value beyond the
+ * Date range (e.g. 99999999999999999999d) is refused here instead of blowing
+ * up inside the record write. The absolute form must look like a calendar
+ * date: a bare number such as `3000` parses as a year in some engines, and an
+ * operator typing that almost certainly meant a duration.
+ */
+function parseExpiry(raw: string, now: number): number | undefined {
+  const duration = DURATION_RE.exec(raw);
+  if (duration !== null) {
+    const expiresAt = now + Number.parseInt(duration[1]!, 10) * DURATION_UNIT_MS[duration[2]!]!;
+    return Number.isSafeInteger(expiresAt) ? expiresAt : undefined;
+  }
+  if (!/^\d{4}-\d{2}-\d{2}/.test(raw)) return undefined;
+  const absolute = Date.parse(raw);
+  return Number.isSafeInteger(absolute) ? absolute : undefined;
+}
+
+/**
+ * Rejects trailing tokens a drain subcommand does not declare, so a typo'd
+ * flag cannot be silently ignored — the same exit-2 scan `intake` and `stats`
+ * run. Both `--flag VALUE` and `--flag=VALUE` are accepted, matching the
+ * shared `flag()` parser.
+ */
+function assertKnownArgs(ctx: CommandContext, sub: string): void {
+  const allowed = DRAIN_FLAGS[sub] ?? [];
+  for (let i = 2; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    const eq = token.startsWith("--") ? token.indexOf("=") : -1;
+    const name = eq < 0 ? token : token.slice(0, eq);
+    if (allowed.includes(name)) {
+      if (eq < 0) i += 1; // consume the flag's value token
+      continue;
+    }
+    process.stderr.write(`omp-conductor: drain ${sub}: unexpected argument "${token}"\n`);
+    process.exit(2);
+  }
+}
+
+export async function drainCommand(ctx: CommandContext): Promise<void> {
+  const sub = ctx.argv[1];
+  if (sub === "--help" || sub === "-h") {
+    process.stdout.write(DRAIN_USAGE);
+    return;
+  }
+  if (sub !== "start" && sub !== "status" && sub !== "cancel") {
+    process.stderr.write("omp-conductor: drain needs start, status, or cancel\n");
+    process.exit(2);
+  }
+  assertKnownArgs(ctx, sub);
+  const project = findProject(loadConfig(), ctx.projectFlag);
+
+  if (sub === "start") {
+    const rawUntil = ctx.flag("until");
+    if (rawUntil === undefined || rawUntil.length === 0) {
+      process.stderr.write(
+        "omp-conductor: drain start needs --until with an ISO instant or a duration (90s, 45m, 2h, 1d)\n",
+      );
+      process.exit(2);
+    }
+    const now = Date.now();
+    const expiresAt = parseExpiry(rawUntil, now);
+    if (expiresAt === undefined) {
+      process.stderr.write(
+        `omp-conductor: drain start: "${rawUntil}" is not a bounded expiry — ` +
+          "use an ISO instant (e.g. 2026-08-20T10:00:00Z) or a duration (90s, 45m, 2h, 1d)\n",
+      );
+      process.exit(2);
+    }
+    if (expiresAt <= now) {
+      process.stderr.write(`omp-conductor: drain start: --until "${rawUntil}" must be in the future\n`);
+      process.exit(2);
+    }
+    const rawReason = ctx.flag("reason")?.trim().replace(/\s+/g, " ");
+    if (rawReason !== undefined && (rawReason === "" || rawReason.length > 500)) {
+      process.stderr.write("omp-conductor: drain start --reason needs 1-500 characters\n");
+      process.exit(2);
+    }
+    createDrain(project.name, {
+      expiresAt,
+      ...(rawReason === undefined ? {} : { reason: rawReason }),
+    });
+    process.stdout.write(
+      ok(
+        `drain started for ${project.name} — claiming paused until ${new Date(expiresAt).toISOString()}` +
+          (rawReason === undefined ? "" : ` (${rawReason})`),
+      ) + "\n",
+    );
+    process.stdout.write(
+      dim(
+        "the drain is a durable record: it survives crashes and resumes admission at the deadline on its own",
+      ) + "\n",
+    );
+    return;
+  }
+
+  if (sub === "status") {
+    const drain = statusSnapshot(project.name).drain;
+    if (drain === undefined) {
+      process.stdout.write(`drain: ${project.name} inactive — admission is open\n`);
+      return;
+    }
+    const lines = [
+      `drain: ${project.name} active`,
+      `  since       ${new Date(drain.since).toISOString()}`,
+      `  expires at  ${new Date(drain.expiresAt).toISOString()}`,
+      ...(drain.reason === undefined ? [] : [`  reason      ${drain.reason}`]),
+      `  remaining   ${drain.remainingRuns} active run${drain.remainingRuns === 1 ? "" : "s"}`,
+    ];
+    process.stdout.write(`${lines.join("\n")}\n`);
+    return;
+  }
+
+  const had = readDrain(project.name);
+  cancelDrain(project.name);
+  process.stdout.write(
+    had.kind === "active"
+      ? ok(`drain cancelled for ${project.name} — admission resumes on the next dispatch pass`) + "\n"
+      : `drain: ${project.name} had no active drain — nothing to cancel\n`,
+  );
+}

package/src/commands/extend.ts

@@ -2,25 +2,21 @@
  * `extend` — raise a live run's turn ceiling, or set a bounded one-shot ceiling after a failed, killed, orphaned or blocked run.
  *
  * 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.
+ * the daemon discovery resolves through {@link requireDaemonControl}, the
+ * same run-control target `worker` uses, so a live systemd-run daemon
+ * stays reachable when its pidfile is missing (#811) and the refusal
+ * answers cannot drift between the two verbs.
  */
 
 import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
-import { livingDaemon } from "../lifecycle.ts";
+import { requireDaemonControl } from "../lifecycle.ts";
 
 export async function extendCommand(ctx: CommandContext): Promise<void> {
 const issue = ctx.issueArg("extend", ctx.argv[1]);
 const maxTurns = ctx.turnsFlag();
 const project = findProject(loadConfig(), ctx.projectFlag);
-const daemon = livingDaemon();
-if (daemon === undefined) throw new Error("daemon is not running");
-if (daemon.project !== undefined && daemon.project !== project.name) {
-  throw new Error(
-    `daemon serves project "${daemon.project}", not requested project "${project.name}"`,
-  );
-}
+const daemon = await requireDaemonControl(project.name);
 const response = await fetch(
   `http://127.0.0.1:${daemon.port}/runs/${issue}/turn-limit`,
   {

package/src/commands/intake.ts

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

package/src/commands/status.ts

@@ -47,7 +47,6 @@ function styleStatus(text: string): string {
     .map((line) => {
       if (
         line === "caps" ||
-        line === "daemon" ||
         line === "active runs" ||
         line === "active runs  (none)" ||
         line.startsWith("project   ")
@@ -56,6 +55,11 @@ function styleStatus(text: string): string {
       if (line.includes("STALLED")) return fail(line);
       if (/^(dispatch|ticks|pane|herdr|telegram|  healthz)\s+.*\b(running|healthy|ok)\b/.test(line))
         return ok(line);
+      // The daemon headline carries its own three states (#685): green while
+      // serving, amber when the probe timed out or the pid is gone — a bare
+      // `daemon` heading line no longer exists to style.
+      if (/^daemon\s+.*\b(not running|unresponsive)\b/.test(line)) return warn(line);
+      if (/^daemon\s+running\b/.test(line)) return ok(line);
       if (/^(dispatch|ticks|daemon)\s+.*\b(paused|stopped|not running|overdue)\b/.test(line))
         return warn(line);
       return line;

package/src/commands/watch.ts

@@ -21,31 +21,58 @@
 import type { CommandContext } from "./context.ts";
 import { findProject, loadConfig } from "../config.ts";
 import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
+import { shellQuote } from "../shell.ts";
 import { dbPath, openStore } from "../store.ts";
 
-const WATCH_USAGE = `omp-conductor watch — set a condition or carry note for the orchestrator itself.
+/** The flags each watch subcommand accepts, after the subcommand itself.
+ *  `add`'s positional note and `withdraw`'s positional id are validated by
+ *  the branches below, not through this table. */
+const WATCH_FLAGS: Readonly<Record<string, readonly string[]>> = {
+  add: ["--blocks", "--note", "--project", "--resolves-when"],
+  list: ["--json", "--project"],
+  withdraw: ["--project", "--reason"],
+};
 
-usage:
-  omp-conductor watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
-  omp-conductor watch list [--project NAME] [--json]
-  omp-conductor watch withdraw <id> [--reason TEXT] [--project NAME]
+/** Flags that take no value — `list --json` must not consume the token after it. */
+const WATCH_BOOL_FLAGS: Readonly<Record<string, true>> = { "--json": true };
 
-add records a row the daemon checks for you and the next tick reads, with no
-operator answer needed. list shows open watches, oldest first. withdraw ends
-one with a recorded reason — the verb that creates a watch is the verb that
-ends it. A watch whose PR condition can no longer be observed (the PR merged
-or closed first) is withdrawn by the daemon itself.`;
+/**
+ * Rejects any token after the subcommand that its surface does not declare,
+ * so a typo'd flag can never be silently ignored — the defect where
+ * `--condition` created a watch with no condition at all. Both `--flag VALUE`
+ * and `--flag=VALUE` are accepted, matching the shared `flag()` parser; a
+ * value flag consumes the next token, a `--flag=VALUE` form or a boolean flag
+ * never does. The same exit-2 scan `drain` and `stats` run (#462).
+ */
+function assertKnownWatchArgs(ctx: CommandContext, sub: string, from: number): void {
+  const allowed = WATCH_FLAGS[sub] ?? [];
+  for (let i = from; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    const eq = token.startsWith("--") ? token.indexOf("=") : -1;
+    const name = eq < 0 ? token : token.slice(0, eq);
+    if (allowed.includes(name)) {
+      if (eq < 0 && WATCH_BOOL_FLAGS[name] !== true) i += 1; // consume the flag's value token
+      continue;
+    }
+    process.stderr.write(
+      `omp-conductor: watch ${sub}: unexpected argument "${token}" (known: ${allowed.join(" ")}) — nothing was recorded\n`,
+    );
+    process.exit(2);
+  }
+}
 
 export async function watchCommand(ctx: CommandContext): Promise<void> {
+  // `--help`/`-h` never arrives here: the CLI dispatch gate answers a real
+  // help request from the manifest before this handler runs (#863), which is
+  // why the long-form prose lives on the manifest's `details` field rather
+  // than in a usage string this module would print itself.
   const sub = ctx.argv[1];
-  if (sub === "--help" || sub === "-h") {
-    process.stdout.write(WATCH_USAGE);
-    return;
-  }
   const project = findProject(loadConfig(), ctx.projectFlag);
   const store = openStore(dbPath());
   try {
     if (sub === "add") {
+      assertKnownWatchArgs(ctx, "add", 2);
       const note = ctx.flag("note")?.trim();
       if (note === undefined || note.length === 0 || note.startsWith("--")) {
         process.stderr.write("omp-conductor: watch add needs --note with what the next tick should know\n");
@@ -68,13 +95,17 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
         at: Date.now(),
       });
       const wake = condition === undefined ? "read by the next tick" : "the daemon wakes the next tick when it is met";
+      // The verb that ends the row names the project it was created in: this
+      // command is copied, and on a host with several projects the bare form is
+      // ambiguous (#810).
       process.stdout.write(
-        `watch ${watch.id} added — ${wake} (no operator answer needed); end with: omp-conductor watch withdraw ${watch.id}\n`,
+        `watch ${watch.id} added — ${wake} (no operator answer needed); end with: omp-conductor watch withdraw ${watch.id} --project ${shellQuote(project.name)}\n`,
       );
       return;
     }
 
     if (sub === "list" || sub === undefined) {
+      assertKnownWatchArgs(ctx, "list", 2);
       const open = store.openDecisions(project.name).filter((d) => d.kind === "watch");
       const now = Date.now();
       const watches = open.map((d) => ({
@@ -95,13 +126,17 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
       for (const watch of watches) {
         process.stdout.write(
           `${watch.id}  ${watch.ageHours}h  blocks:${watch.blocks ?? "-"}  ` +
-            `condition:${watch.condition ?? "-"}  ${watch.note}  (end: omp-conductor watch withdraw ${watch.id})\n`,
+            // The listing already resolved the project, so the cleanup command
+            // it displays must carry it: an operator copying a command from
+            // this output should get one that runs as written (#810).
+            `condition:${watch.condition ?? "-"}  ${watch.note}  (end: omp-conductor watch withdraw ${watch.id} --project ${shellQuote(project.name)})\n`,
         );
       }
       return;
     }
 
     if (sub === "withdraw") {
+      assertKnownWatchArgs(ctx, "withdraw", 3);
       const id = ctx.argv[2];
       if (id === undefined || id.startsWith("--")) {
         process.stderr.write("omp-conductor: watch withdraw needs the watch id\n");