@inflexa-ai/harness 0.12.0 → 0.14.0

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
  *
@@ -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,8 +49,8 @@ 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. */
@@ -251,33 +251,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, persistCtx, pool, resourcePolicy, logger) {
     const submitPlanTool = defineTool({
         id: "submit_plan",
         description: "Submit the final plan for persistence. Re-validates the plan; on " +
@@ -285,9 +259,16 @@ 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) {
                 return ok({
@@ -303,6 +284,7 @@ stores) {
             }
             const result = fullyValidate(input.plan, resourcePolicy);
             if (!result.valid) {
+                logger.debug("submit_plan rejected a plan", { issueCount: result.issues.length, issues: result.issues });
                 return ok({ accepted: false, issues: result.issues });
             }
             const persisted = await persistPlan(result.plan, persistCtx, pool);
@@ -358,60 +340,95 @@ stores) {
             "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 };
+}
+function inventoryContent(label, result) {
+    if (result.isErr())
+        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)}`;
 }
 /**
  * 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. " +
@@ -420,7 +437,7 @@ export function createGeneratePlanTool(deps) {
             "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. " +
-            "Returns a structured plan ready for show_plan and execute_plan, or a clarification question if " +
+            "Returns a structured plan ready for show_plan and execute_analysis plan mode, or a clarification question if " +
             "the planner is missing something it cannot infer.",
         inputSchema: z.object({
             researchQuestion: z.string().describe("What the user wants to analyze — their goal and specific questions."),
@@ -450,6 +467,18 @@ 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();
+            // 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 });
+                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 +489,17 @@ 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);
                 }
                 catch {
-                    return ok({
-                        event: "error",
-                        error: "Plan iteration failed — parent plan could not be loaded.",
+                    return finish({
+                        output: { event: "error", error: "Plan iteration failed — parent plan could not be loaded." },
+                        kind: "parent_plan_load_failed",
                     });
                 }
             }
@@ -484,9 +513,21 @@ export function createGeneratePlanTool(deps) {
             // the user their plan.
             const profileStatus = await loadDataProfileStatus(deps.pool, analysisId).unwrapOr(null);
             const dataContextBlock = renderDataContext(classifyGrounding(profileStatus));
+            // 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 groundingBlock = [inventoryContent("Available Reference Data", refsResult), inventoryContent("Available Packages", packagesResult)].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] : []),
@@ -498,12 +539,12 @@ export function createGeneratePlanTool(deps) {
                 analysisId,
                 parentPlanId: input.parentPlanId ?? null,
             };
-            const innerTools = buildInnerTools(holder, persistCtx, deps.pool, deps.resourcePolicy, deps);
+            const innerTools = buildInnerTools(holder, 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
@@ -512,12 +553,17 @@ export function createGeneratePlanTool(deps) {
             let runError = null;
             try {
                 await runToTerminal(planner, [{ role: "user", content: prompt }], forSubAgent(ctx.session, PLANNER_AGENT_ID), {
-                    provider: deps.provider,
+                    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,7 +573,7 @@ export function createGeneratePlanTool(deps) {
             catch (err) {
                 runError = err;
             }
-            return ok(shapeOutcome({
+            return finish(shapeOutcome({
                 holder,
                 runError,
                 timedOut: signal.aborted && !ctx.signal.aborted,

package/dist/tools/research/inspect-data-profile.d.ts

@@ -12,11 +12,9 @@
  * and it is why the record is served in full rather than summarized: an agent that
  * cannot pull a fact here has no fallback but to re-derive it from the raw bytes.
  *
- * Bounded by construction. `inspect_run` is the cautionary counter-example — it caps
- * its query at 50 rows with no `limit` parameter and no signal to the caller, so a
- * 51st run is simply invisible. Here the per-file scope is explicitly paged and always
- * reports `total` and `hasMore`: an elided tail is a fact the model can see and act on,
- * never a silent truncation.
+ * Bounded by construction. Like `inspect_run`, the per-file scope is explicitly
+ * paged and always reports `total` and `hasMore`: an elided tail is a fact the
+ * model can see and act on, never a silent truncation.
  *
  * Lifecycle states are data variants, not errors (the `defineTool` contract): a missing,
  * in-flight, failed, or stale profile is an ordinary, expected outcome the model must be
@@ -61,7 +59,17 @@ interface FilesOutput extends ProfileEnvelope {
     readonly hasMore: boolean;
     readonly files: DataProfileFile[];
 }
-/** No profile to serve — the honest lifecycle states, in the ok channel. */
+/**
+ * No profile to serve — the honest lifecycle states, in the ok channel.
+ *
+ * Deliberately carries no staleness verdict. None of this variant's three
+ * producers retains a comparand: an analysis that was never profiled and one
+ * with no input files never had one, and `clearDataProfile` nulls
+ * `seed_input_file_ids` along with every other profile column, so a cleared row
+ * keeps no record of what it once covered. Such a field could only ever be
+ * constant here, and a constant field carries no information while implying
+ * that it does. `FailedOutput` omits one for the same reason — see its note.
+ */
 interface AbsentOutput {
     readonly state: "absent";
     readonly message: string;
@@ -71,9 +79,26 @@ interface PendingOutput {
     readonly status: "pending" | "running";
     readonly message: string;
 }
+/**
+ * A recorded failure with no profile to fall back on.
+ *
+ * Carries no staleness verdict, deliberately. Whether the failed attempt covered
+ * the files the analysis holds NOW is not derivable here: this tool reads one
+ * `cortex_analysis_state` row, the current input set is the embedder's knowledge,
+ * and `seed_input_file_ids` is the most recently seeded set rather than a
+ * per-attempt snapshot (`upsertAnalysis` overwrites it). A field reporting that
+ * verdict could only ever hold one value, which carries no information while
+ * implying that it does — and the tool description, being the whole of what an
+ * agent knows about this tool, must not advertise a distinction it cannot make.
+ *
+ * `failedAt` is reported instead: a fact the row actually holds, and one an agent
+ * that knows when the input set last changed can act on.
+ */
 interface FailedOutput {
     readonly state: "failed";
     readonly error: string | null;
+    /** When the failure was recorded; `null` when the row holds no time. */
+    readonly failedAt: string | null;
     readonly message: string;
 }
 export type InspectDataProfileOutput = OverviewOutput | FilesOutput | AbsentOutput | PendingOutput | FailedOutput;

package/dist/tools/research/inspect-data-profile.js

@@ -12,11 +12,9 @@
  * and it is why the record is served in full rather than summarized: an agent that
  * cannot pull a fact here has no fallback but to re-derive it from the raw bytes.
  *
- * Bounded by construction. `inspect_run` is the cautionary counter-example — it caps
- * its query at 50 rows with no `limit` parameter and no signal to the caller, so a
- * 51st run is simply invisible. Here the per-file scope is explicitly paged and always
- * reports `total` and `hasMore`: an elided tail is a fact the model can see and act on,
- * never a silent truncation.
+ * Bounded by construction. Like `inspect_run`, the per-file scope is explicitly
+ * paged and always reports `total` and `hasMore`: an elided tail is a fact the
+ * model can see and act on, never a silent truncation.
  *
  * Lifecycle states are data variants, not errors (the `defineTool` contract): a missing,
  * in-flight, failed, or stale profile is an ordinary, expected outcome the model must be
@@ -57,6 +55,15 @@ function stalenessReasons(status, result) {
     }
     return reasons;
 }
+/**
+ * The qualification the `failed` message must carry. A bare `failed: <error>`
+ * reads as a verdict on whatever files the agent is currently holding, and
+ * `message` is what an agent quotes back to the user — so the limit of what this
+ * row can establish belongs in the prose channel, not only in the field set.
+ */
+const FAILURE_SCOPE_NOTE = "This records an earlier attempt; this row cannot establish whether it covered the input files the analysis " +
+    "holds now, so do not read it as a verdict on the current data. Compare failedAt against when the input set " +
+    "last changed, and re-profile if they have moved apart.";
 export function createInspectDataProfileTool(pool) {
     return defineTool({
         id: "inspect_data_profile",
@@ -72,7 +79,11 @@ export function createInspectDataProfileTool(pool) {
             "always with the true total and hasMore, so you can see exactly what you have not read yet. " +
             "The state field says what you got: 'ready'; 'stale' (a profile is returned but may not describe the current " +
             "inputs — staleReason says why); 'pending' (profiling is still running); 'failed'; or 'absent' (never profiled, " +
-            "or the analysis has no input files).",
+            "or the analysis has no input files). " +
+            "A 'failed' state reports a PAST attempt, with failedAt naming when it was recorded — it is not a verdict on the " +
+            "input files you are holding now, and this tool cannot tell you whether that attempt covered them. Compare failedAt " +
+            "against when the input set last changed before you conclude anything: if the data moved since, say the profile " +
+            "needs re-running rather than diagnosing the data itself.",
         inputSchema: z.object({
             scope: z
                 .enum(["overview", "files"])
@@ -101,10 +112,15 @@ export function createInspectDataProfileTool(pool) {
             const result = status.result;
             if (!result) {
                 if (status.status === "failed") {
+                    // A failure that DID leave a prior profile on the row never reaches
+                    // here — it is served as `stale`, where `stalenessReasons` names the
+                    // failed re-profile and compares the input sets through the single
+                    // shared predicate. This branch is the case with nothing to compare.
                     return ok({
                         state: "failed",
                         error: status.error,
-                        message: `Data profiling failed and no earlier profile exists: ${status.error ?? "no reason recorded"}.`,
+                        failedAt: status.completedAt,
+                        message: `Data profiling failed and no earlier profile exists: ${status.error ?? "no reason recorded"}. ${FAILURE_SCOPE_NOTE}`,
                     });
                 }
                 if (status.status === "completed") {

package/dist/tools/research/inspect-run.d.ts

@@ -1,16 +1,9 @@
 /**
  * inspectRun — inspect workflow runs for the current analysis.
  *
- * Dependency-bearing: the database `Pool` is captured by the factory
- * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`,
- * not an ambient request context.
- *
- * Results are pull-only via this tool — the workflow does NOT write to the
- * conversation thread on completion. The retired `run-result-writer` push
- * payload (run status, step summaries, run synthesis, artifact paths) is
- * surfaced here on demand: the run row + step `summaryPath` references +
- * the `synthesisPath` for runs whose synthesis was produced let the
- * conversation agent `read_file` the artefacts it needs.
+ * Results are pull-only: workflows never append completion messages to a
+ * conversation. List mode is active-first and paged. Targeted mode makes
+ * readiness explicit and can perform one bounded, abort-aware wait.
  */
 import type { Pool } from "pg";
 import type { CortexRunRow } from "../../state/schema.js";
@@ -20,7 +13,6 @@ interface FormattedStep {
     agentId: string;
     wave: number;
     status: string;
-    /** Absent for steps that never ran (`pending`/`skipped`) — no output tree exists to point at. */
     summaryPath?: string;
     durationMs?: number | null;
     error?: string | null;
@@ -29,15 +21,34 @@ interface FormattedStep {
     finishReason?: string | null;
     hitMaxSteps?: boolean | null;
 }
+interface WaitMetadata {
+    readonly requestedSeconds: number;
+    readonly cutoffReached: boolean;
+}
 type InspectRunOutput = {
-    message: string;
-} | {
     runs: FormattedRun[];
+    total: number;
+    page: number;
+    pageSize: number;
+    hasMore: boolean;
+} | {
+    inspectionState: "not_found";
+    message: string;
+    wait?: WaitMetadata;
 } | {
+    inspectionState: "in_progress" | "suspended" | "terminal";
+    message: string;
     run: FormattedRun;
     steps: FormattedStep[];
+    elapsedMs?: number;
+    wait?: WaitMetadata;
+    selfWaitPrevented?: boolean;
 };
-declare function formatRun(r: CortexRunRow, verbose: boolean): {
+interface InspectRunClock {
+    now(): number;
+    wait(ms: number, signal: AbortSignal): Promise<void>;
+}
+declare function formatRun(r: CortexRunRow, verbose: boolean, exposePaths?: boolean): {
     error?: string | null | undefined;
     synthesisReason?: string | undefined;
     runId: string;
@@ -49,8 +60,15 @@ declare function formatRun(r: CortexRunRow, verbose: boolean): {
     synthesisPath: string | null;
     synthesisStatus: "failed" | "produced" | "skipped_no_summaries" | "skipped_blocker" | null;
 };
-export declare function createInspectRunTool(pool: Pool): import("../define-tool.js").Tool<{
+/**
+ * Build the run-inspection tool. The optional clock is an internal testing
+ * seam for deterministic cutoff and transition coverage.
+ */
+export declare function createInspectRunTool(pool: Pool, clock?: InspectRunClock): import("../define-tool.js").Tool<{
     runId?: string | undefined;
+    page?: number | undefined;
+    pageSize?: number | undefined;
+    waitForTerminalSeconds?: number | undefined;
     includeDiagnostics?: boolean | undefined;
 }, InspectRunOutput>;
 export {};