@coreplane/switchboard 1.213.0 → 1.215.0

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

@@ -0,0 +1,187 @@
+// The transcript on the wire (docs/reference/specs/run-history.md item 32). The runner's
+// `messages` array is append-only, so the durable form is one row per content
+// part: no row nears the Durable Object's 2 MB limit, a step writes only its
+// new turns, and the read side assembles the exact array — thinking blocks and
+// all — or names the gap. Base64 attachment data over a threshold is stored
+// once and referenced, so a 20 MB PDF in the seed is one attachment row, not
+// a 20 MB part row.
+
+import type { ChatMessage, ContentPart } from "../../providers/types.js";
+import { utf8ByteLength } from "../runRecord.js";
+import {
+  ATTACHMENT_REF_BYTES,
+  TRANSCRIPT_PART_BYTES,
+  type CompactionEntry,
+  type TranscriptAttachment,
+  type TranscriptRow,
+} from "./types.js";
+
+// Every budget here is in UTF-8 BYTES, measured with `utf8ByteLength`, because
+// the fences they must stay under are bytes: the Worker's Content-Length check
+// and the Durable Object's row limit. `String.length` counts UTF-16 code units,
+// and JSON.stringify leaves non-ASCII literal, so a 1.4M-character CJK part is
+// ~4.2 MB on the wire.
+
+/** The stored form of one part: the turn's role rides on every row so a turn
+ *  is reconstructible from its rows alone. */
+export interface StoredPart {
+  role: ChatMessage["role"];
+  part: ContentPart | (ContentPart & { dataRef: string });
+}
+
+/** The stored form of a compaction row: no role, no part — the entry alone. */
+export interface StoredCompaction {
+  compaction: CompactionEntry;
+}
+
+export type StoredRow = StoredPart | StoredCompaction;
+
+const attachmentRef = (idx: number, part: number) => `t${idx}p${part}`;
+
+function hasData(part: ContentPart): part is ContentPart & { data: string; mediaType: string } {
+  return (part.type === "image" || part.type === "document") && typeof (part as { data?: unknown }).data === "string";
+}
+
+const isCompaction = (v: ChatMessage | StoredCompaction): v is StoredCompaction => "compaction" in v;
+
+/** One turn → its rows (and any externalized attachments). Refuses a part the
+ *  row budget cannot hold: a transcript is never truncated. A compaction entry
+ *  is one row at its index, part 0. */
+export function turnRows(
+  idx: number,
+  message: ChatMessage | StoredCompaction,
+  opts: { partBytes?: number; attachmentRefBytes?: number } = {},
+): { rows: TranscriptRow[]; attachments: TranscriptAttachment[] } {
+  const partBytes = opts.partBytes ?? TRANSCRIPT_PART_BYTES;
+  const refBytes = opts.attachmentRefBytes ?? ATTACHMENT_REF_BYTES;
+  const rows: TranscriptRow[] = [];
+  const attachments: TranscriptAttachment[] = [];
+  if (isCompaction(message)) {
+    const json = JSON.stringify({ compaction: message.compaction } satisfies StoredCompaction);
+    const bytes = utf8ByteLength(json);
+    if (bytes > partBytes) {
+      throw new Error(
+        `transcript: the compaction row at turn ${idx} is ${bytes} bytes, over the ${partBytes} row budget`,
+      );
+    }
+    return { rows: [{ idx, part: 0, json }], attachments };
+  }
+  message.content.forEach((part, i) => {
+    let stored: StoredPart["part"] = part;
+    if (hasData(part) && part.data.length > refBytes) {
+      const ref = attachmentRef(idx, i);
+      attachments.push({ ref, mediaType: part.mediaType, data: part.data });
+      stored = { ...(part as ContentPart), data: "", dataRef: ref } as StoredPart["part"];
+    }
+    const json = JSON.stringify({ role: message.role, part: stored } satisfies StoredPart);
+    const bytes = utf8ByteLength(json);
+    if (bytes > partBytes) {
+      throw new Error(`transcript: part ${i} of turn ${idx} is ${bytes} bytes, over the ${partBytes} row budget`);
+    }
+    rows.push({ idx, part: i, json });
+  });
+  return { rows, attachments };
+}
+
+/** Pack rows into requests whose JSON stays under `maxBytes`, in order. A
+ *  single row larger than the fence travels alone (the row budget already
+ *  bounds it below the fence in production). */
+export function chunkRows(rows: readonly TranscriptRow[], maxBytes: number): TranscriptRow[][] {
+  const chunks: TranscriptRow[][] = [];
+  let current: TranscriptRow[] = [];
+  let size = 2; // the array brackets
+  for (const row of rows) {
+    const rowSize = utf8ByteLength(JSON.stringify(row)) + 1;
+    if (current.length > 0 && size + rowSize > maxBytes) {
+      chunks.push(current);
+      current = [];
+      size = 2;
+    }
+    current.push(row);
+    size += rowSize;
+  }
+  if (current.length > 0) chunks.push(current);
+  return chunks;
+}
+
+/** A compaction row as the assembled transcript reports it: the entry, the
+ *  index in `messages` of the first message after it (`before`), and — when
+ *  the entry names `keptFrom` and that row is in the assembled span — the
+ *  index in `messages` of the message pi kept first. */
+export interface AssembledCompaction {
+  before: number;
+  entry: CompactionEntry;
+  keptBefore?: number;
+}
+
+export type AssembledTranscript =
+  | { complete: true; turns: number; messages: ChatMessage[]; compactions: AssembledCompaction[] }
+  | { complete: false; turns: number; messages: ChatMessage[]; compactions: AssembledCompaction[]; gap: string };
+
+/** Rows (any order) → the turns, contiguous from `base` (a log index; 0 for a
+ *  run's own object), as a conversation counted from 0. `turns` counts every
+ *  row index — a compaction row included, since the step records count it —
+ *  while `messages` carries the conversation alone and `compactions` says
+ *  where each entry sits in it. Stops at the first gap and says where it is;
+ *  the turns before it are returned so an `interrupted` record can still carry
+ *  what was stored. */
+export function assembleTranscript(
+  rows: readonly TranscriptRow[],
+  attachments: readonly TranscriptAttachment[],
+  base = 0,
+): AssembledTranscript {
+  const byRef = new Map(attachments.map((a) => [a.ref, a]));
+  const byTurn = new Map<number, Map<number, StoredRow>>();
+  for (const row of rows) {
+    const idx = row.idx - base;
+    let parts = byTurn.get(idx);
+    if (!parts) byTurn.set(idx, (parts = new Map()));
+    parts.set(row.part, JSON.parse(row.json) as StoredRow);
+  }
+  const messages: ChatMessage[] = [];
+  const compactions: AssembledCompaction[] = [];
+  /** The `messages` index each turn index landed at (a compaction row lands nowhere). */
+  const messageIndexOf = new Map<number, number>();
+  const gap = (why: string): AssembledTranscript => ({
+    complete: false,
+    turns: messages.length + compactions.length,
+    messages,
+    compactions,
+    gap: why,
+  });
+  const turnCount = byTurn.size === 0 ? 0 : Math.max(...byTurn.keys()) + 1;
+  for (let idx = 0; idx < turnCount; idx++) {
+    const parts = byTurn.get(idx);
+    if (!parts) return gap(`turn ${idx} is missing`);
+    const first = parts.get(0);
+    if (first && "compaction" in first) {
+      compactions.push({ before: messages.length, entry: first.compaction });
+      continue;
+    }
+    const content: ContentPart[] = [];
+    let role: ChatMessage["role"] | undefined;
+    const partCount = Math.max(...parts.keys()) + 1;
+    for (let p = 0; p < partCount; p++) {
+      const stored = parts.get(p);
+      if (!stored || "compaction" in stored) return gap(`turn ${idx} is missing part ${p}`);
+      role = stored.role;
+      const part = stored.part as ContentPart & { dataRef?: string };
+      if (part.dataRef !== undefined) {
+        const att = byRef.get(part.dataRef);
+        if (!att) return gap(`attachment ${part.dataRef} is missing`);
+        const { dataRef: _ref, ...rest } = part;
+        content.push({ ...rest, data: att.data } as ContentPart);
+      } else {
+        content.push(part);
+      }
+    }
+    messageIndexOf.set(idx, messages.length);
+    messages.push({ role: role ?? "user", content });
+  }
+  for (const c of compactions) {
+    if (c.entry.keptFrom === undefined) continue;
+    const kept = messageIndexOf.get(c.entry.keptFrom - base);
+    if (kept !== undefined) c.keptBefore = kept;
+  }
+  return { complete: true, turns: messages.length + compactions.length, messages, compactions };
+}

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

