@open-everywhere/core 0.1.0

package/agent/memory/dream/mode3-last-mile.ts

@@ -0,0 +1,365 @@
+// The optional last mile: for the TOP recurring cluster only, attempt a repro and, when it reproduces, open a DRAFT pull request that a human merges.
+// 🔴 It ships OFF in the tracked literal below (`enabled: false`, `repo: null`) and there is no environment variable — which repository the agent may propose against is a trust declaration that changes by reviewed diff.
+
+import { createHash } from "node:crypto";
+import { getConfigPrProvider, type ConfigPrProvider } from "../../credentials/config-pr.js";
+import { appendAudit } from "../../audit/audit.js";
+import type { AuditInput } from "../../operational/store.js";
+import { DREAM_ACTOR } from "./proposal.js";
+import type { Mode3ClusterReport, Mode3Report } from "./mode3.js";
+import type { SignatureCluster } from "./mode3-cluster.js";
+import { signatureKey } from "./mode3-cluster.js";
+
+export interface Mode3LastMileConfig {
+  readonly enabled: boolean;
+  /** The ONE repository the arm may propose against, `"owner/name"`. `null` means none is
+   *  declared, and the arm refuses — it never infers a repo from anything it read. */
+  readonly repo: string | null;
+  /** The branch the draft targets. Read for a sha, NEVER written. */
+  readonly base: string;
+  /**
+   * Directory inside the repo the repro file is committed to. The transport supplies the bytes and a FILE NAME, and {@link isPlainFileName} refuses any name that is not one plain segment.
+   * The committed path is therefore always exactly `<reproDir>/<name>`, so an operator reads the whole blast radius off this literal.
+   */
+  readonly reproDir: string;
+}
+
+/**
+ * 🔴 SHIPPED OFF. Both `enabled: false` and `repo: null` are load-bearing, and each alone refuses:
+ * an operator who flips `enabled` without declaring a repo still gets a refusal, not a guess.
+ */
+export const MODE3_LAST_MILE: Mode3LastMileConfig = {
+  enabled: false,
+  repo: null,
+  base: "main",
+  reproDir: "repros/dream-mode3",
+};
+
+export interface ReproRequest {
+  readonly org: string;
+  /** The declared repo, `"owner/name"` — the only repository the transport may clone. */
+  readonly repo: string;
+  readonly cluster: SignatureCluster;
+}
+
+export interface ReproResult {
+  /** True ONLY when the failure actually reproduced. A transport that is unsure says false. */
+  readonly reproduced: boolean;
+  /** One plain sentence for the digest's reader. Required on both outcomes. */
+  readonly note: string;
+  /** The repro's file — its content is what the draft pull request carries. Required when
+   *  `reproduced` is true; a `reproduced: true` with no file is treated as NOT reproduced,
+   *  because a proposal with nothing in it is not a proposal. */
+  readonly file?: { readonly name: string; readonly content: string };
+}
+
+/** Clone the declared repo and attempt the repro. Registered at boot; core never shells out. */
+export type Mode3Repro = (req: ReproRequest) => Promise<ReproResult>;
+
+/**
+ * What the approval plane is asked to allow is THE ATTEMPT — this repository, base, head, title and cluster, each frozen before the gate and used verbatim after.
+ * 🔴 It is NOT content-level approval: the pull-request body and the repro bytes do not exist yet, because the gate runs before the clone so a refusal costs nothing.
+ */
+export interface LastMileApprovalRequest {
+  readonly org: string;
+  readonly repo: string;
+  readonly base: string;
+  readonly head: string;
+  readonly title: string;
+  readonly cluster: SignatureCluster;
+}
+
+/** The approval-plane gate. `true` allows the attempt; anything else refuses. Fail-closed. */
+export type Mode3LastMileApproval = (req: LastMileApprovalRequest) => Promise<boolean>;
+
+let registeredRepro: Mode3Repro | null = null;
+let registeredApproval: Mode3LastMileApproval | null = null;
+
+export function registerMode3Repro(repro: Mode3Repro): void {
+  registeredRepro = repro;
+}
+
+export function registerMode3LastMileApproval(approval: Mode3LastMileApproval): void {
+  registeredApproval = approval;
+}
+
+export type LastMileOutcome =
+  | { readonly kind: "disabled" }
+  | { readonly kind: "no-repo" }
+  | { readonly kind: "no-transport" }
+  | { readonly kind: "refused"; readonly reason: string }
+  | { readonly kind: "not-reproduced"; readonly note: string }
+  /**
+   * A FAILURE THAT ALREADY WROTE: `refused` means nothing was written, while this means the head branch exists and the pull request did not open.
+   * The two must not share a shape — a reader told "refused" never goes looking for the branch, which then takes a commit a week with nobody watching.
+   */
+  | { readonly kind: "failed-after-write"; readonly reason: string; readonly head: string }
+  /**
+   * THE ONCE-GUARD SKIPPED THIS RUN, AND THAT IS NOT A REFUSAL: an earlier attempt for this same digest may have cut the head branch, or opened the draft, before it was interrupted.
+   * Reporting it as `refused` would print "refused before it wrote anything" over a branch that exists.
+   */
+  | { readonly kind: "skipped-resume" }
+  | { readonly kind: "opened"; readonly url: string; readonly number: number; readonly updated: boolean };
+
+export function lastMileLine(outcome: LastMileOutcome): string {
+  switch (outcome.kind) {
+    case "disabled":
+      return "_Discovery only — the last-mile draft-PR arm is off on this deployment._";
+    case "no-repo":
+      return "_Discovery only — the last-mile arm is on but no repository is declared, so nothing was attempted._";
+    case "no-transport":
+      return "_Discovery only — the last-mile arm is on but no repro transport is registered, so nothing was attempted._";
+    case "refused":
+      return `_Discovery only — the last mile was refused before it wrote anything: ${outcome.reason}._`;
+    case "failed-after-write":
+      return `:warning: The last mile committed a repro to \`${outcome.head}\` but FAILED to open the pull request: ${outcome.reason}. The branch exists and needs a human.`;
+    case "skipped-resume":
+      return "_The last mile was skipped as a resume duplicate — an attempt for this digest already ran inside the dedupe window. That attempt may have cut the head branch or opened the draft, so read the `dream.mode3_last_mile` audit rows before assuming nothing was written._";
+    case "not-reproduced":
+      return `:mag: *Could not reproduce* the top cluster, so no pull request was opened. ${outcome.note}`;
+    case "opened":
+      return `:memo: Draft pull request ${outcome.updated ? "updated" : "opened"} for the top cluster — <${outcome.url}|#${outcome.number}>. It is a DRAFT proposal; a human reviews and merges.`;
+  }
+}
+
+const HEAD_PREFIX = "oe/dream-mode3";
+
+/**
+ * DETERMINISTIC in the signature, so re-running next week on a still-recurring signature updates the same pull request instead of opening a second one.
+ * The digest is of the signature key — the only cluster field that is stable across weeks (counts and examples are not).
+ */
+export function headBranchFor(cluster: SignatureCluster): string {
+  return `${HEAD_PREFIX}/${createHash("sha256").update(signatureKey(cluster.signature)).digest("hex").slice(0, 12)}`;
+}
+
+/**
+ * The dedupe identity of one digest's last-mile attempt — the TOP cluster's signature key, the same field {@link headBranchFor} derives the branch from.
+ * 🔴 Never key it on the label or the count: the label is a model completion a re-judged tick can change, and the count comes from a window that slides on a later resume.
+ */
+export function lastMileDedupeKey(report: Mode3Report): string | null {
+  const top = report.clusters[0];
+  return top && isSignatureReport(top) ? signatureKey(top.signature) : null;
+}
+
+/**
+ * 🔴 Refuse when the head and the base are the same branch. Under the deterministic head above
+ * this cannot happen by accident, which is the point: it is the guard that holds if the naming
+ * ever changes, or if an operator declares a base that collides with it. Throwing is correct —
+ * the caller turns it into a refusal outcome, and no ref has been written by this point.
+ */
+export function assertHeadIsNotBase(head: string, base: string): void {
+  if (head === base) {
+    throw new Error(`mode3 last mile: refusing to target the base branch (head "${head}" === base "${base}")`);
+  }
+}
+
+export type SignatureClusterReport = Mode3ClusterReport & SignatureCluster;
+
+/** Both fields are checked because a half-shaped cluster must reach neither: `signature` is what the head is derived from, `days` is what the body reports as spread. */
+function isSignatureReport(cluster: Mode3ClusterReport): cluster is SignatureClusterReport {
+  const c = cluster as Partial<SignatureCluster>;
+  return typeof c.signature === "object" && c.signature !== null && typeof c.days === "number";
+}
+
+/**
+ * 🔴 ONE PLAIN FILE NAME — the guard that makes `reproDir` a bound at all. The name comes from the repro TRANSPORT, which may derive it from failure text a stranger provoked.
+ * Without this check `sub/dir/x.md` already leaves the directory and `../../.github/workflows/x.yml` leaves the subtree, on a repo whose write token the arm holds.
+ */
+export function isPlainFileName(name: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/.test(name) && !name.includes("..");
+}
+
+export interface LastMileDeps {
+  readonly config?: Mode3LastMileConfig;
+  readonly repro?: Mode3Repro;
+  readonly approve?: Mode3LastMileApproval;
+  readonly provider?: ConfigPrProvider;
+  /**
+   * The audit append the arm makes AT THE MOMENT IT WRITES: the arm audits itself, because the schedule appends its digest row only after this returns.
+   * A run that writes a ref appends TWO rows — the `branch-cut` row the moment `ensureBranch` returns, then the outcome row — so a process death between them still leaves the branch named in the trail.
+   */
+  readonly audit?: (input: AuditInput) => Promise<unknown>;
+}
+
+function titleFor(cluster: SignatureClusterReport, label: string): string {
+  return `Mode 3 repro: ${label} (${cluster.signature.action} × ${cluster.count})`;
+}
+
+const BODY_LINE_MAX = 300;
+
+/**
+ * Flatten and clamp one line of audited text before it reaches a pull-request body. An example line is neither clamped nor flattened upstream, and the audited text behind it is unbounded — a whole HTTP response body can land in one.
+ * Left unclamped it earns a 422 against GitHub's 65536-character limit and leaves an orphan branch; flattening stops a newline-bearing body reshaping the markdown around it.
+ */
+function bodyLine(text: string): string {
+  const flat = text.replace(/\s+/g, " ").trim();
+  // Cut by CODE POINT, not by UTF-16 unit: a plain `slice` can split a surrogate pair when the
+  // audited text carries an emoji at the boundary, and a lone surrogate in a pull-request body is
+  // another way to earn a 422 after the repro commit is already written.
+  const points = Array.from(flat);
+  return points.length > BODY_LINE_MAX ? `${points.slice(0, BODY_LINE_MAX).join("")}… (${points.length - BODY_LINE_MAX} more chars)` : flat;
+}
+
+/**
+ * Every field carrying free-text audited DETAIL goes through {@link bodyLine}; the where-fields (`org`, `action`, `surface`) do not need it — `action` is one of a fixed set and the other two are the store's partition keys.
+ * The bound is PER LINE, so the total holds only while `maxExamplesPerCluster` stays at its default of 3.
+ */
+function bodyFor(report: Mode3Report, cluster: SignatureClusterReport, label: string, fixSketch: string, note: string): string {
+  return [
+    `Opened by the weekly failure digest (Mode 3) for \`${report.org}\`, window ${report.windowStart.slice(0, 10)} → ${report.windowEnd.slice(0, 10)}.`,
+    "",
+    `**Top recurring cluster** — \`${cluster.signature.action}\`, ${cluster.count} occurrence(s) across ${cluster.days} day(s) in \`${cluster.signature.surface}\`.`,
+    `**Label:** ${label}`,
+    `**Fix sketch:** ${fixSketch}`,
+    // `errorClass` is already normalised and 87 chars at most; `tool` is a raw `detail` string with
+    // no upstream bound of its own, so both go through bodyLine rather than only the one that needs it.
+    cluster.signature.tool ? `**Blamed:** \`${bodyLine(cluster.signature.tool)}\`` : "",
+    cluster.signature.errorClass ? `**Error class:** \`${bodyLine(cluster.signature.errorClass)}\`` : "",
+    "",
+    "**Examples**",
+    ...cluster.examples.map((e) => `- ${bodyLine(e)}`),
+    "",
+    "**Repro**",
+    bodyLine(note),
+    "",
+    "This is a DRAFT proposal written by the agent. It carries a reproduction, not a fix. A human reviews, decides and merges.",
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+}
+
+/**
+ * Record a write the arm actually made, at the moment it made it. Best-effort and never throwing:
+ * a failed audit must not turn a successfully opened pull request into a `refused` outcome, which
+ * would be the very mis-report this row exists to prevent.
+ */
+async function recordWrite(org: string, repo: string, outcome: LastMileOutcome, deps: LastMileDeps): Promise<void> {
+  try {
+    await (deps.audit ?? appendAudit)({
+      org,
+      platform: "dream",
+      workspace: "mode3",
+      principalId: DREAM_ACTOR,
+      action: "dream.mode3_last_mile",
+      detail:
+        outcome.kind === "opened"
+          ? { repo, outcome: outcome.kind, number: outcome.number, url: outcome.url, updated: outcome.updated }
+          : outcome.kind === "failed-after-write"
+            ? { repo, outcome: outcome.kind, head: outcome.head, reason: outcome.reason }
+            : { repo, outcome: outcome.kind },
+    });
+  } catch {
+  }
+}
+
+/**
+ * Appended the moment a head branch exists, before the repro commit and the pull-request call. It carries the branch name because the branch is the only thing a reader has to act on.
+ * Best-effort like {@link recordWrite}: a store that refuses this row must not turn a real pull request into a refusal.
+ */
+async function recordBranchCut(org: string, repo: string, head: string, deps: LastMileDeps): Promise<void> {
+  try {
+    await (deps.audit ?? appendAudit)({
+      org,
+      platform: "dream",
+      workspace: "mode3",
+      principalId: DREAM_ACTOR,
+      action: "dream.mode3_last_mile",
+      detail: { repo, outcome: "branch-cut", head },
+    });
+  } catch {
+  }
+}
+
+/**
+ * Never throws: every failure becomes an outcome the digest can print, because this arm must never take down the digest that carries it.
+ * The refusal order matters and is tested — config, then the declared repo, then the transport, then APPROVAL, all before the clone.
+ */
+export async function runLastMile(report: Mode3Report, deps: LastMileDeps = {}): Promise<LastMileOutcome> {
+  const config = deps.config ?? MODE3_LAST_MILE;
+  if (!config.enabled) return { kind: "disabled" };
+  if (!config.repo) return { kind: "no-repo" };
+
+  const repro = deps.repro ?? registeredRepro;
+  if (!repro) return { kind: "no-transport" };
+  const approve = deps.approve ?? registeredApproval;
+  if (!approve) return { kind: "refused", reason: "no approval gate is registered, and this arm is fail-closed" };
+
+  // The top cluster ONLY. `clusters` is already ranked recurrence-first by mode3-cluster.ts.
+  const first = report.clusters[0];
+  if (!first) return { kind: "refused", reason: "the digest named no cluster" };
+  // v1's action bucketing produces clusters with no `signature`. The arm needs the signature for
+  // its deterministic head, so it refuses rather than inventing one from a coarser grouping.
+  if (!isSignatureReport(first)) return { kind: "refused", reason: "the digest was built without signature clustering" };
+  const top = first;
+
+  const repo = config.repo;
+  // Set the moment the FIRST ref write happens. It is what tells a post-write failure from a
+  // refusal in the catch below — the two report differently, on purpose.
+  let wroteHead: string | null = null;
+  try {
+    const head = headBranchFor(top);
+    assertHeadIsNotBase(head, config.base);
+    // Flattened here, once, for both the title and the body: the upstream clamp bounds LENGTH alone, and a newline in the model-written label splits the pull request's title.
+    const label = bodyLine(top.label);
+    const fixSketch = bodyLine(top.fixSketch);
+    const title = titleFor(top, label);
+
+    if ((await approve({ org: report.org, repo, base: config.base, head, title, cluster: top })) !== true) {
+      return { kind: "refused", reason: "the approval plane did not approve the draft pull request" };
+    }
+
+    const result = await repro({ org: report.org, repo, cluster: top });
+    if (!result.reproduced || !result.file) {
+      return { kind: "not-reproduced", note: result.note };
+    }
+    if (!isPlainFileName(result.file.name)) {
+      return { kind: "refused", reason: "the repro transport named a file outside the declared repro directory" };
+    }
+
+    const provider = deps.provider ?? getConfigPrProvider();
+    const token = await provider.resolveWriteToken(repo);
+
+    // Read the BASE for a sha — a read, never a write — and cut the head from it. ensureBranch is
+    // idempotent, so a still-recurring signature reuses last week's branch.
+    const baseSha = await provider.getBranchSha({ repo, branch: config.base, token });
+    if (!baseSha) return { kind: "refused", reason: `the declared base branch \`${config.base}\` does not exist in \`${repo}\`` };
+    await provider.ensureBranch({ repo, branch: head, sha: baseSha, token });
+    wroteHead = head; // from here on a failure has left a ref behind, and must say so
+    // 🔴 Record before the rest of the write. The catch below records a THROW, but a process death is not a throw, and the branch above would then exist with nothing in the trail naming it.
+    await recordBranchCut(report.org, repo, head, deps);
+
+    // Every content call below names `branch: head`. The base is never a write target.
+    const path = `${config.reproDir}/${result.file.name}`;
+    const existing = await provider.getFile({ repo, path, branch: head, token });
+    await provider.putFile({
+      repo,
+      path,
+      content: result.file.content,
+      message: `dream mode 3: repro for ${top.signature.action} in ${top.signature.surface}`,
+      branch: head,
+      token,
+      committer: provider.committer(),
+      ...(existing ? { sha: existing.sha } : {}),
+    });
+
+    const outcome = await provider.openOrReopenPr({
+      repo,
+      head,
+      base: config.base,
+      title,
+      body: bodyFor(report, top, label, fixSketch, result.note),
+      token,
+      draft: true, // 🔴 a machine-written proposal opens as a draft, and this arm can never merge it
+    });
+    const opened: LastMileOutcome = { kind: "opened", url: outcome.url, number: outcome.number, updated: outcome.updated };
+    await recordWrite(report.org, repo, opened, deps);
+    return opened;
+  } catch (err) {
+    // Bounded, single-line — this string reaches an audit row and a Slack message.
+    const brief = String(err instanceof Error ? err.message : err).split("\n")[0].slice(0, 160);
+    if (!wroteHead) return { kind: "refused", reason: brief };
+    const failed: LastMileOutcome = { kind: "failed-after-write", reason: brief, head: wroteHead };
+    await recordWrite(report.org, repo, failed, deps);
+    return failed;
+  }
+}

package/agent/memory/dream/mode3.ts

@@ -0,0 +1,311 @@
+// Mode 3, the weekly failure digest: it clusters the org's audited failure-shaped rows, facets the top clusters with the cheap utility model, and reports them. It edits nothing and opens nothing.
+// The narrowing layer and the facet judge are both injected, so the module edge to dream/mode3-cluster.ts stays one-way.
+
+import type { AuditEntry } from "../../operational/store.js";
+
+/** The audit `action` values mined as a failed turn or interaction. `turn.failed` itself is a hook event rather than a durable audit row, so these are the queryable proxy. */
+export const FAILURE_ACTIONS = [
+  "surface.quiet_fail", // slack.ts: an uninvited turn's failure, suppressed on-surface
+  "turn.bare_stop", // slack.ts: turn ended with no reply/react/no_reply — a missing judgment call
+  "webhook.rejected", // webhooks/reject-audit.ts: an inbound delivery failed signature/route checks
+  "spend.cap_bypassed", // spend/bypass.ts: an admin sudo'd past a spend cap
+  "approval.failed", // approvals/flow.ts: an approved pending action's execute() threw
+  "unified.supervisor_turn_failed", // channels/unified.ts: a unified-supervisor turn threw; carries failureDiag()
+  "unified.supervisor_session_failed", // channels/unified.ts: a unified-supervisor session failed; carries failureDiag() + the OPE-573 `unresumable` label
+] as const;
+
+export type FailureAction = (typeof FAILURE_ACTIONS)[number];
+
+const FAILURE_ACTION_SET: ReadonlySet<string> = new Set(FAILURE_ACTIONS);
+
+export function isFailureAction(action: string): action is FailureAction {
+  return FAILURE_ACTION_SET.has(action);
+}
+
+export interface FailureCluster {
+  readonly action: string;
+  readonly count: number;
+  readonly examples: readonly string[];
+}
+
+export interface BucketOptions {
+  /** Top clusters to keep, by count descending. Default 3. */
+  readonly maxClusters?: number;
+  /** Example one-liners kept per cluster (for the facet prompt + report). Default 3. */
+  readonly maxExamplesPerCluster?: number;
+  /** Optional surface-name lookup ("#e2e-smoke") for example lines. The caller resolves
+   *  (the schedule, with live credentials); this module stays pure. Undefined → raw ids. */
+  readonly surfaceName?: SurfaceNamer;
+  /**
+   * The narrowing layer {@link buildMode3Report} runs; default {@link bucketFailures}. schedules/dream-mode3.ts passes the signature clustering here.
+   * Injected rather than imported so the dependency edge stays one-way: mode3-cluster.ts reads this module and this module never reads it back.
+   */
+  readonly cluster?: FailureClusterer;
+}
+
+export type FailureClusterer = (rows: readonly AuditEntry[], opts: BucketOptions) => FailureCluster[];
+
+export type SurfaceNamer = (row: AuditEntry) => string | undefined;
+
+/**
+ * One human-readable line for a single audited failure row, grounded in each action's actual `detail` shape.
+ * It always leads with the platform: a bare Slack team id reads as Microsoft Teams to a human, so the ids never stand alone.
+ */
+export function exampleLine(row: AuditEntry, name?: SurfaceNamer): string {
+  const resolved = name?.(row);
+  const where = resolved
+    ? `${row.platform} ${resolved}${row.surface ? ` (${row.surface})` : ""}`
+    : `${row.platform} ${row.surface ? `${row.workspace}/${row.surface}` : row.workspace}`;
+  const d = row.detail ?? {};
+  switch (row.action) {
+    case "surface.quiet_fail":
+      return `${where}: ${String(d["event"] ?? "quiet-fail")} — ${String(d["message"] ?? "(no message)")}`;
+    case "turn.bare_stop":
+      return `${where}: turn ended with no reply, no react, and no no_reply (thread ${String(d["threadTs"] ?? "?")})`;
+    case "webhook.rejected":
+      return `${where}: hook "${String(d["hookId"] ?? "?")}" rejected (${String(d["status"] ?? "?")} — ${String(d["reason"] ?? "unknown reason")})`;
+    case "spend.cap_bypassed":
+      return `${where}: spend cap bypassed (${String(d["standing"] ?? "?")})${d["reason"] ? ` — ${String(d["reason"])}` : ""}`;
+    case "approval.failed":
+      return `${where}: "${String(d["kind"] ?? "?")}" approval execute() failed — ${String(d["error"] ?? "(no error)")}`;
+    case "unified.supervisor_turn_failed":
+    case "unified.supervisor_session_failed":
+      return `${where}: ${row.action === "unified.supervisor_turn_failed" ? "supervisor turn failed" : "supervisor session failed"} — ${String(d["message"] ?? "(no message)")}${failureDiagSuffix(d)}`;
+    default:
+      return `${where}: ${row.action}`;
+  }
+}
+
+// The exact key set `failureDiag()` (channels/unified.ts) is whitelisted to emit onto `detail`, mirrored here and never widened, so the line assumes no vendor or gateway shape.
+const FAILURE_DIAG_KEYS = [
+  "code",
+  "errorId",
+  "name",
+  "statusCode",
+  "generationId",
+  "gatewayName",
+  "gatewayType",
+  "upstreamType",
+  "upstreamStatusCode",
+  "upstreamMessage",
+] as const;
+
+function failureDiagSuffix(d: Record<string, unknown>): string {
+  const parts = FAILURE_DIAG_KEYS.filter((k) => d[k] !== undefined).map((k) => `${k}=${String(d[k])}`);
+  return parts.length > 0 ? ` [${parts.join(" ")}]` : "";
+}
+
+/** Group the failure-shaped rows by `action` in first-seen order, with no cap and no row dropped. Non-failure rows are ignored. Pure. */
+export function groupFailuresByAction(rows: readonly AuditEntry[]): Map<string, AuditEntry[]> {
+  const byAction = new Map<string, AuditEntry[]>();
+  for (const row of rows) {
+    if (!isFailureAction(row.action)) continue;
+    const list = byAction.get(row.action);
+    if (list) list.push(row);
+    else byAction.set(row.action, [row]);
+  }
+  return byAction;
+}
+
+/**
+ * Bucket the week's audit rows by `action`, keep the top `maxClusters` by count (descending,
+ * ties broken by first-seen order — stable). Non-failure rows are ignored. Pure.
+ */
+export function bucketFailures(rows: readonly AuditEntry[], opts: BucketOptions = {}): FailureCluster[] {
+  const maxClusters = opts.maxClusters ?? 3;
+  const maxExamples = opts.maxExamplesPerCluster ?? 3;
+  return Array.from(groupFailuresByAction(rows).entries())
+    .map(([action, entries]) => ({
+      action,
+      count: entries.length,
+      examples: entries.slice(0, maxExamples).map((row) => exampleLine(row, opts.surfaceName)),
+    }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, maxClusters);
+}
+
+/** Longest facet label kept. Enforced in BOTH places a facet can enter — see buildMode3Report. */
+export const FACET_LABEL_MAX = 120;
+export const FACET_SKETCH_MAX = 300;
+
+export interface FailureFacet {
+  readonly label: string;
+  readonly fixSketch: string;
+}
+
+// The fallback facet used when no judge is registered, or when the judge abstains or throws for a cluster, so a cluster is never blank.
+const STATIC_FACET: Record<FailureAction, FailureFacet> = {
+  "surface.quiet_fail": {
+    label: "Uninvited-turn failures suppressed on-surface",
+    fixSketch: "Check upstream model/gateway reliability for uninvited (name-drop) turns; consider whether that surface's retry/backoff needs tightening.",
+  },
+  "turn.bare_stop": {
+    label: "Turn ended with no reply, react, or no_reply",
+    fixSketch: "Usually a missing judgment call, not a deliberate one — review NO_REPLY/no_reply tool coverage or clarify the dispatch prompt for this case.",
+  },
+  "webhook.rejected": {
+    label: "Inbound webhook deliveries rejected",
+    fixSketch: "Check the failing hook id's HMAC secret provisioning and trusted-host allow-list.",
+  },
+  "spend.cap_bypassed": {
+    label: "Admin spend-cap bypasses",
+    fixSketch: "Review whether the surface's spend cap is sized correctly, or whether the bypass rate signals a cap that's too tight for normal usage.",
+  },
+  "approval.failed": {
+    label: "Approved actions failing at execute()",
+    fixSketch: "Inspect the failing ActionKind's execute() error — likely an external dependency hiccup (GitHub/Slack) or a stale frozen arg.",
+  },
+  "unified.supervisor_turn_failed": {
+    label: "Unified-supervisor turn failures",
+    fixSketch: "Check the example's statusCode/gatewayType/upstreamType — a gateway 4xx/5xx names the failing provider; an EmptyModelResponse has no provider to attribute and may instead need a retry/backoff tweak.",
+  },
+  "unified.supervisor_session_failed": {
+    label: "Unified-supervisor session failures",
+    fixSketch:
+      "Same diagnostic fields as a turn failure. Nothing rotates the seat in response — read the row's `unresumable` label first: TRUE names a session the runtime can never resume (rotate the window), FALSE points at a bad delegated route or a persistently unhealthy provider.",
+  },
+};
+
+function staticFacet(action: string): FailureFacet {
+  return (STATIC_FACET as Record<string, FailureFacet>)[action] ?? {
+    label: action,
+    fixSketch: "No static fix-sketch on file for this action — inspect the example occurrences directly.",
+  };
+}
+
+function extractJSON(text: string): unknown | null {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end <= start) return null;
+  try {
+    return JSON.parse(text.slice(start, end + 1));
+  } catch {
+    return null;
+  }
+}
+
+export function facetPrompt(cluster: FailureCluster): string {
+  return [
+    "You are triaging a week of recorded failures from an AI agent harness (not memory content — a",
+    "code-level reliability review).",
+    `Failure action: "${cluster.action}" — ${cluster.count} occurrence(s) this week.`,
+    "Example occurrences:",
+    ...cluster.examples.map((e) => `- ${e}`),
+    "",
+    "Write a short label (<=8 words) naming the failure pattern, and ONE concrete sentence",
+    "suggesting a harness/prompt/skill/config change a human could investigate or make.",
+    'Reply with STRICT JSON only, no prose: {"label": "…", "fixSketch": "…"}',
+  ].join("\n");
+}
+
+/** Tolerant parse of a facet completion into a FailureFacet, or null (fail quiet — the
+ *  static fallback is used instead). Clamped: label <=120 chars, fixSketch <=300 chars. */
+export function parseFailureFacet(text: string): FailureFacet | null {
+  const raw = extractJSON(text);
+  if (typeof raw !== "object" || raw === null) return null;
+  const o = raw as Record<string, unknown>;
+  if (typeof o["label"] !== "string" || o["label"].trim().length === 0) return null;
+  if (typeof o["fixSketch"] !== "string" || o["fixSketch"].trim().length === 0) return null;
+  return { label: o["label"].trim().slice(0, FACET_LABEL_MAX), fixSketch: o["fixSketch"].trim().slice(0, FACET_SKETCH_MAX) };
+}
+
+export type FacetCompletion = (scope: string, prompt: string) => Promise<string>;
+
+export interface FailureFacetJudge {
+  facet(scope: string, cluster: FailureCluster): Promise<FailureFacet | null>;
+}
+
+export function facetJudgeFromCompletion(complete: FacetCompletion): FailureFacetJudge {
+  return {
+    async facet(scope, cluster) {
+      try {
+        return parseFailureFacet(await complete(scope, facetPrompt(cluster)));
+      } catch {
+        return null; // fail quiet — the static fallback facet is used instead
+      }
+    },
+  };
+}
+
+let registeredFacetJudge: FailureFacetJudge | null = null;
+
+/** Register the deployment's facet transport at boot. A later call replaces it; with none registered the report uses the static, zero-LLM facets. */
+export function registerFailureFacetJudge(judge: FailureFacetJudge): void {
+  registeredFacetJudge = judge;
+}
+
+function failureFacetJudge(): FailureFacetJudge | null {
+  return registeredFacetJudge;
+}
+
+export interface Mode3ClusterReport extends FailureCluster {
+  readonly label: string;
+  readonly fixSketch: string;
+  /** True when the LLM facet was used for this cluster; false = the static v1 fallback
+   *  (no judge registered, or it abstained/threw for this cluster). */
+  readonly judged: boolean;
+}
+
+export interface Mode3Report {
+  readonly org: string;
+  readonly windowStart: string;
+  readonly windowEnd: string;
+  /** Count of ALL failure-shaped rows in the window (not just the top clusters kept). */
+  readonly totalFailures: number;
+  readonly clusters: readonly Mode3ClusterReport[];
+}
+
+/**
+ * Returns null when there is nothing to say: an empty week is a no-op by design, so the schedule never posts on a quiet week.
+ * The facet judge's `scope` is the org id.
+ */
+export async function buildMode3Report(
+  org: string,
+  rows: readonly AuditEntry[],
+  windowStart: string,
+  windowEnd: string,
+  opts: BucketOptions = {},
+): Promise<Mode3Report | null> {
+  const clusters = (opts.cluster ?? bucketFailures)(rows, opts);
+  if (clusters.length === 0) return null;
+
+  const judge = failureFacetJudge();
+  const shaped: Mode3ClusterReport[] = [];
+  for (const c of clusters) {
+    let facet: FailureFacet | null = null;
+    if (judge) {
+      try {
+        facet = await judge.facet(org, c);
+      } catch {
+        facet = null; // belt-and-braces — a well-behaved judge never throws
+      }
+    }
+    const chosen = facet ?? staticFacet(c.action);
+    // Clamp here, not only in `parseFailureFacet`: a registered `FailureFacetJudge` may return a facet of any size, and only `facetJudgeFromCompletion` routes through that parser.
+    // This is the one point every consumer reads, and the label reaches a pull-request title (GitHub refuses past 256 characters) and a Slack message.
+    shaped.push({ ...c, label: chosen.label.slice(0, FACET_LABEL_MAX), fixSketch: chosen.fixSketch.slice(0, FACET_SKETCH_MAX), judged: facet !== null });
+  }
+
+  const totalFailures = rows.filter((r) => isFailureAction(r.action)).length;
+  return { org, windowStart, windowEnd, totalFailures, clusters: shaped };
+}
+
+const DISCOVERY_ONLY_FOOTER =
+  "_Discovery only — no PR opened this run. A human picks which fix sketch, if any, to act on._";
+
+/**
+ * Render a report as the admin-channel Slack message text. Pure.
+ * A caller passes its own `footer` in place of the default: the last mile puts its outcome line there, so a failure to reproduce reaches the reader in words rather than as silence.
+ */
+export function formatMode3Report(report: Mode3Report, footer: string = DISCOVERY_ONLY_FOOTER): string {
+  const lines = [
+    `:microscope: *Weekly failure digest* (${report.windowStart.slice(0, 10)} → ${report.windowEnd.slice(0, 10)}) — ` +
+      `${report.totalFailures} failure event(s), top ${report.clusters.length} cluster(s):`,
+  ];
+  report.clusters.forEach((c, i) => {
+    lines.push(`${i + 1}. *${c.label}* (\`${c.action}\`, ${c.count}×) — ${c.fixSketch}`);
+    if (c.examples[0]) lines.push(`   e.g. ${c.examples[0]}`);
+  });
+  lines.push(footer);
+  return lines.join("\n");
+}