@coreplane/switchboard 1.239.0 → 1.241.0

package/dist/assets/src/core/costsSnapshotStore.ts

@@ -0,0 +1,209 @@
+import type { CloudflareUsage, DateRange, LlmCostRow } from "./costs.js";
+import { isRunUsageReport, type RunUsageReport } from "./runUsage.js";
+import {
+  DEFAULT_STATE_WORKER_TOKEN_ENV,
+  STATE_WORKER_BLOCK_NAMES,
+  stateWorkerOf,
+  type SecretReader,
+  type StateWorkerBlocks,
+} from "./stateWorkerRef.js";
+import { errorSuffix } from "./workerError.js";
+
+// Where the costs snapshot lives (docs/reference/specs/costs.md item 6): the
+// billing sources' answers over the page's widest range — Cloudflare's usage
+// rows, Anthropic's daily cost rows, the run history's per-user usage — as the
+// sources gave them, and when they were read. ONE snapshot per installation:
+// the Cloudflare read is account-wide and the LLM rows carry every workspace,
+// so every configured group's report is arithmetic over the same document.
+// Two implementations of one seam (AGENTS.md invariant 2):
+//
+// - `WorkerCostsSnapshotStore` — the production choice — an HTTPS client to
+//   the `CostsSnapshotDO` on the state Worker (deploy/cloudflare-memory/, one
+//   SQLite Durable Object, the same MEMORY_TOKEN bearer as memory, run history
+//   and the delivery snapshot), so a bot restart keeps the snapshot
+//   (invariant 6) and the first request after one is served, not computed.
+// - `InMemoryCostsSnapshotStore` — tests, and the process without a state
+//   Worker: the snapshot lives as long as the process does.
+//
+// Node-free on purpose: the state Worker imports `isCostsSnapshot` by
+// relative path so the bot and the Worker validate ONE shape.
+//
+// Route contract (JSON in/out, bearer = the Worker's MEMORY_TOKEN):
+//   POST /costs/snapshot/get {}          → {snapshot: CostsSnapshot | null}
+//   POST /costs/snapshot/put {snapshot}  → {ok: true}          replace the snapshot whole
+
+/** The billing sources' answers over the snapshot window, and when they were read. */
+export interface CostsSnapshot {
+  /** ISO 8601 — when the read began. */
+  takenAt: string;
+  /** Who asked for it: `schedule` for the refresh loop, else the caller's label. */
+  takenBy: string;
+  /** How long the read took, both sources and the run history together. */
+  durationMs: number;
+  /** The window the rows were read for: `MAX_DAYS` UTC days ending on the take day. */
+  range: DateRange;
+  /** Every meter Cloudflare bills on, account-wide, as `CloudflareUsageSource` answered. */
+  usage: CloudflareUsage;
+  /** Anthropic's daily cost rows (the open days estimated); null when no LLM source is configured. */
+  llm: LlmCostRow[] | null;
+  /** The run history's per-user usage over the window; null with run history off. */
+  runUsage: RunUsageReport | null;
+}
+
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+const isInstant = (v: unknown): v is string => typeof v === "string" && Number.isFinite(Date.parse(v));
+const isFiniteNumber = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);
+
+/** The datasets every `CloudflareUsage` carries — the guard checks each is rows with a day. */
+const USAGE_DATASETS = [
+  "containers",
+  "durableObjectRequests",
+  "durableObjectDays",
+  "durableObjectStorage",
+  "workers",
+  "r2Storage",
+  "r2Operations",
+  "workflows",
+] as const;
+
+function isDatedRows(v: unknown): boolean {
+  return (
+    Array.isArray(v) &&
+    v.every((row) => typeof row === "object" && row !== null && ISO_DAY.test(String((row as { date?: unknown }).date)))
+  );
+}
+
+function isDateRange(v: unknown): v is DateRange {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v as Record<string, unknown>;
+  return (
+    typeof r.from === "string" &&
+    ISO_DAY.test(r.from) &&
+    typeof r.to === "string" &&
+    ISO_DAY.test(r.to) &&
+    isFiniteNumber(r.days) &&
+    typeof r.partialLastDay === "boolean"
+  );
+}
+
+function isLlmRows(v: unknown): v is LlmCostRow[] {
+  return (
+    Array.isArray(v) &&
+    v.every((row) => {
+      if (typeof row !== "object" || row === null) return false;
+      const r = row as Record<string, unknown>;
+      return (
+        typeof r.date === "string" &&
+        ISO_DAY.test(r.date) &&
+        (r.workspaceId === null || typeof r.workspaceId === "string") &&
+        isFiniteNumber(r.amountUsd)
+      );
+    })
+  );
+}
+
+/** The fields the arithmetic reads, present and of the right kind; the rows are the sources'. */
+export function isCostsSnapshot(v: unknown): v is CostsSnapshot {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  if (!isInstant(s.takenAt) || typeof s.takenBy !== "string") return false;
+  if (!isFiniteNumber(s.durationMs) || s.durationMs < 0) return false;
+  if (!isDateRange(s.range)) return false;
+  const usage = s.usage as Record<string, unknown> | null | undefined;
+  if (typeof usage !== "object" || usage === null) return false;
+  if (!USAGE_DATASETS.every((name) => isDatedRows(usage[name]))) return false;
+  if (s.llm !== null && !isLlmRows(s.llm)) return false;
+  return s.runUsage === null || isRunUsageReport(s.runUsage);
+}
+
+export interface CostsSnapshotStore {
+  /** The stored snapshot, or undefined when none was ever stored. Throws on failure. */
+  get(): Promise<CostsSnapshot | undefined>;
+  /** Replace the snapshot whole. Throws on failure; callers warn, never crash. */
+  put(snapshot: CostsSnapshot): Promise<void>;
+}
+
+export class InMemoryCostsSnapshotStore implements CostsSnapshotStore {
+  private stored: CostsSnapshot | undefined;
+
+  async get(): Promise<CostsSnapshot | undefined> {
+    return this.stored ? structuredClone(this.stored) : undefined;
+  }
+
+  async put(snapshot: CostsSnapshot): Promise<void> {
+    this.stored = structuredClone(snapshot);
+  }
+}
+
+/** Per-request ceiling: a ninety-day snapshot is a few hundred KB each way. */
+export const COSTS_SNAPSHOT_WORKER_TIMEOUT_MS = 30_000;
+
+export interface WorkerCostsSnapshotStoreOptions {
+  /** Base URL of the state Worker. */
+  baseUrl: string;
+  /** Bearer secret (MEMORY_TOKEN on the Worker). */
+  token: string;
+  /** Injectable for tests; defaults to global fetch. */
+  fetch?: typeof fetch;
+}
+
+export class WorkerCostsSnapshotStore implements CostsSnapshotStore {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly opts: WorkerCostsSnapshotStoreOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? fetch;
+  }
+
+  async get(): Promise<CostsSnapshot | undefined> {
+    const res = await this.post("/costs/snapshot/get", {});
+    if (!res.ok) throw new Error(`state Worker /costs/snapshot/get HTTP ${res.status}${await errorSuffix(res)}`);
+    const data = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    if (data.snapshot === null || data.snapshot === undefined) return undefined;
+    if (!isCostsSnapshot(data.snapshot))
+      throw new Error("state Worker /costs/snapshot/get: the answer is not a costs snapshot");
+    return data.snapshot;
+  }
+
+  async put(snapshot: CostsSnapshot): Promise<void> {
+    const res = await this.post("/costs/snapshot/put", { snapshot });
+    if (!res.ok) throw new Error(`state Worker /costs/snapshot/put HTTP ${res.status}${await errorSuffix(res)}`);
+  }
+
+  private post(path: string, body: unknown): Promise<Response> {
+    return this.fetchImpl(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: `Bearer ${this.opts.token}` },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(COSTS_SNAPSHOT_WORKER_TIMEOUT_MS),
+    });
+  }
+}
+
+/** Process-startup store selection (src/index.ts): the Worker store behind
+ *  whichever `*.worker` block names the state Worker — the snapshot is a cache,
+ *  so it earns no block of its own — else the in-memory store with a warning
+ *  naming what a restart then costs. Pure w.r.t. the environment. */
+export function buildCostsSnapshotStore(
+  config: StateWorkerBlocks,
+  secrets: SecretReader,
+  warn: (message: string) => void,
+): CostsSnapshotStore {
+  const worker = stateWorkerOf(config);
+  if (!worker) {
+    warn(
+      `the costs snapshot is kept in memory — a restart loses it and the costs page has nothing to show until the next one is taken. Name the state Worker (${STATE_WORKER_BLOCK_NAMES}) to keep it there.`,
+    );
+    return new InMemoryCostsSnapshotStore();
+  }
+  const tokenEnv = worker.tokenEnv ?? DEFAULT_STATE_WORKER_TOKEN_ENV;
+  const token = secrets.named(tokenEnv);
+  if (!token) {
+    warn(
+      `the state Worker is configured but ${tokenEnv} is unset — the costs snapshot is kept in memory and a restart loses it. Set ${tokenEnv} to the state Worker's bearer.`,
+    );
+    return new InMemoryCostsSnapshotStore();
+  }
+  return new WorkerCostsSnapshotStore({ baseUrl: worker.baseUrl, token: token.reveal() });
+}

