@inflexa-ai/harness 0.19.2 → 0.21.0

package/dist/agents/conversation-agent.d.ts

@@ -14,21 +14,18 @@
  * `execute_analysis` is wired here — it launches the DBOS `executeAnalysis` parent
  * workflow under `workflowId = runId` (the bare run UUID) through the
  * `RunLauncher` seam and returns the runId (results are pull-only via
- * `inspectRun` on a later turn). Report authoring is wired here as the
- * pair `plan_report` (returns the report-brief schema + authoring rules
- * just-in-time as its result) + `submit_report` (validates the composed brief
- * and drives in-process Nunjucks rendering via the `report-builder` agent, no
- * sandbox). The 4 custom tools the builder itself drives (`build_report`, its
- * own terminal `submit_report`, `preview_snapshot`, `mint_preview_url`) are
- * constructed inside the runner so they share closure-captured outcome state +
- * preview-dir paths.
+ * `inspectRun` on a later turn). `start_report_session` is the one report path.
+ * It starts a report thread as a child of the conversation, and the Report
+ * Builder composes the report in that thread.
  * The workspace read surface (`read_file`, `grep`, `workspace_search`) is
  * wired here over the `WorkspaceFilesystem` seam.
  */
 import type { Pool } from "pg";
 import type { ExecuteAnalysisInput, ExecuteAnalysisResult } from "../workflows/execute-analysis.js";
+import type { EnsureSessionStateResult } from "../app/report-session-runtime.js";
 import type { ResourcePolicy } from "../config/resource-limits.js";
 import type { ChromeConfig } from "../lib/chrome.js";
+import type { AcquireEyes } from "../lib/eyes.js";
 import type { AgentDefinition } from "../loop/types.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { Tool } from "../tools/define-tool.js";
@@ -38,7 +35,7 @@ import { type BioToolKeys } from "../tools/bio/keys.js";
 import type { EnvironmentStorePaths } from "../config/environment-stores.js";
 import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { RunLauncher } from "../execution/run-launcher.js";
-import { type SubmitReportDeps } from "../tools/iterate-report.js";
+import type { SubmitReportDeps } from "../tools/iterate-report.js";
 import type { Logger } from "../lib/logger.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { CitationResolver } from "../citations/types.js";
@@ -80,6 +77,13 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      * launches it through the `RunLauncher` seam to start the run.
      */
     readonly executeAnalysisWorkflow: (input: ExecuteAnalysisInput) => Promise<ExecuteAnalysisResult>;
+    /**
+     * The anchor operation of the report session runtime — produced by
+     * `createReportSessionRuntime` and wired by `assembleCoreRuntime`. The spawn
+     * of `start_report_session` runs it after the seed of the child lands, thus
+     * the transcript anchor and the data snapshot pin at one moment.
+     */
+    readonly anchorReportSession: (threadId: string) => Promise<EnsureSessionStateResult>;
     /** Workspace-root resolution seam (see workspace/paths.ts). */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /**
@@ -95,19 +99,27 @@ export interface ConversationAgentDeps extends EnvironmentStorePaths {
      */
     readonly runLauncher: RunLauncher;
     /**
-     * Preview-publishing seam factory for `submit_report` — injected, not
-     * constructed here. The managed root closes its platform deps over this; the
-     * OSS root returns the "unavailable" publisher.
+     * Preview-publishing seam factory. No tool of the roster reads it. The field
+     * stays, because a change to the deps breaks an embedder at its composition
+     * root.
      */
     readonly createPreviewPublisher: SubmitReportDeps["createPreviewPublisher"];
     /** API keys for the external bio/chem data sources. */
     readonly bioKeys: BioToolKeys;
-    /** Root templates dir for in-process report rendering (`submit_report`). */
+    /** Root templates dir. No tool of the roster reads it. */
     readonly templatesDir: string;
