omp-conductor 0.13.0 → 0.15.0

package/src/config.ts

@@ -37,6 +37,7 @@ import {
   REPORT_SCOPES,
   INTERRUPT_CATEGORIES,
   DIGEST_CADENCES,
+  WEEKDAYS,
   type Caps,
   type ConductorConfig,
   type DigestCadence,
@@ -49,38 +50,43 @@ import {
   type ReleaseRequirement,
   type ReportScope,
   type ReportingPolicy,
+  type Weekday,
+  type WeeklyAvailability,
   type RepoTarget,
   type ResolvedGrants,
 } from "./types.ts";
+import {
+  AUTHORITY_HOLDER_LIST,
+  BASE_FRESHNESS_LIST,
+  BEHIND_BASE_ACTION_LIST,
+  ConfigSchema,
+  DIGEST_CADENCE_LIST,
+  DRAFT_POLICY_LIST,
+  INTERRUPT_CATEGORY_LIST,
+  LEGACY_RELEASE_POLICY_LIST,
+  ORCHESTRATOR_MODE_LIST,
+  RELEASE_REQUIREMENT_LIST,
+  RELEASE_SHAPE_LIST,
+  REPORT_SCOPE_LIST,
+  WEEKDAY_LIST,
+  quoteList,
+} from "./config-schema.ts";
 
 /**
  * A JSON node whose fields are all still unproven. Reading a field off a
  * non-object (string, number, null) yields `undefined` at runtime, so every
- * field read below is safe and the `typeof` checks on the values do the real
- * validating — no structural guard needed.
+ * field read below is safe.
  *
- * ponytail: this is hand-rolled validation, not a schema. It stays honest only
- * because `ConductorConfig` is small; the upgrade path when it grows is to
- * parse with zod/valibot at this one boundary and delete `validate` below.
+ * ponytail: this is no longer the validator — `ConfigSchema` in
+ * `config-schema.ts` owns every shape/type/enum/required-optional decision, and
+ * the normalisers below read already-validated values and apply only what zod
+ * cannot express.
  */
 type Raw = { readonly [key: string]: unknown };
 
 /** Derived from the data so a new `Caps` field cannot be silently ignored. */
 const CAP_KEYS = Object.keys(DEFAULT_CAPS) as (keyof Caps)[];
 
-/** Quoted for error messages, from the same data the guards below read. */
-const REPORT_SCOPE_LIST = quoteList(REPORT_SCOPES);
-const INTERRUPT_CATEGORY_LIST = quoteList(INTERRUPT_CATEGORIES);
-const DIGEST_CADENCE_LIST = quoteList(DIGEST_CADENCES);
-const AUTHORITY_HOLDER_LIST = quoteList(AUTHORITY_HOLDERS);
-const ORCHESTRATOR_MODE_LIST = quoteList(ORCHESTRATOR_MODES);
-const RELEASE_SHAPE_LIST = quoteList(RELEASE_SHAPES);
-const LEGACY_RELEASE_POLICY_LIST = quoteList(LEGACY_RELEASE_POLICIES);
-const BASE_FRESHNESS_LIST = quoteList(BASE_FRESHNESS);
-const DRAFT_POLICY_LIST = quoteList(DRAFT_POLICIES);
-const BEHIND_BASE_ACTION_LIST = quoteList(BEHIND_BASE_ACTIONS);
-const RELEASE_REQUIREMENT_LIST = quoteList(RELEASE_REQUIREMENTS);
-
 /** `owner/repo`, the only tracker spelling `gh` accepts without a host. */
 const REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
 
@@ -142,7 +148,7 @@ export function loadConfig(): ConductorConfig {
   const path = configPath();
 
   if (!existsSync(path)) {
-    throw new Error(`No conductor config at ${path} — run /conductor setup to create one.`);
+    throw new Error(`No conductor config at ${path} — run \`omp-conductor setup\` to create one.`);
   }
 
   let raw: string;
@@ -182,9 +188,23 @@ export function saveConfig(c: ConductorConfig): void {
  * rewrote a live fleet's config into a dialect the previous release rejected.
  */
 export function writeConfigFile(c: unknown): void {
-  writeConfigRaw(`${JSON.stringify(c, null, 2)}\n`);
+  const withSchema =
+    typeof c === "object" && c !== null && !Array.isArray(c) && "version" in c && !("$schema" in c)
+      ? { ...(c as Record<string, unknown>), $schema: SCHEMA_URI }
+      : c;
+  writeConfigRaw(`${JSON.stringify(withSchema, null, 2)}\n`);
 }
 
+/**
+ * Where the shipped `config.schema.json` is installed, referenced from the top
+ * of every config `saveConfig` writes. It is derived from this module's own
+ * location (`import.meta.dir` is the installed package's `src/`), so the URI
+ * points at the actual installed copy rather than a dangling relative path —
+ * the config lives at `$OMP_CONDUCTOR_HOME/config.json`, which has no
+ * `node_modules` beside it.
+ */
+const SCHEMA_URI = join(dirname(import.meta.dir), "schema", "config.schema.json");
+
 /**
  * Atomic write of exact bytes.
  *
@@ -349,20 +369,621 @@ export function findProject(c: ConductorConfig, name?: string): ProjectConfig {
 }
 
 // ---------------------------------------------------------------------------
-// validation / normalisation
+// load boundary: zod parse + residue normalisation
 // ---------------------------------------------------------------------------
 
+/**
+ * Validates and normalises an on-disk config into a `ConductorConfig`.
+ *
+ * Per-field shape, type, enum, numeric-bound and required/optional validity is
+ * enforced entirely by `ConfigSchema` (zod) at this boundary — the hand-rolled
+ * field guards that used to live below are gone. What zod cannot express is
+ * done here as a thin residue layer, in today's exact wording:
+ *
+ * - cross-field coherence (reporting scope-vs-explicit, digest/availability
+ *   times, `start !== end`);
+ * - the version-keyed cap migration (v1 drops a retired key, v2 rejects it);
+ * - the clone-URL credential rejection; and
+ * - legacy-key / path normalisation (defaults, presets, `~` and default roots).
+ */
 function validate(parsed: unknown, path: string): ConductorConfig {
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`Conductor config at ${path} must be a JSON object — run /conductor setup to recreate it.`);
+    throw new Error(`Conductor config at ${path} must be a JSON object — run \`omp-conductor setup\` to recreate it.`);
+  }
+  const shape = ConfigSchema.safeParse(parsed);
+  if (!shape.success) {
+    // Shape faults from zod, plus the cross-field/credential complaints that
+    // only the residue layer can voice. For the nested objects below, zod stops
+    // collecting member faults once any sibling fails, so zod's issues for
+    // those objects are folded into a single accumulated pass that reports
+    // every faulty member (matching the envelope's "whole list" promise).
+    const expanded = shape.error.issues.flatMap(expandIssue);
+    const problems = [
+      ...expanded.filter((issue) => !inAccumulatedObject(issue.path)).map((issue) => issueToProblem(issue, parsed)),
+      ...crossFieldProblems(parsed),
+      ...nestedObjectProblems(parsed),
+    ];
+    throw new Error(problemEnvelope(path, problems));
+  }
+  return finalize(shape.data as unknown, path);
+}
+
+/**
+ * True when a zod issue path lives inside one of the objects whose member
+ * faults must all be reported together (availability, digest, caps, authority,
+ * per-repo gates). zod skips those once a sibling fails, so the failure path
+ * drops zod's issues for them and lets {@link nestedObjectProblems} own them.
+ */
+function inAccumulatedObject(path: readonly PropertyKey[]): boolean {
+  if (path[0] !== "projects" || typeof path[1] !== "number") return false;
+  const rel = path.slice(2).map(String);
+  if (rel[0] === "caps" || rel[0] === "authority") return true;
+  if (rel[0] === "reporting" && (rel[1] === "digest" || rel[1] === "availability")) return true;
+  if (rel[0] === "routing" && rel[1] === "repos" && rel[3] === "gates") return true;
+  return false;
+}
+
+/**
+ * Reports every faulty member of the nested objects in one pass, in today's
+ * wording, so an operator hears the whole list the first time. zod cannot do
+ * this (it abandons an object's remaining members once one fails), so the
+ * failure path substitutes this for zod's issues inside those objects.
+ * Cross-field items (scope-vs-explicit, at-only-with-daily, timezone match,
+ * start != end, clone URLs) are {@link crossFieldProblems}' job, not this one's.
+ */
+function nestedObjectProblems(parsed: unknown): string[] {
+  const problems: string[] = [];
+  const root = parsed as Raw | undefined;
+  const list = root?.["projects"];
+  if (!Array.isArray(list)) return problems;
+  const legacyCaps = root?.["version"] === 1;
+
+  list.forEach((p: unknown, i) => {
+    const proj = p as Raw;
+    if (typeof proj !== "object" || proj === null) return;
+    const name = proj["name"];
+    const label = typeof name === "string" && name.trim() !== "" ? `project "${name}"` : `projects[${i}]`;
+
+    // availability — every member, even when days already failed.
+    const reporting = typeof proj["reporting"] === "object" && proj["reporting"] !== null && !Array.isArray(proj["reporting"])
+      ? (proj["reporting"] as Raw)
+      : undefined;
+    const availability = reporting !== undefined && typeof reporting["availability"] === "object" && reporting["availability"] !== null && !Array.isArray(reporting["availability"])
+      ? (reporting["availability"] as Raw)
+      : undefined;
+    if (availability !== undefined) checkAvailability(availability, label, problems);
+
+    // digest — every member even when cadence already failed.
+    if (reporting !== undefined && typeof reporting["digest"] === "object" && reporting["digest"] !== null && !Array.isArray(reporting["digest"])) {
+      checkDigest(reporting["digest"] as Raw, label, problems);
+    }
+
+    // authority
+    const authority = proj["authority"];
+    if (typeof authority === "object" && authority !== null && !Array.isArray(authority)) {
+      checkAuthority(authority as Raw, label, problems);
+    }
+
+    // caps
+    reconcileCaps(proj["caps"], `${label}: caps`, problems, legacyCaps);
+
+    // per-repo gates (two bad gates must both surface)
+    const routing = typeof proj["routing"] === "object" && proj["routing"] !== null && !Array.isArray(proj["routing"])
+      ? (proj["routing"] as Raw)
+      : undefined;
+    const repos = routing !== undefined && typeof routing["repos"] === "object" && routing["repos"] !== null && !Array.isArray(routing["repos"])
+      ? (routing["repos"] as Record<string, unknown>)
+      : undefined;
+    if (repos !== undefined) {
+      for (const [key, entry] of Object.entries(repos)) {
+        const e = entry as Raw | undefined;
+        if (e === undefined || typeof e !== "object") continue;
+        const gates = e["gates"];
+        if (gates === undefined) continue;
+        const base = `${label}: routing.repos.${key}`;
+        if (!Array.isArray(gates)) {
+          problems.push(`${base}.gates must be an array of { cmd, cwd }`);
+          continue;
+        }
+        gates.forEach((g: unknown, gi: number) => {
+          const cmd = (g as Raw | undefined)?.["cmd"];
+          if (typeof cmd !== "string" || cmd.trim() === "") {
+            problems.push(`${base}.gates[${gi}] must be { cmd, cwd } with a non-empty cmd`);
+          }
+        });
+      }
+    }
+  });
+  return problems;
+}
+
+function checkAvailability(a: Raw, label: string, problems: string[]): void {
+  if (typeof a["timezone"] !== "string" || a["timezone"].trim() === "") {
+    problems.push(`${label}: reporting.availability.timezone must be a known IANA timezone`);
+  } else {
+    try {
+      new Intl.DateTimeFormat("en-GB", { timeZone: a["timezone"] });
+    } catch {
+      problems.push(`${label}: reporting.availability.timezone is not a known IANA timezone`);
+    }
+  }
+  const days = a["days"];
+  if (!Array.isArray(days) || days.length === 0) {
+    problems.push(`${label}: reporting.availability.days must be a non-empty array of ${WEEKDAY_LIST}`);
+  } else {
+    for (const d of days) {
+      if (typeof d !== "string" || !(WEEKDAYS as readonly string[]).includes(d)) {
+        problems.push(`${label}: reporting.availability.days has unknown day ${JSON.stringify(d)} — one of ${WEEKDAY_LIST}`);
+      }
+    }
+  }
+  if (typeof a["start"] !== "string" || !DIGEST_AT.test(a["start"])) {
+    problems.push(`${label}: reporting.availability.start must be a 24h HH:MM time`);
+  }
+  if (typeof a["end"] !== "string" || !DIGEST_AT.test(a["end"])) {
+    problems.push(`${label}: reporting.availability.end must be a 24h HH:MM time`);
+  }
+  if (!Array.isArray(a["bypass"])) {
+    problems.push(`${label}: reporting.availability.bypass must be an array of ${INTERRUPT_CATEGORY_LIST} (empty means none)`);
+  } else {
+    for (const b of a["bypass"]) {
+      if (typeof b !== "string" || !(INTERRUPT_CATEGORIES as readonly string[]).includes(b)) {
+        problems.push(`${label}: reporting.availability.bypass has unknown category ${JSON.stringify(b)} — one of ${INTERRUPT_CATEGORY_LIST}`);
+      }
+    }
+  }
+}
+
+function checkDigest(d: Raw, label: string, problems: string[]): void {
+  if (typeof d["cadence"] !== "string" || !(DIGEST_CADENCES as readonly string[]).includes(d["cadence"])) {
+    problems.push(`${label}: reporting.digest.cadence must be ${DIGEST_CADENCE_LIST}`);
+  }
+  if (d["at"] !== undefined && (typeof d["at"] !== "string" || !DIGEST_AT.test(d["at"]))) {
+    problems.push(`${label}: reporting.digest.at must be a 24h HH:MM time`);
+  }
+  if (d["timezone"] !== undefined) {
+    if (typeof d["timezone"] !== "string") {
+      problems.push(`${label}: reporting.digest.timezone must be a string`);
+    } else {
+      try {
+        new Intl.DateTimeFormat("en-GB", { timeZone: d["timezone"] });
+      } catch {
+        problems.push(`${label}: reporting.digest.timezone is not a known IANA timezone`);
+      }
+    }
+  }
+}
+
+function checkAuthority(a: Raw, label: string, problems: string[]): void {
+  const merge = a["merge"];
+  const release = a["release"];
+  if (merge !== undefined && typeof merge === "string" && !(AUTHORITY_HOLDERS as readonly string[]).includes(merge)) {
+    problems.push(`${label}: authority.merge must be ${AUTHORITY_HOLDER_LIST}, found ${JSON.stringify(merge)}`);
+  }
+  if (release !== undefined && typeof release === "string" && !(AUTHORITY_HOLDERS as readonly string[]).includes(release)) {
+    problems.push(`${label}: authority.release must be ${AUTHORITY_HOLDER_LIST}, found ${JSON.stringify(release)}`);
+  }
+  const unknown = Object.keys(a).filter((k) => k !== "merge" && k !== "release");
+  if (unknown.length > 0) problems.push(`${label}: authority has unknown key(s): ${unknown.join(", ")}`);
+}
+
+/**
+ * The cross-field and credential complaints zod cannot express, stated against
+ * the raw document so they are reported even when a sibling key fails its
+ * shape. On the success path the same checks run inside `finalize`; this is the
+ * failure-path twin, keeping the multi-problem envelope cumulative.
+ */
+function crossFieldProblems(parsed: unknown): string[] {
+  const problems: string[] = [];
+  const list = (parsed as Raw | undefined)?.["projects"];
+  if (!Array.isArray(list)) return problems;
+  list.forEach((p: unknown, i) => {
+    const proj = p as Raw;
+    if (typeof proj !== "object" || proj === null) return;
+    const name = proj["name"];
+    const label = typeof name === "string" && name.trim() !== "" ? `project "${name}"` : `projects[${i}]`;
+
+    const reporting = proj["reporting"];
+    if (typeof reporting === "object" && reporting !== null && !Array.isArray(reporting)) {
+      const r = reporting as Raw;
+      const hasScope = r["scope"] !== undefined;
+      const hasExplicit =
+        r["interruptOn"] !== undefined || r["digest"] !== undefined || r["availability"] !== undefined;
+      if (hasScope && hasExplicit) {
+        problems.push(
+          `${label}: reporting.scope is a preset — remove it when configuring interruptOn/digest/availability explicitly`,
+        );
+      }
+      const digest = typeof r["digest"] === "object" && r["digest"] !== null && !Array.isArray(r["digest"])
+        ? (r["digest"] as Raw)
+        : undefined;
+      if (digest !== undefined && digest["cadence"] !== undefined && digest["cadence"] !== "daily") {
+        if (digest["at"] !== undefined) problems.push(`${label}: reporting.digest.at is only valid with cadence "daily"`);
+        if (digest["timezone"] !== undefined) {
+          problems.push(`${label}: reporting.digest.timezone is only valid with cadence "daily"`);
+        }
+      }
+      const availability = typeof r["availability"] === "object" && r["availability"] !== null && !Array.isArray(r["availability"])
+        ? (r["availability"] as Raw)
+        : undefined;
+      if (availability !== undefined) {
+        const start = availability["start"];
+        const end = availability["end"];
+        if (typeof start === "string" && typeof end === "string" && start === end) {
+          problems.push(`${label}: reporting.availability.start and end must differ`);
+        }
+        if (
+          digest !== undefined &&
+          digest["cadence"] === "daily" &&
+          digest["timezone"] !== undefined &&
+          availability["timezone"] !== undefined &&
+          digest["timezone"] !== availability["timezone"]
+        ) {
+          problems.push(`${label}: reporting.digest.timezone must match reporting.availability.timezone`);
+        }
+      }
+    }
+
+    const routing = proj["routing"];
+    const repos = typeof routing === "object" && routing !== null && !Array.isArray(routing)
+      ? (routing as Raw)["repos"]
+      : undefined;
+    if (typeof repos === "object" && repos !== null && !Array.isArray(repos)) {
+      for (const [key, entry] of Object.entries(repos as Record<string, unknown>)) {
+        const cloneUrl = (entry as Raw | undefined)?.["cloneUrl"];
+        if (typeof cloneUrl === "string") {
+          const credential = cloneUrlCredentialProblem(cloneUrl);
+          if (credential !== undefined) {
+            problems.push(
+              `${label}: routing.repos.${key}.cloneUrl ${credential}. Use an SSH URL, or an https URL ` +
+                `backed by the daemon's own credential helper.`,
+            );
+          }
+        }
+      }
+    }
+  });
+  return problems;
+}
+
+/**
+ * Expands a zod `invalid_union` into its most specific branch — the one with
+ * the deepest path — so `releasePolicy: { deploy: "worker" }` reports the
+ * offending holder (and its field) rather than a bare "Invalid input". The
+ * legacy-literal branch of the same union always errors for an object and is
+ * the one we discard.
+ */
+type LooseIssue = {
+  path: PropertyKey[];
+  code: string;
+  message: string;
+  keys?: readonly string[];
+  values?: readonly unknown[];
+  received?: unknown;
+};
+
+function expandIssue(issue: unknown): LooseIssue[] {
+  const raw = issue as { code?: string; path?: PropertyKey[]; errors?: unknown; message?: string };
+  const base = { ...(issue as object) } as LooseIssue;
+  if (raw.code !== "invalid_union" || !Array.isArray(raw.errors)) {
+    return [{ ...base, path: raw.path ?? [], code: raw.code ?? "invalid_type", message: raw.message ?? "Invalid input" }];
+  }
+  let best: { path?: PropertyKey[]; code?: string; message?: string } | undefined;
+  let bestDepth = -1;
+  for (const branch of raw.errors) {
+    for (const e of Array.isArray(branch) ? branch : [branch]) {
+      const er = e as { path?: PropertyKey[] };
+      const depth = (raw.path?.length ?? 0) + (er.path?.length ?? 0);
+      if (depth > bestDepth) {
+        bestDepth = depth;
+        best = { path: er.path, code: (e as { code?: string }).code, message: (e as { message?: string }).message };
+      }
+    }
+  }
+  if (best === undefined) {
+    return [{ ...base, path: raw.path ?? [], code: raw.code, message: raw.message ?? "Invalid input" }];
+  }
+  return [
+    { ...base, path: [...(raw.path ?? []), ...(best.path ?? [])], code: best.code ?? "invalid_type", message: best.message ?? "Invalid input" },
+  ];
+}
+
+function problemEnvelope(path: string, problems: string[]): string {
+  return (
+    `Invalid conductor config at ${path}:\n${problems.map((p) => `  - ${p}`).join("\n")}\n` +
+    `Fix the file or run \`omp-conductor setup\`.`
+  );
+}
+
+/** The operator-facing label of a project from its issue path, or undefined. */
+function projectLabel(root: unknown, index: number): string | undefined {
+  const list = (root as Raw | undefined)?.["projects"];
+  if (!Array.isArray(list)) return undefined;
+  const p = list[index] as Raw | undefined;
+  const name = p?.["name"];
+  return typeof name === "string" && name.trim() !== "" ? `project "${name}"` : `projects[${index}]`;
+}
+
+/** Joins zod's issue path segments into the dotted config path an operator sees. */
+function dottedPath(segments: readonly PropertyKey[]): string {
+  return segments
+    .map((seg) => (typeof seg === "number" ? `[${seg}]` : `.${String(seg)}`))
+    .join("")
+    .replace(/^\./, "");
+}
+
+/** Reads a value out of the original parsed document at a zod issue path. */
+function rawAt(root: unknown, path: readonly PropertyKey[]): unknown {
+  let cur: unknown = root;
+  for (const seg of path) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[String(seg)];
+  }
+  return cur;
+}
+
+const FOUND = (v: unknown): string => (v === "" ? '""' : JSON.stringify(v));
+
+/**
+ * Renders a zod issue the way the loader has always worded faults — the dotted
+ * config path, the exact alternatives, the offending value — so moving the
+ * validation to zod changes how a problem is *found*, never how it reads.
+ */
+function issueToProblem(issue: {
+  path: readonly PropertyKey[];
+  code: string;
+  message: string;
+  keys?: readonly string[];
+  values?: readonly unknown[];
+}, root: unknown): string {
+  const path = issue.path;
+
+  // Top-level version / projects faults carry no project label.
+  if (path.length === 1 && (path[0] === "version" || path[0] === "projects")) {
+    if (path[0] === "version") {
+      return `"version" must be 1 or 2, found ${JSON.stringify(rawAt(root, path))} — this config was written by a different conductor`;
+    }
+    return `"projects" must be a non-empty array — the dispatcher has nothing to service otherwise`;
+  }
+
+  if (path[0] === "projects" && typeof path[1] === "number") {
+    const rel = path.slice(2);
+    // The project's own name is invalid precisely when *its* field fails, and
+    // that fault has always been voiced as `projects[N].name …`.
+    if (rel.length === 1 && rel[0] === "name") {
+      return `projects[${path[1]}].name must be a non-empty string`;
+    }
+    const label = projectLabel(root, path[1]) ?? `projects[${path[1]}]`;
+    return `${label}: ${clauseFor(rel, issue, root, path)}`;
+  }
+
+  return clauseFor(path, issue, root, path);
+}
+
+/** The clause after the project label — `<dotted-path> <finding>`. */
+function clauseFor(rel: readonly PropertyKey[], issue: {
+  code: string;
+  message: string;
+  keys?: readonly string[];
+  values?: readonly unknown[];
+}, root: unknown, fullPath: readonly PropertyKey[]): string {
+  const pathStr = dottedPath(rel);
+  const found = (at?: readonly PropertyKey[]): string => FOUND(rawAt(root, at ?? fullPath));
+
+  if (rel.length === 1 && rel[0] === "releasePolicy") {
+    return `releasePolicy must be an object mapping release shapes (${RELEASE_SHAPE_LIST}) to ${AUTHORITY_HOLDER_LIST}, or the legacy ${LEGACY_RELEASE_POLICY_LIST}, found ${found()}`;
+  }
+  if (rel[0] === "routing" && (rel.length === 1 || (rel.length === 2 && rel[1] === "repos"))) {
+    return `routing.repos needs at least one repo entry, or no issue can be routed`;
+  }
+  if (rel.length >= 2 && rel[rel.length - 1] === "dir" && rel.includes("migrations")) {
+    return `${pathStr} must be a non-empty string`;
+  }
+  const NAME_LIST_FIELDS = new Set(["requiredChecks", "artefacts", "environments"]);
+  // A whole name-list field of the wrong shape.
+  if (
+    rel.length >= 2 &&
+    NAME_LIST_FIELDS.has(String(rel[rel.length - 1])) &&
+    (rel[rel.length - 2] === "merge" || rel[rel.length - 2] === "release")
+  ) {
+    return `${pathStr} must be an array of non-empty strings`;
+  }
+  // One malformed element of a name-list.
+  if (
+    typeof rel[rel.length - 1] === "number" &&
+    rel.length >= 3 &&
+    NAME_LIST_FIELDS.has(String(rel[rel.length - 2]))
+  ) {
+    return `${pathStr} must be a non-empty string, found ${found()}`;
+  }
+
+  // Schema-authored findings (`.superRefine` / `.message` carried on the node
+  // with a `custom` code) assemble as `<dotted-path> <finding>`.
+  if (issue.code === "custom") return `${pathStr} ${issue.message}`;
+
+  // Presence of an object-looking field where a singular scalar belongs, or a
+  // whole object/array of the wrong type — the "must be an object" family.
+  if (issue.code === "invalid_type") {
+    const relStr = (rel[0] as string) ?? "";
+    if (rel.length === 1 && relStr === "reporting") {
+      return `reporting must be an object with a "scope" preset or explicit "interruptOn"/"digest"`;
+    }
+    if (rel.length === 2 && relStr === "reporting" && rel[1] === "digest") {
+      return `reporting.digest must be an object with a "cadence" of ${DIGEST_CADENCE_LIST}`;
+    }
+    if (rel.length === 2 && relStr === "reporting" && rel[1] === "availability") {
+      return `reporting.availability must be an object`;
+    }
+    if (rel.length === 1 && relStr === "escalation") return `escalation must be an object`;
+    if (rel.length === 1 && relStr === "authority") {
+      return `authority must be an object with "merge" and "release" of ${AUTHORITY_HOLDER_LIST}`;
+    }
+    if (rel.length === 1 && relStr === "policy") {
+      return `policy must be an object with "merge" and "release" sections`;
+    }
+    if (rel.length === 2 && relStr === "policy") return `${pathStr} must be an object`;
+    if (rel.length === 1 && relStr === "caps") return `caps must be an object`;
+    if (rel.length === 2 && relStr === "caps" && rel[1] === "planUsage") {
+      return `caps.planUsage must be { windowId, maxUsedFraction } or null (unmetered), found ${found()}`;
+    }
+    if (rel.length === 1 && relStr === "releasePolicy") {
+      return `releasePolicy must be an object mapping release shapes (${RELEASE_SHAPE_LIST}) to ${AUTHORITY_HOLDER_LIST}, or the legacy ${LEGACY_RELEASE_POLICY_LIST}, found ${found()}`;
+    }
+    if (rel.length === 3 && rel[0] === "routing" && rel[1] === "repos") {
+      return `routing.repos needs at least one repo entry, or no issue can be routed`;
+    }
+    if (rel.length === 1 && relStr === "tracker") {
+      return `tracker.repo must look like "owner/repo", found undefined`;
+    }
+    // A numeric cap field of the wrong shape (zod union over number|null).
+    if (rel.length === 2 && relStr === "caps") {
+      return capProblem(rel[1] as string, found());
+    }
+    // A missing/wrong name-list element.
+    if (typeof rel[rel.length - 1] === "number") {
+      return `${pathStr} must be a non-empty string, found ${found()}`;
+    }
+    // Every remaining require/missing-property case is authored here; never
+    // fall through to zod's own rendering.
+    if (rel[0] === "tracker") return `tracker.repo must look like "owner/repo", found undefined`;
+    if (pathStr === "reporting.digest.cadence") return `reporting.digest.cadence must be ${DIGEST_CADENCE_LIST}`;
+    if (pathStr === "reporting.digest.at") return `reporting.digest.at must be a 24h HH:MM time`;
+    if (pathStr === "reporting.digest.timezone") return `reporting.digest.timezone must be a string`;
+    if (pathStr === "reporting.availability.timezone") return `reporting.availability.timezone must be a known IANA timezone`;
+    if (pathStr === "reporting.availability.start" || pathStr === "reporting.availability.end") {
+      return `${pathStr} must be a 24h HH:MM time`;
+    }
+    if (pathStr === "reporting.availability.days") {
+      return `reporting.availability.days must be a non-empty array of ${WEEKDAY_LIST}`;
+    }
+    if (pathStr === "reporting.availability.bypass") {
+      return `reporting.availability.bypass must be an array of ${INTERRUPT_CATEGORY_LIST} (empty means none)`;
+    }
+    if (pathStr === "reporting.interruptOn") return `reporting.interruptOn must name at least one category`;
+    if (rel.length >= 2 && String(rel[rel.length - 1]).endsWith("graphProject")) {
+      return `${pathStr} must be a non-empty absolute path, found ${found()}`;
+    }
+    if (rel.length >= 2 && String(rel[rel.length - 1]) === "gates") return `${pathStr} must be an array of { cmd, cwd }`;
+    if (rel.length === 2 && rel[0] === "caps") return capProblem(rel[1] as string, found());
+    return `${pathStr} is invalid`;
+  }
+
+  if (issue.code === "unrecognized_keys") {
+    const keys = (issue.keys ?? []).join(", ");
+    if (pathStr === "policy") return `policy has unknown key(s): ${keys} — expected "merge" or "release"`;
+    if (pathStr === "policy.merge") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_MERGE_KEYS}`;
+    if (pathStr === "policy.release") return `${pathStr} has unknown key(s): ${keys} — expected ${POLICY_RELEASE_KEYS}`;
+    if (pathStr === "caps.planUsage") {
+      return `caps.planUsage has unknown key(s): ${keys} — expected windowId and maxUsedFraction`;
+    }
+    if (pathStr === "releasePolicy") {
+      return `releasePolicy has unknown release shape(s): ${keys} — expected ${RELEASE_SHAPE_LIST}`;
+    }
+    return `${pathStr} has unknown key(s): ${keys}`;
+  }
+
+  // Enum membership (invalid_value). The wording depends on the field.
+  if (issue.code === "invalid_value") {
+    const tail = rel[rel.length - 1];
+    const parent = dottedPath(rel.slice(0, rel.length - 1));
+    // Array-element vocabularies stated with their own phrasing.
+    if (parent === "reporting.interruptOn") {
+      return `reporting.interruptOn has unknown category ${found()} — one of ${INTERRUPT_CATEGORY_LIST}`;
+    }
+    if (parent === "reporting.availability.bypass") {
+      return `reporting.availability.bypass has unknown category ${found()} — one of ${INTERRUPT_CATEGORY_LIST}`;
+    }
+    if (parent === "reporting.availability.days") {
+      return `reporting.availability.days has unknown day ${found()} — one of ${WEEKDAY_LIST}`;
+    }
+    if (parent === "policy.release.requires") {
+      return `${pathStr} must be ${RELEASE_REQUIREMENT_LIST}, found ${found()}`;
+    }
+    if (rel.length >= 2 && rel[0] === "releasePolicy") {
+      return `releasePolicy.${String(tail)} must be ${AUTHORITY_HOLDER_LIST}, found ${found()}`;
+    }
+    if (pathStr === "tracker.kind") return `tracker.kind must be "github", found ${found()}`;
+    if (pathStr === "reporting.scope" || pathStr === "reporting.scopePreset") {
+      return `${pathStr} must be ${REPORT_SCOPE_LIST}, found ${found()}`;
+    }
+    if (pathStr === "reporting.digest.cadence") return `${pathStr} must be ${DIGEST_CADENCE_LIST}, found ${found()}`;
+    if (pathStr === "escalation.orchestrator") return `${pathStr} must be ${ORCHESTRATOR_MODE_LIST}, found ${found()}`;
+    if (pathStr === "authority.merge" || pathStr === "authority.release") {
+      return `${pathStr} must be ${AUTHORITY_HOLDER_LIST}, found ${found()}`;
+    }
+    if (pathStr === "policy.merge.baseFreshness") return `${pathStr} must be ${BASE_FRESHNESS_LIST}, found ${found()}`;
+    if (pathStr === "policy.merge.drafts") return `${pathStr} must be ${DRAFT_POLICY_LIST}, found ${found()}`;
+    if (pathStr === "policy.merge.whenBehindBase") return `${pathStr} must be ${BEHIND_BASE_ACTION_LIST}, found ${found()}`;
+    const values = (issue.values ?? []).map(String);
+    return `${pathStr} must be ${quoteList(values)}, found ${found()}`;
+  }
+
+  // Regex / custom-message failures carry the finding in issue.message.
+  if (issue.code === "too_small") {
+    // Empty array (reporting.interruptOn, availability.days) has its own line.
+    if (parentOf(rel) === "reporting.interruptOn") return `reporting.interruptOn must name at least one category`;
+    if (pathStr === "reporting.availability.days") return `reporting.availability.days must be a non-empty array of ${WEEKDAY_LIST}`;
+    if (pathStr === "reporting.availability.timezone") return `reporting.availability.timezone must be a known IANA timezone`;
+    if (pathStr === "routing.repos" ) return `routing.repos needs at least one repo entry, or no issue can be routed`;
+    if (cloneUrlPath(rel) ) return `${pathStr} must be a non-empty string`;
+    if (gatesCmdPath(rel)) return `${pathStr} must be { cmd, cwd } with a non-empty cmd`;
+    if (rel.length === 2 && rel[0] === "caps") return capProblem(rel[1] as string, found());
+    if (pathStr === "caps.planUsage.maxUsedFraction") {
+      return `caps.planUsage.maxUsedFraction must be a fraction between 0 and 1 (0.85 holds at 85% of the allowance), found ${found()}`;
+    }
+    return `${pathStr} ${finding(issue.message)}`;
+  }
+
+  if (issue.code === "too_big") {
+    if (rel.length === 2 && rel[0] === "caps") return capProblem(rel[1] as string, found());
+    if (pathStr === "caps.planUsage.maxUsedFraction") {
+      return `caps.planUsage.maxUsedFraction must be a fraction between 0 and 1 (0.85 holds at 85% of the allowance), found ${found()}`;
+    }
+    return `${pathStr} ${finding(issue.message)}`;
+  }
+
+  // invalid_format (the repo / HH:MM regexes) and anything else.
+  if (pathStr === "reporting.digest.at" || pathStr === "reporting.availability.start" || pathStr === "reporting.availability.end") {
+    return `${pathStr} must be a 24h HH:MM time`;
   }
-  const root = parsed as Raw;
+  if (pathStr === "tracker.repo") return `tracker.repo must look like "owner/repo", found ${found()}`;
+  return `${pathStr} ${finding(issue.message)}`;
+}
+
+/** zod's own phrasing, which must never reach an operator-facing problem line. */
+const LEAKY = /(Invalid input|expected |received |Unrecognized key|Too small|Too big)/;
+function finding(message: string): string {
+  return LEAKY.test(message) ? "is not valid" : message;
+}
+
+function parentOf(rel: readonly PropertyKey[]): string {
+  return dottedPath(rel.slice(0, rel.length - 1));
+}
+function cloneUrlPath(rel: readonly PropertyKey[]): boolean {
+  return rel.length >= 4 && rel[rel.length - 1] === "cloneUrl";
+}
+function gatesCmdPath(rel: readonly PropertyKey[]): boolean {
+  return rel.some((s, i) => s === "gates" && typeof rel[i + 1] === "number" && rel[rel.length - 1] === "cmd");
+}
+function capProblem(key: string, found: string): string {
+  return key === "dailySpendUsd"
+    ? `caps.dailySpendUsd must be a non-negative finite number or null (no cap), found ${found}`
+    : `caps.${key} must be a non-negative finite number, found ${found}`;
+}
+
+/** Quted fallback key lists for policy unknown-key errors. */
+const POLICY_MERGE_KEYS = quoteList(Object.keys(clonePolicy(DEFAULT_PROJECT_POLICY).merge));
+const POLICY_RELEASE_KEYS = quoteList(Object.keys(clonePolicy(DEFAULT_PROJECT_POLICY).release));
+
+// ---------------------------------------------------------------------------
+// residue: cross-field coherence, migrations, defaults, path expansion
+// ---------------------------------------------------------------------------
+
+function finalize(data: unknown, path: string): ConductorConfig {
+  const root = data as Raw;
   const problems: string[] = [];
 
   const version = root["version"];
-  // A v1 file predates the retirement of a cap key, so its caps are read
-  // leniently and the result is normalised up to v2. Any other version is a
-  // config this build cannot honestly claim to understand.
   const legacyCaps = version === 1;
   if (!READABLE_CONFIG_VERSIONS.some((v) => v === version)) {
     problems.push(
@@ -370,13 +991,12 @@ function validate(parsed: unknown, path: string): ConductorConfig {
     );
   }
 
-  const configuredDefaults = coerceCaps(root["defaults"], `"defaults"`, problems, legacyCaps);
+  const configuredDefaults = reconcileCaps(root["defaults"], `"defaults"`, problems, legacyCaps);
   const defaultWorkerMaxTurns = configuredDefaults.workerMaxTurns ?? DEFAULT_CAPS.workerMaxTurns;
   const defaults: Caps = {
     ...DEFAULT_CAPS,
     ...configuredDefaults,
-    workerMaxTurnsCeiling:
-      configuredDefaults.workerMaxTurnsCeiling ?? defaultWorkerMaxTurns * 2,
+    workerMaxTurnsCeiling: configuredDefaults.workerMaxTurnsCeiling ?? defaultWorkerMaxTurns * 2,
   };
 
   const rawProjects = root["projects"];
@@ -385,94 +1005,58 @@ function validate(parsed: unknown, path: string): ConductorConfig {
     problems.push(`"projects" must be a non-empty array — the dispatcher has nothing to service otherwise`);
   } else {
     rawProjects.forEach((p: unknown, i) => {
-      const project = normalizeProject(p, i, problems, legacyCaps);
+      const project = finalizeProject(p, i, problems, legacyCaps);
       if (project !== undefined) projects.push(project);
     });
   }
 
-  if (problems.length > 0) {
-    throw new Error(
-      `Invalid conductor config at ${path}:\n${problems.map((p) => `  - ${p}`).join("\n")}\n` +
-        `Fix the file or run /conductor setup.`,
-    );
-  }
-
-  // Always v2 out: a loaded v1 config is migrated in memory, and the next
-  // `saveConfig` is what persists the migration. `loadConfig` stays read-only.
+  if (problems.length > 0) throw new Error(problemEnvelope(path, problems));
   return { version: CONFIG_VERSION, defaults, projects };
 }
 
-/** Returns `undefined` when the project was too broken to shape; problems are appended. */
-function normalizeProject(
+function finalizeProject(
   parsed: unknown,
   index: number,
   problems: string[],
   legacyCaps: boolean,
 ): ProjectConfig | undefined {
   const at = `projects[${index}]`;
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${at} must be an object`);
-    return undefined;
-  }
-  const raw = parsed as Raw;
   const before = problems.length;
