@warlock.js/ai 4.4.0 → 4.6.0

package/esm/planner/planner-run.mjs

@@ -5,9 +5,14 @@ import { PlannerPlanInvalidError } from "../errors/planner-plan-invalid-error.mj
 import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
 import { accumulateCost } from "../utils/compute-cost.mjs";
 import { generateRunId } from "../utils/generate-run-id.mjs";
+import { captureChildReport, withoutRunFrame } from "../utils/run-context.mjs";
 import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
 import { stampReportLineage } from "../utils/stamp-report-lineage.mjs";
+import { notifyObservers } from "../observe/resolve-observers.mjs";
+import { buildDag, readyNodes, sinkNodes } from "./dag-scheduler.mjs";
 import { planSchema } from "./plan-schema.mjs";
+import { deletePlannerSnapshot, persistPlannerSnapshot } from "./snapshot.mjs";
+import { log } from "@warlock.js/logger";
 
 //#region ../@warlock.js/ai/src/planner/planner-run.ts
 /**
@@ -40,7 +45,18 @@ var PlannerRun = class {
 		};
 		this.children = [];
 		this.executedSteps = [];
-		this.runId = args.options?.runId ?? generateRunId("planner");
+		this.awaitingApproval = false;
+		this.replanCount = 0;
+		this.dagResumeConsumed = false;
+		this.runId = args.resumeFrom?.runId ?? args.options?.runId ?? generateRunId("planner");
+		if (args.resumeFrom) {
+			this.plan = args.resumeFrom.plan;
+			this.executedSteps.push(...args.resumeFrom.executedSteps);
+			this.children.push(...args.resumeFrom.children);
+			this.mergeUsage(this.usage, args.resumeFrom.usage);
+			this.replanCount = args.resumeFrom.replanCount;
+			this.startedAt = args.resumeFrom.startedAt;
+		}
 	}
 	/**
 	* Run the planner end-to-end. Never throws on runtime failure —
@@ -49,19 +65,57 @@ var PlannerRun = class {
 	* `report.status`.
 	*/
 	async run() {
+		const result = await this.runPlan();
+		await notifyObservers(this.args.config.observe, result.report);
+		captureChildReport(result.report);
+		return result;
+	}
+	/**
+	* Drive the planner lifecycle and return the built result WITHOUT
+	* routing it — `run()` owns observer routing + auto-nesting so the
+	* unified tree is emitted exactly once.
+	*/
+	async runPlan() {
+		if (this.args.resumeFrom && this.args.resumeFrom.status === "completed") {
+			this.rebuildResumedTerminal("completed");
+			return this.buildResult();
+		}
 		try {
 			if (this.isAborted()) {
 				this.markCancelled();
+				await this.checkpoint(this.resolveSnapshotStatus());
+				return this.buildResult();
+			}
+			const plan = this.args.resumeFrom ? this.plan : this.args.options?.approvedPlan ?? await this.generatePlan();
+			if (this.error || !plan) {
+				await this.checkpoint(this.resolveSnapshotStatus());
 				return this.buildResult();
 			}
-			const plan = await this.generatePlan();
-			if (this.error || !plan) return this.buildResult();
+			if (!this.args.resumeFrom) {
+				this.assertPlanValid(plan);
+				if (this.error) {
+					await this.checkpoint(this.resolveSnapshotStatus());
+					return this.buildResult();
+				}
+			}
 			this.plan = plan;
+			if (!this.args.resumeFrom && this.args.options?.mode === "plan-only" && !this.args.options?.approvedPlan) {
+				this.awaitingApproval = true;
+				return this.buildResult();
+			}
 			await this.executePlan(plan);
 			await this.finalizeOutput();
 		} catch (caught) {
 			this.error = this.toAIError(caught);
 		}
+		await this.checkpoint(this.resolveSnapshotStatus());
+		if (!this.error && this.args.config.durable?.deleteOnComplete) {
+			const outcome = await deletePlannerSnapshot({
+				durable: this.args.config.durable,
+				runId: this.runId
+			});
+			if (!outcome.ok) this.logDurableFailure("snapshot.delete.failed", outcome.error);
+		}
 		return this.buildResult();
 	}
 	/**
@@ -70,15 +124,19 @@ var PlannerRun = class {
 	* agent's per-call `output`, so the model is steered to reference only
 	* real capabilities. The planning trip's usage + report roll into the
 	* planner's totals regardless of outcome.
+	*
+	* `feedback` is set only on a RE-plan: the regenerated request is
+	* seeded with the executed-step digest plus the caller's feedback so
+	* the planner revises the remaining work rather than starting cold.
 	*/