package/dist/assets/src/core/delivery.ts

@@ -1,3 +1,4 @@
+import { snapshotAgeText } from "./snapshotAge.js";
 import { systemClock } from "./trace/clock.js";
 
 // Delivery indicators: what the run history and the pull requests' own facts
@@ -553,17 +554,9 @@ function indicatorLines(x: DeliveryIndicators): string[] {
   ];
 }
 
-/** `just now`, `12 minutes ago`, `3 hours ago`, `2 days ago` — how old the snapshot is, for a footer or a head line. */
-export function snapshotAgeText(snapshotAt: string, nowMs: number): string {
-  const minutes = Math.max(0, Math.floor((nowMs - Date.parse(snapshotAt)) / 60_000));
-  if (!Number.isFinite(minutes)) return "";
-  const unit = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"} ago`;
-  if (minutes < 1) return "just now";
-  if (minutes < 90) return unit(minutes, "minute");
-  const hours = Math.round(minutes / 60);
-  if (hours < 48) return unit(hours, "hour");
-  return unit(Math.round(hours / 24), "day");
-}
+/** `just now`, `12 minutes ago`, `3 hours ago`, `2 days ago` — how old the snapshot is, for a footer or a head line
+ *  (src/core/snapshotAge.ts, shared with the costs page). */
+export { snapshotAgeText };
 
 /** `<YYYY-MM-DD> <hh:mm> UTC` — an instant as the text spells one. */
 const clock = (iso: string): string => `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC`;