+  const p = parsed as Raw;
+
+  // zod guarantees name/repo/queueLabel/kind are present and well-formed.
+  const name = p["name"] as string;
+  const label = `project "${name}"`;
+  const trackerRepo = ((p["tracker"] as Raw | undefined)?.["repo"]) as string;
 
-  const rawName = raw["name"];
-  let name = "";
-  if (nonEmptyString(rawName)) name = rawName;
-  else problems.push(`${at}.name must be a non-empty string`);
-  const label = name === "" ? at : `project "${name}"`;
-
-  const tracker = raw["tracker"] as Raw | undefined;
-  const rawRepo = tracker?.["repo"];
-  let trackerRepo = "";
-  if (nonEmptyString(rawRepo) && REPO_RE.test(rawRepo)) trackerRepo = rawRepo;
-  else problems.push(`${label}: tracker.repo must look like "owner/repo", found ${JSON.stringify(rawRepo)}`);
-  const rawKind = tracker?.["kind"];
-  if (rawKind !== undefined && rawKind !== "github") {
-    problems.push(`${label}: tracker.kind must be "github", found ${JSON.stringify(rawKind)}`);
-  }
-
-  const rawQueueLabel = raw["queueLabel"];
-  let queueLabel = "";
-  if (nonEmptyString(rawQueueLabel)) queueLabel = rawQueueLabel;
-  else problems.push(`${label}: queueLabel must be a non-empty string — it is the human sign-off gate`);
-
-  // Tolerant like the other optional fields: an integer >= 1 is a grooming
-  // trigger, and anything else degrades to absent (the tick default) rather
-  // than invalidating the whole project.
-  const rawGroomBelow = raw["groomBelow"];
+  const rawGroomBelow = p["groomBelow"];
   const groomBelow =
     typeof rawGroomBelow === "number" && Number.isInteger(rawGroomBelow) && rawGroomBelow >= 1
       ? rawGroomBelow
       : undefined;
 