@@ -7,6 +7,7 @@ import type { ChatMessage, ToolDef } from "../../providers/types.js";
 import type { ChannelVisibility } from "../authz/types.js";
 import type { RunProfile } from "../../config/profile.js";
 import type { RunEvent } from "../runEvents.js";
+import type { RunSeed, RunSession } from "../runRecord.js";
 
 /** How long a generation's claim on a run lasts without a heartbeat. */
 export const LEASE_MS = 30_000;
@@ -69,6 +70,15 @@ export interface LiveRunMeta {
    *  still sends the parent its event and a retried spawn finds its run. */
   parentInstanceId?: string;
   idempotencyKey?: string;
+  /** Where the run's conversation started (item 52), so a reclaimed run's
+   *  record still says so: `parent` for a spawned child, `channel` otherwise. */
+  seed?: RunSeed;
+  /** The run's place in its session's log (docs/reference/specs/session-log.md item
+   *  2): set at the claim, so a resume reads the rows from `seedFrom` and
+   *  continues appending at its indices. Absent on rows claimed before the
+   *  session log existed — those resume from their own transcript object —
+   *  and on runs without a conversation of their own. */
+  session?: RunSession;
   /** Which executor the run attached: what `makeExecutor` chose. */
   selection?: "resident" | "sandbox" | "local" | "none";
   /** The worktree path the system prompt names. */
@@ -190,10 +200,21 @@ export interface TranscriptAttachment {
   data: string;
 }
 
-/** The turns a step write carries: the previous step's results and this step's assistant turn. */
-export interface TranscriptTurn {
-  idx: number;
-  message: ChatMessage;
+/** pi's compaction entry as the log stores it (docs/reference/specs/session-log.md item
+ *  6): the summary pi wrote of everything before the row, the size it replaced,
+ *  pi's own id for the first entry it kept (forensics: it names nothing in a
+ *  rebuilt file) and, when the mirror can say, `keptFrom` — the log index of
+ *  that entry — so a rebuilt session keeps what pi kept. */
+export interface CompactionEntry {
+  summary: string;
+  tokensBefore?: number;
+  firstKeptEntryId?: string;
+  keptFrom?: number;
 }
 
+/** The rows a step write carries, each at its log index: the previous step's
+ *  results and this step's assistant turn as messages, and pi's compaction
+ *  entry as a row of its own between them. */
+export type TranscriptTurn = { idx: number; message: ChatMessage } | { idx: number; compaction: CompactionEntry };
+
 export type AppendableEvent = RunEvent & { seq: number };

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

@@ -145,6 +145,52 @@ export interface RunRecord {
    *  item 48), stored at the claim so a retried spawn finds its run. Present
    *  exactly when `parentInstanceId` is — both or neither, never one alone. */
   idempotencyKey?: string;
+  /** Where the run's conversation started (item 52): `channel` — its own
+   *  thread's history, as for every run a person, a schedule or a coordinator
+   *  started — or `parent` — a spawned child seeded from its parent's text
+   *  turns at the spawn (`DispatchOptions.seed`). Absent on records written
+   *  before it existed. */
+  seed?: RunSeed;
+  /** The run as a range of its session's log (item 53; docs/reference/specs/session-log.md):
+   *  the object's key, the log index its seed began at, its request row and
+   *  the rows it appended — closed at finish, or `broken` when a refused or
+   *  failed write detached the run and its later turns never landed. Absent
+   *  on records written before the session log existed and on runs without
+   *  a conversation of their own. */
+  session?: RunSession;
+}
+
+/** The two places a run's conversation can start (item 52). */
+export const RUN_SEEDS = ["channel", "parent"] as const;
+export type RunSeed = (typeof RUN_SEEDS)[number];
+
+/** A session log's name: `<threadKey>:<agent>` (docs/reference/specs/session-log.md item 1). */
+export const SESSION_KEY_PATTERN = /^[A-Za-z0-9_.:@+/-]{1,512}$/;
+
+/** Where a run sits in its session's log (session-log item 2): `seedFrom` is
+ *  the first log index its seed included, `request` the index of its request
+ *  row, `range.from` the first row it appended and `range.to` the last, set
+ *  at finish; `broken` says the run detached from the ledger and the log
+ *  ends short of what the model saw. */
+export interface RunSession {
+  key: string;
+  seedFrom: number;
+  request: number;
+  range: { from: number; to?: number } | "broken";
+}
+
+const isIndex = (v: unknown): v is number => typeof v === "number" && Number.isInteger(v) && v >= 0;
+
+export function isRunSession(v: unknown): v is RunSession {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v as Record<string, unknown>;
+  if (typeof s.key !== "string" || !SESSION_KEY_PATTERN.test(s.key)) return false;
+  if (!isIndex(s.seedFrom) || !isIndex(s.request) || s.request < s.seedFrom) return false;
+  if (s.range === "broken") return true;
+  if (typeof s.range !== "object" || s.range === null) return false;
+  const range = s.range as Record<string, unknown>;
+  if (!isIndex(range.from) || range.from < s.seedFrom) return false;
+  return range.to === undefined || (isIndex(range.to) && range.to >= range.from);
 }
 
 /** The profile as the record stores it: the run's effective profile plus the preset it came from. */
@@ -383,6 +429,10 @@ export interface RetentionPolicy {
   retentionDays: number;
   maxRuns: number;
   maxBytes: number;
+  /** The most bytes one session log holds (docs/reference/specs/session-log.md item 5):
+   *  past it the object replaces its oldest tool results with a marker;
+   *  `maxBytes` bounds the run records alone. */
+  sessionLogMaxBytes: number;
 }
 
 const KIB = 1024;
@@ -393,6 +443,7 @@ export const DEFAULT_RETENTION_POLICY: Readonly<RetentionPolicy> = {
   retentionDays: 30,
   maxRuns: 5000,
   maxBytes: 2 * GIB,
+  sessionLogMaxBytes: 200 * MIB,
 };
 
 /** Inclusive `[min, max]` per policy field. */
@@ -400,6 +451,7 @@ export const RETENTION_BOUNDS: Readonly<Record<keyof RetentionPolicy, readonly [
   retentionDays: [1, 365],
   maxRuns: [1, 20_000],
   maxBytes: [16 * MIB, 8 * GIB],
+  sessionLogMaxBytes: [16 * MIB, 2 * GIB],
 };
 
 /** Fill a partial policy from the defaults and clamp every field into its
@@ -411,7 +463,12 @@ export function clampRetentionPolicy(partial: Partial<RetentionPolicy>): Retenti
     const [lo, hi] = RETENTION_BOUNDS[k];
     return Math.min(hi, Math.max(lo, n));
   };
-  return { retentionDays: field("retentionDays"), maxRuns: field("maxRuns"), maxBytes: field("maxBytes") };
+  return {
+    retentionDays: field("retentionDays"),
+    maxRuns: field("maxRuns"),
+    maxBytes: field("maxBytes"),
+    sessionLogMaxBytes: field("sessionLogMaxBytes"),
+  };
 }
 
 // ---- validation -------------------------------------------------------------
@@ -515,6 +572,10 @@ export function isRunRecord(v: unknown): v is RunRecord {
   // A parent is named by a run id (item 46): the same shape as the record's own.
   if (r.parentRunId !== undefined && (typeof r.parentRunId !== "string" || !RUN_ID_PATTERN.test(r.parentRunId)))
     return false;
+  // Where the conversation started (item 52): one of the two words, or absent.
+  if (r.seed !== undefined && !RUN_SEEDS.includes(r.seed as RunSeed)) return false;
+  // The run's place in its session's log (item 53), or absent.
+  if (r.session !== undefined && !isRunSession(r.session)) return false;
   // A coordinator's child (item 48): the instance id in the platform's alphabet
   // and the key `<instance>:<step>` — both or neither; one alone is no tag.
   if ((r.parentInstanceId === undefined) !== (r.idempotencyKey === undefined)) return false;

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

@@ -283,22 +283,26 @@ export function cursorFinished(cursor: PlanCursor): boolean {
 
 // ---- the unit pipeline: shapes --------------------------------------------------------------------
 
-export type RoundKind = "coding" | "review" | "fix";
+/** `findings` is the step after a verdict that requests changes: the review's
+ *  findings dispatched into the unit thread as `agent:coding`, so the coding
+ *  session there continues with them (record 0034). Never a `fix` child briefed
+ *  from the review. */
+export type RoundKind = "coding" | "review" | "findings";
 export interface RoundRef {
-  /** Round 0 is the coding round; review round n and its fix round share n. */
+  /** Round 0 is the coding round; review round n and its findings step share n. */
   index: number;
   kind: RoundKind;
 }
 export type ChildPreset = "coding" | "review";
 
-/** The preset a round's child runs as: a fix round is a coding child. */
+/** The preset a round's child runs as: the findings step's run is a coding run. */
 export function presetOf(kind: RoundKind): ChildPreset {
   return kind === "review" ? "review" : "coding";
 }
 
 /** How a spawn's child is briefed — ids only, never text. The bot composes the
  *  turn: the unit's contract, or the review turn from the pull request and the
- *  prior rounds' records, or the fix turn from the review run's verdict. */
+ *  prior rounds' records, or the findings message from the review run's verdict. */
 export type Brief =
   | { kind: "contract"; unit: string; rebase: { branch: string; onto: string } }
   | {
@@ -307,10 +311,10 @@ export type Brief =
       pr: number;
       headSha?: string;
       round: number;
-      /** The previous review round's run and the fix round that answered it, for a re-review. */
-      prior?: { reviewRunId: string; fixRunId?: string };
+      /** The previous review round's run and the coding run that answered its findings, for a re-review. */
+      prior?: { reviewRunId: string; codingRunId?: string };
     }
-  | { kind: "fix"; unit: string; pr: number; reviewRunId: string };
+  | { kind: "findings"; unit: string; pr: number; reviewRunId: string };
 
 export interface PrRef {
   number: number;
@@ -351,7 +355,7 @@ export type ChildFacts =
       /** Why the child recorded no post, when it recorded one it chose or failed. */
       reviewPostReason?: string;
       reviewHead?: string;
-      /** A fix child's dispositions. */
+      /** The dispositions a coding run recorded, as it submitted them: the machine matches them to the round's findings. */
       dispositions?: FindingDisposition[];
       handoff?: boolean;
     };
@@ -451,13 +455,16 @@ export interface UnitPipelineState {
   readonly pr?: PrRef;
   readonly lastReviewHead?: string;
   readonly lastVerdictSummary?: string;
-  /** Findings per review round and dispositions per fix round, keyed by the
-   *  review round they belong to — finding ids are unique within one round only. */
+  /** Findings per review round and the dispositions the round's findings step
+   *  recorded against them, keyed by the review round they belong to — finding
+   *  ids are unique within one round only. A disposition naming an id the review
+   *  never issued is dropped at the match (`matchDispositions`). */
   readonly findingsByRound: Readonly<Record<number, Finding[]>>;
   readonly dispositionsByRound: Readonly<Record<number, FindingDisposition[]>>;
   readonly reviewRunByRound: Readonly<Record<number, string>>;
-  readonly fixRunByRound: Readonly<Record<number, string>>;
-  /** The last coding child (round 0 or a fix round): its record carries the unit's handoff. */
+  /** The coding run each round's findings step dispatched. */
+  readonly findingsRunByRound: Readonly<Record<number, string>>;
+  /** The last coding run (round 0's child or a findings step's): its record carries the unit's handoff. */
   readonly lastCodingRunId?: string;
   readonly ending?: UnitEnding;
 }
@@ -490,7 +497,7 @@ export function openUnitPipeline(input: UnitPipelineInput, at: number): UnitPipe
     findingsByRound: {},
     dispositionsByRound: {},
     reviewRunByRound: {},
-    fixRunByRound: {},
+    findingsRunByRound: {},
   };
   if (!input.resume) return base;
   const url = input.resume.url ?? `https://github.com/${input.repo}/pull/${input.resume.pr}`;
