omp-conductor 0.15.11 → 0.15.13

package/src/cli.ts

@@ -8,7 +8,7 @@
  * ./daemon.ts and the background process lifecycle in ./lifecycle.ts.
  */
 import { userInfo } from "node:os";
-import { findProject, loadConfig } from "./config.ts";
+import { loadConfig } from "./config.ts";
 import { AMEND_AREA_IDS } from "./setup.ts";
 import type { ProjectConfig } from "./types.ts";
 import { armCommand } from "./commands/arm.ts";
@@ -43,7 +43,12 @@ import { upgradeCommand } from "./commands/upgrade.ts";
 import { verbCommand } from "./commands/verb.ts";
 import { versionCommand } from "./commands/version.ts";
 import { workerCommand } from "./commands/worker.ts";
-import type { CommandContext, CommandHandler } from "./commands/context.ts";
+import {
+  COMMAND_SCOPES,
+  resolveProjectsByScope,
+  type CommandContext,
+  type CommandHandler,
+} from "./commands/context.ts";
 
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
@@ -55,7 +60,7 @@ usage:
   omp-conductor restart [--now] [--timeout SECONDS] [--port N] [--project NAME]
   omp-conductor upgrade [--to VERSION] [--project NAME]
   omp-conductor upgrade-install --to VERSION [--project NAME]
-  omp-conductor upgrade-rollback [--project NAME]
+  omp-conductor upgrade-rollback
   omp-conductor board [--project NAME] [--json]
   omp-conductor dashboard [--port N] [--host ADDR]
   omp-conductor status [--project NAME]
@@ -78,7 +83,7 @@ usage:
   omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
   omp-conductor event record --category NAME --summary TEXT --evidence REF [--occurred-at ISO] [--project NAME]
   omp-conductor report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure] [--events IDS] [--notices IDS] [--project NAME]
-  omp-conductor message --text TEXT [--project NAME]
+  omp-conductor message --text TEXT [--category CATEGORY] [--blocks TEXT] [--project NAME]
   omp-conductor decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
   omp-conductor decision resolve <id> --answer TEXT [--project NAME]
   omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
@@ -86,6 +91,7 @@ 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]
   omp-conductor help
 
   setup    interview, then write config.json, the labels, the briefs and the
@@ -110,9 +116,10 @@ usage:
            dispatch loop in the background and wait until it answers GET
            /healthz on :8787 (override with --port). Refuses if one is running.
   stop     stop the conductor: pause claiming, disarm ticks, then stop the
-           dispatch daemon (systemctl-aware, so Restart=on-failure cannot bring
-           it back). Pane stays up unless --pane is passed. To bounce the daemon
-           without stopping the fleet, use restart.
+           dispatch daemon (systemctl-aware: an explicit stop is recorded by
+           systemd, so Restart=always does not undo it). Pane stays up unless
+           --pane is passed. To bounce the daemon without stopping the fleet,
+           use restart.
   stop --pane
            also stop the conductor agent's pane and pin herdr-conductor recovery
            off for that agent only — it does NOT stop herdr-fleet.service or any
@@ -222,9 +229,14 @@ usage:
            last wrote to the session. This is how a locally injected tick
            answers or asks something directly: telegram_send keeps the active
            topic only while it names no chat, and a tick has no active topic to