-  const routing = raw["routing"] as Raw | undefined;
-  const rawPrefix = routing?.["labelPrefix"];
+  const rawRouting = p["routing"] as Raw | undefined;
+  const rawPrefix = rawRouting?.["labelPrefix"];
   const labelPrefix = typeof rawPrefix === "string" ? rawPrefix : DEFAULT_LABEL_PREFIX;
-  const repos = normalizeRepos(routing?.["repos"], label, problems);
-
-  const stateLabels = raw["stateLabels"] as Raw | undefined;
-
-  const escalation = normalizeEscalation(raw["escalation"], label, problems);
-  const authority = normalizeAuthority(raw["authority"], label, problems);
-  const releasePolicy = normalizeReleasePolicy(raw["releasePolicy"], label, problems);
-  const policy = normalizeProjectPolicy(raw["policy"], label, problems);
-
-  const caps = coerceCaps(raw["caps"], `${label}: caps`, problems, legacyCaps);
-  const reporting = normalizeReporting(raw["reporting"], label, problems);
-  // A hint passed to the harness, not a budget guard: an unusable value is
-  // dropped rather than reported, and the session's own model-fallback notice
-  // (logged by `runWorker`) is what tells the operator the pattern missed.
-  const rawWorkerModel = raw["workerModel"];
-  const workerModel = nonEmptyString(rawWorkerModel) ? rawWorkerModel : undefined;
+  const repos = finalizeRepos(rawRouting?.["repos"], label, problems);
+
+  const stateLabels = p["stateLabels"] as Raw | undefined;
+  const escalation = finalizeEscalation(p["escalation"] as Raw | undefined);
+  const authority = finalizeAuthority(p["authority"] as Raw | undefined);
+  const releasePolicy = finalizeReleasePolicy(p["releasePolicy"], label, problems);
+  const policy = finalizePolicy(p["policy"], label, problems);
+  const caps = reconcileCaps(p["caps"], `${label}: caps`, problems, legacyCaps);
+  const reporting = finalizeReporting(p["reporting"], label, problems);
+  const rawWorkerModel = p["workerModel"];
+  const workerModel =
+    typeof rawWorkerModel === "string" && rawWorkerModel.trim() !== "" ? rawWorkerModel : undefined;
 
   if (problems.length > before) return undefined;
 
   return {
     name,
     tracker: { kind: "github", repo: trackerRepo },
-    queueLabel,
+    queueLabel: p["queueLabel"] as string,
     ...(groomBelow === undefined ? {} : { groomBelow }),
     stateLabels: {
       inProgress: pickString(stateLabels?.["inProgress"], DEFAULT_STATE_LABELS.inProgress),
@@ -487,508 +1071,137 @@ function normalizeProject(
     releasePolicy,
     policy,
     reporting,
-    workspaceRoot: expandHome(pickString(raw["workspaceRoot"], defaultWorkspaceRoot())),
-    mirrorRoot: expandHome(pickString(raw["mirrorRoot"], defaultMirrorRoot())),
+    workspaceRoot: expandHome(pickString(p["workspaceRoot"], defaultWorkspaceRoot())),
+    mirrorRoot: expandHome(pickString(p["mirrorRoot"], defaultMirrorRoot())),
   };
 }
 
-/**
- * Reporting scope decides whether the orchestrator speaks up or stays quiet, so
- * a typo is rejected rather than folded to the default: a misspelt `"materal"`
- * that silently resolved to `"material"` would read as configured on the day the
- * operator meant to turn the volume down, and the config would keep lying.
- */
-/** The legacy `reporting.scope` presets, materialised as explicit policies.
- *  Kept separate from {@link DEFAULT_REPORT_POLICY} (the "no key on disk"
- *  default, which must stay `material`): each preset records `scopePreset` so
- *  the tick prompt can keep saying the exact legacy words (#229). Exported so
- *  the setup wizard and the config validator agree on one mapping. */
-export const SCOPE_PRESETS: Record<ReportScope, ReportingPolicy> = {
-  material: {
-    interruptOn: [...INTERRUPT_CATEGORIES],
-    digest: { cadence: "per-tick" },
-    scopePreset: "material",
-  },
-  decisions: {
-    interruptOn: ["tier2", "decision-needed", "fleet-stopped"],
-    digest: { cadence: "per-tick" },
-    scopePreset: "decisions",
-  },
-  escalations: {
-    interruptOn: ["tier2", "fleet-stopped"],
-    digest: { cadence: "daily" },
-    scopePreset: "escalations",
-  },
-};
-
-function defaultReporting(): ReportingPolicy {
-  return { ...DEFAULT_REPORT_POLICY, interruptOn: [...DEFAULT_REPORT_POLICY.interruptOn] };
+function finalizeEscalation(parsed: Raw | undefined): ProjectConfig["escalation"] {
+  if (parsed === undefined) {
+    return { fallbackToIssueComment: true, orchestrator: "embedded" };
+  }
+  const escalation = {
+    fallbackToIssueComment: parsed["fallbackToIssueComment"] !== false,
+    orchestrator: (parsed["orchestrator"] as ProjectConfig["escalation"]["orchestrator"]) ?? "embedded",
+  } as ProjectConfig["escalation"];
+  const chatId = parsed["telegramChatId"];
+  if (typeof chatId === "string" && chatId.trim() !== "") escalation.telegramChatId = chatId;
+  // Admit a finite integer topic id; numeric strings that parse cleanly count.
+  // Non-integers are omitted rather than rejected so a hand-edit never bricks load.
+  const rawTopic = parsed["telegramTopicId"];
+  if (typeof rawTopic === "number") {
+    if (Number.isFinite(rawTopic) && Number.isSafeInteger(rawTopic)) {
+      escalation.telegramTopicId = rawTopic;
+    }
+  } else if (typeof rawTopic === "string") {
+    const trimmed = rawTopic.trim();
+    if (trimmed !== "") {
+      const n = Number(trimmed);
+      if (Number.isFinite(n) && Number.isSafeInteger(n) && String(n) === trimmed) {
+        escalation.telegramTopicId = n;
+      }
+    }
+  }
+  return escalation;
 }
 
-/** The 24-hour `HH:MM` shape `digest.at` must take. */
-const DIGEST_AT = /^([01]\d|2[0-3]):[0-5]\d$/;
+function finalizeAuthority(parsed: Raw | undefined): ProjectConfig["authority"] {
+  if (parsed === undefined) return { ...DEFAULT_AUTHORITY };
+  return {
+    merge: (parsed["merge"] as ProjectConfig["authority"]["merge"]) ?? DEFAULT_AUTHORITY.merge,
+    release: (parsed["release"] as ProjectConfig["authority"]["release"]) ?? DEFAULT_AUTHORITY.release,
+  };
+}
 
-/**
- * The reporting policy: a legacy `scope` preset, or the explicit
- * `interruptOn` + `digest` form. The two forms are mutually exclusive — a
- * preset IS a policy, so configuring alongside it says one thing and means
- * another (#229).
- */
-function normalizeReporting(parsed: unknown, label: string, problems: string[]): ReportingPolicy {
-  if (parsed === undefined) return defaultReporting();
+function finalizeReleasePolicy(parsed: unknown, label: string, problems: string[]): ResolvedGrants {
+  if (parsed === undefined || parsed === "none") return { ...DENIED_RELEASE_GRANTS };
+  if (parsed === "operator-brief") return { ...OPERATOR_BRIEF_GRANTS };
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${label}: reporting must be an object with a "scope" preset or explicit "interruptOn"/"digest"`);
-    return defaultReporting();
+    problems.push(
+      `${label}: releasePolicy must be an object mapping release shapes (${RELEASE_SHAPE_LIST}) to ` +
+        `${AUTHORITY_HOLDER_LIST}, or the legacy ${LEGACY_RELEASE_POLICY_LIST}, found ${JSON.stringify(parsed)}`,
+    );
+    return { ...DENIED_RELEASE_GRANTS };
   }
   const raw = parsed as Raw;
-  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 unknownKeys = keys.filter((k) => !known.includes(k));
+  const unknownKeys = Object.keys(raw).filter((k) => !Object.hasOwn(DENIED_RELEASE_GRANTS, 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");
-  if (hasScope && hasExplicit) {
-    problems.push(`${label}: reporting.scope is a preset — remove it when configuring interruptOn/digest explicitly`);
-    return defaultReporting();
-  }
-  if (hasScope || (!hasExplicit && keys.length === 0)) {
-    const scope = pickLiteral(
-      raw["scope"],
-      REPORT_SCOPES,
-      DEFAULT_REPORT_SCOPE,
-      `${label}: reporting.scope`,
-      REPORT_SCOPE_LIST,
-      problems,
+    problems.push(
+      `${label}: releasePolicy has unknown release shape(s): ${unknownKeys.join(", ")} — expected ${RELEASE_SHAPE_LIST}`,
     );
-    const preset = SCOPE_PRESETS[scope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE];
-    return {
-      interruptOn: [...preset.interruptOn],
-      digest: { ...preset.digest },
-      scopePreset: preset.scopePreset,
-    };
   }
-
-  // A fully-normalised policy (what the setup wizard writes and saveConfig
-  // round-trips) has interruptOn/digest and may carry scopePreset; keep that
-  // back-annotation so the tick prompt can still speak the legacy words.
-  const storedPreset = raw["scopePreset"];
-  const scopePreset =
-    typeof storedPreset === "string" && (REPORT_SCOPES as readonly string[]).includes(storedPreset)
-      ? (storedPreset as ReportScope)
-      : undefined;
-
-  return {
-    interruptOn: normalizeInterruptOn(raw["interruptOn"], label, problems),
-    digest: normalizeDigest(raw["digest"], label, problems),
-    ...(scopePreset === undefined ? {} : { scopePreset }),
-  };
-}
-
-function normalizeInterruptOn(parsed: unknown, label: string, problems: string[]): InterruptCategory[] {
-  const fallback = [...INTERRUPT_CATEGORIES];
-  if (parsed === undefined) {
-    problems.push(`${label}: reporting.interruptOn is required in the explicit form (or use reporting.scope)`);
-    return fallback;
-  }
-  if (!Array.isArray(parsed)) {
-    problems.push(`${label}: reporting.interruptOn must be an array of ${INTERRUPT_CATEGORY_LIST}`);
-    return fallback;
-  }
-  const out: InterruptCategory[] = [];
-  for (const item of parsed) {
-    if (typeof item !== "string" || !(INTERRUPT_CATEGORIES as readonly string[]).includes(item)) {
-      problems.push(`${label}: reporting.interruptOn has unknown category ${JSON.stringify(item)} — one of ${INTERRUPT_CATEGORY_LIST}`);
-      continue;
-    }
-    const category = item as InterruptCategory;
-    if (!out.includes(category)) out.push(category);
-  }
-  if (out.length === 0) {
-    problems.push(`${label}: reporting.interruptOn must name at least one category`);
-    return fallback;
-  }
-  return out;
-}
-
-function normalizeDigest(parsed: unknown, label: string, problems: string[]): ReportingPolicy["digest"] {
-  const fallback: ReportingPolicy["digest"] = { cadence: "per-tick" };
-  if (parsed === undefined) {
-    problems.push(`${label}: reporting.digest is required in the explicit form (or use reporting.scope)`);
-    return fallback;
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${label}: reporting.digest must be an object with a "cadence" of ${DIGEST_CADENCE_LIST}`);
-    return fallback;
-  }
-  const raw = parsed as Raw;
-  const unknownKeys = Object.keys(raw).filter((k) => !["cadence", "at", "timezone"].includes(k));
-  if (unknownKeys.length > 0) {
-    problems.push(`${label}: reporting.digest has unknown key(s): ${unknownKeys.join(", ")}`);
-  }
-  const cadence = pickLiteral(
-    raw["cadence"],
-    DIGEST_CADENCES,
-    "per-tick",
-    `${label}: reporting.digest.cadence`,
-    DIGEST_CADENCE_LIST,
-    problems,
-  );
-  const digest: ReportingPolicy["digest"] = { cadence };
-  if (cadence !== "daily") {
-    if (raw["at"] !== undefined) problems.push(`${label}: reporting.digest.at is only valid with cadence "daily"`);
-    if (raw["timezone"] !== undefined) problems.push(`${label}: reporting.digest.timezone is only valid with cadence "daily"`);
-    return digest;
-  }
-  if (raw["at"] !== undefined) {
-    if (typeof raw["at"] !== "string" || !DIGEST_AT.test(raw["at"])) {
-      problems.push(`${label}: reporting.digest.at must be a 24h HH:MM time`);
-    } else {
-      digest.at = raw["at"];
-    }
-  }
-  if (raw["timezone"] !== undefined) {
-    if (typeof raw["timezone"] !== "string") {
-      problems.push(`${label}: reporting.digest.timezone must be a string`);
-    } else {
-      try {
-        new Intl.DateTimeFormat("en-GB", { timeZone: raw["timezone"] });
-        digest.timezone = raw["timezone"];
-      } catch {
-        problems.push(`${label}: reporting.digest.timezone is not a known IANA timezone`);
-      }
-    }
-  }
-  return digest;
-}
-
-/**
- * Who triages escalations, and how they are delivered when nobody answers.
- *
- * `orchestrator` is validated rather than folded to the default for the reason
- * `reporting.scope` is: a misspelt `"externl"` that quietly resolved to
- * `"embedded"` would start a second brain beside the operator's own session,
- * and both of them would triage the same issue from different transcripts.
- */
-function normalizeEscalation(parsed: unknown, label: string, problems: string[]): ProjectConfig["escalation"] {
-  let raw: Raw = {};
-  if (parsed !== undefined) {
-    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) raw = parsed as Raw;
-    else problems.push(`${label}: escalation must be an object`);
-  }
-
-  const escalation: ProjectConfig["escalation"] = {
-    // Absent means "yes, still tell me": a silently stuck run is the worst case.
-    fallbackToIssueComment: raw["fallbackToIssueComment"] !== false,
-    orchestrator: pickLiteral(
-      raw["orchestrator"],
-      ORCHESTRATOR_MODES,
-      "embedded",
-      `${label}: escalation.orchestrator`,
-      ORCHESTRATOR_MODE_LIST,
-      problems,
-    ),
-  };
-  const chatId = raw["telegramChatId"];
-  if (nonEmptyString(chatId)) escalation.telegramChatId = chatId;
-  return escalation;
-}
-
-/**
- * Who lands PRs and who cuts releases. Both default to the human: this is the
- * one config value that decides whether an unattended session may write to a
- * main branch, so it is granted explicitly or not at all.
- *
- * Unknown keys are rejected outright, as in `reporting` and for the same
- * reason: the object has exactly two members, so an unrecognised one is a typo
- * every time — and a `authority: { merges: "orchestrator" }` that loaded
- * cleanly would read as delegated while the orchestrator was still told to keep
- * its hands off.
- */
-function normalizeAuthority(parsed: unknown, label: string, problems: string[]): ProjectConfig["authority"] {
-  if (parsed === undefined) return { ...DEFAULT_AUTHORITY };
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${label}: authority must be an object with "merge" and "release" of ${AUTHORITY_HOLDER_LIST}`);
-    return { ...DEFAULT_AUTHORITY };
-  }
-  const raw = parsed as Raw;
-
-  const unknownKeys = Object.keys(raw).filter((k) => k !== "merge" && k !== "release");
-  if (unknownKeys.length > 0) {
-    problems.push(`${label}: authority has unknown key(s): ${unknownKeys.join(", ")}`);
-  }
-
-  return {
-    merge: pickLiteral(
-      raw["merge"],
-      AUTHORITY_HOLDERS,
-      DEFAULT_AUTHORITY.merge,
-      `${label}: authority.merge`,
-      AUTHORITY_HOLDER_LIST,
-      problems,
-    ),
-    release: pickLiteral(
-      raw["release"],
-      AUTHORITY_HOLDERS,
-      DEFAULT_AUTHORITY.release,
-      `${label}: authority.release`,
-      AUTHORITY_HOLDER_LIST,
-      problems,
-    ),
-  };
-}
-
-/**
- * Per-shape release grants, and the migration off the two legacy strings.
- *
- * Normalised to a *complete* map at load, so everything downstream — the gate,
- * `status`, the standing orders, the wizard — reads the same five answers and
- * none of them has to know which spelling was on disk.
- *
- * `"operator-brief"` migrates to every shape except `deploy` (#122). That is the
- * safe reading of what an operator believed the binary gate opened: a stale
- * `operator-brief` was enough for an orchestrator session to invoke Komodo
- * `DeployStack`, which is the grant nobody knowingly gave.
- *
- * An unknown shape key is rejected rather than ignored, as in `authority` and
- * for the same reason: the set is closed, so `{ "deploy-prod": "orchestrator" }`
- * is a typo every time — and a config that loaded it cleanly would read as
- * granted in the file while the gate denied every call.
- */
-function normalizeReleasePolicy(parsed: unknown, label: string, problems: string[]): ResolvedGrants {
-  if (parsed === undefined || parsed === "none") return { ...DENIED_RELEASE_GRANTS };
-  if (parsed === "operator-brief") return { ...OPERATOR_BRIEF_GRANTS };
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(
-      `${label}: releasePolicy must be an object mapping release shapes (${RELEASE_SHAPE_LIST}) to ` +
-        `${AUTHORITY_HOLDER_LIST}, or the legacy ${LEGACY_RELEASE_POLICY_LIST}, found ${JSON.stringify(parsed)}`,
-    );
-    return { ...DENIED_RELEASE_GRANTS };
-  }
-  const raw = parsed as Raw;
-
-  const unknownKeys = Object.keys(raw).filter((k) => !Object.hasOwn(DENIED_RELEASE_GRANTS, k));
-  if (unknownKeys.length > 0) {
-    problems.push(
-      `${label}: releasePolicy has unknown release shape(s): ${unknownKeys.join(", ")} — expected ${RELEASE_SHAPE_LIST}`,
-    );
-  }
-
   const grants = { ...DENIED_RELEASE_GRANTS };
   for (const shape of RELEASE_SHAPES) {
-    // An absent shape stays denied; a present-but-malformed one is reported and
-    // also stays denied, never folded to the value the operator asked for.
-    grants[shape] = pickLiteral(
-      raw[shape],
-      AUTHORITY_HOLDERS,
-      "human",
-      `${label}: releasePolicy.${shape}`,
-      AUTHORITY_HOLDER_LIST,
-      problems,
-    );
+    grants[shape] = (AUTHORITY_HOLDERS as readonly string[]).includes(raw[shape] as string)
+      ? (raw[shape] as ResolvedGrants[typeof shape])
+      : "human";
   }
   return grants;
 }
 
-/**
- * The merge and release gating conditions (#129).
- *
- * These used to be sentences in the operator's POLICY.md, which meant a verb
- * could only honour them by asking a model to read prose. Typed and normalised
- * here to a *complete* value, so the gate, the wizard, the plan summary and the
- * brief all read the same answers and none of them has to know which fields
- * were spelled on disk.
- *
- * Fail-closed throughout, as in `authority` and for the same reason: both
- * sections have a closed key set, so an unrecognised key is a typo every time —
- * and a `policy: { merge: { requiredCheck: [...] } }` that loaded cleanly would
- * read as configured in the file while the gate went on requiring every check.
- * A malformed value takes the documented default and is reported; it is never
- * folded to whatever the operator asked for.
- */
-function normalizeProjectPolicy(parsed: unknown, label: string, problems: string[]): ProjectPolicy {
+function finalizePolicy(parsed: unknown, label: string, problems: string[]): ProjectPolicy {
   if (parsed === undefined) return clonePolicy(DEFAULT_PROJECT_POLICY);
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     problems.push(`${label}: policy must be an object with "merge" and "release" sections`);
     return clonePolicy(DEFAULT_PROJECT_POLICY);
   }
   const raw = parsed as Raw;
-
-  const unknownKeys = Object.keys(raw).filter((k) => k !== "merge" && k !== "release");
-  if (unknownKeys.length > 0) {
-    problems.push(`${label}: policy has unknown key(s): ${unknownKeys.join(", ")} — expected "merge" or "release"`);
-  }
-
   return {
-    merge: normalizeMergePreconditions(raw["merge"], `${label}: policy.merge`, problems),
-    release: normalizeReleasePreconditions(raw["release"], `${label}: policy.release`, problems),
+    merge: finalizeMergePreconditions(raw["merge"], problems),
+    release: finalizeReleasePreconditions(raw["release"], problems),
   };
 }
 
-/** When a pull request may be merged. Absent members take {@link DEFAULT_PROJECT_POLICY}. */
-function normalizeMergePreconditions(parsed: unknown, at: string, problems: string[]): MergePreconditions {
-  const fallback = clonePolicy(DEFAULT_PROJECT_POLICY).merge;
-  if (parsed === undefined) return fallback;
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${at} must be an object`);
-    return fallback;
-  }
+function finalizeMergePreconditions(parsed: unknown, problems: string[]): MergePreconditions {
+  if (parsed === undefined) return clonePolicy(DEFAULT_PROJECT_POLICY).merge;
   const raw = parsed as Raw;
-
-  const known = new Set(Object.keys(fallback));
-  const unknownKeys = Object.keys(raw).filter((k) => !known.has(k));
-  if (unknownKeys.length > 0) {
-    problems.push(`${at} has unknown key(s): ${unknownKeys.join(", ")} — expected ${quoteList([...known])}`);
-  }
-
+  const fallback = clonePolicy(DEFAULT_PROJECT_POLICY).merge;
   return {
-    requiredChecks: normalizeNameList(raw["requiredChecks"], `${at}.requiredChecks`, problems),
-    baseFreshness: pickLiteral(
-      raw["baseFreshness"],
-      BASE_FRESHNESS,
-      fallback.baseFreshness,
-      `${at}.baseFreshness`,
-      BASE_FRESHNESS_LIST,
-      problems,
-    ),
-    drafts: pickLiteral(raw["drafts"], DRAFT_POLICIES, fallback.drafts, `${at}.drafts`, DRAFT_POLICY_LIST, problems),
-    whenBehindBase: pickLiteral(
-      raw["whenBehindBase"],
-      BEHIND_BASE_ACTIONS,
-      fallback.whenBehindBase,
-      `${at}.whenBehindBase`,
-      BEHIND_BASE_ACTION_LIST,
-      problems,
-    ),
+    requiredChecks: trimNames(raw["requiredChecks"]),
+    baseFreshness: (raw["baseFreshness"] as MergePreconditions["baseFreshness"]) ?? fallback.baseFreshness,
+    drafts: (raw["drafts"] as MergePreconditions["drafts"]) ?? fallback.drafts,
+    whenBehindBase: (raw["whenBehindBase"] as MergePreconditions["whenBehindBase"]) ?? fallback.whenBehindBase,
   };
 }
 
