omp-conductor 0.18.0 → 0.18.1

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/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,6 +21,7 @@
 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.
@@ -36,6 +37,44 @@ 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.`;
 
+/** 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"],
+};
+
+/** Flags that take no value — `list --json` must not consume the token after it. */
+const WATCH_BOOL_FLAGS: Readonly<Record<string, true>> = { "--json": true };
+
+/**
+ * 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> {
   const sub = ctx.argv[1];
   if (sub === "--help" || sub === "-h") {
@@ -46,6 +85,7 @@ export async function watchCommand(ctx: CommandContext): Promise<void> {
   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 +108,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 +139,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");

package/src/commands/worker.ts

@@ -2,13 +2,13 @@
  * `worker` — pause/resume/stop one live worker session through the daemon's run-control HTTP endpoints.
  *
  * 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} so a
+ * live systemd-run daemon stays reachable when its pidfile is missing (#811).
  */
 
 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 workerCommand(ctx: CommandContext): Promise<void> {
 const sub = ctx.argv[1];
@@ -28,13 +28,12 @@ if (sub === "stop" && (reason === undefined || reason === "" || reason.length >
   process.exit(2);
 }
 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}"`,
-  );
-}
+// The pidfile is authoritative when it names a live process; a missing or
+// stale record falls back to the systemd unit, proved through its own
+// /healthz answer, so a live unit-owned daemon is never reported stopped
+// because the runtime directory was wiped (#811). The refusal chain is
+// shared with `extend` through requireDaemonControl.
+const daemon = await requireDaemonControl(project.name);
 const response = await fetch(
   `http://127.0.0.1:${daemon.port}/runs/${issue}/${sub}`,
   {

package/src/config-schema.ts

@@ -336,6 +336,25 @@ const stateLabelsSchema = z
   })
   .partial();
 
+// ---------------------------------------------------------------------------
+// Host constraints (#721)
+// ---------------------------------------------------------------------------
+
+const hostConstraintsSchema = z
+  .object({
+    description: z.string().min(1).describe("What this host is and what else it runs"),
+    path: z
+      .string()
+      .min(1)
+      .describe('The non-interactive PATH a script or `ssh host "<cmd>"` invocation must export'),
+    conventions: z
+      .record(z.string().min(1), z.string().min(1))
+      .describe("Per-repo command conventions, keyed by the brief's `owner/repo` slug"),
+  })
+  .strict()
+  .partial()
+  .describe("Operator-authored host facts rendered into every worker brief");
+
 // ---------------------------------------------------------------------------
 // Project / root
 // ---------------------------------------------------------------------------
@@ -409,6 +428,11 @@ const configSchema = z
       .min(1, "must name a directory")
       .optional()
       .describe("Absolute directory for restorable conductor.db snapshots; defaults to <stateDir>/backups/db"),
+    // Cores and RAM are derived by host.ts at render time; only what the
+    // operator must type belongs in this block.
+    host: hostConstraintsSchema
+      .optional()
+      .describe("Host facts every worker brief renders; absent renders no section"),
     projects: z.array(projectSchema).min(1, `"projects" must be a non-empty array — the dispatcher has nothing to service otherwise`),
   })
   .loose()

package/src/config.ts

@@ -49,6 +49,7 @@ import {
   type Caps,
   type ConductorConfig,
   type DigestCadence,
+  type HostConstraints,
   type InterruptCategory,
   type MergePreconditions,
   type PlanUsageCap,
@@ -1092,8 +1093,48 @@ function finalize(data: unknown, path: string): ConductorConfig {
     });
   }
 
+  const rawHost = root["host"] as Raw | undefined;
+  const host = finalizeHost(rawHost);
+  const rawDbBackupDir = root["dbBackupDir"];
+  const dbBackupDir = typeof rawDbBackupDir === "string" ? rawDbBackupDir : undefined;
+
   if (problems.length > 0) throw new Error(problemEnvelope(path, problems));
-  return { version: CONFIG_VERSION, defaults, projects };
+  // `ConductorConfig` is rebuilt here, so every optional top-level key must be
+  // spelled out or it silently vanishes from every loaded config. `dbBackupDir`
+  // and `host` are the two today; a third needs its own line below (#773).
+  return {
+    version: CONFIG_VERSION,
+    defaults,
+    projects,
+    ...(dbBackupDir === undefined ? {} : { dbBackupDir }),
+    ...(host === undefined ? {} : { host }),
+  };
+}
+
+/**
+ * The typed host-constraints block (#721), or `undefined` when nothing usable
+ * was configured — matching the schema's "absent renders no section" promise.
+ * Trimming and empty-drop mirror the other hand-edited string fields; an
+ * object whose every key is empty loads as if the field were absent.
+ */
+function finalizeHost(parsed: Raw | undefined): HostConstraints | undefined {
+  if (parsed === undefined) return undefined;
+  const out: HostConstraints = {};
+  const description = parsed["description"];
+  if (typeof description === "string" && description.trim() !== "") out.description = description.trim();
+  const path = parsed["path"];
+  if (typeof path === "string" && path.trim() !== "") out.path = path.trim();
+  const conventions = parsed["conventions"];
+  if (typeof conventions === "object" && conventions !== null && !Array.isArray(conventions)) {
+    const kept: Record<string, string> = {};
+    for (const [slug, value] of Object.entries(conventions as Record<string, unknown>)) {
+      if (typeof value === "string" && value.trim() !== "" && slug.trim() !== "") {
+        kept[slug.trim()] = value.trim();
+      }
+    }
+    if (Object.keys(kept).length > 0) out.conventions = kept;
+  }
+  return Object.keys(out).length === 0 ? undefined : out;
 }
 
 function finalizeProject(