@yaag/runtime 0.10.0 → 0.11.0

package/src/agent/spawn.ts

@@ -1,29 +1,13 @@
-import { resolve } from "node:path";
 import type { ConfigExtension } from "../config/index.ts";
 import { YaagError } from "../errors.ts";
 import type { EventSink } from "../events.ts";
-import {
-  ModelErrorHistory,
-  type ModelSelection,
-  normalizeModelResolution,
-  resolveModel,
-  resolveRecordedModel,
-} from "../model/index.ts";
 import type { RunContext } from "../run/index.ts";
-import type { AgentTransport, TransportFactory, TransportStartup } from "../transport/index.ts";
-import type {
-  AskOptions,
-  Handle,
-  ResolvedSpawnOptions,
-  SpawnOptions,
-  SpawnOverrides,
-} from "../types.ts";
-import { Agent } from "./agent.ts";
-import { uniqueAgentName } from "./agent-names.ts";
+import type { TransportFactory } from "../transport/index.ts";
+import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
+import type { Agent } from "./agent.ts";
 import { type AgentDefinition, agentDefinitionConfig, isAgentDefinition } from "./define-agent.ts";
-import { resolveSpawnExtensions } from "./spawn-extensions.ts";
-import { resolveParent } from "./spawn-parent.ts";
-import { openRequest, withSelection } from "./spawn-request.ts";
+import { type ForkSpawner, forkRequest } from "./fork.ts";
+import { type OpenAgentContext, type OpenAgentRequest, openAgent } from "./spawn-open.ts";
 
 /** Dependencies for one Run's Agent-spawn gate. */
 export interface SpawnDependencies {
@@ -51,130 +35,30 @@ export interface SpawnGate {
 export function makeSpawn(deps: SpawnDependencies): SpawnGate {
   const taken = new Set<string>();
   let closed = false;
+  // Declared before use: every Agent this gate opens is handed the same fork
+  // spawner, so a fork is gated and named exactly like a spawn.
+  const forkSpawner: ForkSpawner = async (source, overrides) => {
+    if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
+    const request = forkRequest(source, overrides);
+    const handle = await openAgent(context, {
+      spawnOptions: request.spawnOptions,
+      parent: request.parent,
+      askDefaults: undefined,
+      definitionName: undefined,
+      fork: request.fork,
+    });
+    if (request.compact !== undefined && request.compact !== false) {
+      await handle.compact(typeof request.compact === "string" ? request.compact : undefined);
+    }
+    return handle;
+  };
+  const context: OpenAgentContext = { ...deps, taken, forkSpawner };
   const spawn: RunContext["spawn"] = async (
     definitionOrOptions: SpawnOptions | AgentDefinition = {},
     overrides?: SpawnOverrides,
   ): Promise<Handle> => {
     if (closed) throw new YaagError("RUN_CLOSED", "run has already settled");
-    const request = resolveRequest(definitionOrOptions, overrides);
-    const cwd = resolve(request.spawnOptions.cwd ?? process.cwd());
-    const name = uniqueAgentName(request.spawnOptions.name, deps.agents.length, taken);
-    // Resolved before any transport work, so a bad Parent Link costs nothing.
-    const parent = resolveParent(request.parent, deps.agents);
-    const resolution = normalizeModelResolution(request.spawnOptions);
-    // One history per Agent: its spawn loop and every mid-Ask fallback loop
-    // append to it, so a resolver sees every candidate that already failed.
-    const history = new ModelErrorHistory();
-    try {
-      // Extension paths do not vary per candidate, so a bad path fails once, generically.
-      const extensions = await resolveSpawnExtensions({
-        configExtensions: deps.configExtensions,
-        declared: request.spawnOptions.extensions,
-        useConfigExtensions: request.spawnOptions.configExtensions !== false,
-        ...(deps.programFile === undefined ? {} : { programFile: deps.programFile }),
-        projectRoot: cwd,
-      }).catch((error: unknown) => {
-        if (error instanceof YaagError) throw error;
-        throw new YaagError("SPAWN_FAILED", `agent "${name}": ${String(error)}`, name);
-      });
-      // One local for both open sites, so the launch arguments and the recorded
-      // identity cannot drift apart.
-      const extensionFields =
-        extensions === undefined
-          ? {}
-          : {
-              resolvedExtensionPaths: extensions.resolvedPaths,
-              declaredExtensions: extensions.declared,
-            };
-      const attempt = async (
-        selection: ModelSelection,
-      ): Promise<{ opened: OpenedTransport; spawnOptions: ResolvedSpawnOptions }> => {
-        const settled = withSelection(request.spawnOptions, selection);
-        return {
-          opened: await openTransport({
-            factory: deps.factory,
-            name,
-            cwd,
-            spawnOptions: settled,
-            ...extensionFields,
-            ...(parent === undefined ? {} : { parent }),
-            sessionDir: deps.sessionDir,
-          }),
-          spawnOptions: settled,
-        };
-      };
-      // The peek must stay in the same synchronous block as the first open: a
-      // Cassette-backed factory claims Agents in open order (ADR-0013).
-      const recorded = deps.factory.recordedSpawn?.(
-        openRequest({
-          name,
-          cwd,
-          spawnOptions: request.spawnOptions,
-          ...extensionFields,
-          ...(parent === undefined ? {} : { parent }),
-          sessionDir: deps.sessionDir,
-        }),
-      );
-      // A Cassette-backed spawn adopts the recorded resolved selection and skips
-      // the loop, so a replayed Run emits no spawn-time fallback (ADR-0039).
-      const adopted =
-        recorded === undefined ? undefined : resolveRecordedModel({ resolution, recorded });
-      // The adopted outcome carries the attempts the recording already spent, so
-      // a later mid-Ask fallback re-resolves from that attempt index (ADR-0039).
-      for (const skipped of adopted?.skipped ?? []) {
-        history.record(skipped.reason, skipped.failedModel);
-      }
-      const { opened, spawnOptions } =
-        adopted === undefined
-          ? await resolveModel({
-              resolution,
-              agent: name,
-              history,
-              onFallback: (fallback) => {
-                deps.emit({ type: "model_fallback", agent: name, ...fallback });
-              },
-              attempt,
-            })
-          : await attempt(adopted.selection);
-      const resolvedCwd = opened.startup.worktree?.cwd ?? cwd;
-      const branch = opened.startup.worktree?.branch;
-      const sessionFile = opened.startup.sessionFile;
-      const agent = new Agent({
-        name,
-        cwd: resolvedCwd,
-        branch,
-        transport: opened.transport,
-        emit: deps.emit,
-        spawnOptions,
-        // An Agent that named no candidate inherits pi's default model, so a
-        // failing Ask has nothing to fall back from and stays an Ask failure.
-        ...(spawnOptions.model === undefined
-          ? {}
-          : { modelFallback: { resolution, history, candidate: spawnOptions.model } }),
-        ...(request.askDefaults === undefined ? {} : { askDefaults: request.askDefaults }),
-        ...(request.definitionName === undefined ? {} : { definitionName: request.definitionName }),
-      });
-      deps.agents.push(agent);
-      deps.emit({
-        type: "agent_spawn",
-        agent: name,
-        model: agent.model,
-        cwd: resolvedCwd,
-        ...(branch === undefined ? {} : { branch }),
-        ...(sessionFile === undefined ? {} : { sessionFile }),
-        ...(parent === undefined ? {} : { parent }),
-      });
-      return agent;
-    } catch (error) {
-      if (request.definitionName !== undefined && isSpawnFailure(error)) {
-        throw new YaagError(
-          "SPAWN_FAILED",
-          `definition "${request.definitionName}": ${error.message}`,
-          name,
-        );
-      }
-      throw error;
-    }
+    return openAgent(context, resolveRequest(definitionOrOptions, overrides));
   };
   return {
     spawn,
@@ -195,20 +79,10 @@ interface ValidatedOverrides {
   readonly parent: unknown;
 }
 
-interface SpawnRequest {
-  /** Never carries `parent`: a Handle must not reach the recorded options. */
-  readonly spawnOptions: SpawnOptions;
-  /** The raw Parent Link option, validated by `resolveParent`. */
-  readonly parent: unknown;
-  readonly askDefaults: AskOptions | undefined;
-  /** Definition identity stays separate from a topology-overridden Agent name. */
-  readonly definitionName: string | undefined;
-}
-
 function resolveRequest(
   definitionOrOptions: SpawnOptions | AgentDefinition,
   overrides: SpawnOverrides | undefined,
-): SpawnRequest {
+): OpenAgentRequest {
   if (!isAgentDefinition(definitionOrOptions)) {
     const { parent, ...spawnOptions } = definitionOrOptions;
     return { spawnOptions, parent, askDefaults: undefined, definitionName: undefined };
@@ -284,49 +158,3 @@ function validateOverrides(overrides: unknown): ValidatedOverrides {
   }
   return { topology, parent };
 }
-
-function isSpawnFailure(error: unknown): error is YaagError {
-  return error instanceof YaagError && error.code === "SPAWN_FAILED";
-}
-
-interface OpenTransportOptions {
-  readonly factory: TransportFactory;
-  readonly name: string;
-  readonly cwd: string;
-  readonly spawnOptions: ResolvedSpawnOptions;
-  readonly resolvedExtensionPaths?: readonly string[];
-  readonly declaredExtensions?: readonly string[];
-  readonly parent?: string;
-  readonly sessionDir: string | undefined;
-}
-
-interface OpenedTransport {
-  readonly transport: AgentTransport;
-  readonly startup: TransportStartup;
-}
-
-async function openTransport(options: OpenTransportOptions): Promise<OpenedTransport> {
-  const startup: TransportStartup = {};
-  try {
-    const transport = await options.factory.open(
-      openRequest({
-        name: options.name,
-        cwd: options.cwd,
-        spawnOptions: options.spawnOptions,
-        ...(options.resolvedExtensionPaths === undefined
-          ? {}
-          : { resolvedExtensionPaths: options.resolvedExtensionPaths }),
-        ...(options.declaredExtensions === undefined
-          ? {}
-          : { declaredExtensions: options.declaredExtensions }),
-        ...(options.parent === undefined ? {} : { parent: options.parent }),
-        sessionDir: options.sessionDir,
-      }),
-      (report) => Object.assign(startup, report),
-    );
-    return { transport, startup };
-  } catch (error) {
-    if (error instanceof YaagError) throw error;
-    throw new YaagError("SPAWN_FAILED", `agent "${options.name}": ${String(error)}`, options.name);
-  }
-}

package/src/cassette/cassette-replay.ts

@@ -1,6 +1,13 @@
 import type { ReportedResult } from "../ask-contract/index.ts";
 import { isReportResultCommandFrame, ReportResultCall } from "../ask-contract/index.ts";
-import type { AgentStats, AskMarker, AskPlayback, Frame } from "../transport/index.ts";
+import type {
+  AgentStats,
+  AskMarker,
+  AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  Frame,
+} from "../transport/index.ts";
 import { FrameQueue } from "../transport/index.ts";
 import type { CassetteAgent } from "./cassette.ts";
 
@@ -92,6 +99,31 @@ export class CassetteReplay {
     };
   }
 
+  /**
+   * Moves playback to a compaction its caller has already identity-checked.
+   *
+   * A compaction lives between two Asks, and `beginAsk` never switches the
+   * cursors back to the Agent-level streams, so the recorded compaction owns
+   * its own streams (ADR-0043).
+   */
+  beginCompaction(marker: CompactionMarker): CompactionPlayback {
+    const compaction = this.#agent.compactions?.[marker.index];
+    if (!compaction) throw new Error("unreachable replay compaction cursor");
+    this.#sentCursor = 0;
+    this.#receivedCursor = 0;
+    this.#sent = compaction.sentFrames;
+    this.#received = compaction.receivedFrames;
+    this.#openAttempt(0);
+    return {
+      result: compaction.result ?? {
+        tokensBefore: null,
+        tokensAfter: null,
+        tokens: null,
+        cost: null,
+      },
+    };
+  }
+
   /** Ends the stream cleanly, allowing a caller to switch to another source. */
   finish(): void {
     this.#queue.end();

package/src/cassette/cassette-schema.ts

@@ -39,6 +39,9 @@ const CassetteSpawnSchema = Type.Object({
   worktree: Type.Optional(Type.Literal(true)),
   declaredExtensions: Type.Optional(StringArray),
   parent: Type.Optional(Type.String()),
+  origin: Type.Optional(Type.Literal("fork")),
+  forkOf: Type.Optional(Type.String()),
+  forkAsks: Type.Optional(Type.Number()),
 });
 
 const ContextSpawnSchema = Type.Object({
@@ -119,6 +122,22 @@ const TokenBreakdownSchema = Type.Object({
   total: Type.Number(),
 });
 
+const CompactionResultSchema = Type.Object({
+  tokensBefore: Type.Union([Type.Null(), Type.Number()]),
+  tokensAfter: Type.Union([Type.Null(), Type.Number()]),
+  tokens: Type.Union([Type.Null(), TokenBreakdownSchema]),
+  cost: Type.Union([Type.Null(), Type.Number()]),
+});
+
+const CassetteCompactionSchema = Type.Object({
+  index: Type.Number(),
+  hash: Type.String(),
+  afterAsks: Type.Number(),
+  result: Type.Optional(CompactionResultSchema),
+  sentFrames: Type.Array(FrameSchema),
+  receivedFrames: Type.Array(FrameSchema),
+});
+
 const CassetteAgentSchema = Type.Object({
   spawn: CassetteSpawnSchema,
   model: Type.String(),
@@ -128,6 +147,7 @@ const CassetteAgentSchema = Type.Object({
   sentFrames: Type.Array(FrameSchema),
   receivedFrames: Type.Array(FrameSchema),
   asks: Type.Array(CassetteAskSchema),
+  compactions: Type.Optional(Type.Array(CassetteCompactionSchema)),
   stats: Type.Object({
     tokens: Type.Union([Type.Null(), TokenBreakdownSchema]),
     cost: Type.Union([Type.Null(), Type.Number()]),

package/src/cassette/cassette.ts

@@ -7,6 +7,8 @@ import type {
   AskInvalidOutputPlayback,
   AskMarker,
   AskMarkerContext,
+  CompactionMarker,
+  CompactionResult,
   Frame,
   OpenOptions,
   WorktreeResolution,
@@ -60,9 +62,23 @@ export interface CassetteAgent {
   readonly sentFrames: readonly Frame[];
   readonly receivedFrames: readonly Frame[];
   readonly asks: readonly CassetteAsk[];
+  /** Compactions between this Agent's Asks; absent for an Agent that compacted none. */
+  readonly compactions?: readonly CassetteCompaction[];
   readonly stats: AgentStats;
 }
 
+/** The frames attributed to one compaction marker (ADR-0043). */
+export interface CassetteCompaction {
+  readonly index: number;
+  readonly hash: string;
+  /** Settled Asks of this Agent at the compaction point. */
+  readonly afterAsks: number;
+  /** What the recorded compaction reported; absent when the exchange failed. */
+  readonly result?: CompactionResult;
+  readonly sentFrames: readonly Frame[];
+  readonly receivedFrames: readonly Frame[];
+}
+
 /** Behavioural identity supplied when opening a recorded Agent. */
 export interface CassetteSpawn {
   readonly name: string;
@@ -93,6 +109,12 @@ export interface CassetteSpawn {
    * Part of spawn identity; absent for a root Agent and for older Cassettes.
    */
   readonly parent?: string;
+  /** How the Agent came to be; absent means an ordinary spawn. Spawn identity. */
+  readonly origin?: "fork";
+  /** Name of the Agent this one was forked from. Spawn identity. */
+  readonly forkOf?: string;
+  /** Settled Asks of the fork source at the fork point. Spawn identity. */
+  readonly forkAsks?: number;
 }
 
 /** The frames attributed to one Ask marker. */
@@ -142,6 +164,8 @@ export interface CassetteRecorder {
   received(frame: Frame): void;
   beginAsk(marker: AskMarker): void;
   finishAsk(completion: AskCompletion): void;
+  beginCompaction(marker: CompactionMarker): void;
+  finishCompaction(result: CompactionResult | undefined): void;
   closed(stats: AgentStats): void;
 }
 
@@ -161,6 +185,15 @@ interface MutableAsk {
   recovered?: true;
 }
 
+interface MutableCompaction {
+  readonly index: number;
+  readonly hash: string;
+  readonly afterAsks: number;
+  readonly sentFrames: Frame[];
+  readonly receivedFrames: Frame[];
+  result?: CompactionResult;
+}
+
 interface MutableAgent {
   readonly spawn: CassetteSpawn;
   readonly model: string;
@@ -170,8 +203,10 @@ interface MutableAgent {
   readonly sentFrames: Frame[];
   readonly receivedFrames: Frame[];
   readonly asks: MutableAsk[];
+  readonly compactions: MutableCompaction[];
   stats: AgentStats;
-  active: MutableAsk | null;
+  /** The slot later frames belong to: one Ask, one compaction, or the Agent. */
+  active: MutableAsk | MutableCompaction | null;
 }
 
 /** Collects a Cassette in memory; `executeRun` serializes it at Run settlement. */
@@ -194,6 +229,7 @@ export class CassetteCollector implements CassetteSink {
           sentFrames: [],
           receivedFrames: [],
           asks: [],
+          compactions: [],
           stats: { tokens: null, cost: null },
           active: null,
         };
@@ -211,11 +247,24 @@ export class CassetteCollector implements CassetteSink {
         agent.active = ask;
       },
       finishAsk: (completion): void => {
-        if (!agent?.active) return;
-        if (completion.limit !== undefined) agent.active.limit = completion.limit;
-        if (completion.stalled !== undefined) agent.active.stalled = completion.stalled;
-        if (completion.invalidOutput !== undefined) agent.active.outcome = completion.invalidOutput;
-        if (completion.recovered === true) agent.active.recovered = true;
+        const ask = activeAsk(agent);
+        if (!ask) return;
+        if (completion.limit !== undefined) ask.limit = completion.limit;
+        if (completion.stalled !== undefined) ask.stalled = completion.stalled;
+        if (completion.invalidOutput !== undefined) ask.outcome = completion.invalidOutput;
+        if (completion.recovered === true) ask.recovered = true;
+      },
+      beginCompaction: (marker): void => {
+        if (!agent) return;
+        const compaction = { ...marker, sentFrames: [], receivedFrames: [] };
+        agent.compactions.push(compaction);
+        agent.active = compaction;
+      },
+      finishCompaction: (result): void => {
+        const compaction = agent?.compactions.at(-1);
+        if (compaction !== undefined && result !== undefined) compaction.result = result;
+        // Later frames belong to the Agent again, not to the compaction.
+        if (agent) agent.active = null;
       },
       closed: (stats): void => {
         if (agent) agent.stats = stats;
@@ -239,6 +288,7 @@ export class CassetteCollector implements CassetteSink {
             sentFrames,
             receivedFrames,
             asks,
+            compactions,
             stats,
           }) => ({
             spawn,
@@ -249,6 +299,9 @@ export class CassetteCollector implements CassetteSink {
             sentFrames,
             receivedFrames,
             asks,
+            // Absent for an Agent that compacted nothing, so every Cassette
+            // recorded before ADR-0043 keeps its byte-identical shape.
+            ...(compactions.length === 0 ? {} : { compactions }),
             stats,
           }),
         ),
@@ -278,10 +331,20 @@ function spawnIdentity(options: OpenOptions): CassetteSpawn {
       ? {}
       : { declaredExtensions: [...options.declaredExtensions] }),
     ...(options.parent === undefined ? {} : { parent: options.parent }),
+    ...(options.origin === undefined ? {} : { origin: options.origin }),
+    ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
+    ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
     ...(options.worktree === true ? { worktree: true } : {}),
   };
 }
 
+/** The Ask that later frames belong to, or nothing when a compaction owns them. */
+function activeAsk(agent: MutableAgent | null): MutableAsk | null {
+  const active = agent?.active;
+  if (!active || "afterAsks" in active) return null;
+  return active;
+}
+
 function append(
   agent: MutableAgent | null,
   direction: "sentFrames" | "receivedFrames",

package/src/cassette/index.ts

@@ -10,6 +10,7 @@ export {
   type CassetteArtifact,
   type CassetteAsk,
   CassetteCollector,
+  type CassetteCompaction,
   type CassetteGit,
   type CassetteRun,
   type CassetteSink,

package/src/cassette/recording-transport.ts

@@ -4,6 +4,9 @@ import type {
   AskCompletion,
   AskMarker,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
+  CompactionResult,
   Frame,
   OpenOptions,
   RecordedSpawnSelection,
@@ -87,6 +90,16 @@ class RecordingTransport implements AgentTransport {
     this.#inner.finishAsk(completion);
   }
 
+  beginCompaction(marker: CompactionMarker): CompactionPlayback | undefined {
+    this.#recorder.beginCompaction(marker);
+    return this.#inner.beginCompaction(marker);
+  }
+
+  finishCompaction(result: CompactionResult | undefined): void {
+    this.#recorder.finishCompaction(result);
+    this.#inner.finishCompaction(result);
+  }
+
   recordedExtractionPolicy(index: number): string | undefined {
     return this.#inner.recordedExtractionPolicy?.(index);
   }

package/src/cassette/replay-divergence.ts

@@ -2,6 +2,7 @@ import { YaagError } from "../errors.ts";
 import type {
   AskMarker,
   AskMarkerContext,
+  CompactionMarker,
   OpenOptions,
   RecordedSpawnSelection,
 } from "../transport/index.ts";
@@ -9,7 +10,13 @@ import type { CassetteAgent, CassetteAsk, CassetteSpawn } from "./cassette.ts";
 
 /** A pure description of the first strict replay identity mismatch. */
 export interface ReplayMismatch {
-  readonly kind: "unexpected-spawn" | "spawn-options" | "changed-ask" | "extra-ask";
+  readonly kind:
+    | "unexpected-spawn"
+    | "spawn-options"
+    | "changed-ask"
+    | "extra-ask"
+    | "changed-compaction"
+    | "extra-compaction";
   readonly agent: string;
   readonly index?: number;
   readonly expectedHash: string;
@@ -71,6 +78,32 @@ export const replayMismatch = {
               }),
         };
   },
+
+  compaction(
+    agent: CassetteAgent,
+    cursor: number,
+    actual: CompactionMarker,
+  ): ReplayMismatch | null {
+    const expected = agent.compactions?.[cursor];
+    if (!expected) {
+      return {
+        kind: "extra-compaction",
+        agent: agent.spawn.name,
+        index: actual.index,
+        expectedHash: "<none>",
+        actualHash: actual.hash,
+      };
+    }
+    return expected.index === actual.index && expected.hash === actual.hash
+      ? null
+      : {
+          kind: "changed-compaction",
+          agent: agent.spawn.name,
+          index: actual.index,
+          expectedHash: expected.hash,
+          actualHash: actual.hash,
+        };
+  },
 };
 
 /** Where a user reads what a Divergence means and what to do about it. */
@@ -86,7 +119,8 @@ export function strictReplay(mismatch: ReplayMismatch): never {
       mismatch.agent,
     );
   }
-  const at = mismatch.index === undefined ? "spawn" : `Ask ${mismatch.index}`;
+  const at =
+    compactionAt(mismatch) ?? (mismatch.index === undefined ? "spawn" : `Ask ${mismatch.index}`);
   const changed =
     mismatch.kind === "spawn-options" && mismatch.changedFields !== undefined
       ? ` changed ${mismatch.changedFields.join(", ")};`
@@ -98,6 +132,14 @@ export function strictReplay(mismatch: ReplayMismatch): never {
   );
 }
 
+/** Names the compaction seam of a compaction mismatch, or nothing for other kinds. */
+function compactionAt(mismatch: ReplayMismatch): string | undefined {
+  if (mismatch.kind !== "changed-compaction" && mismatch.kind !== "extra-compaction") {
+    return undefined;
+  }
+  return `compaction #${mismatch.index}`;
+}
+
 /** The identity fields a changed spawn altered, for the Divergence report (ADR-0039). */
 function spawnChangedFields(expected: CassetteSpawn, actual: OpenOptions): readonly string[] {
   return changedAmong(SPAWN_OPEN_FIELDS, expected, actual);
@@ -150,6 +192,9 @@ const SPAWN_OPEN_FIELDS = [
   ...SPAWN_IDENTITY_FIELDS,
   "declaredExtensions",
   "parent",
+  "origin",
+  "forkOf",
+  "forkAsks",
 ] as const;
 
 /** The listed fields whose canonical JSON differs between two identity records. */
@@ -222,6 +267,10 @@ function spawnHash(options: CassetteSpawn | OpenOptions): string {
         ? {}
         : { declaredExtensions: options.declaredExtensions }),
       ...(options.parent === undefined ? {} : { parent: options.parent }),
+      // Conditional, so a Cassette recorded before forking keeps its hash.
+      ...(options.origin === undefined ? {} : { origin: options.origin }),
+      ...(options.forkOf === undefined ? {} : { forkOf: options.forkOf }),
+      ...(options.forkAsks === undefined ? {} : { forkAsks: options.forkAsks }),
     }),
   );
   return hasher.digest("hex");

package/src/cassette/replay-transport.ts

@@ -3,6 +3,8 @@ import type {
   AgentTransport,
   AskMarker,
   AskPlayback,
+  CompactionMarker,
+  CompactionPlayback,
   Frame,
   OpenOptions,
   RecordedSpawnSelection,
@@ -30,7 +32,14 @@ export function replayTransport(cassette: Cassette): TransportFactory {
       const mismatch = replayMismatch.spawn(agent, options);
       if (mismatch) strictReplay(mismatch);
       spawnCursor += 1;
-      if (agent.worktree !== undefined) observeStartup?.({ worktree: agent.worktree });
+      // The recorded session file rides along, so a replayed Agent can be
+      // forked exactly where the recording forked it (ADR-0044).
+      if (agent.worktree !== undefined || agent.sessionFile !== undefined) {
+        observeStartup?.({
+          ...(agent.worktree === undefined ? {} : { worktree: agent.worktree }),
+          ...(agent.sessionFile === undefined ? {} : { sessionFile: agent.sessionFile }),
+        });
+      }
       return new ReplayTransport(new CassetteReplay(agent));
     },
 
@@ -46,6 +55,7 @@ class ReplayTransport implements AgentTransport {
   readonly model: string;
   readonly #replay: CassetteReplay;
   #askCursor = 0;
+  #compactionCursor = 0;
   #closed: Promise<AgentStats> | null = null;
 
   constructor(replay: CassetteReplay) {
@@ -72,6 +82,17 @@ class ReplayTransport implements AgentTransport {
     // A completed replay does not alter the recorded Cassette.
   }
 
+  beginCompaction(marker: CompactionMarker): CompactionPlayback {
+    const mismatch = replayMismatch.compaction(this.#replay.agent, this.#compactionCursor, marker);
+    if (mismatch) strictReplay(mismatch);
+    this.#compactionCursor += 1;
+    return this.#replay.beginCompaction(marker);
+  }
+
+  finishCompaction(): void {
+    // A completed replay does not alter the recorded Cassette.
+  }
+
   recordedExtractionPolicy(index: number): string | undefined {
     return this.#replay.agent.asks[index]?.extractionPolicy;
   }