@inflexa-ai/harness 0.14.0 → 0.14.1

package/dist/loop/run-agent.js

@@ -60,6 +60,12 @@ export async function runAgent(agent, initial, session, opts) {
     });
     let iterations = 0;
     let truncationRecoveries = 0;
+    // Counted rather than listed: the finish record stays one bounded line for a run of
+    // any length, and "50 iterations, 49 tool calls, 47 of them errored" already separates
+    // a productive long run from a loop stuck retrying one failing call. The per-iteration
+    // `debug` records name the tools when that distinction is not enough.
+    let toolCallCount = 0;
+    let toolErrorCount = 0;
     // Resolved once, not per iteration: an identical options object across every
     // call is itself part of the cache contract — the request prefix has to be
     // byte-identical to be read back.
@@ -69,7 +75,7 @@ export async function runAgent(agent, initial, session, opts) {
     // what keeps the default level affordable for an agent that runs long; the
     // per-iteration detail lives at `debug`, where paying per iteration is the point.
     const logFinish = (level, reason, cappedOut) => {
-        log[level]("run finished", { iterations, reason, cappedOut, truncationRecoveries, usage });
+        log[level]("run finished", { iterations, reason, cappedOut, truncationRecoveries, toolCalls: toolCallCount, toolErrors: toolErrorCount, usage });
     };
     // The user said no. A subsequent model call would only let the agent argue
     // with the decision, or spend a call acknowledging it; the denial tool result
@@ -82,6 +88,29 @@ export async function runAgent(agent, initial, session, opts) {
         logFinish("warn", "denied", false);
         return { messages, finish: { reason: "denied", cappedOut: false, truncationRecoveries } };
     };
+    /**
+     * Fold one dispatch round into the run's counters and the event sink, returning the
+     * tools whose results the model will read as errors.
+     *
+     * Shared by both dispatch paths so a truncated round and a normal one cannot drift
+     * in what they count. An error tool result is otherwise invisible to every sink —
+     * it is not a thrown failure, so nothing reports it and the loop simply feeds it
+     * back — and a run that ends badly is usually a run whose tool calls were failing.
+     */
+    const settleRound = async (calls, results) => {
+        const errored = [];
+        for (let idx = 0; idx < calls.length; idx++) {
+            const tu = calls[idx];
+            const isError = isErrorOutput(results[idx]);
+            toolCallCount++;
+            if (isError) {
+                toolErrorCount++;
+                errored.push(tu.toolName);
+            }
+            await emit({ type: "tool-finished", source, toolUseId: tu.toolCallId, name: tu.toolName, isError });
+        }
+        return errored;
+    };
     const stopOnResolved = async (i) => {
         await emit({ type: "iteration", source, index: i, final: true });
         recordAgentRun({ agentId: agent.id, iterations, cappedOut: false, usage });
@@ -134,17 +163,16 @@ export async function runAgent(agent, initial, session, opts) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input });
             }
             const results = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-            for (let idx = 0; idx < earlier.length; idx++) {
-                const tu = earlier[idx];
-                await emit({
-                    type: "tool-finished",
-                    source,
-                    toolUseId: tu.toolCallId,
-                    name: tu.toolName,
-                    isError: isErrorOutput(results[idx]),
-                });
-            }
+            const errored = await settleRound(earlier, results);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
+            // The trailing call was never dispatched, but it reaches the model as an error
+            // result like any other — so it counts, or `toolErrors` reports a cleaner run
+            // than the model actually read. It gets no `tool-finished` event: no
+            // `tool-started` was emitted for it either, and the pair must stay balanced.
+            toolCallCount++;
+            toolErrorCount++;
+            errored.push(trailing.toolName);
+            log.debug("tool results returned errors", { iteration: i, tools: errored });
             messages.push({ role: "tool", content: results });
             if (hasDenial(results))
                 return stopOnDenial(i);