@@ -528,9 +535,9 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
   if (round.kind === "coding")
     return { kind: "contract", unit, rebase: { branch: s.input.unit.branch, onto: s.input.base } };
   const pr = s.pr!.number;
-  if (round.kind === "fix") return { kind: "fix", unit, pr, reviewRunId: s.reviewRunByRound[round.index]! };
+  if (round.kind === "findings") return { kind: "findings", unit, pr, reviewRunId: s.reviewRunByRound[round.index]! };
   const priorReview = s.reviewRunByRound[round.index - 1];
-  const priorFix = s.fixRunByRound[round.index - 1];
+  const priorCoding = s.findingsRunByRound[round.index - 1];
   return {
     kind: "review",
     unit,
@@ -538,11 +545,27 @@ function briefFor(s: UnitPipelineState, round: RoundRef): Brief {
     ...(s.lastReviewHead !== undefined ? { headSha: s.lastReviewHead } : {}),
     round: round.index,
     ...(priorReview !== undefined
-      ? { prior: { reviewRunId: priorReview, ...(priorFix !== undefined ? { fixRunId: priorFix } : {}) } }
+      ? { prior: { reviewRunId: priorReview, ...(priorCoding !== undefined ? { codingRunId: priorCoding } : {}) } }
       : {}),
   };
 }
 
