omp-conductor 0.10.0 → 0.12.0

package/src/cli.ts

@@ -36,6 +36,7 @@ import {
   startHerdrFleet,
 } from "./fleet.ts";
 import { formatGraphSetup, graphRepos, writeGraphSetup, type GraphSetupWrite } from "./graph.ts";
+import { readBaseChain } from "./gitops.ts";
 import {
   clearRecord,
   DEFAULT_PORT,
@@ -48,6 +49,7 @@ import {
 } from "./lifecycle.ts";
 import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
 import { digestDedupeKey } from "./reports.ts";
+import { digestDue } from "./digest-schedule.ts";
 import {
   briefPathForProject,
   policyPathForProject,
@@ -61,7 +63,7 @@ import { formatVerbLedgerEntry } from "./verbs/ledger.ts";
 import { makeTracker } from "./tracker/github.ts";
 import { githubVerbActions } from "./verbs/actions.ts";
 import { handleVerbCall, type VerbChannel } from "./verbs/server.ts";
-import { REPORT_KINDS, VERB_NAMES } from "./types.ts";
+import { REPORT_KINDS, DEFAULT_REPORT_POLICY, VERB_NAMES } from "./types.ts";
 import type { ProjectConfig, ReportKind } from "./types.ts";
 import { formatUnblock, unblockIssue } from "./unblock.ts";
 import { DEFAULT_DEPS, drainAndRestart, upgradeConductor, type UpgradeDeps } from "./upgrade.ts";
@@ -102,6 +104,8 @@ usage:
   omp-conductor release-pane [--project NAME]
   omp-conductor tail <issue> [--project NAME]
   omp-conductor extend <issue> --turns N [--project NAME]
+  omp-conductor worker pause <issue> [--project NAME]
+  omp-conductor worker resume <issue> [--project NAME]
   omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
   omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
   omp-conductor daemon [--once] [--port N] [--project NAME]
@@ -170,6 +174,9 @@ usage:
            transcript has stopped growing.
   extend   monotonically raise a live run's turn ceiling without restarting its
            session. Refuses settled runs and values at or below its current cap.
+  worker   cooperatively pause one live worker at harness idle, then resume the
+           same session with a continuation prompt. Its wall clock is frozen
+           while parked. Distinct from fleet-level pause/resume.
   unblock  clear <issue>'s blocked and failed labels so the next tick can claim
            it again — the supported way back for an escalation you answered,
            and why the brief's "never hand-edit a state label" rule can stay
@@ -784,6 +791,50 @@ try {
       break;
     }
 
+    case "worker": {
+      const sub = argv[1];
+      if (sub !== "pause" && sub !== "resume") {
+        process.stderr.write(
+          "omp-conductor: worker needs pause or resume, then an issue number\n",
+        );
+        process.exit(2);
+      }
+      const issue = issueArg("worker", argv[2]);
+      const project = findProject(loadConfig(), flag(argv, "project"));
+      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 response = await fetch(
+        `http://127.0.0.1:${daemon.port}/runs/${issue}/${sub}`,
+        {
+          method: "PUT",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ project: project.name }),
+        },
+      );
+      const payload = (await response.json()) as {
+        error?: unknown;
+        runId?: unknown;
+        phase?: unknown;
+      };
+      if (!response.ok) {
+        throw new Error(
+          typeof payload.error === "string" ? payload.error : `daemon returned HTTP ${response.status}`,
+        );
+      }
+      if (typeof payload.runId !== "string" || typeof payload.phase !== "string") {
+        throw new Error("daemon returned an invalid worker-control response");
+      }
+      process.stdout.write(
+        `#${issue} worker ${payload.phase} (run ${payload.runId})\n`,
+      );
+      break;
+    }
+
     case "unblock": {
       const issue = issueArg("unblock", argv[1]);
       const cfg = loadConfig();
@@ -873,6 +924,7 @@ try {
             pausedAt,
             log: (m) => process.stderr.write(`${m}\n`),
             now: () => Date.now(),
+            chain: { readBaseChain },
           },
           channel,
           { verb: name, args },
@@ -914,15 +966,51 @@ try {
       const store = openStore(dbPath());
       try {
         const at = Date.now();
+        // #229: the policy decides what may interrupt the phone. A kind the
+        // policy defers is refused here rather than silently turning into a
+        // page, or a digest going out off-schedule.
+        const policy = project.reporting;
+        if (kind === "digest") {
+          const digestPolicy = policy?.digest ?? { cadence: "per-tick" };
+          if (digestPolicy.cadence === "none") {
+            process.stderr.write(`omp-conductor: report: digest cadence is "none" for this project\n`);
+            process.exit(2);
+          }
+          if (digestPolicy.cadence === "daily" && digestPolicy.at !== undefined) {
+            const lastKey = store.lastDigestDedupeKey(project.name);
+            const lastDay = lastKey === undefined ? undefined : lastKey.slice("digest:".length);
+            if (!digestDue(policy ?? DEFAULT_REPORT_POLICY, lastDay, at)) {
+              process.stderr.write(
+                `omp-conductor: report: the daily digest is not due until ${digestPolicy.at}` +
+                  `${digestPolicy.timezone === undefined ? "" : ` ${digestPolicy.timezone}`}\n`,
+              );
+              process.exit(2);
+            }
+          }
+        }
+        if (kind === "material") {
+          const interruptOn = policy?.interruptOn;
+          if (interruptOn !== undefined && !interruptOn.includes("material")) {
+            process.stderr.write(
+              "omp-conductor: report: material updates are digest-only under this reporting policy; fold this into the next digest (--kind digest)\n",
+            );
+            process.exit(2);
+          }
+        }
         const { report, deduped } = store.enqueueReport({
           project: project.name,
           kind,
           body,
           // Only the digest is at-most-once. A material report describes one
           // event as it happens, and two of those in a day are two events.
-          ...(kind === "digest" ? { dedupeKey: digestDedupeKey(at) } : {}),
+          ...(kind === "digest"
+            ? { dedupeKey: digestDedupeKey(at, project.reporting?.digest?.timezone) }
+            : {}),
           at,
         });
+        // The held notices an accepted digest re-surfaces are now owed by it,
+        // whatever the model goes on to write.
+        if (kind === "digest") store.markNoticesDigested(project.name, at);
         process.stdout.write(
           deduped
             ? `today's digest was already handed over as report ${report.id} (${report.state}) — nothing queued\n` +

package/src/config.ts

@@ -24,6 +24,7 @@ import {
   DEFAULT_AUTHORITY,
   DEFAULT_CAPS,
   DEFAULT_PROJECT_POLICY,
+  DEFAULT_REPORT_POLICY,
   DEFAULT_REPORT_SCOPE,
   DENIED_RELEASE_GRANTS,
   DRAFT_POLICIES,
@@ -34,8 +35,12 @@ import {
   RELEASE_REQUIREMENTS,
   RELEASE_SHAPES,
   REPORT_SCOPES,
+  INTERRUPT_CATEGORIES,
+  DIGEST_CADENCES,
   type Caps,
   type ConductorConfig,
+  type DigestCadence,
+  type InterruptCategory,
   type MergePreconditions,
   type PlanUsageCap,
   type ProjectConfig,
@@ -43,6 +48,7 @@ import {
   type ReleasePreconditions,
   type ReleaseRequirement,
   type ReportScope,
+  type ReportingPolicy,
   type RepoTarget,
   type ResolvedGrants,
 } from "./types.ts";
@@ -64,6 +70,8 @@ const CAP_KEYS = Object.keys(DEFAULT_CAPS) as (keyof Caps)[];
 
 /** Quoted for error messages, from the same data the guards below read. */
 const REPORT_SCOPE_LIST = quoteList(REPORT_SCOPES);
+const INTERRUPT_CATEGORY_LIST = quoteList(INTERRUPT_CATEGORIES);
+const DIGEST_CADENCE_LIST = quoteList(DIGEST_CADENCES);
 const AUTHORITY_HOLDER_LIST = quoteList(AUTHORITY_HOLDERS);
 const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
 const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
@@ -482,34 +490,173 @@ function normalizeProject(
  * that silently resolved to `"material"` would read as configured on the day the
  * operator meant to turn the volume down, and the config would keep lying.
  */
-function normalizeReporting(parsed: unknown, label: string, problems: string[]): ProjectConfig["reporting"] {
-  if (parsed === undefined) return { scope: DEFAULT_REPORT_SCOPE };
+/** The legacy `reporting.scope` presets, materialised as explicit policies.
+ *  Kept separate from {@link DEFAULT_REPORT_POLICY} (the "no key on disk"
+ *  default, which must stay `material`): each preset records `scopePreset` so
+ *  the tick prompt can keep saying the exact legacy words (#229). Exported so
+ *  the setup wizard and the config validator agree on one mapping. */
+export const SCOPE_PRESETS: Record<ReportScope, ReportingPolicy> = {
+  material: {
+    interruptOn: [...INTERRUPT_CATEGORIES],
+    digest: { cadence: "per-tick" },
+    scopePreset: "material",
+  },
+  decisions: {
+    interruptOn: ["tier2", "decision-needed", "fleet-stopped"],
+    digest: { cadence: "per-tick" },
+    scopePreset: "decisions",
+  },
+  escalations: {
+    interruptOn: ["tier2", "fleet-stopped"],
+    digest: { cadence: "daily" },
+    scopePreset: "escalations",
+  },
+};
+
+function defaultReporting(): ReportingPolicy {
+  return { ...DEFAULT_REPORT_POLICY, interruptOn: [...DEFAULT_REPORT_POLICY.interruptOn] };
+}
+
+/** The 24-hour `HH:MM` shape `digest.at` must take. */
+const DIGEST_AT = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+/**
+ * The reporting policy: a legacy `scope` preset, or the explicit
+ * `interruptOn` + `digest` form. The two forms are mutually exclusive — a
+ * preset IS a policy, so configuring alongside it says one thing and means
+ * another (#229).
+ */
+function normalizeReporting(parsed: unknown, label: string, problems: string[]): ReportingPolicy {
+  if (parsed === undefined) return defaultReporting();
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${label}: reporting must be an object with a "scope" of ${REPORT_SCOPE_LIST}`);
-    return { scope: DEFAULT_REPORT_SCOPE };
+    problems.push(`${label}: reporting must be an object with a "scope" preset or explicit "interruptOn"/"digest"`);
+    return defaultReporting();
   }
   const raw = parsed as Raw;
-
-  const unknownKeys = Object.keys(raw).filter((k) => k !== "scope");
+  const keys = Object.keys(raw);
+  // `scopePreset` is written by a fully-normalised policy (the setup wizard
+  // saves presets materialised); `scope` is the legacy form. Both are known.
+  const known = ["scope", "interruptOn", "digest", "scopePreset"];
+  const unknownKeys = keys.filter((k) => !known.includes(k));
   if (unknownKeys.length > 0) {
-    // Stricter than caps, which tolerate a retired key: `reporting` has exactly
-    // one member, so an unrecognised key here is a typo every time, and the
-    // block that ignores it looks configured either way.
     problems.push(`${label}: reporting has unknown key(s): ${unknownKeys.join(", ")}`);
   }
-
-  return {
-    scope: pickLiteral(
+  const hasScope = raw["scope"] !== undefined;
+  const hasExplicit = keys.includes("interruptOn") || keys.includes("digest");
+  if (hasScope && hasExplicit) {
+    problems.push(`${label}: reporting.scope is a preset — remove it when configuring interruptOn/digest explicitly`);
+    return defaultReporting();
+  }
+  if (hasScope || (!hasExplicit && keys.length === 0)) {
+    const scope = pickLiteral(
       raw["scope"],
       REPORT_SCOPES,
       DEFAULT_REPORT_SCOPE,
       `${label}: reporting.scope`,
       REPORT_SCOPE_LIST,
       problems,
-    ),
+    );
+    const preset = SCOPE_PRESETS[scope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE];
+    return {
+      interruptOn: [...preset.interruptOn],
+      digest: { ...preset.digest },
+      scopePreset: preset.scopePreset,
+    };
+  }
+
+  // A fully-normalised policy (what the setup wizard writes and saveConfig
+  // round-trips) has interruptOn/digest and may carry scopePreset; keep that
+  // back-annotation so the tick prompt can still speak the legacy words.
+  const storedPreset = raw["scopePreset"];
+  const scopePreset =
+    typeof storedPreset === "string" && (REPORT_SCOPES as readonly string[]).includes(storedPreset)
+      ? (storedPreset as ReportScope)
+      : undefined;
+
+  return {
+    interruptOn: normalizeInterruptOn(raw["interruptOn"], label, problems),
+    digest: normalizeDigest(raw["digest"], label, problems),
+    ...(scopePreset === undefined ? {} : { scopePreset }),
   };
 }
 
+function normalizeInterruptOn(parsed: unknown, label: string, problems: string[]): InterruptCategory[] {
+  const fallback = [...INTERRUPT_CATEGORIES];
+  if (parsed === undefined) {
+    problems.push(`${label}: reporting.interruptOn is required in the explicit form (or use reporting.scope)`);
+    return fallback;
+  }
+  if (!Array.isArray(parsed)) {
+    problems.push(`${label}: reporting.interruptOn must be an array of ${INTERRUPT_CATEGORY_LIST}`);
+    return fallback;
+  }
+  const out: InterruptCategory[] = [];
+  for (const item of parsed) {
+    if (typeof item !== "string" || !(INTERRUPT_CATEGORIES as readonly string[]).includes(item)) {
+      problems.push(`${label}: reporting.interruptOn has unknown category ${JSON.stringify(item)} — one of ${INTERRUPT_CATEGORY_LIST}`);
+      continue;
+    }
+    const category = item as InterruptCategory;
+    if (!out.includes(category)) out.push(category);
+  }
+  if (out.length === 0) {
+    problems.push(`${label}: reporting.interruptOn must name at least one category`);
+    return fallback;
+  }
+  return out;
+}
+
+function normalizeDigest(parsed: unknown, label: string, problems: string[]): ReportingPolicy["digest"] {
+  const fallback: ReportingPolicy["digest"] = { cadence: "per-tick" };
+  if (parsed === undefined) {
+    problems.push(`${label}: reporting.digest is required in the explicit form (or use reporting.scope)`);
+    return fallback;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${label}: reporting.digest must be an object with a "cadence" of ${DIGEST_CADENCE_LIST}`);
+    return fallback;
+  }
+  const raw = parsed as Raw;
+  const unknownKeys = Object.keys(raw).filter((k) => !["cadence", "at", "timezone"].includes(k));
+  if (unknownKeys.length > 0) {
+    problems.push(`${label}: reporting.digest has unknown key(s): ${unknownKeys.join(", ")}`);
+  }
+  const cadence = pickLiteral(
+    raw["cadence"],
+    DIGEST_CADENCES,
+    "per-tick",
+    `${label}: reporting.digest.cadence`,
+    DIGEST_CADENCE_LIST,
+    problems,
+  );
+  const digest: ReportingPolicy["digest"] = { cadence };
+  if (cadence !== "daily") {
+    if (raw["at"] !== undefined) problems.push(`${label}: reporting.digest.at is only valid with cadence "daily"`);
+    if (raw["timezone"] !== undefined) problems.push(`${label}: reporting.digest.timezone is only valid with cadence "daily"`);
+    return digest;
+  }
+  if (raw["at"] !== undefined) {
+    if (typeof raw["at"] !== "string" || !DIGEST_AT.test(raw["at"])) {
+      problems.push(`${label}: reporting.digest.at must be a 24h HH:MM time`);
+    } else {
+      digest.at = raw["at"];
+    }
+  }
+  if (raw["timezone"] !== undefined) {
+    if (typeof raw["timezone"] !== "string") {
+      problems.push(`${label}: reporting.digest.timezone must be a string`);
+    } else {
+      try {
+        new Intl.DateTimeFormat("en-GB", { timeZone: raw["timezone"] });
+        digest.timezone = raw["timezone"];
+      } catch {
+        problems.push(`${label}: reporting.digest.timezone is not a known IANA timezone`);
+      }
+    }
+  }
+  return digest;
+}
+
 /**
  * Who triages escalations, and how they are delivered when nobody answers.
  *
@@ -853,12 +1000,37 @@ function normalizeRepos(parsed: unknown, label: string, problems: string[]): Rec
     };
     const graph = normalizeGraphProject(value?.["graphProject"], `${label}: routing.repos.${key}`, problems);
     if (graph !== undefined) target.graphProject = graph;
+    const migrations = normalizeMigrationsDir(value?.["migrations"], `${label}: routing.repos.${key}`, problems);
+    if (migrations !== undefined) target.migrations = { dir: migrations };
     repos[key] = target;
   }
 
   return repos;
 }
 
+/**
+ * The ordered-migration-chain directory (#227), or `undefined` when the repo
+ * opts out of the chain check.
+ *
+ * Repo-relative, no leading `/`, and no `..` segment — the value is read in one
+ * process and used in another against the base branch's tree, so anything that
+ * is not plainly a directory name is a guess the guard must not make.
+ */
+function normalizeMigrationsDir(parsed: unknown, label: string, problems: string[]): string | undefined {
+  if (parsed === undefined) return undefined;
+  const raw = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Raw) : undefined;
+  const dir = raw?.["dir"];
+  if (!nonEmptyString(dir)) {
+    problems.push(`${label}.migrations.dir must be a non-empty string`);
+    return undefined;
+  }
+  if (dir.startsWith("/") || dir.split("/").includes("..")) {
+    problems.push(`${label}.migrations.dir must be a repo-relative directory`);
+    return undefined;
+  }
+  return dir;
+}
+
 /**
  * The path of the index-only clone whose code graph this repo's workers query,
  * or `undefined` when the repo has none.