-/** When a release may be cut, what it produces, and where it may go. */
-function normalizeReleasePreconditions(parsed: unknown, at: string, problems: string[]): ReleasePreconditions {
-  const fallback = clonePolicy(DEFAULT_PROJECT_POLICY).release;
-  if (parsed === undefined) return fallback;
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    problems.push(`${at} must be an object`);
-    return fallback;
-  }
+function finalizeReleasePreconditions(parsed: unknown, problems: string[]): ReleasePreconditions {
+  if (parsed === undefined) return clonePolicy(DEFAULT_PROJECT_POLICY).release;
   const raw = parsed as Raw;
-
-  const known = new Set(Object.keys(fallback));
-  const unknownKeys = Object.keys(raw).filter((k) => !known.has(k));
-  if (unknownKeys.length > 0) {
-    problems.push(`${at} has unknown key(s): ${unknownKeys.join(", ")} — expected ${quoteList([...known])}`);
-  }
-
+  const fallback = clonePolicy(DEFAULT_PROJECT_POLICY).release;
   return {
-    requires: normalizeReleaseRequirements(raw["requires"], `${at}.requires`, fallback.requires, problems),
-    requiredChecks: normalizeNameList(raw["requiredChecks"], `${at}.requiredChecks`, problems),
-    artefacts: normalizeNameList(raw["artefacts"], `${at}.artefacts`, problems),
-    environments: normalizeNameList(raw["environments"], `${at}.environments`, problems),
+    requires: canonicalRequirements(raw["requires"]),
+    requiredChecks: trimNames(raw["requiredChecks"]),
+    artefacts: trimNames(raw["artefacts"]),
+    environments: trimNames(raw["environments"]),
   };
 }
 
