omp-conductor 0.10.0 → 0.13.0

package/src/chain-check.ts

@@ -0,0 +1,157 @@
+/**
+ * The ordered-migration-chain guard (#227).
+ *
+ * A project that declares `routing.repos.<repo>.migrations.dir` gets its
+ * merges checked against one invariant: after the merge, the base branch's
+ * `revision`/`down_revision` graph has exactly one head. The check runs on the
+ * base tip at merge time, against the PR's diff — a stale parent, a reused
+ * revision id, or a deleted migration is refused before the merge, because a
+ * wrong merge here is silent production schema drift.
+ *
+ * Alembic-convention only (`revision = "<id>"` / `down_revision = <expr>` in
+ * `*.py`); a repo without the config key is never touched. Pure by
+ * construction: every fact arrives as strings, and the module reads no files.
+ */
+
+import type { PrDiffFile } from "./types.ts";
+
+/** One migration file's identity, as the chain check reasons about it. */
+export interface ChainEntry {
+  /** Repo-relative path of the file that declares the revision. */
+  path: string;
+  /** The revision id this file declares. */
+  id: string;
+  /** Parent revision ids; empty for a root. */
+  parents: string[];
+}
+
+const REVISION_LINE = /^\s*revision(?::[^=]*)?\s*=\s*["']([^"']+)["']/m;
+const DOWN_REVISION_LINE = /^\s*down_revision(?::[^=]*)?\s*=\s*(.*)$/m;
+const QUOTED = /["']([^"']+)["']/g;
+
+/**
+ * Parse one migration file's source into its chain identity, or `undefined`
+ * when it declares no `revision` (not a chain file; skip it).
+ *
+ * `down_revision` may be `"abc"`, `None`, or a tuple `('a', 'b')` (a merge
+ * migration) — the parents are every quoted string on the right-hand side, so
+ * `None`/empty reads as a root without special-casing syntax.
+ */
+export function parseChainSource(path: string, source: string): ChainEntry | undefined {
+  const id = REVISION_LINE.exec(source)?.[1];
+  if (id === undefined) return undefined;
+  const parents: string[] = [];
+  const rhs = DOWN_REVISION_LINE.exec(source)?.[1] ?? "";
+  for (const m of rhs.matchAll(QUOTED)) {
+    const parent = m[1];
+    if (parent !== undefined && !parents.includes(parent)) parents.push(parent);
+  }
+  return { path, id, parents };
+}
+
+/** Post-image source of one diff file: the added lines, rejoined as a file. */
+function postImageSource(file: PrDiffFile): string {
+  const hunks = file.hunks ?? "";
+  const lines: string[] = [];
+  for (const line of hunks.split("\n")) {
+    if (line.startsWith("+")) lines.push(line.slice(1));
+  }
+  return lines.join("\n");
+}
+
+/** Whether one diff entry lives inside the chain directory. */
+function inChainDir(dir: string, path: string): boolean {
+  return path.startsWith(`${dir}/`) && path.endsWith(".py");
+}
+
+/**
+ * What the PR does to the chain: entries added, entries changed (post-image
+ * used — a modified file's base entry stands when its added lines declare no
+ * revision), and chain files deleted.
+ */
+export function chainEntriesFromDiff(
+  files: readonly PrDiffFile[],
+  dir: string,
+): { added: ChainEntry[]; changed: ChainEntry[]; deleted: string[] } {
+  const added: ChainEntry[] = [];
+  const changed: ChainEntry[] = [];
+  const deleted: string[] = [];
+  for (const file of files) {
+    if (!inChainDir(dir, file.path)) continue;
+    if (file.status === "removed") {
+      deleted.push(file.path);
+      continue;
+    }
+    const entry = parseChainSource(file.path, postImageSource(file));
+    if (entry === undefined) continue;
+    if (file.status === "added") added.push(entry);
+    else changed.push(entry); // modified, or renamed into the chain directory
+  }
+  return { added, changed, deleted };
+}
+
+export interface ChainViolationInput {
+  base: ChainEntry[];
+  added: ChainEntry[];
+  changed: ChainEntry[];
+  deleted: string[];
+}
+
+/**
+ * Refuse a merge that would corrupt the ordered chain, or return [] to pass.
+ *
+ * A combined graph that no PR touches is never judged: a broken base is not
+ * this PR's problem.
+ */
+export function chainViolations(input: ChainViolationInput): string[] {
+  const touched = input.added.length + input.changed.length + input.deleted.length;
+  if (touched === 0) return [];
+
+  const violations: string[] = [];
+
+  // 1. The one deletion nothing can justify: a published migration may not
+  //    disappear from the base branch.
+  for (const path of input.deleted) {
+    if (input.base.some((entry) => entry.path === path)) {
+      violations.push(`deletes ${path}, which exists on the base branch — a published migration may never be deleted`);
+    }
+  }
+
+  // 2. Reusing an id that already exists on the base at a DIFFERENT path makes
+  //    two files claim one revision; the graph stops being an order.
+  const baseByPath = new Map(input.base.map((entry) => [entry.path, entry]));
+  for (const entry of [...input.added, ...input.changed]) {
+    const owner = input.base.find((b) => b.id === entry.id);
+    if (owner !== undefined && owner.path !== entry.path) {
+      violations.push(`reuses revision id ${entry.id}, already declared by ${owner.path} on the base branch`);
+    }
+  }
+
+  // 3. Head coherence: the combined graph — base, minus deleted files, minus
+  //    changed files' base entries (replaced by their post-image), plus added
+  //    entries — must have exactly one head. Two heads means a stale parent or
+  //    a fork nobody repaired; one head after a repair merge is the goal. A
+  //    duplicate id inside the PR's own entries is incoherent too.
+  const combined = new Map(baseByPath);
+  for (const path of input.deleted) combined.delete(path);
+  for (const entry of input.changed) combined.delete(entry.path);
+  for (const entry of [...input.changed, ...input.added]) combined.set(entry.path, entry);
+
+  const ids = [...combined.values()].map((entry) => entry.id);
+  const duplicateIds = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (duplicateIds.length > 0) {
+    violations.push(
+      `the migration graph would declare duplicate revision id${duplicateIds.length > 1 ? "s" : ""} ${[...new Set(duplicateIds)].join(", ")} after merge`,
+    );
+  }
+
+  const referenced = new Set([...combined.values()].flatMap((entry) => entry.parents));
+  const heads = ids.filter((id, index) => ids.indexOf(id) === index && !referenced.has(id));
+  if (heads.length !== 1) {
+    violations.push(
+      `the migration graph would have ${heads.length} heads after merge (${heads.join(", ") || "none"}); parent(s) must be the current tip`,
+    );
+  }
+
+  return violations;
+}

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,9 @@ 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 worker stop <issue> --reason TEXT [--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]
@@ -168,8 +173,12 @@ usage:
            the daemon rather than terminals, so this is the only way to watch
            one live. Runs until Ctrl-C, or until the run has finished and its
            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.
