@yaag/runtime 0.1.2 → 0.2.0

package/src/report-result-extension.ts

@@ -0,0 +1,128 @@
+/**
+ * yaag's private structured-result tool, loaded into every Agent at spawn.
+ *
+ * The tool stays inactive until a schema-bearing Ask delivers its output schema
+ * through the `yaag-report-result` command; the schema becomes the tool's input
+ * schema, so pi validates the arguments and the Orchestrator settles the Ask
+ * from the call instead of scraping final text (ADR-0032).
+ *
+ * Types are declared locally rather than imported from pi: this file is passed
+ * to `pi -e` as a path and must load without yaag's dependency graph.
+ */
+
+/** One tool result, in the shape pi's tool layer returns to the model. */
+export interface ReportResultToolResult {
+  readonly content: readonly { readonly type: "text"; readonly text: string }[];
+  readonly details?: { readonly reportedResult: unknown };
+  readonly isError?: boolean;
+  readonly terminate?: boolean;
+}
+
+/** One tool definition, in the shape `pi.registerTool` accepts. */
+export interface ReportResultToolDefinition {
+  readonly name: string;
+  readonly label: string;
+  readonly description: string;
+  readonly promptSnippet: string;
+  readonly promptGuidelines: readonly string[];
+  readonly parameters: object;
+  execute(toolCallId: string, params: unknown): Promise<ReportResultToolResult>;
+}
+
+/** The part of pi's extension API this extension uses (pi docs/extensions.md). */
+export interface ReportResultAPI {
+  registerTool(definition: ReportResultToolDefinition): void;
+  registerCommand(
+    name: string,
+    command: {
+      readonly description: string;
+      handler(args: string): void;
+    },
+  ): void;
+  getActiveTools(): string[];
+  setActiveTools(names: readonly string[]): void;
+}
+
+const TOOL_NAME = "report_result";
+const COMMAND_NAME = "yaag-report-result";
+const DESCRIPTION = [
+  "Report the final structured result of the current task.",
+  "Call report_result exactly once, with the complete result as its arguments.",
+  "Do not send the result as text.",
+].join(" ");
+const ALREADY_REPORTED = "result already reported";
+/**
+ * Guidelines name the tool, because pi appends them flat to one Guidelines
+ * section where "this tool" cannot be resolved (pi docs/extensions.md).
+ */
+const GUIDELINES = [
+  "End every task by calling report_result exactly once with the complete final result.",
+  "Write your prose answer first if you want one, then call report_result: prose alone does not" +
+    " deliver the result.",
+];
+
+export default function (pi: ReportResultAPI): void {
+  let reported = false;
+
+  const register = (schema: object): void => {
+    pi.registerTool({
+      name: TOOL_NAME,
+      label: "Report Result",
+      description: DESCRIPTION,
+      promptSnippet: "Report the final structured result of the current task",
+      promptGuidelines: GUIDELINES,
+      parameters: schema,
+      execute: (_toolCallId, params): Promise<ReportResultToolResult> => {
+        if (reported) {
+          return Promise.resolve({
+            content: [{ type: "text", text: ALREADY_REPORTED }],
+            isError: true,
+          });
+        }
+        reported = true;
+        // `details` carries the arguments pi validated, which differ from the
+        // arguments on `tool_execution_start` when pi coerces a value. It is
+        // what the Orchestrator settles the Ask with, live and in replay.
+        // `terminate` ends the turn on the call itself, so no extra assistant
+        // turn is paid for (ADR-0032).
+        return Promise.resolve({
+          content: [{ type: "text", text: reportedText(params) }],
+          details: { reportedResult: params },
+          terminate: true,
+        });
+      },
+    });
+  };
+
+  pi.registerCommand(COMMAND_NAME, {
+    description: "Internal yaag command: sets the structured-result schema of one Ask",
+    handler: (args): void => {
+      const schema = parseSchema(args);
+      if (schema === null) {
+        pi.setActiveTools(pi.getActiveTools().filter((name) => name !== TOOL_NAME));
+        return;
+      }
+      reported = false;
+      register(schema);
+      pi.setActiveTools([...new Set([...pi.getActiveTools(), TOOL_NAME])]);
+    },
+  });
+}
+
+/** Null deactivates the tool; a schema object activates it for the next Ask. */
+function parseSchema(args: string): object | null {
+  const payload: unknown = JSON.parse(args);
+  if (typeof payload !== "object" || payload === null || !("schema" in payload)) {
+    throw new Error("yaag-report-result requires a JSON payload with a schema field");
+  }
+  const schema: unknown = payload.schema;
+  if (schema === null) return null;
+  if (typeof schema !== "object" || Array.isArray(schema)) {
+    throw new Error("yaag-report-result schema must be a JSON schema object or null");
+  }
+  return schema;
+}
+
+function reportedText(params: unknown): string {
+  return `Result reported: ${JSON.stringify(params)}`;
+}