package/dist/assets/src/core/deliverySnapshotStore.ts

@@ -1,6 +1,15 @@
 import { REPO_SLUG, type DeliveryRange, type PullRequestFacts } from "./delivery.js";
+import {
+  DEFAULT_STATE_WORKER_TOKEN_ENV,
+  STATE_WORKER_BLOCK_NAMES,
+  stateWorkerOf,
+  type SecretReader,
+  type StateWorkerBlocks,
+} from "./stateWorkerRef.js";
 import { errorSuffix } from "./workerError.js";
 
+export type { SecretReader, StateWorkerBlocks, StateWorkerRef } from "./stateWorkerRef.js";
+
 // Where a repository's delivery snapshot lives (docs/reference/specs/delivery.md item 10):
 // the merged pull requests' facts over the snapshot window, as GitHub gave
 // them, and when they were read. Two implementations of one seam (AGENTS.md
@@ -207,29 +216,6 @@ export class WorkerDeliverySnapshotStore implements DeliverySnapshotStore {
   }
 }
 
-/** A `{ baseUrl, tokenEnv? }` reference to the state Worker, as every `*.worker` config block spells it. */
-export interface StateWorkerRef {
-  baseUrl: string;
-  /** Env var holding the bearer; default MEMORY_TOKEN. */
-  tokenEnv?: string;
-}
-
-/** The config blocks that may name the state Worker — one Worker, referenced from each capability that uses it. */
-export interface StateWorkerBlocks {
-  runtimeOverrides?: { worker?: StateWorkerRef };
-  runHistory?: { worker?: StateWorkerRef };
-  schedules?: { worker?: StateWorkerRef };
-  memory?: { worker?: StateWorkerRef };
-}
-
-const DEFAULT_TOKEN_ENV = "MEMORY_TOKEN";
-
-/** The slice of the process's `Secrets` the builder reads (src/secrets.ts; named
- *  structurally so this module stays free of the bot's Node-only imports for the Worker). */
-export interface SecretReader {
-  named(name: string): { reveal(): string } | undefined;
-}
-
 /** Process-startup store selection (src/index.ts, the CLI): the Worker store
  *  behind whichever `*.worker` block names the state Worker — the snapshot is
  *  a cache, so it earns no block of its own — else the in-memory store with a
@@ -239,16 +225,14 @@ export function buildDeliverySnapshotStore(
   secrets: SecretReader,
   warn: (message: string) => void,
 ): DeliverySnapshotStore {
-  const worker = [config.runtimeOverrides, config.runHistory, config.schedules, config.memory].find(
-    (block) => block?.worker?.baseUrl,
-  )?.worker;
+  const worker = stateWorkerOf(config);
   if (!worker) {
     warn(
-      "delivery snapshots are kept in memory — a restart loses them and the first request after one reads GitHub live. Name the state Worker (runHistory.worker, runtimeOverrides.worker, schedules.worker or memory.worker) to keep them on it.",
+      `delivery snapshots are kept in memory — a restart loses them and the first request after one reads GitHub live. Name the state Worker (${STATE_WORKER_BLOCK_NAMES}) to keep them on it.`,
     );
     return new InMemoryDeliverySnapshotStore();
   }
-  const tokenEnv = worker.tokenEnv ?? DEFAULT_TOKEN_ENV;
+  const tokenEnv = worker.tokenEnv ?? DEFAULT_STATE_WORKER_TOKEN_ENV;
   const token = secrets.named(tokenEnv);
   if (!token) {
     warn(

package/dist/assets/src/core/ingressTokens.ts

@@ -2,22 +2,29 @@
 // (src/channels/http.ts, src/channels/mcp.ts) and the Cloudflare Worker shim
 // (deploy/cloudflare/worker.ts, which fires scheduled runs through /ingress)
 // read `SWITCHBOARD_INGRESS_TOKENS` with ONE parser. The shape is
-//   {"<raw bearer token>": {"subject": "alice", "channel": "ops"}, ...}
+//   {"<raw bearer token>": {"subject": "alice", "channel": "ops", "email": "alice@example.com"}, ...}
 // A token is a CREDENTIAL, nothing more: what its bearer may do — start a run
 // (`dispatch`), read runs, anything else — is the `grants` entry for
 // `http:<subject>` / `mcp:<subject>` in config.yaml (docs/reference/specs/authorization.md
-// item 9). Absent, empty, or malformed => an empty map. Callers treat an empty
-// map as "ingress disabled" (fail-closed) — this module never decides that, it
-// only parses. Token material is never logged here; the caller may log the reason.
+// item 9). `email` names the PERSON the credential belongs to (identity, never
+// authority: the run is theirs, the grants stay the credential's —
+// authorization.md item 15). Absent, empty, or malformed => an empty map.
+// Callers treat an empty map as "ingress disabled" (fail-closed) — this module
+// never decides that, it only parses. Token material is never logged here; the
+// caller may log the reason.
 
-/** The identity a token maps to. `subject` becomes the platform-namespaced user
- *  id (`http:<subject>`); an optional `channel` names the channel a dispatch
- *  through this token is recorded under (`http:<channel>`) — routing, not a
- *  grant. These two are the whole identity: any other field in an entry is
- *  ignored, so nothing in the token map can widen what the grants entry says. */
+/** The identity a token maps to. `subject` becomes the platform-namespaced
+ *  credential id (`http:<subject>`); an optional `channel` names the channel a
+ *  dispatch through this token is recorded under (`http:<channel>`) — routing,
+ *  not a grant; an optional `email` names the person the credential is bound
+ *  to, resolved to their Slack identity by the adapter (`boundRequester`) so
+ *  the run is requested by the person and the credential is `authenticatedAs`.
+ *  These three are the whole identity: any other field in an entry is ignored,
+ *  so nothing in the token map can widen what the grants entry says. */
 export interface IngressIdentity {
   subject: string;
   channel?: string;
+  email?: string;
 }
 
 export type IngressTokenMap = Record<string, IngressIdentity>;
