@coreplane/switchboard 1.214.0 → 1.215.0

package/dist/assets/deploy/cloudflare-memory/wrangler.template.jsonc

@@ -35,7 +35,15 @@
       // ONE DeliveryDO (named "delivery"): the delivery page's snapshot per
       // repository — the merged pull requests' facts over the window, one row
       // each, and when they were read (docs/reference/specs/delivery.md item 10).
-      { "name": "DELIVERY", "class_name": "DeliveryDO" }
+      { "name": "DELIVERY", "class_name": "DeliveryDO" },
+      // One SessionLogDO per session — a thread and an agent (the DO name is
+      // `<threadKey>:<agent>`): the transcript rows of every run of the
+      // session, a full-text index over them, and the notepad
+      // (docs/reference/specs/session-log.md). Kept after a run finishes; the
+      // retention sweep drops it once its last kept run is gone and no run is
+      // live on the thread. Runs claimed before it existed still finish on
+      // RunTranscriptDO, which stays bound until no such row is live.
+      { "name": "SESSION_LOGS", "class_name": "SessionLogDO" }
     ]
   },
   // The bot shim's ship coordinator Workflow, bound across scripts by the bot's
@@ -65,6 +73,7 @@
     // run's diagnosis); the FrictionDO that once mirrored those diagnoses is
     // retired with its rows — docs/reference/specs/self-improvement.md item 1.
     { "tag": "v7", "deleted_classes": ["FrictionDO"] },
-    { "tag": "v8", "new_sqlite_classes": ["DeliveryDO"] }
+    { "tag": "v8", "new_sqlite_classes": ["DeliveryDO"] },
+    { "tag": "v9", "new_sqlite_classes": ["SessionLogDO"] }
   ]
 }

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.214.0",
+  "version": "1.215.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.214.0",
+      "version": "1.215.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -19000,7 +19000,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.214.0",
+      "version": "1.215.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.124.0",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.214.0",
+  "version": "1.215.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.214.0",
-  "commit": "5f594682c5b0a24cb11929a33cd6ef28a085634c",
-  "builtAt": "2026-09-14T19:50:00.483Z"
+  "version": "1.215.0",
+  "commit": "801fa224f1f6af4bd152b8555337aa4c8c0b9ea2",
+  "builtAt": "2026-09-14T21:24:17.702Z"
 }

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