+/** The dispositions a coding run recorded that answer `findings`, and the ids
+ *  it named that the review never issued (agent-ship item 6). The tool records
+ *  whatever the run submits, so the match is the runner's: `matched` is what the
+ *  state, the report and the re-review carry, `dropped` what the re-review's
+ *  note names. Pure and node-free, so the spawn route composing the re-review
+ *  turn and this machine agree by construction. */
+export function matchDispositions(
+  findings: readonly Finding[],
+  dispositions: readonly FindingDisposition[],
+): { matched: FindingDisposition[]; dropped: string[] } {
+  const issued = new Set(findings.map((f) => f.id));
+  const matched = dispositions.filter((d) => issued.has(d.findingId));
+  const dropped = [...new Set(dispositions.filter((d) => !issued.has(d.findingId)).map((d) => d.findingId))];
+  return { matched, dropped };
+}
+
 /** The step the machine is at. Pure over the state: asked before every step
  *  and again after a replay, it names the same step for the same state. */
 export function nextAction(s: UnitPipelineState): CoordinatorAction {
@@ -629,7 +652,7 @@ function nextReview(s: UnitPipelineState, notes: CoordinatorNote[] = []): Transi
 const stopMode = (status: RunStatus): "soft" | "hard" | undefined =>
   status === "stopped_soft" ? "soft" : status === "stopped_hard" ? "hard" : undefined;
 
-/** A coding or fix child's confirmed end. */
+/** A coding run's confirmed end: round 0's child, or the run a findings step dispatched. */
 function settleCoding(
   s: UnitPipelineState,
   round: RoundRef,
@@ -637,12 +660,19 @@ function settleCoding(
   facts: Extract<ChildFacts, { finished: true }>,
 ): Transition {
   // Recorded before the checks below: a pull request is a fact a stop must
-  // still report, and submitted dispositions are a fact no ending erases.
+  // still report, and submitted dispositions are a fact no ending erases. The
+  // run records whatever it submitted; only the dispositions that answer this
+  // round's findings enter the state (agent-ship item 6).
   let next: UnitPipelineState = {
     ...s,
     ...(facts.pr !== undefined ? { pr: { number: facts.pr.number, url: facts.pr.url } } : {}),
-    ...(round.kind === "fix" && facts.dispositions !== undefined
-      ? { dispositionsByRound: { ...s.dispositionsByRound, [round.index]: facts.dispositions } }
+    ...(round.kind === "findings" && facts.dispositions !== undefined
+      ? {
+          dispositionsByRound: {
+            ...s.dispositionsByRound,
+            [round.index]: matchDispositions(s.findingsByRound[round.index] ?? [], facts.dispositions).matched,
+          },
+        }
       : {}),
   };
   const mode = stopMode(facts.status);
@@ -752,7 +782,7 @@ function settleReview(
     return { state: { ...next, phase: { at: "merge", pr, headSha, n: 1, since: next.clock } }, notes };
   }
   // request_changes: the verdict settled (and posted) — now a stop
-  // short-circuits the fix round, naming the review standing on the pull request.
+  // short-circuits the findings step, naming the review standing on the pull request.
   if (mode !== undefined)
     return end(
       next,
@@ -772,7 +802,11 @@ function settleReview(
       { kind: "round_cap", maxRounds: next.input.caps.maxRounds, reviewRounds: next.reviewRounds },
       notes,
     );
-  return enterRound(next, { index: round.index, kind: "fix" }, notes);
+  // The findings step (agent-ship item 7): the review's findings dispatched into
+  // the unit thread as a coding run, under the review round's index. A run live
+  // there is a person's (this machine awaited its own child's end), so the
+  // spawn answers busy and the step waits under the unit's clock like any round.
+  return enterRound(next, { index: round.index, kind: "findings" }, notes);
 }
 
 /** The unit's ending when its pull request is found merged — by a person, or
@@ -792,7 +826,7 @@ function foundMerged(
   );
 }
 
-/** The pull request heading the branch after a coding or fix round. */
+/** The pull request heading the branch after round 0 or a findings step. */
 function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-check" }>, pr: PrCheck): Transition {
   const { round } = phase;
   // The merge landed during the round: the child found nothing left to ship
@@ -803,7 +837,7 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
     const reason =
       round.index === 0
         ? `⚠️ Ship ended at round 0: the coding round ended without opening a pull request (a clarifying question, a budget write-up, an unproven push or a description-less push ends the pipeline here). No review round ran.`
-        : `⚠️ Fix round ${round.index} left no open pull request heading \`${s.input.unit.branch}\` — the pull request was closed out from under the pipeline and none was reopened, so there is nothing to re-review.`;
+        : `⚠️ Round ${round.index}'s findings step left no open pull request heading \`${s.input.unit.branch}\` — the pull request was closed out from under the pipeline and none was reopened, so there is nothing to re-review.`;
     return end(
       s,
       {
@@ -818,13 +852,13 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
   }
   const head = pr.headSha ?? phase.childHead;
   const next: UnitPipelineState = { ...s, pr: { number: pr.prNumber, url: pr.url } };
-  if (round.kind === "fix") {
+  if (round.kind === "findings") {
     // Nothing repushed → nothing to re-review, unless every finding of the
     // last review was declined on the record: that re-review verifies the
     // arguments and may concede.
-    const fixHead = normalizeHead(head);
+    const codingHead = normalizeHead(head);
     const reviewedAt = normalizeHead(s.lastReviewHead);
-    if (fixHead !== undefined && reviewedAt !== undefined && sameCommit(fixHead, reviewedAt)) {
+    if (codingHead !== undefined && reviewedAt !== undefined && sameCommit(codingHead, reviewedAt)) {
       const findings = s.findingsByRound[round.index] ?? [];
       const dispositions = s.dispositionsByRound[round.index] ?? [];
       const allDeclined =
@@ -835,7 +869,7 @@ function settlePrCheck(s: UnitPipelineState, phase: Extract<Phase, { at: "pr-che
           next,
           {
             kind: "aborted",
-            reason: `⚠️ Fix round ${round.index} produced no new head — the branch still sits at \`${fixHead.slice(0, 7)}\`, the commit the review already read, and not every finding was declined on the record, so there is nothing new to re-review.`,
+            reason: `⚠️ Round ${round.index}'s findings step produced no new head — the branch still sits at \`${codingHead.slice(0, 7)}\`, the commit the review already read, and not every finding was declined on the record, so there is nothing new to re-review.`,
             round,
             reviewRounds: next.reviewRounds,
           },
@@ -889,8 +923,11 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
           const runs =
             p.round.kind === "review"
               ? { reviewRunByRound: { ...s.reviewRunByRound, [p.round.index]: r.runId } }
-              : p.round.kind === "fix"
-                ? { fixRunByRound: { ...s.fixRunByRound, [p.round.index]: r.runId }, lastCodingRunId: r.runId }
+              : p.round.kind === "findings"
+                ? {
+                    findingsRunByRound: { ...s.findingsRunByRound, [p.round.index]: r.runId },
+                    lastCodingRunId: r.runId,
+                  }
                 : { lastCodingRunId: r.runId };
           return {
             state: { ...clocked, ...runs, phase: { at: "wait", round: p.round, runId: r.runId, n: 1, until } },
@@ -999,8 +1036,8 @@ export function applyReturn(s: UnitPipelineState, ret: StepReturn): Transition {
 const sameFinding = (a: Finding, b: Finding) => a.severity === b.severity && a.file === b.file && a.title === b.title;
 
 /** The disposition that answers `finding` as review round `round` listed it:
- *  that round's own fix round's, else one carried forward unchanged from an
- *  earlier round — never across a reused id, which inherits nothing. */
+ *  the one that round's findings step recorded, else one carried forward
+ *  unchanged from an earlier round — never across a reused id, which inherits nothing. */
 function dispositionFor(s: UnitPipelineState, finding: Finding, round: number): FindingDisposition | undefined {
   let cur = finding;
   for (let r = round; r >= 1; r--) {
@@ -1097,7 +1134,7 @@ export function renderUnitReport(s: UnitPipelineState): string {
       return join([e.finalReply, e.reason, `⚠️ Ship aborted after ${rounds}.`, reissue]);
     case "no_verdict":
       return join([
-        `⚠️ Review round ${e.round.index} ended without a submitted verdict (budget, refusal, or stop) — ship never converts that into a request for changes, so no fix round ran.`,
+        `⚠️ Review round ${e.round.index} ended without a submitted verdict (budget, refusal, or stop) — ship never converts that into a request for changes, so no findings step ran.`,
         e.finalReply ? `Review round's final message:\n\n${e.finalReply}` : undefined,
         `⚠️ Ship aborted after ${rounds}.`,
         reissue,

package/dist/assets/src/core/trace/workerTrace.ts

@@ -52,6 +52,8 @@ export function shimRoute(pathname: string): string | undefined {
   if (pathname === "/costs" || pathname.startsWith("/costs/")) return "costs";
   if (pathname.startsWith("/api/")) return "api";
   if (pathname.startsWith("/admin/")) return "admin";
+  // The artifact copy (deploy/cloudflare/artifactsCopy.ts): the shim's own route, a 1 GB stream.
+  if (pathname === "/artifacts/copy") return "artifacts";
   // The model proxy's two routes (docs/reference/specs/model-proxy.md): a bounded
   // request per model call, forwarded to the container like everything else.
   if (pathname === "/v1/messages" || pathname === "/v1/chat/completions") return "model-proxy";

package/dist/assets/src/deploy/profile.ts

@@ -89,6 +89,17 @@ export const profileSchema = z.object({
   /** The Cloudflare Access application in front of the bot's dashboards, when
    *  there is one: the team domain the JWT is issued by and the app's AUD. */
   access: z.object({ teamDomain: hostname, aud: z.string().regex(/^[0-9a-f]{64}$/) }).optional(),
+  /** The artifact store's bucket (docs/reference/specs/execution.md item 20), when the installation
+   *  has one: the bot Worker's template binds it as `ARTIFACTS` and `deploy` creates it before the
+   *  upload. The bot's runtime config (`artifacts.r2.bucket`) must name the same bucket — the two
+   *  are held equal by `artifacts check`, not by the profile. R2's own bucket-name rules. */
+  artifacts: z
+    .object({
+      bucket: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/, "an R2 bucket name: 3–63 lowercase letters, digits and hyphens"),
+    })
+    .optional(),
 });
 
 export type DeploymentProfile = z.infer<typeof profileSchema>;

package/dist/assets/src/execution/residentInstanceId.ts

@@ -136,13 +136,21 @@ export type InstanceDecision =
 /** Create an instance only for a row no live cycle blocks (`refreshCycleBlocked`)
  *  whose cadence has elapsed since the last instance — counted in whole
  *  buckets so cron jitter never skips a due bucket: the awake cadence is one
- *  bucket, the idle cadence the row records (`idleSince` set) is the idle
- *  interval in buckets. */
+ *  bucket, the idle cadence is the idle interval in buckets. The idle cadence
+ *  is for a `warm` row with `idleSince` set and no other: only a cycle's gate
+ *  clears `idleSince`, so a wake that dies before its cycle (a deploy rolling
+ *  the container mid-restore) leaves the marker on a `restoring` row, and on
+ *  the `degraded(stale-mid-flight…)` the watchdog stamps it with; both must
+ *  run at the next bucket, or the resident sits degraded for the idle
+ *  interval. A streak-parked `degraded` row (item 16b) runs every bucket
+ *  too: its gate parks it again without a fetch, and the first rehydrate
+ *  flips it `warm`. */
 export function shouldCreateRefreshInstance(row: RefreshRow, nowMs: number, cadence: RefreshCadence): InstanceDecision {
   const blocked = refreshCycleBlocked(row, nowMs);
   if (blocked) return { create: false, why: blocked };
   if (row.lastInstanceAt !== null) {
-    const delayS = row.idleSince !== null ? cadence.idleIntervalS : cadence.intervalS;
+    const parked = row.state === "warm" && row.idleSince !== null;
+    const delayS = parked ? cadence.idleIntervalS : cadence.intervalS;
     const dueBuckets = Math.max(1, Math.ceil((delayS * 1000) / REFRESH_BUCKET_MS));
     if (refreshBucket(nowMs) - refreshBucket(row.lastInstanceAt) < dueBuckets) return { create: false, why: "not-due" };
   }