@inflexa-ai/harness 0.2.0 → 0.3.0

package/README.md

@@ -37,6 +37,9 @@ import {
     createNoopArtifactRegistry,     // ArtifactRegistry seam
     UnavailablePreviewPublisher,    // PreviewPublisher seam
     createDbosRunLauncher,          // shared RunLauncher
+    createConsoleLogger,            // Logger — writes to console
+    createNoopLogger,               // Logger — discards (the fallback when none is wired)
+    defaultErrorFields,             // the shipped `Logger.errorFields` mapping
     defineTool,
     runAgent,
     makeLocalAuth,
@@ -45,6 +48,51 @@ import {
 
 `assembleCoreRuntime` is the single composition point: it registers the durable workflows and builds the conversation agent over them. The harness declares **five capability seams** an embedder wires — `RunAuthorizer`, `ResolveBilling`, `ArtifactRegistry`, `RunCharge`, `PreviewPublisher` — plus the **shared `RunLauncher`** (one host-neutral realization, `createDbosRunLauncher`). Local, dependency-free realizations of all five ship from the barrel; an embedder constructs them (or its own) and passes them in. The harness only ever sees the interface.
 
+## Logging
+
+The harness names no logging library. It logs through a `Logger` you supply, so the destination, format, and verbosity stay yours:
+
+```ts
+export interface Logger {
+    debug(msg: string, fields?: LogFields): void;
+    info(msg: string, fields?: LogFields): void;
+    warn(msg: string, fields?: LogFields): void;
+    error(msg: string, fields?: LogFields): void;
+    with(fields: LogFields): Logger;        // bind context onto every record (slog's `With`)
+    named(name: string): Logger;            // bind a namespace, rendered as a `[a.b]` message prefix
+    errorFields(err: unknown): LogFields;   // normalize a thrown value; `defaultErrorFields` is the shipped mapping
+}
+```
+
+Pass `createConsoleLogger()` if you have no logging infrastructure. Wire nothing and the harness falls back to `createNoopLogger()` — it never falls back to `console`, because a host whose UI owns stdout (an alternate-screen TUI, say) discards console output, and a diagnostic written to a discarded stream is worse than no diagnostic at all.
+
+`errorFields` is on the interface, not a helper we own, so your realization can defer to your sink's native error handling rather than a shape we imposed.
+
+**Migrating from a version that took a `pino.Logger`** — `bootHarness` and the deps bags now take this interface. pino is object-first where this is message-first, so pass an adapter:
+
+```ts
+import type { LogFields, Logger } from "@inflexa-ai/harness";
+import type pino from "pino";
+
+function pinoAsHarnessLogger(p: pino.Logger, names: readonly string[] = []): Logger {
+    const prefixed = (msg: string): string => (names.length > 0 ? `[${names.join(".")}] ${msg}` : msg);
+    const emit =
+        (level: "debug" | "info" | "warn" | "error") =>
+        (msg: string, fields?: LogFields): void => {
+            p[level](fields ?? {}, prefixed(msg));
+        };
+    return {
+        debug: emit("debug"),
+        info: emit("info"),
+        warn: emit("warn"),
+        error: emit("error"),
+        with: (fields) => pinoAsHarnessLogger(p.child(fields), names),
+        named: (name) => pinoAsHarnessLogger(p, [...names, name]),
+        errorFields: (err) => ({ err }), // let pino's own `err` serializer render it
+    };
+}
+```
+
 ## How it executes
 
 Chat is a plain in-process turn (`prepareChatTurn` → `runAgent` → `appendTurn`); the harness ships no HTTP layer, so the host owns the route. Compute-heavy work runs as **durable workflows** — `executeAnalysis` starts a child workflow per plan step once its dependencies have completed, and each step drives a sandbox agent inside a container. The same `runAgent` primitive runs in both modes; durability and the event sink are injected, so the loop body is identical.

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

@@ -41,10 +41,13 @@ 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 { EphemeralWorkflowInput, EphemeralResult } from "../execution/ephemeral-runner.js";
+import type { Logger } from "../lib/logger.js";
 /** Canonical agent id — the single source of truth. */
 export declare const CONVERSATION_AGENT_ID: "conversation-agent";
 /** The shared dependencies the composition root explodes apart. */
 export interface ConversationAgentDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     /** The LLM seam every loop-driving tool runs its sub-agent on. */
     readonly provider: ChatProvider;
     /** Postgres pool — plan persistence, run inspection, workspace index, working memory. */

package/dist/agents/conversation-agent.js

@@ -32,7 +32,7 @@ import { createWorkingMemory } from "../memory/working-memory.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 // Bio-lookup leaf tools (pure — no dependencies).
-import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, searchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
+import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, createSearchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
 import { createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
 // Dependency-bearing tool factories.
 import { createGeneratePlanTool, createLiteratureReviewerTool, createInspectRunTool, createInspectDataProfileTool, createGenerateAnalogyReportTool, } from "../tools/research/index.js";
@@ -70,7 +70,7 @@ export function createConversationAgent(deps) {
         searchFaersTool,
         searchClinicalTrialsTool,
         searchGeoDatasetsTool,
-        searchDgidbTool,
+        createSearchDgidbTool({ ...(deps.logger ? { logger: deps.logger } : {}) }),
         // Preclinical.
         searchBgeeExpressionTool,
         getImpcKoProfileTool,

package/dist/agents/sandbox/shared.d.ts

@@ -25,6 +25,7 @@ import type { ProvenanceCollector as LineageCollector } from "../../provenance/c
 import { type BioToolKeys } from "../../tools/bio/keys.js";
 import { type BlockerHolder } from "../../tools/sandbox/report-blocker.js";
 import type { AgentMeta, SandboxToolName } from "./types.js";
+import type { Logger } from "../../lib/logger.js";
 /**
  * Tools every sandbox agent receives — sandbox-environment introspection,
  * library docs, and run inspection. Spread into each agent's
@@ -50,6 +51,8 @@ export interface SandboxStepCoords {
 }
 /** The shared dependency graph every sandbox agent draws from. */
 export interface SandboxAgentDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Pool;
     readonly sandboxClient: SandboxClient;

package/dist/agents/sandbox/shared.js

@@ -26,7 +26,7 @@ import { createInspectRunTool } from "../../tools/research/inspect-run.js";
 // Data-profile retrieval (dependency-bearing) — always-on, see `createSandboxAgent`.
 import { createInspectDataProfileTool } from "../../tools/research/inspect-data-profile.js";
 // Bio leaf tools.
-import { checkSafetyPanelTool, chemblTool, getImpcKoProfileTool, lookupGoTermTool, openTargetsTool, pubchemTool, searchBgeeExpressionTool, searchClinicalTrialsTool, searchDgidbTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchGwasCatalogTool, searchInteractionsTool, searchPathwayTool, searchPharmgkbTool, } from "../../tools/bio/index.js";
+import { checkSafetyPanelTool, chemblTool, getImpcKoProfileTool, lookupGoTermTool, openTargetsTool, pubchemTool, searchBgeeExpressionTool, searchClinicalTrialsTool, createSearchDgidbTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchGwasCatalogTool, searchInteractionsTool, searchPathwayTool, searchPharmgkbTool, } from "../../tools/bio/index.js";
 import { createNcbiTools, createChemDbTools } from "../../tools/bio/keys.js";
 // Workspace read surface.
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../../tools/workspace/index.js";
@@ -80,7 +80,7 @@ function resolveSandboxTools(deps, tools) {
         searchClinicalTrials: searchClinicalTrialsTool,
         searchGeoDatasets: searchGeoDatasetsTool,
         searchClinvar: ncbi.searchClinvar,
-        searchDgidb: searchDgidbTool,
+        searchDgidb: createSearchDgidbTool({ ...(deps.logger ? { logger: deps.logger } : {}) }),
         searchGwasCatalog: searchGwasCatalogTool,
         searchDisgenet: chemDb.searchDisgenet,
         searchDrugbank: chemDb.searchDrugbank,

package/dist/app/chat-turn.d.ts

@@ -14,7 +14,10 @@
  */
 import type { Pool } from "pg";
 import { type AssembledMessages } from "./message-assembly.js";
+import type { Logger } from "../lib/logger.js";
 export interface PrepareChatTurnDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
 }
 export interface PrepareChatTurnParams {

package/dist/app/chat-turn.js

@@ -19,6 +19,7 @@ import { createThreadStore } from "../memory/thread-store.js";
 import { createWorkingMemory } from "../memory/working-memory.js";
 import { loadAnalysisStatus } from "../state/index.js";
 import { assembleMessages } from "./message-assembly.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 /**
  * Prepare one chat turn: resolve thread ownership, seed the title, load
  * analysis status, and assemble the message array. Input sanitization stays
@@ -48,7 +49,8 @@ export async function prepareChatTurn(deps, params) {
         }
     }
     catch (err) {
-        console.warn("[harness.chat] title-seed failed (non-fatal):", err instanceof Error ? err.message : err);
+        const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+        logger.warn("title-seed failed (non-fatal)", logger.errorFields(err));
     }
     const analysisState = await loadAnalysisStatus(pool, analysisId).unwrapOr(null);
     const history = createThreadHistory(pool);

package/dist/app/synthesize-run.d.ts

@@ -22,7 +22,10 @@ import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { RunFinding } from "../workflows/execute-analysis.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { Logger } from "../lib/logger.js";
 export interface SynthesizeRunDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
     readonly provider: ChatProvider;
     /** Write-side embedder — its `dimensions` sizes the per-analysis index. */

package/dist/app/synthesize-run.js

@@ -20,6 +20,7 @@ import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.j
 import { createVectorStore } from "../state/vector-store.js";
 import { loadPlan, queryRun } from "../state/index.js";
 import { unwrapOrThrow } from "../lib/result.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 export async function synthesizeRun(deps, params) {
     const { pool, provider, embedding, resolveWorkspaceRoot, synthesisModel, bioKeys } = deps;
     const { analysisId, runId, completedSteps, session, emit, onProgress } = params;
@@ -71,7 +72,8 @@ export async function synthesizeRun(deps, params) {
             }));
         }
         catch (indexErr) {
-            console.warn(`[synthesize-run] vector indexing failed for run ${runId}:`, indexErr instanceof Error ? indexErr.message : indexErr);
+            const logger = (deps.logger ?? createNoopLogger()).named("synthesize-run");
+            logger.warn("vector indexing failed", { runId, ...logger.errorFields(indexErr) });
         }
         await onProgress("persisting", "Persisting synthesis");
         await persistSynthesis({ workspaceRoot, runId, synthesis });

package/dist/execution/artifact-metadata.d.ts

@@ -24,6 +24,7 @@ import type { AgentSession } from "../auth/types.js";
 import type { LoopMessage } from "../loop/types.js";
 import type { AgentChat } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
+import type { Logger } from "../lib/logger.js";
 export interface ArtifactForMetadata {
     /** Path used to update `cortex_artifacts` after metadata generation. */
     readonly dbPath: string;
@@ -33,6 +34,8 @@ export interface ArtifactForMetadata {
     readonly sizeBytes?: number;
 }
 export interface GenerateFileMetadataOptions {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: AgentChat;
     readonly session: AgentSession;
     readonly artifacts: readonly ArtifactForMetadata[];

package/dist/execution/artifact-metadata.js

@@ -29,6 +29,7 @@ import { createReadFileTool } from "../tools/workspace/read-file.js";
 import { composeSystemPrompt } from "../agents/system-prompt.js";
 import { inferArtifactType } from "../schemas/artifact-manifest.js";
 import { SubmitFileMetadataInputSchema } from "../schemas/file-metadata.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 /** Sub-agent identity for the describer loop — provenance only. */
 const DESCRIBER_AGENT_ID = "file-metadata-describer";
 /**
@@ -156,6 +157,7 @@ function fallbackEntry(artifact, extra) {
  * result always carries exactly one entry per input artifact.
  */
 export async function generateFileMetadata(opts) {
+    const logger = (opts.logger ?? createNoopLogger()).named("artifact-metadata").with({ resourceId: opts.resourceId });
     if (opts.artifacts.length === 0) {
         return { indexed: 0, entries: [] };
     }
@@ -183,7 +185,7 @@ export async function generateFileMetadata(opts) {
         });
     }
     catch (err) {
-        console.warn(`[artifact-metadata] describer loop failed (resource=${opts.resourceId}); using fallbacks: ${err instanceof Error ? err.message : err}`);
+        logger.warn("describer loop failed; using fallbacks", logger.errorFields(err));
     }
     const entries = [];
     const fallbackPaths = [];
@@ -198,7 +200,11 @@ export async function generateFileMetadata(opts) {
         }
     }
     if (fallbackPaths.length > 0) {
-        console.warn(`[artifact-metadata] ${fallbackPaths.length}/${opts.artifacts.length} file(s) used a deterministic fallback description (resource=${opts.resourceId}): ${fallbackPaths.join(", ")}`);
+        logger.warn("file(s) used a deterministic fallback description", {
+            fallbackCount: fallbackPaths.length,
+            artifactCount: opts.artifacts.length,
+            fallbackPaths,
+        });
     }
     return { indexed: holder.size, entries };
 }