package/src/report-result-output.ts

@@ -0,0 +1,73 @@
+import type { TSchema } from "typebox";
+import { Value } from "typebox/value";
+import type { AskOutputResult } from "./ask-output.ts";
+import { invalidAskOutputError } from "./ask-output.ts";
+import type { ReportedResult } from "./report-result.ts";
+import type { AskInvalidOutputPlayback } from "./transport.ts";
+import { formatValidationErrors } from "./validation-errors.ts";
+
+/** The one correction an Agent gets when it settles without reporting a result. */
+export const REPORT_RESULT_CORRECTION =
+  "You did not report a result. Call the report_result tool exactly once with the final" +
+  " result. Do not send the result as text.";
+
+/** Appended to a limit wrap-up so the Agent still ends on a reported result. */
+export const REPORT_RESULT_WRAP_UP =
+  "End by calling report_result exactly once with the final result.";
+
+/** What `ASK_INVALID_OUTPUT` carries when no `report_result` call ever arrived. */
+export const REPORT_RESULT_MISSING_ERRORS: readonly string[] = [
+  "$: agent did not call report_result",
+];
+
+/** What a rethrown recorded failure carries when its recorded value now validates. */
+export const REPORT_RESULT_RECORDED_FAILURE_ERRORS: readonly string[] = [
+  "$: the recorded Ask produced no valid result",
+];
+
+/**
+ * Validates one reported result against the Ask's schema, without coercion.
+ *
+ * pi validates and coerces the call arguments first, so a failure here means
+ * the recorded or reported value does not match the schema the Ask declared.
+ */
+export function validateReportedResult(value: unknown, schema: TSchema): AskOutputResult {
+  const errors = formatValidationErrors(value, Value.Errors(schema, value));
+  return errors.length === 0 ? { ok: true, value } : { ok: false, errors };
+}
+
+/** One recorded structured Ask, as playback resolves it. */
+export interface PlaybackReportedResult {
+  readonly agent: string;
+  readonly schema: TSchema;
+  /** The call the Cassette recorded, absent when the Ask reported nothing. */
+  readonly reported: ReportedResult | undefined;
+  /** The invalid-output outcome the recorded Ask surfaced, when it surfaced one. */
+  readonly recordedOutcome: AskInvalidOutputPlayback | undefined;
+}
+
+/**
+ * Resolves a replayed structured Ask from the `report_result` call in its frames.
+ *
+ * A recorded invalid-output outcome rethrows deterministically, exactly as the
+ * recorded Run failed (ADR-0032). Otherwise the recorded call's value is
+ * re-validated, so playback and live settlement agree. Throws the same
+ * recoverable `ASK_INVALID_OUTPUT` error as a live Ask.
+ */
+export function resolvePlaybackReportedResult(playback: PlaybackReportedResult): unknown {
+  const { agent, schema, reported, recordedOutcome } = playback;
+  const result =
+    reported === undefined
+      ? { ok: false as const, errors: REPORT_RESULT_MISSING_ERRORS }
+      : validateReportedResult(reported.value, schema);
+  if (recordedOutcome !== undefined) {
+    throw invalidAskOutputError(agent, {
+      steeringEfforts: recordedOutcome.steeringEfforts,
+      // The Cassette records the outcome, never its messages, so a recorded
+      // failure whose value now validates still needs a diagnostic.
+      errors: result.ok ? REPORT_RESULT_RECORDED_FAILURE_ERRORS : result.errors,
+    });
+  }
+  if (result.ok) return result.value;
+  throw invalidAskOutputError(agent, { steeringEfforts: 0, errors: result.errors });
+}

package/src/report-result-steering.ts

