@yaag/runtime 0.1.0

package/src/cassette-replay.ts

@@ -0,0 +1,178 @@
+import type { CassetteAgent } from "./cassette.ts";
+import { FrameQueue } from "./frame-queue.ts";
+import type { AgentStats, AskMarker, AskPlayback, Frame } from "./transport.ts";
+
+/**
+ * Replays one Cassette Agent's frame streams at the transport seam.
+ *
+ * It owns frame ordering and command-id remapping, but deliberately leaves
+ * mismatch policy to its caller. `finish()` ends playback for a live handoff.
+ */
+export class CassetteReplay {
+  readonly model: string;
+  readonly stats: AgentStats;
+  readonly #agent: CassetteAgent;
+  readonly #queue = new FrameQueue();
+  #sentCursor = 0;
+  #receivedCursor = 0;
+  #sent: readonly Frame[] = [];
+  #received: readonly Frame[] = [];
+  #ids = new Map<string, string>();
+
+  constructor(agent: CassetteAgent) {
+    this.#agent = agent;
+    this.model = agent.model;
+    this.stats = agent.stats;
+    this.#sent = agent.sentFrames;
+    this.#received = agent.receivedFrames;
+    for (const frame of this.#received) this.#queue.push(frame);
+  }
+
+  /** Returns the recorded Agent whose Ask cursors this instance plays. */
+  get agent(): CassetteAgent {
+    return this.#agent;
+  }
+
+  /** Sends a frame through the recorded conversation, synthesizing internal responses. */
+  send(frame: Frame): void {
+    if (frame.type === "get_last_assistant_text") this.#skipCorrectionHistory();
+    const expected = this.#sent[this.#sentCursor];
+    if (expected && expected.type === frame.type) {
+      this.#sentCursor += 1;
+      this.#rememberId(expected, frame);
+      this.#releaseFor(frame.type);
+      this.#consumeControls();
+      return;
+    }
+    if (frame.type === "get_state") {
+      this.#respond(frame, { model: modelState(this.model) });
+      return;
+    }
+    if (frame.type === "get_session_stats") this.#respond(frame, this.stats);
+  }
+
+  /** Returns a single ordered stream of recorded incoming frames. */
+  frames(): AsyncIterable<Frame> {
+    return this.#queue.frames();
+  }
+
+  /** Moves playback to an Ask that its caller has already identity-checked. */
+  beginAsk(marker: AskMarker): AskPlayback {
+    const ask = this.#agent.asks[marker.index];
+    if (!ask) throw new Error("unreachable replay Ask cursor");
+    this.#sentCursor = 0;
+    this.#receivedCursor = 0;
+    this.#sent = ask.sentFrames;
+    this.#received = ask.receivedFrames;
+    const awaitsAbortSettlement = abortSettlementFollowsFinalText(ask);
+    return {
+      ...(ask.limit === undefined ? {} : { limit: ask.limit }),
+      ...(ask.stalled === undefined ? {} : { stalled: ask.stalled }),
+      ...(ask.outcome === undefined ? {} : { outcome: ask.outcome }),
+      ...(awaitsAbortSettlement ? { awaitsAbortSettlement: true as const } : {}),
+    };
+  }
+
+  /** Ends the stream cleanly, allowing a caller to switch to another source. */
+  finish(): void {
+    this.#queue.end();
+  }
+
+  #consumeControls(): void {
+    for (;;) {
+      const expected = this.#sent[this.#sentCursor];
+      if (expected === undefined || !this.#isRecordedControl(expected)) return;
+      this.#sentCursor += 1;
+      this.#releaseFor(expected.type);
+    }
+  }
+
+  /** Any non-first prompt within an Ask is a recorded correction (ADR-0027 amendment). */
+  #isRecordedControl(frame: Frame): boolean {
+    if (frame.type === "steer" || frame.type === "abort") return true;
+    return frame.type === "prompt" && this.#sentCursor > 0;
+  }
+
+  #skipCorrectionHistory(): void {
+    while (this.#isIntermediateTextQuery()) {
+      const skipped = this.#sent[this.#sentCursor];
+      if (typeof skipped?.id === "string") this.#ids.set(skipped.id, `cassette-${skipped.id}`);
+      this.#sentCursor += 1;
+      this.#releaseFor("get_last_assistant_text", true);
+      this.#consumeControls();
+    }
+  }
+
+  #isIntermediateTextQuery(): boolean {
+    return (
+      this.#sent[this.#sentCursor]?.type === "get_last_assistant_text" &&
+      this.#sent
+        .slice(this.#sentCursor + 1)
+        .some((frame) => frame.type === "get_last_assistant_text")
+    );
+  }
+
+  #releaseFor(command: string, skippedText = false): void {
+    for (; this.#receivedCursor < this.#received.length; this.#receivedCursor += 1) {
+      const frame = this.#received[this.#receivedCursor];
+      if (!frame) return;
+      if (frame.type === "response" && typeof frame.command === "string") {
+        if (
+          frame.command !== command &&
+          !(skippedText && frame.command === "get_last_assistant_text") &&
+          this.#hasFutureCommand(frame.command)
+        ) {
+          return;
+        }
+      }
+      this.#queue.push(this.#remapResponse(frame));
+    }
+  }
+
+  #hasFutureCommand(command: string): boolean {
+    return this.#sent.slice(this.#sentCursor).some((frame) => frame.type === command);
+  }
+
+  #rememberId(expected: Frame, actual: Frame): void {
+    if (typeof expected.id === "string" && typeof actual.id === "string") {
+      this.#ids.set(expected.id, actual.id);
+    }
+  }
+
+  #remapResponse(frame: Frame): Frame {
+    if (frame.type !== "response" || typeof frame.id !== "string") return frame;
+    const id = this.#ids.get(frame.id);
+    return id === undefined ? frame : { ...frame, id };
+  }
+
+  #respond(frame: Frame, data: Record<string, unknown> | AgentStats): void {
+    if (typeof frame.id !== "string") return;
+    this.#queue.push({ type: "response", command: frame.type, id: frame.id, success: true, data });
+  }
+}
+
+function abortSettlementFollowsFinalText(agent: CassetteAgent["asks"][number]): boolean {
+  const finalText = agent.sentFrames.findLastIndex(
+    (frame) => frame.type === "get_last_assistant_text",
+  );
+  if (
+    finalText === -1 ||
+    !agent.sentFrames.slice(finalText + 1).some((frame) => frame.type === "abort")
+  ) {
+    return false;
+  }
+  const abortResponse = agent.receivedFrames.findIndex(
+    (frame) => frame.type === "response" && frame.command === "abort",
+  );
+  return (
+    abortResponse !== -1 &&
+    agent.receivedFrames.slice(abortResponse + 1).some((frame) => frame.type === "agent_settled")
+  );
+}
+
+function modelState(model: string): Record<string, string> {
+  const slash = model.indexOf("/");
+  return slash === -1
+    ? { id: model }
+    : { provider: model.slice(0, slash), id: model.slice(slash + 1) };
+}