package/dist/execution/artifact-registration.d.ts

@@ -11,6 +11,7 @@
  */
 import type { Pool, PoolClient } from "pg";
 import type { AgentSession } from "../auth/types.js";
+import type { Logger } from "../lib/logger.js";
 import type { ArtifactRegistry, ArtifactRegistrationInput } from "./artifact-registry.js";
 export type { ArtifactRegistrationInput };
 export interface ArtifactRegistrationResult {
@@ -33,4 +34,4 @@ export interface ArtifactRegistrationResult {
  * delegates external provenance registration to the injected `ArtifactRegistry`
  * and applies any returned external ids back onto the local rows.
  */
-export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession): Promise<ArtifactRegistrationResult>;
+export declare function registerStepArtifacts(db: Pool | PoolClient, registry: ArtifactRegistry, input: ArtifactRegistrationInput, session: AgentSession, logger?: Logger): Promise<ArtifactRegistrationResult>;

package/dist/execution/artifact-registration.js

@@ -9,6 +9,7 @@
  * (an external provenance ledger, or a filesystem index) is a composition-root
  * decision — this module never names one.
  */
+import { createNoopLogger } from "../lib/console-logger.js";
 import { upsertArtifacts, updateArtifactId } from "../state/index.js";
 // ── Registration ─────────────────────────────────────────────────────
 /**
@@ -18,8 +19,13 @@ import { upsertArtifacts, updateArtifactId } from "../state/index.js";
  * delegates external provenance registration to the injected `ArtifactRegistry`
  * and applies any returned external ids back onto the local rows.
  */
-export async function registerStepArtifacts(db, registry, input, session) {
+export async function registerStepArtifacts(db, registry, input, session, 
+// A parameter rather than a field on `ArtifactRegistrationInput`: that type is
+// the seam's payload, handed verbatim to `registry.register`, and an
+// embedder's registry has no business receiving the host's logger.
+logger = createNoopLogger()) {
     const { resourceId, runId, stepId, artifacts } = input;
+    const log = logger.named("artifact-registration").with({ runId, stepId });
     if (artifacts.length === 0) {
         return { localCount: 0, externalRegistered: 0, externalFailed: 0, failureDetails: [] };
     }
@@ -27,7 +33,7 @@ export async function registerStepArtifacts(db, registry, input, session) {
     const emptyHash = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
     const localEntries = artifacts.map((a) => {
         if (a.size === 0 || a.hash === emptyHash) {
-            console.warn(`[artifact-registration] empty artifact: path=${dbPathPrefix}${a.path} hash=${a.hash?.slice(0, 16)} size=${a.size} runId=${runId} stepId=${stepId}`);
+            log.warn("empty artifact", { path: `${dbPathPrefix}${a.path}`, hash: a.hash?.slice(0, 16), size: a.size });
         }
         return {
             resourceId,

package/dist/execution/ephemeral-runner.d.ts

@@ -29,12 +29,15 @@ import type { SandboxClient } from "../sandbox/client.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { Logger } from "../lib/logger.js";
 /** Sub-agent identity — appended to `callPath`, set as `agentId`. */
 export declare const EPHEMERAL_AGENT_ID = "ephemeral-executor";
 /** Workflow-id prefix — the boot-time never-recover sweep matches on it. */
 export declare const EPHEMERAL_WORKFLOW_PREFIX: "ephemeral:";
 /** The body's construction-time deps — closed over at registration. */
 export interface EphemeralDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Pool;
     readonly sandboxClient: SandboxClient;

package/dist/execution/ephemeral-runner.js

@@ -28,6 +28,7 @@ import { durableStep } from "../loop/run-step.js";
 import { generateExecutionId } from "../sandbox/execution-id.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
 import { createEphemeralExecutorAgent } from "../agents/sandbox/ephemeral-executor.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 /** Sub-agent identity — appended to `callPath`, set as `agentId`. */
 export const EPHEMERAL_AGENT_ID = "ephemeral-executor";
 /**
@@ -85,13 +86,16 @@ export async function runEphemeralBody(input, deps) {
         throw new Error(`runEphemeralBody requires an analysis-scoped session — got ${runSession.scope.kind}`);
     }
     const analysisId = runSession.scope.analysisId;
+    // Bound after the scope guard: `analysisId` comes off the session's scope,
+    // not the workflow input.
+    const logger = (deps.logger ?? createNoopLogger()).named("ephemeral").with({ analysisId });
     const startedAt = performance.now();
     const executionId = generateExecutionId(EPHEMERAL_AGENT_ID);
     const workflowId = DBOS.workflowID ?? `${EPHEMERAL_WORKFLOW_PREFIX}${executionId}`;
     const childSession = forSubAgent(runSession, EPHEMERAL_AGENT_ID);
     // Resolver throw = loud workflow failure, per the workspace-root-resolution contract.
     const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
-    console.log(`[ephemeral] execution=${executionId} analysis=${analysisId} starting sandbox`);
+    logger.info("starting sandbox", { executionId });
     const sandbox = await deps.sandboxClient.createSandbox({
         runId: EPHEMERAL_RUN_LITERAL,
         stepId: EPHEMERAL_RUN_LITERAL,
@@ -148,12 +152,12 @@ export async function runEphemeralBody(input, deps) {
         const text = finalText(finalMessages);
         const stepsUsed = countAssistantTurns(finalMessages);
         const durationMs = Math.round(performance.now() - startedAt);
-        console.log(`[ephemeral] execution=${executionId} completed stepsUsed=${stepsUsed} durationMs=${durationMs}`);
+        logger.info("completed", { executionId, stepsUsed, durationMs });
         return { text, stepsUsed, durationMs };
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        console.error(`[ephemeral] execution=${executionId} failed: ${message}`);
+        logger.error("failed", { executionId, err: message });
         throw err;
     }
     finally {
@@ -163,7 +167,7 @@ export async function runEphemeralBody(input, deps) {
         catch (teardownErr) {
             // Teardown is idempotent — "already gone" is success. A failure here
             // is best-effort logged so the chat turn doesn't fail on cleanup.
-            console.warn(`[ephemeral] execution=${executionId} teardown failed (non-fatal): ${teardownErr instanceof Error ? teardownErr.message : teardownErr}`);
+            logger.warn("teardown failed (non-fatal)", { executionId, ...logger.errorFields(teardownErr) });
         }
     }
 }

package/dist/execution/post-step-pipeline.d.ts

@@ -16,6 +16,7 @@ import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { StepSummary } from "../schemas/step-summary.js";
+import type { Logger } from "../lib/logger.js";
 import type { ArtifactRegistry } from "./artifact-registry.js";
 import { type FileMetadataEntry } from "./artifact-metadata.js";
 import type { PostStepArtifacts, PostStepContext, StepOutputs } from "../workflows/sandbox-step.js";
@@ -25,6 +26,8 @@ import type { PostStepArtifacts, PostStepContext, StepOutputs } from "../workflo
  */
 export interface PostStepPipelineDeps {
     readonly pool: Pool;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     /** Non-streaming chat — the metadata + summary sub-agent loops. */
     readonly provider: AgentChat;
     /** Write-side embedder for the vector index. */

package/dist/execution/post-step-pipeline.js

@@ -12,6 +12,7 @@
  */
 import { join } from "node:path";
 import { unwrapOrThrow } from "../lib/result.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { writeFileWithinRoot } from "../lib/fs-helpers.js";
 import { registerStepArtifacts } from "./artifact-registration.js";
 import { reconcileManifestWithDisk } from "./reconcile-manifest.js";
@@ -79,7 +80,12 @@ export async function generateStepSummaryAndWrite(deps, postCtx, manifest) {
             await writeFileWithinRoot(writePrefix, join(writePrefix, "output", "summary.md"), summary.markdown);
         }
         catch (err) {
-            console.warn(`[post-step.summary] writeFile output/summary.md failed for ${input.stepId}: ${err instanceof Error ? err.message : err}`);
+            const logger = (deps.logger ?? createNoopLogger()).named("post-step").named("summary");
+            logger.warn("writeFile output/summary.md failed", {
+                runId: input.runId,
+                stepId: input.stepId,
+                ...logger.errorFields(err),
+            });
         }
     }
     return summary;
@@ -102,6 +108,7 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
         agentId: input.agentId,
         manifest: [...manifest],
         collector: lineageCollector,
+        ...(deps.logger ? { logger: deps.logger } : {}),
     });
     if (reconciled.manifest.length === 0)
         return reconciled.manifest;
@@ -111,7 +118,7 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
         stepId: input.stepId,
         artifacts: reconciled.manifest,
         collector: lineageCollector,
-    }, session);
+    }, session, deps.logger);
     if (reg.externalFailed > 0) {
         const wholeActivityFailed = reg.externalRegistered === 0;
         const detail = reg.failureDetails.map((f) => `${f.path}: ${f.error}`).join("\n  ");
@@ -119,7 +126,19 @@ export async function reconcileAndRegisterStepArtifacts(deps, postCtx, manifest)
             `${reg.externalFailed} row(s) rejected, ${reg.externalRegistered}/${reg.localCount} local artifact(s) registered` +
             (wholeActivityFailed ? " (WHOLE ACTIVITY ROLLED BACK — outputs orphaned)" : "") +
             (detail ? `\n  ${detail}` : "");
-        console.error(msg);
+        // Logged as fields as well as thrown: the throw reaches `failStep` as one
+        // opaque string, so the per-path rejections are only queryable from here.
+        // This is what distinguishes a registry rejection from the attestation
+        // throws in `reconcileManifestWithDisk` when a step dies.
+        (deps.logger ?? createNoopLogger()).named("post-step").named("reconcile").error("external registration failed", {
+            runId: input.runId,
+            stepId: input.stepId,
+            externalFailed: reg.externalFailed,
+            externalRegistered: reg.externalRegistered,
+            localCount: reg.localCount,
+            wholeActivityFailed,
+            failures: reg.failureDetails,
+        });
         throw new Error(msg);
     }
     return reconciled.manifest;
@@ -176,7 +195,8 @@ export async function vectorIndexStepOutputs(deps, postCtx, artifacts) {
         }
     }
     catch (err) {
-        console.warn(`[post-step.vector-index] indexing failed for ${input.stepId}: ${err instanceof Error ? err.message : err}`);
+        const logger = (deps.logger ?? createNoopLogger()).named("post-step").named("vector-index");
+        logger.warn("indexing failed", { runId: input.runId, stepId: input.stepId, ...logger.errorFields(err) });
     }
 }
 /**

package/dist/execution/reconcile-manifest.d.ts

@@ -1,5 +1,6 @@
 import type { ArtifactManifestEntry } from "../schemas/artifact-manifest.js";
 import type { ProvenanceCollector } from "../provenance/collector.js";
+import type { Logger } from "../lib/logger.js";
 export interface ReconcileManifestInput {
     /** Absolute host root of the analysis's workspace tree. */
     workspaceRoot: string;