-/**
- * The `requires` set, in the vocabulary's own order rather than the file's.
- *
- * Canonical order and de-duplication because this list is rendered into a
- * refusal and into the plan summary: two configs that require the same three
- * things must read identically, or an operator diffing them sees a change that
- * is not one.
- */
-function normalizeReleaseRequirements(
-  parsed: unknown,
-  at: string,
-  fallback: readonly ReleaseRequirement[],
-  problems: string[],
-): ReleaseRequirement[] {
-  if (parsed === undefined) return [...fallback];
-  if (!Array.isArray(parsed)) {
-    problems.push(`${at} must be an array of ${RELEASE_REQUIREMENT_LIST}`);
-    return [...fallback];
-  }
-
+/** The `requires` set in vocabulary order, deduplicated (#129's promise). */
+function canonicalRequirements(parsed: unknown): ReleaseRequirement[] {
   const chosen = new Set<string>();
-  parsed.forEach((entry: unknown, i) => {
-    if (!RELEASE_REQUIREMENTS.some((r) => r === entry)) {
-      problems.push(`${at}[${i}] must be ${RELEASE_REQUIREMENT_LIST}, found ${JSON.stringify(entry)}`);
-      return;
-    }
-    chosen.add(entry as ReleaseRequirement);
-  });
+  if (!Array.isArray(parsed)) return [];
+  for (const entry of parsed) chosen.add(entry as string);
   return RELEASE_REQUIREMENTS.filter((r) => chosen.has(r));
 }
 
-/**
- * A list of names an operator wrote: check names, artefacts, environments.
- *
- * Open-ended by necessity — this package cannot know what a fleet publishes —
- * but a malformed entry still rejects the whole config rather than being
- * dropped. A silently dropped environment name is an operator debugging a
- * refusal that reads exactly like a correctly-denied one.
- */
-function normalizeNameList(parsed: unknown, at: string, problems: string[]): string[] {
-  if (parsed === undefined) return [];
-  if (!Array.isArray(parsed)) {
-    problems.push(`${at} must be an array of non-empty strings`);
-    return [];
-  }
-
-  const names: string[] = [];
-  parsed.forEach((entry: unknown, i) => {
-    if (!nonEmptyString(entry)) {
-      problems.push(`${at}[${i}] must be a non-empty string, found ${JSON.stringify(entry)}`);
-      return;
-    }
-    names.push(entry.trim());
-  });
-  return names;
+/** Trims name-list entries (validation is zod's; this only canonises). */
+function trimNames(parsed: unknown): string[] {
+  if (!Array.isArray(parsed)) return [];
+  return parsed.map((n) => (n as string).trim());
 }
 
-/**
- * A clone URL carrying a password or token is rejected at load.
- *
- * `git clone` persists whatever is in the URL into the mirror's config, and the
- * run repository inherits `origin` from it — so a `https://<pat>@github.com/…`
- * writes the operator's credential into a file on disk that every later run
- * reads, where nobody is looking for it. This used to be a `ponytail` note on
- * `worktree.ts`'s `ensureMirror`; a warning nobody reads is not a check, so it
- * is now rejected at load with the field named.
- *
- * An SSH URL with a plain username (`ssh://git@github.com/o/r`, `git@github.com:o/r`)
- * is not a credential and is left alone — that is how nearly every fleet is
- * configured, and rejecting it would be a migration nobody asked for.
- */
-export function cloneUrlCredentialProblem(url: string): string | undefined {
-  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/]*)@/.exec(url);
-  if (m === null) return undefined;
-  const scheme = (m[1] ?? "").toLowerCase();
-  const userinfo = m[2] ?? "";
-  if (userinfo.includes(":")) {
-    return "embeds a user:password — git persists it into the mirror config, which hands every session the credential";
-  }
-  if (scheme === "http" || scheme === "https") {
-    return "embeds userinfo in an http(s) URL, which is how a personal access token is spelled — git persists it into the mirror config";
-  }
-  return undefined;
-}
-
-function normalizeRepos(parsed: unknown, label: string, problems: string[]): Record<string, RepoTarget> {
+function finalizeRepos(parsed: unknown, label: string, problems: string[]): Record<string, RepoTarget> {
   const repos: Record<string, RepoTarget> = {};
-
   const raw = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Raw) : undefined;
   const entries = raw === undefined ? [] : Object.entries(raw);
   if (entries.length === 0) {
     problems.push(`${label}: routing.repos needs at least one repo entry, or no issue can be routed`);
     return repos;
   }
-
   for (const [key, entry] of entries) {
     const value = entry as Raw | undefined;
-    const cloneUrl = value?.["cloneUrl"];
-    if (!nonEmptyString(cloneUrl)) {
+    const cloneUrl = value?.["cloneUrl"] as string | undefined;
+    if (typeof cloneUrl !== "string" || cloneUrl.trim() === "") {
       problems.push(`${label}: routing.repos.${key}.cloneUrl must be a non-empty string`);
       continue;
     }
@@ -1004,31 +1217,41 @@ function normalizeRepos(parsed: unknown, label: string, problems: string[]): Rec
       name: pickString(value?.["name"], key),
       cloneUrl,
       defaultBranch: pickString(value?.["defaultBranch"], "main"),
-      gates: normalizeGates(value?.["gates"], `${label}: routing.repos.${key}`, problems),
+      gates: finalizeGates(value?.["gates"], `${label}: routing.repos.${key}`, problems),
     };
-    const graph = normalizeGraphProject(value?.["graphProject"], `${label}: routing.repos.${key}`, problems);
+    const graph = finalizeGraphProject(value?.["graphProject"], `${label}: routing.repos.${key}`, problems);
     if (graph !== undefined) target.graphProject = graph;
-    const migrations = normalizeMigrationsDir(value?.["migrations"], `${label}: routing.repos.${key}`, problems);
+    const migrations = finalizeMigrationsDir(value?.["migrations"], `${label}: routing.repos.${key}`, problems);
     if (migrations !== undefined) target.migrations = { dir: migrations };
     repos[key] = target;
   }
-
   return repos;
 }
 
