@inflexa-ai/harness 0.13.0 → 0.14.1

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

@@ -11,11 +11,10 @@
  * database already holds, and it would lose fidelity at every hop.
  *
  * The tool drives an internal "planner" agent that communicates outcomes
- * EXCLUSIVELY via four terminal tool calls:
+ * EXCLUSIVELY via three terminal tool calls:
  *
- *   - validate_plan(plan)       → non-terminal dry-run: an any-shape candidate
- *                                 in, {valid, issues} out (schema + semantic)
- *   - submit_plan(plan)         → terminal success: re-validates + persists
+ *   - 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
  *
@@ -28,7 +27,7 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { formatAgentCatalog } from "../../agents/sandbox-catalog.js";
 import { composeSystemPrompt } from "../../agents/system-prompt.js";
-import { runToTerminal } from "../../loop/run-to-terminal.js";
+import { DEFAULT_SALVAGE_ITERATIONS, runToTerminal } from "../../loop/run-to-terminal.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { forSubAgent, scopeResource } from "../../auth/types.js";
 import { defineTool } from "../define-tool.js";
@@ -42,6 +41,7 @@ import { plannerPrompt } from "../../prompts/planner.js";
 import { hydratePlanSteps, PlannerPlanSchema } from "../../schemas/plan-schemas.js";
 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";
@@ -49,12 +49,76 @@ import { insertPlan, loadDataProfileStatus, loadPlan } from "../../state/index.j
 /** Sub-agent identity for the planner — provenance only. */
 const PLANNER_AGENT_ID = "planner";
 /**
- * Budget for the planner's internal loop: 1 draft + ~3 validate/fix
- * cycles + 1 submit + headroom.
+ * Budget for the planner's internal loop: one draft/submit attempt plus
+ * correction retries and headroom.
  */
 const PLANNER_MAX_ITERATIONS = 13;
 /** Wall-clock guard for a single plan-generation invocation. */
 const PLAN_TIMEOUT_MS = 600_000;
+// ── 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
+// 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
+// planner is behaving at its worst, which is exactly when the record gets read.
+/** Issues kept per rejection record. A plan bounces on a handful of distinct faults; the tail repeats. */
+const MAX_LOGGED_ISSUES = 8;
+/** Per-issue message budget — enough to identify the fault, not to reproduce the plan. */
+const MAX_LOGGED_ISSUE_CHARS = 240;
+/** Rejections kept on the finish record. Enough to show whether the planner converged or thrashed. */
+const MAX_LOGGED_REJECTIONS = 6;
+/** Excerpt of the planner's last words — the one artifact that explains a run ending on prose. */
+const MAX_LOGGED_PROSE_CHARS = 800;
+/** Tool-call trace length. The planner's whole budget is ~16 turns, so this rarely truncates. */
+const MAX_LOGGED_TOOL_CALLS = 48;
+/** Trim to `max`, marking the cut so a truncated value never reads as a complete one. */
+function bounded(value, max) {
+    return value.length <= max ? value : `${value.slice(0, max)}…[+${value.length - max} chars]`;
+}
+/**
+ * Record key under which free-form MODEL-authored text rides — never a structural
+ * field, only prose a language model wrote.
+ *
+ * The segregation exists because these two things need different handling and are
+ * otherwise indistinguishable in a flat record. A planner's own words routinely
+ * quote the analysis: "atopic dermatitis skin biopsies; sample S7 is a QC outlier"
+ * is a real example. That is the user's data. It belongs in a local diagnostic
+ * file, where the user already holds it — and an embedder shipping records off the
+ * machine needs one rule to keep it there, not a list of field names that goes
+ * stale the moment a new field is added.
+ *
+ * The harness cannot enforce that rule: it does not own the sink. It owns the
+ * declaration, so a host has something to act on. The cli drops this key at its
+ * OTLP export boundary (`cli/src/lib/otel.ts`) while keeping it in the log file.
+ *
+ * Redaction at the logger root was the alternative and is wrong here: it applies
+ * to every stream, so it would blank the field in the local file too — deleting
+ * the one artifact that explains a planner which stopped on prose.
+ */
+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);
+    return present.length === 0 ? {} : { [MODEL_AUTHORED_KEY]: Object.fromEntries(present) };
+}
+function toRejectionRecord(attempt, issues) {
+    const kept = issues.slice(0, MAX_LOGGED_ISSUES);
+    return {
+        attempt,
+        issueCount: issues.length,
+        codes: {
+            schema: issues.filter((i) => i.code === "schema").length,
+            semantic: issues.filter((i) => i.code === "semantic").length,
+        },
+        paths: kept.map((i) => i.path),
+        messages: kept.map((i) => bounded(i.message, MAX_LOGGED_ISSUE_CHARS)),
+    };
+}
+function createPlannerTrace() {
+    return { submitAttempts: 0, rejectedAttempts: 0, rejections: [], duplicateTerminalCalls: 0 };
+}
 // ── Prompt / catalog ────────────────────────────────────────────────
 /** The planner system prompt is deterministic per policy — build it once per
  *  factory (the policy is a construction-time dep, fixed for the process). */
