@coreplane/switchboard 1.204.0 → 1.206.0

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

@@ -0,0 +1,260 @@
+import { REPO_SLUG, type DeliveryRange, type PullRequestFacts } from "./delivery.js";
+import { errorSuffix } from "./workerError.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
+// invariant 2):
+//
+// - `WorkerDeliverySnapshotStore` — the production choice — an HTTPS client
+//   to the `DeliveryDO` on the state Worker (deploy/cloudflare-memory/, one
+//   SQLite Durable Object, the same MEMORY_TOKEN bearer as memory, run history
+//   and the schedule store), so a bot restart keeps the snapshot (invariant 6)
+//   and the first request after one is served, not computed.
+// - `InMemoryDeliverySnapshotStore` — 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 `isDeliverySnapshot` by
+// relative path so the bot and the Worker validate ONE shape.
+//
+// A snapshot is written whole once — the first read of a repository — and
+// patched by every refresh after: the rows the refresh re-read, the rows that
+// aged out of the window, the new meta. A busy repository's window is many MB
+// and its hourly change a few rows, so the write follows the change.
+//
+// Route contract (JSON in/out, bearer = the Worker's MEMORY_TOKEN):
+//   POST /delivery/get {repo}       → {snapshot: DeliverySnapshot | null}
+//   POST /delivery/put {snapshot}   → {ok: true, prs}          replace the repository's snapshot whole
+//   POST /delivery/merge {patch}    → {ok: true, prs} | 404    apply a refresh; 404 with no snapshot to merge into
+
+/** What a snapshot says about itself: everything but the rows. */
+export interface DeliverySnapshotMeta {
+  /** `owner/name`. */
+  repo: string;
+  /** ISO 8601 — when the read from GitHub began. */
+  snapshotAt: string;
+  /** The window the facts were read for: Monday-start weeks ending on the snapshot day. */
+  range: DeliveryRange;
+  /** The read stopped at its page cap before the window's start — the newest pull requests only. */
+  truncated: boolean;
+  /** ISO 8601 — every pull request merged at or after this instant is in `prs`: the window's
+   *  start on a complete read, the oldest update a capped listing reached otherwise. */
+  completeFrom: string;
+}
+
+/** One repository's facts as a source assembled them, and when. */
+export interface DeliverySnapshot extends DeliverySnapshotMeta {
+  /** Every pull request merged inside the window that the reads reached, in number order. */
+  prs: PullRequestFacts[];
+}
+
+/** What one refresh changes in a stored snapshot: the new meta, the rows the read re-read — they
+ *  replace the stored ones by number — and the numbers of the rows that aged out of the window. */
+export interface DeliverySnapshotPatch extends DeliverySnapshotMeta {
+  upsert: PullRequestFacts[];
+  drop: number[];
+}
+
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+const isInstant = (v: unknown): v is string => typeof v === "string" && Number.isFinite(Date.parse(v));
+
+/** The fields the arithmetic reads, present and of the right kind; the arrays' rows are the source's. */
+export function isPullRequestFacts(v: unknown): v is PullRequestFacts {
+  if (typeof v !== "object" || v === null) return false;
+  const p = v as Record<string, unknown>;
+  return (
+    typeof p.number === "number" &&
+    Number.isFinite(p.number) &&
+    typeof p.title === "string" &&
+    typeof p.author === "string" &&
+    isInstant(p.createdAt) &&
+    isInstant(p.mergedAt) &&
+    (p.updatedAt === undefined || isInstant(p.updatedAt)) &&
+    (p.firstHeadSha === undefined || typeof p.firstHeadSha === "string") &&
+    Array.isArray(p.ci) &&
+    Array.isArray(p.reviews) &&
+    Array.isArray(p.pushes) &&
+    (p.issue === undefined || (typeof p.issue === "object" && p.issue !== null))
+  );
+}
+
+/** The fields every snapshot document carries, present and of the right kind. */
+function hasSnapshotMeta(s: Record<string, unknown>): boolean {
+  if (typeof s.repo !== "string" || !REPO_SLUG.test(s.repo)) return false;
+  if (!isInstant(s.snapshotAt) || !isInstant(s.completeFrom)) return false;
+  if (typeof s.truncated !== "boolean") return false;
+  const range = s.range as Record<string, unknown> | null | undefined;
+  return (
+    typeof range === "object" &&
+    range !== null &&
+    typeof range.since === "string" &&
+    ISO_DAY.test(range.since) &&
+    typeof range.until === "string" &&
+    ISO_DAY.test(range.until) &&
+    typeof range.weeks === "number" &&
+    Number.isFinite(range.weeks)
+  );
+}
+
+export function isDeliverySnapshot(v: unknown): v is DeliverySnapshot {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  return hasSnapshotMeta(s) && Array.isArray(s.prs) && s.prs.every(isPullRequestFacts);
+}
+
+export function isDeliverySnapshotPatch(v: unknown): v is DeliverySnapshotPatch {
+  if (typeof v !== "object" || v === null) return false;
+  const { upsert, drop, ...meta } = v as Record<string, unknown>;
+  return (
+    hasSnapshotMeta(meta) &&
+    Array.isArray(upsert) &&
+    upsert.every(isPullRequestFacts) &&
+    Array.isArray(drop) &&
+    drop.every((n) => typeof n === "number" && Number.isFinite(n))
+  );
+}
+
+/** The snapshot a patch leaves behind when applied to `stored`: rows by number, in number order. */
+export function applyPatch(stored: DeliverySnapshot, patch: DeliverySnapshotPatch): DeliverySnapshot {
+  const { upsert, drop, ...meta } = patch;
+  const rows = new Map(stored.prs.map((p) => [p.number, p]));
+  for (const p of upsert) rows.set(p.number, p);
+  for (const n of drop) rows.delete(n);
+  return { ...meta, prs: [...rows.values()].sort((a, b) => a.number - b.number) };
+}
+
+export interface DeliverySnapshotStore {
+  /** The repository's stored snapshot, or undefined when none was ever stored. Throws on failure. */
+  get(repo: string): Promise<DeliverySnapshot | undefined>;
+  /** Replace the repository's snapshot whole. Throws on failure; callers warn, never crash. */
+  put(snapshot: DeliverySnapshot): Promise<void>;
+  /** Apply a refresh to the repository's stored snapshot. False when nothing is stored to merge
+   *  into — the caller then writes the snapshot whole. Throws on failure. */
+  merge(patch: DeliverySnapshotPatch): Promise<boolean>;
+}
+
+export class InMemoryDeliverySnapshotStore implements DeliverySnapshotStore {
+  private readonly byRepo = new Map<string, DeliverySnapshot>();
+
+  async get(repo: string): Promise<DeliverySnapshot | undefined> {
+    const s = this.byRepo.get(repo);
+    return s ? structuredClone(s) : undefined;
+  }
+
+  async put(snapshot: DeliverySnapshot): Promise<void> {
+    this.byRepo.set(snapshot.repo, structuredClone(snapshot));
+  }
+
+  async merge(patch: DeliverySnapshotPatch): Promise<boolean> {
+    const stored = this.byRepo.get(patch.repo);
+    if (!stored) return false;
+    this.byRepo.set(patch.repo, applyPatch(stored, structuredClone(patch)));
+    return true;
+  }
+}
+
+/** Per-request ceiling: a snapshot of a busy repository is a few MB each way. */
+export const SNAPSHOT_WORKER_TIMEOUT_MS = 30_000;
+
+export interface WorkerDeliverySnapshotStoreOptions {
+  /** 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 WorkerDeliverySnapshotStore implements DeliverySnapshotStore {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(private readonly opts: WorkerDeliverySnapshotStoreOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? fetch;
+  }
+
+  async get(repo: string): Promise<DeliverySnapshot | undefined> {
+    const res = await this.post("/delivery/get", { repo });
+    if (!res.ok) throw new Error(`state Worker /delivery/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 (!isDeliverySnapshot(data.snapshot))
+      throw new Error(`state Worker /delivery/get: the answer for ${repo} is not a delivery snapshot`);
+    return data.snapshot;
+  }
+
+  async put(snapshot: DeliverySnapshot): Promise<void> {
+    const res = await this.post("/delivery/put", { snapshot });
+    if (!res.ok) throw new Error(`state Worker /delivery/put HTTP ${res.status}${await errorSuffix(res)}`);
+  }
+
+  async merge(patch: DeliverySnapshotPatch): Promise<boolean> {
+    const res = await this.post("/delivery/merge", { patch });
+    // Nothing stored to merge into — or a Worker from before the route: either way the caller writes whole.
+    if (res.status === 404) return false;
+    if (!res.ok) throw new Error(`state Worker /delivery/merge HTTP ${res.status}${await errorSuffix(res)}`);
+    return true;
+  }
+
+  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(SNAPSHOT_WORKER_TIMEOUT_MS),
+    });
+  }
+}
+
+/** 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
+ *  warning naming what a restart then costs. Pure w.r.t. the environment. */
+export function buildDeliverySnapshotStore(
+  config: StateWorkerBlocks,
+  secrets: SecretReader,
+  warn: (message: string) => void,
+): DeliverySnapshotStore {
+  const worker = [config.runtimeOverrides, config.runHistory, config.schedules, config.memory].find(
+    (block) => block?.worker?.baseUrl,
+  )?.worker;
+  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.",
+    );
+    return new InMemoryDeliverySnapshotStore();
+  }
+  const tokenEnv = worker.tokenEnv ?? DEFAULT_TOKEN_ENV;
+  const token = secrets.named(tokenEnv);
+  if (!token) {
+    warn(
+      `the state Worker is configured but ${tokenEnv} is unset — delivery snapshots are kept in memory and a restart loses them. Set ${tokenEnv} to the state Worker's bearer.`,
+    );
+    return new InMemoryDeliverySnapshotStore();
+  }
+  return new WorkerDeliverySnapshotStore({ baseUrl: worker.baseUrl, token: token.reveal() });
+}

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