-           keep. Text beginning "QUESTION:" carries the decision category; the
-           operator's availability policy still decides between sending now and
-           holding a notice, exactly as it does for an autonomous tick.
+           keep. A question — text beginning "QUESTION:", or a --category that
+           is not material — records an open decision row before delivery
+           (parked on silence: still pending in every tick until answered or
+           the seven-day expiry, so no one has to remember a separate
+           \`decision open\`), and --category carries the escalation category
+           directly instead of a text prefix. The operator's availability
+           policy still decides between sending now and holding a notice,
+           exactly as it does for an autonomous tick.
   decision record, list and close the questions you have put to your operator.
            A question that lives only in a session's context is lost to the next
            compaction, so \`decision open\` writes it down and every tick's prompt
@@ -239,8 +251,9 @@ usage:
   intake   keep a raw idea durably before it becomes anything: record it now
            with \`omp-conductor intake "<text>"\`, list what is still pending,
            dismiss what turned out to be nothing. Backed by the sqlite store,
-           not a session, so ideas survive restarts; grooming one into an issue
-           happens behind the scenes, not here.
+           not a session, so ideas survive restarts; the orchestrator grooms
+           one into an issue as its #300 duty and records that provenance with
+           \`omp-conductor intake groomed <id> --issue <url>\`.
   friction record a bounded observation the daemon cannot classify itself:
            an escalation that belonged in a digest, or a tick report that was
            noise/surprising. Repeated observations feed the existing Learning
@@ -249,8 +262,11 @@ usage:
            and exits. This is what \`start\` launches.
   resume   clear pause and any pane-recovery pin. Does NOT re-arm: run arm after
            an inbound Telegram proof to bring ticks back. Use --all for every project.
-  setup host
+  setup host [NAME]
            re-stage the systemd unit and run the install behind one confirm.
+           The units are host-global; NAME (or --project NAME) says which
+           project's per-project tail (tick config, brief link) to write, and
+           is required on a host with several configured projects.
   setup graph
            set up the code-graph indexes workers query instead of grepping, end
            to end: check prerequisites, clone any missing index-only clone as
@@ -402,14 +418,10 @@ const ctx: CommandContext = {
 };
 
 function targetProjects(): ProjectConfig[] {
-  const cfg = loadConfig();
-  if (argv.includes("--all")) return cfg.projects;
-  if (projectFlag === undefined && cfg.projects.length > 1) {
-    throw new Error(
-      `config has ${cfg.projects.length} projects; use --project NAME or --all`,
-    );
-  }
-  return [findProject(cfg, projectFlag)];
+  // The fleet resolution, delegated to the scope machinery (#514) so the
+  // arm/disarm/hold/resume/stop "every project, or the named one" shape is
+  // the same code the classification describes it as.
+  return resolveProjectsByScope(loadConfig(), "fleet", projectFlag, argv.includes("--all"));
 }
 
 /**
@@ -484,6 +496,14 @@ try {
     );
     process.exit(2);
   }
+  // 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
+  // (#514). Host-scoped verbs keep the flag because each one has a documented
+  // per-project tail (or already refuses to narrow, #389).
+  if (COMMAND_SCOPES[cmd ?? ""] === "none" && projectFlag !== undefined) {
+    process.stderr.write(`omp-conductor: ${cmd} does not take a project — it needs no --project\n`);
+    process.exit(2);
+  }
   await handler(ctx);
 } catch (err) {
   // Config, lifecycle and `gh` errors are written to be read by a human, so

package/src/commands/context.ts

@@ -1,4 +1,5 @@
-import type { ProjectConfig } from "../types.ts";
+import { findProject } from "../config.ts";
+import type { ConductorConfig, ProjectConfig } from "../types.ts";
 
 /**
  * What a command handler may read about the invocation it was dispatched for.
@@ -47,3 +48,103 @@ export interface CommandContext {
 
 /** One operator subcommand: what the registration table maps a verb to. */
 export type CommandHandler = (ctx: CommandContext) => Promise<void> | void;
+
+/**
+ * The project scope a command's work is bound to, declared once per verb
+ * (#514). Every command in `omp/src/commands/` carries one, and the
+ * resolution a command performs must follow it rather than defaulting to
+ * `findProject`:
+ *
+ * - `"project"` — the verb acts on exactly one configured project. It
+ *   resolves through {@link findProject}, so a multi-project config demands
+ *   `--project NAME` (ledger, stats, event, report, decision, …).
+ * - `"host"` — the verb acts on the one shared host (units, daemon, package
+ *   surfaces), which no configured project can make ambiguous. It never
+ *   resolves a project; `--project` is either refused (upgrade/restart
+ *   refuse to narrow the shared multi-project daemon, #389) or accepted only
+ *   for the documented per-project tail it affects (start's /healthz check,
+ *   the `daemon --once` drill).
+ * - `"fleet"` — the verb acts on every configured project by default and
+ *   narrows with `--project NAME` / `--all`, the `targetProjects` shape
+ *   (arm, disarm, hold, resume, stop, status, board).
+ * - `"none"` — the verb takes no project at all (dashboard, help, version).
+ */
+export type CommandScope = "project" | "host" | "fleet" | "none";
+
+/**
+ * The explicit scope of every registered command, keyed by the exact strings
+ * the CLI accepts (aliases included). `cli.test.ts` asserts each module in
+ * `commands/` is classified and that each scope resolves the way the table
+ * below says; REFERENCE.md's CLI table carries the same classification in
+ * human form.
+ */
+export const COMMAND_SCOPES: Readonly<Record<string, CommandScope>> = {
+  // project — exactly one project; findProject demands --project when several
+  "brief-upgrade": "project",
+  decision: "project",
+  event: "project",
+  extend: "project",
+  friction: "project",
+  intake: "project",
+  ledger: "project",
+  message: "project",
+  report: "project",
+  setup: "project", // the wizard and `setup graph` configure one project
+  stats: "project",
+  tail: "project",
+  unblock: "project",
+  verb: "project",
+  worker: "project",
+  // host — the shared daemon/package surfaces; never resolves a project
+  daemon: "host",
+  restart: "host",
+  start: "host",
+  upgrade: "host",
+  "upgrade-install": "host",
+  "upgrade-rollback": "host",
+  // fleet — every project by default, --project narrows
+  arm: "fleet",
+  board: "fleet",
+  disarm: "fleet",
+  doctor: "fleet",
+  hold: "fleet",
+  resume: "fleet",
+  status: "fleet",
+  stop: "fleet",
+  // none — no project at all
+  dashboard: "none",
+  help: "none",
+  "--help": "none",
+  "-h": "none",
+  version: "none",
+  "--version": "none",
+  "-V": "none",
+};
+
+/**
+ * Resolve the projects one command's work covers, from its declared scope
+ * (#514) — the single mechanism every scope falls out of, so a host-scoped
+ * command can never inherit `findProject`'s ambiguity by accident.
+ *
+ * `"host"`/`"none"` resolve to nothing. `"fleet"` returns every configured
+ * project with `all`, the named one, or — with neither — the sole configured
+ * project, refusing a multi-project config exactly as `targetProjects` always
+ * has. `"project"` returns exactly one, via {@link findProject}.
+ */
+export function resolveProjectsByScope(
+  cfg: ConductorConfig,
+  scope: CommandScope,
+  name: string | undefined,
+  all: boolean,
+): ProjectConfig[] {
+  if (scope === "host" || scope === "none") return [];
+  if (scope === "fleet") {
+    if (all) return [...cfg.projects];
+    if (name === undefined && cfg.projects.length > 1) {
+      throw new Error(
+        `config has ${cfg.projects.length} projects; use --project NAME or --all`,
+      );
+    }
+  }
+  return [findProject(cfg, name)];
+}

package/src/commands/doctor.ts

@@ -42,8 +42,10 @@ flags:
                          contract
   --probe-telegram       the ONE opt-in side effect: send one self-identified
                          test message through the report transport
-  --project NAME         the project to check (required only when the config
-                         has more than one)
+  --project NAME         narrow to one project. With no name, the host-wide
+                         facts are checked once and every configured project's
+                         per-project facts (labels, timezone, telegram) are
+                         checked, each named.
 
 Exit code is 0 only when nothing failed; warnings do not fail the run.`;
 

package/src/commands/intake.ts

@@ -3,9 +3,9 @@
  *
  * The store is the point of the verb: an idea captured at 02:00 is still there
  * after a restart, and `status` counts what is still pending so a backlog
- * cannot quietly empty itself. This surface only records, lists and dismisses;
- * turning an idea into an issue is #300, which uses `resolveIntake`'s
- * `groomed` path.
+ * cannot quietly empty itself. This surface records, lists, dismisses and —
+ * once the orchestrator has groomed an idea into an issue (#300) — marks the
+ * provenance of that grooming via `resolveIntake`'s `groomed` path.
  */
 
 import type { CommandContext } from "./context.ts";
@@ -18,15 +18,18 @@ 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, and an idea can later be groomed into an issue.`;
+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 };
+const INTAKE_FLAGS: Record<string, true> = { "--project": true, "--issue": true };
 
 /** Every remaining token after the subverb must be one of the known flags
  *  (or its value), otherwise the operator typo'd something that would be
@@ -89,6 +92,24 @@ export async function intakeCommand(ctx: CommandContext): Promise<void> {
       return;
     }
 
+    if (sub === "groomed") {
+      assertKnownArgs(ctx, 3);
+      const id = ctx.argv[2];
+      const url = ctx.flag("issue")?.trim();
+      if (id === undefined || id.startsWith("--") || url === undefined || url.length === 0) {
+        process.stderr.write("omp-conductor: intake groomed needs the idea id and --issue <url>\n");
+        process.exit(2);
+      }
+      if (!store.resolveIntake(id, "groomed", url)) {
+        // Ticks retry: an id that is already groomed (or unknown) is a no-op
+        // with a message, not an error, so a re-filed tick never fails here.
+        process.stdout.write(`intake ${id} already resolved or unknown — nothing to do\n`);
+        return;
+      }
+      process.stdout.write(`intake ${id} groomed → ${url}\n`);
+      return;
+    }
+
     if (sub !== undefined && sub.startsWith("--") && INTAKE_FLAGS[sub] !== true) {
       process.stderr.write(`omp-conductor: intake: unexpected argument "${sub}"\n`);
       process.exit(2);

package/src/commands/message.ts

@@ -1,6 +1,13 @@
 /**
  * `message` — deliver one direct Telegram message to the project's own chat and forum topic, applying the same availability policy as a tick.
  *
+ * A question-shaped message — text that begins with the floor's `QUESTION:`
+ * marker, or an explicitly declared escalation `--category` that is not
+ * `material` — is an ask, not a send: the row is recorded before anything is
+ * delivered (#520), so "asked once, no reply" is a durable open decision row
+ * re-surfaced in every tick until answered or the seven-day expiry, and the
+ * caller never has to remember a separate `decision open`.
+ *
  * 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.
@@ -9,40 +16,81 @@
 import type { CommandContext } from "./context.ts";
 import { randomUUID } from "node:crypto";
 import { findProject, loadConfig } from "../config.ts";
-import { deliverOperatorMessage, type OperatorMessageOutcome } from "../reports.ts";
+import { deliverOperatorMessage, operatorMessageCategory, type OperatorMessageOutcome } from "../reports.ts";
 import { dbPath, openStore } from "../store.ts";
+import { INTERRUPT_CATEGORIES, type DecisionRecord, type InterruptCategory } from "../types.ts";
+
+/** The floor's "this needs an answer" marker, as every other classifier reads it. */
+const QUESTION_MARKER = /^\s*QUESTION:\s/i;
 
 export async function messageCommand(ctx: CommandContext): Promise<void> {
-const rawText = ctx.flag("text");
-const body = rawText?.trim();
-if (body === undefined || body.length === 0 || rawText?.startsWith("--") === true) {
-  process.stderr.write("omp-conductor: message needs --text with the message to deliver\n");
-  process.exit(2);
-}
-const project = findProject(loadConfig(), ctx.projectFlag);
-const store = openStore(dbPath());
-let outcome: OperatorMessageOutcome;
-try {
-  outcome = await deliverOperatorMessage(project, body, {
-    store,
-    at: Date.now(),
-    noticeId: randomUUID(),
-  });
-} catch (err) {
-  process.stderr.write(
-    `omp-conductor: message: ${err instanceof Error ? err.message : String(err)}\n`,
+  const rawText = ctx.flag("text");
+  const body = rawText?.trim();
+  if (body === undefined || body.length === 0 || rawText?.startsWith("--") === true) {
+    process.stderr.write("omp-conductor: message needs --text with the message to deliver\n");
+    process.exit(2);
+  }
+  const categoryRaw = ctx.flag("category");
+  if (
+    categoryRaw !== undefined &&
+    !(INTERRUPT_CATEGORIES as readonly string[]).includes(categoryRaw)
+  ) {
+    process.stderr.write(
+      `omp-conductor: message category must be one of ${INTERRUPT_CATEGORIES.join(", ")} — a question's category is part of the ask, never a text prefix\n`,
+    );
+    process.exit(2);
+  }
+  const category = categoryRaw as InterruptCategory | undefined;
+  const blocks = ctx.flag("blocks")?.trim();
+
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const store = openStore(dbPath());
+  // The durable row exists before the delivery attempt, exactly like the
+  // `conductor_ask` tool: a crash at any point leaves a recorded question, so
+  // the "asked, awaiting the operator" half of the ask cannot be lost. Silence
+  // means the row stays open — re-surfaced in every tick until answered or the
+  // seven-day expiry; it never records an approval.
+  const effectiveCategory = category ?? operatorMessageCategory(body);
+  const isAsk = QUESTION_MARKER.test(body) || effectiveCategory !== "material";
+  let row: DecisionRecord | undefined;
+  let outcome: OperatorMessageOutcome;
+  try {
+    if (isAsk) {
+      row = store.createDecision({
+        project: project.name,
+        // The row archives the question, not the delivery prefix.
+        question: body.replace(QUESTION_MARKER, "").trim(),
+        ...(blocks === undefined ? {} : { blocks }),
+        at: Date.now(),
+      });
+    }
+    outcome = await deliverOperatorMessage(project, body, {
+      store,
+      at: Date.now(),
+      noticeId: randomUUID(),
+      ...(category === undefined ? {} : { category }),
+    });
+  } catch (err) {
+    process.stderr.write(
+      `omp-conductor: message: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(2);
+  } finally {
+    store.close();
+  }
+  if (row !== undefined) {
+    process.stdout.write(
+      `decision ${row.id} recorded — parked on silence: the question stays open until answered or the seven-day expiry. ` +
+        `Resolve it later with: omp-conductor decision resolve ${row.id} --answer "..."\n`,
+    );
+  }
+  process.stdout.write(
+    outcome.kind === "sent"
+      ? // Not "into the topic": a stale topic degrades to the flat chat with
+        // its own warning on stderr, and this line must not contradict it.
+        `message delivered to ${project.name}'s configured Telegram target (${outcome.category})\n`
+      : `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
+          `${outcome.reason === "availability" ? "outside the availability window" : "a digest-only category"})\n` +
+          "nothing was sent; the daemon releases it with the next digest or working-hours catch-up\n",
   );
-  process.exit(2);
-} finally {
-  store.close();
-}
-process.stdout.write(
-  outcome.kind === "sent"
-    ? // Not "into the topic": a stale topic degrades to the flat chat with
-      // its own warning on stderr, and this line must not contradict it.
-      `message delivered to ${project.name}'s configured Telegram target (${outcome.category})\n`
-    : `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
-        `${outcome.reason === "availability" ? "outside the availability window" : "a digest-only category"})\n` +
-        "nothing was sent; the daemon releases it with the next digest or working-hours catch-up\n",
-);
 }

package/src/commands/report.ts

@@ -13,7 +13,14 @@ import { findProject, loadConfig } from "../config.ts";
 import { digestDue } from "../digest-schedule.ts";
 import { dbPath, openStore } from "../store.ts";
 import { digestDedupeKey } from "../reports.ts";
-import { DEFAULT_REPORT_POLICY, REPORT_KINDS, type InterruptCategory, type ReportKind } from "../types.ts";
+import {
+  DEFAULT_REPORT_POLICY,
+  INTERRUPT_CATEGORIES,
+  REPORT_KINDS,
+  SESSION_ROLE_ENV,
+  type InterruptCategory,
+  type ReportKind,
+} from "../types.ts";
 
 export async function reportCommand(ctx: CommandContext): Promise<void> {
 const rawText = ctx.flag("text");
@@ -39,6 +46,23 @@ if (kind !== "digest" && (ctx.argv.includes("--events") || ctx.argv.includes("--
   );
   process.exit(2);
 }
+// Escalation tiers are not a worker session's to claim, like every other
+// privileged surface (#508). The daemon stamps the session role on spawned
+// sessions; a value outside the closed vocabulary is refused, never assumed.
+// A bare CLI run (operator's shell) has the env absent and stays the
+// orchestrator surface, so this refuses precisely the worker who would
+// otherwise page the operator from inside a worktree.
+const sessionRole = process.env[SESSION_ROLE_ENV];
+if (
+  sessionRole === "worker" &&
+  INTERRUPT_CATEGORIES.some((category) => category !== "material" && category === kind)
+) {
+  process.stderr.write(
+    `omp-conductor: report: escalation tier is not a worker session's to claim; ` +
+      `only the operator or orchestrator may hand off a ${kind} report\n`,
+  );
+  process.exit(3);
+}
 const project = findProject(loadConfig(), ctx.projectFlag);
 const store = openStore(dbPath());
 try {
@@ -73,8 +97,20 @@ try {
     const category: InterruptCategory = kind;
     const disposition = interruptDisposition(policy, category, at);
     if (disposition === "digest") {
+      // Name the flags that would have worked rather than only the digest:
+      // the categories this policy actually pages are how a handoff like a
+      // tier-2 install notice gets through, and there is no other spelling to
+      // guess at (#508).
+      const interruptable = INTERRUPT_CATEGORIES.filter(
+        (candidate) => interruptDisposition(policy, candidate, at) === "interrupt",
+      );
+      const flags =
+        interruptable.length > 0
+          ? `hand it off as a category this policy pages (--kind ${interruptable.join("|")}) or fold it ` +
+            "into the next digest (--kind digest)"
+          : "fold it into the next digest (--kind digest)";
       process.stderr.write(
-        `omp-conductor: report: ${category} updates are digest-only under this reporting policy; fold this into the next digest (--kind digest)\n`,
+        `omp-conductor: report: ${category} updates are digest-only under this reporting policy; ${flags}\n`,
       );
       process.exit(2);
     }