@@ -184,8 +248,13 @@ function renderDataContext(grounding) {
 /**
  * Persist a validated plan. Returns the planId, or an outcome-ready error
  * with a sanitized message — DB-shape errors never leak to the planner.
+ *
+ * The sanitization is for the model, not for the operator: "plan could not be
+ * saved, please try again" is all the planner may see, and it is useless to
+ * whoever has to fix the cause. The record here is the only place the real
+ * failure survives, so it is written before the message is flattened.
  */
-async function persistPlan(plan, ctx, pool) {
+async function persistPlan(plan, ctx, pool, logger) {
     try {
         const planId = unwrapOrThrow(await insertPlan(pool, {
             analysisId: ctx.analysisId,
@@ -197,6 +266,12 @@ async function persistPlan(plan, ctx, pool) {
     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);
+        logger.error("plan persistence failed", {
+            parentPlanId: ctx.parentPlanId,
+            stepCount: plan.steps.length,
+            classified: isParentValidation ? "invalid_parent_plan" : "write_failed",
+            ...logger.errorFields(err),
+        });
         return {
             ok: false,
             message: isParentValidation ? "parentPlanId is not a valid plan for this analysis" : "plan could not be saved, please try again",
@@ -251,33 +326,7 @@ function fullyValidate(candidate, resourcePolicy) {
  * shared `holder` so the outer `execute` reads the terminal outcome after the
  * loop finishes.
  */
-function buildInnerTools(holder, persistCtx, pool, resourcePolicy, 
-// The two environment stores travel together as one bag rather than as a pair
-// of adjacent optional strings, which would be silently swappable at the call site.
-stores) {
-    const validatePlanTool = defineTool({
-        id: "validate_plan",
-        description: "Dry-run a candidate plan and get back everything that is wrong with it. " +
-            "Takes the plan in ANY shape: a malformed, partial, or wrong-typed " +
-            "candidate is REPORTED, not rejected. Returns {valid, issues[]} covering " +
-            "both schema problems (missing / wrong-typed fields) and the semantic " +
-            "checks a schema cannot express (unknown agent IDs, DAG cycles, dangling " +
-            "depends_on references, duplicate step IDs, resource ceilings). The " +
-            "authoritative field-by-field plan schema is the arg schema of " +
-            "submit_plan — this tool deliberately does not restate it. Non-terminal: " +
-            "call as often as needed to iterate toward a clean plan, then submit_plan.",
-        // Deliberately permissive: a structurally-invalid candidate must reach
-        // `execute` so the model gets a structured {valid:false, issues} result —
-        // including semantic issues — instead of a bare Zod rejection at the loop's
-        // input boundary. `execute` re-parses against PlannerPlanSchema itself.
-        inputSchema: z.object({
-            plan: z.unknown().describe("The candidate plan, in any shape. Field-by-field schema: see submit_plan."),
-        }),
-        execute: async (input) => {
-            const result = fullyValidate(input.plan, resourcePolicy);
-            return ok(result.valid ? { valid: true, issues: [] } : { valid: false, issues: result.issues });
-        },
-    });
+function buildInnerTools(holder, trace, persistCtx, pool, resourcePolicy, logger) {
     const submitPlanTool = defineTool({
         id: "submit_plan",
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
@@ -285,11 +334,23 @@ stores) {
             "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.",
-        // Strict: a malformed plan must not reach submission. `execute` still
-        // re-validates (schema + semantic) — it does not lean on this boundary.
-        inputSchema: z.object({ plan: PlannerPlanSchema }),
+        // 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
+        // and the validation below is authoritative.
+        inputSchema: z.object({
+            // Keep the authoritative shape visible to the model while the
+            // permissive branch lets malformed candidates reach execute for
+            // structured issue reporting.
+            plan: z.union([PlannerPlanSchema, z.unknown()]).describe("Candidate plan; malformed values are reported in issues."),
+        }),
         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: [
@@ -301,11 +362,21 @@ stores) {
                     ],
                 });
             }
+            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);
+                // `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 });
             }
-            const persisted = await persistPlan(result.plan, persistCtx, pool);
+            const persisted = await persistPlan(result.plan, persistCtx, pool, logger);
             if (!persisted.ok) {
                 holder.outcome = { kind: "persist_error", message: persisted.message };
                 return ok({
@@ -325,6 +396,14 @@ stores) {
                 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 });
         },
     });
@@ -338,80 +417,223 @@ stores) {
             questionContext: z.string().optional(),
         }),
         execute: async (input) => {
-            if (holder.outcome === null) {
-                holder.outcome = {
-                    kind: "clarification",
-                    question: input.question,
-                    questionContext: input.questionContext,
-                };
+            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 });
         },
     });
     const reportBlockerTool = createReportBlockerToolFor({
         record: (outcome) => {
-            if (holder.outcome === null)
-                holder.outcome = 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 " +
             "could fix and submit.",
     });
-    // Environment discovery is non-terminal and read-only: it lets the planner check what
-    // reference data this environment holds, and what a step will actually be able to
-    // import, before committing a step to needing either. Both read host-side, so no
-    // sandbox exists or is needed at plan time — which is the whole point, since a plan
-    // that assumes an absent package fails only once the run reaches that step.
-    const listAvailableRefs = createListAvailableRefsTool(stores.refStorePath === undefined ? {} : { refStorePath: stores.refStorePath });
-    const listAvailablePackages = createListAvailablePackagesTool(stores.packagesFile === undefined ? {} : { packagesFile: stores.packagesFile });
     const terminal = [submitPlanTool, requestClarificationTool, reportBlockerTool];
-    return { all: [validatePlanTool, listAvailableRefs, listAvailablePackages, ...terminal], terminal };
+    return { terminal };
 }
+/**
+ * Render one environment inventory into the seed, reporting a lookup that failed.
+ *
+ * A failed lookup is written INTO the prompt as prose the planner then plans
+ * around — a silent degradation of its grounding that no caller is told about and
+ * no outcome distinguishes. The record is what makes "the planner produced a plan
+ * naming packages this install does not have" traceable to its cause.
+ */
+function inventoryContent(label, result, logger) {
+    if (result.isErr()) {
+        logger.warn("planner grounding inventory lookup failed", { inventory: label, error: result.error.error });
+        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}`;
+    }
+    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`
+ * 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.
+ *
+ * `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
+ * that never called anything, and a trailing `report_blocker` on a run that ended
+ * with no outcome means the terminal call was cut off before it executed.
+ */
+function readTranscript(messages) {
+    const toolCalls = [];
+    let finalProse = "";
+    for (const message of messages) {
+        if (message.role !== "assistant" || typeof message.content === "string") {
+            if (message.role === "assistant" && typeof message.content === "string" && message.content.length > 0)
+                finalProse = message.content;
+            continue;
+        }
+        for (const part of message.content) {
+            if (part.type === "tool-call")
+                toolCalls.push(part.toolName);
+            // Last one wins: the closing text of the run is what explains a run that
+            // stopped talking instead of calling its terminal tool.
+            else if (part.type === "text" && part.text.trim().length > 0)
+                finalProse = part.text;
+        }
+    }
+    return {
+        toolCalls: toolCalls.slice(0, MAX_LOGGED_TOOL_CALLS),
+        truncatedToolCalls: toolCalls.length > MAX_LOGGED_TOOL_CALLS,
+        finalProse: bounded(finalProse.trim(), MAX_LOGGED_PROSE_CHARS),
+    };
+}
+/**
+ * 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.
+ */
+function loopFields(run, kind) {
+    const transcript = readTranscript(run.messages);
+    return {
+        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 } : {}),
+            toolCalls: transcript.toolCalls,
+            ...(transcript.truncatedToolCalls ? { toolCallsTruncated: true } : {}),
+        },
+        ...(PROSE_EXPLAINS_OUTCOME.has(kind) ? modelAuthored({ plannerFinalProse: transcript.finalProse }) : {}),
+    };
+}
+/**
+ * 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
+ * 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.
+ */
+const PROSE_EXPLAINS_OUTCOME = new Set(["no_outcome", "loop_error", "timeout"]);
 /**
  * Translate the captured `PlannerOutcome` (plus any loop error) into the
- * `PlanningAgentOutput` contract the conversation agent consumes.
+ * `PlanningAgentOutput` contract the conversation agent consumes, alongside the
+ * kind the diagnostic record carries.
+ *
+ * Both come out of one branch deliberately: deriving the kind separately would
+ * be a second copy of this precedence order, free to drift from the answer the
+ * caller actually returned.
  */
 function shapeOutcome(args) {
     const { holder, runError, timedOut, outerAborted } = args;
     const outcome = holder.outcome;
     if (outcome?.kind === "plan_submitted") {
-        return { event: "plan_complete", planId: outcome.planId, plan: outcome.plan };
+        return { output: { event: "plan_complete", planId: outcome.planId, plan: outcome.plan }, kind: "plan_submitted" };
     }
     if (outcome?.kind === "clarification") {
         return {
-            event: "clarification_needed",
-            question: outcome.question,
-            ...(outcome.questionContext ? { questionContext: outcome.questionContext } : {}),
+            output: {
+                event: "clarification_needed",
+                question: outcome.question,
+                ...(outcome.questionContext ? { questionContext: outcome.questionContext } : {}),
+            },
+            kind: "clarification",
         };
     }
     if (outcome?.kind === "blocker") {
-        return { event: "error", error: outcome.reason };
+        return { output: { event: "error", error: outcome.reason }, kind: "blocker" };
     }
     if (outcome?.kind === "persist_error") {
-        return { event: "error", error: `Failed to save plan: ${outcome.message}` };
+        return { output: { event: "error", error: `Failed to save plan: ${outcome.message}` }, kind: "persist_error" };
     }
     // No terminal outcome — something went wrong in the loop.
     if (timedOut) {
         return {
-            event: "error",
-            error: "Plan generation timed out — the model may be overloaded.",
+            output: {
+                event: "error",
+                error: "Plan generation timed out — the model may be overloaded.",
+            },
+            kind: "timeout",
         };
     }
     if (outerAborted) {
-        return { event: "error", error: "Plan generation was cancelled." };
+        return { output: { event: "error", error: "Plan generation was cancelled." }, kind: "cancelled" };
     }
     if (runError) {
         const msg = runError instanceof Error ? runError.message : String(runError);
-        return { event: "error", error: `Plan generation failed: ${msg}` };
+        return { output: { event: "error", error: `Plan generation failed: ${msg}` }, kind: "loop_error" };
     }
     return {
-        event: "error",
-        error: "Plan generation completed without a terminal outcome — the planner " + "did not call submit_plan, request_clarification, or report_blocker.",
+        output: {
+            event: "error",
+            error: "Plan generation completed without a terminal outcome — the planner " + "did not call submit_plan, request_clarification, or report_blocker.",
+        },
+        kind: "no_outcome",
     };
 }
+/**
+ * Severity follows the ending, not the return type — which is uniformly `ok(...)`,
+ * so it distinguishes nothing. A submitted plan and a clarification request are
+ * both this tool working as designed; a blocker is a real answer that cost the
+ * user their plan; the rest are failures.
+ */
+const OUTCOME_LEVEL = {
+    plan_submitted: "info",
+    clarification: "info",
+    blocker: "warn",
+    persist_error: "error",
+    timeout: "error",
+    cancelled: "error",
+    loop_error: "error",
+    no_outcome: "error",
+    invalid_parent_plan: "warn",
+    parent_plan_load_failed: "error",
+};
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export function createGeneratePlanTool(deps) {
+    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. " +
@@ -450,6 +672,32 @@ export function createGeneratePlanTool(deps) {
         }),
         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);
+            };
             // 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.
@@ -460,17 +708,24 @@ export function createGeneratePlanTool(deps) {
                         analysisId,
                     }));
                     if (!priorPlan) {
-                        return ok({
-                            event: "error",
-                            error: "parentPlanId is not a valid plan for this analysis",
+                        return finish({
+                            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
+                    // `AnalysisPlan`. Iteration then silently becomes generation-from-scratch, and
+                    // the user gets a plan that ignored everything they asked to keep.
+                    if (priorPlanBlock === null) {
+                        logger.warn("prior plan did not parse — iterating without it", { parentPlanId: input.parentPlanId });
+                    }
                 }
-                catch {
-                    return ok({
-                        event: "error",
-                        error: "Plan iteration failed — parent plan could not be loaded.",
+                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",
                     });
                 }
             }
@@ -482,42 +737,100 @@ export function createGeneratePlanTool(deps) {
             // without dataset facts is a real, supported state (see `renderDataContext`),
             // so a ledger read that fails must cost the planner its grounding — never
             // the user their plan.
-            const profileStatus = await loadDataProfileStatus(deps.pool, analysisId).unwrapOr(null);
-            const dataContextBlock = renderDataContext(classifyGrounding(profileStatus));
+            const profileStatus = await loadDataProfileStatus(deps.pool, analysisId).match((status) => status, (error) => {
+                // 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) : {}),
+                });
+                return null;
+            });
+            const grounding = classifyGrounding(profileStatus);
+            const dataContextBlock = renderDataContext(grounding);
+            // Reference data and package availability are mandatory grounding,
+            // not optional planner lookups. Read both inventories host-side before
+            // 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.packagesFile === undefined ? {} : { packagesFile: deps.packagesFile });
+            // A path-separator query matches every reference path and selects the
+            // tool's recursive leaf scan, so the seed contains usable file paths,
+            // not only top-level directory summaries.
+            const [refsResult, packagesResult] = await Promise.all([listAvailableRefs.execute({ query: "/" }, ctx), listAvailablePackages.execute({}, ctx)]);
+            const refsBlock = inventoryContent("Available Reference Data", refsResult, logger);
+            const packagesBlock = inventoryContent("Available Packages", packagesResult, logger);
+            const groundingBlock = [refsBlock, packagesBlock].join("\n\n");
             const prompt = [
                 ...(priorPlanBlock ? [priorPlanBlock, ""] : []),
                 ...(dataContextBlock ? [dataContextBlock, ""] : []),
+                groundingBlock,
+                "",
                 "## Research Question",
                 input.researchQuestion,
                 ...(input.analystNotes ? ["", "## Analyst Notes (from the user — facts about the data the profile does not record)", input.analystNotes] : []),
                 ...(input.priorRuns ? ["", "## Prior Run Results", input.priorRuns] : []),
                 ...(input.userConstraints ? ["", "## User Constraints", input.userConstraints] : []),
             ].join("\n");
+            // 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: PLAN_TIMEOUT_MS,
+                grounding: grounding.kind,
+                ...(input.parentPlanId ? { parentPlanId: input.parentPlanId } : {}),
+                seedChars: {
+                    total: prompt.length,
+                    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, persistCtx, deps.pool, deps.resourcePolicy, deps);
+            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger);
             const planner = {
                 id: PLANNER_AGENT_ID,
                 systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
-                model: deps.model,
-                tools: innerTools.all,
+                model: deps.conversation.model,
+                tools: 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(PLAN_TIMEOUT_MS)]);
             let runError = null;
+            let run = null;
             try {
-                await runToTerminal(planner, [{ role: "user", content: prompt }], forSubAgent(ctx.session, PLANNER_AGENT_ID), {
-                    provider: deps.provider,
+                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,
+                    // Planner prose is unusable: every meaningful outcome is
+                    // a tool call, and the terminal predicate stops the loop
+                    // as soon as one is recorded.
+                    toolChoice: "required",
+                    logger,
+                }, {
                     tools: innerTools.terminal,
                     nudge: "You ended without a terminal outcome. Call submit_plan with " +
                         "your final plan now, or request_clarification / report_blocker " +
@@ -527,12 +840,19 @@ export function createGeneratePlanTool(deps) {
             catch (err) {
                 runError = err;
             }
-            return ok(shapeOutcome({
+            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) : {}),
+            });
         },
     });
 }