-	async generatePlan() {
+	async generatePlan(feedback) {
 		const schema = planSchema([...this.args.capabilities.keys()], this.args.maxSteps);
-		const result = await this.args.planningAgent.execute(this.buildPlanPrompt(), {
+		const result = await withoutRunFrame(() => this.args.planningAgent.execute(this.buildPlanPrompt(feedback), {
 			output: schema,
 			placeholders: this.args.options?.placeholders,
 			signal: this.args.options?.signal,
 			sessionId: this.args.options?.sessionId
-		});
+		}));
 		this.absorb(result.usage, result.report);
 		if (result.error) {
 			this.error = result.error instanceof SchemaValidationError ? new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): the planner produced no usable plan`, {
@@ -92,43 +150,179 @@ var PlannerRun = class {
 			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): the planner produced no usable plan`, { context: { runId: this.runId } });
 			return;
 		}
-		const unknownStep = plan.steps.find((step) => !this.args.capabilities.has(step.capability));
-		if (unknownStep) {
-			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): plan references unknown capability "${unknownStep.capability}"`, { context: {
-				runId: this.runId,
-				capability: unknownStep.capability
-			} });
+		this.assertPlanValid(plan);
+		if (this.error) return;
+		return plan;
+	}
+	/**
+	* Shared plan-validity guard — used both for a freshly generated plan
+	* and for a caller-supplied `approvedPlan`. Sets `this.error` to a
+	* typed {@link PlannerPlanInvalidError} when the plan is empty or names
+	* an unknown capability; a stale `approvedPlan` thus fails the same way
+	* a hallucinated capability does, never silently mis-dispatching.
+	*/
+	assertPlanValid(plan) {
+		if (!Array.isArray(plan.steps) || plan.steps.length === 0) {
+			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): the planner produced no usable plan`, { context: { runId: this.runId } });
 			return;
 		}
