omp-conductor 0.9.1 → 0.12.0

package/src/setup.ts

@@ -40,6 +40,7 @@ import {
   resolveCaps,
   resolvePolicy,
   resolveReleaseGrants,
+  SCOPE_PRESETS,
   stateDir,
 } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
@@ -61,6 +62,8 @@ import {
   type ProjectPolicy,
   type ReleaseRequirement,
   type ReportScope,
+  type ReportScopeChoice,
+  type ReportingPolicy,
   type RepoTarget,
   type ResolvedGrants,
 } from "./types.ts";
@@ -88,7 +91,9 @@ export interface SetupAnswers {
   telegramChatId?: string;
   fallbackToIssueComment: boolean;
   /** How loud the supervising orchestrator session should be. */
-  reportScope: ReportScope;
+  reportScope: ReportScopeChoice;
+  /** The daily digest wall-clock (`HH:MM`) for the `quiet` choice, blank = model-timed. */
+  quietDigestAt?: string;
   /**
    * Mechanical gate for release/deploy-shaped tool calls, per shape. Always
    * complete: the wizard asks about every shape, so an answer object can never
@@ -175,7 +180,11 @@ export const SETUP_DEFAULTS = {
  * brief spells the same three options out — so "material" cannot come to mean
  * one thing in the dialog and another in the session that has to honour it.
  */
-export const REPORT_SCOPE_CHOICES: readonly { scope: ReportScope; label: string; description: string }[] = [
+export const REPORT_SCOPE_CHOICES: readonly {
+  scope: ReportScopeChoice;
+  label: string;
+  description: string;
+}[] = [
   {
     scope: "decisions",
     label: "Decisions interrupt, rest batches",
@@ -192,6 +201,12 @@ export const REPORT_SCOPE_CHOICES: readonly { scope: ReportScope; label: string;
     label: "Escalations only",
     description: "escalations when they happen, plus one daily digest — silent otherwise",
   },
+  {
+    scope: "quiet",
+    label: "Quiet (scheduled digest)",
+    description:
+      "interrupt only for escalations, fleet stops and confirmed failures; one daily rollup on your schedule",
+  },
 ];
 
 /**
@@ -204,7 +219,7 @@ export const REPORT_SCOPE_CHOICES: readonly { scope: ReportScope; label: string;
  * answers "an operator being asked the question for the first time", where the
  * recommended answer is the useful one — and they see it, and confirm it.
  */
-export const SETUP_DEFAULT_REPORT_SCOPE: ReportScope = REPORT_SCOPE_CHOICES[0]!.scope;
+export const SETUP_DEFAULT_REPORT_SCOPE: ReportScopeChoice = REPORT_SCOPE_CHOICES[0]!.scope;
 
 /**
  * What each precondition value means to the operator being asked about it, in
@@ -560,8 +575,24 @@ export function buildProject(a: SetupAnswers): ProjectConfig {
     // and a release require without anyone having to know a default (#129).
     policy: clonePolicy(a.policy),
     // Written out even when it is the default, so an operator amending the
-    // volume has a line in the file to point at.
-    reporting: { scope: a.reportScope },
+    // volume has a line in the file to point at. A `scope` answer is
+    // materialised as its preset policy (with `scopePreset` set) so the file
+    // and the prompt agree with no migration rule; `quiet` is the explicit
+    // form — a curated interrupt list and a scheduled digest (#229).
+    reporting:
+      a.reportScope === "quiet"
+        ? {
+            interruptOn: ["tier2", "fleet-stopped", "confirmed-failure"],
+            digest: {
+              cadence: "daily",
+              ...(a.quietDigestAt !== undefined && a.quietDigestAt.length > 0 ? { at: a.quietDigestAt } : {}),
+            },
+          }
+        : {
+            interruptOn: [...(SCOPE_PRESETS[a.reportScope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE]).interruptOn],
+            digest: { ...(SCOPE_PRESETS[a.reportScope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE]).digest },
+            scopePreset: (SCOPE_PRESETS[a.reportScope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE]).scopePreset,
+          },
     // Both under the state dir so one `rm -rf ~/.omp/conductor` is a complete
     // uninstall, and neither can land in a repo the daemon then tries to commit.
     workspaceRoot: defaultWorkspaceRoot(),
@@ -667,7 +698,7 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
     releaseGrants: resolveReleaseGrants(p),
     policy: resolvePolicy(p),
     orchestratorMode: p.escalation.orchestrator,
-    reportScope: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
+    reportScope: p.reporting?.scopePreset ?? DEFAULT_REPORT_SCOPE,
     writeOrchestratorBrief: false,
   };
 
@@ -704,7 +735,7 @@ function briefVarsForProject(p: ProjectConfig): Record<string, string> {
     QUEUE_LABEL: p.queueLabel,
     RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
     MERGE_DUTY: MERGE_DUTY[p.authority.merge],
-    REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
+    REPORT_SCOPE: p.reporting?.scopePreset ?? DEFAULT_REPORT_SCOPE,
     POLICY_SOURCE: policySourceLine(p),
   };
 }
@@ -1234,7 +1265,7 @@ export const AMEND_AREAS: {
     name: "reporting scope",
     asks: "how much the orchestrator says unprompted",
     describe: (p) => {
-      const scope = p.reporting?.scope ?? DEFAULT_REPORT_SCOPE;
+      const scope = p.reporting?.scopePreset ?? DEFAULT_REPORT_SCOPE;
       const choice = REPORT_SCOPE_CHOICES.find((c) => c.scope === scope);
       return `${scope} — ${choice?.description ?? "unknown scope"}`;
     },

package/src/store.ts

@@ -26,6 +26,8 @@ import type {
   FrictionKind,
   FrictionObservation,
   FrictionSignal,
+  HeldNotice,
+  HeldNoticeDraft,
   LabelOp,
   MergeLock,
   ReportDeliveryState,
@@ -332,6 +334,24 @@ CREATE UNIQUE INDEX IF NOT EXISTS reports_dedupe
 CREATE INDEX IF NOT EXISTS reports_project_state
   ON reports (project, state, nextAttemptAt);
 
+-- Interrupts a project's reporting.interruptOn policy deferred to the digest
+-- (#229): an escalation that must not page the operator's phone now is held
+-- here so the daily rollup can surface it. digestedAt set -> re-surfaced by a
+-- digest pass and no longer owed. A table rather than a flag on reports: these
+-- are escalations that never reached a send, distinct from reports the model
+-- wrote on purpose.
+CREATE TABLE IF NOT EXISTS held_notices (
+  id         TEXT    PRIMARY KEY,
+  project    TEXT    NOT NULL,
+  category   TEXT    NOT NULL,
+  summary    TEXT    NOT NULL,
+  detail     TEXT    NOT NULL,
+  createdAt  INTEGER NOT NULL,
+  digestedAt INTEGER
+);
+CREATE INDEX IF NOT EXISTS held_notices_project_undigested
+  ON held_notices (project, digestedAt) WHERE digestedAt IS NULL;
+
 -- The action ledger for the conductor-owned mutation verbs (#126). Every
 -- decided call lands here, refusals included: the question an escalation asks
 -- is "what did this run try", and a table that only records what succeeded
@@ -902,12 +922,12 @@ export function openStore(dbPath: string): Store {
   const countFailures = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs
       WHERE project = ? AND issue = ? AND state = 'failed'
-        AND (failureClass IS NULL OR failureClass NOT IN ('ci-infra', 'settlement-stuck', 'env-start-failure', 'dispatch-infra'))`,
+        AND (failureClass IS NULL OR failureClass NOT IN ('ci-infra', 'settlement-stuck', 'env-start-failure', 'dispatch-infra', 'provider-credit', 'provider-transient'))`,
   );
   const countContinuations = db.query<{ n: number }, [string, number]>(
     `SELECT COUNT(*) AS n FROM runs
       WHERE project = ? AND issue = ? AND state IN ('killed', 'orphaned', 'blocked')
-        AND (failureClass IS NULL OR failureClass NOT IN ('admin-kill', 'settlement-stuck', 'env-start-failure', 'dispatch-infra'))`,
+        AND (failureClass IS NULL OR failureClass NOT IN ('admin-kill', 'settlement-stuck', 'env-start-failure', 'dispatch-infra', 'provider-credit', 'provider-transient'))`,
   );
   // How many times one issue reached a given class. Recovery uses it to bound a
   // retry loop whose cause is persistent (e.g. a mirror that will not refresh):
@@ -1079,6 +1099,33 @@ export function openStore(dbPath: string): Store {
       ORDER BY createdAt ASC, rowid ASC
       LIMIT ?`,
   );
+
+  // Held notices (#229): escalations deferred to the digest by the project's
+  // `reporting.interruptOn` policy. `digestedAt` NULL = still owed.
+  const insertHeldNotice = db.query<unknown, SqlValue[]>(
+    `INSERT INTO held_notices (id, project, category, summary, detail, createdAt, digestedAt)
+     VALUES (?, ?, ?, ?, ?, ?, NULL)`,
+  );
+  const selectUndigestedNotices = db.query<
+    { id: string; category: string; summary: string; detail: string; createdAt: number },
+    [string]
+  >(
+    `SELECT id, category, summary, detail, createdAt FROM held_notices
+      WHERE project = ? AND digestedAt IS NULL
+      ORDER BY createdAt ASC`,
+  );
+  const markNoticesDigestedRow = db.query<unknown, [number, string]>(
+    `UPDATE held_notices SET digestedAt = ? WHERE project = ? AND digestedAt IS NULL`,
+  );
+  // The newest digest dedupe key a project has actually run toward — an
+  // `updatedAt`-newest row whose key is a digest prefix and that did not end in
+  // failure. The CLI refuses an off-schedule digest by comparing this against
+  // today's key under `digestDue` (#229).
+  const selectLastDigestKey = db.query<{ key: string | null }, [string]>(
+    `SELECT dedupeKey AS key FROM reports
+      WHERE project = ? AND dedupeKey LIKE 'digest:%' AND state <> 'failed'
+      ORDER BY createdAt DESC LIMIT 1`,
+  );
   const claimReportRow = db.query<unknown, [string, number, string, number]>(
     `UPDATE reports
         SET state = 'sending', attemptId = ?, attempts = attempts + 1, updatedAt = ?
@@ -1445,6 +1492,30 @@ export function openStore(dbPath: string): Store {
       return row === null ? undefined : toDispatchSummary(row.summary);
     },
 
+    lastDigestDedupeKey(project: string): string | undefined {
+      const row = selectLastDigestKey.get(project);
+      return row?.key ?? undefined;
+    },
+
+    addHeldNotice(notice: HeldNoticeDraft): void {
+      insertHeldNotice.run(
+        crypto.randomUUID(),
+        notice.project,
+        notice.category,
+        notice.summary,
+        notice.detail,
+        notice.createdAt,
+      );
+    },
+
+    undigestedNotices(project: string): HeldNotice[] {
+      return selectUndigestedNotices.all(project).map((row) => ({ ...row }) as HeldNotice);
+    },
+
+    markNoticesDigested(project: string, at: number): void {
+      markNoticesDigestedRow.run(at, project);
+    },
+
     recordFriction,
 
     recordGhRefusal,

package/src/types.ts

@@ -114,6 +114,14 @@ export interface RepoTarget {
    * the worker brief.
    */
   graphProject?: string;
+  /**
+   * Ordered-migration-chain guard (#227): repo-relative directory whose *.py
+   * files declare `revision`/`down_revision`. When set, `conductor_pr_merge`
+   * refuses a merge that would collide with the base branch's chain (id reuse,
+   * a deleted migration, or a combined graph with more than one head). Absent
+   * = no chain check.
+   */
+  migrations?: { dir: string };
 }
 
 /**
@@ -140,6 +148,59 @@ export type ReportScope = (typeof REPORT_SCOPES)[number];
  */
 export const DEFAULT_REPORT_SCOPE: ReportScope = "material";
 
+/**
+ * The four answers the wizard offers for "how loud should the orchestrator be".
+ * Three are legacy presets; `quiet` is the explicit form: interrupt only for
+ * escalations, fleet stops and confirmed failures, with one daily rollup
+ * (#229).
+ */
+export type ReportScopeChoice = ReportScope | "quiet";
+
+/**
+ * Which categories may interrupt the operator's phone. Each maps to a tier-2
+ * escalation channel: `tier2` (a plain decision), `decision-needed`, a
+ * fleet-stopping condition, a confirmed failure, or any material event. What an
+ * `interruptOn` list omits is not dropped — it accumulates for the digest.
+ * Data rather than booleans so the config validator, the escalator and the
+ * orchestrator prompt all enumerate the same vocabulary (#229).
+ */
+export const INTERRUPT_CATEGORIES = [
+  "tier2",
+  "decision-needed",
+  "fleet-stopped",
+  "confirmed-failure",
+  "material",
+] as const;
+
+export type InterruptCategory = (typeof INTERRUPT_CATEGORIES)[number];
+
+/** When the daily/report rollup is due. */
+export const DIGEST_CADENCES = ["none", "per-tick", "daily"] as const;
+
+export type DigestCadence = (typeof DIGEST_CADENCES)[number];
+
+/**
+ * Explicit reporting policy: which categories interrupt, and when the daily
+ * rollup happens. `scopePreset` is set when the config came from a legacy
+ * `scope:` preset, and drives the preset tick prompt text.
+ */
+export interface ReportingPolicy {
+  interruptOn: InterruptCategory[];
+  digest: { cadence: DigestCadence; at?: string; timezone?: string };
+  /** Set when the policy came from a legacy `scope` preset. */
+  scopePreset?: ReportScope;
+}
+
+/**
+ * The default policy: the legacy `material` preset, spelled out so an explicit
+ * config can name it and the wizard can show it.
+ */
+export const DEFAULT_REPORT_POLICY: ReportingPolicy = {
+  interruptOn: [...INTERRUPT_CATEGORIES],
+  digest: { cadence: "per-tick" },
+  scopePreset: DEFAULT_REPORT_SCOPE,
+};
+
 /**
  * The irreversible tool-call shapes this package recognises and gates. Data
  * here rather than in `release-policy.ts` because the config validator, the
@@ -431,6 +492,9 @@ export const LABEL_REASONS = [
   "promoted-to-queue",
   /** Re-briefed after a failed attempt, and put back on the queue. */
   "re-briefed",
+  /** Delivered: the PR merged and the issue closed, and the queue label comes
+   *  off as completed lifecycle cleanup — not superseded, not a re-brief (#230). */
+  "completed",
   /** Parked: it needs a decision only a human can make. */
   "needs-human",
   "duplicate",
@@ -534,11 +598,13 @@ export interface ProjectConfig {
    */
   policy?: ProjectPolicy;
   /**
-   * How loud the orchestrator is. Optional on disk — a config written before
-   * this key existed loads as {@link DEFAULT_REPORT_SCOPE} — so read it through
-   * `resolveReportScope` rather than reaching for `.scope` directly.
+   * How loud the orchestrator is, and when the daily rollup happens. Optional
+   * on disk — a config written before this key existed loads as
+   * {@link DEFAULT_REPORT_POLICY} — so read it through `resolveReportScope`
+   * rather than reaching for `.scope` directly. A legacy `scope:` value is
+   * accepted and materialised as a preset (`.scopePreset`).
    */
-  reporting?: { scope: ReportScope };
+  reporting?: ReportingPolicy;
   /** Parent directory for per-run worktrees. */
   workspaceRoot: string;
   /** Cache of bare clones, so N runs share one fetch instead of N. */
@@ -831,6 +897,8 @@ export const FAILURE_CLASSES = [
   "orphan-clean",
   "orphan-dirty",
   "settlement-stuck",
+  "provider-credit",
+  "provider-transient",
   "unknown",
 ] as const;
 
@@ -968,6 +1036,9 @@ export interface DispatchSummary {
   ready: number;
   routed: number;
   admitted: number;
+  /** Ready issues carrying a state label — claimed by a live or settling run.
+   *  Optional: persisted old rows lack it, so readers use `?? 0` (#228). */
+  claimed?: number;
   /** True only for system/API failures, never ordinary policy holds. */
   degraded: boolean;
   holds: AdmissionHoldSummary[];
@@ -1222,6 +1293,15 @@ export interface Store {
   wasNotified(key: string): boolean;
   recordDispatch(project: string, summary: DispatchSummary): void;
   latestDispatch(project: string): DispatchSummary | undefined;
+  /** The newest `digest:` dedupe key a project has run toward without ending in
+   *  failure — what the off-schedule-digest refusal compares against (#229). */
+  lastDigestDedupeKey(project: string): string | undefined;
+  /** Hold a tier-2 escalation the interrupt policy deferred to the digest. */
+  addHeldNotice(notice: HeldNoticeDraft): void;
+  /** Held notices still owed (not yet re-surfaced by a digest pass). */
+  undigestedNotices(project: string): HeldNotice[];
+  /** Mark every undigested notice for a project as re-surfaced. */
+  markNoticesDigested(project: string, at: number): void;
   /** Add one bounded observation to the per-day friction rollup. */
   recordFriction(project: string, observation: FrictionObservation): void;
   /** Repeated signals not surfaced within the supplied cooldown window. */
@@ -1384,6 +1464,28 @@ export interface Escalation {
   summary: string;
   detail?: string;
   runId?: string;
+  /** Tier-2-only interrupt category; defaults to `"tier2"`. Drives whether the
+   *  escalation pages now or is held for the digest under the project's
+   *  `reporting.interruptOn` policy (#229). */
+  category?: InterruptCategory;
+}
+
+/** A tier-2 escalation the project's interrupt policy deferred to the digest. */
+export interface HeldNotice {
+  id: string;
+  category: InterruptCategory;
+  summary: string;
+  detail: string;
+  createdAt: number;
+}
+
+/** What it takes to persist one held notice. */
+export interface HeldNoticeDraft {
+  project: string;
+  category: InterruptCategory;
+  summary: string;
+  detail: string;
+  createdAt: number;
 }
 
 /**
@@ -1510,6 +1612,11 @@ export const VERB_REFUSALS = [
   "release-shape-not-executable",
   /** Config unreadable, project unknown, repo unrouted. Fail closed. */
   "config-unreadable",
+  /** Merging would corrupt the ordered migration chain in `migrations.dir` (#227). */
+  "chain-conflict",
+  /** The PR diff or the base-branch chain could not be read — fail closed rather
+   *  than merge blind into a chain that might be about to fork (#227). */
+  "chain-unreadable",
   /** The privileged half ran and the underlying command failed. */
   "action-failed",
 ] as const;

package/src/verbs/server.ts

@@ -42,6 +42,8 @@ import { randomUUID } from "node:crypto";
 import { createServer, type Server, type Socket } from "node:net";
 
 import { resolvePolicy, resolveReleaseGrants } from "../config.ts";
+import { chainEntriesFromDiff, chainViolations } from "../chain-check.ts";
+import type { readBaseChain as readBaseChainType } from "../gitops.ts";
 import { releaseRefusal } from "../release-policy.ts";
 import { LIVE_STATES } from "../store.ts";
 import type {
@@ -181,6 +183,12 @@ export interface VerbDeps {
   pausedAt: () => number | undefined;
   log: (message: string) => void;
   now: () => number;
+  /**
+   * Read-only access to the ordered-migration-chain guard. A read seam, kept
+   * off `VerbActions` (the mutation surface) on purpose: `prMergeVerb` consults
+   * whether the merge would fork the chain, it never changes it (#227).
+   */
+  chain: { readBaseChain: typeof readBaseChainType };
 }
 
 /**
@@ -728,6 +736,47 @@ async function prMergeVerb(
       );
     }
 
+    const repoTarget = Object.values(project.routing.repos).find((r) => r.name === target.repo);
+    const chainDir = repoTarget?.migrations?.dir;
+    if (chainDir !== undefined && repoTarget !== undefined) {
+      // Checked against the base tip at merge time, not against a stale advisory:
+      // the author hit two merged PRs leaving main with two Alembic heads (#227).
+      const diff = await deps.tracker.prDiff(prUrl).catch(() => undefined);
+      if (diff === undefined) {
+        return refuse(
+          "chain-unreadable",
+          `refused: the diff of ${prUrl} could not be read, so the migration chain in ${chainDir} cannot be verified. Failing closed: a wrong merge here is a silent production schema drift (#227).`,
+          target.issue,
+        );
+      }
+      const { added, changed, deleted } = chainEntriesFromDiff(diff.files, chainDir);
+      if (added.length + changed.length + deleted.length > 0) {
+        if (diff.truncated) {
+          return refuse(
+            "chain-unreadable",
+            `refused: the diff of ${prUrl} was truncated and it touches ${chainDir} — the chain cannot be verified from a partial diff.`,
+            target.issue,
+          );
+        }
+        const base = await deps.chain.readBaseChain(project, repoTarget, chainDir);
+        if (!base.ok) {
+          return refuse(
+            "chain-unreadable",
+            `refused: could not read ${chainDir} at the tip of ${repoTarget.defaultBranch} (${base.stderr}).`,
+            target.issue,
+          );
+        }
+        const violations = chainViolations({ base: base.entries, added, changed, deleted });
+        if (violations.length > 0) {
+          return refuse(
+            "chain-conflict",
+            `refused: merging ${prUrl} would corrupt the ordered migration chain in ${chainDir} — ${violations.join("; ")}. Rebase onto the current tip, regenerate the migration, and call again.`,
+            target.issue,
+          );
+        }
+      }
+    }
+
     const outcome = await deps.actions.mergePr(prUrl, headSha);
     if (!outcome.ok) {
       return refuse("action-failed", `refused: gh could not merge:\n${outcome.stderr}`, target.issue);