@@ -28,9 +35,10 @@ export type ParsedIngressTokens =
   | { ok: false; reason: string; tokens: IngressTokenMap };
 
 /** Parse the raw env value. Entries with an empty token, a non-object value, a
- *  missing/empty `subject`, or a non-string `channel` are skipped; the rest are
- *  kept, each reduced to `{ subject, channel? }`. `ok: false` only for a value
- *  that is not a JSON object at all. */
+ *  missing/empty `subject`, a non-string `channel` or a non-string `email` are
+ *  skipped; the rest are kept, each reduced to `{ subject, channel?, email? }`
+ *  (an `email` without an `@` is dropped from the entry, never the entry).
+ *  `ok: false` only for a value that is not a JSON object at all. */
 export function parseIngressTokenMap(raw: string | undefined): ParsedIngressTokens {
   if (!raw || raw.trim() === "") return { ok: true, tokens: {} };
   let parsed: unknown;
@@ -49,9 +57,15 @@ export function parseIngressTokenMap(raw: string | undefined): ParsedIngressToke
     const v = value as Record<string, unknown>;
     const subject = v.subject;
     const channel = v.channel;
+    const email = v.email;
     if (typeof subject !== "string" || subject === "") continue;
     if (channel !== undefined && typeof channel !== "string") continue;
-    tokens[token] = typeof channel === "string" ? { subject, channel } : { subject };
+    if (email !== undefined && typeof email !== "string") continue;
+    tokens[token] = {
+      subject,
+      ...(typeof channel === "string" ? { channel } : {}),
+      ...(typeof email === "string" && email.includes("@") ? { email: email.trim().toLowerCase() } : {}),
+    };
   }
   return { ok: true, tokens };
 }

