omp-conductor 0.13.0 → 0.14.0

package/src/setup.ts

@@ -52,18 +52,22 @@ import {
   DEFAULT_REPORT_SCOPE,
   DENIED_RELEASE_GRANTS,
   RELEASE_SHAPES,
+  WEEKDAYS,
   type BaseFreshness,
   type BehindBaseAction,
   type Caps,
   type ConductorConfig,
+  type DigestCadence,
   type DraftPolicy,
   type OrchestratorMode,
+  type InterruptCategory,
   type ProjectConfig,
   type ProjectPolicy,
   type ReleaseRequirement,
-  type ReportScope,
   type ReportScopeChoice,
   type ReportingPolicy,
+  type Weekday,
+  type WeeklyAvailability,
   type RepoTarget,
   type ResolvedGrants,
 } from "./types.ts";
@@ -92,8 +96,19 @@ export interface SetupAnswers {
   fallbackToIssueComment: boolean;
   /** How loud the supervising orchestrator session should be. */
   reportScope: ReportScopeChoice;
-  /** The daily digest wall-clock (`HH:MM`) for the `quiet` choice, blank = model-timed. */
-  quietDigestAt?: string;
+  /** One IANA zone shared by the configured window and its daily digest. */
+  reportingTimezone?: string;
+  /** Daily digest wall-clock (`HH:MM`) when an explicit daily policy is chosen. */
+  dailyDigestAt?: string;
+  /** Digest cadence when preserving or explicitly editing a reporting policy. */
+  digestCadence?: DigestCadence;
+  /** Weekly window without its shared timezone; absent keeps 24-hour interrupts. */
+  availability?: Omit<WeeklyAvailability, "timezone">;
+  /**
+   * Exact policy read from disk. Unrelated amend areas carry this through
+   * untouched; the reporting interview deletes it before applying new answers.
+   */
+  preservedReporting?: ReportingPolicy;
   /**
    * Mechanical gate for release/deploy-shaped tool calls, per shape. Always
    * complete: the wizard asks about every shape, so an answer object can never
@@ -189,7 +204,7 @@ export const REPORT_SCOPE_CHOICES: readonly {
     scope: "decisions",
     label: "Decisions interrupt, rest batches",
     description:
-      "tier-2 decisions and fleet-stopping conditions immediately; every other material event ships with the tick report",
+      "tier-2 decisions and fleet-stopping conditions immediately; every other material event ships with the configured digest",
   },
   {
     scope: "material",
@@ -510,6 +525,88 @@ export async function createMissingLabels(trackerRepo: string, plan: LabelPlan[]
   return created;
 }
 
+const QUIET_INTERRUPT_ON: InterruptCategory[] = [
+  "tier2",
+  "fleet-stopped",
+  "confirmed-failure",
+];
+
+function interruptCategories(scope: ReportScopeChoice): InterruptCategory[] {
+  return scope === "quiet"
+    ? [...QUIET_INTERRUPT_ON]
+    : [...(SCOPE_PRESETS[scope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE]).interruptOn];
+}
+
+/** Copy policy arrays so a setup amend cannot mutate the config it was seeded from. */
+function cloneReportingPolicy(policy: ReportingPolicy): ReportingPolicy {
+  return {
+    interruptOn: [...policy.interruptOn],
+    digest: { ...policy.digest },
+    ...(policy.availability === undefined
+      ? {}
+      : {
+          availability: {
+            ...policy.availability,
+            days: [...policy.availability.days],
+            bypass: [...policy.availability.bypass],
+          },
+        }),
+    ...(policy.scopePreset === undefined ? {} : { scopePreset: policy.scopePreset }),
+  };
+}
+
+/** Turn the wizard's local notification answers into the runtime policy. */
+function reportingFromAnswers(a: SetupAnswers): ReportingPolicy {
+  if (a.preservedReporting !== undefined) return cloneReportingPolicy(a.preservedReporting);
+
+  const digest = (fallback: DigestCadence): ReportingPolicy["digest"] => {
+    const cadence = a.digestCadence ?? fallback;
+    if (cadence !== "daily") return { cadence };
+    const at = a.dailyDigestAt?.trim();
+    const timezone = a.reportingTimezone?.trim();
+    return {
+      cadence,
+      ...(at === undefined || at.length === 0 ? {} : { at }),
+      ...(timezone === undefined || timezone.length === 0 ? {} : { timezone }),
+    };
+  };
+
+  const timezone = a.reportingTimezone?.trim();
+  if (a.availability !== undefined) {
+    if (timezone === undefined || timezone.length === 0) {
+      throw new Error("operator availability requires an IANA reporting timezone");
+    }
+    return {
+      interruptOn: interruptCategories(a.reportScope),
+      digest: digest("daily"),
+      availability: {
+        timezone,
+        days: [...a.availability.days],
+        start: a.availability.start,
+        end: a.availability.end,
+        bypass: [...a.availability.bypass],
+      },
+    };
+  }
+  if (a.reportScope === "quiet") {
+    return {
+      interruptOn: [...QUIET_INTERRUPT_ON],
+      digest: digest("daily"),
+    };
+  }
+  const preset = SCOPE_PRESETS[a.reportScope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE];
+  const resolvedDigest = digest(preset.digest.cadence);
+  const presetDigest =
+    resolvedDigest.cadence === preset.digest.cadence &&
+    resolvedDigest.at === preset.digest.at &&
+    resolvedDigest.timezone === preset.digest.timezone;
+  return {
+    interruptOn: [...preset.interruptOn],
+    digest: resolvedDigest,
+    ...(presetDigest ? { scopePreset: preset.scopePreset } : {}),
+  };
+}
+
 /**
  * The single `ProjectConfig` the answers describe.
  *
@@ -576,24 +673,10 @@ 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. 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,
-          },
+    // volume has a line in the file to point at. Opting into availability makes
+    // the schedule explicit and daily; omitting it preserves the preset's
+    // legacy 24-hour behaviour (#273).
+    reporting: reportingFromAnswers(a),
     // 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,19 +750,60 @@ export function defaultAnswers(projectName: string): SetupAnswers {
  * changing an unrelated one. `buildProject(answersFromProject(p))` is pinned to
  * `p` by a test for exactly that reason.
  *
- * Three fields cannot be a straight copy:
+ * Four fields cannot be a straight copy:
  *
  * - `writeOrchestratorBrief` is a decision rather than a value, and it starts
  *   `false` so an amend that never visits the brief area leaves that file alone.
- * - `reportScope` reads through {@link DEFAULT_REPORT_SCOPE}, because the key is
- *   optional on disk. A config written before it existed gains it explicitly on
- *   the next write, saying what it already meant.
+ * - `reportScope` recognizes both preset metadata and the explicit quiet
+ *   category set, because an availability schedule intentionally has no preset.
+ * - The reporting timezone is shared by availability and the daily digest in
+ *   the wizard even though runtime config stores it in both places.
  * - `graphRoot` is one answer for a whole project while the config stores one
  *   path per repo, so it comes back from whichever repo already has one. Repos
  *   that disagree — only a hand-edit can produce that — widen to all of them on
  *   the next write exactly as a full re-run would, and the plan summary names
  *   every clone before anything is written.
  */
+function sameInterruptCategories(
+  actual: readonly InterruptCategory[],
+  expected: readonly InterruptCategory[],
+): boolean {
+  return (
+    actual.length === expected.length &&
+    actual.every((category) => expected.includes(category))
+  );
+}
+
+export function reportScopeFromPolicy(policy: ReportingPolicy | undefined): ReportScopeChoice {
+  if (policy?.scopePreset !== undefined) return policy.scopePreset;
+  const actual = policy?.interruptOn ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE].interruptOn;
+  if (sameInterruptCategories(actual, QUIET_INTERRUPT_ON)) return "quiet";
+  for (const scope of ["material", "decisions", "escalations"] as const) {
+    if (sameInterruptCategories(actual, SCOPE_PRESETS[scope].interruptOn)) return scope;
+  }
+  return DEFAULT_REPORT_SCOPE;
+}
+
+function reportScopeDescriptionForPolicy(policy: ReportingPolicy | undefined): string {
+  const scope = reportScopeFromPolicy(policy);
+  const choice = REPORT_SCOPE_CHOICES.find((candidate) => candidate.scope === scope);
+  const expectedCadence =
+    scope === "quiet" ? "daily" : SCOPE_PRESETS[scope].digest.cadence;
+  const configured = policy?.digest ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE].digest;
+  if (configured.cadence === expectedCadence) {
+    return choice?.description ?? "unknown scope";
+  }
+  const digest =
+    configured.cadence === "none"
+      ? "disabled"
+      : configured.cadence === "per-tick"
+        ? "every tick"
+        : `daily at ${configured.at ?? "(model-timed)"}${
+            configured.timezone === undefined ? "" : ` ${configured.timezone}`
+          }`;
+  return `${choice?.label ?? scope}; configured digest ${digest}`;
+}
+
 export function answersFromProject(p: ProjectConfig): SetupAnswers {
   const answers: SetupAnswers = {
     projectName: p.name,
@@ -699,14 +823,31 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
     releaseGrants: resolveReleaseGrants(p),
     policy: resolvePolicy(p),
     orchestratorMode: p.escalation.orchestrator,
-    reportScope: p.reporting?.scopePreset ?? DEFAULT_REPORT_SCOPE,
+    reportScope: reportScopeFromPolicy(p.reporting),
     writeOrchestratorBrief: false,
   };
+  if (p.reporting !== undefined) {
+    answers.preservedReporting = cloneReportingPolicy(p.reporting);
+    answers.digestCadence = p.reporting.digest.cadence;
+  }
 
   // Set only when present, never as an explicit `undefined`: an absent key is
   // what keeps the rewritten config identical to the one that was read.
   if (p.workerModel !== undefined) answers.workerModel = p.workerModel;
   if (p.escalation.telegramChatId !== undefined) answers.telegramChatId = p.escalation.telegramChatId;
+  if (p.reporting?.digest.at !== undefined) answers.dailyDigestAt = p.reporting.digest.at;
+  if (p.reporting?.digest.timezone !== undefined) {
+    answers.reportingTimezone = p.reporting.digest.timezone;
+  }
+  if (p.reporting?.availability !== undefined) {
+    answers.reportingTimezone = p.reporting.availability.timezone;
+    answers.availability = {
+      days: [...p.reporting.availability.days],
+      start: p.reporting.availability.start,
+      end: p.reporting.availability.end,
+      bypass: [...p.reporting.availability.bypass],
+    };
+  }
   const graphed = graphRepos(p)[0];
   if (graphed !== undefined) answers.graphRoot = dirname(graphed.graphProject);
 
@@ -736,7 +877,6 @@ 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?.scopePreset ?? DEFAULT_REPORT_SCOPE,
     POLICY_SOURCE: policySourceLine(p),
   };
 }
