@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/research/generate-plan.js

@@ -1,6 +1,6 @@
 /**
- * generatePlan — a loop-driving tool: a focused `runAgent` loop that builds
- * an analysis plan (a DAG of steps).
+ * generatePlan — a loop-driving tool: a focused agent loop that builds an
+ * analysis plan (a DAG of steps).
  *
  * The dataset's facts are NOT an input. They are read here, server-side, from
  * the analysis's persisted data profile — the one durable record of what the
@@ -10,34 +10,40 @@
  * caller-typed dataset summary would be a model re-transcribing a record the
  * database already holds, and it would lose fidelity at every hop.
  *
- * The tool drives an internal "planner" agent that communicates outcomes
- * EXCLUSIVELY via three terminal tool calls:
+ * The tool drives an internal "planner" agent that gives its outcome through
+ * three terminal tools. None of them ends the run, and none writes:
  *
- *   - submit_plan(plan)         → terminal success: re-validates + persists;
- *                                 rejected candidates return structured issues
- *   - request_clarification(…)  → terminal: planner needs more context
- *   - report_blocker(reason)    → terminal: no viable plan
+ *   - submit_plan(plan)         → checks a candidate; gives back the accepted
+ *                                 plan or structured issues
+ *   - request_clarification(…)  → the planner needs more context
+ *   - report_blocker(reason)    → no viable plan
  *
- * The planner is an `AgentDefinition` driven by `runAgent`; the pool and
- * resource id are an explicit `Pool` dependency and the request-scoped
- * `Session`. The planner prompt injects the agent catalog and exposes the
- * terminal-tool surface above.
+ * After the run, the tool selects the outcome from the recorded calls — the
+ * last accepted plan, else the last clarification, else the first blocker —
+ * and persists an accepted plan under an id that a rerun of the call gives again.
  */
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
+import { createHash } from "node:crypto";
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { formatAgentCatalog } from "../../agents/sandbox-catalog.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
-import { DEFAULT_SALVAGE_ITERATIONS, runToTerminal } from "../../loop/run-to-terminal.js";
-import { passthroughStep } from "../../loop/run-step.js";
+import { DEFAULT_SALVAGE_REQUESTS, runWithSalvage } from "../../loop/run-loop.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
+import { PLAN_ID_RE } from "../../contracts/schemas/chat-parts.js";
 import { effectiveDeadlineMs } from "../../providers/types.js";
+import { isUnknownArray } from "../../lib/unknown-array.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
 import { defineTool } from "../define-tool.js";
 import { createReadToolOutputTool } from "../read-tool-output.js";
 import { createListAvailablePackagesTool } from "../sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../sandbox/list-available-refs.js";
-import { createReportBlockerToolFor } from "../sandbox/report-blocker.js";
+import { blockerOf, createReportBlockerToolFor } from "../sandbox/report-blocker.js";
+import { terminalTextSchema } from "../terminal-text.js";
 import { searchGeoDatasetsTool } from "../bio/search-geo-datasets.js";
 import { createNcbiTools } from "../bio/keys.js";
+import { createKnowledgeTools } from "../knowledge/index.js";
 import { queryDocsTool, resolveLibraryIdTool } from "./context7-docs.js";
 import { searchArxivTool } from "./search-arxiv.js";
 import { createSearchGithubReposTool } from "./search-github-repos.js";
@@ -50,8 +56,8 @@ import { validatePlan } from "../../schemas/validate-plan.js";
 import { AnalysisPlanSchema } from "../../schemas/workflow-state.js";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { unwrapOrThrow } from "../../lib/result.js";
-import { hintForZodIssue } from "../../lib/zod-issues.js";
-import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.js";
+import { decodeObjectString, hintForZodIssue } from "../../lib/zod-issues.js";
+import { loadDataProfileStatus, loadPlan, upsertPlan } from "../../state/index.js";
 // ── Tool-level config ──────────────────────────────────────────────
 /** Sub-agent identity for the planner — provenance only. */
 const PLANNER_AGENT_ID = "planner";
@@ -62,17 +68,25 @@ const PLANNER_AGENT_ID = "planner";
  * The number is deliberately far above what a plan costs. A well-grounded plan
  * still costs two or three calls, because the prompt gates the research phase on
  * what the seed does not already answer. What the ceiling must never do is stop
- * a planner that is searching correctly. A capped run takes the forced wrap-up
- * path and submits the plan that it had, not the plan that it was building.
- * Thus the wall-clock guard, not this number, is what bounds the worst case.
+ * a planner that is searching correctly. A capped run gets the salvage request
+ * and submits the plan that it had, not the plan that it was building. Thus the
+ * wall-clock guard, not this number, is what bounds the worst case.
  */
 const PLANNER_MAX_ITERATIONS = 300;
 /** Wall-clock guard for a single plan-generation invocation. */
 const PLAN_TIMEOUT_MS = 1_800_000;
+/**
+ * The refusals of the call guard that end the search phase of one plan. A
+ * planner that the guard refused this many times is not searching, it is
+ * looping, and the salvage request lets it submit the plan it has. Six
+ * is above any count a frontier planner reached in the Phase 0 campaign
+ * (zero) and far below the hundred-plus refused calls of a looping run.
+ */
+const PLANNER_REFUSAL_LIMIT = 6;
 // ── Diagnostic bounds ───────────────────────────────────────────────
 //
-// This tool runs on `passthroughStep`: it writes no ledger row and owns no
-// durable stream, so its log records are the ONLY account of an invocation that
+// This tool writes no ledger row before its persist and owns no durable stream,
+// so its log records are the ONLY account of an invocation that
 // survives the turn. That makes them worth spending detail on — and makes every
 // one of them a place an unbounded model-authored string could reach a log file.
 // Each bound below is what keeps a record readable and a sink affordable when the
