@yaag/cli 0.1.2 → 0.2.0

package/assets/types/runtime/report-result-output.d.ts

@@ -0,0 +1,37 @@
+import type { TSchema } from "typebox";
+import type { AskOutputResult } from "./ask-output.ts";
+import type { ReportedResult } from "./report-result.ts";
+import type { AskInvalidOutputPlayback } from "./transport.ts";
+/** The one correction an Agent gets when it settles without reporting a result. */
+export declare const REPORT_RESULT_CORRECTION: string;
+/** Appended to a limit wrap-up so the Agent still ends on a reported result. */
+export declare 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 declare const REPORT_RESULT_MISSING_ERRORS: readonly string[];
+/** What a rethrown recorded failure carries when its recorded value now validates. */
+export declare const REPORT_RESULT_RECORDED_FAILURE_ERRORS: readonly string[];
+/**
+ * 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 declare function validateReportedResult(value: unknown, schema: TSchema): AskOutputResult;
+/** 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 declare function resolvePlaybackReportedResult(playback: PlaybackReportedResult): unknown;

package/assets/types/runtime/report-result-steering.d.ts

@@ -0,0 +1,35 @@
+import type { TSchema } from "typebox";
+import type { ReportedResult } from "./report-result.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 declare class ReportResultSteering {
+    #private;
+    constructor(options: ReportResultSteeringOptions);
+    /** Resolves the validated reported value, or rejects after the abort settlement. */
+    resolve(): Promise<unknown>;
+}

package/assets/types/runtime/report-result.d.ts

@@ -0,0 +1,66 @@
+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 declare const REPORT_RESULT_TOOL_NAME = "report_result";
+/** The pi extension command that carries one Ask's output schema to the Agent. */
+export declare const REPORT_RESULT_COMMAND = "yaag-report-result";
+/** Loadable source path for the private extension that owns `report_result`. */
+export declare const REPORT_RESULT_EXTENSION_PATH: string;
+/**
+ * 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 declare function reportResultCommandMessage(schema: CanonicalJsonObject | null): string;
+/** True exactly for a prompt frame that carries the private schema command. */
+export declare function isReportResultCommandFrame(frame: Frame): boolean;
+/** 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 declare class ReportResultTool {
+    #private;
+    /** The command to send before this Ask's prompt, or null when none is needed. */
+    begin(schema: CanonicalJsonObject | undefined): ReportResultCommand | null;
+}
+/** 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 declare class ReportResultCall {
+    #private;
+    /**
+     * 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;
+    /** Starts accepting calls, from the moment this Ask's prompt is sent. */
+    arm(): void;
+    observe(frame: Frame): void;
+    /** The accepted call, or undefined while the Ask has no reported result. */
+    get reported(): ReportedResult | undefined;
+}

package/assets/types/runtime/run-checkpoint.d.ts

@@ -1,28 +1,50 @@
-import type { CassetteCollector } from "./cassette.ts";
+import type { CassetteCollector, CassetteRun } from "./cassette.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 declare function publishRunCheckpoint(options: RunCheckpointOptions): Promise<RunCheckpointResult>;
+/**
+ * Creates the checkpoint directory a Run owns. An explicit `--record` path keeps
+ * today's rule that its directory must already exist.
  */
-export declare function publishRunCheckpoint(options: RunCheckpointOptions): Promise<unknown | null>;
+export declare function ensureCheckpointDirectory(record: string | undefined, destination: string): Promise<void>;
+/** Resolves what a resume re-executes. The program hash is advisory only. */
+export declare function resolveRunIdentity(programFile: string | undefined, args: unknown): Promise<RunIdentity>;
 /** Reports a secondary Cassette publication failure without displacing the Run's primary error. */
 export declare function writeRecordingDiagnostic(error: unknown): void;

package/assets/types/runtime/run.d.ts

@@ -1,4 +1,4 @@
-import { type Cassette, CassetteCollector } from "./cassette.ts";
+import { type Cassette, type CassetteSink } from "./cassette.ts";
 import { type OrchestrationProgram } from "./define-run.ts";
 import type { StampedEventSink } from "./events.ts";
 import { type SkillProbeFactory } from "./skill-probe.ts";
