@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/contracts/schemas/chat-parts.d.ts

@@ -156,6 +156,7 @@ export declare const DagStatePartSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const StepPhaseSchema: z.ZodEnum<{
     failed: "failed";
+    warning: "warning";
     "sandbox-init": "sandbox-init";
     executing: "executing";
     "generating-metadata": "generating-metadata";
@@ -164,7 +165,6 @@ export declare const StepPhaseSchema: z.ZodEnum<{
     persisting: "persisting";
     complete: "complete";
     retrying: "retrying";
-    warning: "warning";
 }>;
 export declare const StepActivityPartSchema: z.ZodObject<{
     type: z.ZodLiteral<"data-step-activity">;
@@ -173,6 +173,7 @@ export declare const StepActivityPartSchema: z.ZodObject<{
     stepId: z.ZodString;
     phase: z.ZodEnum<{
         failed: "failed";
+        warning: "warning";
         "sandbox-init": "sandbox-init";
         executing: "executing";
         "generating-metadata": "generating-metadata";
@@ -181,7 +182,6 @@ export declare const StepActivityPartSchema: z.ZodObject<{
         persisting: "persisting";
         complete: "complete";
         retrying: "retrying";
-        warning: "warning";
     }>;
     activity: z.ZodString;
 }, z.core.$strip>;
@@ -212,11 +212,11 @@ export declare const StepOutputFileSchema: z.ZodObject<{
     size: z.ZodNumber;
     fileType: z.ZodEnum<{
         output: "output";
+        summary: "summary";
         script: "script";
         figure: "figure";
         log: "log";
         notebook: "notebook";
-        summary: "summary";
     }>;
     description: z.ZodString;
 }, z.core.$strip>;
@@ -231,11 +231,11 @@ export declare const StepOutputPartSchema: z.ZodObject<{
         size: z.ZodNumber;
         fileType: z.ZodEnum<{
             output: "output";
+            summary: "summary";
             script: "script";
             figure: "figure";
             log: "log";
             notebook: "notebook";
-            summary: "summary";
         }>;
         description: z.ZodString;
     }, z.core.$strip>>;
@@ -298,11 +298,11 @@ export declare const SynthesizedFindingSchema: z.ZodObject<{
         low: "low";
     }>;
     noveltyStatus: z.ZodEnum<{
-        expected: "expected";
         novel: "novel";
         confirmed: "confirmed";
         partially_confirmed: "partially_confirmed";
         contradicted: "contradicted";
+        expected: "expected";
     }>;
     literatureInterpretation: z.ZodString;
 }, z.core.$strip>;
@@ -330,11 +330,11 @@ export declare const RunSynthesisPartSchema: z.ZodObject<{
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
-            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
+            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
     }, z.core.$strip>>;
@@ -512,6 +512,7 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     stepId: z.ZodString;
     phase: z.ZodEnum<{
         failed: "failed";
+        warning: "warning";
         "sandbox-init": "sandbox-init";
         executing: "executing";
         "generating-metadata": "generating-metadata";
@@ -520,7 +521,6 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         persisting: "persisting";
         complete: "complete";
         retrying: "retrying";
-        warning: "warning";
     }>;
     activity: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -547,11 +547,11 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         size: z.ZodNumber;
         fileType: z.ZodEnum<{
             output: "output";
+            summary: "summary";
             script: "script";
             figure: "figure";
             log: "log";
             notebook: "notebook";
-            summary: "summary";
         }>;
         description: z.ZodString;
     }, z.core.$strip>>;
@@ -589,11 +589,11 @@ export declare const CortexChatPartSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
             low: "low";
         }>;
         noveltyStatus: z.ZodEnum<{
-            expected: "expected";
             novel: "novel";
             confirmed: "confirmed";
             partially_confirmed: "partially_confirmed";
             contradicted: "contradicted";
+            expected: "expected";
         }>;
         literatureInterpretation: z.ZodString;
     }, z.core.$strip>>;

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