package/dist/assets/src/core/runLedger/types.ts

@@ -53,6 +53,9 @@ export interface LiveRunMeta {
   repo?: string;
   sourceUrl?: string;
   userName?: string;
+  /** The bound credential behind the person (authorization.md item 15): a
+   *  resume or restart dispatches under ITS grants again, never the person's. */
+  authenticatedAs?: string;
   effort?: string;
   ref?: string;
   headSha?: string;

package/dist/assets/src/core/runRecord.ts

@@ -69,12 +69,18 @@ export interface RunRecord {
   model?: string;
   /** Platform-namespaced ids (AGENTS.md invariant 4). */
   channelId: string;
-  /** The person the run was for — the message's sender, or the person an app
-   *  relayed it for (slack-channel.md item 13); `slack:bot:<id>` only when no
-   *  person could be found behind an app's post. */
+  /** The person the run was for — the message's sender, the person an app
+   *  relayed it for (slack-channel.md item 13), or the person a bound
+   *  credential belongs to (authorization.md item 15); `slack:bot:<id>` only
+   *  when no person could be found behind an app's post. */
   userId: string;
   /** The app that posted the request for `userId`, by display name, when it was not their own message. */
   relayedBy?: string;
+  /** The credential that authenticated the request (`http:<subject>`,
+   *  `mcp:<subject>`, `cli:local`) when it was bound to the person `userId`
+   *  names — the run is theirs, the grants were the credential's. Absent when
+   *  the sender and the credential are one. */
+  authenticatedAs?: string;
   threadKey: string;
   /** How the run's channel may travel (authorization): stamped at dispatch
    *  from the `ChannelDirectory`, read by `member-of` (a `public` run is
@@ -767,6 +773,7 @@ export function isRunRecord(v: unknown): v is RunRecord {
     return false;
   if (typeof r.channelId !== "string" || typeof r.userId !== "string" || typeof r.threadKey !== "string") return false;
   if (r.relayedBy !== undefined && typeof r.relayedBy !== "string") return false;
+  if (r.authenticatedAs !== undefined && typeof r.authenticatedAs !== "string") return false;
   // Absent on records written before the stamp existed (read as `unknown`); present → a known value.
   if (r.channelVisibility !== undefined && !CHANNEL_VISIBILITIES.includes(r.channelVisibility as ChannelVisibility))
     return false;

package/dist/assets/src/core/schedules.ts

@@ -415,8 +415,9 @@ export function watchdogFiring(
   const errors = result.results.filter((r) => r.error !== undefined);
   const created = result.results.filter((r) => instanceActionOf(r.instance) === "created").length;
   const timedOut = result.results.filter((r) => r.action === "provision-timed-out").length;
+  const rebuilt = result.results.filter((r) => r.action === "auto-rebuilt").length;
   const disk = fullestDisk(result.results);
-  const counts = `${result.count}/${result.cap} residents · ${created} refreshed · ${timedOut} timed out · ${errors.length} errors${disk ? ` · disk max ${disk}` : ""}`;
+  const counts = `${result.count}/${result.cap} residents · ${created} refreshed · ${timedOut} timed out · ${errors.length} errors${rebuilt > 0 ? ` · ${rebuilt} rebuilt` : ""}${disk ? ` · disk max ${disk}` : ""}`;
   const first = errors[0];
   return {
     schedule: schedule.name,

package/dist/assets/src/core/ship/coordinator.ts

@@ -448,6 +448,8 @@ export type CoordinatorAction =
       recover?: { runId: string };
     }
   | { type: "merge"; step: string; prNumber: number; headSha: string }
+  /** Wait for the intake's checks-settled event at the approved head, bounded as the fallback. */
+  | { type: "wait-checks"; step: string; headSha: string; timeoutMs: number }
   | { type: "sleep"; step: string; ms: number }
   | { type: "end"; step: string; ending: UnitEnding };
 
@@ -508,6 +510,7 @@ export type StepReturn =
   // fired, or a person merged — so the runner merged nothing (`by: other`).
   | { type: "merge"; step: string; outcome: "merged"; by: "other"; sha: string; mergedAt: string; at: number }
   | { type: "merge"; step: string; outcome: "pending" | "refused"; reason: string; at: number }
+  | { type: "wait-checks"; step: string; outcome: "event" | "timeout" }
   | { type: "sleep"; step: string };
 
 /** How one unit's pipeline ended — the truthful vocabulary the ship pipeline
@@ -554,6 +557,27 @@ export type CoordinatorNote =
  *  person can see whether the cap or the child is the problem. */
 export type ShipBudgetSpent = Readonly<Record<"coding" | "review" | "waiting", number>>;
 
+/** The severity ship must address before an approve stands (agent-ship item
+ *  9's gate): an approve carrying a finding at or above this level continues
+ *  into the findings step exactly as a request_changes does. Ordered most to
+ *  least severe. */
+export const ADDRESS_SEVERITIES = ["blocking", "major", "minor", "nit"] as const;
+export type AddressSeverity = (typeof ADDRESS_SEVERITIES)[number];
+/** Where the level in force came from, most specific wins: a `severity:` directive on the request (`run`), the user's or the channel's config scope, the org's `ship.addressSeverity` (or its default). */
+export type AddressSeveritySource = "org" | "channel" | "user" | "run";
+export const DEFAULT_ADDRESS_SEVERITY: AddressSeverity = "minor";
+export const isAddressSeverity = (v: unknown): v is AddressSeverity =>
+  (ADDRESS_SEVERITIES as readonly unknown[]).includes(v);
+
+const severityRank = (s: AddressSeverity): number => ADDRESS_SEVERITIES.indexOf(s);
+/** The findings the gate acts on at `level`: at or above it. Every parsed
+ *  finding carries one of the ladder's four levels — the verdict parser
+ *  (`parseVerdictInput`) drops an entry with any other severity, `fyi` or none,
+ *  with a note — so nothing outside the ladder ever reaches the gate. */
+export function findingsAtOrAbove(findings: readonly Finding[], level: AddressSeverity): Finding[] {
+  return findings.filter((f) => severityRank(f.severity) <= severityRank(level));
+}
+
 export interface UnitPipelineInput {
   unit: { id: string; branch: string };
   repo: string;
@@ -567,6 +591,12 @@ export interface UnitPipelineInput {
    *  `runner` (a seeded plan, under its grant) or `person` (a task, or a
    *  record without the field). */
   merge: "runner" | "person";
+  /** The severity to address: resolved once by the hand-off —
+   *  directive > user > channel > org — and written on the instance beside
+   *  `merge`, so the machine reads one value. Absent reads as the default. */
+  addressSeverity?: AddressSeverity;
+  /** Which layer set the level in force; named in the round header and the ending. */
+  addressSeveritySource?: AddressSeveritySource;
   /** The instance's mark (agent-ship item 16): a generated one-unit plan — a
    *  `plan` with an id and no `path` — whose unit runs in the requesting
    *  thread and is re-issued with the request's own text, never a plan path. */
@@ -601,7 +631,7 @@ type Phase =
       dead?: "failed" | "interrupted";
     }
   | { at: "merge"; pr: PrRef; headSha: string; n: number; since: number }
-  | { at: "merge-sleep"; pr: PrRef; headSha: string; n: number; since: number }
+  | { at: "merge-wait"; pr: PrRef; headSha: string; n: number; since: number }
   | { at: "ended" };
 
 export interface UnitPipelineState {
@@ -641,9 +671,16 @@ export const WAIT_MARGIN_MS = 5 * MIN;
  *  margin and the merge poll are the same number), and it keeps a round to a
  *  few steps: a coding child's 45 minutes are ten waits and ten reads. */
 export const WAIT_CHUNK_MS = 5 * MIN;
-/** How often the runner asks for the merge while the guards are still pending, and for how long at most. */
-export const MERGE_POLL_MS = 5 * MIN;
+/** How long the merge step waits for the guards at most. While checks are
+ *  pending the machine waits on the intake's `checks-settled-<head>` event
+ *  (http-ingress.md item 12) — one bounded wait per ask, the remainder of this
+ *  cap, as the fallback when the event never arrives. */
 export const MERGE_WAIT_MAX_MS = 60 * MIN;
+/** One merge wait's fallback timeout: the old poll's cadence. The event wakes
+ *  the machine at once when the intake delivers it; without one (the webhook
+ *  not configured, a delivery lost) the door is still re-asked every chunk, so
+ *  a merge is never slower than the poll it replaced. */
+export const MERGE_WAIT_CHUNK_MS = 5 * MIN;
 /** A `busy` without the live run's id: nothing to wait on, so a short sleep before the spawn is asked again. */
 export const BUSY_RETRY_MS = 2 * MIN;
 
@@ -789,8 +826,13 @@ export function nextAction(s: UnitPipelineState): CoordinatorAction {
       };
     case "merge":
       return { type: "merge", step: `${unit}/merge/${p.n}`, prNumber: p.pr.number, headSha: p.headSha };
-    case "merge-sleep":
-      return { type: "sleep", step: `${unit}/merge/sleep/${p.n}`, ms: MERGE_POLL_MS };
+    case "merge-wait":
+      return {
+        type: "wait-checks",
+        step: `${unit}/merge/wait/${p.n}`,
+        headSha: p.headSha,
+        timeoutMs: Math.max(MIN, Math.min(MERGE_WAIT_CHUNK_MS, MERGE_WAIT_MAX_MS - (s.clock - p.since))),
+      };
     case "ended":
       return { type: "end", step: `${unit}/end`, ending: s.ending! };
   }
@@ -960,6 +1002,34 @@ function settleReview(
         },
         notes,
       );
+    // The severity gate: an approve carrying a finding at or
+    // above the level in force does not end the unit — the round continues
+    // into the findings step exactly as a request_changes does, and only an
+    // approve whose findings all sit below the level stands as merge-ready.
+    const level = next.input.addressSeverity ?? DEFAULT_ADDRESS_SEVERITY;
+    const gated = findingsAtOrAbove(verdict.findings, level);
+    if (gated.length > 0) {
+      if (mode !== undefined)
+        return end(
+          next,
+          {
+            kind: "stopped",
+            mode,
+            round,
+            reviewRounds: next.reviewRounds,
+            ...(facts.finalReply !== undefined ? { finalReply: facts.finalReply } : {}),
+            ...(facts.reviewPosted === true ? { postedReview: true } : {}),
+          },
+          notes,
+        );
+      if (next.reviewRounds >= next.input.caps.maxRounds)
+        return end(
+          next,
+          { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
+          notes,
+        );
+      return enterRound(next, { index: round.index, kind: "findings" }, notes);
+    }
     const pr = next.pr!;
     if (next.input.merge !== "runner")
       return end(next, { kind: "merge_ready", pr, reviewRounds: next.reviewRounds }, notes);
@@ -1294,11 +1364,11 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           reviewRounds: s.reviewRounds,
         });
       return {
-        state: { ...clocked, phase: { at: "merge-sleep", pr: p.pr, headSha: p.headSha, n: p.n, since: p.since } },
+        state: { ...clocked, phase: { at: "merge-wait", pr: p.pr, headSha: p.headSha, n: p.n, since: p.since } },
         notes: [],
       };
     }
