omp-conductor 0.12.0 → 0.14.0

package/src/cli.ts

@@ -5,6 +5,7 @@
  * process lifecycle in ./lifecycle.ts, so the CLI and the `/conductor` plugin
  * cannot drift apart.
  */
+import { randomUUID } from "node:crypto";
 import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
 import { dirname, join } from "node:path";
@@ -21,6 +22,7 @@ import {
   proposeRetrofit,
   repairPolicyBannerCrumbs,
 } from "./brief-upgrade.ts";
+import { interruptDisposition } from "./availability.ts";
 import { findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { CONDITION_FORMS, parseCondition } from "./decisions.ts";
 import { isPaused, pausedAt, runDaemon, setPaused } from "./daemon.ts";
@@ -106,6 +108,7 @@ usage:
   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]
@@ -114,7 +117,8 @@ usage:
   omp-conductor graph-setup [--project NAME] [--write]
   omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
   omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
-  omp-conductor report --text TEXT [--kind material|digest] [--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] [--events IDS] [--notices IDS] [--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]
@@ -172,8 +176,9 @@ 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.
@@ -195,12 +200,17 @@ usage:
            strings, one per --arg (e.g. --arg prUrl=https://x --arg headSha=y).
            A refusal exits 3. See conductor_pr_merge/conductor_label/
            conductor_release/conductor_pr_update_branch in the brief.
+  event    persist one ordinary material outcome without sending it. Category
+           is a short lowercase slug; summary and evidence name what happened
+           and where it can be verified. --occurred-at defaults to now.
   report   hand a rendered report to the daemon's durable outbox. The report is
            persisted before anything is sent, delivered by the daemon with
            bounded retries, and shown by status until it lands. Delivery is
            at-least-once: a crash mid-send is retried and the retry says it may
            be a repeat. --kind digest is accepted at most once per local day,
            decided from the ledger rather than from what you remember sending.
+           A digest associates the comma-separated --events and --notices rows
+           atomically; omitted rows stay owed.
   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
@@ -263,6 +273,26 @@ function flag(argv: string[], name: string): string | undefined {
   return prefixed?.slice(name.length + 3);
 }
 
+function digestIdsFlag(argv: string[], name: "events" | "notices"): string[] {
+  const raw = flag(argv, name);
+  if (raw === undefined) {
+    if (argv.includes(`--${name}`)) {
+      process.stderr.write(`omp-conductor: report --${name} needs comma-separated row ids\n`);
+      process.exit(2);
+    }
+    return [];
+  }
+  const ids = [...new Set(raw.split(",").map((id) => id.trim()).filter((id) => id.length > 0))];
+  if (
+    ids.length === 0 ||
+    ids.some((id) => !/^(?:[0-9a-f]{12}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/.test(id))
+  ) {
+    process.stderr.write(`omp-conductor: report --${name} needs comma-separated ledger row ids\n`);
+    process.exit(2);
+  }
+  return ids;
+}
+
 /**
  * `--port` for the three verbs that take one. Exits 2 rather than defaulting,
  * because silently ignoring a typo'd port would leave the operator probing an
@@ -612,14 +642,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();
@@ -641,18 +668,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();
       }
@@ -774,14 +821,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");
       }
@@ -793,13 +856,21 @@ try {
 
     case "worker": {
       const sub = argv[1];
-      if (sub !== "pause" && sub !== "resume") {
+      if (sub !== "pause" && sub !== "resume" && sub !== "stop") {
         process.stderr.write(
-          "omp-conductor: worker needs pause or resume, then an issue number\n",
+          "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");
@@ -813,25 +884,63 @@ try {
         {
           method: "PUT",
           headers: { "content-type": "application/json" },
-          body: JSON.stringify({ project: project.name }),
+          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`,
-      );
+      process.stdout.write(`#${issue} worker ${payload.phase} (run ${payload.runId})\n`);
       break;
     }
 
@@ -938,6 +1047,58 @@ try {
       break;
     }
 
+    case "event": {
+      if (argv[1] !== "record") {
+        process.stderr.write("omp-conductor: event needs the record subcommand\n");
+        process.exit(2);
+      }
+      const category = flag(argv, "category");
+      const summary = flag(argv, "summary")?.replace(/\s+/g, " ").trim();
+      const evidence = flag(argv, "evidence")?.replace(/\s+/g, " ").trim();
+      if (
+        category === undefined ||
+        !/^[a-z0-9][a-z0-9-]{0,31}$/.test(category) ||
+        summary === undefined ||
+        summary.length === 0 ||
+        summary.length > 240 ||
+        summary.startsWith("--") ||
+        evidence === undefined ||
+        evidence.length === 0 ||
+        evidence.length > 500 ||
+        evidence.startsWith("--")
+      ) {
+        process.stderr.write(
+          "omp-conductor: event record needs --category with a lowercase slug, --summary (1-240 chars), and --evidence (1-500 chars)\n",
+        );
+        process.exit(2);
+      }
+      const rawOccurredAt = flag(argv, "occurred-at");
+      const recordedAt = Date.now();
+      const occurredAt = rawOccurredAt === undefined ? recordedAt : Date.parse(rawOccurredAt);
+      if (!Number.isFinite(occurredAt)) {
+        process.stderr.write("omp-conductor: event record --occurred-at needs an ISO timestamp\n");
+        process.exit(2);
+      }
+      const project = findProject(loadConfig(), flag(argv, "project"));
+      const store = openStore(dbPath());
+      try {
+        const event = store.recordMaterialEvent({
+          project: project.name,
+          category,
+          summary,
+          evidence,
+          occurredAt,
+          recordedAt,
+        });
+        process.stdout.write(
+          `event ${event.id} recorded for ${project.name} (${event.category}, ${new Date(event.occurredAt).toISOString()}) — nothing sent\n`,
+        );
+      } finally {
+        store.close();
+      }
+      break;
+    }
+
     /**
      * The handover point. Authorship stays with the model; from here the daemon
      * owns delivery, so "I sent the report" stops being a claim the model makes
@@ -962,6 +1123,12 @@ try {
         process.exit(2);
       }
       const kind = rawKind as ReportKind;
+      if (kind !== "digest" && (argv.includes("--events") || argv.includes("--notices"))) {
+        process.stderr.write(
+          "omp-conductor: report --events and --notices are valid only with --kind digest\n",
+        );
+        process.exit(2);
+      }
       const project = findProject(loadConfig(), flag(argv, "project"));
       const store = openStore(dbPath());
       try {
@@ -970,8 +1137,8 @@ try {
         // policy defers is refused here rather than silently turning into a
         // page, or a digest going out off-schedule.
         const policy = project.reporting;
+        const digestPolicy = policy?.digest ?? { cadence: "per-tick" };
         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);
@@ -989,32 +1156,54 @@ try {
           }
         }
         if (kind === "material") {
-          const interruptOn = policy?.interruptOn;
-          if (interruptOn !== undefined && !interruptOn.includes("material")) {
+          const disposition = interruptDisposition(policy, "material", at);
+          if (disposition === "digest") {
             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);
           }
+          if (disposition === "availability") {
+            const noticeId = randomUUID();
+            store.addHeldNotice({
+              id: noticeId,
+              project: project.name,
+              category: "material",
+              summary: body.split("\n", 1)[0]!.slice(0, 240),
+              detail: body,
+              createdAt: at,
+              releaseOnAvailable: true,
+            });
+            process.stdout.write(
+              `held notice ${noticeId} queued for ${project.name} (material; quiet hours)\n` +
+                "the daemon will include it in the next digest or working-hours catch-up\n",
+            );
+            break;
+          }
         }
-        const { report, deduped } = store.enqueueReport({
+        const draft = {
           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, project.reporting?.digest?.timezone) }
+          // Only a daily digest is at-most-once. Per-tick digests and material
+          // reports describe new outcomes each time, so they carry no daily key.
+          ...(kind === "digest" && digestPolicy.cadence === "daily"
+            ? { dedupeKey: digestDedupeKey(at, digestPolicy.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);
+        };
+        const { report, deduped } =
+          kind === "digest"
+            ? store.enqueueDigestReport(
+                draft,
+                digestIdsFlag(argv, "events"),
+                digestIdsFlag(argv, "notices"),
+              )
+            : store.enqueueReport(draft);
         process.stdout.write(
           deduped
             ? `today's digest was already handed over as report ${report.id} (${report.state}) — nothing queued\n` +
-                "the ledger decides this, not your memory of the last tick; use --kind material for a second event\n"
+                "the ledger decides this, not your memory of the last tick; newly named rows remain owed for a later digest\n"
             : `report ${report.id} queued for ${project.name} (${kind})\n` +
                 "the daemon owns delivery from here; omp-conductor status shows it until it lands\n",
         );

package/src/config.ts

@@ -37,6 +37,7 @@ import {
   REPORT_SCOPES,
   INTERRUPT_CATEGORIES,
   DIGEST_CADENCES,
+  WEEKDAYS,
   type Caps,
   type ConductorConfig,
   type DigestCadence,
@@ -49,6 +50,8 @@ import {
   type ReleaseRequirement,
   type ReportScope,
   type ReportingPolicy,
+  type Weekday,
+  type WeeklyAvailability,
   type RepoTarget,
   type ResolvedGrants,
 } from "./types.ts";
@@ -72,6 +75,7 @@ const CAP_KEYS = Object.keys(DEFAULT_CAPS) as (keyof Caps)[];
 const REPORT_SCOPE_LIST = quoteList(REPORT_SCOPES);
 const INTERRUPT_CATEGORY_LIST = quoteList(INTERRUPT_CATEGORIES);
 const DIGEST_CADENCE_LIST = quoteList(DIGEST_CADENCES);
+const WEEKDAY_LIST = quoteList(WEEKDAYS);
 const AUTHORITY_HOLDER_LIST = quoteList(AUTHORITY_HOLDERS);
 const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
 const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
@@ -227,12 +231,16 @@ export function writeConfigRaw(text: string): void {
  */
 export function resolveCaps(p: ProjectConfig, defaults: Caps): Caps {
   const o: Partial<Caps> = p.caps ?? {};
+  const workerMaxTurns = o.workerMaxTurns ?? defaults.workerMaxTurns;
   return {
     maxConcurrentWorkers: o.maxConcurrentWorkers ?? defaults.maxConcurrentWorkers,
     maxConcurrentWorkersPerRepo: o.maxConcurrentWorkersPerRepo ?? defaults.maxConcurrentWorkersPerRepo,
     dailySpendUsd: o.dailySpendUsd !== undefined ? o.dailySpendUsd : defaults.dailySpendUsd,
     planUsage: o.planUsage !== undefined ? o.planUsage : defaults.planUsage,
-    workerMaxTurns: o.workerMaxTurns ?? defaults.workerMaxTurns,
+    workerMaxTurns,
+    workerMaxTurnsCeiling:
+      o.workerMaxTurnsCeiling ??
+      (o.workerMaxTurns === undefined ? defaults.workerMaxTurnsCeiling : workerMaxTurns * 2),
     workerWallClockMs: o.workerWallClockMs ?? defaults.workerWallClockMs,
     maxAttemptsPerIssue: o.maxAttemptsPerIssue ?? defaults.maxAttemptsPerIssue,
     maxContinuationsPerIssue:
@@ -366,9 +374,13 @@ function validate(parsed: unknown, path: string): ConductorConfig {
     );
   }
 
+  const configuredDefaults = coerceCaps(root["defaults"], `"defaults"`, problems, legacyCaps);
+  const defaultWorkerMaxTurns = configuredDefaults.workerMaxTurns ?? DEFAULT_CAPS.workerMaxTurns;
   const defaults: Caps = {
     ...DEFAULT_CAPS,
-    ...coerceCaps(root["defaults"], `"defaults"`, problems, legacyCaps),
+    ...configuredDefaults,
+    workerMaxTurnsCeiling:
+      configuredDefaults.workerMaxTurnsCeiling ?? defaultWorkerMaxTurns * 2,
   };
 
   const rawProjects = root["projects"];
@@ -536,15 +548,17 @@ function normalizeReporting(parsed: unknown, label: string, problems: string[]):
   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 known = ["scope", "interruptOn", "digest", "availability", "scopePreset"];
   const unknownKeys = keys.filter((k) => !known.includes(k));
   if (unknownKeys.length > 0) {
     problems.push(`${label}: reporting has unknown key(s): ${unknownKeys.join(", ")}`);
   }
   const hasScope = raw["scope"] !== undefined;
-  const hasExplicit = keys.includes("interruptOn") || keys.includes("digest");
+  const hasExplicit = keys.includes("interruptOn") || keys.includes("digest") || keys.includes("availability");
   if (hasScope && hasExplicit) {
-    problems.push(`${label}: reporting.scope is a preset — remove it when configuring interruptOn/digest explicitly`);
+    problems.push(
+      `${label}: reporting.scope is a preset — remove it when configuring interruptOn/digest/availability explicitly`,
+    );
     return defaultReporting();
   }
   if (hasScope || (!hasExplicit && keys.length === 0)) {
@@ -573,9 +587,23 @@ function normalizeReporting(parsed: unknown, label: string, problems: string[]):
       ? (storedPreset as ReportScope)
       : undefined;
 
+  const interruptOn = normalizeInterruptOn(raw["interruptOn"], label, problems);
+  const digest = normalizeDigest(raw["digest"], label, problems);
+  const availability = normalizeAvailability(raw["availability"], label, problems);
+  // One setup answer supplies both clocks. Hand-written configs may omit the
+  // digest copy; the availability zone then becomes its daily clock too.
+  if (availability !== undefined && digest.cadence === "daily") {
+    if (digest.timezone === undefined) digest.timezone = availability.timezone;
+    else if (digest.timezone !== availability.timezone) {
+      problems.push(
+        `${label}: reporting.digest.timezone must match reporting.availability.timezone`,
+      );
+    }
+  }
   return {
-    interruptOn: normalizeInterruptOn(raw["interruptOn"], label, problems),
-    digest: normalizeDigest(raw["digest"], label, problems),
+    interruptOn,
+    digest,
+    ...(availability === undefined ? {} : { availability }),
     ...(scopePreset === undefined ? {} : { scopePreset }),
   };
 }
@@ -657,6 +685,94 @@ function normalizeDigest(parsed: unknown, label: string, problems: string[]): Re
   return digest;
 }
 
+function normalizeAvailability(
+  parsed: unknown,
+  label: string,
+  problems: string[],
+): WeeklyAvailability | undefined {
+  if (parsed === undefined) return undefined;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    problems.push(`${label}: reporting.availability must be an object`);
+    return undefined;
+  }
+  const raw = parsed as Raw;
+  const unknownKeys = Object.keys(raw).filter(
+    (key) => !["timezone", "days", "start", "end", "bypass"].includes(key),
+  );
+  if (unknownKeys.length > 0) {
+    problems.push(`${label}: reporting.availability has unknown key(s): ${unknownKeys.join(", ")}`);
+  }
+
+  let timezone: string | undefined;
+  if (typeof raw["timezone"] !== "string" || raw["timezone"].trim() === "") {
+    problems.push(`${label}: reporting.availability.timezone must be a known IANA timezone`);
+  } else {
+    try {
+      new Intl.DateTimeFormat("en-GB", { timeZone: raw["timezone"] });
+      timezone = raw["timezone"];
+    } catch {
+      problems.push(`${label}: reporting.availability.timezone is not a known IANA timezone`);
+    }
+  }
+
+  const days: Weekday[] = [];
+  if (!Array.isArray(raw["days"]) || raw["days"].length === 0) {
+    problems.push(`${label}: reporting.availability.days must be a non-empty array of ${WEEKDAY_LIST}`);
+  } else {
+    for (const item of raw["days"]) {
+      if (typeof item !== "string" || !(WEEKDAYS as readonly string[]).includes(item)) {
+        problems.push(
+          `${label}: reporting.availability.days has unknown day ${JSON.stringify(item)} — one of ${WEEKDAY_LIST}`,
+        );
+        continue;
+      }
+      const day = item as Weekday;
+      if (!days.includes(day)) days.push(day);
+    }
+  }
+
+  const start = raw["start"];
+  const end = raw["end"];
+  if (typeof start !== "string" || !DIGEST_AT.test(start)) {
+    problems.push(`${label}: reporting.availability.start must be a 24h HH:MM time`);
+  }
+  if (typeof end !== "string" || !DIGEST_AT.test(end)) {
+    problems.push(`${label}: reporting.availability.end must be a 24h HH:MM time`);
+  }
+  if (typeof start === "string" && typeof end === "string" && start === end) {
+    problems.push(`${label}: reporting.availability.start and end must differ`);
+  }
+
+  const bypass: InterruptCategory[] = [];
+  if (!Array.isArray(raw["bypass"])) {
+    problems.push(
+      `${label}: reporting.availability.bypass must be an array of ${INTERRUPT_CATEGORY_LIST} (empty means none)`,
+    );
+  } else {
+    for (const item of raw["bypass"]) {
+      if (typeof item !== "string" || !(INTERRUPT_CATEGORIES as readonly string[]).includes(item)) {
+        problems.push(
+          `${label}: reporting.availability.bypass has unknown category ${JSON.stringify(item)} — one of ${INTERRUPT_CATEGORY_LIST}`,
+        );
+        continue;
+      }
+      const category = item as InterruptCategory;
+      if (!bypass.includes(category)) bypass.push(category);
+    }
+  }
+
+  return timezone === undefined ||
+    days.length === 0 ||
+    typeof start !== "string" ||
+    !DIGEST_AT.test(start) ||
+    typeof end !== "string" ||
+    !DIGEST_AT.test(end) ||
+    start === end ||
+    !Array.isArray(raw["bypass"])
+    ? undefined
+    : { timezone, days, start, end, bypass };
+}
+
 /**
  * Who triages escalations, and how they are delivered when nobody answers.
  *