package/src/cassette-schema.ts

@@ -0,0 +1,152 @@
+import { type Static, Type } from "typebox";
+import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
+import type { CassetteArtifact } from "./cassette.ts";
+import type { Frame } from "./transport.ts";
+
+/**
+ * Structure-only mirror of the hand-written Cassette interfaces; `cassette.ts`
+ * stays the public type authority. Semantic invariants — version gate, Ask
+ * positions, contract co-presence, canonical JSON — are loader post-checks.
+ * No node sets `additionalProperties`: unknown fields are tolerated so a newer
+ * artifact still loads.
+ */
+
+const FrameSchema = Type.Unsafe<Frame>(Type.Object({ type: Type.String() }));
+
+const ThinkingSchema = Type.Union(
+  (["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const).map((level) =>
+    Type.Literal(level),
+  ),
+);
+
+const StringArray = Type.Array(Type.String());
+
+const spawnPolicyFields = {
+  model: Type.Optional(Type.String()),
+  systemPrompt: Type.Optional(Type.String()),
+  thinking: Type.Optional(ThinkingSchema),
+  appendSystemPrompt: Type.Optional(Type.String()),
+  tools: Type.Optional(StringArray),
+  disallowedTools: Type.Optional(StringArray),
+  skills: Type.Optional(StringArray),
+  disallowedSkills: Type.Optional(StringArray),
+};
+
+const CassetteSpawnSchema = Type.Object({
+  name: Type.String(),
+  cwd: Type.String(),
+  ...spawnPolicyFields,
+  worktree: Type.Optional(Type.Literal(true)),
+});
+
+const ContextSpawnSchema = Type.Object({
+  cwd: Type.Optional(Type.String()),
+  ...spawnPolicyFields,
+  worktree: Type.Optional(Type.Boolean()),
+});
+
+const contractFields = {
+  outputSchema: Type.Optional(Type.Unsafe<CanonicalJsonObject>(Type.Object({}))),
+  maxSteers: Type.Optional(Type.Integer({ minimum: 0 })),
+  extractionPolicy: Type.Optional(Type.String()),
+};
+
+const ContextAskSchema = Type.Object({
+  maxTurns: Type.Optional(Type.Number()),
+  maxToolCalls: Type.Optional(Type.Number()),
+  maxDurationMs: Type.Optional(Type.Number()),
+  idleMs: Type.Optional(Type.Number()),
+  wrapUpPrompt: Type.Optional(Type.String()),
+  ...contractFields,
+});
+
+const AskMarkerContextSchema = Type.Object({
+  prompt: Type.String(),
+  spawn: ContextSpawnSchema,
+  ask: ContextAskSchema,
+});
+
+const CassetteAskSchema = Type.Object({
+  // Plain number: the loader's Ask-position invariant owns every index error.
+  index: Type.Number(),
+  hash: Type.String(),
+  ...contractFields,
+  definitionName: Type.Optional(Type.String()),
+  context: Type.Optional(AskMarkerContextSchema),
+  sentFrames: Type.Array(FrameSchema),
+  receivedFrames: Type.Array(FrameSchema),
+  limit: Type.Optional(
+    Type.Object({
+      kind: Type.Union([
+        Type.Literal("turns"),
+        Type.Literal("toolCalls"),
+        Type.Literal("durationMs"),
+      ]),
+      count: Type.Integer({ minimum: 0 }),
+    }),
+  ),
+  stalled: Type.Optional(
+    Type.Object({ idleMs: Type.Number({ exclusiveMinimum: 0 }), destructive: Type.Boolean() }),
+  ),
+  outcome: Type.Optional(
+    Type.Object({
+      kind: Type.Literal("invalid_output"),
+      steeringEfforts: Type.Integer({ minimum: 0 }),
+    }),
+  ),
+});
+
+const TokenBreakdownSchema = Type.Object({
+  input: Type.Number(),
+  output: Type.Number(),
+  cacheRead: Type.Number(),
+  cacheWrite: Type.Number(),
+  total: Type.Number(),
+});
+
+const CassetteAgentSchema = Type.Object({
+  spawn: CassetteSpawnSchema,
+  model: Type.String(),
+  sessionFile: Type.Optional(Type.String()),
+  worktree: Type.Optional(Type.Object({ cwd: Type.String(), branch: Type.String() })),
+  git: Type.Optional(Type.Object({ branch: Type.String(), head: Type.String() })),
+  sentFrames: Type.Array(FrameSchema),
+  receivedFrames: Type.Array(FrameSchema),
+  asks: Type.Array(CassetteAskSchema),
+  stats: Type.Object({
+    tokens: Type.Union([Type.Null(), TokenBreakdownSchema]),
+    cost: Type.Union([Type.Null(), Type.Number()]),
+  }),
+});
+
+const CassetteRunSchema = Type.Object({
+  outcome: Type.Union(
+    (["completed", "failed", "stopped", "paused"] as const).map((outcome) => Type.Literal(outcome)),
+  ),
+  programFile: Type.Optional(Type.String()),
+  args: Type.Optional(Type.Unknown()),
+  programHash: Type.Optional(Type.String()),
+});
+
+/**
+ * Structure gate for one Cassette artifact read from disk. `run` stays optional
+ * here because version 1 predates it; the loader's presence invariant rejects a
+ * version 2 artifact without one, so field-path errors stay precise (no union
+ * of whole-artifact schemas).
+ */
+export const CassetteSchema = Type.Object({
+  v: Type.Union([Type.Literal(1), Type.Literal(2)]),
+  run: Type.Optional(CassetteRunSchema),
+  agents: Type.Array(CassetteAgentSchema),
+});
+
+/**
+ * Compile-time soundness: every schema-accepted value IS a Cassette, so the
+ * loader's cast cannot drift. Completeness (schema not over-strict) is pinned
+ * by the committed real-pi fixture round-trip tests.
+ */
+type AssertAssignable<T extends Base, Base> = T;
+export type CassetteSchemaIsSound = AssertAssignable<
+  Static<typeof CassetteSchema>,
+  CassetteArtifact
+>;

package/src/cassette.ts

@@ -0,0 +1,275 @@
+import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
+import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
+import type { RunOutcome } from "./events.ts";
+import type {
+  AgentStats,
+  AskInvalidOutputPlayback,
+  AskMarker,
+  AskMarkerContext,
+  Frame,
+  OpenOptions,
+  WorktreeResolution,
+} from "./transport.ts";
+import type { ThinkingLevel } from "./types.ts";
+
+/** The Cassette format this runtime writes; the loader also reads version 1. */
+export const CASSETTE_VERSION = 2 as const;
+
+/** Run-level settlement record; the ADR-0021 v2 block. */
+export interface CassetteRun {
+  /** The Run's terminal outcome. `paused` arrives with the pause slice. */
+  readonly outcome: RunOutcome;
+  /** Invocation identity: what a resume is about to re-execute. */
+  readonly programFile?: string;
+  readonly args?: unknown;
+  /** Advisory content hash of the program file; SHA-256 hex. */
+  readonly programHash?: string;
+}
+
+/** Versioned JSON artifact containing the frames exchanged during one Run. */
+export interface Cassette {
+  readonly v: typeof CASSETTE_VERSION;
+  readonly run: CassetteRun;
+  readonly agents: readonly CassetteAgent[];
+}
+
+/** On-disk shape the loader accepts: v1 carries no run block, v2 carries one. */
+export interface CassetteArtifact {
+  readonly v: 1 | typeof CASSETTE_VERSION;
+  readonly run?: CassetteRun;
+  readonly agents: readonly CassetteAgent[];
+}
+
+/** Git state observed at Agent spawn, when its cwd is a work tree. */
+export interface CassetteGit {
+  readonly branch: string;
+  readonly head: string;
+}
+
+/** One Agent's independently ordered frame streams. */
+export interface CassetteAgent {
+  readonly spawn: CassetteSpawn;
+  readonly model: string;
+  readonly sessionFile?: string;
+  /** Nondeterministic worktree location, deliberately outside spawn matching. */
+  readonly worktree?: WorktreeResolution;
+  readonly git?: CassetteGit;
+  readonly sentFrames: readonly Frame[];
+  readonly receivedFrames: readonly Frame[];
+  readonly asks: readonly CassetteAsk[];
+  readonly stats: AgentStats;
+}
+
+/** Behavioural identity supplied when opening a recorded Agent. */
+export interface CassetteSpawn {
+  readonly name: string;
+  readonly cwd: string;
+  readonly model?: string;
+  readonly systemPrompt?: string;
+  /** pi thinking level, present only when explicitly requested. */
+  readonly thinking?: ThinkingLevel;
+  /** Text appended to pi's system prompt, present even when empty. */
+  readonly appendSystemPrompt?: string;
+  /** Tool allowlist, including an explicit empty list that disables all tools. */
+  readonly tools?: readonly string[];
+  /** Tool denylist, applied after the allowlist. */
+  readonly disallowedTools?: readonly string[];
+  /** Skill-name allowlist; resolved filesystem paths never enter a Cassette. */
+  readonly skills?: readonly string[];
+  /** Skill-name denylist; resolved filesystem paths never enter a Cassette. */
+  readonly disallowedSkills?: readonly string[];
+  /** Deterministic request, present only when the Agent requested a worktree. */
+  readonly worktree?: true;
+}
+
+/** The frames attributed to one Ask marker. */
+export interface CassetteAsk {
+  readonly index: number;
+  readonly hash: string;
+  /** Canonical schema behavioral identity, never recorded model output. */
+  readonly outputSchema?: CanonicalJsonObject;
+  /** Explicit correction bound; omission remains distinct from the runtime default. */
+  readonly maxSteers?: number;
+  /** Extraction behavior identity, never recorded model output. */
+  readonly extractionPolicy?: string;
+  /** Definition identity for replay divergence diagnostics, never Ask identity. */
+  readonly definitionName?: string;
+  /** Recorded hash inputs for definition-specific divergence diagnostics. */
+  readonly context?: AskMarkerContext;
+  readonly sentFrames: readonly Frame[];
+  readonly receivedFrames: readonly Frame[];
+  /** Present only when the Ask surfaced ASK_LIMIT. */
+  readonly limit?: AskLimitOutcome;
+  /** Present only when the Ask surfaced ASK_STALLED. */
+  readonly stalled?: AskStalledOutcome;
+  /** Present only when the Ask surfaced ASK_INVALID_OUTPUT. */
+  readonly outcome?: AskInvalidOutputPlayback;
+}
+
+/** Sink consumed by recordingTransport without exposing its mutable state. */
+export interface CassetteSink {
+  reserve(options: OpenOptions): CassetteRecorder;
+  cassette(run: CassetteRun): Cassette;
+}
+
+/** Per-Agent recorder returned when a factory open begins. */
+export interface CassetteOpened {
+  readonly model: string;
+  readonly sessionFile?: string;
+  readonly worktree?: WorktreeResolution;
+  readonly git?: CassetteGit;
+}
+
+export interface CassetteRecorder {
+  opened(metadata: CassetteOpened): void;
+  failed(): void;
+  sent(frame: Frame): void;
+  received(frame: Frame): void;
+  beginAsk(marker: AskMarker): void;
+  finishAsk(
+    outcome?: AskLimitOutcome,
+    stalled?: AskStalledOutcome,
+    invalidOutput?: AskInvalidOutputPlayback,
+  ): void;
+  closed(stats: AgentStats): void;
+}
+
+interface MutableAsk {
+  readonly index: number;
+  readonly hash: string;
+  readonly outputSchema?: CanonicalJsonObject;
+  readonly maxSteers?: number;
+  readonly extractionPolicy?: string;
+  readonly definitionName?: string;
+  readonly context?: AskMarkerContext;
+  readonly sentFrames: Frame[];
+  readonly receivedFrames: Frame[];
+  limit?: AskLimitOutcome;
+  stalled?: AskStalledOutcome;
+  outcome?: AskInvalidOutputPlayback;
+}
+
+interface MutableAgent {
+  readonly spawn: CassetteSpawn;
+  readonly model: string;
+  readonly sessionFile?: string;
+  readonly worktree?: WorktreeResolution;
+  readonly git?: CassetteGit;
+  readonly sentFrames: Frame[];
+  readonly receivedFrames: Frame[];
+  readonly asks: MutableAsk[];
+  stats: AgentStats;
+  active: MutableAsk | null;
+}
+
+/** Collects a Cassette in memory; `executeRun` serializes it at Run settlement. */
+export class CassetteCollector implements CassetteSink {
+  readonly #agents: (MutableAgent | null)[] = [];
+
+  reserve(options: OpenOptions): CassetteRecorder {
+    const slot = this.#agents.length;
+    const spawn = spawnIdentity(options);
+    let agent: MutableAgent | null = null;
+    this.#agents.push(null);
+    return {
+      opened: ({ model, sessionFile, worktree, git }): void => {
+        agent = {
+          spawn,
+          model,
+          ...(sessionFile === undefined ? {} : { sessionFile }),
+          ...(worktree === undefined ? {} : { worktree }),
+          ...(git === undefined ? {} : { git }),
+          sentFrames: [],
+          receivedFrames: [],
+          asks: [],
+          stats: { tokens: null, cost: null },
+          active: null,
+        };
+        this.#agents[slot] = agent;
+      },
+      failed: (): void => {
+        this.#agents[slot] = null;
+      },
+      sent: (frame): void => append(agent, "sentFrames", frame),
+      received: (frame): void => append(agent, "receivedFrames", frame),
+      beginAsk: (marker): void => {
+        if (!agent) return;
+        const ask = { ...marker, sentFrames: [], receivedFrames: [] };
+        agent.asks.push(ask);
+        agent.active = ask;
+      },
+      finishAsk: (outcome, stalled, invalidOutput): void => {
+        if (!agent?.active) return;
+        if (outcome !== undefined) agent.active.limit = outcome;
+        if (stalled !== undefined) agent.active.stalled = stalled;
+        if (invalidOutput !== undefined) agent.active.outcome = invalidOutput;
+      },
+      closed: (stats): void => {
+        if (agent) agent.stats = stats;
+      },
+    };
+  }
+
+  cassette(run: CassetteRun): Cassette {
+    return {
+      v: CASSETTE_VERSION,
+      run,
+      agents: this.#agents
+        .filter((agent): agent is MutableAgent => agent !== null)
+        .map(
+          ({
+            spawn,
+            model,
+            sessionFile,
+            worktree,
+            git,
+            sentFrames,
+            receivedFrames,
+            asks,
+            stats,
+          }) => ({
+            spawn,
+            model,
+            ...(sessionFile === undefined ? {} : { sessionFile }),
+            ...(worktree === undefined ? {} : { worktree }),
+            ...(git === undefined ? {} : { git }),
+            sentFrames,
+            receivedFrames,
+            asks,
+            stats,
+          }),
+        ),
+    };
+  }
+}
+
+function spawnIdentity(options: OpenOptions): CassetteSpawn {
+  return {
+    name: options.name,
+    cwd: options.cwd,
+    ...(options.model === undefined ? {} : { model: options.model }),
+    ...(options.systemPrompt === undefined ? {} : { systemPrompt: options.systemPrompt }),
+    ...(options.thinking === undefined ? {} : { thinking: options.thinking }),
+    ...(options.appendSystemPrompt === undefined
+      ? {}
+      : { appendSystemPrompt: options.appendSystemPrompt }),
+    ...(options.tools === undefined ? {} : { tools: [...options.tools] }),
+    ...(options.disallowedTools === undefined
+      ? {}
+      : { disallowedTools: [...options.disallowedTools] }),
+    ...(options.skills === undefined ? {} : { skills: [...options.skills] }),
+    ...(options.disallowedSkills === undefined
+      ? {}
+      : { disallowedSkills: [...options.disallowedSkills] }),
+    ...(options.worktree === true ? { worktree: true } : {}),
+  };
+}
+
+function append(
+  agent: MutableAgent | null,
+  direction: "sentFrames" | "receivedFrames",
+  frame: Frame,
+): void {
+  if (!agent) return;
+  (agent.active ?? agent)[direction].push(frame);
+}

package/src/checkpoint-dir.ts

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { readdir, stat, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { CASSETTE_TEMP_PREFIX } from "./cassette-publish.ts";
+
+/** A temp file left by an interrupted publication is stale after one day (ADR-0021). */
+export const CHECKPOINT_TEMP_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+const CHECKPOINT_SUFFIX = join("yaag", "checkpoints");
+
+/**
+ * Resolves where a stopped Run publishes its checkpoint when `--record` set no
+ * path: `YAAG_CHECKPOINT_DIR`, then an absolute `XDG_STATE_HOME`, then
+ * `$HOME/.local/state`. A relative `XDG_STATE_HOME` is ignored (XDG spec).
+ */
+export function resolveCheckpointDirectory(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env["YAAG_CHECKPOINT_DIR"];
+  if (override !== undefined && override !== "") return override;
+  const xdg = env["XDG_STATE_HOME"];
+  if (xdg !== undefined && isAbsolute(xdg)) return join(xdg, CHECKPOINT_SUFFIX);
+  const home = env["HOME"] !== undefined && env["HOME"] !== "" ? env["HOME"] : homedir();
+  return join(home, ".local", "state", CHECKPOINT_SUFFIX);
+}
+
+/**
+ * Names one checkpoint file. There is no Run id below the transport seam yet, so
+ * the name is a millisecond timestamp, the process id, and a full random UUID.
+ * The UUID is what makes the name collision-safe: two Runs in one process can
+ * settle inside the same millisecond, and a rename onto an existing name would
+ * destroy the earlier checkpoint (ADR-0021). The UUID keeps all 122 random bits;
+ * a truncated nonce would make that silent overwrite reachable.
+ */
+export function checkpointFileName(
+  now: Date = new Date(),
+  pid: number = process.pid,
+  nonce: string = randomUUID(),
+): string {
+  const stamp = now.toISOString().replaceAll(":", "-").replaceAll(".", "-");
+  return `${stamp}-${pid}-${nonce}.cassette.json`;
+}
+
+/** Bounds for {@link cleanStaleCheckpointTemp}; both default when omitted. */
+export interface CleanStaleOptions {
+  /** Epoch milliseconds treated as "now"; defaults to `Date.now()`. */
+  readonly now?: number;
+  /** Age above which a temp file is removed; defaults to {@link CHECKPOINT_TEMP_MAX_AGE_MS}. */
+  readonly maxAgeMs?: number;
+}
+
+/**
+ * Removes publication temp files older than `maxAgeMs`. A missing directory
+ * resolves silently; a `readdir` failure rejects, so the caller owns the
+ * diagnostic. This module never writes to stderr.
+ */
+export async function cleanStaleCheckpointTemp(
+  directory: string,
+  options: CleanStaleOptions = {},
+): Promise<void> {
+  const now = options.now ?? Date.now();
+  const maxAgeMs = options.maxAgeMs ?? CHECKPOINT_TEMP_MAX_AGE_MS;
+  let entries: readonly string[];
+  try {
+    entries = await readdir(directory);
+  } catch (error) {
+    if (isMissing(error)) return;
+    throw error;
+  }
+  await Promise.all(
+    entries
+      .filter((entry) => entry.startsWith(CASSETTE_TEMP_PREFIX))
+      .map((entry) => discardWhenStale(join(directory, entry), now, maxAgeMs)),
+  );
+}
+
+async function discardWhenStale(path: string, now: number, maxAgeMs: number): Promise<void> {
+  try {
+    const info = await stat(path);
+    if (now - info.mtimeMs > maxAgeMs) await unlink(path);
+  } catch {
+    // A concurrent Run may have just renamed the temp file away; cleanup is best-effort.
+  }
+}
+
+function isMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  const { code } = error;
+  return typeof code === "string" && code === "ENOENT";
+}