@@ -0,0 +1,83 @@
+import type { TSchema } from "typebox";
+import { DEFAULT_MAX_STEERS, invalidAskOutputError } from "./ask-output.ts";
+import type { ReportedResult } from "./report-result.ts";
+import {
+  REPORT_RESULT_CORRECTION,
+  REPORT_RESULT_MISSING_ERRORS,
+  validateReportedResult,
+} from "./report-result-output.ts";
+
+/** What one Ask's report-result settlement needs from its exchange. */
+export interface ReportResultSteeringOptions {
+  readonly agent: string;
+  readonly schema: TSchema;
+  readonly maxSteers: number | undefined;
+  /** The accepted `report_result` call of the settled turn, when there is one. */
+  readonly reported: () => ReportedResult | undefined;
+  /** Atomically enters a correction effort, or false after a limit starts wrap-up. */
+  readonly beginCorrection: () => boolean;
+  /** True once a soft limit has sent its wrap-up steer. */
+  readonly wrappingUp: () => boolean;
+  /** Re-arms settlement tracking, sends the correction, and waits for its settlement. */
+  readonly correct: (message: string) => Promise<void>;
+  /** Re-arms settlement tracking, sends abort, and waits for its settlement. */
+  readonly abort: () => Promise<void>;
+}
+
+/**
+ * Settles a schema-bearing Ask from its `report_result` call (ADR-0032).
+ *
+ * Only a settlement without a valid call costs a steering effort: repairing
+ * invalid arguments is pi's own tool-retry loop, bounded by the Ask's outer
+ * envelope. A reported value that still fails validation cannot be repaired by
+ * a correction prompt, so it fails the Ask directly.
+ *
+ * Control-command failures propagate from `correct` or `abort` as Agent
+ * failures, rather than being reported as invalid-output exhaustion.
+ */
+export class ReportResultSteering {
+  readonly #options: ReportResultSteeringOptions;
+  readonly #maxSteers: number;
+
+  constructor(options: ReportResultSteeringOptions) {
+    this.#options = options;
+    this.#maxSteers = options.maxSteers ?? DEFAULT_MAX_STEERS;
+  }
+
+  /** Resolves the validated reported value, or rejects after the abort settlement. */
+  async resolve(): Promise<unknown> {
+    let efforts = 0;
+    for (;;) {
+      const reported = this.#options.reported();
+      if (reported !== undefined) return await this.#settle(reported, efforts);
+      if (efforts >= this.#maxSteers) break;
+      if (!this.#options.beginCorrection()) throw this.#invalidAfterWrapUp();
+      efforts += 1;
+      await this.#options.correct(REPORT_RESULT_CORRECTION);
+    }
+    if (this.#options.wrappingUp()) throw this.#invalidAfterWrapUp();
+    await this.#options.abort();
+    throw this.#invalid(efforts, REPORT_RESULT_MISSING_ERRORS);
+  }
+
+  async #settle(reported: ReportedResult, efforts: number): Promise<unknown> {
+    const result = validateReportedResult(reported.value, this.#options.schema);
+    if (result.ok) return result.value;
+    if (this.#options.wrappingUp()) {
+      throw invalidAskOutputError(this.#options.agent, {
+        steeringEfforts: 0,
+        errors: result.errors,
+      });
+    }
+    await this.#options.abort();
+    throw this.#invalid(efforts, result.errors);
+  }
+
+  #invalid(steeringEfforts: number, errors: readonly string[]): Error {
+    return invalidAskOutputError(this.#options.agent, { steeringEfforts, errors });
+  }
+
+  #invalidAfterWrapUp(): Error {
+    return this.#invalid(0, REPORT_RESULT_MISSING_ERRORS);
+  }
+}

package/src/report-result.ts

@@ -0,0 +1,122 @@
+import { fileURLToPath } from "node:url";
+import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
+import type { Frame } from "./transport.ts";
+
+/** The internal tool a schema-bearing Ask settles from (ADR-0032). */
+export const REPORT_RESULT_TOOL_NAME = "report_result";
+/** The pi extension command that carries one Ask's output schema to the Agent. */
+export const REPORT_RESULT_COMMAND = "yaag-report-result";
+
+/** Loadable source path for the private extension that owns `report_result`. */
+export const REPORT_RESULT_EXTENSION_PATH = fileURLToPath(
+  // `fileURLToPath` decodes percent-escapes, such as a space in a parent path.
+  new URL("./report-result-extension.ts", import.meta.url),
+);
+
+/**
+ * The prompt message that delivers one Ask's schema, or deactivates the tool.
+ *
+ * pi routes a `/command` prompt to the extension and never to the model, so the
+ * Ask's own prompt bytes stay exactly what the Orchestration Program wrote.
+ */
+export function reportResultCommandMessage(schema: CanonicalJsonObject | null): string {
+  return `/${REPORT_RESULT_COMMAND} ${JSON.stringify({ schema })}`;
+}
+
+/** True exactly for a prompt frame that carries the private schema command. */
+export function isReportResultCommandFrame(frame: Frame): boolean {
+  return (
+    frame.type === "prompt" &&
+    typeof frame.message === "string" &&
+    frame.message.startsWith(`/${REPORT_RESULT_COMMAND} `)
+  );
+}
+
+/** One schema command, and the state change the Agent accepting it earns. */
+export interface ReportResultCommand {
+  readonly message: string;
+  /** Records the new activation state, once the Agent has accepted the command. */
+  accepted(): void;
+}
+
+/**
+ * Tracks whether one Agent's `report_result` tool is active across its Asks.
+ *
+ * The tool is inactive at spawn, so an Agent that never declares an output
+ * schema exchanges exactly the frames it did before ADR-0032. A schema Ask
+ * always re-delivers its schema, because the schema is the tool's input schema.
+ */
+export class ReportResultTool {
+  #active = false;
+
+  /** The command to send before this Ask's prompt, or null when none is needed. */
+  begin(schema: CanonicalJsonObject | undefined): ReportResultCommand | null {
+    if (schema === undefined && !this.#active) return null;
+    const active = schema !== undefined;
+    return {
+      message: reportResultCommandMessage(schema ?? null),
+      accepted: (): void => {
+        this.#active = active;
+      },
+    };
+  }
+}
+
+/** The value one accepted `report_result` call reported. */
+export interface ReportedResult {
+  readonly value: unknown;
+}
+
+/**
+ * Collects the first accepted `report_result` call from one Ask's frames.
+ *
+ * The reported value is read from the tool result rather than from the call
+ * arguments, because pi coerces arguments before it runs the tool, and the
+ * coerced value is the one it validated. A refused call — invalid arguments,
+ * or a second call after the result was reported — carries an error and never
+ * becomes the Ask's result. Live settlement and Cassette playback read the
+ * same frames.
+ */
+export class ReportResultCall {
+  #reported: ReportedResult | undefined;
+  #armed = false;
+
+  /**
+   * Accepts calls immediately, for folding one recorded Ask's own frames.
+   *
+   * A live Ask uses the ordinary constructor instead, which ignores everything
+   * until that Ask sends its prompt: a replayed prefix and an abandoned turn
+   * both deliver frames after the Ask they belong to ended, and such a call
+   * must never become the next Ask's result.
+   */
+  static armed(): ReportResultCall {
+    const call = new ReportResultCall();
+    call.arm();
+    return call;
+  }
+
+  /** Starts accepting calls, from the moment this Ask's prompt is sent. */
+  arm(): void {
+    this.#armed = true;
+  }
+
+  observe(frame: Frame): void {
+    if (!this.#armed || frame.type !== "tool_execution_end") return;
+    if (frame.toolName !== REPORT_RESULT_TOOL_NAME || frame.isError === true) return;
+    if (this.#reported !== undefined) return;
+    const result: unknown = frame.result;
+    if (!isObject(result) || result.isError === true) return;
+    const details: unknown = result.details;
+    if (!isObject(details) || !("reportedResult" in details)) return;
+    this.#reported = { value: details.reportedResult };
+  }
+
+  /** The accepted call, or undefined while the Ask has no reported result. */
+  get reported(): ReportedResult | undefined {
+    return this.#reported;
+  }
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/resume-transport.ts

@@ -1,12 +1,12 @@
 import type { Cassette, CassetteAgent } from "./cassette.ts";
 import { CassetteReplay } from "./cassette-replay.ts";
-import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
 import { FrameQueue } from "./frame-queue.ts";
 import { replayMismatch } from "./replay-divergence.ts";
 import { checkResumePreconditions } from "./resume-preconditions.ts";
 import type {
   AgentStats,
   AgentTransport,
+  AskCompletion,
   AskMarker,
   AskPlayback,
   Frame,
@@ -63,7 +63,7 @@ class ResumeTransport implements AgentTransport {
     this.#continuation = continuationOptions(agent, options);
     this.#replay = new CassetteReplay(agent);
     this.model = agent.model;
-    void this.#forward(this.#replay.frames());
+    void this.#forwardReplay();
   }
 
   send(frame: Frame): void {
@@ -95,12 +95,12 @@ class ResumeTransport implements AgentTransport {
     return undefined;
   }
 
-  finishAsk(
-    outcome?: AskLimitOutcome,
-    stalled?: AskStalledOutcome,
-    invalidOutput?: import("./transport.ts").AskInvalidOutputPlayback,
-  ): void {
-    if (this.#mode === "live") this.#live?.finishAsk(outcome, stalled, invalidOutput);
+  finishAsk(completion: AskCompletion): void {
+    if (this.#mode === "live") this.#live?.finishAsk(completion);
+  }
+
+  recordedExtractionPolicy(index: number): string | undefined {
+    return this.#mode === "replay" ? this.#agent.asks[index]?.extractionPolicy : undefined;
   }
 
   close(): Promise<AgentStats> {
@@ -112,6 +112,9 @@ class ResumeTransport implements AgentTransport {
     // End the old source before attaching the new one, but keep the outward
     // queue open so Connection remains attached across the handoff.
     this.#replay.finish();
+    // Every replayed Ask is finished, so whatever the recorded prefix still has
+    // in flight belongs to none of the Asks that follow (ADR-0032).
+    this.#frames.discardPending();
     try {
       const live = await this.#liveFactory.open(this.#continuation);
       this.#live = live;
@@ -140,6 +143,21 @@ class ResumeTransport implements AgentTransport {
   async #forward(source: AsyncIterable<Frame>): Promise<void> {
     for await (const frame of source) this.#frames.push(frame);
   }
+
+  /**
+   * Forwards the recorded prefix, and stops the moment the Run goes live.
+   *
+   * The recorded frames of an Ask are released as a block, so the tail of the
+   * last replayed Ask can still be in flight when the Run goes live. Those
+   * frames belong to a finished Ask, and delivering them to the live Ask that
+   * follows would settle it, or answer it, with recorded work.
+   */
+  async #forwardReplay(): Promise<void> {
+    for await (const frame of this.#replay.frames()) {
+      if (this.#mode !== "replay") return;
+      this.#frames.push(frame);
+    }
+  }
 }
 
 function continuationOptions(agent: CassetteAgent, original: OpenOptions): OpenOptions {

package/src/run-checkpoint.ts

@@ -1,76 +1,128 @@
-import { mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, unlink } from "node:fs/promises";
+import { dirname } from "node:path";
 import type { CassetteCollector, CassetteRun } from "./cassette.ts";
 import { publishCassette } from "./cassette-publish.ts";
-import { checkpointFileName } from "./checkpoint-dir.ts";
 import type { RunOutcome } from "./events.ts";
 
+/** What a resume is about to re-execute; resolved once, at Run start. */
+export type RunIdentity = Omit<CassetteRun, "outcome">;
+
 /**
  * One Run's publication request: what settled, what it collected, and where the
- * artifact may go. `record` wins over `checkpointDir`; a Run that neither
- * recorded nor stopped publishes nothing.
+ * artifact goes. The destination is fixed at Run start (ADR-0031): the
+ * `--record` path itself, or one name in the checkpoint directory.
  */
 export interface RunCheckpointOptions {
-  /** Terminal outcome of the Run; only `stopped` publishes without `record`. */
+  /** Terminal outcome of the Run; only `stopped` keeps the artifact without `record`. */
   readonly outcome: RunOutcome;
   readonly collector: CassetteCollector;
-  /** Explicit `--record` destination; overrides the default checkpoint directory. */
+  /** Explicit `--record` destination, or undefined when the Run only checkpoints. */
   readonly record: string | undefined;
-  /** Already-resolved default directory a stopped Run publishes into. */
-  readonly checkpointDir: string;
-  /** Program entry point recorded as invocation identity; omitted when unknown. */
-  readonly programFile: string | undefined;
-  readonly args: unknown;
+  /** Where this Run's artifact lives, in-flight and at settlement. */
+  readonly destination: string;
+  /** Invocation identity written into the artifact's run block. */
+  readonly identity: RunIdentity;
 }
 
+/**
+ * What one publication attempt did. `published` covers both a written artifact
+ * and a Run that keeps none. `displaced` carries the error that must become the
+ * Run's outcome. `lost` reports a Checkpoint the Run asked for and did not get,
+ * while a primary program error keeps the outcome.
+ */
+export type RunCheckpointResult =
+  | { readonly kind: "published" }
+  | { readonly kind: "displaced"; readonly error: unknown }
+  | { readonly kind: "lost"; readonly message: string };
+
 /**
  * Publishes the collected Cassette when the Run must be restorable: always under
  * `--record`, and additionally into the checkpoint directory when the Run
- * stopped (ADR-0021/0024). Returns the error that must become the Run's outcome,
- * or null when there was nothing to publish or a primary program error owns it.
+ * stopped (ADR-0021/0024).
  */
-export async function publishRunCheckpoint(options: RunCheckpointOptions): Promise<unknown | null> {
-  const destination = checkpointDestination(options);
-  if (destination === null) return null;
+export async function publishRunCheckpoint(
+  options: RunCheckpointOptions,
+): Promise<RunCheckpointResult> {
+  if (!keepsArtifact(options)) {
+    // A clean settlement without --record publishes nothing, so the in-flight
+    // artifact this Run flushed goes away with it (ADR-0031).
+    await discardCheckpoint(options.destination);
+    return { kind: "published" };
+  }
   try {
-    if (options.record === undefined) {
-      // Only the default directory is created; an explicit --record path keeps
-      // today's rule that its directory must already exist.
-      await mkdir(options.checkpointDir, { recursive: true, mode: 0o700 });
-    }
-    await publishCassette(destination, options.collector.cassette(await runBlock(options)));
-    return null;
+    await ensureCheckpointDirectory(options.record, options.destination);
+    await publishCassette(
+      options.destination,
+      options.collector.cassette({ outcome: options.outcome, ...options.identity }),
+    );
+    return { kind: "published" };
   } catch (error) {
-    // A secondary publication failure must not displace a primary program error.
+    // A secondary publication failure must not displace a primary program error,
+    // so the loss rides on run_end instead (ticket 04). The stderr diagnostic
+    // stays: it is the CLI user's own trace of the loss.
     if (options.outcome === "failed") {
       writeRecordingDiagnostic(error);
-      return null;
+      return { kind: "lost", message: String(error) };
     }
     if (options.outcome === "stopped") {
-      return new Error(`run stopped but is not restorable: ${String(error)}`, { cause: error });
+      return {
+        kind: "displaced",
+        error: new Error(`run stopped but is not restorable: ${String(error)}`, { cause: error }),
+      };
     }
     // A requested checkpoint silently going missing is worse than rejecting an
     // otherwise successful Run (ADR-0021).
-    return error;
+    return { kind: "displaced", error };
   }
 }
 
-function checkpointDestination(options: RunCheckpointOptions): string | null {
-  if (options.record !== undefined) return options.record;
-  if (options.outcome !== "stopped") return null;
-  return join(options.checkpointDir, checkpointFileName());
+function keepsArtifact(options: RunCheckpointOptions): boolean {
+  return options.record !== undefined || options.outcome === "stopped";
+}
+
+/**
+ * Creates the checkpoint directory a Run owns. An explicit `--record` path keeps
+ * today's rule that its directory must already exist.
+ */
+export async function ensureCheckpointDirectory(
+  record: string | undefined,
+  destination: string,
+): Promise<void> {
+  if (record !== undefined) return;
+  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
 }
 
-async function runBlock(options: RunCheckpointOptions): Promise<CassetteRun> {
-  const { outcome, programFile } = options;
-  if (programFile === undefined) return { outcome };
+/** Resolves what a resume re-executes. The program hash is advisory only. */
+export async function resolveRunIdentity(
+  programFile: string | undefined,
+  args: unknown,
+): Promise<RunIdentity> {
+  if (programFile === undefined) return {};
   const programHash = await hashProgram(programFile);
-  return {
-    outcome,
-    programFile,
-    args: options.args,
-    ...(programHash === null ? {} : { programHash }),
-  };
+  return { programFile, args, ...(programHash === null ? {} : { programHash }) };
+}
+
+/**
+ * Removes the in-progress artifact of a Run that publishes nothing. A missing
+ * file is the normal case: the Run may never have reached an Ask boundary. Any
+ * other failure is a diagnostic, because the file left behind states
+ * `interrupted` and a reader trusts that word (ADR-0031).
+ */
+async function discardCheckpoint(destination: string): Promise<void> {
+  try {
+    await unlink(destination);
+  } catch (error) {
+    if (!isMissingFile(error)) writeRecordingDiagnostic(error);
+  }
+}
+
+function isMissingFile(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { readonly code?: unknown }).code === "ENOENT"
+  );
 }
 
 /** Advisory only: an unreadable program file omits the hash and never fails the Run. */