-		return plan;
+		const unknownStep = plan.steps.find((step) => !this.args.capabilities.has(step.capability));
+		if (unknownStep) this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): plan references unknown capability "${unknownStep.capability}"`, { context: {
+			runId: this.runId,
+			capability: unknownStep.capability
+		} });
 	}
 	/**
-	* Phase 2 — execute the plan's steps strictly in order, threading each
-	* completed step's output into the next step's input context. Stops at
-	* the first step failure (its `error` becomes the run error) or when
-	* the abort signal fires between steps. Steps beyond `maxSteps` are
-	* recorded as `skipped` without running.
+	* Phase 2 — execute the plan. Branches on `config.dag`: the default is
+	* the strict array-order sequential loop (byte-for-byte today's
+	* behavior when neither `onStep` nor `replan` is configured); `dag:
+	* true` schedules independent `dependsOn` branches in parallel.
 	*/
 	async executePlan(plan) {
+		if (this.args.config.dag) return this.executeDag(plan);
+		return this.executeSequential(plan);
+	}
+	/**
+	* Sequential executor — the original strict array-order loop, threading
+	* each completed step's output into the next step's input context.
+	* Stops at the first step failure or when the abort signal fires
+	* between steps; steps beyond `maxSteps` are recorded `skipped`.
+	*
+	* **Additive hooks (inert by default).** After each step settles it
+	* fires the `onStep` directive hook; an `abort` directive stops the run
+	* like a failure, and a `replan` directive (or, when `config.replan` is
+	* set, an unhandled failure) regenerates the REMAINING plan instead of
+	* aborting. With no `onStep` and no `replan`, the behavior is identical
+	* to before.
+	*/
+	async executeSequential(plan) {
 		const previousOutputs = [];
-		for (let index = 0; index < plan.steps.length; index++) {
-			const step = plan.steps[index];
+		let steps = plan.steps;
+		let index = 0;
+		if (this.args.resumeFrom) index = this.rehydrateSequentialState(steps, previousOutputs);
+		while (index < steps.length) {
+			const step = steps[index];
 			if (index >= this.args.maxSteps) {
 				this.recordSkipped(index, step);
+				index++;
 				continue;
 			}
 			if (this.isAborted()) {
 				this.markCancelled();
 				this.recordSkipped(index, step);
+				index++;
+				continue;
+			}
+			const completed = await this.executeStep(index, step, previousOutputs);
+			const snapshot = this.snapshotFor(index);
+			const directive = snapshot ? await this.resolveDirective(snapshot, plan, completed) : void 0;
+			if (directive?.type === "replan") {
+				const remaining = await this.regeneratePlan(directive.feedback);
+				if (this.error || !remaining) {
+					this.skipRest(steps, index + 1);
+					return;
+				}
+				steps = remaining.steps;
+				index = 0;
+				previousOutputs.length = 0;
+				previousOutputs.push(...this.executedDigest());
 				continue;
 			}
-			if (!await this.executeStep(index, step, previousOutputs)) {
-				for (let rest = index + 1; rest < plan.steps.length; rest++) this.recordSkipped(rest, plan.steps[rest]);
+			if (directive?.type === "abort") {
+				this.skipRest(steps, index + 1);
 				return;
 			}
+			index++;
 		}
 	}
 	/**
+	* DAG executor — schedule independent `dependsOn` branches in parallel.
+	*
+	* Builds the DAG (cycle / unknown-id → `PlannerPlanInvalidError`),
+	* then repeatedly computes the ready set (steps whose deps all
+	* completed), dispatches up to `maxConcurrency` of them with
+	* `Promise.all`, and feeds each step ONLY its dependencies' outputs. A
+	* failed step blocks just its descendants (recorded `skipped`);
+	* independent branches still settle. With an `output` schema set, the
+	* final `data` is the topological SINK's output (multiple sinks → a
+	* convergence error).
+	*/
+	async executeDag(plan) {
+		const dag = buildDag(plan.steps, this.args.config.name);
+		const maxConcurrency = Math.max(1, this.args.config.maxConcurrency ?? 4);
+		const completed = /* @__PURE__ */ new Set();
+		const done = /* @__PURE__ */ new Set();
+		const outputs = /* @__PURE__ */ new Map();
+		const rawOutputs = /* @__PURE__ */ new Map();
+		let executedCount = 0;
+		if (this.args.resumeFrom && !this.dagResumeConsumed) {
+			this.dagResumeConsumed = true;
+			executedCount = this.rehydrateDagState(dag, completed, done, outputs, rawOutputs);
+		}
+		while (done.size < dag.nodes.length) {
+			if (this.isAborted()) {
+				this.markCancelled();
+				this.skipDagRest(dag, done);
+				return;
+			}
+			const ready = readyNodes(dag, completed, done);
+			if (ready.length === 0) {
+				this.skipDagRest(dag, done);
+				return;
+			}
+			const batch = ready.slice(0, maxConcurrency);
+			const settled = await Promise.all(batch.map(async (node) => {
+				if (executedCount >= this.args.maxSteps) {
+					this.recordSkipped(node.index, node.step);
+					return {
+						node,
+						ran: false,
+						completed: false
+					};
+				}
+				executedCount++;
+				const previousOutputs = node.dependencies.map((dependency) => outputs.get(dependency));
+				const stepCompleted = await this.executeStep(node.index, node.step, previousOutputs);
+				if (stepCompleted) {
+					const rawOutput = this.snapshotFor(node.index)?.output;
+					rawOutputs.set(node.id, rawOutput);
+					outputs.set(node.id, this.stringifyOutput(node.step.capability, rawOutput));
+				}
+				return {
+					node,
+					ran: true,
+					completed: stepCompleted
+				};
+			}));
+			for (const entry of settled) {
+				done.add(entry.node.id);
+				if (entry.completed) completed.add(entry.node.id);
+			}
+			let replanFeedback;
+			let shouldAbort = false;
+			for (const entry of settled) {
+				if (!entry.ran) continue;
+				const snapshot = this.snapshotFor(entry.node.index);
+				const directive = snapshot ? await this.resolveDirective(snapshot, plan, entry.completed) : void 0;
+				if (directive?.type === "replan") replanFeedback = directive.feedback;
+				else if (directive?.type === "abort") shouldAbort = true;
+			}
+			if (shouldAbort) {
+				this.skipDagRest(dag, done);
+				return;
+			}
+			if (replanFeedback !== void 0) {
+				const remaining = await this.regeneratePlan(replanFeedback);
+				if (this.error || !remaining) {
+					this.skipDagRest(dag, done);
+					return;
+				}
+				return this.executeDag(remaining);
+			}
+		}
+		this.finalizeDagOutput(dag, completed, rawOutputs);
+	}
+	/**
 	* Dispatch one plan step through its capability's `executable.execute()`
 	* and fold the outcome into the accumulators. Returns `true` when the
 	* step completed, `false` when it failed (setting the run error).
@@ -138,10 +332,10 @@ var PlannerRun = class {
 		const stepStart = performance.now();
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const input = this.composeStepInput(step, previousOutputs);
-		const result = await capability.executable.execute(input, {
+		const result = await withoutRunFrame(() => capability.executable.execute(input, {
 			signal: this.args.options?.signal,
 			sessionId: this.args.options?.sessionId
-		});
+		}));
 		const childReport = "report" in result ? result.report : void 0;
 		this.absorb(result.usage, childReport);
 		const output = this.extractOutput(result);
@@ -158,6 +352,7 @@ var PlannerRun = class {
 			usage: result.usage,
 			childReport
 		});
+		await this.checkpoint("running");
 		if (failed) {
 			this.error = result.error;
 			return false;
@@ -167,6 +362,104 @@ var PlannerRun = class {
 		return true;
 	}
 	/**
+	* Resolve the steering directive for a just-settled step, shared by the
+	* sequential and DAG executors. Fires the user's `onStep` hook, then
+	* normalizes the result against the `replan` budget:
+	*
+	* - explicit `replan` directive — honored only when `config.replan` is
+	*   set and the budget remains; otherwise downgraded to `continue`.
+	* - explicit `abort` — honored.
+	* - failed step with no overriding directive — auto-`replan` when
+	*   `config.replan` is set and the budget remains (feedback = the step
+	*   error message), else `abort` (today's abort-on-first-failure).
+	*
+	* Returns `undefined` when the run should simply continue. A returned
+	* `replan` directive has ALREADY consumed one unit of the replan budget.
+	*/
+	async resolveDirective(snapshot, plan, completed) {
+		const hook = this.args.options?.onStep;
+		const userDirective = hook ? await hook(snapshot, plan) : void 0;
+		if (userDirective?.type === "replan") {
+			if (this.canReplan()) {
+				this.replanCount++;
+				return userDirective;
+			}
+		} else if (userDirective?.type === "abort") return { type: "abort" };
+		else if (userDirective?.type === "continue") return;
+		if (!completed) {
+			if (this.canReplan()) {
+				this.replanCount++;
+				return {
+					type: "replan",
+					feedback: snapshot.error?.message ?? "step failed"
+				};
+			}
+			return { type: "abort" };
+		}
+	}
+	/** Whether a re-plan is configured and the budget has room. */
+	canReplan() {
+		const replan = this.args.config.replan;
+		return replan !== void 0 && this.replanCount < replan.maxReplans;
+	}
+	/**
+	* Re-ask the planning agent for a plan over the REMAINING work — a
+	* second `generatePlan()` seeded with the executed-step digest plus the
+	* caller's feedback. Reuses the exact `generatePlan` plumbing (same
+	* schema, same `PlannerPlanInvalidError` handling), so a regenerated
+	* plan that is empty or names an unknown capability fails identically.
+	* The failed step's error is cleared so the regenerated plan runs
+	* cleanly; a fresh failure (or exhausted budget) re-sets it.
+	*/
+	async regeneratePlan(feedback) {
+		this.error = void 0;
+		return this.generatePlan(feedback);
+	}
+	/**
+	* The executed-so-far digest — one context line per completed step, in
+	* execution order. Seeds the regenerated plan's first step so it builds
+	* on what already ran.
+	*/
+	executedDigest() {
+		return this.executedSteps.filter((snapshot) => snapshot.status === "completed").map((snapshot) => this.stringifyOutput(snapshot.step.capability, snapshot.output));
+	}
+	/** The last-pushed snapshot for a given step index, if any. */
+	snapshotFor(index) {
+		for (let position = this.executedSteps.length - 1; position >= 0; position--) {
+			const snapshot = this.executedSteps[position];
+			if (snapshot.index === index) return snapshot;
+		}
+	}
+	/** Record every step from `from` onward (in a flat array plan) as skipped. */
+	skipRest(steps, from) {
+		for (let rest = from; rest < steps.length; rest++) this.recordSkipped(rest, steps[rest]);
+	}
+	/** Record every not-yet-`done` DAG node as skipped, in plan order. */
+	skipDagRest(dag, done) {
+		for (const node of dag.nodes) if (!done.has(node.id)) this.recordSkipped(node.index, node.step);
+	}
+	/**
+	* Set `this.data` from the DAG's topological sink for a configured
+	* `output` schema. "Last completed step" is meaningless under
+	* parallelism, so the sink (the step nothing depends on) is the
+	* unambiguous final output. Multiple sinks while an `output` schema is
+	* set is a convergence error — a typed `PlannerPlanInvalidError`.
+	*/
+	finalizeDagOutput(dag, completed, rawOutputs) {
+		if (!(this.args.options?.output ?? this.args.config.output) || this.error) return;
+		const sinks = sinkNodes(dag).filter((node) => completed.has(node.id));
+		if (sinks.length > 1) {
+			this.error = new PlannerPlanInvalidError(`ai.planner("${this.args.config.name}"): DAG has multiple sinks but an \`output\` schema is set — the plan must converge to a single final step`, { context: {
+				runId: this.runId,
+				sinks: sinks.map((node) => node.id)
+			} });
+			this.data = void 0;
+			return;
+		}
+		const sink = sinks[0];
+		this.data = sink ? rawOutputs.get(sink.id) : void 0;
+	}
+	/**
 	* Phase 3 — when an `output` schema is configured (factory or per-call
 	* override), validate the final completed step's output into typed
 	* `result.data`. A validation failure replaces the run error and flips
@@ -205,6 +498,7 @@ var PlannerRun = class {
 			version: this.args.config.version,
 			type: "planner",
 			status,
+			...this.error ? { error: this.error } : {},
 			startedAt: this.startedAt,
 			endedAt: (/* @__PURE__ */ new Date()).toISOString(),
 			duration: performance.now() - this.startPerf,
