@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/io/project-name.d.ts

@@ -33,46 +33,37 @@
  * to occupy and against it carrying control characters anywhere
  * downstream.
  *
- * WHAT A REJECTION LOOKS LIKE. `deriveProjectName` (`src/runtime/git-
- * context.ts`) validates its own return value at every exit, so a
- * checkout directory whose basename contains a control character now
- * takes the same path a `".."` basename already took: the helper returns
- * `null`, no project override layer is looked up for that repository,
- * and the base/machine value applies unchanged. There is no error and no
- * warning; the operator sees the host-wide value instead of a per-repo
- * one (`harness doctor`'s setup-version finding then carries
- * `projectName: null` and renders no `(project: X)` suffix). An explicit
- * `--project` carrying a control character is instead reported:
+ * WHAT A REJECTION LOOKS LIKE. An explicit `--project` carrying a control
+ * character or a path-escaping shape is reported, not silently used:
  * `resolvePaths` resolves no project layer for it, and
  * `substituteProject` (`src/probes/memory.ts`) degrades to the "no
  * project supplied" branch, which `harness doctor` surfaces as its
  * rejected-`--project` warn line.
  *
- * Exported (task c88461c1, review round 3 residual; task `1c4eb3ea`
- * of the batch-44 follow-up run) so `resolvePaths` (`src/cli/loader.ts`)
- * can apply the SAME guard at its own `path.join` sink, defense in
- * depth: this function already rejects an unsafe name at every
- * `deriveProjectName` exit, but an `opts.project` reaching
- * `resolvePaths`' OWN sink from anywhere else (a caller building
- * `LoaderOptions` by hand, a future producer) had no equivalent check
- * of its own until now. Applied a THIRD time at `substituteProject`'s
- * own sink (`src/probes/memory.ts`, task `e904f25a`): an invalid name
- * there degrades to the "no project supplied" branch instead of being
- * interpolated into the `{project}` placeholder. Applied a FOURTH time
- * at `buildLockEntries`' own sink (`src/io/harness-lock.ts`, task
- * `b5e6ccb0`): an invalid name there skips the templated directory's
- * lock entry instead of the raw value being interpolated into the path
- * this function stats, hashes and writes into `harness.lock`.
+ * Exported (task c88461c1; task `1c4eb3ea` of the batch-44 follow-up run)
+ * so `resolvePaths` (`src/cli/loader.ts`) can apply the SAME guard at
+ * its own `path.join` sink, defense in depth: an `opts.project`
+ * reaching `resolvePaths` from anywhere (the explicit `--project`
+ * flag, a caller building `LoaderOptions` by hand, a future producer)
+ * is checked there. Applied a SECOND time at
+ * `substituteProject`'s own sink (`src/probes/memory.ts`, task
+ * `e904f25a`): an invalid name there degrades to the "no project
+ * supplied" branch instead of being interpolated into the `{project}`
+ * placeholder. Applied a THIRD time at `buildLockEntries`' own sink
+ * (`src/io/harness-lock.ts`, task `b5e6ccb0`): an invalid name there
+ * skips the templated directory's lock entry instead of the raw value
+ * being interpolated into the path this function stats, hashes and
+ * writes into `harness.lock`.
  * `resolvePaths`, `substituteProject` and `buildLockEntries` are now all
  * guarded; one `{project}` sink is NOT: `generate-memory-index.ts`'s own
  * substitution still interpolates an operator-supplied `--project` value
  * into a path unvalidated, left unguarded (reached only via the explicit
- * CLI flag, not this module's derivation; see CHANGELOG.md for the
- * reservation/follow-up). That one call site calls this function
- * nowhere, so it inherits NOTHING from the control-character screen
- * above either: a caller reading this comment should not assume this
- * function guards every `{project}`-shaped sink in the codebase, for
- * path escapes or for control characters.
+ * `--project` CLI flag; see CHANGELOG.md for the reservation/follow-up).
+ * That one call site calls this function nowhere, so it inherits NOTHING
+ * from the control-character screen above either: a caller reading
+ * this comment should not assume this function guards every
+ * `{project}`-shaped sink in the codebase, for path escapes or for
+ * control characters.
  */
 export declare function isValidProjectName(name: string): boolean;
 /**
@@ -96,14 +87,6 @@ export declare function isValidProjectName(name: string): boolean;
  *    field (`src/cli/list.ts`, and with it the text table derived from
  *    it).
  *
- * The `session_start_preflight.setup` finding's `(project: X)` suffix is
- * also wrapped, as defense in depth rather than as an echo of a rejected
- * value: `harness doctor` sets that finding's `projectName` only when
- * `resolvePaths` actually resolved a project layer FILE, which requires
- * the name to have passed {@link isValidProjectName} first. The wrap
- * stays so a hand-built finding or a future producer cannot reintroduce
- * a forged line through that one call site.
- *
  * Strips (rather than escapes) every character in
  * {@link PROJECT_NAME_CONTROL_CHARS}. A name with no control character
  * (`..`, `a/b`, every ordinary shape) passes through unchanged. Report

package/dist/io/project-name.js

@@ -10,9 +10,9 @@
 // documents for `src/policies/duration.ts`, `src/policies/extract.ts`,
 // `src/runtime/ledger-record.ts` and `src/runtime/expand-home.ts`: a
 // utility needed below its original layer moves down rather than the
-// importing layer's boundary being relaxed. `src/runtime/git-context.ts`
-// re-exports both names so every existing consumer that imports them from
-// `../runtime/git-context.js` keeps working unchanged.
+// importing layer's boundary being relaxed. This module is the home of
+// both helpers: every consumer imports them from `src/io/project-name.ts`
+// directly.
 /**
  * Every C0 control character (U+0000 to U+001F, so NUL, LF, CR and ESC
  * among them), DEL (U+007F), and every C1 control character (U+0080 to
@@ -65,46 +65,37 @@ const PROJECT_NAME_CONTROL_CHARS_GLOBAL = new RegExp(PROJECT_NAME_CONTROL_CHARS.
  * to occupy and against it carrying control characters anywhere
  * downstream.
  *
- * WHAT A REJECTION LOOKS LIKE. `deriveProjectName` (`src/runtime/git-
- * context.ts`) validates its own return value at every exit, so a
- * checkout directory whose basename contains a control character now
- * takes the same path a `".."` basename already took: the helper returns
- * `null`, no project override layer is looked up for that repository,
- * and the base/machine value applies unchanged. There is no error and no
- * warning; the operator sees the host-wide value instead of a per-repo
- * one (`harness doctor`'s setup-version finding then carries
- * `projectName: null` and renders no `(project: X)` suffix). An explicit
- * `--project` carrying a control character is instead reported:
+ * WHAT A REJECTION LOOKS LIKE. An explicit `--project` carrying a control
+ * character or a path-escaping shape is reported, not silently used:
  * `resolvePaths` resolves no project layer for it, and
  * `substituteProject` (`src/probes/memory.ts`) degrades to the "no
  * project supplied" branch, which `harness doctor` surfaces as its
  * rejected-`--project` warn line.
  *
- * Exported (task c88461c1, review round 3 residual; task `1c4eb3ea`
- * of the batch-44 follow-up run) so `resolvePaths` (`src/cli/loader.ts`)
- * can apply the SAME guard at its own `path.join` sink, defense in
- * depth: this function already rejects an unsafe name at every
- * `deriveProjectName` exit, but an `opts.project` reaching
- * `resolvePaths`' OWN sink from anywhere else (a caller building
- * `LoaderOptions` by hand, a future producer) had no equivalent check
- * of its own until now. Applied a THIRD time at `substituteProject`'s
- * own sink (`src/probes/memory.ts`, task `e904f25a`): an invalid name
- * there degrades to the "no project supplied" branch instead of being
- * interpolated into the `{project}` placeholder. Applied a FOURTH time
- * at `buildLockEntries`' own sink (`src/io/harness-lock.ts`, task
- * `b5e6ccb0`): an invalid name there skips the templated directory's
- * lock entry instead of the raw value being interpolated into the path
- * this function stats, hashes and writes into `harness.lock`.
+ * Exported (task c88461c1; task `1c4eb3ea` of the batch-44 follow-up run)
+ * so `resolvePaths` (`src/cli/loader.ts`) can apply the SAME guard at
+ * its own `path.join` sink, defense in depth: an `opts.project`
+ * reaching `resolvePaths` from anywhere (the explicit `--project`
+ * flag, a caller building `LoaderOptions` by hand, a future producer)
+ * is checked there. Applied a SECOND time at
+ * `substituteProject`'s own sink (`src/probes/memory.ts`, task
+ * `e904f25a`): an invalid name there degrades to the "no project
+ * supplied" branch instead of being interpolated into the `{project}`
+ * placeholder. Applied a THIRD time at `buildLockEntries`' own sink
+ * (`src/io/harness-lock.ts`, task `b5e6ccb0`): an invalid name there
+ * skips the templated directory's lock entry instead of the raw value
+ * being interpolated into the path this function stats, hashes and
+ * writes into `harness.lock`.
  * `resolvePaths`, `substituteProject` and `buildLockEntries` are now all
  * guarded; one `{project}` sink is NOT: `generate-memory-index.ts`'s own
  * substitution still interpolates an operator-supplied `--project` value
  * into a path unvalidated, left unguarded (reached only via the explicit
- * CLI flag, not this module's derivation; see CHANGELOG.md for the
- * reservation/follow-up). That one call site calls this function
- * nowhere, so it inherits NOTHING from the control-character screen
- * above either: a caller reading this comment should not assume this
- * function guards every `{project}`-shaped sink in the codebase, for
- * path escapes or for control characters.
+ * `--project` CLI flag; see CHANGELOG.md for the reservation/follow-up).
+ * That one call site calls this function nowhere, so it inherits NOTHING
+ * from the control-character screen above either: a caller reading
+ * this comment should not assume this function guards every
+ * `{project}`-shaped sink in the codebase, for path escapes or for
+ * control characters.
  */
 export function isValidProjectName(name) {
     if (name.length === 0)
@@ -136,14 +127,6 @@ export function isValidProjectName(name) {
  *    field (`src/cli/list.ts`, and with it the text table derived from
  *    it).
  *
- * The `session_start_preflight.setup` finding's `(project: X)` suffix is
- * also wrapped, as defense in depth rather than as an echo of a rejected
- * value: `harness doctor` sets that finding's `projectName` only when
- * `resolvePaths` actually resolved a project layer FILE, which requires
- * the name to have passed {@link isValidProjectName} first. The wrap
- * stays so a hand-built finding or a future producer cannot reintroduce
- * a forged line through that one call site.
- *
  * Strips (rather than escapes) every character in
  * {@link PROJECT_NAME_CONTROL_CHARS}. A name with no control character
  * (`..`, `a/b`, every ordinary shape) passes through unchanged. Report

package/dist/io/project-name.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-name.js","sourceRoot":"","sources":["../../src/io/project-name.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,yCAAyC;AACzC,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,2EAA2E;AAC3E,+DAA+D;AAC/D,wEAAwE;AACxE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,yEAAyE;AACzE,0EAA0E;AAC1E,uDAAuD;AAEvD;;;;;;;GAOG;AACH,MAAM,0BAA0B,GAAG,8BAA8B,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,iCAAiC,GAAG,IAAI,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI,CAAC,OAAO,CAAC,iCAAiC,EAAE,EAAE,CAAC,CAAC;AAC7D,CAAC"}
+{"version":3,"file":"project-name.js","sourceRoot":"","sources":["../../src/io/project-name.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,yCAAyC;AACzC,EAAE;AACF,4EAA4E;AAC5E,uEAAuE;AACvE,2EAA2E;AAC3E,+DAA+D;AAC/D,wEAAwE;AACxE,wEAAwE;AACxE,uEAAuE;AACvE,qEAAqE;AACrE,qEAAqE;AACrE,uEAAuE;AACvE,0EAA0E;AAC1E,YAAY;AAEZ;;;;;;;GAOG;AACH,MAAM,0BAA0B,GAAG,8BAA8B,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,iCAAiC,GAAG,IAAI,MAAM,CAAC,0BAA0B,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAChD,IAAI,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,IAAI,CAAC,OAAO,CAAC,iCAAiC,EAAE,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/dist/io/read-regular-file.d.ts

@@ -1,8 +1,8 @@
 /**
  * Result of a symlink-rejecting regular-file read. The kinds are deliberately
- * fine-grained because the gate readers need to keep their distinct deny
- * details (missing vs symlink vs not-regular) and one caller treats
- * exists-but-unreadable as "existence already satisfied the gate".
+ * fine-grained because the readers need to keep their distinct failure
+ * details (missing vs symlink vs not-regular); every caller treats
+ * `unreadable` (an oversized file included) as fail-closed.
  */
 export type RegularFileRead = {
     kind: "ok";
@@ -17,47 +17,110 @@ export type RegularFileRead = {
     kind: "unreadable";
 };
 /**
- * Result of a stat-only existence probe (see `probePathPresence`). No
- * `content`: this never reads the file, only classifies what lstat sees at
- * the path. `present` covers a symlink, a directory, or any other non-regular
- * node the caller wants to treat as "something is there" without yet reading
- * it or deciding whether it is a valid regular file.
+ * The most bytes a read returns by default. The current callers read small
+ * text records: the harness manifest and its override layers
+ * (`src/cli/loader.ts`) and, with a larger bound of their own, the Claude
+ * Code user-scope MCP registry (`src/io/claude-mcp.ts`). A file over the
+ * cap is refused as `unreadable` (fail-closed in every caller) before any
+ * byte is read: a sparse multi-gigabyte file at one of these paths
+ * otherwise makes the caller wait on bytes it never asked for, the same
+ * stall a FIFO used to cause.
  */
-export type PathPresence = {
-    kind: "missing";
-} | {
-    kind: "present";
-};
+export declare const MAX_REGULAR_FILE_READ_BYTES: number;
+/**
+ * Options of the readers below. They default to the strict read this module
+ * was built for (the 1 MiB cap, a symlink refused).
+ */
+export interface BoundedReadOptions {
+    /**
+     * The most bytes the read returns; a file over it is refused as
+     * `unreadable` before any byte is read, exactly like the default cap.
+     * Defaults to {@link MAX_REGULAR_FILE_READ_BYTES}. A caller
+     * with a legitimately larger input (the Claude Code user registry) passes
+     * its own, larger bound and justifies
+     * it at the call site; there is deliberately no way to ask for no bound.
+     */
+    maxBytes?: number;
+    /**
+     * Follow a symbolic link at the path (the open drops `O_NOFOLLOW`). For a
+     * reader of a file the operator legitimately keeps behind a link
+     * (a dotfiles-managed manifest); it never weakens the
+     * rest: the type of the OPENED descriptor still decides, so a link to a
+     * FIFO, a device or a directory is `not-regular` and never blocks.
+     * Defaults to `false` (a link is refused as `symlink`).
+     */
+    followSymlinks?: boolean;
+}
+export type RegularFileBytesRead = {
+    kind: "ok";
+    bytes: Buffer;
+} | Exclude<RegularFileRead, {
+    kind: "ok";
+}>;
 /**
- * Read a marker/verdict file as utf8, refusing symlinks and non-regular
- * files. lstat (NOT stat): defense-in-depth against a symlink at the marker
- * path pointing at an arbitrary target the agent controls. In today's threat
- * model the agent has no Edit / Write / Bash path to plant such a symlink
- * (the same PreToolUse hook gates all three), but the gate contract is to
- * assume the agent is hostile, so the lstat reject is cheap insurance
+ * The one open-once, type-checked-on-the-descriptor, size-bounded read every
+ * by-path reader on a hook path stands on, returning raw bytes (a binary key
+ * file needs them, `readRegularFileBounded` decodes them). The cap and the
+ * symlink policy are options.
+ *
+ * The path is opened once, read-only, with `O_NOFOLLOW` (a symlink at the
+ * path is refused by the open itself) and `O_NONBLOCK` (opening a FIFO with
+ * no writer returns at once instead of waiting for one). The type of the
+ * OPENED descriptor then decides (`fstat`, never a separate stat of the
+ * path), and the content is read through that same descriptor, so nothing
+ * can be swapped in between a check and the read: a writer that replaces the
+ * file with a FIFO or a symlink after any earlier look gets `not-regular` /
+ * `symlink` back, not a read that blocks the hook past its budget (which the
+ * runtime treats as an allow). The descriptor is always closed. The size is
+ * bounded too: a file over the cap by `fstat` is refused as `unreadable`
+ * without a read, and the read itself stops one byte past the cap, so a file
+ * that grows after the `fstat` is bounded as well.
+ *
+ * Why refuse symlinks at all: defense-in-depth against a symlink at the
+ * path pointing at an arbitrary target the agent controls. The gate contract
+ * is to assume the agent is hostile, so the refusal is cheap insurance
  * (agent-tasks/d39f160e).
  *
- * This is THE shared implementation for every gate-marker read; a future
- * defensive fix belongs in `lstatOrNull`, above, and nowhere else. Its
- * lighter-weight sibling `probePathPresence`, below, shares this file for
- * the same reason: both stand on the same `lstatOrNull` helper, and a
- * caller that only needs to know "is anything there" before deciding
- * whether to pay for the full read (e.g. `verifyDelegation`'s
- * existence-before-path-hash check in
- * `src/policy-packs/builtin/understanding-before-execution/delegation-markers.ts`)
- * gets that from here instead of hand-rolling its own `lstatSync` try/catch.
+ * Platforms without `O_NOFOLLOW` (Windows): an `lstat` runs first and
+ * refuses a symlink or a non-regular node before the open, because the open
+ * alone would follow a link. That leaves the old lstat-to-open window on
+ * those platforms; there is no FIFO node on the filesystem there to swap in
+ * (named pipes live in a separate namespace), and `O_NONBLOCK` is a no-op
+ * flag that is simply left out. The descriptor type check still runs.
+ *
+ * A future defensive fix belongs here and in `classifyOpenFailure` /
+ * `lstatOrNull`, and nowhere else.
+ */
+export declare function readRegularFileBytesBounded(filePath: string, opts?: BoundedReadOptions): RegularFileBytesRead;
+/**
+ * {@link readRegularFileBytesBounded} decoded as utf8, for the by-path
+ * readers of a file a symlink at the path is acceptable for or a larger cap
+ * is justified (see {@link BoundedReadOptions}). Same five result kinds as
+ * {@link readRegularFileBytesBounded}; `missing` is the one a caller may
+ * treat as "legitimately absent", every other non-`ok` kind means something
+ * is at the path that must not be read as the file (a FIFO, a device, a
+ * directory, an oversized or unreadable file) and is fail-closed or
+ * explicitly reported by the caller.
+ */
+export declare function readRegularFileBounded(filePath: string, opts?: BoundedReadOptions): RegularFileRead;
+/**
+ * Thrown by {@link readTextFileBoundedOrThrow}. `code` is `ENOENT` for a
+ * path that is not there (so a caller's existing `ENOENT` branch keeps
+ * meaning "absent") and `E_<KIND>` (`E_SYMLINK`, `E_NOT_REGULAR`,
+ * `E_UNREADABLE`) for anything else, which never matches `ENOENT`.
  */
-export declare function readRegularFileRejectingSymlink(filePath: string): RegularFileRead;
+export declare class BoundedReadError extends Error {
+    readonly code: string;
+    readonly kind: Exclude<RegularFileRead["kind"], "ok">;
+    constructor(filePath: string, kind: Exclude<RegularFileRead["kind"], "ok">);
+}
 /**
- * Stat-only existence probe: "is anything there", nothing more. Uses the
- * same `lstatOrNull` helper (not `stat`) as `readRegularFileRejectingSymlink`
- * so a symlink or a directory answers `present`, not `missing`; this probe
- * cannot and does not classify WHAT is there (regular file, symlink,
- * directory), only whether lstat can see anything at all. A path lstat
- * cannot reach for any reason (absent, or unreachable: `EACCES`, `ENOTDIR`,
- * ...) comes back `missing`; lstat cannot distinguish those cases, so
- * neither does this probe. Callers that need the file-type distinction
- * (symlink vs directory vs regular) read the file instead, through
- * `readRegularFileRejectingSymlink`.
+ * {@link readRegularFileBounded} for the call sites that already wrap a
+ * `fs.readFileSync(path, "utf8")` in a try/catch (and, some of them, branch
+ * on `ENOENT`): the same bounded, non-blocking read, thrown as a
+ * {@link BoundedReadError} instead of returned, so the existing catch blocks
+ * keep their shape and every FIFO, device, directory or oversized file now
+ * lands in the catch block it would have reached on any other read error,
+ * rather than blocking the process.
  */
-export declare function probePathPresence(filePath: string): PathPresence;
+export declare function readTextFileBoundedOrThrow(filePath: string, opts?: BoundedReadOptions): string;

package/dist/io/read-regular-file.js

@@ -1,11 +1,10 @@
 import * as fs from "node:fs";
 /**
- * The single `fs.lstatSync` call both exports below stand on. Returns `null`
+ * The single `fs.lstatSync` call the readers below stand on. Returns `null`
  * on any lstat failure (absent path, or unreachable for another reason:
  * `EACCES`, `ENOTDIR`, ...); lstat cannot distinguish those cases from each
- * other, so neither export tries to. A future defensive fix here (e.g.
- * closing the lstat/read race with `O_NOFOLLOW`, `ENOTDIR` handling) lands in
- * this one place and is inherited by both callers.
+ * other, so no caller tries to. A future defensive fix here
+ * (e.g. `ENOTDIR` handling) lands in this one place.
  */
 function lstatOrNull(filePath) {
     try {
@@ -16,25 +15,79 @@ function lstatOrNull(filePath) {
     }
 }
 /**
- * Read a marker/verdict file as utf8, refusing symlinks and non-regular
- * files. lstat (NOT stat): defense-in-depth against a symlink at the marker
- * path pointing at an arbitrary target the agent controls. In today's threat
- * model the agent has no Edit / Write / Bash path to plant such a symlink
- * (the same PreToolUse hook gates all three), but the gate contract is to
- * assume the agent is hostile, so the lstat reject is cheap insurance
- * (agent-tasks/d39f160e).
- *
- * This is THE shared implementation for every gate-marker read; a future
- * defensive fix belongs in `lstatOrNull`, above, and nowhere else. Its
- * lighter-weight sibling `probePathPresence`, below, shares this file for
- * the same reason: both stand on the same `lstatOrNull` helper, and a
- * caller that only needs to know "is anything there" before deciding
- * whether to pay for the full read (e.g. `verifyDelegation`'s
- * existence-before-path-hash check in
- * `src/policy-packs/builtin/understanding-before-execution/delegation-markers.ts`)
- * gets that from here instead of hand-rolling its own `lstatSync` try/catch.
+ * Open flags for the reads in this module. `O_NOFOLLOW` makes the open itself
+ * refuse a symbolic link at the final path component (`ELOOP`), so no
+ * earlier `lstat` is needed for a swap to race. `O_NONBLOCK` keeps an open
+ * of a FIFO with no writer from waiting for one: the open returns at once
+ * and the descriptor's type then refuses it. `O_NOFOLLOW` covers only the
+ * LAST path component; a symlinked parent directory is followed, as it was
+ * under the earlier lstat. `O_NOCTTY` is belt and braces for a tty node at
+ * the path. All three are POSIX-only flags; `fs.constants` leaves them
+ * `undefined` on Windows, where the code falls back to 0 (see
+ * `readRegularFileBytesBounded` for that fallback).
+ */
+const O_NOFOLLOW = fs.constants.O_NOFOLLOW;
+const O_NONBLOCK = fs.constants.O_NONBLOCK ?? 0;
+/** A read here must never make a terminal the process's controlling one. */
+const O_NOCTTY = fs.constants.O_NOCTTY ?? 0;
+/**
+ * The most bytes a read returns by default. The current callers read small
+ * text records: the harness manifest and its override layers
+ * (`src/cli/loader.ts`) and, with a larger bound of their own, the Claude
+ * Code user-scope MCP registry (`src/io/claude-mcp.ts`). A file over the
+ * cap is refused as `unreadable` (fail-closed in every caller) before any
+ * byte is read: a sparse multi-gigabyte file at one of these paths
+ * otherwise makes the caller wait on bytes it never asked for, the same
+ * stall a FIFO used to cause.
+ */
+export const MAX_REGULAR_FILE_READ_BYTES = 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+/**
+ * Read the opened descriptor to EOF, never more than `maxBytes + 1` bytes: a
+ * file that grows after the `fstat` size check stays bounded too. Returns
+ * `null` when the file is over the cap. Any read error propagates to the
+ * caller.
+ */
+function readDescriptorBounded(fd, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const want = Math.min(READ_CHUNK_BYTES, maxBytes + 1 - total);
+        const chunk = Buffer.allocUnsafe(want);
+        const got = fs.readSync(fd, chunk, 0, want, null);
+        if (got === 0)
+            break;
+        total += got;
+        if (total > maxBytes)
+            return null;
+        chunks.push(got === want ? chunk : chunk.subarray(0, got));
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Classify a failed open by what `lstat` sees at the path now, so the
+ * caller-visible kinds stay what they were when `lstat` came first: an
+ * unreachable path (absent, `ENOTDIR`, an unsearchable parent) is `missing`,
+ * a symlink (dangling included) is `symlink`, any other non-regular node is
+ * `not-regular`, and a regular file the open could not read (`EACCES`, ...)
+ * is `unreadable`. A path that raced into a different state between the
+ * failed open and this `lstat` still lands on one of the five kinds, never
+ * on `ok`.
  */
-export function readRegularFileRejectingSymlink(filePath) {
+function classifyOpenFailure(filePath, followSymlinks = false) {
+    if (followSymlinks) {
+        // A link is followed by this read, so what matters is what it leads to:
+        // a dangling link (or an unreachable parent) is absent, exactly as a
+        // by-path read of it reports `ENOENT`; a link loop or an unreadable
+        // target is something there that cannot be read.
+        try {
+            return fs.statSync(filePath).isFile() ? { kind: "unreadable" } : { kind: "not-regular" };
+        }
+        catch (err) {
+            const code = err.code;
+            return code === "ENOENT" || code === "ENOTDIR" ? { kind: "missing" } : { kind: "unreadable" };
+        }
+    }
     const stat = lstatOrNull(filePath);
     if (stat === null)
         return { kind: "missing" };
@@ -42,26 +95,134 @@ export function readRegularFileRejectingSymlink(filePath) {
         return { kind: "symlink" };
     if (!stat.isFile())
         return { kind: "not-regular" };
+    return { kind: "unreadable" };
+}
+/**
+ * The one open-once, type-checked-on-the-descriptor, size-bounded read every
+ * by-path reader on a hook path stands on, returning raw bytes (a binary key
+ * file needs them, `readRegularFileBounded` decodes them). The cap and the
+ * symlink policy are options.
+ *
+ * The path is opened once, read-only, with `O_NOFOLLOW` (a symlink at the
+ * path is refused by the open itself) and `O_NONBLOCK` (opening a FIFO with
+ * no writer returns at once instead of waiting for one). The type of the
+ * OPENED descriptor then decides (`fstat`, never a separate stat of the
+ * path), and the content is read through that same descriptor, so nothing
+ * can be swapped in between a check and the read: a writer that replaces the
+ * file with a FIFO or a symlink after any earlier look gets `not-regular` /
+ * `symlink` back, not a read that blocks the hook past its budget (which the
+ * runtime treats as an allow). The descriptor is always closed. The size is
+ * bounded too: a file over the cap by `fstat` is refused as `unreadable`
+ * without a read, and the read itself stops one byte past the cap, so a file
+ * that grows after the `fstat` is bounded as well.
+ *
+ * Why refuse symlinks at all: defense-in-depth against a symlink at the
+ * path pointing at an arbitrary target the agent controls. The gate contract
+ * is to assume the agent is hostile, so the refusal is cheap insurance
+ * (agent-tasks/d39f160e).
+ *
+ * Platforms without `O_NOFOLLOW` (Windows): an `lstat` runs first and
+ * refuses a symlink or a non-regular node before the open, because the open
+ * alone would follow a link. That leaves the old lstat-to-open window on
+ * those platforms; there is no FIFO node on the filesystem there to swap in
+ * (named pipes live in a separate namespace), and `O_NONBLOCK` is a no-op
+ * flag that is simply left out. The descriptor type check still runs.
+ *
+ * A future defensive fix belongs here and in `classifyOpenFailure` /
+ * `lstatOrNull`, and nowhere else.
+ */
+export function readRegularFileBytesBounded(filePath, opts = {}) {
+    const maxBytes = opts.maxBytes ?? MAX_REGULAR_FILE_READ_BYTES;
+    const noFollow = opts.followSymlinks !== true;
+    if (noFollow && O_NOFOLLOW === undefined) {
+        const stat = lstatOrNull(filePath);
+        if (stat === null)
+            return { kind: "missing" };
+        if (stat.isSymbolicLink())
+            return { kind: "symlink" };
+        if (!stat.isFile())
+            return { kind: "not-regular" };
+    }
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | (noFollow ? (O_NOFOLLOW ?? 0) : 0) | O_NONBLOCK | O_NOCTTY);
+    }
+    catch {
+        return classifyOpenFailure(filePath, !noFollow);
+    }
     try {
-        return { kind: "ok", content: fs.readFileSync(filePath, "utf8") };
+        const st = fs.fstatSync(fd);
+        if (!st.isFile())
+            return { kind: "not-regular" };
+        if (st.size > maxBytes)
+            return { kind: "unreadable" };
+        const bytes = readDescriptorBounded(fd, maxBytes);
+        if (bytes === null)
+            return { kind: "unreadable" };
+        return { kind: "ok", bytes };
     }
     catch {
         return { kind: "unreadable" };
     }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // Already gone; nothing left to release.
+        }
+    }
+}
+/**
+ * {@link readRegularFileBytesBounded} decoded as utf8, for the by-path
+ * readers of a file a symlink at the path is acceptable for or a larger cap
+ * is justified (see {@link BoundedReadOptions}). Same five result kinds as
+ * {@link readRegularFileBytesBounded}; `missing` is the one a caller may
+ * treat as "legitimately absent", every other non-`ok` kind means something
+ * is at the path that must not be read as the file (a FIFO, a device, a
+ * directory, an oversized or unreadable file) and is fail-closed or
+ * explicitly reported by the caller.
+ */
+export function readRegularFileBounded(filePath, opts = {}) {
+    const read = readRegularFileBytesBounded(filePath, opts);
+    return read.kind === "ok" ? { kind: "ok", content: read.bytes.toString("utf8") } : read;
+}
+/**
+ * Thrown by {@link readTextFileBoundedOrThrow}. `code` is `ENOENT` for a
+ * path that is not there (so a caller's existing `ENOENT` branch keeps
+ * meaning "absent") and `E_<KIND>` (`E_SYMLINK`, `E_NOT_REGULAR`,
+ * `E_UNREADABLE`) for anything else, which never matches `ENOENT`.
+ */
+export class BoundedReadError extends Error {
+    code;
+    kind;
+    constructor(filePath, kind) {
+        const code = kind === "missing" ? "ENOENT" : `E_${kind.toUpperCase().replace(/-/g, "_")}`;
+        super(`${code}: ${filePath} ${DESCRIBE_KIND[kind]}`);
+        this.name = "BoundedReadError";
+        this.code = code;
+        this.kind = kind;
+    }
 }
+const DESCRIBE_KIND = {
+    missing: "does not exist",
+    symlink: "is a symbolic link (refused)",
+    "not-regular": "is not a regular file (refused without a read)",
+    unreadable: "is unreadable or larger than the read cap",
+};
 /**
- * Stat-only existence probe: "is anything there", nothing more. Uses the
- * same `lstatOrNull` helper (not `stat`) as `readRegularFileRejectingSymlink`
- * so a symlink or a directory answers `present`, not `missing`; this probe
- * cannot and does not classify WHAT is there (regular file, symlink,
- * directory), only whether lstat can see anything at all. A path lstat
- * cannot reach for any reason (absent, or unreachable: `EACCES`, `ENOTDIR`,
- * ...) comes back `missing`; lstat cannot distinguish those cases, so
- * neither does this probe. Callers that need the file-type distinction
- * (symlink vs directory vs regular) read the file instead, through
- * `readRegularFileRejectingSymlink`.
+ * {@link readRegularFileBounded} for the call sites that already wrap a
+ * `fs.readFileSync(path, "utf8")` in a try/catch (and, some of them, branch
+ * on `ENOENT`): the same bounded, non-blocking read, thrown as a
+ * {@link BoundedReadError} instead of returned, so the existing catch blocks
+ * keep their shape and every FIFO, device, directory or oversized file now
+ * lands in the catch block it would have reached on any other read error,
+ * rather than blocking the process.
  */
-export function probePathPresence(filePath) {
-    return lstatOrNull(filePath) === null ? { kind: "missing" } : { kind: "present" };
+export function readTextFileBoundedOrThrow(filePath, opts = {}) {
+    const read = readRegularFileBounded(filePath, opts);
+    if (read.kind === "ok")
+        return read.content;
+    throw new BoundedReadError(filePath, read.kind);
 }
 //# sourceMappingURL=read-regular-file.js.map