@@ -142,6 +142,10 @@ export interface CoordinatorUnit {
   /** The unit's thread, once opened; a task's is the requesting thread from the start. */
   threadKey?: string;
   sourceUrl?: string;
+  /** The unit's review thread, opened once beside the unit's thread: every
+   *  review round runs there (record 0034), so the review child's worktree is
+   *  readonly and its own and no round wipes the coding thread's. */
+  reviewThread?: { threadKey: string; sourceUrl?: string };
   /** The unit's board issue in the repository, when one titled by the unit id exists — the handoff's destination. */
   issue?: number;
   pr?: { number: number; url: string };
@@ -173,6 +177,7 @@ const isResume = (v: unknown): boolean =>
   isFinite(v.pr) &&
   (v.headSha === undefined || isText(v.headSha)) &&
   (v.url === undefined || isText(v.url, 2048));
+const isThread = (v: unknown): boolean => isObject(v) && isText(v.threadKey) && isOptionalText(v.sourceUrl);
 
 /** Structural check on a record from outside the process (a Worker response, an HTTP body). */
 export function isCoordinatorInstance(v: unknown): v is CoordinatorInstance {
@@ -202,6 +207,7 @@ export function isCoordinatorUnit(v: unknown): v is CoordinatorUnit {
   if (!isText(r.unit, 32) || !isText(r.slug) || !isText(r.branch) || !isOptionalText(r.title)) return false;
   if (!Array.isArray(r.dependsOn) || !r.dependsOn.every((d) => isText(d, 32))) return false;
   if (!isOptionalText(r.threadKey) || !isOptionalText(r.sourceUrl)) return false;
+  if (r.reviewThread !== undefined && !isThread(r.reviewThread)) return false;
   if (r.issue !== undefined && !isFinite(r.issue)) return false;
   if (r.pr !== undefined && !isPr(r.pr)) return false;
   if (r.resume !== undefined && !isResume(r.resume)) return false;

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

@@ -536,20 +536,24 @@ export type RunEvent =
    *  the router gave (redacted, capped — the same text the card's `routed:`
    *  line carries) and the model that decided. A compound route is `preset:
    *  "conductor"` with `parts` — one per child the conductor was told to
-   *  spawn: its preset and its text, the child's whole prompt. A compound the
-   *  parse refused is recorded too, on the run that fell to the default:
-   *  `preset` is `defaults.agent` and `reason` reads `compound_rejected:
-   *  <why>` (the run's `run_meta.agentSource` stays `default`). Published by
-   *  the dispatcher straight to the registry right after `run_meta`, once per
-   *  run the router answered; absent on every run a directive, a sticky
-   *  preset or a scope chose. Head material, like `run_meta`. Additive:
-   *  unknown → ignored. */
+   *  spawn: its preset and its text, the child's whole prompt. A compound
+   *  answer that carried a write-identity part collapsed onto that preset
+   *  (record 0034: a write ask is never a part): `preset` is the write preset
+   *  the run is, `collapsed.presets` the preset each part named in answer
+   *  order, and no `parts`. A compound the parse refused is recorded too, on
+   *  the run that fell to the default: `preset` is `defaults.agent` and
+   *  `reason` reads `compound_rejected: <why>` (the run's
+   *  `run_meta.agentSource` stays `default`). Published by the dispatcher
+   *  straight to the registry right after `run_meta`, once per run the router
+   *  answered; absent on every run a directive, a sticky preset or a scope
+   *  chose. Head material, like `run_meta`. Additive: unknown → ignored. */
   | {
       type: "route";
       preset: string;
       reason: string;
       model: string;
       parts?: ReadonlyArray<{ preset: string; text: string }>;
+      collapsed?: { presets: ReadonlyArray<string> };
       seq?: number;
       at?: number;
     }

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

@@ -0,0 +1,207 @@
+// The session log's pure rules (docs/decisions/0035-a-session-log-outlives-its-runs-compaction-is-a-pointer.md;
+// docs/reference/specs/session-log.md): one log per thread and agent holds the
+// transcript rows of every run of the session, each run a range of it. This
+// file is node-free — the bot and `deploy/cloudflare-memory/worker.ts` import
+// it alike — and holds what both sides must agree on: the object's name, the
+// text the full-text index sees for a row, the byte policy's choice of what to
+// drop, the tail cut a follow-up seeds from, and the sweep's drop decision.
+
+import type { ChatMessage, ContentPart } from "../../providers/types.js";
+import { DEFAULT_RETENTION_POLICY, utf8ByteLength } from "../runRecord.js";
+import type { StoredRow } from "./transcript.js";
+
+export { isRunSession, SESSION_KEY_PATTERN, type RunSession } from "../runRecord.js";
+
+/** The byte policy's default: `RetentionPolicy.sessionLogMaxBytes`. */
+export const DEFAULT_SESSION_LOG_MAX_BYTES = DEFAULT_RETENTION_POLICY.sessionLogMaxBytes;
+
+/** The object's name: the thread and the agent, the pair record 0034 calls a
+ *  session. A run without a resolved agent keys on a dash so the name still
+ *  has both halves. */
+export function sessionKey(threadKey: string, agent: string | undefined): string {
+  return `${threadKey}:${agent ?? "-"}`;
+}
+
+/** The request is the seed's last user turn (`splitSeed` reads the seed the
+ *  same way); a seed with no user turn — or no turns — puts its first row there. */
+export function requestIndex(seed: readonly ChatMessage[]): number {
+  for (let i = seed.length - 1; i >= 0; i--) if (seed[i].role === "user") return i;
+  return 0;
+}
+
+export type RowKind = "text" | "tool_result" | "tool_use" | "attachment" | "compaction" | "other";
+
+function parseStored(json: string): StoredRow | undefined {
+  try {
+    const v = JSON.parse(json) as unknown;
+    return typeof v === "object" && v !== null ? (v as StoredRow) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** What a stored row holds, for the byte policy (only a `tool_result` is
+ *  replaceable) and the index (only text kinds carry text). */
+export function rowKind(json: string): RowKind {
+  const stored = parseStored(json);
+  if (!stored) return "other";
+  if ("compaction" in stored) return "compaction";
+  const type = (stored.part as { type?: unknown }).type;
+  switch (type) {
+    case "text":
+      return "text";
+    case "tool_result":
+      return "tool_result";
+    case "tool_use":
+      return "tool_use";
+    case "image":
+    case "document":
+      return "attachment";
+    default:
+      return "other";
+  }
+}
+
+const textOfResultContent = (content: unknown): string => {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((c): c is { type: "text"; text: string } => typeof c === "object" && c !== null && c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+};
+
+/** The text the full-text index holds for a row: a text part's text, a tool
+ *  result's text (the failing test's name in a vitest report is findable), a
+ *  tool call's name and arguments (a command is findable), a compaction row's
+ *  summary; an attachment, a thinking block or an unreadable row index nothing. */
+export function textOfStoredRow(json: string): string {
+  const stored = parseStored(json);
+  if (!stored) return "";
+  if ("compaction" in stored) return typeof stored.compaction?.summary === "string" ? stored.compaction.summary : "";
+  const part = stored.part as ContentPart | undefined;
+  if (!part) return "";
+  switch (part.type) {
+    case "text":
+      return part.text;
+    case "tool_result":
+      return textOfResultContent(part.content);
+    case "tool_use":
+      return `${part.name} ${JSON.stringify(part.input ?? {})}`;
+    default:
+      return "";
+  }
+}
+
+/** The run record keeps this much of a tool's output; the marker says so. */
+const RECORD_TOOL_OUTPUT_CHARS = "8,000 characters";
+
+/** The row that replaces a tool result the byte policy drops: the same role
+ *  and call id (the model's `tool_use` keeps its result, so the conversation
+ *  stays valid), the error flag, and a text naming what went and where the
+ *  rest still is. Undefined for any row that is not a tool result — user and
+ *  assistant text are never dropped. */
+export function droppedToolResultRow(json: string): string | undefined {
+  const stored = parseStored(json);
+  if (!stored || "compaction" in stored) return undefined;
+  const part = stored.part as ContentPart | undefined;
+  if (!part || part.type !== "tool_result") return undefined;
+  const marker: ContentPart = {
+    type: "tool_result",
+    toolUseId: part.toolUseId,
+    content: `[session log: this tool result (${utf8ByteLength(json)} bytes) was dropped to keep the session under its byte policy; the run record keeps its first ${RECORD_TOOL_OUTPUT_CHARS}]`,
+    ...(part.isError === true ? { isError: true } : {}),
+  };
+  return JSON.stringify({ role: stored.role, part: marker });
+}
+
+export interface TrimCandidate {
+  id: number;
+  bytes: number;
+}
+
+/** Which tool-result rows the byte policy replaces once a log is `excess`
+ *  bytes over its budget: the oldest first (the caller passes them oldest
+ *  first), each freeing its bytes less the marker's, until the excess is
+ *  covered or the candidates run out — never a user or assistant text row,
+ *  which are not candidates. */
+export function planSessionTrim(candidates: readonly TrimCandidate[], excess: number, markerBytes: number): number[] {
+  const ids: number[] = [];
+  let freed = 0;
+  for (const c of candidates) {
+    if (freed >= excess) break;
+    const gain = c.bytes - markerBytes;
+    if (gain <= 0) continue;
+    ids.push(c.id);
+    freed += gain;
+  }
+  return ids;
+}
+
+export interface TailRow {
+  idx: number;
+  bytes: number;
+}
+
+/** The tail a follow-up seeds from: walking the rows newest first, the first
+ *  index of the oldest turn that still fits `maxBytes` with every newer turn
+ *  — whole turns only, so no tool call is parted from its result. Undefined
+ *  when even the newest turn is over the budget, or the log is empty. */
+export function tailCut(rowsNewestFirst: readonly TailRow[], maxBytes: number): number | undefined {
+  let total = 0;
+  let from: number | undefined;
+  let i = 0;
+  while (i < rowsNewestFirst.length) {
+    const idx = rowsNewestFirst[i].idx;
+    let turnBytes = 0;
+    let j = i;
+    while (j < rowsNewestFirst.length && rowsNewestFirst[j].idx === idx) turnBytes += rowsNewestFirst[j++].bytes;
+    if (total + turnBytes > maxBytes) break;
+    total += turnBytes;
+    from = idx;
+    i = j;
+  }
+  return from;
+}
+
+/** What the sweep re-reads about one candidate right before dropping it
+ *  (session-log item 7): whether a kept run record names the session, and
+ *  whether any run is live on its thread. */
+export interface DropCandidate {
+  key: string;
+  hasKeptRun: boolean;
+  threadLive: boolean;
+}
+
+export type DropDecision = "drop" | "kept-run" | "thread-live";
+
+/** The sweep's decision (session-log item 7), one per candidate on the facts
+ *  read at that moment: a session object is dropped only when no kept run
+ *  record names it and no live run holds its thread — any live run on the
+ *  thread blocks every session of that thread, since the live row is the
+ *  conservative signal the sweep has. A kept run outranks a live thread in
+ *  the answer, since it is the longer-lived reason. */
+export function sessionsToDrop(candidates: readonly DropCandidate[]): Array<{ key: string; decision: DropDecision }> {
+  return candidates.map((c) => ({
+    key: c.key,
+    decision: c.hasKeptRun ? "kept-run" : c.threadLive ? "thread-live" : "drop",
+  }));
+}
+
+/** The attachments a stored row references: a part's own `dataRef`, and the
+ *  `dataRef` of each of a tool result's nested parts — so a trimmed result
+ *  can take with it what nothing else references (session-log item 5). */
+export function attachmentRefsOf(json: string): string[] {
+  const stored = parseStored(json);
+  if (!stored || "compaction" in stored) return [];
+  const part = stored.part as (ContentPart & { dataRef?: unknown }) | undefined;
+  if (!part) return [];
+  const refs: string[] = [];
+  if (typeof part.dataRef === "string") refs.push(part.dataRef);
+  if (part.type === "tool_result" && Array.isArray(part.content)) {
+    for (const c of part.content as Array<{ dataRef?: unknown }>) {
+      if (typeof c?.dataRef === "string") refs.push(c.dataRef);
+    }
+  }
+  return refs;
+}

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,7 +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 } from "../runRecord.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;
@@ -73,6 +73,12 @@ export interface LiveRunMeta {
   /** 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. */
@@ -194,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 };