@@ -164,16 +192,9 @@ export async function runAgent(agent, initial, session, opts) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input });
         }
         const results = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-        for (let idx = 0; idx < toolCalls.length; idx++) {
-            const tu = toolCalls[idx];
-            await emit({
-                type: "tool-finished",
-                source,
-                toolUseId: tu.toolCallId,
-                name: tu.toolName,
-                isError: isErrorOutput(results[idx]),
-            });
-        }
+        const errored = await settleRound(toolCalls, results);
+        if (errored.length > 0)
+            log.debug("tool results returned errors", { iteration: i, tools: errored });
         messages.push({ role: "tool", content: results });
         if (hasDenial(results))
             return stopOnDenial(i);

package/dist/loop/run-to-terminal.d.ts

@@ -22,10 +22,30 @@
  */
 import type { AgentSession } from "../auth/types.js";
 import type { Tool } from "../tools/define-tool.js";
-import { type RunAgentOptions, type RunAgentResult } from "./run-agent.js";
+import { type AgentFinish, type RunAgentOptions, type RunAgentResult } from "./run-agent.js";
 import type { AgentDefinition, LoopMessage } from "./types.js";
 /** Default salvage budget: one submit plus a validation-fix retry or two. */
 export declare const DEFAULT_SALVAGE_ITERATIONS = 3;
+/**
+ * What a salvage continuation was and how it went — present only when one ran.
+ *
+ * The two finishes answer different questions and a diagnostician needs both: a
+ * first run that ended `max_iterations` spent its whole budget failing to submit,
+ * while one that ended `stop` gave up on prose after a single turn. Those call for
+ * opposite responses, and the returned `RunAgentResult` carries only the second
+ * run's finish, which is the same for either.
+ */
+export interface SalvageRecord {
+    /** How the FIRST run ended — the reason a salvage was needed at all. */
+    readonly firstFinish: AgentFinish;
+    /** How the salvage continuation itself ended. */
+    readonly finish: AgentFinish;
+}
+/** A `runToTerminal` outcome: the driving run's result, plus the salvage account. */
+export interface RunToTerminalResult extends RunAgentResult {
+    /** Null when the first run reached its terminal tool and no salvage was needed. */
+    readonly salvage: SalvageRecord | null;
+}
 /** Describes how to salvage a run that never reached its terminal tool. */
 export interface TerminalSalvage {
     /** Terminal tools offered on the salvage turn (submit / blocker / …). Must be
@@ -41,4 +61,4 @@ export interface TerminalSalvage {
  * Returns the salvage run's result when a salvage occurred (its message array
  * already includes the first run's), otherwise the first run's result.
  */
-export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunAgentResult>;
+export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunToTerminalResult>;

package/dist/loop/run-to-terminal.js

@@ -38,21 +38,30 @@ function salvageStepNames(base) {
 export async function runToTerminal(agent, initial, session, opts, salvage) {
     const first = await runAgent(agent, initial, session, opts);
     if (opts.resolved?.() || opts.signal.aborted)
-        return first;
+        return { ...first, salvage: null };
+    const salvageBudget = salvage.maxIterations ?? DEFAULT_SALVAGE_ITERATIONS;
     // Reported here rather than in `runAgent` because the loop cannot know it is being
     // salvaged: it sees an ordinary run with a small budget and a restricted tool set.
     // Only this wrapper holds the fact that a first attempt ended without its outcome.
-    (opts.logger ?? createNoopLogger())
-        .named("loop")
-        .warn("salvaging a run that never reached its terminal tool", { agentId: agent.id, callPath: session.provenance.callPath });
+    // The first run's finish rides along because it is the whole diagnosis of WHY a
+    // salvage was needed, and it is the field the second run's result overwrites.
+    (opts.logger ?? createNoopLogger()).named("loop").warn("salvaging a run that never reached its terminal tool", {
+        agentId: agent.id,
+        callPath: session.provenance.callPath,
+        firstFinishReason: first.finish.reason,
+        firstCappedOut: first.finish.cappedOut,
+        salvageTools: salvage.tools.map((t) => t.id),
+        salvageMaxIterations: salvageBudget,
+    });
     const salvageAgent = {
         ...agent,
         tools: [...salvage.tools],
-        maxIterations: salvage.maxIterations ?? DEFAULT_SALVAGE_ITERATIONS,
+        maxIterations: salvageBudget,
     };
     const salvageOpts = {
         ...opts,
         formatStepName: salvageStepNames(opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER),
     };
-    return runAgent(salvageAgent, [...first.messages, { role: "user", content: salvage.nudge }], session, salvageOpts);
+    const salvaged = await runAgent(salvageAgent, [...first.messages, { role: "user", content: salvage.nudge }], session, salvageOpts);
+    return { ...salvaged, salvage: { firstFinish: first.finish, finish: salvaged.finish } };
 }

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

@@ -27,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";
@@ -55,6 +55,70 @@ const PLANNER_AGENT_ID = "planner";
 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,7 +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, logger) {
+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 " +
@@ -271,6 +346,11 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy, logger) {
         }),
         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: [
@@ -282,12 +362,21 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy, logger) {
                     ],
                 });
             }