@@ -0,0 +1,296 @@
+// Deterministic review verdict → GitHub comment body.
+//
+// Downstream automation (a repository's opt-in `auto-approve-review-lgtm.yml`
+// workflow) approves a PR when the review App's review body STARTS WITH the
+// exact token `LGTM:`. That token must therefore never depend on how the model happens to
+// phrase its opening line. The model states its judgement through the
+// structured `submit_verdict` tool (src/tools/workspace.ts); this module turns
+// that structured value into the first line of the posted body:
+//
+//   approve          → "LGTM: <summary>"
+//   request_changes  → "Changes requested: <summary>"
+//   (no verdict)     → "No verdict submitted — not approving." (fail-closed)
+//
+// The model's prose follows after a blank line. Whatever the prose says, only
+// an explicit `approve` verdict can produce a body that begins with "LGTM".
+//
+// The verdict also carries typed findings (docs/reference/specs/agent-ship.md item 6):
+// one compact entry per issue, rendered as a list under the verdict line, so
+// a fix round can reference each finding by its stable id and answer it with
+// a typed disposition (`parseDispositionsInput` below). Findings validate
+// fail-closed PER finding — a malformed finding drops with a note, a
+// malformed array drops the whole field — and an `approve` carrying a
+// self-declared `blocking` finding is downgraded to `request_changes`, so the
+// posted body can never begin with `LGTM:` over a defect the reviewer itself
+// called blocking.
+
+import { normalizeHead } from "./reviewedHead.js";
+import { redactSecrets } from "./redact.js";
+
+export type ReviewVerdictKind = "approve" | "request_changes";
+
+export const FINDING_SEVERITIES = ["blocking", "major", "minor", "nit"] as const;
+export type FindingSeverity = (typeof FINDING_SEVERITIES)[number];
+
+export interface Finding {
+  /** Stable id the reviewer assigned in order ("F1", "F2", …) — dispositions
+   *  reference findings by this id. */
+  id: string;
+  severity: FindingSeverity;
+  /** Repo-relative file the finding points at. */
+  file: string;
+  /** Optional 1-based line. An unusable value is dropped like a malformed
+   *  `head` — the finding stands without it. */
+  line?: number;
+  /** One line naming the issue; the full explanation lives in the prose. */
+  title: string;
+}
+
+export interface ReviewVerdict {
+  verdict: ReviewVerdictKind;
+  /** One line: why. Newlines are collapsed so the token line stays one line. */
+  summary: string;
+  /** The commit the agent says it reviewed (`git rev-parse HEAD` in its
+   *  checkout), 7–40 lowercase hex. The dispatcher's reviewed-head guard
+   *  (reviewedHead.ts) compares it to the PR head when the workspace HEAD
+   *  could not be observed directly. Absent when not supplied or malformed. */
+  head?: string;
+  /** Typed findings enumerated through `submit_verdict`. Present only when
+   *  the input carried a findings array (possibly empty after drops); absent
+   *  when no array was supplied or the array itself was malformed. */
+  findings?: Finding[];
+  /** Parse notes naming what was dropped from `findings` (ids/indices with
+   *  reasons) — surfaced in the tool ack so the model can resubmit, never
+   *  rendered into the posted body. */
+  droppedFindings?: string[];
+}
+
+export const LGTM_TOKEN = "LGTM:";
+export const CHANGES_TOKEN = "Changes requested:";
+export const NO_VERDICT_LINE = "No verdict submitted — not approving.";
+
+/** Parse an arbitrary tool input into a verdict, or null when it is not one. */
+export function parseVerdictInput(input: Record<string, unknown>): ReviewVerdict | null {
+  const verdict = input.verdict;
+  if (verdict !== "approve" && verdict !== "request_changes") return null;
+  const summary = typeof input.summary === "string" ? oneLine(input.summary) : "";
+  const head = normalizeHead(input.head);
+  const out: ReviewVerdict = { verdict, summary };
+  if (head) out.head = head;
+  if (input.findings !== undefined) {
+    const parsed = parseFindings(input.findings);
+    if (parsed.findings) out.findings = parsed.findings;
+    if (parsed.dropped.length) out.droppedFindings = parsed.dropped;
+    // Verdict/severity consistency, fail-closed: an approve carrying a
+    // blocking finding downgrades so the posted body can never start with
+    // `LGTM:` over a self-declared blocking defect. Keyed on the RAW entries'
+    // declared severity, not the validated survivors — a blocking entry that
+    // itself failed validation and dropped still poisons the approve.
+    if (out.verdict === "approve" && parsed.blocking.length > 0) {
+      out.verdict = "request_changes";
+      out.summary = oneLine(
+        `${out.summary} [downgraded from approve: blocking finding${parsed.blocking.length === 1 ? "" : "s"} ${parsed.blocking.join(", ")}]`,
+      );
+    }
+  }
+  return out;
+}
+
+/** Fail-closed per finding: each malformed entry drops with a note naming its
+ *  index (and id when readable); a non-array drops the whole field.
+ *  `blocking` labels every raw entry that declared severity "blocking" —
+ *  valid or not — for the approve downgrade above. */
+function parseFindings(value: unknown): { findings?: Finding[]; dropped: string[]; blocking: string[] } {
+  if (!Array.isArray(value)) {
+    return { dropped: ["findings: dropped — not an array"], blocking: [] };
+  }
+  const findings: Finding[] = [];
+  const dropped: string[] = [];
+  const blocking: string[] = [];
+  value.forEach((raw, i) => {
+    const parsed = parseFinding(raw);
+    if (parsed.finding) {
+      findings.push(parsed.finding);
+    } else {
+      dropped.push(`findings[${i}]${parsed.id ? ` (${parsed.id})` : ""}: dropped — ${parsed.reason}`);
+    }
+    const label = parsed.finding?.id ?? parsed.id ?? `findings[${i}]`;
+    const r = typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : undefined;
+    if (r?.severity === "blocking") blocking.push(label);
+  });
+  return { findings, dropped, blocking };
+}
+
+function parseFinding(
+  raw: unknown,
+): { finding: Finding; id?: never; reason?: never } | { finding?: never; id?: string; reason: string } {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { reason: "not an object" };
+  const r = raw as Record<string, unknown>;
+  const id = typeof r.id === "string" ? oneLine(r.id) : "";
+  if (!id) return { reason: "missing or empty id" };
+  const severity = r.severity;
+  if (!(FINDING_SEVERITIES as readonly unknown[]).includes(severity)) {
+    return { id, reason: `invalid severity ${JSON.stringify(r.severity)} (expected ${FINDING_SEVERITIES.join("|")})` };
+  }
+  const file = typeof r.file === "string" ? oneLine(r.file) : "";
+  if (!file) return { id, reason: "missing or empty file" };
+  const title = typeof r.title === "string" ? oneLine(r.title) : "";
+  if (!title) return { id, reason: "missing or empty title" };
+  const finding: Finding = { id, severity: severity as FindingSeverity, file, title };
+  // Like `head`: an unusable optional locator is dropped, the finding stands —
+  // dropping the whole finding over a bad line would also drop the severity
+  // that the approve→request_changes downgrade keys on.
+  if (typeof r.line === "number" && Number.isInteger(r.line) && r.line >= 1) finding.line = r.line;
+  return { finding };
+}
+
+function oneLine(s: string): string {
+  return s.replace(/\s*\n+\s*/g, " ").trim();
+}
+
+/** The exact first line of the posted body for a verdict (or its absence). */
+export function verdictLine(verdict: ReviewVerdict | undefined): string {
+  if (!verdict) return NO_VERDICT_LINE;
+  const token = verdict.verdict === "approve" ? LGTM_TOKEN : CHANGES_TOKEN;
+  const summary = oneLine(verdict.summary);
+  return summary ? `${token} ${summary}` : token;
+}
+
+/** One compact finding line — `[severity] id file[:line] — title` — shared by
+ *  the posted body's list (bulleted below) and ship's synthesized child turns. */
+export function formatFinding(f: Finding): string {
+  const location = f.line !== undefined ? `${f.file}:${f.line}` : f.file;
+  return `[${f.severity}] ${f.id} ${location} — ${f.title}`;
+}
+
+/**
+ * Build the body posted to GitHub: the deterministic verdict line, the
+ * compact findings list (when present), a blank line, then the model's
+ * review text. Never starts with "LGTM" unless the verdict is `approve`.
+ */
+export function buildReviewPostBody(answer: string, verdict: ReviewVerdict | undefined): string {
+  const head = [verdictLine(verdict), ...(verdict?.findings ?? []).map((f) => `- ${formatFinding(f)}`)];
+  return `${head.join("\n")}\n\n${answer.trim()}`;
+}
+
+// --- Dispositions (the coding side's answer to findings) -------------------
+//
+// A fix round records one disposition per finding through the
+// `submit_dispositions` tool; the ship orchestrator keeps the last valid set
+// and splits a cap report into declined (disposition recorded) vs unaddressed
+// (none). Validation mirrors the findings above: a malformed entry drops with
+// a note; a non-array input rejects the whole call.
+
+export type DispositionKind = "fixed" | "declined";
+
+export interface FindingDisposition {
+  /** The stable finding id from the review verdict this disposition answers. */
+  findingId: string;
+  disposition: DispositionKind;
+  /** One line: what was done, or why the finding was declined. */
+  note: string;
+}
+
+/**
+ * Parse a `submit_dispositions` input. Null when `dispositions` is not an
+ * array (the call is rejected, nothing recorded); otherwise each malformed
+ * entry drops with a note naming its index (and findingId when readable),
+ * mirroring the per-finding validation above. A missing note is tolerated as
+ * "" (the summary convention), never a dropped entry.
+ */
+export function parseDispositionsInput(
+  input: Record<string, unknown>,
+): { dispositions: FindingDisposition[]; dropped: string[] } | null {
+  const value = input.dispositions;
+  if (!Array.isArray(value)) return null;
+  const dispositions: FindingDisposition[] = [];
+  const dropped: string[] = [];
+  value.forEach((raw, i) => {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      dropped.push(`dispositions[${i}]: dropped — not an object`);
+      return;
+    }
+    const r = raw as Record<string, unknown>;
+    const findingId = typeof r.findingId === "string" ? oneLine(r.findingId) : "";
+    if (!findingId) {
+      dropped.push(`dispositions[${i}]: dropped — missing or empty findingId`);
+      return;
+    }
+    const disposition = r.disposition;
+    if (disposition !== "fixed" && disposition !== "declined") {
+      dropped.push(
+        `dispositions[${i}] (${findingId}): dropped — invalid disposition ${JSON.stringify(r.disposition)} (expected fixed|declined)`,
+      );
+      return;
+    }
+    const note = typeof r.note === "string" ? oneLine(r.note) : "";
+    dispositions.push({ findingId, disposition, note });
+  });
+  return { dispositions, dropped };
+}
+
+// ---- the stored shapes (docs/reference/specs/run-history.md items 2 and 3) ---------------------------
+
+const VERDICT_KINDS: readonly string[] = ["approve", "request_changes"];
+const DISPOSITION_KINDS: readonly string[] = ["fixed", "declined"];
+
+const isRecordLike = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
+
+function isFindingShape(v: unknown): v is Finding {
+  if (!isRecordLike(v)) return false;
+  return (
+    typeof v.id === "string" &&
+    (FINDING_SEVERITIES as readonly string[]).includes(v.severity as string) &&
+    typeof v.file === "string" &&
+    typeof v.title === "string" &&
+    (v.line === undefined || typeof v.line === "number")
+  );
+}
+
+/** Structural check on a verdict read back from a stored record: the kind, a
+ *  string summary, an optional string head, findings each with an id, a known
+ *  severity, a file and a title. Shape only, no bounds — what a record carries
+ *  was validated by `parseVerdictInput` on the way in and redacted since. */
+export function isReviewVerdictShape(v: unknown): v is ReviewVerdict {
+  if (!isRecordLike(v)) return false;
+  if (!VERDICT_KINDS.includes(v.verdict as string) || typeof v.summary !== "string") return false;
+  if (v.head !== undefined && typeof v.head !== "string") return false;
+  if (v.findings !== undefined && !(Array.isArray(v.findings) && v.findings.every(isFindingShape))) return false;
+  return true;
+}
+
+/** Structural check on a disposition set read back from a stored record. */
+export function isFindingDispositionsShape(v: unknown): v is FindingDisposition[] {
+  return (
+    Array.isArray(v) &&
+    v.every(
+      (d) =>
+        isRecordLike(d) &&
+        typeof d.findingId === "string" &&
+        DISPOSITION_KINDS.includes(d.disposition as string) &&
+        typeof d.note === "string",
+    )
+  );
+}
+
+/** Every string leaf of the verdict through the redaction seam — the summary,
+ *  each finding's file and title — the input untouched: what the one record
+ *  assembly writes. `droppedFindings` are parse notes for the model and never
+ *  ride a record. */
+export function redactVerdict(v: ReviewVerdict, redact: (s: string) => string = redactSecrets): ReviewVerdict {
+  return {
+    verdict: v.verdict,
+    summary: redact(v.summary),
+    ...(v.head !== undefined ? { head: v.head } : {}),
+    ...(v.findings !== undefined
+      ? { findings: v.findings.map((f) => ({ ...f, file: redact(f.file), title: redact(f.title) })) }
+      : {}),
+  };
+}
+
+export function redactDispositions(
+  dispositions: readonly FindingDisposition[],
+  redact: (s: string) => string = redactSecrets,
+): FindingDisposition[] {
+  return dispositions.map((d) => ({ findingId: d.findingId, disposition: d.disposition, note: redact(d.note) }));
+}

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