-    case "merge-sleep":
+    case "merge-wait":
       return {
         state: { ...s, phase: { at: "merge", pr: p.pr, headSha: p.headSha, n: p.n + 1, since: p.since } },
         notes: [],
@@ -1383,6 +1453,17 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
   const declined = [...(s.dispositionsByRound[e.reviewRounds - 1] ?? [])].filter((d) => d.disposition === "declined");
   const declinedLine = `Declined findings: ${declined.length > 0 ? declined.map((d) => `${d.findingId}${d.note ? ` — ${d.note}` : ""}`).join("; ") : "none"}`;
   const verdictLine = `Verdict: LGTM${s.lastVerdictSummary ? ` — ${s.lastVerdictSummary}` : ""}`;
+  // The level in force and its source, plus the findings it left
+  // below the gate on the approved round — named so a skipped finding is a
+  // stated decision, never a silent one.
+  const level = s.input.addressSeverity ?? DEFAULT_ADDRESS_SEVERITY;
+  const levelLine = `Severity addressed: ${level} and above (set by ${s.input.addressSeveritySource ?? "org"}).`;
+  const lastFindings = s.findingsByRound[e.reviewRounds] ?? [];
+  const skipped = lastFindings.filter((f) => !findingsAtOrAbove([f], level).length);
+  const skippedLine =
+    skipped.length > 0
+      ? `Findings below ${level}, left as-is: ${skipped.map((f) => `${f.id} (${f.severity}) — ${f.title}`).join("; ")}`
+      : undefined;
   const join = (parts: Array<string | undefined>) => parts.filter(Boolean).join("\n\n");
   switch (e.kind) {
     case "merged":
@@ -1391,12 +1472,16 @@ export function renderUnitReport(s: UnitPipelineState, facts?: MergeReadyFacts):
       return [
         `✅ Merged after ${rounds}: ${e.pr.url} (squash \`${e.sha.slice(0, 7)}\`) — merged by the plan runner under \`plan:merge\`: the review approved at this head and the guards were green.`,
         verdictLine,
+        levelLine,
+        ...(skippedLine ? [skippedLine] : []),
         declinedLine,
       ].join("\n");
     case "merge_ready":
       return [
         `✅ Merge-ready after ${rounds}: ${e.pr.url}`,
         verdictLine,
+        levelLine,
+        ...(skippedLine ? [skippedLine] : []),
         declinedLine,
         // What the driver read at the approved head when it composed this
         // ending (agent-ship item 9): a merge that already happened is named

package/dist/assets/src/core/snapshotAge.ts

@@ -0,0 +1,30 @@
+// How old a snapshot is, in the words every page that serves one uses (the
+// delivery page, the costs page): shared so the two never drift. Node-free.
+
+/** `just now`, `n minutes ago`, `n hours ago`, `n days ago` — the snapshot's age at `nowMs`; empty for an unparsable instant. */
+export function snapshotAgeText(snapshotAt: string, nowMs: number): string {
+  const minutes = Math.max(0, Math.floor((nowMs - Date.parse(snapshotAt)) / 60_000));
+  if (!Number.isFinite(minutes)) return "";
+  const unit = (n: number, word: string): string => `${n} ${word}${n === 1 ? "" : "s"} ago`;
+  if (minutes < 1) return "just now";
+  if (minutes < 90) return unit(minutes, "minute");
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return unit(hours, "hour");
+  return unit(Math.round(hours / 24), "day");
+}
+
+/** `in n minutes`, `in n hours`, `in n days` — how far off an instant is at `nowMs`; once it has passed,
+ *  `due now` for the first minute and `due n minutes ago` after (so an overdue take reads as overdue,
+ *  not as forever imminent); empty for an unparsable instant. */
+export function untilText(at: string, nowMs: number): string {
+  const diffMs = Date.parse(at) - nowMs;
+  if (!Number.isFinite(diffMs)) return "";
+  if (diffMs <= -60_000) return `due ${snapshotAgeText(at, nowMs)}`;
+  if (diffMs < 60_000) return "due now";
+  const minutes = Math.floor(diffMs / 60_000);
+  const unit = (n: number, word: string): string => `in ${n} ${word}${n === 1 ? "" : "s"}`;
+  if (minutes < 90) return unit(minutes, "minute");
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return unit(hours, "hour");
+  return unit(Math.round(hours / 24), "day");
+}