@@ -44,7 +44,8 @@ export declare function executeRun<Args, Result>(program: OrchestrationProgram<A
  */
 export interface FactorySelection {
     readonly options: RunOptions;
-    readonly collector: CassetteCollector;
+    /** Receives every frame; wrapped so Ask boundaries flush the Checkpoint (ADR-0031). */
+    readonly collector: CassetteSink;
     readonly replay: Cassette | null;
     readonly resume: Cassette | null;
 }

package/assets/types/runtime/stall-watchdog.d.ts

@@ -0,0 +1,70 @@
+import type { CommandResponse } from "./connection.ts";
+import type { AskStalledOutcome } from "./errors.ts";
+import type { Frame } from "./transport.ts";
+/** Silence allowed on a live Ask before the Stall Watchdog probes the Agent. */
+export declare const DEFAULT_STALL_MS = 600000;
+/** Time allowed for the `get_state` probe to answer before yaag kills the Agent. */
+export declare const STALL_PROBE_SETTLE_MS = 45000;
+/** Why an Ask settled: normal frames, watchdog recovery, or a stall rejection. */
+export type SettlementCause = "normal" | "recovered" | "stalled";
+/** Rejection carried by {@link StallWatchdog.failed} for both stall outcomes. */
+export declare class StallSignal extends Error {
+    readonly outcome: AskStalledOutcome;
+    constructor(outcome: AskStalledOutcome);
+}
+export interface StallWatchdogOptions {
+    /** Silence, in milliseconds, that arms the probe. */
+    readonly stallMs: number;
+    /** Bounded wait for the probe response; defaults to 45s. */
+    readonly probeSettleMs?: number;
+    /** Sends one command to the Agent and resolves with its response. */
+    readonly command: (frame: Frame) => Promise<CommandResponse>;
+    /** True when this Ask already observed a terminal assistant `message_end`. */
+    readonly terminal: () => boolean;
+    /** Settles the Ask from the observed terminal state. */
+    readonly recover: () => void;
+}
+/**
+ * Default liveness guard for every live Ask (ADR-0029).
+ *
+ * It measures silence, not wall time: any Agent frame resets the timer, so a
+ * legitimately long Ask is never punished. On expiry it sends one `get_state`
+ * probe and takes one of three exits:
+ * - the probe answers, the Agent is not working, and this Ask already saw a
+ *   terminal assistant `message_end` — the Ask settles as `recovered`;
+ * - the probe answers and the Agent is still working — the Ask fails with a
+ *   recoverable `ASK_STALLED` and the Agent stays alive;
+ * - the probe stays silent — the Ask fails with a destructive `ASK_STALLED`
+ *   and the Agent is killed.
+ */
+export declare class StallWatchdog {
+    #private;
+    constructor(options: StallWatchdogOptions);
+    /** Arms the silence timer immediately before the prompt command is sent. */
+    start(): void;
+    /** Resets the silence timer. Frames that arrive after the probe are ignored. */
+    observe(_frame: Frame): void;
+    /**
+     * Disarms the watchdog for a settled turn, so the commands that follow
+     * settlement — `get_last_assistant_text` and output steering — can never be
+     * mistaken for Agent silence. Idempotent.
+     */
+    settled(): void;
+    /** Re-arms the timer for a further effort in the same Ask. Inert after a trip. */
+    rearm(): void;
+    /** Cancels every timer once the Ask leaves. Idempotent. */
+    cleanup(): void;
+    /** How this Ask settled, as reported in its `ask_end` Lifecycle Event. */
+    get cause(): SettlementCause;
+    /** The stalled outcome, once the probe protocol resolved either way. */
+    get result(): AskStalledOutcome | null;
+    /** Rejects with a {@link StallSignal} on both stall exits. */
+    get failed(): Promise<never>;
+}
+/**
+ * Resolves the effective stall budget.
+ *
+ * `false` and any value that is not above zero disable the watchdog for one
+ * Ask. An absent value takes the 10-minute default.
+ */
+export declare function stallBudgetMs(stallMs: number | false | undefined): number | null;

package/assets/types/runtime/summary-agent.d.ts

@@ -96,7 +96,13 @@ export declare function setActivity(current: AgentRecord | undefined, index: num
  * Folds an Ask settlement into the idle arm, retaining the settled Ask identity.
  * Older stamped events are ignored and legacy unstamped events use stream order.
  */
-export declare function endAsk(current: AgentRecord | undefined, index: number, at: number | null): AgentRecord;
+/** One Ask settlement as the fold sees it. */
+export interface AskSettlement {
+    readonly index: number;
+    /** A recovered settlement makes this Agent's accounting a floor, not a total. */
+    readonly recovered: boolean;
+}
+export declare function endAsk(current: AgentRecord | undefined, settlement: AskSettlement, at: number | null): AgentRecord;
 /**
  * Folds a cumulative usage snapshot without changing Agent lifecycle state.
  *

package/assets/types/runtime/summary.d.ts

@@ -9,6 +9,11 @@ export type RunState = "running" | "ended";
 interface RunSummaryBase {
     readonly program: string;
     readonly startedAt: number | null;
+    /**
+     * Path of the Run's Checkpoint, as `run_start` named it (ADR-0031). It is
+     * null for a Run whose CLI is older than that event field.
+     */
+    readonly artifact: string | null;
     readonly agents: Readonly<Record<string, AgentInfo>>;
     readonly asksStarted: number;
     readonly asksSettled: number;
@@ -31,6 +36,11 @@ export interface EndedRunSummary extends RunSummaryBase {
     readonly ok: boolean;
     /** The `run_end.at` event fact used to reject strictly older stamped endings. */
     readonly endedAt: number | null;
+    /**
+     * The Run asked for a Checkpoint with `--record`, failed, and lost the
+     * artifact too. Carries the publication error text (ticket 04).
+     */
+    readonly checkpointLost?: string;
 }
 /**
  * The pure, discriminated observer fold of a Run's Lifecycle Events.

package/assets/types/runtime/thinking-level.d.ts

@@ -0,0 +1,11 @@
+/**
+ * pi's supported thinking levels.
+ *
+ * Lives in its own leaf module so both `types.ts` and the Model Resolution
+ * modules can depend on it without forming an import cycle.
+ */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+/** Every thinking level pi accepts, in documented order. */
+export declare const THINKING_LEVELS: readonly ThinkingLevel[];
+/** True only for one of pi's thinking levels; case-sensitive and total. */
+export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;

package/assets/types/runtime/transport.d.ts

@@ -1,6 +1,7 @@
 import type { CanonicalJsonObject } from "./ask-contract-identity.ts";
 import type { AskLimitOutcome, AskStalledOutcome } from "./errors.ts";
-import type { AskOptions, SpawnOptions, ThinkingLevel } from "./types.ts";
+import type { ReportedResult } from "./report-result.ts";
+import type { AskOptions, ResolvedSpawnOptions, ThinkingLevel } from "./types.ts";
 /**
  * The one seam of the runtime (ticket 04). An AgentTransport represents a whole
  * Agent and exchanges raw JSONL frames; it is the only place a process is known.
@@ -31,8 +32,8 @@ export interface AgentStats {
 /** Recorded inputs used to explain an Ask-hash mismatch without changing identity. */
 export interface AskMarkerContext {
     readonly prompt: string;
-    readonly spawn: Pick<SpawnOptions, "cwd" | "model" | "systemPrompt" | "thinking" | "appendSystemPrompt" | "tools" | "disallowedTools" | "skills" | "disallowedSkills" | "worktree">;
-    readonly ask: Pick<AskOptions, "maxTurns" | "maxToolCalls" | "maxDurationMs" | "idleMs" | "wrapUpPrompt"> & {
+    readonly spawn: Pick<ResolvedSpawnOptions, "cwd" | "model" | "systemPrompt" | "thinking" | "appendSystemPrompt" | "tools" | "disallowedTools" | "skills" | "disallowedSkills" | "worktree">;
+    readonly ask: Pick<AskOptions, "maxTurns" | "maxToolCalls" | "maxDurationMs" | "idleMs" | "stallMs" | "wrapUpPrompt"> & {
         readonly outputSchema?: CanonicalJsonObject;
         readonly maxSteers?: number;
         readonly extractionPolicy?: string;
@@ -60,6 +61,17 @@ export interface AskInvalidOutputPlayback {
     readonly kind: "invalid_output";
     readonly steeringEfforts: number;
 }
+/** What one live Ask produced, reported to its transport when the Ask finishes. */
+export interface AskCompletion {
+    /** Limit outcome, present only when the Ask rejected with ASK_LIMIT. */
+    readonly limit?: AskLimitOutcome;
+    /** Stalled outcome, present only when the Ask rejected with ASK_STALLED. */
+    readonly stalled?: AskStalledOutcome;
+    /** Invalid structured-output result, present only when it surfaced. */
+    readonly invalidOutput?: AskInvalidOutputPlayback;
+    /** The Stall Watchdog settled this Ask from observed state (ADR-0029). */
+    readonly recovered?: true;
+}
 /** Presence identifies Cassette playback, including recorded successful Asks. */
 export interface AskPlayback {
     /** Limit outcome recorded for this Ask, if it rejected with ASK_LIMIT. */
@@ -68,8 +80,26 @@ export interface AskPlayback {
     readonly stalled?: AskStalledOutcome;
     /** Invalid structured-output result recorded for this Ask, if it surfaced. */
     readonly outcome?: AskInvalidOutputPlayback;
+    /**
+     * The result the recorded Ask reported through `report_result`, read from its
+     * frames when the Cassette holds one. Reading it here keeps playback a pure
+     * function of the Cassette instead of a race with the replayed frame stream.
+     */
+    readonly reported?: ReportedResult;
     /** Whether recorded correction history has an abort settlement after final text. */
     readonly awaitsAbortSettlement?: true;
+    /**
+     * The recorded Ask settled through Stall Watchdog recovery, so no
+     * `agent_settled` frame exists: playback settles on the terminal assistant
+     * `message_end` instead.
+     */
+    readonly recovered?: true;
+    /**
+     * False when the recorded Ask holds no `agent_settled` frame. Playback then
+     * surfaces the recorded outcome instead of waiting for a settlement that the
+     * Cassette does not contain.
+     */
+    readonly settles?: false;
 }
 /** One Agent, as the layer above sees it. */
 export interface AgentTransport {
@@ -85,7 +115,14 @@ export interface AgentTransport {
      */
     beginAsk(marker: AskMarker): AskPlayback | undefined;
     /** Reports surfaced live outcomes; replay ignores completion. */
-    finishAsk(outcome?: AskLimitOutcome, stalled?: AskStalledOutcome, invalidOutput?: AskInvalidOutputPlayback): void;
+    finishAsk(completion: AskCompletion): void;
+    /**
+     * The extraction policy recorded for the Ask at `index`, when a Cassette
+     * backs it. An Ask recorded under an older policy keeps that policy, so its
+     * identity and its settlement behavior stay the ones it was recorded with
+     * (ADR-0032). Live transports have nothing recorded and omit this method.
+     */
+    recordedExtractionPolicy?(index: number): string | undefined;
     /**
      * Shut the Agent down and report its cost. Idempotent.
      * Owns the whole reap contract, so nothing above this interface knows what a

package/assets/types/runtime/types.d.ts

@@ -1,16 +1,27 @@
 import type { Static, TSchema } from "typebox";
-/** pi's supported thinking levels. */
-export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+import type { ModelSpec, ThinkingSpec } from "./model-resolution.ts";
+import type { ThinkingLevel } from "./thinking-level.ts";
+export type { ThinkingLevel } from "./thinking-level.ts";
 /** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
 export interface SpawnOptions {
     /** Working directory. Defaults to the Orchestrator's cwd. */
     readonly cwd?: string;
-    /** Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default. */
-    readonly model?: string;
+    /**
+     * Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default.
+     *
+     * An array is an ordered fallback list and a function picks the next candidate
+     * from the failures so far. Any resolved pattern may carry an inline thinking
+     * suffix (`"opus-5:medium"`), which wins over `thinking`.
+     */
+    readonly model?: ModelSpec;
     /** Replaces the default system prompt (`pi --system-prompt`). */
     readonly systemPrompt?: string;
-    /** Sets pi's thinking level; omission preserves pi's default. */
-    readonly thinking?: ThinkingLevel;
+    /**
+     * Sets pi's thinking level; omission preserves pi's default. A function picks
+     * the level from the settled model, and is not consulted for a model pattern
+     * that carries an inline thinking suffix.
+     */
+    readonly thinking?: ThinkingSpec;
     /** Appends text to pi's system prompt (`pi --append-system-prompt`). */
     readonly appendSystemPrompt?: string;
     /**
@@ -46,6 +57,11 @@ export interface SpawnOptions {
     /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
     readonly worktree?: boolean;
 }
+/** Spawn options after Model Resolution has settled one model and thinking level. */
+export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking"> {
+    readonly model?: string;
+    readonly thinking?: ThinkingLevel;
+}
 /** Topology-only fields that may change when spawning an Agent Definition. */
 export interface SpawnOverrides {
     /** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
@@ -81,14 +97,31 @@ export interface AskOptions {
      * idle detection (ADR-0020).
      */
     readonly idleMs?: number;
+    /**
+     * Silence budget in milliseconds for the Stall Watchdog, which guards every
+     * live Ask by default (ADR-0029). On expiry yaag probes the Agent and either
+     * recovers a missed settlement or rejects with `ASK_STALLED`. Omission uses
+     * the 10-minute default. `false`, and any value that is not above zero,
+     * disable the watchdog for this Ask.
+     */
+    readonly stallMs?: number | false;
     /** Per-Ask replacement for the runtime's wrap-up steering message. */
     readonly wrapUpPrompt?: string;
 }
 /** Ask options that require a schema and preserve its inferred successful result. */
 export interface StructuredAskOptions<Schema extends TSchema> extends AskOptions {
-    /** TypeBox schema that changes successful Ask resolution from text to a parsed value. */
+    /**
+     * TypeBox object schema the Agent reports its result against, instead of text.
+     *
+     * It becomes the input schema of one internal tool, so it must describe an
+     * object (ADR-0032).
+     */
     readonly outputSchema: Schema;
-    /** Maximum corrective steering efforts for this Ask; defaults to 3 when omitted. */
+    /**
+     * Maximum settlements without a reported result that this Ask corrects;
+     * defaults to 3 when omitted. Argument repair inside a turn is the Agent's
+     * own loop and costs nothing here.
+     */
     readonly maxSteers?: number;
 }
 /**
@@ -108,12 +141,14 @@ export interface Handle {
      * Sends a prompt and resolves after the Agent's turn settles.
      *
      * Schema-free calls resolve with the exact final assistant text. Calls with
-     * `outputSchema` resolve with the extracted, TypeBox-validated value. Rejects
-     * with a YaagError for a failed or empty turn, timeout, `ASK_LIMIT`, or dead
-     * Agent; invalid structured output rejects recoverably with
-     * `ASK_INVALID_OUTPUT` after at most `maxSteers` (default 3) in-Ask
-     * correction efforts and an abort settlement. These recoverable outcomes
-     * leave the Handle reusable. A concurrent call rejects with `AGENT_BUSY`.
+     * `outputSchema` resolve with the TypeBox-validated value the Agent reports
+     * through one internal tool call (ADR-0032). Rejects with a YaagError for a
+     * failed or empty turn, timeout, `ASK_LIMIT`, or dead Agent. An Ask that
+     * settles without a reported result is corrected at most `maxSteers` times
+     * (default 3) and then rejects recoverably with `ASK_INVALID_OUTPUT` after an
+     * abort settlement; a reported value the schema rejects fails the same way
+     * without a correction. These recoverable outcomes leave the Handle reusable.
+     * A concurrent call rejects with `AGENT_BUSY`.
      */
     ask<Schema extends TSchema>(prompt: string, options: StructuredAskOptions<Schema>): Promise<Static<Schema>>;
     ask(prompt: string, options?: AskOptions): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/cli",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -16,13 +16,13 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "bun test src scripts",
-    "test:e2e": "bun test e2e"
+    "test": "bun test --timeout 30000 src scripts",
+    "test:e2e": "bun test --timeout 30000 e2e"
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "workspace:*",
-    "@yaag/tui": "workspace:*",
+    "@yaag/runtime": "0.2.0",
+    "@yaag/tui": "0.2.0",
     "typebox": "1.3.7"
   }
 }

package/src/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env bun
-import { writeSync } from "node:fs";
 import { resolve } from "node:path";
 import {
+  assertReplayable,
   executeRun,
   isOrchestrationProgram,
   isYaagError,
@@ -13,6 +13,7 @@ import {
 import { interactiveAvailable } from "./alt-screen.ts";
 import { parseArgv } from "./argv.ts";
 import { runInteractive } from "./interactive-run.ts";
+import { writeChannel, writeChannelFd } from "./output-channel.ts";
 import { createPlainPresenter } from "./presenter.ts";
 import { executeOptions, formatResult, type RunFlags } from "./run-invocation.ts";
 import { registerRuntimeAlias } from "./runtime-alias.ts";
@@ -24,18 +25,22 @@ registerRuntimeAlias();
 export async function main(argv: readonly string[]): Promise<number> {
   const parsed = parseArgv(argv);
   if (!parsed.ok) {
-    process.stderr.write(`${parsed.error}\n`);
+    writeChannel(process.stderr, `${parsed.error}\n`);
     return 2;
   }
 
   try {
     if (parsed.command === "setup-workspace") {
-      process.stdout.write(`${(await setupWorkspace(resolve(parsed.dir))).join("\n")}\n`);
+      writeChannel(process.stdout, `${(await setupWorkspace(resolve(parsed.dir))).join("\n")}\n`);
       return 0;
     }
-    // A bad artifact must fail before importing an arbitrary program module.
-    if (parsed.command === "run" && (parsed.replay !== undefined || parsed.resume !== undefined)) {
-      await loadCassette(parsed.replay ?? parsed.resume ?? "");
+    // A bad artifact must fail before importing an arbitrary program module,
+    // and an interrupted artifact is a bad artifact for strict replay (ADR-0031).
+    if (parsed.command === "run" && parsed.replay !== undefined) {
+      assertReplayable(await loadCassette(parsed.replay), parsed.replay);
+    }
+    if (parsed.command === "run" && parsed.resume !== undefined) {
+      await loadCassette(parsed.resume);
     }
     const programFile = resolve(parsed.file);
     const program = await loadProgram(programFile);
@@ -50,14 +55,18 @@ export async function main(argv: readonly string[]): Promise<number> {
       quiet: parsed.quiet,
     });
   } catch (error) {
-    process.stderr.write(`[yaag] ${error instanceof Error ? error.message : String(error)}\n`);
+    writeChannel(
+      process.stderr,
+      `[yaag] ${error instanceof Error ? error.message : String(error)}\n`,
+    );
     return parsed.command === "run" && isYaagError(error) && error.code === "ARGS_INVALID" ? 2 : 1;
   }
 }
 
 function describe(program: OrchestrationProgram): number {
   const definition = programDefinition(program);
-  process.stdout.write(
+  writeChannel(
+    process.stdout,
     `${JSON.stringify({
       name: definition.name ?? null,
       description: definition.description ?? null,
@@ -110,7 +119,7 @@ async function runPlain(program: OrchestrationProgram, flags: RunFlags): Promise
       executeOptions(flags, eventSink(flags.eventsFd, presenter.present), stop.signal),
     );
     const output = formatResult(result);
-    if (output !== null) process.stdout.write(`${output}\n`);
+    if (output !== null) writeChannel(process.stdout, `${output}\n`);
     return 0;
   } finally {
     process.off("SIGINT", onSignal);
@@ -128,7 +137,7 @@ async function runPlain(program: OrchestrationProgram, flags: RunFlags): Promise
  */
 function eventSink(fd: number | undefined, present: StampedEventSink): StampedEventSink {
   return (event) => {
-    if (fd !== undefined) writeSync(fd, `${JSON.stringify({ v: 1, ...event })}\n`);
+    if (fd !== undefined) writeChannelFd(fd, `${JSON.stringify({ v: 1, ...event })}\n`);
     present(event);
   };
 }