@@ -15,6 +16,12 @@ export interface ReconcileManifestInput {
     manifest: ArtifactManifestEntry[];
     /** Collector backing the manifest; mutated to reflect drops/rehashes. */
     collector: ProvenanceCollector;
+    /**
+     * Operational logging seam; omitted falls back to no-op. Attestation is
+     * fail-fast, so what this records — which entry was dropped, which input
+     * could not be hashed — is the account of why a step died.
+     */
+    logger?: Logger;
 }
 export interface ReconcileManifestResult {
     /** Reconciled manifest — phantoms removed, every entry rehashed from disk. */

package/dist/execution/reconcile-manifest.js

@@ -21,10 +21,12 @@
  */
 import { stat } from "node:fs/promises";
 import path from "node:path";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { computeSha256File, hasValidContentHash } from "../lib/fs-helpers.js";
 import { artifactReconcileDropped } from "../lib/metrics.js";
 export async function reconcileManifestWithDisk(input) {
     const { workspaceRoot, resourceId, runId, stepId, agentId, manifest, collector } = input;
+    const logger = (input.logger ?? createNoopLogger()).named("reconcile-manifest").with({ runId, stepId, agentId });
     const stepRoot = path.join(workspaceRoot, "runs", runId, stepId);
     const reconciled = [];
     let droppedCount = 0;
@@ -36,7 +38,7 @@ export async function reconcileManifestWithDisk(input) {
         // ENOENT and silently drop a real artifact, or — worse — succeed
         // against a host file the step never produced.
         if (!absPath.startsWith(stepRoot + path.sep) && absPath !== stepRoot) {
-            console.warn(`[reconcile-manifest] skipping out-of-bounds path=${entry.path} stepId=${stepId} runId=${runId}`);
+            logger.warn("skipping out-of-bounds entry", { path: entry.path });
             continue;
         }
         let info;
@@ -45,7 +47,7 @@ export async function reconcileManifestWithDisk(input) {
         }
         catch (err) {
             if (err.code === "ENOENT") {
-                console.debug(`[reconcile-manifest] dropping phantom path=${entry.path} stepId=${stepId} runId=${runId}`);
+                logger.debug("dropping phantom entry", { path: entry.path });
                 collector.removeRecord(entry.path);
                 droppedCount++;
                 artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
@@ -58,7 +60,7 @@ export async function reconcileManifestWithDisk(input) {
         // uses `createReadStream`, which throws `EISDIR` on directories and would
         // fail the whole step's reconciliation.
         if (!info.isFile()) {
-            console.debug(`[reconcile-manifest] dropping non-file path=${entry.path} stepId=${stepId} runId=${runId}`);
+            logger.debug("dropping non-file entry", { path: entry.path });
             collector.removeRecord(entry.path);
             droppedCount++;
             artifactReconcileDropped.add(1, { agent_id: agentId, step_id: stepId });
@@ -72,7 +74,7 @@ export async function reconcileManifestWithDisk(input) {
         const hash = await computeSha256File(absPath);
         reconciled.push({ ...entry, hash, size: info.size });
     }
-    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId);
+    await fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, logger);
     return { manifest: reconciled, droppedCount };
 }
 /**
@@ -88,22 +90,31 @@ export async function reconcileManifestWithDisk(input) {
  * Lineage attestation is fail-fast: an input we cannot hash (gone, or resolving
  * outside the analysis tree) throws rather than registering a hashless edge.
  */
-async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId) {
+async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, runId, stepId, logger) {
     const resourceRoot = path.resolve(workspaceRoot);
     for (const ref of collector.getTrackedInputs()) {
         if (ref.source === "artifacts")
             continue;
         if (hasValidContentHash(ref.hash))
             continue;
+        // Each throw below is logged before it is raised. The thrown message reaches
+        // `failStep` as one opaque string and everything downstream of that is
+        // scrubbed, so naming the site and the offending ref HERE is what makes a
+        // fail-fast attestation distinguishable from a registry rejection after the
+        // fact — the read's `source` in particular says whether the step declared
+        // this input at all.
+        const attestation = { path: ref.path, source: ref.source, refRunId: ref.runId, refStepId: ref.stepId };
         // `ref.path` is the absolute container path `/{resourceId}/...`; strip the
         // mount segment and map the tail onto the host workspace root. `path.join`
         // normalizes any `..`, and the bound confines the read to the analysis tree.
         const containerPrefix = `/${resourceId}`;
         if (ref.path !== containerPrefix && !ref.path.startsWith(containerPrefix + "/")) {
+            logger.error("input read resolves outside the analysis tree", { ...attestation, throwSite: "container-prefix-bound" });
             throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
         }
         const hostPath = path.join(resourceRoot, ref.path.slice(containerPrefix.length + 1));
         if (hostPath !== resourceRoot && !hostPath.startsWith(resourceRoot + path.sep)) {
+            logger.error("input read resolves outside the analysis tree", { ...attestation, hostPath, throwSite: "workspace-root-bound" });
             throw new Error(`[reconcile-manifest] input read resolves outside the analysis tree: path=${ref.path} stepId=${stepId} runId=${runId}`);
         }
         let info;
@@ -112,10 +123,12 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
         }
         catch (err) {
             if (err.code === "ENOENT") {
+                logger.error("cannot attest input — not present at reconcile", { ...attestation, hostPath, throwSite: "input-enoent" });
                 throw new Error(`[reconcile-manifest] cannot attest input ${ref.path}: not present at reconcile (stepId=${stepId} runId=${runId})`, {
                     cause: err,
                 });
             }
+            logger.error("cannot attest input — stat failed", { ...attestation, hostPath, throwSite: "input-stat", ...logger.errorFields(err) });
             throw err;
         }
         if (!info.isFile()) {
@@ -124,6 +137,7 @@ async function fillInputHashesFromDisk(collector, workspaceRoot, resourceId, run
             // it from lineage rather than failing the step — mirrors the output-side
             // non-file drop above. A genuinely missing FILE (ENOENT) still fails fast
             // as drift; a directory is not drift.
+            logger.debug("dropping non-file input from lineage", attestation);
             collector.dropInput(ref);
             continue;
         }

package/dist/execution/report-runner.d.ts

@@ -37,7 +37,10 @@ import type { EmitFn } from "../loop/types.js";
 import type { ChatProvider } from "../providers/types.js";
 import type { PreviewPublisher } from "../tools/report/preview-publisher.js";
 import type { ChromeConfig } from "../lib/chrome.js";
+import type { Logger } from "../lib/logger.js";
 export interface ReportRunnerDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Pool;
     /** Model id — provenance / metric label; provider owns the wire model. */

package/dist/execution/report-runner.js

@@ -41,10 +41,12 @@ import { withPreviewLock } from "../tools/lib/preview-lock.js";
 import { createBuildReportTool, createSubmitReportTool, createMintPreviewUrlTool, createPreviewSnapshotTool, createVersionFsTools, } from "../tools/report/index.js";
 import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID } from "../agents/report-builder.js";
 import { createSkillTools } from "../tools/sandbox/skills.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 /** Skill pack the report-builder prompt directs the model to read (design-system reference). */
 const REPORT_BUILDER_SKILLS = ["report-html"];
 const REPORT_AGENT_MAX_STEPS = 75;
 export async function runReportIteration(deps, opts) {
+    const logger = (deps.logger ?? createNoopLogger()).named("report-runner").with({ previewId: opts.previewId });
     const startTime = performance.now();
     return withPreviewLock(opts.previewId, async () => {
         // ── Resolve version directories ───────────────────────────────
@@ -169,9 +171,7 @@ export async function runReportIteration(deps, opts) {
             }
         }
         if (!outcome || agentError || phantomSuccess) {
-            console.warn(`[report-runner] event=report.agent.finish preview=${opts.previewId} v${newVersion} ` +
-                `submitted=${outcome?.ok === true} phantom=${phantomSuccess} ` +
-                `agentError=${agentError ?? "null"}`);
+            logger.warn("report.agent.finish", { version: newVersion, submitted: outcome?.ok === true, phantom: phantomSuccess, agentError });
             const { reason, errorKind } = classifyFailure({
                 phantomSuccess,
                 agentError,
@@ -182,7 +182,7 @@ export async function runReportIteration(deps, opts) {
                 await rm(versionDirAbs, { recursive: true, force: true });
             }
             catch (err) {
-                console.error(`[report-runner] rollback failed for ${versionDirAbs}:`, err instanceof Error ? err.message : err);
+                logger.error("rollback failed", { versionDirAbs, ...logger.errorFields(err) });
             }
             return failure(opts.previewId, newVersion, reason, errorKind, startTime);
         }

package/dist/execution/step-summary.d.ts

@@ -29,7 +29,10 @@ import type { LoopMessage } from "../loop/types.js";
 import type { AgentChat } from "../providers/types.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
 import { type StepSummary } from "../schemas/step-summary.js";
+import type { Logger } from "../lib/logger.js";
 export interface GenerateStepSummaryOptions {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: AgentChat;
     readonly session: AgentSession;
     readonly modelId: string;