@@ -931,6 +1071,12 @@ function pairedOwner(accessPath: string): string | undefined {
   return undefined;
 }
 
+function describeAvailabilityDays(days: readonly Weekday[]): string {
+  return days.length === WEEKDAYS.length && WEEKDAYS.every((day) => days.includes(day))
+    ? "every day"
+    : days.join(",");
+}
+
 /**
  * Everything that would change, as plain text, with no side effects at all.
  *
@@ -1083,12 +1229,27 @@ export function summarisePlan(
     `  environments ${a.policy.release.environments.join(", ") || "none declared — every deploy target is refused"}`,
   );
 
-  const chosen = REPORT_SCOPE_CHOICES.find((c) => c.scope === a.reportScope);
+  const reporting = project.reporting as ReportingPolicy;
   const briefPath = orchestratorBriefPath(a);
   lines.push(
     "",
     "reporting",
-    `  scope          ${a.reportScope} — ${chosen?.description ?? "unknown scope"}`,
+    `  scope          ${a.reportScope} — ${reportScopeDescriptionForPolicy(reporting)}`,
+  );
+  if (reporting.availability === undefined) {
+    lines.push("  availability   continuous — interrupt categories may page 24 hours a day");
+  } else {
+    lines.push(
+      `  availability   ${describeAvailabilityDays(reporting.availability.days)} ` +
+        `${reporting.availability.start}-${reporting.availability.end} ${reporting.availability.timezone}`,
+      `  bypass         ${reporting.availability.bypass.join(", ") || "none"}`,
+    );
+  }
+  lines.push(
+    `  digest         ${reporting.digest.cadence}` +
+      (reporting.digest.cadence === "daily"
+        ? ` at ${reporting.digest.at ?? "(model-timed)"}${reporting.digest.timezone ? ` ${reporting.digest.timezone}` : ""}`
+        : ""),
   );
   if (a.writeOrchestratorBrief) {
     const policyPath = briefPath.replace(/ORCHESTRATOR\.md$/, "POLICY.md");
@@ -1267,9 +1428,8 @@ export const AMEND_AREAS: {
     name: "reporting scope",
     asks: "how much the orchestrator says unprompted",
     describe: (p) => {
-      const scope = p.reporting?.scopePreset ?? DEFAULT_REPORT_SCOPE;
-      const choice = REPORT_SCOPE_CHOICES.find((c) => c.scope === scope);
-      return `${scope} — ${choice?.description ?? "unknown scope"}`;
+      const scope = reportScopeFromPolicy(p.reporting);
+      return `${scope} — ${reportScopeDescriptionForPolicy(p.reporting)}`;
     },
   },
   brief: {