@inflexa-ai/harness 0.44.0 → 0.45.0

package/dist/memory/conversation-display-recorder.js

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { applyChatFrame, checkChatPart, isRootFrame, toChatFrame } from "../contracts/chat-frame.js";
 import { PART_REGISTRY } from "../contracts/part-registry.js";
+import { createSubAgentActivityTracker } from "../contracts/subagent-activity.js";
 import { compactionExchangeOf, compactionMarkerOf } from "./ai-sdk-message-storage.js";
 import { conversationDisplayPart } from "./conversation-display-storage.js";
 function jsonCopy(value) {
@@ -69,6 +70,8 @@ export function createConversationDisplayRecorder(options) {
     // The messages of the open round. A later update of a part lands in the next round, and the replay replaces the earlier copy.
     let round = [];
     let finished = false;
+    const now = options.now ?? Date.now;
+    const subAgentActivity = createSubAgentActivityTracker();
     function apply(frame) {
         round = applyChatFrame(round, frame, assistantMessageId).messages;
     }
@@ -84,7 +87,13 @@ export function createConversationDisplayRecorder(options) {
     }
     function record(event) {
         const frame = toChatFrame(event, rootSource);
-        if (frame === null || !isRootFrame(frame))
+        if (frame === null)
+            return;
+        // The tracker reads the frames of the sub-agents, and `applyChatFrame` ignores them.
+        const activity = subAgentActivity.track(frame, now());
+        if (activity !== null && durableConversationType(activity.type))
+            apply(recordedPart(activity));
+        if (!isRootFrame(frame))
             return;
         if (frame.type.startsWith("data-")) {
             // Each chat event type is named without the `data-` prefix, thus a `data-` frame is a part frame.

package/dist/memory/conversation-display-storage.d.ts

@@ -15,7 +15,7 @@
  * reconstruction.
  */
 import { type DataUIPart, type UIMessage } from "ai";
-import type { AskPart, ChildSessionStartedPart, CompactionPart, FileReferencePart, PlanPart, PresentationPart, ReportRenderedPart, RunCardPart } from "../contracts/chat-parts.js";
+import type { AskPart, ChildSessionStartedPart, CompactionPart, FileReferencePart, PlanApprovalPart, PlanPart, PresentationPart, ReportRenderedPart, RunCardPart, SubAgentActivityEntry, SubAgentActivityPart } from "../contracts/chat-parts.js";
 import type { ToolCallOutcome } from "../contracts/chat-events.js";
 import type { ChatMessage, MessagePart, ToolCallPart } from "../contracts/message.js";
 import type { Logger } from "../lib/logger.js";
@@ -37,11 +37,17 @@ export type ConversationUIData = {
     presentation: Payload<PresentationPart>;
     plan: Payload<PlanPart>;
     "run-card": Payload<RunCardPart>;
+    "plan-approval": Payload<PlanApprovalPart>;
     "file-reference": Payload<FileReferencePart>;
     ask: Payload<AskPart>;
     "child-session-started": Payload<ChildSessionStartedPart>;
     "report-rendered": Payload<ReportRenderedPart>;
     compaction: Payload<CompactionPart>;
+    "subagent-activity": Omit<Payload<SubAgentActivityPart>, "entries"> & {
+        entries: (Omit<SubAgentActivityEntry, "outcome"> & {
+            outcome: ToolCallOutcome;
+        })[];
+    };
 };
 export interface ConversationDisplayMetadata {
     interrupted?: boolean;
@@ -63,7 +69,8 @@ export declare function parseStoredDisplayEnvelope(value: unknown, identity: str
  * flight) and required here, because a record is of a call that is no longer
  * running. An in-flight call being recorded is one the turn never saw finish, so
  * absence resolves to `incomplete` at exactly this boundary — once, where the
- * lifetime changes — rather than at each reader.
+ * lifetime changes — rather than at each reader. An entry of a sub-agent call
+ * closes the same way, and an `incomplete` entry has no end time.
  */
 export declare function conversationDisplayPart(part: Exclude<MessagePart, {
     type: "text";

package/dist/memory/conversation-display-storage.js

@@ -16,7 +16,7 @@
  */
 import { validateUIMessages } from "ai";
 import { z } from "zod";
-import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, } from "../contracts/schemas/chat-parts.js";
+import { AskPartSchema, ChildSessionStartedPartSchema, CompactionPartSchema, FileReferencePartSchema, PlanApprovalPartSchema, PlanPartSchema, PresentationPartSchema, ReportRenderedPartSchema, RunCardPartSchema, SubAgentActivityEntrySchema, SubAgentActivityPartSchema, } from "../contracts/schemas/chat-parts.js";
 import { ToolCallOutcomeSchema } from "../contracts/schemas/chat-events.js";
 export const SUPPORTED_DISPLAY_SCHEMA_VERSION = 1;
 const DisplayEnvelopeHeaderSchema = z.object({
@@ -65,11 +65,15 @@ const dataSchemas = {
     presentation: PresentationPartSchema.omit({ type: true }),
     plan: PlanPartSchema.omit({ type: true }),
     "run-card": RunCardPartSchema.omit({ type: true }),
+    "plan-approval": PlanApprovalPartSchema.omit({ type: true }),
     "file-reference": FileReferencePartSchema.omit({ type: true }),
     ask: AskPartSchema.omit({ type: true }),
     "child-session-started": ChildSessionStartedPartSchema.omit({ type: true }),
     "report-rendered": ReportRenderedPartSchema.omit({ type: true }),
     compaction: CompactionPartSchema.omit({ type: true }),
+    "subagent-activity": SubAgentActivityPartSchema.omit({ type: true }).extend({
+        entries: z.array(SubAgentActivityEntrySchema.extend({ outcome: ToolCallOutcomeSchema })),
+    }),
 };
 export function envelopeDisplayMessages(messages) {
     if (messages.length === 0)
@@ -157,6 +161,12 @@ export async function parseStoredDisplayEnvelope(value, identity, logger) {
 function displayPartType(part) {
     return (part.type === "tool-call" ? "data-tool-call" : part.type);
 }
+function closedEntry(entry) {
+    if (entry.outcome !== undefined)
+        return { ...entry, outcome: entry.outcome };
+    const { endedAt: _endedAt, ...open } = entry;
+    return { ...open, outcome: "incomplete" };
+}
 /** The id a part reconciles on: a tool call by its call id, a card by its own stable id. */
 function displayPartId(part) {
     if (part.type === "tool-call")
@@ -171,11 +181,16 @@ function displayPartId(part) {
  * flight) and required here, because a record is of a call that is no longer
  * running. An in-flight call being recorded is one the turn never saw finish, so
  * absence resolves to `incomplete` at exactly this boundary — once, where the
- * lifetime changes — rather than at each reader.
+ * lifetime changes — rather than at each reader. An entry of a sub-agent call
+ * closes the same way, and an `incomplete` entry has no end time.
  */
 export function conversationDisplayPart(part) {
     const { type: _type, ...rest } = part;
-    const data = part.type === "tool-call" ? { ...rest, outcome: part.outcome ?? "incomplete" } : rest;
+    const data = part.type === "tool-call"
+        ? { ...rest, outcome: part.outcome ?? "incomplete" }
+        : part.type === "data-subagent-activity"
+            ? { ...rest, entries: part.entries.map(closedEntry) }
+            : rest;
     return { type: displayPartType(part), id: displayPartId(part), data };
 }
 /**

package/dist/memory/thread-history.d.ts

@@ -27,6 +27,7 @@ import type { TokenUsageRollup } from "../contracts/usage.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
 import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+import type { MessagePart } from "../contracts/message.js";
 import { type ConversationUIMessage, type StoredDisplayEnvelope } from "./conversation-display-storage.js";
 /** One stored message, as returned by the display read (`loadAll`). */
 export interface StoredMessage {
@@ -104,8 +105,14 @@ export interface ConversationTurn {
  * never shown. The harness owns the record-to-`system` mapping for the same
  * reason it owns the marker — a host that hand-assembled either could produce a
  * message the turn-boundary predicates fail to recognise.
+ *
+ * With `displayParts`, the display message holds those parts in place of the
+ * text part, and the model message is still the record of `text`. The text then
+ * stays for the model alone.
  */
-export declare function conversationRecordTurn(text: string): ConversationTurn;
+export declare function conversationRecordTurn(text: string, displayParts?: readonly Exclude<MessagePart, {
+    type: "text";
+}>[]): ConversationTurn;
 /** The status of a chat turn: `open` while it runs, then its outcome. */
 export type TurnStatus = "open" | "done" | "aborted" | "failed";
 /** The close of a chat turn. It sets the outcome on the turn record, one time. */

package/dist/memory/thread-history.js

@@ -29,7 +29,7 @@ import { hasReportedUsage } from "../loop/metrics.js";
 import { countTokens } from "./count-tokens.js";
 import { conversationView, groupTurns, isGenuineUserStart } from "./conversation-view.js";
 import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, parseStoredMessageEnvelope, syntheticRecordMessage, } from "./ai-sdk-message-storage.js";
-import { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./conversation-display-storage.js";
+import { conversationDisplayPart, envelopeDisplayMessages, parseStoredDisplayEnvelope, } from "./conversation-display-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
 function okVoid() {
     return new ResultAsync(Promise.resolve(ok(undefined)));
@@ -44,11 +44,21 @@ function okVoid() {
  * never shown. The harness owns the record-to-`system` mapping for the same
  * reason it owns the marker — a host that hand-assembled either could produce a
  * message the turn-boundary predicates fail to recognise.
+ *
+ * With `displayParts`, the display message holds those parts in place of the
+ * text part, and the model message is still the record of `text`. The text then
+ * stays for the model alone.
  */
-export function conversationRecordTurn(text) {
+export function conversationRecordTurn(text, displayParts) {
     return {
         modelMessages: [syntheticRecordMessage(text)],
-        displayMessages: [{ id: randomUUID(), role: "system", parts: [{ type: "text", text, state: "done" }] }],
+        displayMessages: [
+            {
+                id: randomUUID(),
+                role: "system",
+                parts: displayParts !== undefined && displayParts.length > 0 ? displayParts.map(conversationDisplayPart) : [{ type: "text", text, state: "done" }],
+            },
+        ],
     };
 }
 /**

package/dist/memory/thread-store.d.ts

@@ -169,6 +169,12 @@ export interface ListThreadsInput {
     /** Narrow to one thread's direct children, exact match. Same polarity as `type`: omitting it narrows nothing. */
     readonly parentThreadId?: string;
 }
+export interface ListRecentThreadsInput {
+    /** The most threads to give. It clamps to 1 to 200, the bounds of a page of `listThreads`. */
+    readonly limit: number;
+    /** Narrow to one kind of session, exact match. Omitting it narrows nothing. */
+    readonly type?: ThreadType;
+}
 export interface ThreadPage {
     readonly threads: Thread[];
     readonly total: number;
@@ -247,6 +253,13 @@ export interface ThreadStore {
      * always describe whichever set the page was drawn from.
      */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
+    /**
+     * The newest live threads over every analysis, newest-updated first, with
+     * `thread_id` breaking a tie in ascending order. One statement that walks
+     * the live-row index on the update time. `type` narrows the result, and an
+     * archived thread is never in it.
+     */
+    listRecentThreads(input: ListRecentThreadsInput): ResultAsync<Thread[], DbError>;
 }
 /**
  * Create a `ThreadStore` bound to a Postgres pool — a factory closure

package/dist/memory/thread-store.js

@@ -366,5 +366,19 @@ export function createThreadStore(pool) {
             }));
         });
     }
-    return { createThread, getThread, updateTitle, setAutoTitle, archiveThread, unarchiveThread, purgeThread, listThreads };
+    function listRecentThreads(input) {
+        const limit = Math.min(Math.max(input.limit, 1), MAX_PER_PAGE);
+        const values = [limit];
+        let typePredicate = "";
+        if (input.type !== undefined) {
+            values.push(input.type);
+            typePredicate = " AND thread_type = $2";
+        }
+        return tryQuery("thread-store.listRecentThreads", () => pool.query(`SELECT ${THREAD_COLUMNS}
+         FROM cortex_analysis_threads
+         WHERE deleted_at IS NULL${typePredicate}
+         ORDER BY updated_at DESC, thread_id
+         LIMIT $1`, values)).map(({ rows }) => rows.map(toThread));
+    }
+    return { createThread, getThread, updateTitle, setAutoTitle, archiveThread, unarchiveThread, purgeThread, listThreads, listRecentThreads };
 }

package/dist/prompts/conversation.d.ts

@@ -1 +1 @@
-export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via\n   `execute_analysis`. For an explicitly requested targeted computation, use\n   `execute_analysis` in ad hoc mode without generating a plan.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do not\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. Do not re-derive these\n   facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`, then `list_files`.\n3. **What is inside a file** \u2192 `read_file` on a path a search returned.\n\nDo not tell the user you cannot access their files \u2014 you can.\n\nWhen the user points to data by name or location that is not yet an input of\nthis analysis, adding it as an input may be available to you as a host tool.\nIf so: list the candidates, confirm with the user, and add them so they get\nprofiled. Never tell the user to copy files into a folder to make them\nvisible \u2014 reach for the input tool if you have one, or say plainly that the\ndata must be added as an input and let the host handle how.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do not summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call\n   `execute_analysis({ mode: \"plan\", planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow.\n6. **Plan stale / invalid?** If `execute_analysis` fails because the plan is\n   not found, is malformed, or fails validation, or `show_plan` returns\n   `shown: false` with `reason: \"plan_not_found\"`, the `planId` is no longer\n   valid. Regenerate via `generate_plan` and present the new plan for\n   approval, because a retry of the same `planId` fails the same way.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it. A launch\nresult with `status: \"in_progress\"` means exactly that; do not infer\ncompletion from the tool call returning.\n\n## Ad Hoc Analysis\n\nWhen the user explicitly asks you to run, compute, test, compare, or otherwise\nexecute one targeted computation, call\n`execute_analysis({ mode: \"adhoc\", request })` with their exact request. Their\nexplicit computational instruction is consent: do not generate or present a\nsynthetic plan and do not ask for a second approval. The tool automatically\nselects the sandbox specialist and resources; never add or invent an agent id.\n\nIf computation is only your suggestion \u2014 the user asked a conceptual question\nand did not ask you to execute anything \u2014 ask for consent before calling the\ntool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve\ntheir results later with `inspect_run`. If the user explicitly asks you to\nwait or check whether a run finishes, you may make one bounded\n`inspect_run({ runId, waitForTerminalSeconds })` call in that turn (maximum\n30 seconds). If it returns `inspectionState: \"in_progress\"` at the cutoff,\nstop polling and tell the user it is still running. Never loop on\n`inspect_run`; otherwise inspect on a later turn.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **A step summary**, one for each step \u2014 computational findings, method\n  choices, quality assessment. Pure facts, no literature.\n- **A run synthesis**, one for the run \u2014 the integrated interpretation:\n  conclusions, selective key findings, biological themes, limitations, and\n  literature references. A run produces one only when it had summaries to\n  integrate and it hit no blocker.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the `synthesisStatus` of the run, and it gives a `synthesisPath`\n   only when that status is `produced`. The synthesis is your primary source\n   when it exists. When it was skipped or failed, read the step summaries and\n   integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the summary of that step for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use your\n   bio-lookup tools directly to investigate beyond what the synthesis\n   already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYour bio-lookup tools are how you answer a biology question. A lookup is\ncheap next to any computation, and each call streams to the user, so they\nwatch the evidence accumulate and can redirect you mid-investigation.\n\n**A quick answer** is one or two calls:\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `lookup_annotation`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**A systematic investigation** (3+ targets, evidence profiles, novelty\ngrading) is the same tools driven wider. Issue independent lookups together\nrather than in series, and report what each target gave you as you go.\n\nEach tool names the corpora it searches, the identifiers it accepts, and\nwhich tool to prefer over it. Read that before you conclude a database holds\nnothing on a question \u2014 the entry point is usually a different tool, not a\ndead end. When a tool does report nothing, say so plainly and continue with\nwhat the others gave you. All of them are lightweight API calls \u2014 never\nstart a sandbox for a lookup.\n\nGround every claim in a record you actually retrieved. Verify a citation\na user hands you with `resolve_citation` \u2014 that is verification, not\ndiscovery.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, the phases below cover the\nevidence that a hypothesis set needs.\n\n### 1. Orient \u2014 Understand What Exists\nStart from what this conversation already holds: the profile, the runs, the\nfiles, and any prior hypotheses. Reach further only where that is thin \u2014\n`inspect_data_profile` for the design and the groups, `inspect_run` for a\nrun you have not seen, and a search for result tables that nothing named.\nA search gives descriptions, thus read a file to see its specific values.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nInvestigate the genes, pathways, and features you identified in\norientation, with your own bio-lookup tools. Carry the fold changes and\nthe condition names into what you look up.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo things serve hypothesis exploration: your own bio-lookup tools for\nin-domain biology evidence (used here), and `generate_analogy_report`\nfor cross-domain inspiration (used in the Ideate step below). Treat them\nas a pair \u2014 biology evidence anchors hypotheses to reality, analogies\nbroaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Keep only the hypotheses that earn a test.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders the result of `generate_analogy_report` as a card, so the\ncard is the presentation and your reply is the steering. Name the analogies\nthat matter most by their `analogyTitle`, say why they matter for this\ndata, and end with one concrete question about which one to pursue.\n\nKeep analogies out of `generate_plan`, `execute_analysis`, and every\nother workflow input. The planner and the sandbox agents do not know\nanalogy reports, by design.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation.\n\nCall `start_report_session`. It opens a report chat as a child of this\nconversation. Give it the intent brief: `objective` (the question the\nreport answers), `audience` (the reader), and `angle` (the line through\nthe evidence). Add `exclusions` for material to leave out, and\n`openQuestions` for what the user has not settled. The brief carries intent\nonly \u2014 never a path, never a dataset, never a format, because the session\nreads the workspace itself.\n\nThen tell the user where the report is. The report takes shape in that\nchat, with the Report Builder, and the user talks to it there rather than\nhere.\n\nWhen the tool returns `existing-session`, no new session started. Tell the\nuser to continue the report in that chat. Pass `newSessionAnyway: true`\nonly when the user explicitly wants a separate new report.\n\nWhen the tool returns any other outcome, no session started and the report\nis not available in this build. Say that in one line, and give the detail\nthat the outcome carries. Do not compose the report here instead.\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience matters\nand has not been established.\n\nStart a report session only when the user asks for a report. Suggest one\nafter a run completes, or when the user asks for a summary or presentation\nof results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing or looked up that exists in no artifact, `show_plan` for a\nstored `planId`, `show_file` for an existing artifact path. Cards render in\nthe order you emit them.\n\nPut each figure next to the prose that discusses it. Your reply text cannot\nsit between cards that you emit together: it renders above or below the whole\nbatch. Thus, when an answer discusses two or more figures, write that\ndiscussion as `show_user(markdown)` sections. Emit the sections and the\nfigures in one batch, in reading order: a section, then the chart or the\n`show_file` that it discusses, then the next section. Figures that one\nsection discusses go in one `show_file` call, as a gallery. Figures for\ndifferent sections go in separate calls. Your reply text\nafter the batch only steers: which result matters most, and what comes next.\nAn answer about one figure needs no sections. Show the figure, then write the\nanswer.\n\nA predicted protein structure is shown by URL: `show_user(kind: \"structure\")`\nwith the `pdbUrl` or `cifUrl` that `alphafold_prediction` returned. A\n`.pdb` or `.cif` a step wrote is an existing artifact \u2014 `show_file`.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it brief.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Interpret from search descriptions.** A `workspace_search` hit gives a\n  description, not the values. Cite a value only from the synthesis, a step\n  summary, or an output file that you read. If you cannot find the data\n  behind a claim, say so.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs whenever the analysis\n  has inputs \u2014 at init, and again when inputs are added or removed during the\n  conversation. Never propose \"explore data structure\" or \"initial\n  assessment\" steps.\n- **Split one targeted request into multiple ad hoc runs.** Keep one explicit\n  computational request in one ad hoc call. Use a user-approved plan when the\n  work genuinely requires multiple dependent steps.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";
+export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via\n   `execute_analysis`. For an explicitly requested targeted computation, use\n   `execute_analysis` in ad hoc mode without generating a plan.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do not\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. Do not re-derive these\n   facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`, then `list_files`.\n3. **What is inside a file** \u2192 `read_file` on a path a search returned.\n\nDo not tell the user you cannot access their files \u2014 you can.\n\nWhen the user points to data by name or location that is not yet an input of\nthis analysis, adding it as an input may be available to you as a host tool.\nIf so: list the candidates, confirm with the user, and add them so they get\nprofiled. Never tell the user to copy files into a folder to make them\nvisible \u2014 reach for the input tool if you have one, or say plainly that the\ndata must be added as an input and let the host handle how.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do not summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call\n   `execute_analysis({ mode: \"plan\", planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. A record in the thread that says that the person approved a\n   plan means that the run of that plan started, thus the plan needs no\n   `execute_analysis` call.\n6. **Plan stale / invalid?** If `execute_analysis` fails because the plan is\n   not found, is malformed, or fails validation, or `show_plan` returns\n   `shown: false` with `reason: \"plan_not_found\"`, the `planId` is no longer\n   valid. Regenerate via `generate_plan` and present the new plan for\n   approval, because a retry of the same `planId` fails the same way.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it. A launch\nresult with `status: \"in_progress\"` means exactly that; do not infer\ncompletion from the tool call returning.\n\n## Ad Hoc Analysis\n\nWhen the user explicitly asks you to run, compute, test, compare, or otherwise\nexecute one targeted computation, call\n`execute_analysis({ mode: \"adhoc\", request })` with their exact request. Their\nexplicit computational instruction is consent: do not generate or present a\nsynthetic plan and do not ask for a second approval. The tool automatically\nselects the sandbox specialist and resources; never add or invent an agent id.\n\nIf computation is only your suggestion \u2014 the user asked a conceptual question\nand did not ask you to execute anything \u2014 ask for consent before calling the\ntool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve\ntheir results later with `inspect_run`. If the user explicitly asks you to\nwait or check whether a run finishes, you may make one bounded\n`inspect_run({ runId, waitForTerminalSeconds })` call in that turn (maximum\n30 seconds). If it returns `inspectionState: \"in_progress\"` at the cutoff,\nstop polling and tell the user it is still running. Never loop on\n`inspect_run`; otherwise inspect on a later turn.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **A step summary**, one for each step \u2014 computational findings, method\n  choices, quality assessment. Pure facts, no literature.\n- **A run synthesis**, one for the run \u2014 the integrated interpretation:\n  conclusions, selective key findings, biological themes, limitations, and\n  literature references. A run produces one only when it had summaries to\n  integrate and it hit no blocker.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the `synthesisStatus` of the run, and it gives a `synthesisPath`\n   only when that status is `produced`. The synthesis is your primary source\n   when it exists. When it was skipped or failed, read the step summaries and\n   integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the summary of that step for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use your\n   bio-lookup tools directly to investigate beyond what the synthesis\n   already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYour bio-lookup tools are how you answer a biology question. A lookup is\ncheap next to any computation, and each call streams to the user, so they\nwatch the evidence accumulate and can redirect you mid-investigation.\n\n**A quick answer** is one or two calls:\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `lookup_annotation`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**A systematic investigation** (3+ targets, evidence profiles, novelty\ngrading) is the same tools driven wider. Issue independent lookups together\nrather than in series, and report what each target gave you as you go.\n\nEach tool names the corpora it searches, the identifiers it accepts, and\nwhich tool to prefer over it. Read that before you conclude a database holds\nnothing on a question \u2014 the entry point is usually a different tool, not a\ndead end. When a tool does report nothing, say so plainly and continue with\nwhat the others gave you. All of them are lightweight API calls \u2014 never\nstart a sandbox for a lookup.\n\nGround every claim in a record you actually retrieved. Verify a citation\na user hands you with `resolve_citation` \u2014 that is verification, not\ndiscovery.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, the phases below cover the\nevidence that a hypothesis set needs.\n\n### 1. Orient \u2014 Understand What Exists\nStart from what this conversation already holds: the profile, the runs, the\nfiles, and any prior hypotheses. Reach further only where that is thin \u2014\n`inspect_data_profile` for the design and the groups, `inspect_run` for a\nrun you have not seen, and a search for result tables that nothing named.\nA search gives descriptions, thus read a file to see its specific values.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nInvestigate the genes, pathways, and features you identified in\norientation, with your own bio-lookup tools. Carry the fold changes and\nthe condition names into what you look up.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo things serve hypothesis exploration: your own bio-lookup tools for\nin-domain biology evidence (used here), and `generate_analogy_report`\nfor cross-domain inspiration (used in the Ideate step below). Treat them\nas a pair \u2014 biology evidence anchors hypotheses to reality, analogies\nbroaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Keep only the hypotheses that earn a test.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders the result of `generate_analogy_report` as a card, so the\ncard is the presentation and your reply is the steering. Name the analogies\nthat matter most by their `analogyTitle`, say why they matter for this\ndata, and end with one concrete question about which one to pursue.\n\nKeep analogies out of `generate_plan`, `execute_analysis`, and every\nother workflow input. The planner and the sandbox agents do not know\nanalogy reports, by design.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation.\n\nCall `start_report_session`. It opens a report chat as a child of this\nconversation. Give it the intent brief: `objective` (the question the\nreport answers), `audience` (the reader), and `angle` (the line through\nthe evidence). Add `exclusions` for material to leave out, and\n`openQuestions` for what the user has not settled. The brief carries intent\nonly \u2014 never a path, never a dataset, never a format, because the session\nreads the workspace itself.\n\nThen tell the user where the report is. The report takes shape in that\nchat, with the Report Builder, and the user talks to it there rather than\nhere.\n\nWhen the tool returns `existing-session`, no new session started. Tell the\nuser to continue the report in that chat. Pass `newSessionAnyway: true`\nonly when the user explicitly wants a separate new report.\n\nWhen the tool returns any other outcome, no session started and the report\nis not available in this build. Say that in one line, and give the detail\nthat the outcome carries. Do not compose the report here instead.\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience matters\nand has not been established.\n\nStart a report session only when the user asks for a report. Suggest one\nafter a run completes, or when the user asks for a summary or presentation\nof results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing or looked up that exists in no artifact, `show_plan` for a\nstored `planId`, `show_file` for an existing artifact path. Cards render in\nthe order you emit them.\n\nPut each figure next to the prose that discusses it. Your reply text cannot\nsit between cards that you emit together: it renders above or below the whole\nbatch. Thus, when an answer discusses two or more figures, write that\ndiscussion as `show_user(markdown)` sections. Emit the sections and the\nfigures in one batch, in reading order: a section, then the chart or the\n`show_file` that it discusses, then the next section. Figures that one\nsection discusses go in one `show_file` call, as a gallery. Figures for\ndifferent sections go in separate calls. Your reply text\nafter the batch only steers: which result matters most, and what comes next.\nAn answer about one figure needs no sections. Show the figure, then write the\nanswer.\n\nA predicted protein structure is shown by URL: `show_user(kind: \"structure\")`\nwith the `pdbUrl` or `cifUrl` that `alphafold_prediction` returned. A\n`.pdb` or `.cif` a step wrote is an existing artifact \u2014 `show_file`.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it brief.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Interpret from search descriptions.** A `workspace_search` hit gives a\n  description, not the values. Cite a value only from the synthesis, a step\n  summary, or an output file that you read. If you cannot find the data\n  behind a claim, say so.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs whenever the analysis\n  has inputs \u2014 at init, and again when inputs are added or removed during the\n  conversation. Never propose \"explore data structure\" or \"initial\n  assessment\" steps.\n- **Split one targeted request into multiple ad hoc runs.** Keep one explicit\n  computational request in one ad hoc call. Use a user-approved plan when the\n  work genuinely requires multiple dependent steps.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";

package/dist/prompts/conversation.js

@@ -77,7 +77,9 @@ When the user wants to run an analysis:
 5. **Execute** — on approval, call
    \`execute_analysis({ mode: "plan", planId })\` with the
    approved \`planId\`. The tool resolves the plan server-side and starts
-   the workflow.
+   the workflow. A record in the thread that says that the person approved a
+   plan means that the run of that plan started, thus the plan needs no
+   \`execute_analysis\` call.
 6. **Plan stale / invalid?** If \`execute_analysis\` fails because the plan is
    not found, is malformed, or fails validation, or \`show_plan\` returns
    \`shown: false\` with \`reason: "plan_not_found"\`, the \`planId\` is no longer

package/dist/provenance/seam.d.ts

@@ -68,10 +68,8 @@ export type RunProvenanceEvent = {
     analysisId: string;
     runId: string;
     /**
-     * The body's terminal status. Both boundary sites resolve it through `deriveFinalStatus`,
-     * which records a suspension as `"canceled"` — so `"suspended_insufficient_funds"` (a
-     * `RunStatus` member) is never emitted here and is deliberately absent from this narrower
-     * `ExecuteAnalysisFinalStatus`-minus-`"running"` set.
+     * The body's terminal status, resolved through `deriveFinalStatus`. A suspension is
+     * `"suspended_insufficient_funds"`.
      */
     status: Exclude<ExecuteAnalysisFinalStatus, "running">;
     atMs: number;
@@ -95,7 +93,7 @@ type BlockAct = {
  * One observation of a session.
  *
  * The union names one event for each act: the start of a session, the four block operations, the title,
- * the derivation, the preview, the record, and the file write of a conversation turn. Each event carries
+ * the derivation, the preview, the record, the file write of a conversation turn, and the approval of a plan. Each event carries
  * the analysis and the thread, thus a consumer places it with no lookup. The title sits on the document,
  * thus the title event names no block.
  *
@@ -151,6 +149,19 @@ export type SessionProvenanceEvent = {
     threadId: string;
     versionId: string;
     replaced: boolean;
+} | {
+    /**
+     * A host approved a plan and the approval started its run. This is the one session event that
+     * carries a time: the approval is read before the launch, and the run emits `run_started` from
+     * its workflow body, thus a record orders the approval before the start only through `atMs`.
+     */
+    type: "approve-plan";
+    analysisId: string;
+    threadId: string;
+    planId: string;
+    runId: string;
+    /** Epoch milliseconds of the approval, read before the launch. */
+    atMs: number;
 } | {
     /**
      * One file that a conversation turn wrote with a file tool — a write under no run and no

package/dist/providers/ai-sdk.js

@@ -789,10 +789,12 @@ export function wrapFetchWithRequestTimeout(fetchImpl, requestTimeoutMs) {
         const signal = callerSignal ? AbortSignal.any([callerSignal, controller.signal]) : controller.signal;
         callerSignal?.addEventListener("abort", clear, { once: true });
         // `timeout: false` is an extension of the fetch init of Bun. Bun cuts a
-        // request that stays idle for 300 seconds, and this key lifts that cut. Node
-        // ignores an unknown member of the init, thus the key is inert there. A
-        // probe on Bun 1.3.14 proved both results. The `RequestInit` type declares
-        // no such member, thus the cast.
+        // request that stays idle past its default of 300 seconds, and this key
+        // lifts that cut. Node ignores an unknown member of the init, thus the key
+        // is inert there. A probe on Bun 1.4.2 proved both results: the cut fired
+        // at 360 seconds, because Bun pads the timer to its minute wheel, and a
+        // request with the key completed after 420 seconds. The `RequestInit` type
+        // declares no such member, thus the cast.
         const forwarded = { ...init, signal, timeout: false };
         try {
             return await fetchImpl(input, forwarded);

package/dist/report-model/pin-snapshot.d.ts

@@ -18,7 +18,7 @@
  */
 import { type Result } from "neverthrow";
 import type { Querier } from "../state/db.js";
-import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ReportSnapshot } from "./reference-resolver.js";
 /**
  * The reason that the pin gave no snapshot. The ledger read and the run listing are the two operations

package/dist/report-model/pin-snapshot.js

@@ -17,54 +17,11 @@
  * keeps the membership role, thus the record map is optional and it changes no resolution.
  */
 import { err, ok } from "neverthrow";
-import { open } from "node:fs/promises";
-import { join } from "node:path";
-import { tryFs } from "../lib/fs-result.js";
+import { readSynthesisText } from "../execution/run-synthesis.js";
 import { queryAnalysisArtifacts } from "../state/artifacts.js";
 import { queryRunsByAnalysis } from "../state/runs.js";
-import { isSafeId, runDir } from "../workspace/paths.js";
-/** The file name of the synthesis record inside the run directory. */
-const SYNTHESIS_FILE = "synthesis.json";
-/**
- * The cap of one synthesis read. A synthesis record is small by construction, and the cap bounds the
- * cost of a file that is not. A file over the cap gives no key, because a cut JSON text cannot parse.
- */
-const SYNTHESIS_CAP_BYTES = 1024 * 1024;
 /** The page size of the run listing. The listing walks the pages until a short page ends the walk. */
 const RUN_PAGE_SIZE = 200;
-/**
- * Read a synthesis record under the cap, or give `undefined` when the bytes do not come back.
- *
- * The read takes a bounded byte window, thus a file of any size costs the cap. An absent file, a genuine
- * read fault, and a file over the cap each give `undefined`, because the collection reports no error for
- * one record.
- */
-async function readSynthesisText(absolute) {
-    return tryFs("pinReportSnapshot.readSynthesis", async () => {
-        const handle = await open(absolute, "r");
-        try {
-            // The window takes one byte more than the cap. A read that fills it states that the file
-            // holds more bytes than the cap admits, thus the two conditions stay apart.
-            const buffer = Buffer.alloc(SYNTHESIS_CAP_BYTES + 1);
-            // One read of a network-backed file can give fewer bytes than the window holds. Such a
-            // short read cuts the text in the middle of the JSON, and the record then parses to no
-            // key at all. Thus the loop reads again from the offset that the last read reached, and
-            // it stops when the window fills or when a read gives no byte.
-            let filled = 0;
-            while (filled < buffer.length) {
-                const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, filled);
-                if (bytesRead === 0) {
-                    break;
-                }
-                filled += bytesRead;
-            }
-            return filled > SYNTHESIS_CAP_BYTES ? undefined : buffer.subarray(0, filled).toString("utf8");
-        }
-        finally {
-            await handle.close();
-        }
-    }, { path: absolute, onAbsent: () => undefined }).unwrapOr(undefined);
-}
 /** The trimmed text of a field, or `undefined` when the field is not a non-empty string. */
 function trimmedText(value) {
     if (typeof value !== "string") {
@@ -181,12 +138,7 @@ async function collectCitations(pool, resolveWorkspaceRoot, analysisId) {
             return err({ kind: "run-listing-failed", cause: page.error.cause });
         }
         for (const run of page.value) {
-            // The path builder refuses an id that can escape the run tree. A refusal is a throw, thus
-            // the guard keeps the collection on the value channel.
-            if (!isSafeId(run.runId)) {
-                continue;
-            }
-            const text = await readSynthesisText(join(root, runDir(run.runId), SYNTHESIS_FILE));
+            const text = await readSynthesisText({ workspaceRoot: root, runId: run.runId });
             if (text === undefined) {
                 continue;
             }

package/dist/runtime/assemble.d.ts

@@ -14,8 +14,9 @@
  * `applicationVersion` stamp because all registration happens in this one call,
  * before launch — a blue/green drain treats them as a single cohort.
  */
-import { type Result } from "neverthrow";
+import { type Result, type ResultAsync } from "neverthrow";
 import { type ConversationAgentDeps } from "../agents/conversation-agent.js";
+import { type ApprovePlanInput, type ApprovePlanRefusal, type PlanApproval } from "../app/approve-plan.js";
 import { type ReportSessionRuntime } from "../app/report-session-runtime.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
@@ -235,6 +236,12 @@ export interface CoreRuntime {
     readonly reportSession: Pick<ReportSessionRuntime, "ensureSessionState">;
     readonly workflows: RegisteredWorkflows;
     readonly citationResolver: CitationResolver;
+    /**
+     * Approve a stored plan by its id and start its run with no model call. It runs over the deps that
+     * reach the `execute_analysis` tool of the conversation agent, thus the approval and the tool launch
+     * a plan the same way.
+     */
+    readonly approvePlan: (input: ApprovePlanInput) => ResultAsync<PlanApproval, ApprovePlanRefusal>;
 }
 /**
  * The eyes of the composition, or none.

package/dist/runtime/assemble.js

@@ -17,6 +17,7 @@
 import { err, ok } from "neverthrow";
 import { createConversationAgent } from "../agents/conversation-agent.js";
 import { createReportSessionAgent } from "../agents/report-session-agent.js";
+import { approvePlan } from "../app/approve-plan.js";
 import { createReportSessionRuntime } from "../app/report-session-runtime.js";
 import { createNoopUsageRecorder } from "../billing/noop-usage-recorder.js";
 import { hasBrowserUrl } from "../lib/chrome.js";
@@ -210,5 +211,15 @@ export function assembleCoreRuntime(deps) {
             deriveTableExec,
         },
         citationResolver,
+        approvePlan: (input) => approvePlan({
+            pool: conversation.pool,
+            executeAnalysisWorkflow: executeAnalysis,
+            runAuthorizer: conversation.runAuthorizer,
+            runLauncher: conversation.runLauncher,
+            ...(resourcePolicy ? { resourcePolicy } : {}),
+            ...(conversation.extendAnalysisFarm ? { extendAnalysisFarm: conversation.extendAnalysisFarm } : {}),
+            ...(conversation.logger ? { logger: conversation.logger } : {}),
+            ...(deps.provenance ? { provenance: deps.provenance } : {}),
+        }, input),
     };
 }

package/dist/runtime/boot.d.ts

@@ -25,6 +25,9 @@
  *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
  *   7. `launchDbos(...)` — the last registration-dependent step.
+ *   8. `reconcileOrphanedRuns(pool)` — fails each `running` run whose workflow never started. It runs
+ *      after launch, thus a workflow that recovery re-queued counts as started. A failure is logged and does
+ *      not stop the boot, because the repair only frees the slot of a plan.
  *
  * No step reads or rewrites stored conversation display. A boot that validated
  * every `messages` row is what let a single retired part key fail startup for a

package/dist/runtime/boot.js

@@ -25,6 +25,9 @@
  *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
  *   7. `launchDbos(...)` — the last registration-dependent step.
+ *   8. `reconcileOrphanedRuns(pool)` — fails each `running` run whose workflow never started. It runs
+ *      after launch, thus a workflow that recovery re-queued counts as started. A failure is logged and does
+ *      not stop the boot, because the repair only frees the slot of a plan.
  *
  * No step reads or rewrites stored conversation display. A boot that validated
  * every `messages` row is what let a single retired part key fail startup for a
@@ -38,6 +41,7 @@
 import { SANDBOX_AGENT_META } from "../agents/sandbox/index.js";
 import { validateAgentSkills } from "../agents/sandbox/validate-skills.js";
 import { initCortexState } from "../state/init.js";
+import { reconcileOrphanedRuns } from "../state/runs.js";
 import { assembleCoreRuntime } from "./assemble.js";
 import { assertConnectionBudget } from "./connection-budget.js";
 import { launchDbos, shutdownDbos } from "./dbos.js";
@@ -56,7 +60,12 @@ export async function bootHarness(deps) {
     const runtime = assembleCoreRuntime(core);
     await deps.beforeLaunch?.();
     await launchDbos({ config: deps.dbos, logger });
-    logger.named("boot").info("harness booted", { executorId: deps.dbos.executorId });
+    const bootLog = logger.named("boot");
+    (await reconcileOrphanedRuns(pool)).match((runIds) => {
+        if (runIds.length > 0)
+            bootLog.warn("failed the runs whose workflow never started", { runIds });
+    }, (error) => bootLog.warn("the repair of the orphaned runs failed", bootLog.errorFields(error)));
+    bootLog.info("harness booted", { executorId: deps.dbos.executorId });
     const shutdown = (signal) => runShutdownSequence({
         signal,
         logger,

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -5,6 +5,7 @@
  * extraction/fold, and the chat-data-part narrowing a workflow body composes
  * into its emitters.
  */
+import type { ActivityEntryPart, StepActivityPart, StepPhase, SynthesisPhase, SynthesisProgressPart } from "../contracts/chat-parts.js";
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
 import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 /**
@@ -19,6 +20,28 @@ import type { ToolDetailResolver } from "../tools/detail-resolver.js";
  * producers construct it identically.
  */
 export declare function stepPartId(kind: string, runId: string, stepId: string): string;
+/**
+ * The two parts of one activity emission: the reconciling `data-step-activity` that holds the current activity,
+ * and the `data-activity-entry` that keeps the emission in the run stream. Both carry the same phase, activity,
+ * and time. `seq` is the position of the emission in the body of its workflow, so each entry has its own id, and a
+ * recovered body counts the same emissions again and gives the same ids. Every producer mints the two parts here.
+ */
+export declare function activityEmission(frame: {
+    readonly runId: string;
+    readonly stepId: string;
+}, seq: number, phase: StepPhase, activity: string, at: string): {
+    readonly activity: StepActivityPart;
+    readonly entry: ActivityEntryPart;
+};
+/**
+ * The two parts of one synthesis progress report: the reconciling `data-synthesis-progress` that holds the current
+ * phase, and the `data-activity-entry` that keeps the report in the run stream under the synthesis step. `seq` is the
+ * position of the report in the synthesis, so each entry has its own id. The `extra` fields stay on the progress part.
+ */
+export declare function synthesisEmission(runId: string, stepId: string, seq: number, phase: SynthesisPhase, activity: string, at: string, extra: Pick<SynthesisProgressPart, "delegationCount" | "reason" | "error">): {
+    readonly progress: SynthesisProgressPart;
+    readonly entry: ActivityEntryPart;
+};
 /**
  * The live-activity phrase for one tool call: the tool's name, then its own
  * description of this call when it has one.