-/**
- * The ordered-migration-chain directory (#227), or `undefined` when the repo
- * opts out of the chain check.
- *
- * Repo-relative, no leading `/`, and no `..` segment — the value is read in one
- * process and used in another against the base branch's tree, so anything that
- * is not plainly a directory name is a guess the guard must not make.
- */
-function normalizeMigrationsDir(parsed: unknown, label: string, problems: string[]): string | undefined {
+function finalizeGates(parsed: unknown, label: string, problems: string[]): { cmd: string; cwd: string }[] {
+  if (parsed === undefined) return [];
+  if (!Array.isArray(parsed)) {
+    problems.push(`${label}.gates must be an array of { cmd, cwd }`);
+    return [];
+  }
+  const gates: { cmd: string; cwd: string }[] = [];
+  parsed.forEach((entry: unknown, i) => {
+    const gate = entry as Raw | undefined;
+    const cmd = gate?.["cmd"];
+    if (typeof cmd !== "string" || cmd.trim() === "") {
+      problems.push(`${label}.gates[${i}] must be { cmd, cwd } with a non-empty cmd`);
+      return;
+    }
+    gates.push({ cmd, cwd: pickString(gate?.["cwd"], ".") });
+  });
+  return gates;
+}
+
+function finalizeMigrationsDir(parsed: unknown, label: string, problems: string[]): string | undefined {
   if (parsed === undefined) return undefined;
   const raw = typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) ? (parsed as Raw) : undefined;
   const dir = raw?.["dir"];
-  if (!nonEmptyString(dir)) {
+  if (typeof dir !== "string" || dir.trim() === "") {
     problems.push(`${label}.migrations.dir must be a non-empty string`);
     return undefined;
   }
@@ -1039,24 +1262,12 @@ function normalizeMigrationsDir(parsed: unknown, label: string, problems: string
   return dir;
 }
 
-/**
- * The path of the index-only clone whose code graph this repo's workers query,
- * or `undefined` when the repo has none.
- *
- * A relative path is rejected rather than resolved, and that rejection is the
- * whole reason this is validated here: the value is written in one process and
- * *used* in another, by a session whose cwd is its own throwaway worktree. So
- * `../graph/api` would name a different directory for every reader, and none of
- * them the one that was indexed. There is no cwd this file could honestly
- * resolve it against, so it says so rather than guessing.
- */
-function normalizeGraphProject(parsed: unknown, label: string, problems: string[]): string | undefined {
+function finalizeGraphProject(parsed: unknown, label: string, problems: string[]): string | undefined {
   if (parsed === undefined) return undefined;
-  if (!nonEmptyString(parsed)) {
+  if (typeof parsed !== "string" || parsed.trim() === "") {
     problems.push(`${label}.graphProject must be a non-empty absolute path, found ${JSON.stringify(parsed)}`);
     return undefined;
   }
-
   const path = expandHome(parsed.trim());
   if (isAbsolute(path)) return path;
   problems.push(
@@ -1067,53 +1278,16 @@ function normalizeGraphProject(parsed: unknown, label: string, problems: string[
 }
 
 /**
- * `orchestratorReadPaths` was the allowlist extension for the orchestrator's
- * file gate (#127). The gate is gone — the orchestrator is unconfined by
- * operator ruling (#143) — and with it every reader of this key.
- *
- * It is deliberately *not* validated, and not rejected either: project-level
- * keys this build does not know are ignored, so a live fleet whose config still
- * carries it keeps loading. A retired key that failed validation would brick
- * exactly the fleets that adopted it, which is the 0.4.1→0.4.2 outage repeated
- * on purpose.
- */
-
-/**
- * Gates are the pre-push CI equivalent, so a malformed entry is an error, not
- * something to drop quietly: a skipped gate is exactly how a lint failure
- * reaches the runners unattended.
- */
-function normalizeGates(parsed: unknown, label: string, problems: string[]): { cmd: string; cwd: string }[] {
-  if (parsed === undefined) return [];
-  if (!Array.isArray(parsed)) {
-    problems.push(`${label}.gates must be an array of { cmd, cwd }`);
-    return [];
-  }
-
-  const gates: { cmd: string; cwd: string }[] = [];
-  parsed.forEach((entry: unknown, i) => {
-    const gate = entry as Raw | undefined;
-    const cmd = gate?.["cmd"];
-    if (!nonEmptyString(cmd)) {
-      problems.push(`${label}.gates[${i}] must be { cmd, cwd } with a non-empty cmd`);
-      return;
-    }
-    gates.push({ cmd, cwd: pickString(gate?.["cwd"], ".") });
-  });
-  return gates;
-}
-
-/**
- * Keeps only well-formed numeric caps; a value of the wrong shape is always
- * reported, because a ceiling the daemon cannot read is worth stopping for.
- *
- * `legacy` decides what an *unrecognised* key means. In a v1 file it is a cap
- * this version retired, so it is dropped and the config still loads — refusing
- * would strand a fleet on upgrade. In a v2 file every key this build writes is
- * current, so an unknown one is a typo and is reported: otherwise a mistyped
- * `dailySpendUsd` reads as configured while the real ceiling is the default.
+ * Reconciles a caps object against the active key set, version-aware. zod has
+ * already typed the *known* cap values; this drop-versus-reject is the one
+ * version-keyed decision that impossibly lives in a value schema.
  */
-function coerceCaps(parsed: unknown, label: string, problems: string[], legacy: boolean): Partial<Caps> {
+function reconcileCaps(
+  parsed: unknown,
+  label: string,
+  problems: string[],
+  legacy: boolean,
+): Partial<Caps> {
   const out: Partial<Caps> = {};
   if (parsed === undefined) return out;
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
@@ -1125,29 +1299,24 @@ function coerceCaps(parsed: unknown, label: string, problems: string[], legacy:
   for (const key of CAP_KEYS) {
     const v = raw[key];
     if (v === undefined) continue;
-    // The plan-allowance guard is the only cap that is an object rather than a
-    // number, so it validates its own shape before the numeric rule below can
-    // reject it wholesale.
     if (key === "planUsage") {
       const cap = coercePlanUsage(v, `${label}.planUsage`, problems);
       if (cap !== undefined) out.planUsage = cap;
       continue;
     }
-    // Spend is the only cap that may be null (= no gate). Every other ceiling
-    // is a non-negative number; 0 remains a hard stop where it already was.
-    if (key === "dailySpendUsd" && v === null) {
-      out.dailySpendUsd = null;
+    if (typeof v === "number" && Number.isFinite(v) && v >= 0) {
+      (out as Record<string, unknown>)[key as string] = v;
       continue;
     }
-    if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
-      problems.push(
-        key === "dailySpendUsd"
-          ? `${label}.${key} must be a non-negative finite number or null (no cap), found ${JSON.stringify(v)}`
-          : `${label}.${key} must be a non-negative finite number, found ${JSON.stringify(v)}`,
-      );
+    if (key === "dailySpendUsd" && v === null) {
+      out.dailySpendUsd = null;
       continue;
     }
-    out[key] = v;
+    problems.push(
+      key === "dailySpendUsd"
+        ? `${label}.${key} must be a non-negative finite number or null (no cap), found ${JSON.stringify(v)}`
+        : `${label}.${key} must be a non-negative finite number, found ${JSON.stringify(v)}`,
+    );
   }
 
   if (!legacy) {
@@ -1158,28 +1327,9 @@ function coerceCaps(parsed: unknown, label: string, problems: string[], legacy:
       );
     }
   }
-
   return out;
 }
 
-/**
- * `{ windowId, maxUsedFraction }`, or `null` for unmetered.
- *
- * Fail-closed for the same reason every other guard here is: a plan-allowance
- * cap the daemon cannot read is a ceiling the operator believes they have. Two
- * mistakes in particular are rejected by name rather than folded:
- *
- * - **`maxUsedFraction: 85`.** The threshold is a fraction, so `85` compares
- *   as "hold at 8500% consumed" — a guard that can never fire, and one that
- *   reads in the config file exactly like a deliberate 85% ceiling.
- * - **A misspelled key.** `windowID`, `window`, `maxUsedPercent` and friends
- *   would leave a cap with a missing half, which is the same silent
- *   never-fires outcome.
- *
- * A `windowId` no provider reports cannot be caught here — only a live reading
- * knows what exists — so that case is caught at admission instead, where it
- * holds dispatch and names the window (see `planUsageStatus` in `usage.ts`).
- */
 function coercePlanUsage(
   v: unknown,
   label: string,
@@ -1193,15 +1343,14 @@ function coercePlanUsage(
     return undefined;
   }
   const raw = v as Raw;
+  const unknownKeys = Object.keys(raw).filter((k) => k !== "windowId" && k !== "maxUsedFraction");
   const rawId = raw["windowId"];
+  const windowId = typeof rawId === "string" && rawId.trim() !== "" ? rawId.trim() : undefined;
   const rawFraction = raw["maxUsedFraction"];
-  const windowId = nonEmptyString(rawId) ? rawId.trim() : undefined;
   const maxUsedFraction =
     typeof rawFraction === "number" && Number.isFinite(rawFraction) && rawFraction >= 0 && rawFraction <= 1
       ? rawFraction
       : undefined;
-  const unknownKeys = Object.keys(raw).filter((k) => k !== "windowId" && k !== "maxUsedFraction");
-
   if (windowId === undefined) {
     problems.push(
       `${label}.windowId must be a non-empty allowance id such as "anthropic:7d", found ${JSON.stringify(rawId)}`,
@@ -1219,51 +1368,260 @@ function coercePlanUsage(
   return { windowId, maxUsedFraction };
 }
 
-function nonEmptyString(v: unknown): v is string {
-  return typeof v === "string" && v.trim().length > 0;
+/**
+ * Reporting scope decides whether the orchestrator speaks up or stays quiet, so
+ * a typo is rejected rather than folded to the default: a misspelt `"materal"`
+ * that silently resolved to `"material"` would read as configured on the day the
+ * operator meant to turn the volume down, and the config would keep lying.
+ */
+/** The legacy `reporting.scope` presets, materialised as explicit policies.
+ *  Kept separate from {@link DEFAULT_REPORT_POLICY} (the "no key on disk"
+ *  default, which must stay `material`): each preset records `scopePreset` so
+ *  the tick prompt can keep saying the exact legacy words (#229). Exported so
+ *  the setup wizard and the config validator agree on one mapping. */
+export const SCOPE_PRESETS: Record<ReportScope, ReportingPolicy> = {
+  material: {
+    interruptOn: [...INTERRUPT_CATEGORIES],
+    digest: { cadence: "per-tick" },
+    scopePreset: "material",
+  },
+  decisions: {
+    interruptOn: ["tier2", "decision-needed", "fleet-stopped"],
+    digest: { cadence: "per-tick" },
+    scopePreset: "decisions",
+  },
+  escalations: {
+    interruptOn: ["tier2", "fleet-stopped"],
+    digest: { cadence: "daily" },
+    scopePreset: "escalations",
+  },
+};
+
+function defaultReporting(): ReportingPolicy {
+  return { ...DEFAULT_REPORT_POLICY, interruptOn: [...DEFAULT_REPORT_POLICY.interruptOn] };
 }
 
-/** One rule for "a usable string, else the documented default", used throughout. */
-function pickString(v: unknown, fallback: string): string {
-  return nonEmptyString(v) ? v : fallback;
+/** The 24-hour `HH:MM` shape `digest.at` must take. */
+const DIGEST_AT = /^([01]\d|2[0-3]):[0-5]\d$/;
+
+/**
+ * The reporting policy: a legacy `scope` preset, or the explicit
+ * `interruptOn` + `digest` form. The two forms are mutually exclusive — a
+ * preset IS a policy, so configuring alongside it says one thing and means
+ * another (#229). zod validates the shapes; this enforces the mutual exclusion,
+ * materialises a preset, and reconciles the availability/digest clocks.
+ */
+function finalizeReporting(parsed: unknown, label: string, problems: string[]): ReportingPolicy {
+  if (parsed === undefined) return defaultReporting();
+  const raw = parsed as Raw;
+  const hasScope = raw["scope"] !== undefined;
+  const hasExplicit = raw["interruptOn"] !== undefined || raw["digest"] !== undefined || raw["availability"] !== undefined;
+  if (hasScope && hasExplicit) {
+    problems.push(
+      `${label}: reporting.scope is a preset — remove it when configuring interruptOn/digest/availability explicitly`,
+    );
+    return defaultReporting();
+  }
+  if (hasScope || (!hasExplicit && Object.keys(raw).length === 0)) {
+    const scope = (raw["scope"] as ReportScope) ?? DEFAULT_REPORT_SCOPE;
+    const preset = SCOPE_PRESETS[scope] ?? SCOPE_PRESETS[DEFAULT_REPORT_SCOPE];
+    return {
+      interruptOn: [...preset.interruptOn],
+      digest: { ...preset.digest },
+      scopePreset: preset.scopePreset,
+    };
+  }
+
+  const storedPreset = raw["scopePreset"];
+  const scopePreset =
+    typeof storedPreset === "string" && (REPORT_SCOPES as readonly string[]).includes(storedPreset)
+      ? (storedPreset as ReportScope)
+      : undefined;
+
+  const interruptOn = finalizeInterruptOn(raw["interruptOn"], label, problems);
+  const digest = finalizeDigest(raw["digest"], label, problems);
+  const availability = finalizeAvailability(raw["availability"], label, problems);
+  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,
+    digest,
+    ...(availability === undefined ? {} : { availability }),
+    ...(scopePreset === undefined ? {} : { scopePreset }),
+  };
 }
 
-/** Quoted alternatives for an error message, from the same data the guard reads. */
-function quoteList(values: readonly string[]): string {
-  return values.map((v) => `"${v}"`).join(" or ");
+function finalizeInterruptOn(
+  parsed: unknown,
+  label: string,
+  problems: string[],
+): InterruptCategory[] {
+  if (parsed === undefined) {
+    problems.push(`${label}: reporting.interruptOn is required in the explicit form (or use reporting.scope)`);
+    return [...INTERRUPT_CATEGORIES];
+  }
+  const out: InterruptCategory[] = [];
+  for (const item of parsed as readonly unknown[]) {
+    const category = item as InterruptCategory;
+    if (!out.includes(category)) out.push(category);
+  }
+  if (out.length === 0) {
+    problems.push(`${label}: reporting.interruptOn must name at least one category`);
+    return [...INTERRUPT_CATEGORIES];
+  }
+  return out;
+}
+
+function finalizeDigest(parsed: unknown, label: string, problems: string[]): ReportingPolicy["digest"] {
+  const fallback: ReportingPolicy["digest"] = { cadence: "per-tick" };
+  if (parsed === undefined) {
+    problems.push(`${label}: reporting.digest is required in the explicit form (or use reporting.scope)`);
+    return fallback;
+  }
+  const raw = parsed as Raw;
+  const cadence = (raw["cadence"] as DigestCadence) ?? "per-tick";
+  const digest: ReportingPolicy["digest"] = { cadence };
+  if (cadence !== "daily") {
+    if (raw["at"] !== undefined) problems.push(`${label}: reporting.digest.at is only valid with cadence "daily"`);
+    if (raw["timezone"] !== undefined) {
+      problems.push(`${label}: reporting.digest.timezone is only valid with cadence "daily"`);
+    }
+    return digest;
+  }
+  if (raw["at"] !== undefined) {
+    if (typeof raw["at"] !== "string" || !DIGEST_AT.test(raw["at"])) {
+      problems.push(`${label}: reporting.digest.at must be a 24h HH:MM time`);
+    } else {
+      digest.at = raw["at"];
+    }
+  }
+  if (raw["timezone"] !== undefined) {
+    const tz = raw["timezone"];
+    if (typeof tz !== "string") {
+      problems.push(`${label}: reporting.digest.timezone must be a string`);
+    } else {
+      try {
+        new Intl.DateTimeFormat("en-GB", { timeZone: tz });
+        digest.timezone = tz;
+      } catch {
+        problems.push(`${label}: reporting.digest.timezone is not a known IANA timezone`);
+      }
+    }
+  }
+  return digest;
+}
+
+function finalizeAvailability(
+  parsed: unknown,
+  label: string,
+  problems: string[],
+): WeeklyAvailability | undefined {
+  if (parsed === undefined) return undefined;
+  const raw = parsed as Raw;
+
+  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"] as readonly unknown[]) {
+      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"] as readonly unknown[]) {
+      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 };
 }
 
 /**
- * One rule for "a declared literal out of a closed set, else the documented
- * default", used by every such field here.
+ * A clone URL carrying a password or token is rejected at load.
  *
- * Absent takes the default silently; a value outside the set is always
- * reported and never folded. Each of these sets decides something the operator
- * would otherwise believe they had configured — who merges, who triages, how
- * loud the fleet is — and a typo that resolves to the default reads exactly
- * like a deliberate choice in the file afterwards.
+ * `git clone` persists whatever is in the URL into the mirror's config, and the
+ * run repository inherits `origin` from it — so a `https://<pat>@github.com/…`
+ * writes the operator's credential into a file on disk that every later run
+ * reads, where nobody is looking for it. This used to be a `ponytail` note on
+ * `worktree.ts`'s `ensureMirror`; a warning nobody reads is not a check, so it
+ * is now rejected at load with the field named.
+ *
+ * An SSH URL with a plain username (`ssh://git@github.com/o/r`, `git@github.com:o/r`)
+ * is not a credential and is left alone — that is how nearly every fleet is
+ * configured, and rejecting it would be a migration nobody asked for.
  */
-function pickLiteral<T extends string>(
-  v: unknown,
-  allowed: readonly T[],
-  fallback: T,
-  field: string,
-  quoted: string,
-  problems: string[],
-): T {
-  if (v === undefined) return fallback;
-  const hit = allowed.find((a) => a === v);
-  if (hit === undefined) {
-    problems.push(`${field} must be ${quoted}, found ${JSON.stringify(v)}`);
-    return fallback;
+export function cloneUrlCredentialProblem(url: string): string | undefined {
+  const m = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/([^/]*)@/.exec(url);
+  if (m === null) return undefined;
+  const scheme = (m[1] ?? "").toLowerCase();
+  const userinfo = m[2] ?? "";
+  if (userinfo.includes(":")) {
+    return "embeds a user:password — git persists it into the mirror config, which hands every session the credential";
   }
-  return hit;
+  if (scheme === "http" || scheme === "https") {
+    return "embeds userinfo in an http(s) URL, which is how a personal access token is spelled — git persists it into the mirror config";
+  }
+  return undefined;
+}
+
+function nonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+/** One rule for "a usable string, else the documented default", used throughout. */
+function pickString(v: unknown, fallback: string): string {
+  return nonEmptyString(v) ? v : fallback;
 }
 
 /**
  * `~/x` in a hand-written config must not create a literal `~` directory.
  *
- * Exported because the wizard and `graph-setup` derive paths the operator may
+ * Exported because the wizard and `setup graph` derive paths the operator may
  * have typed with a `~` in them, and one spelling of this rule in the package
  * is the only way a path shown in a plan matches the path a validator accepts.
  */