@@ -114,7 +128,12 @@ function bounded(value, max) {
 const MODEL_AUTHORED_KEY = "modelAuthored";
 /** Nest model-authored prose under {@link MODEL_AUTHORED_KEY}, or contribute nothing when there is none. */
 function modelAuthored(fields) {
-    const present = Object.entries(fields).filter((entry) => entry[1] !== undefined && entry[1].length > 0);
+    const present = Object.entries(fields).reduce((kept, entry) => {
+        const value = entry[1];
+        if (value !== undefined && value.length > 0)
+            kept.push([entry[0], value]);
+        return kept;
+    }, []);
     return present.length === 0 ? {} : { [MODEL_AUTHORED_KEY]: Object.fromEntries(present) };
 }
 function toRejectionRecord(attempt, issues) {
@@ -130,8 +149,24 @@ function toRejectionRecord(attempt, issues) {
         messages: kept.map((i) => bounded(i.message, MAX_LOGGED_ISSUE_CHARS)),
     };
 }
-function createPlannerTrace() {
-    return { submitAttempts: 0, rejectedAttempts: 0, rejections: [], duplicateTerminalCalls: 0 };
+function traceOf(steps) {
+    let submitAttempts = 0;
+    let rejectedAttempts = 0;
+    const rejections = [];
+    for (const step of steps) {
+        for (const call of step.calls) {
+            if (call.toolName !== SUBMIT_PLAN_TOOL_ID || call.output === undefined)
+                continue;
+            submitAttempts += 1;
+            const issues = submitIssuesOf(call.output);
+            if (issues === undefined)
+                continue;
+            rejectedAttempts += 1;
+            if (rejections.length < MAX_LOGGED_REJECTIONS)
+                rejections.push(toRejectionRecord(submitAttempts, issues));
+        }
+    }
+    return { submitAttempts, rejectedAttempts, rejections };
 }
 // ── Prompt / catalog ────────────────────────────────────────────────
 /** The planner system prompt is deterministic per policy — build it once per
@@ -139,6 +174,53 @@ function createPlannerTrace() {
 function plannerInstructions(resourcePolicy) {
     return plannerPrompt(formatAgentCatalog(), resourcePolicy);
 }
+const ValidationIssueSchema = z.object({ path: z.string(), code: z.enum(["schema", "semantic"]), message: z.string(), hint: z.string().optional() });
+const SubmitPlanOutputSchema = z.discriminatedUnion("accepted", [
+    z.object({ accepted: z.literal(false), issues: z.array(ValidationIssueSchema) }),
+    z.object({ accepted: z.literal(true), plan: PlannerPlanSchema }),
+]);
+const SUBMIT_PLAN_TOOL_ID = "submit_plan";
+const REQUEST_CLARIFICATION_TOOL_ID = "request_clarification";
+const ClarificationSchema = z.object({ kind: z.literal("clarification"), question: z.string(), questionContext: z.string().optional() });
+/** The issues of a refused submission, or `undefined` for an accepted one and for an output that is no submission. */
+function submitIssuesOf(output) {
+    if (output.outcome === "error")
+        return [{ path: "plan", code: "schema", message: output.text }];
+    if (output.outcome !== "ok")
+        return undefined;
+    const parsed = SubmitPlanOutputSchema.safeParse(output.value);
+    return parsed.success && !parsed.data.accepted ? parsed.data.issues : undefined;
+}
+/**
+ * The outcome of a run, selected from its recorded calls: the last accepted
+ * plan, else the last clarification, else the first blocker.
+ */
+function selectedOutcomeOf(steps) {
+    let plan;
+    let clarification;
+    for (const step of steps) {
+        for (const call of step.calls) {
+            if (call.output?.outcome !== "ok")
+                continue;
+            if (call.toolName === SUBMIT_PLAN_TOOL_ID) {
+                const parsed = SubmitPlanOutputSchema.safeParse(call.output.value);
+                if (parsed.success && parsed.data.accepted)
+                    plan = parsed.data.plan;
+            }
+            else if (call.toolName === REQUEST_CLARIFICATION_TOOL_ID) {
+                const parsed = ClarificationSchema.safeParse(call.output.value);
+                if (parsed.success)
+                    clarification = { kind: "clarification", question: parsed.data.question, questionContext: parsed.data.questionContext };
+            }
+        }
+    }
+    if (plan !== undefined)
+        return { kind: "plan", plan };
+    if (clarification !== undefined)
+        return clarification;
+    const blocker = blockerOf(steps);
+    return blocker === null ? null : { kind: "blocker", reason: blocker.reason };
+}
 // ── Prior plan serialization (iteration context) ───────────────────
 /**
  * Format a loaded prior plan as a markdown block the planner can read —
@@ -255,6 +337,10 @@ function renderDataContext(grounding, analysisId) {
     }
 }
 // ── Persistence ─────────────────────────────────────────────────────
+/** The id of the plan of one call. A rerun of the call gives the same id, thus the upsert keeps one plan. */
+function planIdFor(ctx) {
+    return `pln-${createHash("sha256").update(`${ctx.analysisId}:${ctx.invocationId}`).digest("hex").slice(0, 8)}`;
+}
 /**
  * Persist a validated plan. Returns the planId, or an outcome-ready error
  * with a sanitized message — DB-shape errors never leak to the planner.
@@ -266,7 +352,9 @@ function renderDataContext(grounding, analysisId) {
  */
 async function persistPlan(plan, ctx, pool, logger) {
     try {
-        const planId = unwrapOrThrow(await insertPlan(pool, {
+        const planId = planIdFor(ctx);
+        unwrapOrThrow(await upsertPlan(pool, {
+            planId,
             analysisId: ctx.analysisId,
             plan: hydratePlanSteps(plan),
             parentPlanId: ctx.parentPlanId,
@@ -274,8 +362,9 @@ async function persistPlan(plan, ctx, pool, logger) {
         return { ok: true, planId };
     }
     catch (err) {
-        const raw = err instanceof Error ? err.message : String(err);
-        const isParentValidation = /^parent plan .* (?:not found|belongs to a different analysis)$/i.test(raw);
+        const raw = errorMessageOf(err) ?? textOf(err);
+        const lower = raw.toLowerCase();
+        const isParentValidation = lower.startsWith("parent plan ") && (lower.endsWith("not found") || lower.endsWith("belongs to a different analysis"));
         logger.error("plan persistence failed", {
             parentPlanId: ctx.parentPlanId,
             stepCount: plan.steps.length,
@@ -297,14 +386,153 @@ function zodIssuesToValidationIssues(error, input, rootPath = "plan") {
         hint: hintForZodIssue(i, input),
     }));
 }
+function rememberAnswer(memory, answer) {
+    memory.steps.clear();
+    memory.claims.clear();
+    memory.digest = answer.snapshot.digest;
+    for (const step of answer.plan_skeleton) {
+        memory.steps.set(step.id, step);
+        for (const claim of step.grounding.claims)
+            memory.claims.add(claim);
+        for (const alternative of step.alternatives)
+            for (const rule of alternative.rules)
+                memory.claims.add(rule);
+        if (step.disputed !== undefined)
+            memory.claims.add(step.disputed.rule);
+    }
+    for (const claim of answer.claims)
+        memory.claims.add(claim.id);
+    for (const flag of answer.flags)
+        memory.claims.add(flag.rule);
+}
+/** The rule of a claim id: `R-0001` of `R-0001@e7d0`. */
+function ruleOf(claim) {
+    return claim.split("@")[0] ?? claim;
+}
+/** One claim id per rule of the answer. A rule with two ids in one answer cannot be repaired, and it is absent. */
+function claimsByRule(claims) {
+    const byRule = new Map();
+    const ambiguous = new Set();
+    for (const claim of claims) {
+        const rule = ruleOf(claim);
+        if (byRule.has(rule))
+            ambiguous.add(rule);
+        else
+            byRule.set(rule, claim);
+    }
+    for (const rule of ambiguous)
+        byRule.delete(rule);
+    return byRule;
+}
+/**
+ * Restore the grounding fields the host owns on each candidate step, from the
+ * last answer. A model copies the skeleton into the plan, and it drops the
+ * template field at times, or it miscopies the 64-character digest or the
+ * hash of a claim id, while it keeps the claims and the settings.
+ *
+ * On a step that copies a skeleton step, by step id, the host stamps the
+ * snapshot digest of the answer and restores a dropped template: the digest
+ * is what pins the step to the snapshot, and the template is what the host
+ * binds the contract to. A step whose snapshot is `none` states that it does
+ * not use the answer, and it stays as it is. A step whose status is
+ * `ungrounded` states a departure from the answer: the digest is stamped,
+ * and no template is restored, because the template realizes the method the
+ * step left.
+ *
+ * On every step, a claim id the answer did not return is repaired when the
+ * answer holds one claim of the same rule: one snapshot holds one version of
+ * a rule, thus the rule names the claim. A claim of a rule the answer does
+ * not hold is an issue that rejects the plan, so the model cites a claim of
+ * the answer or removes it.
+ *
+ * A step the skeleton does not hold, for example a robustness step the model
+ * adds under its own id, gets the digest stamped too when one of its claims
+ * is a claim of the answer: the claim vouches that the step consulted the
+ * answer, and the digest it typed is as prone to a miscopy as any other. A
+ * step with no claim of the answer stays as the model wrote it, because
+ * nothing of the answer vouches for it. Returns the stamped steps, the
+ * restored steps, the repaired claims, and the issues beside the new
+ * candidate. A candidate that is not a plan-shaped object, or a plan with no
+ * answer, comes back as it is.
+ */
+function restoreSkeletonGrounding(candidate, memory) {
+    const decoded = decodeObjectString(candidate);
+    const decodedRecord = parseUnknownRecord(decoded);
+    const decodedSteps = decodedRecord?.steps;
+    if (memory.steps.size === 0 || !isUnknownArray(decodedSteps)) {
+        return { candidate: decoded, stamped: [], restored: [], repaired: [], unknown: [] };
+    }
+    const byRule = claimsByRule(memory.claims);
+    const stamped = [];
+    const restored = [];
+    const repaired = [];
+    const unknown = [];
+    const steps = decodedSteps.map((step, index) => {
+        const fields = parseUnknownRecord(step);
+        if (fields === undefined)
+            return step;
+        const { id, grounding } = fields;
+        const current = parseUnknownRecord(grounding);
+        if (current === undefined)
+            return step;
+        const label = typeof id === "string" ? id : String(index);
+        let next = current;
+        const source = typeof id === "string" ? memory.steps.get(id) : undefined;
+        if (source !== undefined && current.snapshot !== "none") {
+            if (next.snapshot !== source.grounding.snapshot) {
+                stamped.push(label);
+                next = { ...next, snapshot: source.grounding.snapshot };
+            }
+            if (next.template === undefined && source.grounding.template !== undefined && current.status !== "ungrounded") {
+                restored.push(label);
+                next = { ...next, template: source.grounding.template };
+            }
+        }
+        if (isUnknownArray(current.claims)) {
+            let changed;
+            const claims = current.claims.map((claim, position) => {
+                if (typeof claim !== "string" || memory.claims.has(claim))
+                    return claim;
+                const match = byRule.get(ruleOf(claim));
+                if (match !== undefined) {
+                    repaired.push({ step: label, from: claim, to: match });
+                    changed = true;
+                    return match;
+                }
+                unknown.push({
+                    path: `plan.steps.${index}.grounding.claims.${position}`,
+                    code: "semantic",
+                    message: `Claim ${claim} is not a claim of the knowledge_recommend answer of this run. Cite a claim id the answer returned, or remove it.`,
+                });
+                return claim;
+            });
+            if (changed)
+                next = { ...next, claims };
+        }
+        // The repaired claims are the ones compared, thus a step whose only claim was miscopied still gets the digest.
+        const vouched = Array.isArray(next.claims) && next.claims.some((claim) => typeof claim === "string" && memory.claims.has(claim));
+        if (source === undefined && vouched && memory.digest !== undefined && current.snapshot !== "none" && next.snapshot !== memory.digest) {
+            stamped.push(label);
+            next = { ...next, snapshot: memory.digest };
+        }
+        return next === current ? step : { ...fields, grounding: next };
+    });
+    return { candidate: { ...decodedRecord, steps }, stamped, restored, repaired, unknown };
+}
 /**
  * Full validation: Zod schema + semantic checks. The plan is valid only if
  * BOTH pass.
  */
 function fullyValidate(candidate, resourcePolicy) {
-    const parsed = PlannerPlanSchema.safeParse(candidate);
+    // The permissive arg schema of the planner tools accepts a string, thus the
+    // loop-boundary repair never sees a plan that a model sent as a JSON-encoded
+    // string. A small model does this on a large nested schema. Decode it here,
+    // the same as run-synthesis does, so the schema issues describe the plan
+    // inside the string and not the string.
+    const decoded = decodeObjectString(candidate);
+    const parsed = PlannerPlanSchema.safeParse(decoded);
     if (!parsed.success) {
-        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, candidate) };
+        return { valid: false, issues: zodIssuesToValidationIssues(parsed.error, decoded) };
     }
     // Semantic checks operate on the AnalysisPlan shape — PlannerPlan omits
     // maxSteps, so inject the execution-time default to satisfy the validator.
@@ -332,19 +560,18 @@ function fullyValidate(candidate, resourcePolicy) {
     return { valid: true, plan: parsed.data };
 }
 /**
- * Build the planner's inner tools for one invocation. They close over the
- * shared `holder` so the outer `execute` reads the terminal outcome after the
- * loop finishes.
+ * Build the planner's inner tools for one invocation. `memory` holds the last
+ * `knowledge_recommend` answer of the run, which the loop folds after each round.
  */
-function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger) {
+function buildInnerTools(resourcePolicy, logger, memory) {
     const submitPlanTool = defineTool({
-        id: "submit_plan",
-        description: "Submit the final plan for persistence. Re-validates the plan; on " +
-            "success returns {accepted: true, planId}, and an accepted call ends " +
-            "the planning session. On " +
+        id: SUBMIT_PLAN_TOOL_ID,
+        description: "Submit the plan. Checks the plan; on success returns {accepted: true, plan} " +
+            "with the plan as the harness saves it — stop after an accepted plan. On " +
             "rejection returns {accepted: false, issues} — fix and call again, " +
-            "or switch to report_blocker if the plan cannot be made valid. This " +
-            "arg schema is the authoritative plan contract.",
+            "or switch to report_blocker if the plan cannot be made valid. The last " +
+            "accepted plan is the plan of this session. This arg schema is the " +
+            "authoritative plan contract.",
         // Permissive on purpose: every candidate reaches `execute`, where the
         // model gets structured schema and semantic issues in one response.
         // The field-by-field contract remains visible in this tool's description
@@ -356,123 +583,51 @@ function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger
             plan: z.union([PlannerPlanSchema, z.unknown()]).describe("Candidate plan; malformed values are reported in issues."),
         }),
         describeCall: "none",
-        execute: async (input) => {
-            if (holder.outcome !== null) {
-                trace.duplicateTerminalCalls++;
-                logger.warn("submit_plan called after a terminal outcome was recorded", {
-                    recordedOutcome: holder.outcome.kind,
-                    duplicateTerminalCalls: trace.duplicateTerminalCalls,
-                });
-                return ok({
-                    accepted: false,
-                    issues: [
-                        {
-                            path: "plan",
-                            code: "semantic",
-                            message: "A terminal outcome has already been recorded; submit_plan " + "can only be called once per invocation.",
-                        },
-                    ],
-                });
-            }
-            const attempt = ++trace.submitAttempts;
-            const result = fullyValidate(input.plan, resourcePolicy);
-            if (!result.valid) {
-                trace.rejectedAttempts++;
-                const rejection = toRejectionRecord(attempt, result.issues);
-                if (trace.rejections.length < MAX_LOGGED_REJECTIONS)
-                    trace.rejections.push(rejection);
+        execute: (input) => {
+            // The host owns the grounding fields: it fills them from the last answer of the run.
+            const { candidate, stamped, restored, repaired, unknown } = restoreSkeletonGrounding(input.plan, memory);
+            if (stamped.length > 0)
+                logger.info("submit_plan stamped the snapshot digest of the answer on steps", { steps: stamped });
+            if (restored.length > 0)
+                logger.info("submit_plan restored the template of skeleton steps", { steps: restored });
+            if (repaired.length > 0)
+                logger.info("submit_plan repaired the claim ids of plan steps", { claims: repaired });
+            const result = fullyValidate(candidate, resourcePolicy);
+            // An unknown claim rejects a plan that the schema accepts, beside the
+            // schema issues when the schema rejects it, thus one attempt shows both.
+            if (!result.valid || unknown.length > 0) {
+                const issues = [...(result.valid ? [] : result.issues), ...unknown];
                 // `warn`, not `debug`: a rejection is non-terminal by design, so the model
                 // reads the issues and the invocation carries on — nothing else reports that
-                // an attempt was spent. A run that exhausts its budget on rejections ends
-                // looking identical to one that never tried, and this is the difference.
-                logger.warn("submit_plan rejected a plan", { ...rejection });
-                return ok({ accepted: false, issues: result.issues });
+                // an attempt was spent.
+                logger.warn("submit_plan rejected a plan", { issueCount: issues.length, paths: issues.slice(0, MAX_LOGGED_ISSUES).map((i) => i.path) });
+                return Promise.resolve(ok({ accepted: false, issues }));
             }
-            const persisted = await persistPlan(result.plan, persistCtx, pool, logger);
-            if (!persisted.ok) {
-                holder.outcome = { kind: "persist_error", message: persisted.message };
-                return ok({
-                    accepted: false,
-                    issues: [
-                        {
-                            path: "plan",
-                            code: "semantic",
-                            message: persisted.message,
-                            hint: "Persistence failed — do not retry submit_plan.",
-                        },
-                    ],
-                });
-            }
-            holder.outcome = {
-                kind: "plan_submitted",
-                planId: persisted.planId,
-                plan: result.plan,
-            };
-            // The attempt count is the cost of this plan, and it is only knowable here.
-            // A plan accepted on attempt 5 is a success that nearly was not one.
             logger.info("submit_plan accepted a plan", {
-                planId: persisted.planId,
-                attempt,
                 stepCount: result.plan.steps.length,
                 agents: [...new Set(result.plan.steps.map((s) => s.agent))],
             });
-            return ok({ accepted: true, planId: persisted.planId });
+            return Promise.resolve(ok({ accepted: true, plan: result.plan }));
         },
     });
     const requestClarificationTool = defineTool({
-        id: "request_clarification",
+        id: REQUEST_CLARIFICATION_TOOL_ID,
         description: "Terminal. Use when a specific fact you need is missing from the " +
             "input and cannot be inferred. The question reaches the user through " +
-            "the conversation agent. A call ends the planning session with no " +
-            "plan saved.",
+            "the conversation agent, and no plan is saved. Stop after this call.",
         inputSchema: z.object({
-            question: z.string().min(1).describe("One short question that names each missing fact, and the step that needs it."),
+            question: terminalTextSchema("One short question that names each missing fact, and the step that needs it."),
             questionContext: z.string().optional().describe("Optional context: why the plan needs the fact, and what the inputs already say about it."),
         }),
         describeCall: "none",
-        execute: async (input) => {
-            if (holder.outcome !== null) {
-                trace.duplicateTerminalCalls++;
-                logger.warn("request_clarification called after a terminal outcome was recorded", {
-                    recordedOutcome: holder.outcome.kind,
-                    duplicateTerminalCalls: trace.duplicateTerminalCalls,
-                });
-                return ok({ recorded: true });
-            }
-            holder.outcome = {
-                kind: "clarification",
-                question: input.question,
-                questionContext: input.questionContext,
-            };
-            // The question is the answer to "why did planning stop?" — and it reaches the
-            // user through the conversation agent, which may paraphrase it into something
-            // that no longer identifies the missing fact.
-            logger.info("planner requested clarification", {
-                submitAttempts: trace.submitAttempts,
-                ...modelAuthored({ clarificationQuestion: bounded(input.question, MAX_LOGGED_PROSE_CHARS) }),
-            });
-            return ok({ recorded: true });
-        },
+        execute: (input) => Promise.resolve(ok({
+            kind: "clarification",
+            question: input.question,
+            questionContext: input.questionContext,
+            message: "Clarification recorded. Stop now.",
+        })),
     });
     const reportBlockerTool = createReportBlockerToolFor({
-        record: (outcome) => {
-            if (holder.outcome !== null) {
-                trace.duplicateTerminalCalls++;
-                logger.warn("report_blocker called after a terminal outcome was recorded", {
-                    recordedOutcome: holder.outcome.kind,
-                    duplicateTerminalCalls: trace.duplicateTerminalCalls,
-                });
-                return;
-            }
-            holder.outcome = outcome;
-            // A blocker after several rejected submits is a planner giving up on a plan it
-            // could not make valid — a validation problem wearing a blocker's clothes. The
-            // attempt count is what tells those apart, and only this record carries both.
-            logger.warn("planner reported a blocker", {
-                submitAttempts: trace.submitAttempts,
-                ...modelAuthored({ blockerReason: bounded(outcome.reason, MAX_LOGGED_PROSE_CHARS) }),
-            });
-        },
         blockedWhen: "Ends plan generation with no plan saved. Use it when no valid plan can " +
             "be produced for this data and research question (out of scope, data " +
             "incompatible with every available agent, etc.) — not for a plan you " +
@@ -495,17 +650,18 @@ function inventoryContent(label, result, logger) {
         return `## ${label}\n\nInventory lookup failed: ${result.error.error}`;
     }
     const value = result.value;
-    if (typeof value === "object" && value !== null && "content" in value && typeof value.content === "string") {
-        return `## ${label}\n\n${value.content}`;
+    const content = parseUnknownRecord(value)?.["content"];
+    if (typeof content === "string") {
+        return `## ${label}\n\n${content}`;
     }
     return `## ${label}\n\n${JSON.stringify(value)}`;
 }
 // ── Transcript reading (diagnostics only) ───────────────────────────
 /**
- * The planner's own account of the run, read off the message array `runToTerminal`
+ * The planner's own account of the run, read off the message array that the run
  * returns. Nothing else can produce it: the transcript is ephemeral — a sub-agent
- * loop on `passthroughStep` persists no messages anywhere — so it is read here or
- * it is lost with the turn.
+ * loop persists no messages anywhere — so it is read here or it is lost with the
+ * turn.
  *
  * `toolCalls` in order is what shows the SHAPE of a failure at a glance:
  * `[submit_plan × 13]` is a planner thrashing on validation, `[]` is a planner
@@ -540,32 +696,34 @@ function readTranscript(messages) {
  * The loop half of the finish record: how the planner's run ended, and what it
  * did to get there.
  *
- * Built from the `runToTerminal` result that the tool previously discarded
- * entirely. Without it, `no_outcome` is a single word covering three unrelated
- * failures — a budget spent on rejected submits (`max_iterations`), a planner that
- * answered in prose (`stop`), and a reply cut off at the output-token limit
- * (`length`) — which is why three identical-looking retries taught nobody anything.
+ * Without it, `no_outcome` is a single word covering three unrelated failures — a
+ * budget spent on rejected submits (`max_iterations`), a planner that answered in
+ * prose (`stop`), and a reply cut off at the output-token limit (`length`) — which
+ * is why three identical-looking retries taught nobody anything.
  */
 function loopFields(run, kind) {
     const transcript = readTranscript(run.messages);
-    return {
+    const fields = {
         loop: {
             finishReason: run.finish.reason,
             cappedOut: run.finish.cappedOut,
-            truncationRecoveries: run.finish.truncationRecoveries,
             salvaged: run.salvage !== null,
-            ...(run.salvage ? { firstFinishReason: run.salvage.firstFinish.reason, salvageFinishReason: run.salvage.finish.reason } : {}),
+            firstFinishReason: run.salvage === null ? undefined : run.salvage.firstFinish.reason,
+            salvageFinishReason: run.salvage === null ? undefined : run.salvage.finish.reason,
             toolCalls: transcript.toolCalls,
-            ...(transcript.truncatedToolCalls ? { toolCallsTruncated: true } : {}),
+            toolCallsTruncated: transcript.truncatedToolCalls ? true : undefined,
         },
-        ...(PROSE_EXPLAINS_OUTCOME.has(kind) ? modelAuthored({ plannerFinalProse: transcript.finalProse }) : {}),
     };
+    if (PROSE_EXPLAINS_OUTCOME.has(kind))
+        Object.assign(fields, modelAuthored({ plannerFinalProse: transcript.finalProse }));
+    return fields;
 }
 /**
  * The endings whose only account is what the planner said last.
  *
- * Everywhere else something better already explains the outcome: a terminal tool
- * recorded its own argument, or a thrown cause carries the fault. Logging the
+ * Everywhere else something better already explains the outcome: the selected
+ * result carries its own argument, the blocker record gives its reason, or a
+ * thrown cause carries the fault. Logging the
  * prose there would put model output describing the user's data into a record
  * that had no use for it — including on every successful plan, where the closing
  * text is the planner narrating work that demonstrably went fine.
@@ -581,8 +739,7 @@ const PROSE_EXPLAINS_OUTCOME = new Set(["no_outcome", "loop_error", "timeout"]);
  * caller actually returned.
  */
 function shapeOutcome(args) {
-    const { holder, runError, timedOut, outerAborted } = args;
-    const outcome = holder.outcome;
+    const { outcome, runError, timedOut, outerAborted } = args;
     if (outcome?.kind === "plan_submitted") {
         return { output: { event: "plan_complete", planId: outcome.planId, plan: outcome.plan }, kind: "plan_submitted" };
     }
@@ -591,7 +748,7 @@ function shapeOutcome(args) {
             output: {
                 event: "clarification_needed",
                 question: outcome.question,
-                ...(outcome.questionContext ? { questionContext: outcome.questionContext } : {}),
+                questionContext: outcome.questionContext ? outcome.questionContext : undefined,
             },
             kind: "clarification",
         };
@@ -616,7 +773,7 @@ function shapeOutcome(args) {
         return { output: { event: "error", error: "Plan generation was cancelled." }, kind: "cancelled" };
     }
     if (runError) {
-        const msg = runError instanceof Error ? runError.message : String(runError);
+        const msg = errorMessageOf(runError) ?? textOf(runError);
         return { output: { event: "error", error: `Plan generation failed: ${msg}` }, kind: "loop_error" };
     }
     return {
@@ -657,7 +814,7 @@ const OUTCOME_LEVEL = {
  * A tool here never writes and never computes. Thus the worst outcome of a
  * needless call is latency, and the prompt is what bounds that.
  */
-function buildPlannerSearchTools(deps) {
+export function buildPlannerSearchTools(deps, hooks = {}) {
     const bioKeys = deps.bioKeys;
     const ncbi = createNcbiTools(bioKeys);
     return [
@@ -669,7 +826,7 @@ function buildPlannerSearchTools(deps) {
         // cross-field index that ranks a method paper best.
         ncbi.pubmed,
         searchArxivTool,
-        createSearchSemanticScholarTool({ ...(bioKeys.semanticScholar === undefined ? {} : { apiKey: bioKeys.semanticScholar }) }),
+        createSearchSemanticScholarTool({ apiKey: bioKeys.semanticScholar }),
         // The same approach as running code — a pipeline that someone published.
         createSearchGithubReposTool({ githubToken: bioKeys.github }),
         // The API of a staged package, so a step names a function that exists.
@@ -683,83 +840,78 @@ function buildPlannerSearchTools(deps) {
         // The planner is a conversation surface, thus the pool-scope reader binds
         // when the embedder gives one, and the answer names what the store HOLDS.
         createListAvailablePackagesTool({
-            ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
-            ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
-            ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+            farmLockFile: deps.farmLockFile,
+            imagePackagesFile: deps.imagePackagesFile,
+            readPoolInventory: deps.readPoolInventory,
+        }),
+        // The knowledge plane: one cited procedure per situation, and one check
+        // of the draft. Both attach only when the embedder binds a client.
+        ...createKnowledgeTools({
+            client: deps.knowledge,
+            farmLockFile: deps.farmLockFile,
+            imagePackagesFile: deps.imagePackagesFile,
+            refStorePath: deps.refStorePath,
+            onRecommend: hooks.onRecommend,
         }),
     ];
 }
+const generatePlanInputSchema = z.object({
+    researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
+    analystNotes: z
+        .string()
+        .optional()
+        .describe("Facts about the data that ONLY the user could have told you and the data profile cannot know — " +
+        'e.g. "samples 3 and 7 were re-sequenced", "treat batch B as the reference", ' +
+        '"the tumor/normal labels in column 4 are swapped". ' +
+        "This is NOT a place to restate the data profile: organism, omics type, experimental design, " +
+        "condition names, file names and dimensions are already loaded server-side and given to the " +
+        "planner — repeating them here only risks contradicting the record. Omit entirely unless the " +
+        "user has told you something the profile does not already hold."),
+    priorRuns: z
+        .string()
+        .optional()
+        .describe("Summary of prior run results if any exist: which steps ran, " + "what succeeded/failed, key findings. Omit if no prior runs."),
+    userConstraints: z
+        .string()
+        .optional()
+        .describe("User-specified constraints: preferred methods, steps to " + "include/exclude, resource limits, modifications to a prior plan."),
+    parentPlanId: z
+        .string()
+        .regex(PLAN_ID_RE, "parentPlanId must be a pln-<8hex> value")
+        .optional()
+        .describe("The planId of the prior plan being iterated on. Set only when " + "the user is asking for modifications to an existing plan."),
+});
 /** Build the `generate_plan` tool bound to its provider and pool. */
-export function createGeneratePlanTool(deps) {
+export function createGeneratePlanTool(deps, registerSubAgent) {
     const baseLogger = (deps.logger ?? createNoopLogger()).named("generate-plan");
-    return defineTool({
-        id: "generate_plan",
-        description: "Generate an analysis plan (DAG of steps) for this analysis's data and the user's research question. " +
-            "The dataset's own facts — domain, organism, experimental design, condition names, quality concerns, " +
-            "per-file data types and dimensions — are read server-side from the persisted data profile and handed " +
-            "to the planner directly. Do NOT summarize or re-type them into this call; you cannot restate that " +
-            "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
-            "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
-            "The planner is a multi-step sub-agent, thus a call can take many minutes. " +
-            "The result carries an `event`: `plan_complete` with {planId, plan} — the plan is saved and ready for show_plan and " +
-            "execute_analysis plan mode, and this call neither shows nor runs it; `clarification_needed` with {question, questionContext?} " +
-            "when the planner is missing a fact it cannot infer; or `error` with {error} when no plan was saved (the planner reported " +
-            "a blocker, the save failed, the call timed out or was cancelled, or parentPlanId is not a plan of this analysis).",
-        inputSchema: z.object({
-            researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
-            analystNotes: z
-                .string()
-                .optional()
-                .describe("Facts about the data that ONLY the user could have told you and the data profile cannot know — " +
-                'e.g. "samples 3 and 7 were re-sequenced", "treat batch B as the reference", ' +
-                '"the tumor/normal labels in column 4 are swapped". ' +
-                "This is NOT a place to restate the data profile: organism, omics type, experimental design, " +
-                "condition names, file names and dimensions are already loaded server-side and given to the " +
-                "planner — repeating them here only risks contradicting the record. Omit entirely unless the " +
-                "user has told you something the profile does not already hold."),
-            priorRuns: z
-                .string()
-                .optional()
-                .describe("Summary of prior run results if any exist: which steps ran, " + "what succeeded/failed, key findings. Omit if no prior runs."),
-            userConstraints: z
-                .string()
-                .optional()
-                .describe("User-specified constraints: preferred methods, steps to " + "include/exclude, resource limits, modifications to a prior plan."),
-            parentPlanId: z
-                .string()
-                .regex(/^pln-[a-f0-9]{8}$/, "parentPlanId must be a pln-<8hex> value")
-                .optional()
-                .describe("The planId of the prior plan being iterated on. Set only when " + "the user is asking for modifications to an existing plan."),
-        }),
-        describeCall: ({ researchQuestion }) => researchQuestion,
-        execute: async (input, ctx) => {
-            const analysisId = scopeResource(ctx.session.scope).resourceId;
-            // Bound per invocation: `analysisId` comes from the call-time session, not from
-            // the construction-time deps the factory closes over.
-            const logger = baseLogger.with({ analysisId });
-            const startedAt = Date.now();
-            const trace = createPlannerTrace();
-            // Every exit routes through here, so "recorded exactly once per invocation" holds
-            // by construction rather than by remembering. `elapsedMs` is what separates a
-            // planner that gave up early from one still working when the guard cut it — the
-            // fixed budget above makes the number readable without any other context.
-            //
-            // `extra` carries the loop account on the paths that reached the loop. The two
-            // parent-plan early returns never do, and a record claiming `loop.finishReason`
-            // for a run that never started would be worse than one that omits the field.
-            const finish = (shaped, extra = {}) => {
-                logger[OUTCOME_LEVEL[shaped.kind]]("plan generation finished", {
-                    outcome: shaped.kind,
-                    elapsedMs: Date.now() - startedAt,
-                    submitAttempts: trace.submitAttempts,
-                    rejectedAttempts: trace.rejectedAttempts,
-                    ...(trace.rejections.length > 0 ? { rejections: trace.rejections } : {}),
-                    ...(trace.rejectedAttempts > trace.rejections.length ? { rejectionsTruncated: true } : {}),
-                    ...(trace.duplicateTerminalCalls > 0 ? { duplicateTerminalCalls: trace.duplicateTerminalCalls } : {}),
-                    ...extra,
-                });
-                return ok(shaped.output);
-            };
+    const plan = registerSubAgent(PLANNER_AGENT_ID, async ({ payload: input, ctx, loop, durably }) => {
+        const analysisId = scopeResource(ctx.session.scope).resourceId;
+        // Bound per invocation: `analysisId` comes from the call-time session, not from
+        // the construction-time deps the factory closes over.
+        const logger = baseLogger.with({ analysisId });
+        const startedAt = Date.now();
+        let trace = { submitAttempts: 0, rejectedAttempts: 0, rejections: [] };
+        // Every exit routes through here, so "recorded exactly once per invocation" holds
+        // by construction rather than by remembering. `elapsedMs` is what separates a
+        // planner that gave up early from one still working when the guard cut it — the
+        // fixed budget above makes the number readable without any other context.
+        //
+        // `extra` carries the loop account on the paths that reached the loop. The two
+        // parent-plan early returns never do, and a record claiming `loop.finishReason`
+        // for a run that never started would be worse than one that omits the field.
+        const finish = (shaped, extra = {}) => {
+            logger[OUTCOME_LEVEL[shaped.kind]]("plan generation finished", {
+                outcome: shaped.kind,
+                elapsedMs: Date.now() - startedAt,
+                submitAttempts: trace.submitAttempts,
+                rejectedAttempts: trace.rejectedAttempts,
+                rejections: trace.rejections,
+                rejectionsTruncated: trace.rejectedAttempts > trace.rejections.length ? true : undefined,
+                ...extra,
+            });
+            return shaped.output;
+        };
+        const seed = await durably("planner.seed", async () => {
             // If iterating, load the parent plan so the planner sees what it is
             // revising. Fails fast with the sanitized message submit_plan would
             // have surfaced — saves a wasted planner run.
@@ -770,10 +922,12 @@ export function createGeneratePlanTool(deps) {
                         analysisId,
                     }));
                     if (!priorPlan) {
-                        return finish({
-                            output: { event: "error", error: "parentPlanId is not a valid plan for this analysis" },
-                            kind: "invalid_parent_plan",
-                        });
+                        return {
+                            early: {
+                                output: { event: "error", error: "parentPlanId is not a valid plan for this analysis" },
+                                kind: "invalid_parent_plan",
+                            },
+                        };
                     }
                     priorPlanBlock = formatPriorPlan(input.parentPlanId, priorPlan);
                     // `formatPriorPlan` returns null on a stored plan that no longer parses as an
@@ -785,10 +939,12 @@ export function createGeneratePlanTool(deps) {
                 }
                 catch (err) {
                     logger.error("parent plan could not be loaded", { parentPlanId: input.parentPlanId, ...logger.errorFields(err) });
-                    return finish({
-                        output: { event: "error", error: "Plan iteration failed — parent plan could not be loaded." },
-                        kind: "parent_plan_load_failed",
-                    });
+                    return {
+                        early: {
+                            output: { event: "error", error: "Plan iteration failed — parent plan could not be loaded." },
+                            kind: "parent_plan_load_failed",
+                        },
+                    };
                 }
             }
             // The dataset's facts come from the ledger, not from a string a model
@@ -803,11 +959,10 @@ export function createGeneratePlanTool(deps) {
                 // Degrading to "no profile" is correct behaviour and indistinguishable, from
                 // the outcome, from an analysis that genuinely has none — so the read failure
                 // is reported here or it is never known to have happened.
-                logger.warn("data profile read failed — planning without dataset facts", {
-                    dbErrorType: error.type,
-                    ...("op" in error ? { dbOp: error.op } : {}),
-                    ...("cause" in error ? logger.errorFields(error.cause) : {}),
-                });
+                const fields = { dbErrorType: error.type, dbOp: error.op };
+                if ("cause" in error)
+                    Object.assign(fields, logger.errorFields(error.cause));
+                logger.warn("data profile read failed — planning without dataset facts", fields);
                 return null;
             });
             const grounding = classifyGrounding(profileStatus);
@@ -817,9 +972,9 @@ export function createGeneratePlanTool(deps) {
             // the loop and put their rendered content in the planner's seed.
             const listAvailableRefs = createListAvailableRefsTool(deps.refStorePath === undefined ? {} : { refStorePath: deps.refStorePath });
             const listAvailablePackages = createListAvailablePackagesTool({
-                ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
-                ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
-                ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+                farmLockFile: deps.farmLockFile,
+                imagePackagesFile: deps.imagePackagesFile,
+                readPoolInventory: deps.readPoolInventory,
             });
             // A path-separator query matches every reference path and selects the
             // tool's recursive leaf scan, so the seed contains usable file paths,
@@ -839,102 +994,174 @@ export function createGeneratePlanTool(deps) {
                 ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
                 ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
             ].join("\n");
-            const planTimeoutMs = effectiveDeadlineMs(deps.conversation.provider, PLAN_TIMEOUT_MS);
-            // Opens the invocation. Two things are only knowable here and both are
-            // first-order suspects when a planner runs long and returns nothing: the size
-            // of the seed it was handed, and which of its blocks made it that size. The
-            // reference inventory in particular is a recursive leaf scan of whatever this
-            // install has staged — a quantity the harness does not control and no other
-            // record reports. The census is sizes only: the seed carries the user's
-            // research question and dataset facts, which belong in the model's context and
-            // not in a log file.
-            logger.info("plan generation started", {
-                model: deps.conversation.model,
-                maxIterations: PLANNER_MAX_ITERATIONS,
-                salvageIterations: DEFAULT_SALVAGE_ITERATIONS,
-                timeoutMs: planTimeoutMs,
+            return {
+                prompt,
                 grounding: grounding.kind,
-                ...(input.parentPlanId ? { parentPlanId: input.parentPlanId } : {}),
-                seedChars: {
-                    total: prompt.length,
+                chars: {
                     priorPlan: priorPlanBlock?.length ?? 0,
                     dataContext: dataContextBlock.length,
                     referenceData: refsBlock.length,
                     packages: packagesBlock.length,
-                    researchQuestion: input.researchQuestion.length,
-                    analystNotes: input.analystNotes?.length ?? 0,
-                    priorRuns: input.priorRuns?.length ?? 0,
-                    userConstraints: input.userConstraints?.length ?? 0,
                 },
-            });
-            const holder = { outcome: null };
-            const persistCtx = {
-                analysisId,
-                parentPlanId: input.parentPlanId ?? null,
             };
-            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger);
-            // Built here rather than at construction: a `describeCall` hook reads no
-            // dep, thus the tool must stay constructible from an empty bag. The tool
-            // definitions are identical across invocations, thus the request prefix
-            // that the cache keys on does not move.
-            const searchTools = buildPlannerSearchTools(deps);
-            const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
-            const planner = {
-                id: PLANNER_AGENT_ID,
-                systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
-                model: deps.conversation.model,
-                // The search tools come first, and the terminal tools come last.
-                // The order is the order of the prompt, and it is stable across
-                // every invocation, thus the cached request prefix holds.
-                tools: [...searchTools, ...readTools, ...innerTools.terminal],
-                maxIterations: PLANNER_MAX_ITERATIONS,
-            };
-            // Merge the outer abort signal with a wall-clock timeout — either
-            // cancels the planner promptly.
-            const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(planTimeoutMs)]);
-            let runError = null;
-            let run = null;
-            try {
-                run = await runToTerminal(planner, [{ role: "user", content: prompt }], forSubAgent(ctx.session, PLANNER_AGENT_ID), {
-                    provider: deps.conversation.provider,
-                    signal,
-                    emit: ctx.emit,
-                    runStep: passthroughStep,
-                    resolved: () => holder.outcome !== null,
-                    // No forced tool choice: some Claude models reject it with a
-                    // 400. The prompt names the terminal tools, and the salvage
-                    // turn below recovers a run that ends on prose.
-                    logger,
-                    usageRecorder: deps.usageRecorder,
-                    toolOutputStore: deps.toolOutputStore,
-                    // Fold the planner's calls into the turn total the root loop reports.
-                    turnUsage: ctx.turnUsage,
-                    // Keeps the usage record keys of two parallel dispatches disjoint —
-                    // same frame, same call path, same loop-local step names.
-                    invocationId: ctx.invocationId,
-                }, {
-                    tools: innerTools.terminal,
-                    nudge: "You ended without a terminal outcome. Call submit_plan with " +
-                        "your final plan now, or request_clarification / report_blocker " +
-                        "if you cannot. Do not reply with prose.",
-                });
+        });
+        if ("early" in seed)
+            return finish(seed.early);
+        const { prompt } = seed;
+        const planTimeoutMs = effectiveDeadlineMs(deps.conversation.provider, PLAN_TIMEOUT_MS);
+        // Opens the invocation. Two things are only knowable here and both are
+        // first-order suspects when a planner runs long and returns nothing: the size
+        // of the seed it was handed, and which of its blocks made it that size. The
+        // reference inventory in particular is a recursive leaf scan of whatever this
+        // install has staged — a quantity the harness does not control and no other
+        // record reports. The census is sizes only: the seed carries the user's
+        // research question and dataset facts, which belong in the model's context and
+        // not in a log file.
+        logger.info("plan generation started", {
+            model: deps.conversation.model,
+            maxIterations: PLANNER_MAX_ITERATIONS,
+            salvageRequests: DEFAULT_SALVAGE_REQUESTS,
+            timeoutMs: planTimeoutMs,
+            grounding: seed.grounding,
+            parentPlanId: input.parentPlanId,
+            seedChars: {
+                total: prompt.length,
+                ...seed.chars,
+                researchQuestion: input.researchQuestion.length,
+                analystNotes: input.analystNotes?.length ?? 0,
+                priorRuns: input.priorRuns?.length ?? 0,
+                userConstraints: input.userConstraints?.length ?? 0,
+            },
+        });
+        const persistCtx = {
+            analysisId,
+            parentPlanId: input.parentPlanId ?? null,
+            invocationId: ctx.invocationId,
+        };
+        // The last recommend answer of this invocation, thus `submit_plan`
+        // stamps the snapshot digest, restores a template the model dropped,
+        // and repairs or refuses a claim id the answer did not return. The loop
+        // folds each answer after its round, on the first run and on a replay.
+        const memory = { steps: new Map(), claims: new Set() };
+        const innerTools = buildInnerTools(deps.resourcePolicy, logger, memory);
+        // Built here rather than at construction: a `describeCall` hook reads no
+        // dep, thus the tool must stay constructible from an empty bag. The tool
+        // definitions are identical across invocations, thus the request prefix
+        // that the cache keys on does not move.
+        const searchTools = buildPlannerSearchTools(deps, {
+            onRecommend: (answer) => rememberAnswer(memory, answer),
+        });
+        const readTools = deps.toolOutputStore ? [createReadToolOutputTool(deps.toolOutputStore)] : [];
+        const planner = {
+            id: PLANNER_AGENT_ID,
+            systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
+            model: deps.conversation.model,
+            // The search tools come first, and the terminal tools come last.
+            // The order is the order of the prompt, and it is stable across
+            // every invocation, thus the cached request prefix holds.
+            tools: [...searchTools, ...readTools, ...innerTools.terminal],
+            maxIterations: PLANNER_MAX_ITERATIONS,
+        };
+        // Merge the outer abort signal with a wall-clock timeout — either
+        // cancels the planner promptly.
+        const signal = AbortSignal.any([ctx.signal, AbortSignal.timeout(planTimeoutMs)]);
+        // The guard bounds the repeated calls of one plan: the third call with
+        // an input the plan already sent, or the call past the budget of one
+        // tool, answers a refusal that says to continue. The terminal tools
+        // stay outside it, because a refused submit would strand the plan.
+        let refusals = 0;
+        let runError = null;
+        let run = null;
+        try {
+            run = await runWithSalvage(planner, [{ role: "user", content: prompt }], forSubAgent(ctx.session, PLANNER_AGENT_ID), {
+                ...loop,
+                provider: deps.conversation.provider,
+                signal,
+                policy: {
+                    guard: {
+                        tools: searchTools.map((tool) => tool.id),
+                        onRefusal: (refusal) => {
+                            refusals += 1;
+                            logger.warn("planner call refused by the guard", { ...refusal, refusals });
+                        },
+                    },
+                },
+                // A planner the guard refused too many times is looping:
+                // the early cap ends the search, and the salvage request
+                // submits the plan it has.
+                capWhen: () => refusals >= PLANNER_REFUSAL_LIMIT,
+                // No forced tool choice: some Claude models reject it with a
+                // 400. The prompt names the terminal tools, and the salvage
+                // request below recovers a run that ends on prose.
+                logger,
+                usageRecorder: deps.usageRecorder,
+                toolOutputStore: deps.toolOutputStore,
+            }, {
+                tools: innerTools.terminal.map((tool) => tool.id),
+                nudge: "You ended without a terminal outcome. Call submit_plan with " +
+                    "your final plan now, or request_clarification / report_blocker " +
+                    "if you cannot. Do not reply with prose.",
+                hasOutcome: (steps) => selectedOutcomeOf(steps) !== null,
+            });
+        }
+        catch (err) {
+            runError = err;
+        }
+        let outcome = null;
+        if (run !== null) {
+            trace = traceOf(run.steps);
+            const selected = selectedOutcomeOf(run.steps);
+            if (selected?.kind === "plan") {
+                const persisted = await durably("planner.persist", () => persistPlan(selected.plan, persistCtx, deps.pool, logger));
+                outcome = persisted.ok
+                    ? { kind: "plan_submitted", planId: persisted.planId, plan: selected.plan }
+                    : { kind: "persist_error", message: persisted.message };
             }
-            catch (err) {
-                runError = err;
+            else {
+                outcome = selected;
             }
-            const shaped = shapeOutcome({
-                holder,
-                runError,
-                timedOut: signal.aborted && !ctx.signal.aborted,
-                outerAborted: ctx.signal.aborted,
-            });
-            return finish(shaped, {
-                // A throw leaves no result to read the transcript off, so the cause takes its
-                // place — `shapeOutcome` folds it into one prose sentence for the model, and
-                // this is the only place its type and stack survive.
-                ...(run ? loopFields(run, shaped.kind) : {}),
-                ...(runError ? logger.errorFields(runError) : {}),
-            });
-        },
+            if (selected?.kind === "blocker") {
+                // A blocker after several rejected submits is a planner giving up on a plan it
+                // could not make valid — a validation problem wearing a blocker's clothes. The
+                // attempt count is what tells those apart, and only this record carries both.
+                logger.warn("planner reported a blocker", {
+                    submitAttempts: trace.submitAttempts,
+                    ...modelAuthored({ blockerReason: bounded(selected.reason, MAX_LOGGED_PROSE_CHARS) }),
+                });
+            }
+        }
+        const shaped = shapeOutcome({
+            outcome,
+            runError,
+            timedOut: signal.aborted && !ctx.signal.aborted,
+            outerAborted: ctx.signal.aborted,
+        });
+        const extra = {};
+        if (run)
+            Object.assign(extra, loopFields(run, shaped.kind));
+        // A throw leaves no result to read the transcript off, so the cause takes its
+        // place — `shapeOutcome` folds it into one prose sentence for the model, and
+        // this is the only place its type and stack survive.
+        if (runError)
+            Object.assign(extra, logger.errorFields(runError));
+        return finish(shaped, extra);
+    });
+    return defineTool({
+        id: "generate_plan",
+        description: "Generate an analysis plan (DAG of steps) for this analysis's data and the user's research question. " +
+            "The dataset's own facts — domain, organism, experimental design, condition names, quality concerns, " +
+            "per-file data types and dimensions — are read server-side from the persisted data profile and handed " +
+            "to the planner directly. Do NOT summarize or re-type them into this call; you cannot restate that " +
+            "record more faithfully than the record itself. Pass only what the profile cannot hold: the research " +
+            "question, facts the user told you (analystNotes), prior run results, and their constraints. " +
+            "The planner is a multi-step sub-agent, thus a call can take many minutes. " +
+            "The result carries an `event`: `plan_complete` with {planId, plan} — the plan is saved and ready for show_plan and " +
+            "execute_analysis plan mode, and this call neither shows nor runs it; `clarification_needed` with {question, questionContext?} " +
+            "when the planner is missing a fact it cannot infer; or `error` with {error} when no plan was saved (the planner reported " +
+            "a blocker, the save failed, the call timed out or was cancelled, or parentPlanId is not a plan of this analysis).",
+        inputSchema: generatePlanInputSchema,
+        describeCall: ({ researchQuestion }) => researchQuestion,
+        startsWorkflow: true,
+        execute: async (input, ctx) => ok(await plan(input, ctx)),
     });
 }