-    /** Skills root; the in-process report-builder gets `report-html` skill tools. */
+    /** Skills root. No tool of the roster reads it. */
     readonly skillsDir: string;
     /** Headless-Chrome config for report snapshot/preview rendering. */
     readonly chrome: ChromeConfig;
+    /**
+     * The eyes of a report session — where a browser comes from for one look at
+     * the rendered page. `start_report_session` hands it to its spawn, thus a
+     * composition that binds the seam and names no browser still starts a
+     * session. The assembly resolves the eyes one time, and the agent that looks
+     * at a page reads that same answer.
+     */
+    readonly eyes?: AcquireEyes;
     /**
      * Host resource policy — per-step ceilings + machine budget. `generate_plan`
      * states the ceilings to the planner and validates against them;

package/dist/agents/conversation-agent.js

@@ -14,14 +14,9 @@
  * `execute_analysis` is wired here — it launches the DBOS `executeAnalysis` parent
  * workflow under `workflowId = runId` (the bare run UUID) through the
  * `RunLauncher` seam and returns the runId (results are pull-only via
- * `inspectRun` on a later turn). Report authoring is wired here as the
- * pair `plan_report` (returns the report-brief schema + authoring rules
- * just-in-time as its result) + `submit_report` (validates the composed brief
- * and drives in-process Nunjucks rendering via the `report-builder` agent, no
- * sandbox). The 4 custom tools the builder itself drives (`build_report`, its
- * own terminal `submit_report`, `preview_snapshot`, `mint_preview_url`) are
- * constructed inside the runner so they share closure-captured outcome state +
- * preview-dir paths.
+ * `inspectRun` on a later turn). `start_report_session` is the one report path.
+ * It starts a report thread as a child of the conversation, and the Report
+ * Builder composes the report in that thread.
  * The workspace read surface (`read_file`, `grep`, `workspace_search`) is
  * wired here over the `WorkspaceFilesystem` seam.
  */
@@ -39,7 +34,7 @@ import { createUpdateWorkingMemoryTool } from "../tools/memory/index.js";
 import { createListAvailablePackagesTool } from "../tools/sandbox/list-available-packages.js";
 import { createListAvailableRefsTool } from "../tools/sandbox/list-available-refs.js";
 import { createExecuteAnalysisTool } from "../tools/execute-analysis.js";
-import { planReportTool, createReportSubmitTool } from "../tools/iterate-report.js";
+import { createStartReportSessionTool } from "../tools/start-report-session.js";
 import { createResolveCitationTool } from "../tools/research/resolve-citation.js";
 /** Canonical agent id — the single source of truth. */
 export const CONVERSATION_AGENT_ID = "conversation-agent";
@@ -47,7 +42,7 @@ export const CONVERSATION_AGENT_ID = "conversation-agent";
 const CONVERSATION_MAX_ITERATIONS = 50;
 /** Build the conversation `AgentDefinition` with every tool fully dep-bound. */
 export function createConversationAgent(deps) {
-    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, resolveWorkspaceRoot, runAuthorizer, runLauncher, createPreviewPublisher, bioKeys, templatesDir, skillsDir, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, usageRecorder, citationResolver, } = deps;
+    const { provider, pool, embedding, workspaceFs, model, utilityProvider, utilityModel, executeAnalysisWorkflow, runAuthorizer, runLauncher, bioKeys, chrome, resourcePolicy, hostTools, refStorePath, packagesFile, usageRecorder, citationResolver, } = deps;
     const workingMemory = createWorkingMemory(pool);
     const ncbi = createNcbiTools(bioKeys);
     const chemDb = createChemDbTools(bioKeys, { ...(deps.logger ? { logger: deps.logger } : {}) });
@@ -114,21 +109,15 @@ export function createConversationAgent(deps) {
             utilityModel,
             ...(deps.logger ? { logger: deps.logger } : {}),
         }),