@@ -0,0 +1,77 @@
+// Reviewed-head guard for the review post-step (docs/reference/specs/agent-review.md item 8).
+//
+// A review may only be posted to a PR when the commit the agent ACTUALLY
+// reviewed is the PR head resolved for the run (`RepoContext.headSha`). The
+// failure this guards against: the agent's own worktree is on the right
+// branch, but it fetches and checks out another PR's branch because the PR
+// body references it, reviews that, calls `submit_verdict approve`, and the
+// deterministic post-step puts `LGTM:` on the PR under review — which an
+// auto-approve workflow then approves. Every layer has done its job except the
+// one that asks "is this review OF this PR?".
+//
+// Two sources for the reviewed head, in authority order:
+//   observed — `git rev-parse HEAD` run by the dispatcher in the run's
+//              workspace AFTER the model finished and BEFORE the workspace is
+//              released (a resident worktree; authoritative). Absent when the
+//              cwd is not a git repo (the cold sandbox's workspace root — the
+//              clone lives in a subdirectory the agent chose).
+//   reported — the `head` the agent passed to `submit_verdict` (it is told to
+//              run `git rev-parse HEAD` in the checkout it reviewed). Consulted
+//              only when nothing was observed; an observed mismatch is never
+//              rescued by a matching report.
+//
+// Fail-closed: unknown PR head, or no head from either source → no post.
+
+export type HeadCheck = { ok: true; head: string; source: "observed" | "reported" } | { ok: false; reason: string };
+
+const FULL_SHA = /^[0-9a-f]{40}$/;
+const SHA_PREFIX = /^[0-9a-f]{7,40}$/;
+
+/** Normalize a reported/observed head: trimmed, lowercased, 7–40 hex; else undefined. */
+export function normalizeHead(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const h = value.trim().toLowerCase();
+  return SHA_PREFIX.test(h) ? h : undefined;
+}
+
+/** The 40-hex commit from `git rev-parse HEAD` output, or undefined when the
+ *  command failed (not a git repo, git missing) or printed nothing usable. */
+export function parseRevParseOutput(output: string): string | undefined {
+  for (const line of output.split(/\r?\n/)) {
+    const t = line.trim().toLowerCase();
+    if (FULL_SHA.test(t)) return t;
+  }
+  return undefined;
+}
+
+/** Two normalized heads name the same commit when one is a ≥7-hex prefix of
+ *  the other (the dispatcher's pre-run attach check reuses this). */
+export function sameCommit(a: string, b: string): boolean {
+  const n = Math.min(a.length, b.length);
+  return n >= 7 && a.slice(0, n) === b.slice(0, n);
+}
+
+/**
+ * Decide whether the reviewed head is the PR head. `expected` is the PR head
+ * from repo resolution; `observed` the dispatcher's own `git rev-parse HEAD`
+ * (40-hex or undefined); `reported` whatever the agent passed to submit_verdict.
+ */
+export function checkReviewedHead(input: { expected?: string; observed?: string; reported?: string }): HeadCheck {
+  const expected = normalizeHead(input.expected);
+  if (!expected) return { ok: false, reason: "PR head unknown at resolution time — cannot verify what was reviewed" };
+  const observed = normalizeHead(input.observed);
+  if (observed) {
+    return sameCommit(observed, expected)
+      ? { ok: true, head: observed, source: "observed" }
+      : { ok: false, reason: `reviewed head ${observed.slice(0, 7)} is not the PR head ${expected.slice(0, 7)}` };
+  }
+  const reported = normalizeHead(input.reported);
+  if (!reported)
+    return {
+      ok: false,
+      reason: "reviewed head unknown — the workspace HEAD could not be read and no head was reported with the verdict",
+    };
+  return sameCommit(reported, expected)
+    ? { ok: true, head: reported, source: "reported" }
+    : { ok: false, reason: `reviewed head ${reported.slice(0, 7)} is not the PR head ${expected.slice(0, 7)}` };
+}

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