@@ -220,27 +514,42 @@ var PlannerRun = class {
 			rootRunId: this.runId,
 			sessionId: this.args.options?.sessionId
 		});
-		return {
+		const result = {
 			type: "planner",
 			data: this.error ? void 0 : this.data,
 			error: this.error,
 			usage: this.usage,
 			report
 		};
+		if (this.awaitingApproval) result.plan = this.plan;
+		return result;
 	}
 	/**
-	* Resolve the terminal status from the accumulated outcome. Cancelled
-	* wins over failed (an abort that also produced a step error still
-	* reads as cancelled); failed wins over completed.
+	* Resolve the terminal status from the accumulated outcome.
+	* `awaiting-approval` (plan-only short-circuit) wins over everything —
+	* nothing executed, so neither cancellation nor error applies.
+	* Otherwise cancelled wins over failed (an abort that also produced a
+	* step error still reads as cancelled); failed wins over completed.
 	*/
 	resolveStatus() {
+		if (this.awaitingApproval) return "awaiting-approval";
 		if (this.cancelledAt !== void 0) return "cancelled";
 		if (this.error) return "failed";
 		return "completed";
 	}
-	/** Build the prompt handed to the planning agent — the user's goal. */
-	buildPlanPrompt() {
-		return this.args.goal;
+	/**
+	* Build the prompt handed to the planning agent. On the first pass this
+	* is just the user's goal (byte-for-byte unchanged). On a RE-plan it
+	* prepends the executed-step digest and the steering feedback so the
+	* planner revises the remaining work.
+	*/
+	buildPlanPrompt(feedback) {
+		if (feedback === void 0) return this.args.goal;
+		const digest = this.executedDigest();
+		const sections = [`Goal: ${this.args.goal}`, ""];
+		if (digest.length > 0) sections.push("Steps already completed:", ...digest, "");
+		sections.push(`Feedback requiring a revised plan: ${feedback}`, "", "Produce a plan for the REMAINING work only.");
+		return sections.join("\n");
 	}
 	/**
 	* Compose a step's effective input: the step's own `input`, prefixed
@@ -313,6 +622,123 @@ var PlannerRun = class {
 		const mergedCost = accumulateCost(target.cost, child.cost);
 		if (mergedCost !== void 0) target.cost = mergedCost;
 	}
+	/**
+	* Re-derive the sequential cursor + prior-output context from the
+	* persisted ledger on resume. Threads every already-`completed` node's
+	* output into `previousOutputs`, returns the first index NOT completed
+	* as the resume cursor, and prunes stale non-completed ledger entries
+	* (the failed node + any skipped tail) at-or-after that cursor so the
+	* re-run repopulates them without duplicating.
+	*/
+	rehydrateSequentialState(steps, previousOutputs) {
+		let cursor = 0;
+		for (let index = 0; index < steps.length; index++) {
+			const snapshot = this.snapshotFor(index);
+			if (snapshot?.status === "completed") {
+				const step = steps[index];
+				previousOutputs.push(this.stringifyOutput(step.capability, snapshot.output));
+				cursor = index + 1;
+				continue;
+			}
+			break;
+		}
+		this.pruneLedgerFrom(cursor);
+		return cursor;
+	}
+	/**
+	* Re-derive the DAG scheduler's working sets from the persisted ledger
+	* on resume. Completed nodes go into `completed` + `done` with their
+	* string + raw outputs restored (so dependents read the right context);
+	* stale non-completed entries are pruned so the re-run repopulates them.
+	* Returns the count of nodes already dispatched (for the `maxSteps`
+	* truncation budget).
+	*/
+	rehydrateDagState(dag, completed, done, outputs, rawOutputs) {
+		const completedIndices = /* @__PURE__ */ new Set();
+		for (const node of dag.nodes) {
+			const snapshot = this.snapshotFor(node.index);
+			if (snapshot?.status !== "completed") continue;
+			completed.add(node.id);
+			done.add(node.id);
+			completedIndices.add(node.index);
+			rawOutputs.set(node.id, snapshot.output);
+			outputs.set(node.id, this.stringifyOutput(node.step.capability, snapshot.output));
+		}
+		const retained = this.executedSteps.filter((snapshot) => completedIndices.has(snapshot.index));
+		this.executedSteps.length = 0;
+		this.executedSteps.push(...retained);
+		return completedIndices.size;
+	}
+	/**
+	* Drop every ledger entry whose index is at or after `from`. Used by
+	* the sequential resume re-seed to clear the crashed run's failed /
+	* skipped frontier before the re-run repopulates it.
+	*/
+	pruneLedgerFrom(from) {
+		const retained = this.executedSteps.filter((snapshot) => snapshot.index < from);
+		this.executedSteps.length = 0;
+		this.executedSteps.push(...retained);
+	}
+	/**
+	* Map the run's terminal outcome to the persisted snapshot status.
+	* `awaiting-approval` (plan-only) never persists a durable snapshot
+	* (resume is always an execution), so it folds to `running` here —
+	* but the durable + plan-only combination is disallowed at the call
+	* site, so this path is effectively unreachable.
+	*/
+	resolveSnapshotStatus() {
+		if (this.cancelledAt !== void 0) return "cancelled";
+		if (this.error) return "failed";
+		if (this.awaitingApproval) return "running";
+		return "completed";
+	}
+	/**
+	* Build and persist a {@link PlannerSnapshot} from the current
+	* accumulators. The per-node and terminal checkpoints both route
+	* through here. No-op when `durable` is absent. A failed persist is
+	* logged and swallowed (never aborts the run), matching the supervisor
+	* / workflow checkpoint policy.
+	*/
+	async checkpoint(status) {
+		if (!this.args.config.durable || !this.plan) return;
+		const outcome = await persistPlannerSnapshot({
+			durable: this.args.config.durable,
+			runId: this.runId,
+			plannerName: this.args.config.name,
+			signature: this.args.signature,
+			version: this.args.config.version,
+			goal: this.args.goal,
+			plan: this.plan,
+			executedSteps: this.executedSteps,
+			usage: this.usage,
+			children: this.children,
+			replanCount: this.replanCount,
+			status,
+			startedAt: this.startedAt
+		});
+		if (!outcome.ok) this.logDurableFailure("snapshot.persist.failed", outcome.error);
+	}
+	/**
+	* Re-derive the terminal state when a resume short-circuits a snapshot
+	* whose run already COMPLETED. The persisted ledger is the
+	* authoritative outcome — `this.data` is restored from the last
+	* completed node so the rebuilt result carries the final output.
+	*
+	* Only reached for a `completed` snapshot — `failed` / `cancelled`
+	* snapshots re-enter execution to retry the unfinished frontier instead.
+	*/
+	rebuildResumedTerminal(_status) {
+		const lastCompleted = [...this.executedSteps].reverse().find((snapshot) => snapshot.status === "completed");
+		if (lastCompleted) this.data = lastCompleted.output;
+	}
+	/** Structured-log a durable persist/delete failure. */
+	logDurableFailure(action, error) {
+		log.warn("ai.planner", action, "durable snapshot operation failed", {
+			runId: this.runId,
+			planner: this.args.config.name,
+			error: error instanceof Error ? error.message : String(error)
+		});
+	}
 	/** Whether the caller's abort signal has fired. */
 	isAborted() {
 		return this.args.options?.signal?.aborted === true;