+            const attempt = ++trace.submitAttempts;
             const result = fullyValidate(input.plan, resourcePolicy);
             if (!result.valid) {
-                logger.debug("submit_plan rejected a plan", { issueCount: result.issues.length, issues: result.issues });
+                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({
@@ -307,6 +396,14 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy, logger) {
                 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 });
         },
     });
@@ -320,20 +417,47 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy, logger) {
             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 " +
@@ -343,15 +467,96 @@ function buildInnerTools(holder, persistCtx, pool, resourcePolicy, logger) {
     const terminal = [submitPlanTool, requestClarificationTool, reportBlockerTool];
     return { terminal };
 }
-function inventoryContent(label, result) {
-    if (result.isErr())
+/**
+ * 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, alongside the
@@ -471,12 +676,26 @@ export function createGeneratePlanTool(deps) {
             // 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.
-            const finish = (shaped) => {
-                logger[OUTCOME_LEVEL[shaped.kind]]("plan generation finished", { outcome: shaped.kind, elapsedMs: Date.now() - startedAt });
+            //
+            // `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
@@ -495,8 +714,15 @@ export function createGeneratePlanTool(deps) {
                         });
                     }
                     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 {
+                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",
@@ -511,8 +737,19 @@ 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.
@@ -522,7 +759,9 @@ export function createGeneratePlanTool(deps) {
             // 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 groundingBlock = [inventoryContent("Available Reference Data", refsResult), inventoryContent("Available Packages", packagesResult)].join("\n\n");
+            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, ""] : []),
@@ -534,12 +773,39 @@ export function createGeneratePlanTool(deps) {
                 ...(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, logger);
+            const innerTools = buildInnerTools(holder, trace, persistCtx, deps.pool, deps.resourcePolicy, logger);
             const planner = {
                 id: PLANNER_AGENT_ID,
                 systemPrompt: composeSystemPrompt(plannerInstructions(deps.resourcePolicy)),
@@ -551,8 +817,9 @@ export function createGeneratePlanTool(deps) {
             // 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), {
+                run = await runToTerminal(planner, [{ role: "user", content: prompt }], forSubAgent(ctx.session, PLANNER_AGENT_ID), {
                     provider: deps.conversation.provider,
                     signal,
                     emit: ctx.emit,
@@ -573,12 +840,19 @@ export function createGeneratePlanTool(deps) {
             catch (err) {
                 runError = err;
             }
-            return finish(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) : {}),
+            });
         },
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.14.0",
+    "version": "0.14.1",
     "description": "Host-agnostic bioinformatics agent harness \u2014 hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",