+  extend   raise a live run's turn ceiling, or set a bounded one-shot ceiling
+           after a failed, killed, orphaned or blocked run. Refuses values outside
+           configured bounds.
+  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
@@ -605,14 +614,11 @@ try {
     }
 
     /**
-     * The action ledger (#126): every conductor-verb call, what it asked for,
-     * and how the daemon decided it.
-     *
-     * Its own command as well as a block in `status`, because the two questions
-     * are different sizes. `status` answers "is anything being refused right
-     * now"; this answers "what did run 3 actually try to do", which is the
-     * question an escalation about a run asks, and it needs the whole record
-     * rather than the newest five lines of every run at once.
+     * The action ledger: mediated conductor verbs plus durable per-issue budget
+     * changes. Its own command as well as a block in `status`, because the two
+     * questions are different sizes. `status` answers "what is pending or being
+     * refused now"; this answers "what did run 3 actually try, and what budget
+     * did the operator assign", which needs history rather than only live state.
      */
     case "ledger": {
       const cfg = loadConfig();
@@ -634,18 +640,38 @@ try {
           ...(issue === undefined ? {} : { issue }),
           limit,
         });
-        if (entries.length === 0) {
+        const overrides = store.turnOverrideLedger(p.name, {
+          ...(issue === undefined ? {} : { issue }),
+          limit,
+        });
+        if (entries.length === 0 && overrides.length === 0) {
           process.stdout.write(
-            `no conductor-verb calls recorded for ${p.name}` +
+            `no conductor actions recorded for ${p.name}` +
               `${issue === undefined ? "" : ` on #${String(issue)}`}\n`,
           );
           break;
         }
-        const refused = entries.filter((e) => e.decision === "refused").length;
-        process.stdout.write(
-          `${p.name} — ${entries.length} verb call(s), ${refused} refused (newest first)\n` +
-            `${entries.flatMap(formatVerbLedgerEntry).join("\n")}\n`,
-        );
+        const blocks: string[] = [];
+        if (entries.length > 0) {
+          const refused = entries.filter((e) => e.decision === "refused").length;
+          blocks.push(
+            `${p.name} — ${entries.length} verb call(s), ${refused} refused (newest first)\n` +
+              entries.flatMap(formatVerbLedgerEntry).join("\n"),
+          );
+        }
+        if (overrides.length > 0) {
+          blocks.push(
+            `${p.name} — ${overrides.length} turn override(s) (newest first)\n` +
+              overrides
+                .map(
+                  (entry) =>
+                    `  ${new Date(entry.setAt).toISOString()}  #${entry.issue}  ` +
+                    `${entry.maxTurns} turns`,
+                )
+                .join("\n"),
+          );
+        }
+        process.stdout.write(`${blocks.join("\n\n")}\n`);
       } finally {
         store.close();
       }