-        // Report authoring: the always-on `plan_report` trigger delivers the
-        // heavy brief schema + rules just-in-time as its result; `submit_report`
-        // takes the composed brief as `unknown` and validates it in-execute, so
-        // the ~12k schema never rides the always-on tool surface.
-        planReportTool,
-        createReportSubmitTool({
-            provider,
+        // The one report path. The tool starts a report thread as a child of the
+        // conversation, and the user composes the report there with the Report
+        // Builder.
+        createStartReportSessionTool({
             pool,
-            resolveWorkspaceRoot,
-            model,
-            templatesDir,
-            skillsDir,
             chrome,
-            createPreviewPublisher,
-            usageRecorder,
+            anchorSession: deps.anchorReportSession,
+            ...(deps.eyes ? { eyes: deps.eyes } : {}),
+            ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         // Display.
         showUserTool,

package/dist/agents/report-session-agent.d.ts

@@ -3,9 +3,9 @@
  *
  * `createReportSessionAgent` is the composition root of the report path. It gets
  * the shared deps one time, and it hands each tool exactly what it needs. The
- * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
- * session-state gateway, thus one assembled definition serves every thread, and the
- * per-session state stays behind the tool boundary.
+ * authoring tools, the listing tool, the preview tool, the eyes tool, and the record
+ * tool bind to the session-state gateway, thus one assembled definition serves every
+ * thread, and the per-session state stays behind the tool boundary.
  *
  * The roster is read-only toward the analysis. It holds the workspace read tools,
  * the workspace search, the run inspection, and the data-profile inspection. It
@@ -13,6 +13,10 @@
  * mutate surface. Thus no tool starts a run, and no tool changes an analysis. The
  * roster omits those tools, and no runtime guard blocks them.
  *
+ * The derivation tool is the one tool that runs a container, and it changes no
+ * analysis either. It mints no run id, it registers no artifact, and it writes under
+ * the directory of the session alone.
+ *
  * The definition carries no per-session value. The system prompt composes through
  * `composeSystemPrompt` with the identity part and the conversational part, the
  * same composition as the conversation agent. Thus the prompt prefix stays constant
@@ -20,11 +24,15 @@
  */
 import type { Pool } from "pg";
 import type { AuthContext } from "../auth/types.js";
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
 import type { AgentDefinition } from "../loop/types.js";
+import type { SandboxClient } from "../sandbox/client.js";
+import type { ReportSessionStateStore } from "../state/report-session-state.js";
 import type { EmbeddingProvider } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ChromeConfig } from "../lib/chrome.js";
+import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
 import type { ThreadStore } from "../memory/thread-store.js";
 import type { ReferenceResolver } from "../report-model/reference-resolver.js";
@@ -48,16 +56,34 @@ export interface ReportSessionAgentDeps {
     readonly embedding: EmbeddingProvider;
     /** Workspace filesystem read seam -- the four read tools. */
     readonly workspaceFs: WorkspaceFilesystem;
-    /** Session-state gateway -- the authoring tools, the preview tool, the eyes tool, and the record tool bind to it. */
+    /** Session-state gateway -- the authoring tools, the listing tool, the preview tool, the eyes tool, and the record tool bind to it. */
     readonly gateway: ReportSessionStateGateway;
-    /** Workspace-root resolution seam -- the preview tool and the eyes tool resolve the page root per call. */
+    /** Workspace-root resolution seam -- the listing tool, the preview tool, and the eyes tool resolve the root per call. */
     readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
     /** Append-only version store -- the record tool gates the whole document first, then records one version. */
     readonly store: ReportVersionStore;
+    /** Derivation ledger -- the derivation tool appends one record for each derived table. */
+    readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
+    /**
+     * Sandbox seam -- the derivation tool runs one ephemeral container for each derived table. Omitted, the
+     * tool reports that the composition gives no sandbox, and it derives nothing.
+     */
+    readonly sandboxClient?: SandboxClient;
+    /**
+     * Run-authorization seam -- the derivation tool authorizes the exec and revokes on every terminal path.
+     * Omitted, the tool derives nothing, the same as an absent sandbox client.
+     */
+    readonly runAuthorizer?: RunAuthorizer;
     /** Thread reader -- the record tool reads the anchor of the report thread. */
     readonly threads: Pick<ThreadStore, "getThread">;
     /** Headless-Chrome config -- the eyes tool opens the rendered page. */
     readonly chrome: ChromeConfig;
+    /**
+     * Eyes seam -- where a browser comes from for one look. The eyes tool takes one lease for each look,
+     * and it releases the lease after the look. Omitted, the tool falls back to the chrome config, and a
+     * config that names no browser leaves the session with no look at all.
+     */
+    readonly eyes?: AcquireEyes;
     /**
      * Reference-resolution factory -- absent until a realization lands; the preview tool and the record tool
      * degrade as data. The factory binds one analysis, thus a tool makes the resolver over the scope of the call.

package/dist/agents/report-session-agent.js

@@ -3,9 +3,9 @@
  *
  * `createReportSessionAgent` is the composition root of the report path. It gets
  * the shared deps one time, and it hands each tool exactly what it needs. The
- * authoring tools, the preview tool, the eyes tool, and the record tool bind to the
- * session-state gateway, thus one assembled definition serves every thread, and the
- * per-session state stays behind the tool boundary.
+ * authoring tools, the listing tool, the preview tool, the eyes tool, and the record
+ * tool bind to the session-state gateway, thus one assembled definition serves every
+ * thread, and the per-session state stays behind the tool boundary.
  *
  * The roster is read-only toward the analysis. It holds the workspace read tools,
  * the workspace search, the run inspection, and the data-profile inspection. It
@@ -13,13 +13,17 @@
  * mutate surface. Thus no tool starts a run, and no tool changes an analysis. The
  * roster omits those tools, and no runtime guard blocks them.
  *
+ * The derivation tool is the one tool that runs a container, and it changes no
+ * analysis either. It mints no run id, it registers no artifact, and it writes under
+ * the directory of the session alone.
+ *
  * The definition carries no per-session value. The system prompt composes through
  * `composeSystemPrompt` with the identity part and the conversational part, the
  * same composition as the conversation agent. Thus the prompt prefix stays constant
  * across threads, and the provider cache reuses it.
  */
 import { createReportAuthoringTools } from "../tools/report-authoring/authoring-tools.js";
-import { createExaminePageTool, createPreviewReportTool, createRecordVersionTool } from "../tools/report-session/index.js";
+import { createDeriveTableTool, createExaminePageTool, createListPinnedArtifactsTool, createPreviewReportTool, createRecordVersionTool, } from "../tools/report-session/index.js";
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../tools/workspace/index.js";
 import { createInspectDataProfileTool, createInspectRunTool } from "../tools/research/index.js";
 import { reportSessionPrompt } from "../prompts/report-session.js";
@@ -33,7 +37,8 @@ export const REPORT_SESSION_AGENT_ID = "report-session";
 const REPORT_SESSION_MAX_ITERATIONS = 50;
 /** Build the report `AgentDefinition` with every tool bound to its deps. */
 export function createReportSessionAgent(deps) {
-    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, makeResolver, resolvePageAsset, logger } = deps;
+    const { model, pool, embedding, workspaceFs, gateway, resolveWorkspaceRoot, store, threads, chrome, eyes, makeResolver, resolvePageAsset, logger } = deps;
+    const { derivations, sandboxClient, runAuthorizer } = deps;
     const authoring = createReportAuthoringTools(gateway);
     const tools = [
         // The read surface toward the analysis. It roams the tree read-only.
@@ -54,6 +59,23 @@ export function createReportSessionAgent(deps) {
         authoring.read_outline,
         authoring.read_block,
         authoring.finish_draft,
+        // The orientation source of the pinned evidence. It reads the snapshot of the
+        // thread, and it resolves the workspace root per call for the header columns.
+        createListPinnedArtifactsTool({
+            gateway,
+            resolveWorkspaceRoot,
+            ...(logger ? { logger } : {}),
+        }),
+        // The derivation tool. It reshapes the pinned evidence into one table under the
+        // session directory, on the sandbox rails of the value tier.
+        createDeriveTableTool({
+            gateway,
+            resolveWorkspaceRoot,
+            derivations,
+            ...(sandboxClient ? { sandboxClient } : {}),
+            ...(runAuthorizer ? { runAuthorizer } : {}),
+            ...(logger ? { logger } : {}),
+        }),
         // The render-and-preview tool. It resolves the page root per call.
         createPreviewReportTool({
             gateway,
@@ -67,13 +89,16 @@ export function createReportSessionAgent(deps) {
             gateway,
             resolveWorkspaceRoot,
             chrome,
+            ...(eyes ? { eyes } : {}),
             ...(logger ? { logger } : {}),
         }),
-        // The record tool. It gates the whole document, then records one version.
+        // The record tool. It gates the whole document, records one version, then prunes each
+        // derived table that the recorded document does not bind.
         createRecordVersionTool({
             gateway,
             store,
             threads,
+            resolveWorkspaceRoot,
             ...(makeResolver ? { makeResolver } : {}),
             ...(logger ? { logger } : {}),
         }),

package/dist/app/chat-turn.js

@@ -36,7 +36,8 @@ export async function prepareChatTurn(deps, params) {
     if (existing && existing.analysisId !== analysisId) {
         return { kind: "not_found" };
     }
-    // The type a caller resolves the turn's agent from. An existing row carries
+    // The type a caller resolves the turn's agent from, and the type that the
+    // message assembly reads for its tail. An existing row carries
     // its own. An absent one defaults to `conversation` — the store's own
     // default — so a best-effort create that fails non-fatally still leaves a
     // usable type; a successful create overrides it from the returned row.
@@ -67,6 +68,7 @@ export async function prepareChatTurn(deps, params) {
     const history = createThreadHistory(pool);
     const { messages, userMessage } = await assembleMessages({
         threadId,
+        threadType,
         analysisId,
         userInput,
         analysisContext: analysisState?.context ?? null,

package/dist/app/message-assembly.d.ts

@@ -6,7 +6,7 @@
  *   [ ...loadRecent(threadId, budget)            ← stable, cacheable prefix
  *     {user: cortex_analysis_state.context},     ← tail
  *     {user: runActivityContext},                 ← tail
- *     {user: render(workingMemory)},             ← tail
+ *     {user: render(workingMemory)},             ← tail, `conversation` thread only
  *     {user: normalizeUnicode(redactSecrets(input))} ]  ← tail
  *
  * `system + tools + history` is the cacheable prefix — it only extends
@@ -14,6 +14,17 @@
  * **tail** as `user` messages: they change every turn, so a system-message
  * placement would bust the Anthropic cache prefix.
  *
+ * A `report` thread does not get the working-memory tail. The spawn copies the
+ * working-memory render into the child transcript at the anchor. A live render
+ * sees state past that anchor, and that breaks the knowledge cap of a report
+ * session. The analysis context and the run activity stay on both thread types.
+ *
+ * The history window of a `report` thread also keeps the first turn. That turn
+ * is the seed, and it is the one record of the brief and of the copied render.
+ * The window evicts the oldest turn first, thus a long session would drop its
+ * own charter and keep only its tools. A `conversation` thread evicts as before,
+ * because its live tail carries the working memory on each turn.
+ *
  * Sanitization (`redactSecrets`, `normalizeUnicode`) is applied **once**, to
  * the new user input only — never to history, assistant messages, tool
  * results, the analysis context, or the rendered working memory.
@@ -26,6 +37,7 @@
 import type { ModelMessage } from "ai";
 import type { LoopMessage } from "../loop/types.js";
 import type { ThreadHistory } from "../memory/thread-history.js";
+import type { ThreadType } from "../memory/thread-store.js";
 import type { WorkingMemoryStore } from "../memory/working-memory.js";
 /**
  * Token budget for the `loadRecent` history window. Sized to leave headroom
@@ -36,6 +48,8 @@ export declare const DEFAULT_HISTORY_TOKEN_BUDGET = 120000;
 export interface AssembleMessagesArgs {
     /** The conversation thread — a UI-generated UUID, never the analysisId. */
     readonly threadId: string;
+    /** The type of the thread. A `report` thread drops the working-memory tail, and its window keeps the seed. */
+    readonly threadType: ThreadType;
     /** The analysis scope — keys working memory and (separately) the context. */
     readonly analysisId: string;
     /** The raw, untrusted user input for this turn. */

package/dist/app/message-assembly.js

@@ -6,7 +6,7 @@
  *   [ ...loadRecent(threadId, budget)            ← stable, cacheable prefix
  *     {user: cortex_analysis_state.context},     ← tail
  *     {user: runActivityContext},                 ← tail
- *     {user: render(workingMemory)},             ← tail
+ *     {user: render(workingMemory)},             ← tail, `conversation` thread only
  *     {user: normalizeUnicode(redactSecrets(input))} ]  ← tail
  *
  * `system + tools + history` is the cacheable prefix — it only extends
@@ -14,6 +14,17 @@
  * **tail** as `user` messages: they change every turn, so a system-message
  * placement would bust the Anthropic cache prefix.
  *
+ * A `report` thread does not get the working-memory tail. The spawn copies the
+ * working-memory render into the child transcript at the anchor. A live render
+ * sees state past that anchor, and that breaks the knowledge cap of a report
+ * session. The analysis context and the run activity stay on both thread types.
+ *
+ * The history window of a `report` thread also keeps the first turn. That turn
+ * is the seed, and it is the one record of the brief and of the copied render.
+ * The window evicts the oldest turn first, thus a long session would drop its
+ * own charter and keep only its tools. A `conversation` thread evicts as before,
+ * because its live tail carries the working memory on each turn.
+ *
  * Sanitization (`redactSecrets`, `normalizeUnicode`) is applied **once**, to
  * the new user input only — never to history, assistant messages, tool
  * results, the analysis context, or the rendered working memory.
@@ -37,7 +48,7 @@ export const DEFAULT_HISTORY_TOKEN_BUDGET = 120_000;
  */
 export async function assembleMessages(args) {
     const budget = args.tokenBudget ?? DEFAULT_HISTORY_TOKEN_BUDGET;
-    const history = unwrapOrThrow(await args.history.loadRecent(args.threadId, budget));
+    const history = unwrapOrThrow(await args.history.loadRecent(args.threadId, budget, { keepFirstTurn: args.threadType === "report" }));
     // Sanitization — applied once, here, to the new user input only.
     const userMessage = {
         role: "user",
@@ -55,12 +66,15 @@ export async function assembleMessages(args) {
         role: "user",
         content: args.runActivityContext,
     });
-    // Working memory — agent-authored, trusted. Always injected (its rendered
-    // form names the sections even when empty).
-    tail.push({
-        role: "user",
-        content: unwrapOrThrow(await args.workingMemory.render(args.analysisId)),
-    });
+    // Working memory — agent-authored and trusted. A `conversation` thread
+    // always gets it, because the render names each section even when it is
+    // empty. A `report` thread reads the frozen copy in its seed message.
+    if (args.threadType !== "report") {
+        tail.push({
+            role: "user",
+            content: unwrapOrThrow(await args.workingMemory.render(args.analysisId)),
+        });
+    }
     tail.push(userMessage);
     return { messages: [...history, ...tail], userMessage };
 }

package/dist/app/report-session-runtime.d.ts

@@ -26,11 +26,17 @@
  * thread and a wrong thread type are permanent, and a store or pin fault is
  * transient. The persist is a compare-and-swap against the prior document that the
  * load read, thus two concurrent turns cannot both land.
+ *
+ * The load serves the stored pin with the derivations of the session merged onto it.
+ * Thus a derived table binds, resolves, and validates the same way as a pinned one.
+ * The stored pin never changes, thus the anchor stays honest and the merge is
+ * recomputable from the row.
  */
 import type { Pool } from "pg";
 import type { Logger } from "../lib/logger.js";
-import { type ReportSessionState as StoredSessionState } from "../state/report-session-state.js";
+import { type ReportSessionState as StoredSessionState, type ReportSessionStateStore } from "../state/report-session-state.js";
 import type { ReportSessionStateGateway } from "../tools/report-authoring/authoring-tools.js";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 /**
  * How a failed anchor ends. `absent-thread` and `wrong-thread-type` are permanent
  * conditions, and `unavailable` is a transient store or pin fault. The gateway load
@@ -52,16 +58,27 @@ export type EnsureSessionStateResult = {
 };
 export interface ReportSessionRuntimeDeps {
     readonly pool: Pool;
+    /**
+     * The workspace-root seam of the pin. The citation evidence of an analysis sits on disk under the
+     * root, thus a composition that binds no seam pins the artifact map alone.
+     */
+    readonly resolveWorkspaceRoot?: ResolveWorkspaceRoot;
     readonly logger?: Logger;
 }
 /**
  * The report session-state runtime. The gateway serves the authoring tools, and
- * `ensureSessionState` anchors the session. The serving path of a report turn runs
- * `ensureSessionState` at the turn start, and the gateway `load` runs it too, thus
- * a tool call cannot arrive before the state exists.
+ * `ensureSessionState` anchors the session. The spawn of a report session runs
+ * `ensureSessionState` at the moment of the spawn, the serving path of a report
+ * turn runs it at the turn start, and the gateway `load` runs it too. Thus a tool
+ * call cannot arrive before the state exists.
  */
 export interface ReportSessionRuntime {
     readonly gateway: ReportSessionStateGateway;
+    /**
+     * The derivation ledger of the session state. The derivation tool appends one record for each
+     * derivation, and the gateway load serves each record as a member of the snapshot.
+     */
+    readonly derivations: Pick<ReportSessionStateStore, "appendDerivation">;
     ensureSessionState(threadId: string): Promise<EnsureSessionStateResult>;
 }
 /**

package/dist/app/report-session-runtime.js

@@ -26,14 +26,47 @@
  * thread and a wrong thread type are permanent, and a store or pin fault is
  * transient. The persist is a compare-and-swap against the prior document that the
  * load read, thus two concurrent turns cannot both land.
+ *
+ * The load serves the stored pin with the derivations of the session merged onto it.
+ * Thus a derived table binds, resolves, and validates the same way as a pinned one.
+ * The stored pin never changes, thus the anchor stays honest and the merge is
+ * recomputable from the row.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
 import { describeDbError } from "../lib/db-result.js";
 import { createThreadStore } from "../memory/thread-store.js";
 import { pinReportSnapshot } from "../report-model/pin-snapshot.js";
-import { createReportSessionStateStore } from "../state/report-session-state.js";
+import { createReportSessionStateStore, } from "../state/report-session-state.js";
 /** The empty draft of a fresh session. The pin writes the snapshot first, thus the document is empty here. */
 const EMPTY_DRAFT = { title: "", sections: [] };
+/**
+ * The served membership: the stored pin, with one entry for each derivation of the session.
+ *
+ * The tools read the served snapshot, thus a derived table binds the same way as a pinned one. The stored
+ * pin stays untouched, thus the merge runs again on each load and the row keeps the evidence of the pin
+ * alone.
+ *
+ * A derived entry carries the output hash alone. A file type states a role of the run ledger, and a
+ * derivation holds none. The map takes a null prototype, the same as the stored parse, thus a path such as
+ * `__proto__` stays an ordinary entry.
+ *
+ * The derivations land last, thus a record whose output path equals a pinned path would shadow the pin. No
+ * such record exists: the derivation tool refuses an output name that the served membership already holds,
+ * and the output path of a derivation sits under the session directory, which the pin never reaches.
+ */
+function serveMembership(snapshot, derivations) {
+    if (derivations.length === 0) {
+        return snapshot;
+    }
+    const artifacts = Object.create(null);
+    for (const [path, entry] of Object.entries(snapshot.artifacts)) {
+        artifacts[path] = entry;
+    }
+    for (const record of derivations) {
+        artifacts[record.outputPath] = { hash: record.outputHash };
+    }
+    return { ...snapshot, artifacts };
+}
 /**
  * Build the report session-state runtime bound to a Postgres pool. The factory
  * closure captures the pool and constructs the session-state store and the thread
@@ -61,12 +94,20 @@ export function createReportSessionRuntime(deps) {
      * Pin the snapshot and write the row. A pin failure writes no row, thus a
      * later run pins again. The write is insert-if-absent, thus two concurrent
      * first runs make one row and both read the winner back.
+     *
+     * The pin takes the workspace-root seam for the citation evidence. An absent
+     * seam pins no citation, thus a citation block of the session resolves against
+     * an empty list. The warning names that condition one time for each session.
      */
     async function pinAndWrite(threadId, analysisId) {
-        const pinned = await pinReportSnapshot(pool, analysisId);
+        if (deps.resolveWorkspaceRoot === undefined) {
+            log.warn("the composition binds no workspace root, thus the pin carries no citation evidence", { threadId, analysisId });
+        }
+        const pinned = await pinReportSnapshot(pool, analysisId, deps.resolveWorkspaceRoot ? { resolveWorkspaceRoot: deps.resolveWorkspaceRoot } : {});
         if (pinned.isErr()) {
-            log.error("the snapshot pin failed", { threadId, analysisId, ...log.errorFields(pinned.error.cause) });
-            return { outcome: "failed", kind: "unavailable", detail: "the artifact ledger read failed" };
+            log.error("the snapshot pin failed", { threadId, analysisId, kind: pinned.error.kind, ...log.errorFields(pinned.error.cause) });
+            const detail = pinned.error.kind === "run-listing-failed" ? "the run listing read failed" : "the artifact ledger read failed";
+            return { outcome: "failed", kind: "unavailable", detail };
         }
         const written = await store.writeSnapshot({ threadId, analysisId, snapshot: pinned.value });
         return written.match((row) => ({ outcome: "ready", state: row }), (error) => storeFault(threadId, error));
@@ -104,6 +145,11 @@ export function createReportSessionRuntime(deps) {
      * no document, thus the load gives the empty draft. The found load carries the
      * stored analysis and the prior document as the concurrency token. A row with no
      * snapshot cannot serve a tool, because the pin writes the snapshot first.
+     *
+     * The served snapshot is the stored pin with the derivations merged onto it, thus a
+     * tool reads one membership and it never merges again. The records ride the load
+     * beside the merged snapshot, because the chain of a derived path and the unused set
+     * both read the record and not the membership.
      */
     function toLoad(state) {
         if (state.snapshot === null) {
@@ -112,10 +158,11 @@ export function createReportSessionRuntime(deps) {
         }
         return {
             outcome: "found",
-            state: { document: state.document ?? EMPTY_DRAFT, snapshot: state.snapshot },
+            state: { document: state.document ?? EMPTY_DRAFT, snapshot: serveMembership(state.snapshot, state.derivations) },
             analysisId: state.analysisId,
             token: state.document,
             seenDocumentHash: state.seenDocumentHash,
+            derivations: state.derivations,
         };
     }
     const gateway = {
@@ -179,5 +226,5 @@ export function createReportSessionRuntime(deps) {
             });
         },
     };
-    return { gateway, ensureSessionState };
+    return { gateway, derivations: store, ensureSessionState };
 }