@@ -26,8 +26,10 @@ import { runAgent } from "../loop/run-agent.js";
 import { passthroughStep } from "../loop/run-step.js";
 import { defineTool } from "../tools/define-tool.js";
 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";
 /**
@@ -155,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: [] };
     }
@@ -166,7 +169,7 @@ export async function generateFileMetadata(opts) {
     }
     const describer = {
         id: DESCRIBER_AGENT_ID,
-        systemPrompt: SYSTEM_PROMPT,
+        systemPrompt: composeSystemPrompt(SYSTEM_PROMPT),
         model: opts.modelId,
         tools,
         maxIterations: opts.maxIterations ?? DEFAULT_MAX_ITERATIONS,
@@ -182,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 = [];
@@ -197,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;
@@ -72,6 +75,19 @@ export interface EphemeralResult {
  * so the `run_ephemeral` tool can dispatch via `DBOS.startWorkflow`.
  */
 export declare function registerEphemeralWorkflow(deps: EphemeralDeps): (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
+/**
+ * The executor's seed: its workspace frame, then the caller's ask.
+ *
+ * An ephemeral run is not scheduled by `executeAnalysis`, so no step briefing is
+ * composed for it — and the sandbox system prompt names no paths (it is static
+ * per agent type, so the provider's prompt cache can reuse it). The analysis
+ * root would otherwise reach the agent nowhere: `run_ephemeral`'s `prompt` is
+ * free text authored by the conversation agent.
+ *
+ * The frame differs from a step's, so this does not reuse `renderWorkspace`:
+ * there is no writable directory to name. The read-only tree IS the cwd.
+ */
+export declare function ephemeralSeed(analysisId: string, prompt: string): string;
 /**
  * Run the ephemeral-executor agent against a fresh read-only sandbox.
  * Throws on sandbox start failure; otherwise returns the agent's final

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";
 /**
@@ -51,6 +52,28 @@ const EPHEMERAL_SANDBOX_RESOURCES = { cpu: 4, memoryGb: 8 };
 export function registerEphemeralWorkflow(deps) {
     return DBOS.registerWorkflow((input) => runEphemeralBody(input, deps), { name: "ephemeral" });
 }
+/**
+ * The executor's seed: its workspace frame, then the caller's ask.
+ *
+ * An ephemeral run is not scheduled by `executeAnalysis`, so no step briefing is
+ * composed for it — and the sandbox system prompt names no paths (it is static
+ * per agent type, so the provider's prompt cache can reuse it). The analysis
+ * root would otherwise reach the agent nowhere: `run_ephemeral`'s `prompt` is
+ * free text authored by the conversation agent.
+ *
+ * The frame differs from a step's, so this does not reuse `renderWorkspace`:
+ * there is no writable directory to name. The read-only tree IS the cwd.
+ */
+export function ephemeralSeed(analysisId, prompt) {
+    const root = `/${analysisId}`;
+    return [
+        "## Workspace",
+        `- Analysis root (read-only): \`${root}\` — inputs at \`${root}/data/inputs/\`, prior runs at \`${root}/runs/\`.`,
+        `- The analysis root is also your cwd, and what relative paths resolve against. The sandbox is read-only: there is nowhere to write, so return every result inline.`,
+        "",
+        prompt,
+    ].join("\n");
+}
 /**
  * Run the ephemeral-executor agent against a fresh read-only sandbox.
  * Throws on sandbox start failure; otherwise returns the agent's final
@@ -63,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,
@@ -116,7 +142,7 @@ export async function runEphemeralBody(input, deps) {
         const agentDef = createEphemeralExecutorAgent(sandboxAgentDeps);
         const agent = input.maxIterations !== undefined ? { ...agentDef, maxIterations: input.maxIterations } : agentDef;
         const signal = new AbortController().signal;
-        const { messages: finalMessages } = await runAgent(agent, [{ role: "user", content: input.prompt }], childSession, {
+        const { messages: finalMessages } = await runAgent(agent, [{ role: "user", content: ephemeralSeed(analysisId, input.prompt) }], childSession, {
             provider: deps.provider,
             signal,
             emit: () => { },
@@ -126,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 {
@@ -141,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);
         }