omp-conductor 0.10.0 → 0.12.0

package/src/daemon.ts

@@ -35,7 +35,7 @@ import { recordReleaseBlock } from "./release-policy.ts";
 import { branchName, effectiveLabels, route } from "./routing.ts";
 import type { Routed, UnroutableReason } from "./routing.ts";
 import { evaluateDecisionConditions, probeNpmVersion, probeRateLimitReset } from "./decisions.ts";
-import { classifyRun, providerCreditRefusal, type ClassifyFacts } from "./failure-class.ts";
+import { classifyRun, providerCreditRefusal, providerTransientFault, type ClassifyFacts } from "./failure-class.ts";
 import { projectLabels } from "./label-projection.ts";
 import { dbPath, openStore, utcDay } from "./store.ts";
 import { makeTracker, type RateLimitStatus } from "./tracker/github.ts";
@@ -61,7 +61,14 @@ import type {
   Tracker,
   VerbLedgerEntry,
 } from "./types.ts";
-import { type KilledBy, type WorkerResult, renderBrief, runWorker } from "./worker.ts";
+import {
+  type KilledBy,
+  type WorkerPauseControl,
+  type WorkerPausePhase,
+  type WorkerResult,
+  renderBrief,
+  runWorker,
+} from "./worker.ts";
 import {
   addRunRepo,
   cleanupRetainedWorktree,
@@ -86,7 +93,7 @@ import {
 } from "./verbs/socket.ts";
 import { homedir } from "node:os";
 
-import { pushRunBranch, type RunRepoRef } from "./gitops.ts";
+import { pushRunBranch, readBaseChain, type RunRepoRef } from "./gitops.ts";
 import {
   planUsageLine,
   readPlanUsage,
@@ -108,6 +115,11 @@ const REPORT_DELIVERY_INTERVAL_MS = 30_000;
  *  means the mirror itself is broken, not unlucky, and the sweep escalates
  *  instead of burning a turn-0 run per tick forever (#168, #177). */
 const DISPATCH_INFRA_MAX_STRIKES = 3;
+/** A provider-transient requeue (stream stalled mid-run) is retried, but only a
+ *  bounded number of times: three aborted streams for one issue means the
+ *  provider itself is degraded, not unlucky, and the sweep escalates to a
+ *  human instead of requeueing into a down provider forever (#220). */
+const PROVIDER_TRANSIENT_MAX_STRIKES = 3;
 const DEFAULT_PORT = 8787;
 const BRIEF_TEMPLATE_PATH = join(import.meta.dir, "briefs", "worker.md");
 
@@ -144,6 +156,7 @@ interface Deps {
   usage: UsageSource;
   escalate(e: Escalation): Promise<void>;
   turnLimits: TurnLimitRegistry;
+  workerControls: WorkerControlRegistry;
   integrity: IntegrityGate;
   stall: StallGate;
   cleanup?: RetainedCleanupCursor;
@@ -190,6 +203,7 @@ export function verbDeps(d: Pick<Deps, "project" | "store" | "tracker" | "verbAc
     pausedAt,
     log,
     now: () => Date.now(),
+    chain: { readBaseChain },
   };
 }
 
@@ -264,6 +278,7 @@ async function watchOrchestrator(d: Deps): Promise<void> {
   log(`ERROR: the orchestrator session is not draining its queue — ${verdict.since ?? "no timestamp"}`);
   const delivered = await safeEscalate(d, {
     tier: 2,
+    category: "confirmed-failure",
     project: d.project.name,
     issue: NO_ISSUE,
     // Keyed on the marker's own timestamp, not the date. The dedup ledger keys
@@ -823,6 +838,91 @@ export function createTurnLimitRegistry(
   };
 }
 
+export type WorkerControlResult =
+  | { kind: "ok"; runId: string; phase: WorkerPausePhase }
+  | { kind: "refused"; runId: string; error: string }
+  | { kind: "not-active" };
+
+export interface WorkerControlSlot {
+  install(control: WorkerPauseControl): void;
+  close(): void;
+}
+
+export interface WorkerControlRegistry {
+  open(project: string, issue: number, runId: string): WorkerControlSlot;
+  pause(project: string, issue: number): Promise<WorkerControlResult>;
+  resume(project: string, issue: number): WorkerControlResult;
+  /** Live runs whose phase is not `running` — what /healthz and the board show. */
+  snapshot(project: string): { issue: number; runId: string; phase: WorkerPausePhase }[];
+}
+
+/** Authoritative controls for sessions owned by this daemon process. */
+export function createWorkerControlRegistry(): WorkerControlRegistry {
+  const active = new Map<
+    string,
+    { project: string; issue: number; runId: string; control?: WorkerPauseControl }
+  >();
+  const key = (project: string, issue: number): string => `${project}\0${issue}`;
+  return {
+    open(project, issue, runId) {
+      const k = key(project, issue);
+      if (active.has(k)) throw new Error(`#${issue} already has a live worker controller`);
+      const entry = { project, issue, runId } as {
+        project: string;
+        issue: number;
+        runId: string;
+        control?: WorkerPauseControl;
+      };
+      active.set(k, entry);
+      return {
+        install: (control) => {
+          if (active.get(k) === entry) entry.control = control;
+        },
+        close: () => {
+          if (active.get(k) === entry) active.delete(k);
+        },
+      };
+    },
+    async pause(project, issue) {
+      const entry = active.get(key(project, issue));
+      if (entry?.control === undefined) return { kind: "not-active" };
+      try {
+        await entry.control.pause();
+        return { kind: "ok", runId: entry.runId, phase: entry.control.phase() };
+      } catch (err) {
+        return {
+          kind: "refused",
+          runId: entry.runId,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+    resume(project, issue) {
+      const entry = active.get(key(project, issue));
+      if (entry?.control === undefined) return { kind: "not-active" };
+      try {
+        entry.control.resume();
+        return { kind: "ok", runId: entry.runId, phase: entry.control.phase() };
+      } catch (err) {
+        return {
+          kind: "refused",
+          runId: entry.runId,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+    snapshot(project) {
+      const workers: { issue: number; runId: string; phase: WorkerPausePhase }[] = [];
+      for (const entry of active.values()) {
+        if (entry.project !== project || entry.control === undefined) continue;
+        const phase = entry.control.phase();
+        if (phase !== "running") workers.push({ issue: entry.issue, runId: entry.runId, phase });
+      }
+      return workers;
+    },
+  };
+}
+
 export async function verifyPushedGreenClaim(
   tracker: Pick<Tracker, "verifyPr">,
   claim: Pick<WorkerResult, "prUrl" | "headSha">,
@@ -926,6 +1026,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
   const mirrorPath = mirrorPathFor(r.repo, project.mirrorRoot);
   let worktreePath: string | undefined;
   let turnLimit: TurnLimitController | undefined;
+  let workerControl: WorkerControlSlot | undefined;
   // The run's own repository. Hoisted for the same reason `worktreePath` is —
   // the catch and finally paths have to publish the branch.
   let runRepo: RunRepoRef | undefined;
@@ -981,6 +1082,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
     store.enqueueLabelOps(project.name, [{ issue, op: "add", label: inProgress }]);
     claimed = true;
     turnLimit = d.turnLimits.open(project.name, issue, runId, caps.workerMaxTurns);
+    workerControl = d.workerControls.open(project.name, issue, runId);
 
     // A run's tree is <workspaceRoot>/<issue> and addRunRepo refuses to reuse
     // an existing path, so a retry — or a tree kept from a failed attempt — has
@@ -1057,6 +1159,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         cwd: worktreePath,
         caps,
         maxTurns: () => turnLimit?.maxTurns() ?? caps.workerMaxTurns,
+        onPauseControl: (control) => workerControl?.install(control),
         sessionDir,
         // The session's control socket, under the daemon's own state directory —
         // a child process of the daemon reaches it directly.
@@ -1081,6 +1184,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         onKilled: () => {
           turnLimit?.close();
           turnLimit = undefined;
+          workerControl?.close();
+          workerControl = undefined;
         },
         // Recorded the moment the session opens its transcript, not when the run
         // ends: `omp-conductor tail` resolves an issue to a file through this row,
@@ -1093,6 +1198,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       // PR verification or terminal row writes can leave stale `running` state.
       turnLimit?.close();
       turnLimit = undefined;
+      workerControl?.close();
+      workerControl = undefined;
     }
 
     // A configured model the harness could not honour means this run was done by
@@ -1110,13 +1217,10 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
 
     // Read before the row is written so `lastError` carries the provider's own
     // message — it names the fix and the URL, which no classification can.
-    const providerCredit =
-      state === "failed" || state === "killed"
-        ? (() => {
-            const err = readSessionError(result.sessionFile);
-            return err === undefined ? undefined : providerCreditRefusal(err);
-          })()
-        : undefined;
+    const sessionErr = state === "failed" || state === "killed" ? readSessionError(result.sessionFile) : undefined;
+    const providerCredit = sessionErr === undefined ? undefined : providerCreditRefusal(sessionErr);
+    const providerTransient =
+      providerCredit !== undefined || sessionErr === undefined ? undefined : providerTransientFault(sessionErr);
 
     // The other half of not believing a worker about its own run (#128). The
     // claim being audited is `state: pushed-green`, so the audit runs on the
@@ -1202,8 +1306,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
       // push: the report of a killed attempt is exactly the one a later
       // continuation must pool its disclosures from (#199).
       report: result.report,
-      ...(providerCredit !== undefined
-        ? { lastError: providerCredit }
+      ...(providerCredit !== undefined || providerTransient !== undefined
+        ? { lastError: providerCredit ?? providerTransient }
         : verified.reason === undefined
           ? {}
           : { lastError: verified.reason }),
@@ -1251,6 +1355,7 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
         // instead of once per affected run.
         await safeEscalate(d, {
           tier: 2,
+          category: "fleet-stopped",
           project: project.name,
           issue: NO_ISSUE,
           summary: `Model provider refused for credit — ${project.name} is paused`,
@@ -1364,6 +1469,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
     // inner settlement guard exists. Latch it before any terminal write or await.
     turnLimit?.close();
     turnLimit = undefined;
+    workerControl?.close();
+    workerControl = undefined;
     const detail = errText(err);
     log(`#${issue} errored: ${detail}`);
     // A crash lands anywhere, including mid-edit in a tree holding the only
@@ -1409,6 +1516,8 @@ async function handleIssue(d: Deps, r: Routed, attempt: number): Promise<void> {
     // a failure path, and whatever it still held is now a commit on the branch.
   } finally {
     turnLimit?.close();
+    workerControl?.close();
+    workerControl = undefined;
     // The run is over, so its channel is too. Closed here rather than beside
     // the session so the crash path closes it as well: a listener left bound
     // after its run settled is a socket whose `run-not-live` check is the only
@@ -1730,6 +1839,7 @@ const DEGRADED_HOLDS: ReadonlySet<AdmissionHoldReason> = new Set([
 export function summarizeDispatch(
   ready: number,
   routed: number,
+  claimed: number,
   admitted: number,
   holds: readonly AdmissionHold[],
   completedAt = Date.now(),
@@ -1745,6 +1855,7 @@ export function summarizeDispatch(
     completedAt,
     ready,
     routed,
+    claimed,
     admitted,
     degraded: holds.some((hold) => DEGRADED_HOLDS.has(hold.reason)),
     holds: [...groups]
@@ -1792,6 +1903,7 @@ function planUsageEscalation(project: string, plan: PlanUsageStatus): Escalation
     return {
       ...base,
       tier: 2,
+      category: "fleet-stopped",
       // Dated: a meter that breaks again next month is a new incident, not a
       // repeat of this one.
       summary: `Plan usage source unreadable — ${project} is not claiming new work (${new Date().toISOString().slice(0, 10)})`,
@@ -1810,6 +1922,7 @@ function planUsageEscalation(project: string, plan: PlanUsageStatus): Escalation
     return {
       ...base,
       tier: 2,
+      category: "fleet-stopped",
       summary: `Plan usage cap names an unusable window "${plan.cap?.windowId ?? "?"}" — ${project} is not claiming new work`,
       detail: [
         plan.detail,
@@ -2284,6 +2397,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
     if (integrity.page) {
       const delivered = await safeEscalate(d, {
         tier: 2,
+        category: "fleet-stopped",
         project: project.name,
         issue: NO_ISSUE,
         // Dated for the same reason the spend cap is: the dedup key is the
@@ -2327,6 +2441,10 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
     return pending.length === 0 ? issue : { ...issue, labels: effectiveLabels(issue.labels, pending) };
   });
   const { routed, unroutable } = route(effective, project);
+  // Ready issues that route() dropped without a reason carry a state label —
+  // claimed by a live or settling run — so the claimed count is subtraction
+  // rather than a routed-state signal (#228).
+  const claimed = effective.length - routed.length - unroutable.length;
   const routingHolds: AdmissionHold[] = unroutable.map((u) => ({
     issue: u.issue.number,
     reason: `unroutable:${u.reason}`,
@@ -2334,7 +2452,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   const recordDispatch = (admitted: number, holds: readonly AdmissionHold[]): void => {
     store.recordDispatch(
       project.name,
-      summarizeDispatch(ready.length, routed.length, admitted, holds),
+      summarizeDispatch(ready.length, routed.length, claimed, admitted, holds),
     );
   };
 
@@ -2368,6 +2486,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
     setPaused(true, { source: "spend-cap", reason: `daily spend reached $${caps.dailySpendUsd}` });
     await safeEscalate(d, {
       tier: 2,
+      category: "fleet-stopped",
       project: project.name,
       issue: NO_ISSUE,
       // Dated so the same cap pages again tomorrow, but only once per day.
@@ -2433,6 +2552,8 @@ export interface DaemonHealthSnapshot {
   rssBytes: number;
   dispatch?: DispatchSummary;
   codeGraph?: CodeGraphHealth;
+  /** Live workers in a non-running pause phase; absent/empty = nothing paused. */
+  workers?: { issue: number; runId: string; phase: WorkerPausePhase }[];
 }
 
 export function daemonHealthSnapshot(
@@ -2441,6 +2562,7 @@ export function daemonHealthSnapshot(
   paused = isPaused(),
   rssBytes = process.memoryUsage().rss,
   codeGraph?: CodeGraphHealth,
+  workerControls?: WorkerControlRegistry,
 ): DaemonHealthSnapshot {
   const dispatch = store.latestDispatch(project);
   return {
@@ -2451,6 +2573,7 @@ export function daemonHealthSnapshot(
     rssBytes,
     ...(dispatch === undefined ? {} : { dispatch }),
     ...(codeGraph?.configured === true ? { codeGraph } : {}),
+    ...(workerControls === undefined ? {} : { workers: workerControls.snapshot(project) }),
   };
 }
 
@@ -2515,10 +2638,70 @@ export async function turnLimitResponse(
   );
 }
 
+export async function workerControlResponse(
+  req: Request,
+  project: string,
+  store: Pick<Store, "latestRun">,
+  registry: WorkerControlRegistry,
+): Promise<Response | undefined> {
+  const url = new URL(req.url);
+  const match = /^\/runs\/(\d+)\/(pause|resume)$/.exec(url.pathname);
+  if (req.method !== "PUT" || match === null) return undefined;
+  if (!req.headers.get("content-type")?.startsWith("application/json")) {
+    return Response.json({ error: "content-type must be application/json" }, { status: 415 });
+  }
+
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return Response.json({ error: "request body must be valid JSON" }, { status: 400 });
+  }
+  if (body === null || typeof body !== "object") {
+    return Response.json({ error: "request body must be a JSON object" }, { status: 400 });
+  }
+  const requestedProject = Reflect.get(body, "project");
+  if (typeof requestedProject !== "string" || requestedProject.length === 0) {
+    return Response.json({ error: "project must be a non-empty string" }, { status: 400 });
+  }
+  if (requestedProject !== project) {
+    return Response.json(
+      { error: `daemon serves project "${project}", not requested project "${requestedProject}"` },
+      { status: 409 },
+    );
+  }
+
+  const issue = Number(match[1]);
+  const outcome =
+    match[2] === "pause"
+      ? await registry.pause(project, issue)
+      : registry.resume(project, issue);
+  if (outcome.kind === "ok") {
+    return Response.json({ runId: outcome.runId, phase: outcome.phase });
+  }
+  if (outcome.kind === "refused") {
+    return Response.json({ error: `#${issue}: ${outcome.error}` }, { status: 409 });
+  }
+
+  const latest = store.latestRun(project, issue);
+  if (latest === undefined) {
+    return Response.json({ error: `no run recorded for #${issue}` }, { status: 404 });
+  }
+  return Response.json(
+    {
+      error:
+        `#${issue} has no live worker controller; its session already settled ` +
+        `or belongs to another daemon (stored state: ${latest.state})`,
+    },
+    { status: 409 },
+  );
+}
+
 export interface DaemonHttpDeps {
   project: string;
   store: Pick<Store, "latestRun">;
   turnLimits: TurnLimitRegistry;
+  workerControls: WorkerControlRegistry;
   health: () => DaemonHealthSnapshot;
 }
 
@@ -2526,17 +2709,18 @@ export interface DaemonHttpDeps {
  * The whole HTTP surface, in one named function so a test can pin what is *not*
  * on it.
  *
- * Two routes: a health read, and the turn-limit control. Everything else is
- * 404, and that is the contract — see the prohibition at the `Bun.serve` call
- * for why no mutation may be added here. Extracted from the serve callback
- * precisely so "the daemon's HTTP port exposes no mutation route" is something
- * a test asserts rather than something a reviewer has to notice (#126).
+ * Three route families: the health read, turn-limit control, and worker
+ * pause/resume control. Everything else is 404. The controls mutate only
+ * daemon-owned live sessions; tracker and repository mutations stay on the
+ * authenticated per-run channel described at the `Bun.serve` call (#126).
  */
 export async function daemonHttpResponse(req: Request, d: DaemonHttpDeps): Promise<Response> {
   const url = new URL(req.url);
   if (req.method === "GET" && url.pathname === "/healthz") return Response.json(d.health());
-  const control = await turnLimitResponse(req, d.project, d.store, d.turnLimits);
-  return control ?? new Response("not found\n", { status: 404 });
+  const turnLimit = await turnLimitResponse(req, d.project, d.store, d.turnLimits);
+  if (turnLimit !== undefined) return turnLimit;
+  const workerControl = await workerControlResponse(req, d.project, d.store, d.workerControls);
+  return workerControl ?? new Response("not found\n", { status: 404 });
 }
 
 export interface StatusSnapshot {
@@ -2672,7 +2856,7 @@ export function formatDispatchSummary(summary?: DispatchSummary): string {
   if (summary === undefined) return "last dispatch  (none recorded)";
   const lines = [
     `last dispatch  ${new Date(summary.completedAt).toISOString()}${summary.degraded ? "  DEGRADED" : ""}`,
-    `  candidates    ${summary.ready} ready / ${summary.routed} routed`,
+    `  candidates    ${summary.ready} ready / ${summary.claimed ?? 0} in flight / ${summary.routed} spare`,
     `  admitted      ${summary.admitted}`,
   ];
   if (summary.holds.length === 0) {
@@ -3104,6 +3288,28 @@ async function recoverRun(
       log(`#${run.issue} escalated from persistent ${cls}: ${evidence}`);
       return;
     }
+    // Same bound for provider-transient: an issue whose stream keeps stalling
+    // mid-run is requeued free (no attempt, no continuation charged) — but a
+    // provider that aborts three times for one issue is down, and a human has
+    // to check its status before hand-requeueing (#220).
+    if (
+      cls === "provider-transient" &&
+      store.classCountFor(project.name, run.issue, "provider-transient") >= PROVIDER_TRANSIENT_MAX_STRIKES
+    ) {
+      await safeEscalate(d, {
+        tier: 1,
+        project: project.name,
+        issue: run.issue,
+        summary: `[provider-transient] #${run.issue}: the provider keeps aborting mid-stream — ${evidence}`,
+        detail: [
+          `The provider aborted the stream for #${run.issue} ${PROVIDER_TRANSIENT_MAX_STRIKES} times without the run ever producing a verdict (0 tokens billed each time).`,
+          "Check provider status before requeueing by hand.",
+        ].join("\n"),
+      });
+      store.updateRun(run.id, { recoveredAt: Date.now() });
+      log(`#${run.issue} escalated from persistent ${cls}: ${evidence}`);
+      return;
+    }
     // Only when the tracker still shows this issue as ours to hand back. An
     // issue that is closed, or has no state label, was resolved by another route
     // and requeueing it would dispatch work nobody asked for.
@@ -3521,6 +3727,7 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   const turnLimits = createTurnLimitRegistry((runId, maxTurns) => {
     store.updateRun(runId, { maxTurns });
   });
+  const workerControls = createWorkerControlRegistry();
   const d: Deps = {
     project,
     caps,
@@ -3531,6 +3738,7 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
     usage: sharedUsageSource(),
     escalate: (e) => escalator.escalate(e),
     turnLimits,
+    workerControls,
     integrity,
     // Fresh per daemon run, like the integrity gate: a restart is entitled to
     // page again about a stall that is still on disk.
@@ -3607,14 +3815,15 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
   process.on("SIGINT", stop);
   process.on("SIGTERM", stop);
 
-  // ── NO MUTATION ROUTE BELONGS ON THIS PORT ────────────────────────────────
+  // ── NO TRACKER OR REPOSITORY MUTATION BELONGS ON THIS PORT ───────────────
   //
   // This is unauthenticated loopback TCP. Every local user can reach it, it
   // carries no credential of any kind, and it cannot tell one caller from
-  // another: `127.0.0.1` is not an identity. `turnLimitResponse` already shows
-  // what that costs — it trusts a body-supplied `project`, which is exactly the
-  // shape "identity from the payload" takes when nobody is watching, and it is
-  // tolerable only because raising a turn ceiling is bounded and reversible.
+  // another: `127.0.0.1` is not an identity. The turn-limit and worker
+  // pause/resume controls trust a body-supplied `project`, which is exactly the
+  // shape "identity from the payload" takes when nobody is watching. Those
+  // controls are tolerable only because they are bounded, live-run-local, and
+  // reversible.
   //
   // A merge, a push, a release or a label is none of those things. Do not add
   // one here, and do not add "just a small one" behind a shared secret either:
@@ -3630,7 +3839,9 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
         project: project.name,
         store,
         turnLimits,
-        health: () => daemonHealthSnapshot(store, project.name, undefined, undefined, codeGraph),
+        workerControls,
+        health: () =>
+          daemonHealthSnapshot(store, project.name, undefined, undefined, codeGraph, workerControls),
       }),
   });
   log(`serving /healthz on :${server.port}, project ${project.name}`);

package/src/diff-flags.ts

@@ -266,17 +266,49 @@ const CHANGED_LINE = /^[ \t>]*changed:[ \t]*(.*)$/im;
  */
 const CLAIMED_PATH = /^(?:[\w.@~+-]+\/)+[\w.@~*+-]*$|^[\w.@~+-]*\.[A-Za-z][A-Za-z0-9]{1,7}$/;
 
+/** A Python dotted module: `services.rule_purge`, `omp.routing`. Not a path —
+ *  segments joined by `.` — but a legitimate way for a report to name the file
+ *  it touched without disclosing the directory it lives in (#224).
+ *
+ *  Every segment is at least two characters so prose abbreviations (`e.g`,
+ *  `i.e.`, `a.k.a`) stay commentary: they are exactly the prose the path
+ *  heuristic exists to reject, and each one that slipped through would become
+ *  an "you claimed a file you never touched" flag on an honest report. */
+const DOTTED_MODULE = /^[A-Za-z_]\w+(?:\.[A-Za-z_]\w+)+$/;
+
+/** One-level brace expansion: `a/{b,c}.py` → [`a/b.py`, `a/c.py`]. Braces are
+ *  how a report compresses adjacent files into one token; each comma-separated
+ *  alternative is substituted into the skeleton. Nesting is deliberately
+ *  unsupported — one level matches the spellings reports actually produce. */
+function expandBraces(token: string): string[] {
+  const group = /\{[^{}]*\}/.exec(token);
+  if (group === null) return [token];
+  const alternatives = group[0].slice(1, -1).split(",").filter((a) => a.length > 0);
+  if (alternatives.length === 0) return [token];
+  const prefix = token.slice(0, group.index);
+  const suffix = token.slice(group.index + group[0].length);
+  return alternatives.map((alt) => prefix + alt + suffix);
+}
+
 /** Every path-shaped token on the report's `changed:` line. An absent line and
  *  a line naming nothing are the same answer: nothing was disclosed. */
 export function claimedPaths(report: string): string[] {
   const line = CHANGED_LINE.exec(report)?.[1] ?? "";
   const seen = new Set<string>();
-  for (const raw of line.split(/[\s,;]+/)) {
+  // Split on whitespace and semicolons, and on commas *outside* a brace group:
+  // the comma in `a/{b,c}.py` is an alternative separator, not a token
+  // separator, so a brace-compressed token must survive whole (#224).
+  for (const raw of line.split(/[\s;]+|,(?![^{}]*\})/)) {
     const token = raw.replace(/^[`'"([*-]+/, "").replace(/[`'")\].,:;]+$/, "");
     if (token === "" || token === "none") continue;
     const normalised = token.replace(/^\.?\//, "");
-    if (!CLAIMED_PATH.test(normalised)) continue;
-    seen.add(normalised);
+    // Expansion happens here so every downstream consumer — both `covers`
+    // directions — sees plain paths: a brace token dies earlier at the
+    // CLAIMED_PATH filter if it is never opened up (#224).
+    for (const expanded of expandBraces(normalised)) {
+      if (!CLAIMED_PATH.test(expanded) && !DOTTED_MODULE.test(expanded)) continue;
+      seen.add(expanded);
+    }
   }
   return [...seen];
 }
@@ -305,6 +337,15 @@ function covers(claim: string, path: string): boolean {
     return pattern.test(path) || pattern.test(basename(path));
   }
   if (path.endsWith(`/${claim}`) || claim.endsWith(`/${path}`)) return true;
+  // A Python dotted module names a file by import path, not by location:
+  // `services.rule_purge` covers `backend/app/services/rule_purge.py`. Only
+  // consulted after the path rules, because `foo.bar` is also a valid filename
+  // and a literal match must win. Matching several changed files is fine — the
+  // check wants evidence the worker knew, not a unique index (#224).
+  if (DOTTED_MODULE.test(claim)) {
+    const fragment = `${claim.replaceAll(".", "/")}.py`;
+    if (path === fragment || path.endsWith(`/${fragment}`)) return true;
+  }
   const last = claim.slice(claim.lastIndexOf("/") + 1);
   return !last.includes(".") && path.startsWith(`${claim}/`);
 }

package/src/digest-schedule.ts

@@ -0,0 +1,59 @@
+/**
+ * When the daily digest is due, in the zone the operator reads it (#229).
+ *
+ * Pure by construction: every fact arrives as a timestamp and the policy, and
+ * nothing here reads a clock or a file. The digest is "one per day" in the
+ * IANA zone it is configured with (host zone when none) — a UTC key would roll
+ * the digest over mid-evening for anyone west of Greenwich.
+ */
+
+import type { ReportingPolicy } from "./types.ts";
+
+/** `YYYY-MM-DD` in an IANA timezone (host zone when `timezone` is absent). */
+export function localDayKey(at: number, timezone?: string): string {
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(new Date(at));
+  const get = (type: "year" | "month" | "day"): string =>
+    parts.find((p) => p.type === type)?.value ?? "00";
+  return `${get("year")}-${get("month")}-${get("day")}`;
+}
+
+/** `HH:MM` wall-clock in the zone, 24h and zero-padded. */
+function localClockAt(at: number, timezone?: string): string {
+  return new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  }).format(new Date(at));
+}
+
+/**
+ * Whether the digest is due now.
+ *
+ * - `none` → never.
+ * - `per-tick` → always (the orchestrator sends it with every report).
+ * - `daily` without `at` → once per day in the configured zone.
+ * - `daily` with `at` → on a day it has not already run, once the local clock
+ *   has passed `at`. A restart after `at` still finds today unsent → one
+ *   catch-up; a fully missed day is skipped, never sent late.
+ */
+export function digestDue(
+  policy: Pick<ReportingPolicy, "digest">,
+  lastDigestDayKey: string | undefined,
+  now: number,
+): boolean {
+  const { cadence, at, timezone } = policy.digest;
+  if (cadence === "none") return false;
+  if (cadence === "per-tick") return true;
+  // daily
+  if (at === undefined) {
+    return lastDigestDayKey !== localDayKey(now, timezone);
+  }
+  if (lastDigestDayKey === localDayKey(now, timezone)) return false;
+  return localClockAt(now, timezone) >= at;
+}

package/src/escalate.ts

@@ -213,6 +213,23 @@ export function createEscalator(
       if (e.tier === 2 && chatId) {
         const token = readTelegramToken();
         if (token) {
+          // A category this policy defers does not page now: it is held here so
+          // the digest is the delivery authority for it (#229). A missing
+          // `reporting` block means the default (page everything); an explicit
+          // list decides each escalation by its category, defaulting `tier2`.
+          const category = e.category ?? "tier2";
+          const interruptOn = p.reporting?.interruptOn;
+          if (interruptOn !== undefined && !interruptOn.includes(category)) {
+            store.addHeldNotice({
+              project: p.name,
+              category,
+              summary: e.summary,
+              detail: text,
+              createdAt: Date.now(),
+            });
+            store.markNotified(key);
+            return;
+          }
           // A send failure throws: `markNotified` stays uncalled so the next
           // poll retries instead of writing the event off as delivered. No
           // backoff in here — the dispatcher tick *is* the retry, and an