@@ -319,8 +319,10 @@ export type RunEvent =
       text: string;
       /** Where the request came from, for the Request block: the channel and
        *  user display names and a link back to the triggering message —
-       *  whatever the adapter supplied (all optional). */
-      source?: { url?: string; channel?: string; user?: string };
+       *  whatever the adapter supplied (all optional) — and, for a follow-up a
+       *  run sent rather than a person (a parent's `send_to_run`), that run's
+       *  id (docs/reference/specs/agent-conductor.md item 8). */
+      source?: { url?: string; channel?: string; user?: string; run?: string };
       seq?: number;
       at?: number;
     }

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

@@ -9,7 +9,7 @@ import type { ClaimResult, FenceResult, LivePhase } from "./types.js";
  *  after a lost response), anything else is refused with what the steer
  *  message needs. */
 export function decideClaim(
-  existing: { runId: string; agent?: string; startedAt: number; ownerGen: string } | undefined,
+  existing: { runId: string; agent?: string; startedAt: number; ownerGen: string; idempotencyKey?: string } | undefined,
   req: { runId: string; gen: string },
 ): ClaimResult {
   if (!existing) return { ok: true };
@@ -21,6 +21,7 @@ export function decideClaim(
       runId: existing.runId,
       ...(existing.agent !== undefined ? { agent: existing.agent } : {}),
       startedAt: existing.startedAt,
+      ...(existing.idempotencyKey !== undefined ? { idempotencyKey: existing.idempotencyKey } : {}),
     },
   };
 }