@@ -767,14 +793,30 @@ try {
       );
       const payload = (await response.json()) as {
         error?: unknown;
+        kind?: unknown;
         runId?: unknown;
         maxTurns?: unknown;
+        issue?: unknown;
+        nextAttemptMaxTurns?: unknown;
+        baseMaxTurns?: unknown;
       };
       if (!response.ok) {
         throw new Error(
           typeof payload.error === "string" ? payload.error : `daemon returned HTTP ${response.status}`,
         );
       }
+      if (
+        payload.kind === "next-attempt" &&
+        payload.issue === issue &&
+        typeof payload.nextAttemptMaxTurns === "number" &&
+        typeof payload.baseMaxTurns === "number"
+      ) {
+        process.stdout.write(
+          `#${issue} next attempt turn ceiling set to ${payload.nextAttemptMaxTurns} ` +
+            `(project base ${payload.baseMaxTurns})\n`,
+        );
+        break;
+      }
       if (typeof payload.runId !== "string" || typeof payload.maxTurns !== "number") {
         throw new Error("daemon returned an invalid turn-extension response");
       }
@@ -784,6 +826,96 @@ try {
       break;
     }
 
+    case "worker": {
+      const sub = argv[1];
+      if (sub !== "pause" && sub !== "resume" && sub !== "stop") {
+        process.stderr.write(
+          "omp-conductor: worker needs pause, resume, or stop, then an issue number\n",
+        );
+        process.exit(2);
+      }
+      const issue = issueArg("worker", argv[2]);
+      const rawReason = sub === "stop" ? flag(argv, "reason") : undefined;
+      const reason = rawReason?.trim().replace(/\s+/g, " ");
+      if (sub === "stop" && (reason === undefined || reason === "" || reason.length > 500)) {
+        process.stderr.write(
+          "omp-conductor: worker stop needs --reason with 1-500 characters\n",
+        );
+        process.exit(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,
+            ...(reason === undefined ? {} : { reason }),
+          }),
+        },
+      );
+      const payload = (await response.json()) as {
+        error?: unknown;
+        runId?: unknown;
+        phase?: unknown;
+        outcome?: unknown;
+        state?: unknown;
+        reason?: unknown;
+        salvageSha?: unknown;
+        salvageError?: unknown;
+        worktree?: unknown;
+      };
+      if (!response.ok) {
+        throw new Error(
+          typeof payload.error === "string" ? payload.error : `daemon returned HTTP ${response.status}`,
+        );
+      }
+      if (sub === "stop") {
+        if (
+          typeof payload.runId !== "string" ||
+          typeof payload.state !== "string" ||
+          (payload.outcome !== "stopped" && payload.outcome !== "already-terminal")
+        ) {
+          throw new Error("daemon returned an invalid worker-stop response");
+        }
+        if (payload.outcome === "already-terminal") {
+          process.stdout.write(
+            `#${issue} worker already terminal: ${payload.state} (run ${payload.runId})\n`,
+          );
+          break;
+        }
+        if (typeof payload.reason !== "string") {
+          throw new Error("daemon returned an invalid worker-stop response");
+        }
+        process.stdout.write(
+          `#${issue} worker stopped (run ${payload.runId}): ${payload.reason}\n`,
+        );
+        if (typeof payload.salvageSha === "string") {
+          process.stdout.write(`work preserved: ${payload.salvageSha}\n`);
+        }
+        if (typeof payload.salvageError === "string") {
+          process.stdout.write(
+            `WIP SALVAGE FAILED: ${payload.salvageError}\n` +
+            `worktree kept: ${typeof payload.worktree === "string" ? payload.worktree : "(path unavailable)"}\n`,
+          );
+        }
+        break;
+      }
+      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 +1005,7 @@ try {
             pausedAt,
             log: (m) => process.stderr.write(`${m}\n`),
             now: () => Date.now(),
+            chain: { readBaseChain },
           },
           channel,
           { verb: name, args },
@@ -914,15 +1047,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` +