omp-conductor 0.18.1 → 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";
@@ -55,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}`);
@@ -254,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-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" },
@@ -418,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" },
@@ -443,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" },
@@ -456,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: [],
   },
   {
@@ -480,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",
     "",

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/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/watch.ts

@@ -24,19 +24,6 @@ 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.
-
-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]
-
-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.`;
-
 /** 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. */
@@ -76,11 +63,11 @@ function assertKnownWatchArgs(ctx: CommandContext, sub: string, from: number): v
 }
 
 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 {

package/src/config-schema.ts

@@ -31,6 +31,7 @@ import {
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
+  DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   DEFAULT_REVIEW_MAX_ROUNDS,
   DEFAULT_REVIEW_STRICTNESS,
   DRAFT_POLICIES,
@@ -41,6 +42,7 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  REVIEW_ADJUDICATOR_RE,
   REVIEW_MAX_ROUNDS_MAX,
   REVIEW_MAX_ROUNDS_MIN,
   REVIEW_STRICTNESS,
@@ -265,11 +267,15 @@ const armSchema = z
 
 /**
  * The per-project review policy (#678): how strictly green PRs are reviewed
- * and returned, and the hard ceiling on review rounds per PR lifecycle. Absent
- * or a legacy config without the key loads as `medium` with
- * {@link DEFAULT_REVIEW_MAX_ROUNDS} rounds — the recommended default for a new
- * project, materialised deterministically for every existing one, with the
- * schema bounds and the runtime defaults read from the same constants.
+ * and returned, the hard ceiling on review rounds per PR lifecycle, and which
+ * OMP model role carries the terminal review-ceiling adjudication (#875).
+ * Absent or a legacy config without the keys loads as `medium` with
+ * {@link DEFAULT_REVIEW_MAX_ROUNDS} rounds and
+ * {@link DEFAULT_REVIEW_ADJUDICATOR_ROLE} as adjudicator — the recommended
+ * defaults for a new project, materialised deterministically for every
+ * existing one, with the schema bounds and the runtime defaults read from the
+ * same constants. The adjudicator names a role only; a provider/model is
+ * refused here, because OMP owns exact provider selection.
  */
 const reviewSchema = z
   .object({
@@ -280,9 +286,16 @@ const reviewSchema = z
       .min(REVIEW_MAX_ROUNDS_MIN)
       .max(REVIEW_MAX_ROUNDS_MAX)
       .default(DEFAULT_REVIEW_MAX_ROUNDS),
+    adjudicator: z
+      .string()
+      .regex(
+        REVIEW_ADJUDICATOR_RE,
+        "must name one OMP model role — a single role token like \"task\" (never a provider/model, which omp owns)",
+      )
+      .default(DEFAULT_REVIEW_ADJUDICATOR_ROLE),
   })
   .strict()
-  .describe("Review strictness and round ceiling for green PRs");
+  .describe("Review strictness, round ceiling and adjudicator role for green PRs");
 
 const releasePolicySchema = z.union([
   releasePolicyLegacyEnum,

package/src/config.ts

@@ -28,6 +28,7 @@ import {
   DEFAULT_PROJECT_POLICY,
   DEFAULT_REPORT_POLICY,
   DEFAULT_REPORT_SCOPE,
+  DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   DEFAULT_REVIEW_MAX_ROUNDS,
   DEFAULT_REVIEW_POLICY,
   DEFAULT_REVIEW_STRICTNESS,
@@ -349,12 +350,20 @@ export function resolveArmProof(p: ProjectConfig): ArmProof {
  * The loader always materialises `review` (finalizeProject), so this is only
  * ever the fallback for a `ProjectConfig` that never went through it — a
  * hand-built one in a test, or a config written before the key existed.
- * Absent resolves to {@link DEFAULT_REVIEW_POLICY}, the documented migration
- * default every existing install deterministically upgrades to. A fresh object
- * each call, so mutating the result cannot reach the config it came from.
+ * Absent (or a legacy config that stopped at strictness and maxRounds)
+ * resolves to {@link DEFAULT_REVIEW_POLICY}, the documented migration default
+ * every existing install deterministically upgrades to — the adjudicator role
+ * included, so no consumer ever reads a policy without one (#875). A fresh
+ * object each call, so mutating the result cannot reach the config it came
+ * from.
  */
 export function resolveReview(p: ProjectConfig): ReviewPolicy {
-  return { ...(p.review ?? DEFAULT_REVIEW_POLICY) };
+  const base = p.review ?? DEFAULT_REVIEW_POLICY;
+  return {
+    strictness: base.strictness ?? DEFAULT_REVIEW_STRICTNESS,
+    maxRounds: base.maxRounds ?? DEFAULT_REVIEW_MAX_ROUNDS,
+    adjudicator: base.adjudicator ?? DEFAULT_REVIEW_ADJUDICATOR_ROLE,
+  };
 }
 
 /**
@@ -889,11 +898,14 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
       return `policy must be an object with "merge" and "release" sections`;
     }
     if (rel.length === 1 && relStr === "review") {
-      return `review must be an object with "strictness" and "maxRounds"`;
+      return `review must be an object with "strictness", "maxRounds" and "adjudicator"`;
     }
     if (rel.length === 2 && rel[0] === "review" && rel[1] === "maxRounds") {
       return `review.maxRounds must be an integer between ${REVIEW_MAX_ROUNDS_MIN} and ${REVIEW_MAX_ROUNDS_MAX}, found ${found()}`;
     }
+    if (rel.length === 2 && rel[0] === "review" && rel[1] === "adjudicator") {
+      return `review.adjudicator must be a string naming one OMP model role, found ${found()}`;
+    }
     if (rel.length === 2 && relStr === "policy") return `${pathStr} must be an object`;
     if (rel.length === 1 && relStr === "caps") return `caps must be an object`;
     if (rel.length === 2 && relStr === "caps" && rel[1] === "planUsage") {
@@ -944,7 +956,7 @@ function clauseFor(rel: readonly PropertyKey[], issue: {
   if (issue.code === "unrecognized_keys") {
     const keys = (issue.keys ?? []).join(", ");
     if (pathStr === "policy") return `policy has unknown key(s): ${keys} — expected "merge" or "release"`;
-    if (pathStr === "review") return `review has unknown key(s): ${keys} — expected "strictness" and "maxRounds"`;
+    if (pathStr === "review") return `review has unknown key(s): ${keys} — expected "strictness", "maxRounds" and "adjudicator"`;
     if (pathStr === "policy.merge") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_MERGE_KEYS}`;
     if (pathStr === "policy.release") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_RELEASE_KEYS}`;
     if (pathStr === "caps.planUsage") {
@@ -1320,14 +1332,17 @@ function finalizeArm(parsed: Raw | undefined): ProjectConfig["arm"] {
  * {@link DEFAULT_REVIEW_POLICY}, the documented migration default, so an
  * upgrade changes no existing project's behaviour beyond what its operators
  * then choose in setup. zod has already rejected anything outside the
- * strictness vocabulary or the validated round range, so this only fills the
- * absent-case default.
+ * strictness vocabulary, the validated round range or the adjudicator role
+ * token grammar, so this only fills the absent-case defaults — the
+ * adjudicator included (#875), deterministically the same role a new
+ * project's setup starts from.
  */
 function finalizeReview(parsed: Raw | undefined): ProjectConfig["review"] {
   if (parsed === undefined) return { ...DEFAULT_REVIEW_POLICY };
   return {
     strictness: (parsed["strictness"] as ReviewStrictness | undefined) ?? DEFAULT_REVIEW_STRICTNESS,
     maxRounds: (parsed["maxRounds"] as number | undefined) ?? DEFAULT_REVIEW_MAX_ROUNDS,
+    adjudicator: (parsed["adjudicator"] as string | undefined) ?? DEFAULT_REVIEW_ADJUDICATOR_ROLE,
   };
 }