@inflexa-ai/harness 0.2.0 → 0.3.0

package/dist/workflows/sandbox-step.js

@@ -28,6 +28,7 @@
  */
 import { DBOS, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { insertStepExecution, updateStepExecution } from "../state/index.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { isBudgetExceeded } from "../loop/budget-exceeded.js";
 import { runAgent } from "../loop/run-agent.js";
@@ -101,6 +102,14 @@ export function registerSandboxStep(deps) {
  * (the DBOS calls inside still rely on a workflow context being present).
  */
 async function runSandboxStepBody(input, deps) {
+    // Step coordinates bind once — every record below carries them without each
+    // call site restating them. REPLAY: a recovered workflow re-executes this body
+    // and re-emits its records, so a reader dedups by (runId, stepId), not by count.
+    const logger = (deps.logger ?? createNoopLogger()).named("sandbox-step").with({
+        runId: input.runId,
+        stepId: input.stepId,
+        agentId: input.agentId,
+    });
     const childWorkflowId = DBOS.workflowID ?? `${input.runId}-${input.stepId}`;
     // Checkpointed so the value (and every `durationMs` derived from it) replays
     // identically — a raw `Date.now()` in the workflow body drifts on recovery.
@@ -206,7 +215,7 @@ async function runSandboxStepBody(input, deps) {
             await emitToParentStream(part);
         }
         catch (err) {
-            console.warn(`[sandbox-step] emitToParentStream failed (non-fatal):`, err instanceof Error ? err.message : err);
+            logger.warn("emitToParentStream failed (non-fatal)", logger.errorFields(err));
         }
     };
     // Schema-conformant step-activity emitter — stable id per (runId, stepId)
@@ -230,10 +239,15 @@ async function runSandboxStepBody(input, deps) {
     const failStep = async (errorClass, err) => {
         if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
             throw err;
-        await tryTeardown(deps, sandbox);
+        await tryTeardown(logger, deps, sandbox);
         const durationMs = (await DBOS.now()) - startedAt;
-        const detail = err instanceof Error ? (err.stack ?? err.message) : String(err);
-        console.error(`[sandbox-step] ${errorClass} failure for ${input.runId}/${input.stepId}: ${detail}`);
+        // The scrub below is deliberate and load-bearing, which makes this record
+        // the ONLY account of why the step died — the thrown error carries just the
+        // generic phrase, so nothing downstream can reconstruct the cause.
+        logger.error("step failure", {
+            errorClass,
+            ...logger.errorFields(err),
+        });
         const safe = userFacingStepFailure(errorClass);
         await DBOS.runStep(async () => {
             unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
@@ -334,7 +348,9 @@ async function runSandboxStepBody(input, deps) {
                 await DBOS.runStep(() => DBOS.send(input.parentWorkflowId, notification, BUDGET_EXCEEDED_TOPIC), { name: "notify-parent-budget-exceeded" });
             }
             catch (sendErr) {
-                console.warn(`[sandbox-step] notify-parent-budget-exceeded failed (non-fatal): ${sendErr instanceof Error ? sendErr.message : sendErr}`);
+                logger.warn("notify-parent-budget-exceeded failed (non-fatal)", {
+                    ...logger.errorFields(sendErr),
+                });
             }
             // Self-cancel to CANCELLED so the parent's `getResult` observes the
             // cancellation and triggers the 402 pause cascade. ERROR is NOT
@@ -369,7 +385,7 @@ async function runSandboxStepBody(input, deps) {
     // terminal-failure status so the parent's fail-fast cascade fires.
     const blockerOutcome = blockerHolder.outcome;
     if (blockerOutcome) {
-        await tryTeardown(deps, sandbox);
+        await tryTeardown(logger, deps, sandbox);
         const durationMs = (await DBOS.now()) - startedAt;
         await DBOS.runStep(async () => {
             unwrapOrThrow(await updateStepExecution(deps.pool, input.runId, input.stepId, {
@@ -413,7 +429,7 @@ async function runSandboxStepBody(input, deps) {
         lineageCollector,
     };
     await emitActivity("generating-metadata", "Describing output files");
-    const manifest = await safeRunValue(() => walkStepArtifacts({
+    const manifest = await safeRunValue(logger, () => walkStepArtifacts({
         writePrefix,
         stepId: input.stepId,
         runId: input.runId,
@@ -423,11 +439,11 @@ async function runSandboxStepBody(input, deps) {
     // gate (`data-step-summary`, file-tree) stay replay-stable and the billed
     // LLM calls are not re-issued on recovery. The remaining stages (walk /
     // reconcile / sync / index) stay inline — a separate follow-up.
-    const metadataEntries = await safeRunValue(() => DBOS.runStep(() => generateStepFileMetadata(deps, postCtx, manifest), {
+    const metadataEntries = await safeRunValue(logger, () => DBOS.runStep(() => generateStepFileMetadata(deps, postCtx, manifest), {
         name: "post-step.generate-file-metadata",
     }), "post-step.metadata", []);
     await emitActivity("generating-summary", "Summarizing step results");
-    const summary = await safeRunValue(() => DBOS.runStep(() => generateStepSummaryAndWrite(deps, postCtx, manifest), {
+    const summary = await safeRunValue(logger, () => DBOS.runStep(() => generateStepSummaryAndWrite(deps, postCtx, manifest), {
         name: "post-step.generate-step-summary",
     }), "post-step.summary", undefined);
     // Lineage attestation (registration + sync) is fail-fast (see the artifact-manifest spec): unlike
@@ -459,10 +475,10 @@ async function runSandboxStepBody(input, deps) {
         stepOutputs = collectStepOutputs(postCtx, postArtifacts);
     }
     catch (err) {
-        console.warn(`[sandbox-step] post-step.collect failed (non-fatal):`, err instanceof Error ? err.message : err);
+        logger.warn("post-step.collect failed (non-fatal)", logger.errorFields(err));
     }
     await emitActivity("indexing", "Indexing outputs for search");
-    await safeRun(() => vectorIndexStepOutputs(deps, postCtx, postArtifacts), "post-step.vector-index");
+    await safeRun(logger, () => vectorIndexStepOutputs(deps, postCtx, postArtifacts), "post-step.vector-index");
     // (9) teardown — destroy sandbox + clear sandbox_ref.
     await DBOS.runStep(() => deps.sandboxClient.teardown(sandbox), { name: "sandbox.teardown" });
     // (10) mark-terminal + emit.
@@ -537,14 +553,17 @@ async function runSandboxStepBody(input, deps) {
  * swallows non-fatal failures — these are reflected in the step summary
  * but do not fail the step itself (synthesis/sync/index can be retried).
  */
-async function safeRun(fn, label) {
+async function safeRun(logger, fn, label) {
     try {
         await fn();
     }
     catch (err) {
         if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
             throw err;
-        console.warn(`[sandbox-step] ${label} failed (non-fatal):`, err instanceof Error ? err.message : err);
+        // The stage rides as a namespace, not interpolated prose: `label` is what
+        // says WHICH post-step stage degraded, and a reader must be able to filter
+        // on it without parsing the message.
+        logger.named(label).warn("failed (non-fatal)", logger.errorFields(err));
     }
 }
 /**
@@ -552,22 +571,25 @@ async function safeRun(fn, label) {
  * logs and yields `fallback` so the body can thread a safe default downstream
  * instead of aborting the post-step pipeline.
  */
-async function safeRunValue(fn, label, fallback) {
+async function safeRunValue(logger, fn, label, fallback) {
     try {
         return await fn();
     }
     catch (err) {
         if (err instanceof DBOSErrors.DBOSWorkflowCancelledError)
             throw err;
-        console.warn(`[sandbox-step] ${label} failed (non-fatal):`, err instanceof Error ? err.message : err);
+        // The stage rides as a namespace, not interpolated prose: `label` is what
+        // says WHICH post-step stage degraded, and a reader must be able to filter
+        // on it without parsing the message.
+        logger.named(label).warn("failed (non-fatal)", logger.errorFields(err));
         return fallback;
     }
 }
-async function tryTeardown(deps, sandbox) {
+async function tryTeardown(logger, deps, sandbox) {
     try {
         await DBOS.runStep(() => deps.sandboxClient.teardown(sandbox), { name: "sandbox.teardown" });
     }
     catch (err) {
-        console.warn(`[sandbox-step] teardown failed (non-fatal):`, err instanceof Error ? err.message : err);
+        logger.warn("teardown failed (non-fatal)", logger.errorFields(err));
     }
 }

package/dist/workflows/target-assessment/lib/llm-step.d.ts

@@ -23,6 +23,7 @@
  * the caller bumps the attempt counter so the resumed call lands a fresh
  * DBOS cache slot rather than replaying the cancelled prior attempt.
  */
+import type { Logger } from "../../../lib/logger.js";
 import type { AgentChat, ChatRequest, ChatResponse } from "../../../providers/types.js";
 import type { AgentSession } from "../../../auth/types.js";
 /**
@@ -38,6 +39,8 @@ export interface BudgetExceededMarker {
     readonly error: string;
 }
 export interface RunLlmStepOptions {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     /** Durable-step name — already attempt-numbered by the caller. */
     readonly stepName: string;
     /** Agent id stamped in the marker for telemetry. */

package/dist/workflows/target-assessment/lib/llm-step.js

@@ -24,6 +24,7 @@
  * DBOS cache slot rather than replaying the cancelled prior attempt.
  */
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { createNoopLogger } from "../../../lib/console-logger.js";
 import { unwrapOrThrow } from "../../../lib/result.js";
 import { isBudgetExceeded } from "../../../loop/budget-exceeded.js";
 /**
@@ -82,7 +83,8 @@ export async function runLlmStep(opts) {
             await DBOS.runStep(() => DBOS.send(workflowId, marker, BUDGET_EXCEEDED_TOPIC), { name: `${stepName}:notify-budget-exceeded` });
         }
         catch (sendErr) {
-            console.warn(`[ta-llm-step] notify-budget-exceeded send failed (non-fatal): ${sendErr instanceof Error ? sendErr.message : sendErr}`);
+            const logger = (opts.logger ?? createNoopLogger()).named("ta-llm-step");
+            logger.warn("notify-budget-exceeded send failed (non-fatal)", { stepName, ...logger.errorFields(sendErr) });
         }
         return { kind: "budget-exceeded", sentinel: BUDGET_EXCEEDED_SENTINEL };
     }

package/dist/workflows/target-assessment/lib/structured-llm.d.ts

@@ -18,9 +18,12 @@
  */
 import { z } from "zod";
 import type { AgentSession } from "../../../auth/types.js";
+import type { Logger } from "../../../lib/logger.js";
 import type { AgentChat } from "../../../providers/types.js";
 import { BUDGET_EXCEEDED_SENTINEL } from "./llm-step.js";
 export interface StructuredLlmCallOptions<TSchema extends z.ZodType> {
+    /** Operational logging seam, forwarded to `runLlmStep`; omitted falls back to no-op. */
+    readonly logger?: Logger;
     /** Attempt-numbered durable-step name (e.g. `"ta-decision:modulator-triage:0"`). */
     readonly stepName: string;
     /** Agent id stamped on telemetry and billing-gateway provenance. */

package/dist/workflows/target-assessment/lib/structured-llm.js

@@ -78,6 +78,7 @@ export async function structuredLlmCall(opts) {
         toolChoice: { type: "tool", toolName: SUBMIT_TOOL_NAME },
     };
     const result = await runLlmStep({
+        ...(opts.logger ? { logger: opts.logger } : {}),
         stepName: opts.stepName,
         agentId: opts.agentId,
         provider: opts.provider,

package/dist/workflows/target-assessment/phase5-persist.d.ts

@@ -15,6 +15,7 @@
  * in §17 if a harness-native audit pipeline is wired.
  */
 import { z } from "zod";
+import type { Logger } from "../../lib/logger.js";
 import { type DossierV4Body } from "@inflexa-ai/harness/contracts/target-dossier.js";
 import type { Phase2Bundle } from "./steps/phase2-aggregate.js";
 import type { DossierRecommendationStepOutput, LiabilityBulletsStepOutput, SafetyFlagsTrailStepOutput, TranslationalCommentaryStepOutput } from "./synthesis/index.js";
@@ -27,6 +28,8 @@ export declare class DossierDerivedInvariantError extends Error {
     constructor(message: string, cause?: unknown | undefined);
 }
 export interface Phase5PersistInput {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly assessmentId: string;
     readonly phase4Dossier: DossierV4Body;
     readonly phase2: Phase2Bundle;

package/dist/workflows/target-assessment/phase5-persist.js

@@ -15,6 +15,7 @@
  * in §17 if a harness-native audit pipeline is wired.
  */
 import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
 import { DossierV5Schema, } from "@inflexa-ai/harness/contracts/target-dossier.js";
 import { getDrugPrimaryTargetUniprots } from "../../tools/lib/chembl-client.js";
 import { deterministicTranslationalCommentary } from "./assemblers/index.js";
@@ -84,7 +85,7 @@ function pickCommentarySeverity(row) {
     }
     return "ok";
 }
-function stampSynthesis(phase4Dossier, syn, phase2) {
+function stampSynthesis(logger, phase4Dossier, syn, phase2) {
     const next = structuredClone(phase4Dossier);
     if (syn.bullets.coverage === "available") {
         next.liability_summary.liability_bullets = syn.bullets.data.bullets.map((b) => ({ text: b.text, rationale: b.rationale, category: b.category }));
@@ -147,7 +148,10 @@ function stampSynthesis(phase4Dossier, syn, phase2) {
         try {
             const audit = validateRecommendationCitations(syn.recommendation.data, next);
             if (audit.citations_unresolved.length > 0) {
-                console.warn(`[phase5-persist] recommendation_audit: ${audit.citations_unresolved.length} unresolved citation(s)`);
+                logger.warn("recommendation_audit: unresolved citation(s)", {
+                    unresolvedCount: audit.citations_unresolved.length,
+                    unresolved: audit.citations_unresolved,
+                });
             }
             next.analytics.recommendation_audit = {
                 coverage: "available",
@@ -388,12 +392,13 @@ async function upgradeDossierToV5(body, phase2) {
  * rejects the final dossier.
  */
 export async function phase5Persist(input) {
+    const logger = (input.logger ?? createNoopLogger()).named("phase5-persist").with({ assessmentId: input.assessmentId });
     // The dossier rides through this function as an untyped working blob; the
     // `as unknown as DossierV{4,5}Body` casts below are version-shim views that
     // let the typed helpers operate on it. None of these casts is load-bearing
     // for soundness: `DossierV5Schema.safeParse(fullDossier)` at the end is the
     // single validation gate, and it throws before anything is returned.
-    let dossier = stampSynthesis(input.phase4Dossier, input.synthesis, input.phase2);
+    let dossier = stampSynthesis(logger, input.phase4Dossier, input.synthesis, input.phase2);
     // Demote organ-claim flagged bullets into coverage_qualifier.unverified_bullets.
     const exec = dossier.executive_recommendation;
     if (exec?.coverage === "available") {

package/dist/workflows/target-assessment/progress.d.ts

@@ -12,6 +12,7 @@
  */
 import type { Pool } from "pg";
 import type { TargetAssessmentPhase, TargetAssessmentProgressEvent } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import type { Logger } from "../../lib/logger.js";
 /** DBOS stream key the SSE route reads via `DBOS.readStream(wfId, "progress")`. */
 export declare const TA_PROGRESS_STREAM_KEY = "progress";
 export type ProgressPhase = TargetAssessmentPhase;
@@ -35,4 +36,4 @@ export declare const PROGRESS_MESSAGES: Record<ProgressPhase, string>;
  * Best-effort: a DB or stream failure logs and continues — progress
  * emission MUST NOT block the workflow.
  */
-export declare function emitProgress(pool: Pool, assessmentId: string, phase: ProgressPhase): Promise<void>;
+export declare function emitProgress(pool: Pool, logger: Logger, assessmentId: string, phase: ProgressPhase): Promise<void>;

package/dist/workflows/target-assessment/progress.js

@@ -46,7 +46,8 @@ export const PROGRESS_MESSAGES = {
  * Best-effort: a DB or stream failure logs and continues — progress
  * emission MUST NOT block the workflow.
  */
-export async function emitProgress(pool, assessmentId, phase) {
+export async function emitProgress(pool, logger, assessmentId, phase) {
+    const log = logger.named("ta-progress").with({ assessmentId, phase });
     const message = PROGRESS_MESSAGES[phase];
     const percent = PROGRESS_PERCENTS[phase];
     await DBOS.runStep(async () => {
@@ -58,7 +59,7 @@ export async function emitProgress(pool, assessmentId, phase) {
             await DBOS.writeStream(TA_PROGRESS_STREAM_KEY, part);
         }
         catch (err) {
-            console.warn(`[ta-progress] writeStream failed for ${assessmentId} (${phase}): ${err instanceof Error ? err.message : err}`);
+            log.warn("writeStream failed", log.errorFields(err));
         }
         // The "suspended" phase is owned by the terminal handler
         // (`markAssessmentSuspended` already set status + progress text). A
@@ -69,7 +70,7 @@ export async function emitProgress(pool, assessmentId, phase) {
             // emission MUST NOT block the workflow. `updateProgress` returns
             // its DB failure as an `Err`, so handle both branches here.
             (await updateProgress(pool, assessmentId, message, rowStatus)).match(() => { }, (error) => {
-                console.warn(`[ta-progress] updateProgress failed for ${assessmentId} (${phase}): ${describeDbError(error)}`);
+                log.warn("updateProgress failed", { err: describeDbError(error) });
             });
         }
     }, { name: `ta-progress:${phase}` });

package/dist/workspace/filesystem.js

@@ -28,8 +28,8 @@
  * OUTSIDE `tryFs`, so only the discrete `fs.open` / `fs.read` / `fs.readFile`
  * calls become `err`.
  */
-import { open as fsOpen, readFile as fsReadFile, readdir as fsReaddir, stat as fsStat } from "node:fs/promises";
-import { createReadStream } from "node:fs";
+import { lstat as fsLstat, open as fsOpen, readdir as fsReaddir, stat as fsStat } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { createInterface } from "node:readline";
 import { join } from "node:path";
 import { ResultAsync, err, errAsync, ok } from "neverthrow";
@@ -123,10 +123,20 @@ export function createWorkspaceFilesystem(deps) {
                     return okAsync({ kind: "out_of_scope" });
                 }
                 const absolute = resolved.absolute;
-                return tryFs("workspace.list", () => fsReaddir(absolute, { withFileTypes: true }), { path: absolute, onAbsent: () => ({ notFound: true }) }).andThen((dirents) => {
-                    if ("notFound" in dirents)
-                        return okAsync({ kind: "not_found" });
-                    return collectEntries(absolute, dirents).map((entries) => ({ kind: "ok", entries }));
+                // `lstat` first so a symlinked directory leaf is refused, not
+                // followed: a plain `readdir` would list the target's entries,
+                // and a leaf swapped to an escaping symlink after the realpath
+                // check would leak an off-tree directory's names. Node has no
+                // fd-based readdir, so this narrows (does not fully close) the
+                // readdir race — the atomic guarantee is on the content reads.
+                return safeLstat(absolute).andThen((s) => {
+                    if (s?.isSymbolicLink())
+                        return okAsync({ kind: "out_of_scope" });
+                    return tryFs("workspace.list", () => fsReaddir(absolute, { withFileTypes: true }), { path: absolute, onAbsent: () => ({ notFound: true }) }).andThen((dirents) => {
+                        if ("notFound" in dirents)
+                            return okAsync({ kind: "not_found" });
+                        return collectEntries(absolute, dirents).map((entries) => ({ kind: "ok", entries }));
+                    });
                 });
             });
         },
@@ -135,9 +145,16 @@ export function createWorkspaceFilesystem(deps) {
                 if (resolved.kind === "out_of_scope") {
                     return okAsync({ kind: "out_of_scope" });
                 }
-                return safeStat(resolved.absolute).map((s) => {
+                // `lstat`, not `stat`: a leaf symlink is refused rather than
+                // followed — same policy as the read open's `O_NOFOLLOW`.
+                // Reporting a followed target's type/size would re-open the
+                // metadata side of the confused-deputy leak, and it is atomic
+                // (a single non-following syscall, no check/use gap).
+                return safeLstat(resolved.absolute).map((s) => {
                     if (!s)
                         return { kind: "not_found" };
+                    if (s.isSymbolicLink())
+                        return { kind: "out_of_scope" };
                     return {
                         kind: "ok",
                         type: s.isDirectory() ? "directory" : "file",
@@ -160,29 +177,89 @@ function safeStat(absolute) {
         onAbsent: () => null,
     });
 }
-/** Stat each directory entry to attach a size; absence/I/O failures degrade to no size. */
+/** Like {@link safeStat} but NEVER follows a leaf symlink (`lstat`) — the seam's
+ *  read-side no-follow policy for the `stat`/`list` metadata surface. */
+function safeLstat(absolute) {
+    return tryFs("workspace.lstat", () => fsLstat(absolute), {
+        path: absolute,
+        onAbsent: () => null,
+    });
+}
+/** Lstat each directory entry to attach a size; absence/I/O failures degrade to
+ *  no size. `lstat` (not `stat`) so a symlink entry reports its own size, never
+ *  its target's — a followed target could be off-tree. `d.isDirectory()` comes
+ *  from the dirent, which does not follow, so a symlink is a plain `file` entry. */
 function collectEntries(dir, dirents) {
     return ResultAsync.combine(dirents.map((d) => {
         if (d.isDirectory())
             return okAsync({ name: d.name, type: "directory" });
-        return safeStat(join(dir, d.name)).map((s) => ({ name: d.name, type: "file", size: s?.size ?? undefined }));
+        return safeLstat(join(dir, d.name)).map((s) => ({ name: d.name, type: "file", size: s?.size ?? undefined }));
     }));
 }
+/**
+ * Read-only open flags that REFUSE to follow a final-component symlink.
+ * `classifyWithinRoot` validated a snapshot of the path; a symlink swapped into
+ * the leaf between that check and the open here would otherwise be followed
+ * off-tree, re-opening the read-exfiltration hole for the length of the race
+ * (CWE-367). `O_NOFOLLOW` makes the leaf open atomic — a symlinked final
+ * component fails `ELOOP` in the same syscall that opens it, so there is no
+ * check/use gap. `?? 0` keeps the mask valid on a platform that lacks the flag.
+ *
+ * This refuses EVERY leaf symlink, including an in-tree one the persistent check
+ * would allow: pure Node cannot express "follow only if it stays in-tree" (that
+ * needs `openat2(RESOLVE_BENEATH)`), so the atomic, race-free choice is to not
+ * follow the leaf at all. Hard-linked staged inputs are unaffected — a hard link
+ * is not a symlink. An intermediate-directory symlink is beyond this guard (Node
+ * exposes no `openat2`); the upstream realpath check still rejects the
+ * persistent case of that.
+ */
+const READ_NO_FOLLOW = fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0);
+/**
+ * Open a workspace file read-only without following a leaf symlink (see
+ * {@link READ_NO_FOLLOW}). A symlinked final component surfaces as `out_of_scope`
+ * — the same verdict a persistent escape gets — never as off-tree bytes. Every
+ * content read (`readWithCap`, `readHeadLines`, `readTailLines`) opens through
+ * here so the bytes it streams come from a non-symlink leaf. Absence /
+ * permission / other I/O throws flow the `FsError` channel unchanged.
+ */
+function openReadNoFollow(absolute) {
+    return tryFs("workspace.openNoFollow", async () => {
+        try {
+            return { kind: "ok", fh: await fsOpen(absolute, READ_NO_FOLLOW) };
+        }
+        catch (cause) {
+            if (cause.code === "ELOOP")
+                return { kind: "out_of_scope" };
+            throw cause;
+        }
+    }, { path: absolute });
+}
 function readWithCap(absolute, totalSize, maxBytes) {
-    if (maxBytes !== undefined && totalSize > maxBytes) {
-        return tryFs("workspace.readCapped", async () => {
-            const fh = await fsOpen(absolute, "r");
+    return openReadNoFollow(absolute).andThen((opened) => {
+        if (opened.kind === "out_of_scope")
+            return okAsync({ kind: "out_of_scope" });
+        const fh = opened.fh;
+        if (maxBytes !== undefined && totalSize > maxBytes) {
+            return tryFs("workspace.readCapped", async () => {
+                try {
+                    const buf = Buffer.alloc(maxBytes);
+                    await fh.read(buf, 0, maxBytes, 0);
+                    return { kind: "truncated", content: buf, totalSize };
+                }
+                finally {
+                    await fh.close();
+                }
+            }, { path: absolute });
+        }
+        return tryFs("workspace.readFile", async () => {
             try {
-                const buf = Buffer.alloc(maxBytes);
-                await fh.read(buf, 0, maxBytes, 0);
-                return { kind: "truncated", content: buf, totalSize };
+                return { kind: "ok", content: await fh.readFile(), truncated: false };
             }
             finally {
                 await fh.close();
             }
         }, { path: absolute });
-    }
-    return tryFs("workspace.readFile", async () => ({ kind: "ok", content: await fsReadFile(absolute), truncated: false }), { path: absolute });
+    });
 }
 function capBuffer(content, maxBytes) {
     if (maxBytes !== undefined && content.length > maxBytes) {
@@ -204,43 +281,51 @@ function capBuffer(content, maxBytes) {
  * follow-up `safeStat` (a discrete `fs` call) flows the `FsError` channel.
  */
 function readHeadLines(absolute, headLines, maxBytes) {
-    return new ResultAsync((async () => {
-        const stream = createReadStream(absolute, { highWaterMark: 16 * 1024 });
-        const rl = createInterface({ input: stream, crlfDelay: Infinity });
-        const collected = [];
-        let bytes = 0;
-        let truncated = false;
-        try {
-            for await (const line of rl) {
-                const lineBytes = Buffer.byteLength(line, "utf8") + 1;
-                if (maxBytes !== undefined && bytes + lineBytes > maxBytes) {
-                    truncated = true;
-                    break;
+    return openReadNoFollow(absolute).andThen((opened) => {
+        if (opened.kind === "out_of_scope")
+            return okAsync({ kind: "out_of_scope" });
+        const fh = opened.fh;
+        return new ResultAsync((async () => {
+            // `autoClose: false` keeps the FileHandle ours to close — destroying
+            // the stream must not race a close against our own `fh.close()`.
+            const stream = fh.createReadStream({ highWaterMark: 16 * 1024, autoClose: false });
+            const rl = createInterface({ input: stream, crlfDelay: Infinity });
+            const collected = [];
+            let bytes = 0;
+            let truncated = false;
+            try {
+                for await (const line of rl) {
+                    const lineBytes = Buffer.byteLength(line, "utf8") + 1;
+                    if (maxBytes !== undefined && bytes + lineBytes > maxBytes) {
+                        truncated = true;
+                        break;
+                    }
+                    collected.push(line);
+                    bytes += lineBytes;
+                    if (collected.length >= headLines)
+                        break;
                 }
-                collected.push(line);
-                bytes += lineBytes;
-                if (collected.length >= headLines)
-                    break;
             }
-        }
-        finally {
-            rl.close();
-            stream.destroy();
-        }
-        const content = Buffer.from(collected.join("\n"));
-        if (truncated) {
-            // Total size is unknown without a full stat; report it as a separate read.
-            return (await safeStat(absolute)).map((s) => ({
-                kind: "truncated",
-                content,
-                totalSize: s?.size ?? content.length,
-            }));
-        }
-        // Whether the loop exhausted the file or hit the line cap, the agent asked
-        // for exactly this window, so this is `ok` not `truncated`. The tool layer
-        // reports `mode: "head"` so the agent knows it's a window.
-        return ok({ kind: "ok", content, truncated: false });
-    })());
+            finally {
+                rl.close();
+                stream.destroy();
+                await fh.close();
+            }
+            const content = Buffer.from(collected.join("\n"));
+            if (truncated) {
+                // Total size is unknown without a full stat; report it as a separate read.
+                return (await safeStat(absolute)).map((s) => ({
+                    kind: "truncated",
+                    content,
+                    totalSize: s?.size ?? content.length,
+                }));
+            }
+            // Whether the loop exhausted the file or hit the line cap, the agent asked
+            // for exactly this window, so this is `ok` not `truncated`. The tool layer
+            // reports `mode: "head"` so the agent knows it's a window.
+            return ok({ kind: "ok", content, truncated: false });
+        })());
+    });
 }
 /**
  * Read the last `tailLines` lines via a windowed read from the end. The
@@ -252,30 +337,34 @@ function readHeadLines(absolute, headLines, maxBytes) {
  * slicing is pure and runs inside the same `fn`.
  */
 function readTailLines(absolute, totalSize, tailLines, maxBytes) {
-    return tryFs("workspace.readTail", async () => {
-        const windowSize = Math.min(totalSize, maxBytes ?? totalSize);
-        const offset = totalSize - windowSize;
-        const fh = await fsOpen(absolute, "r");
-        try {
-            const buf = Buffer.alloc(windowSize);
-            if (windowSize > 0) {
-                await fh.read(buf, 0, windowSize, offset);
+    return openReadNoFollow(absolute).andThen((opened) => {
+        if (opened.kind === "out_of_scope")
+            return okAsync({ kind: "out_of_scope" });
+        const fh = opened.fh;
+        return tryFs("workspace.readTail", async () => {
+            try {
+                const windowSize = Math.min(totalSize, maxBytes ?? totalSize);
+                const offset = totalSize - windowSize;
+                const buf = Buffer.alloc(windowSize);
+                if (windowSize > 0) {
+                    await fh.read(buf, 0, windowSize, offset);
+                }
+                const allLines = buf.toString("utf8").split(/\r?\n/);
+                // Drop the partial leading line if the window doesn't cover the file start.
+                const candidateLines = offset > 0 ? allLines.slice(1) : allLines;
+                const sliced = candidateLines.length > tailLines ? candidateLines.slice(-tailLines) : candidateLines;
+                const content = Buffer.from(sliced.join("\n"));
+                const gotEnoughLines = sliced.length >= tailLines || offset === 0;
+                if (!gotEnoughLines) {
+                    return { kind: "truncated", content, totalSize };
+                }
+                return { kind: "ok", content, truncated: false };
             }
-            const allLines = buf.toString("utf8").split(/\r?\n/);
-            // Drop the partial leading line if the window doesn't cover the file start.
-            const candidateLines = offset > 0 ? allLines.slice(1) : allLines;
-            const sliced = candidateLines.length > tailLines ? candidateLines.slice(-tailLines) : candidateLines;
-            const content = Buffer.from(sliced.join("\n"));
-            const gotEnoughLines = sliced.length >= tailLines || offset === 0;
-            if (!gotEnoughLines) {
-                return { kind: "truncated", content, totalSize };
+            finally {
+                await fh.close();
             }
-            return { kind: "ok", content, truncated: false };
-        }
-        finally {
-            await fh.close();
-        }
-    }, { path: absolute });
+        }, { path: absolute });
+    });
 }
 function sliceHeadLines(content, headLines, maxBytes) {
     const capped = maxBytes !== undefined && content.length > maxBytes ? content.subarray(0, maxBytes) : content;