@lannguyensi/harness 0.60.0 → 0.62.0

package/dist/policy-packs/builtin/understanding-before-execution/index.js

@@ -37,7 +37,7 @@
 // harness gate; `harness approve understanding` is the approval path.
 export { APPROVED_LEDGER_TAG_PREFIX, approvedLedgerTagFor, isPolicyDecisionRow, matchLedgerEntries, } from "./ledger.js";
 export { APPROVAL_MARKER_DIRNAME, approvalMarkerPathFor, writeApprovalMarker, checkApprovalMarker, clearApprovalMarker, } from "./markers.js";
-export { REPORTS_DIR_ENV, defaultReportsDir, reportsDirForManifest, listPersistedReports, TOLERANT_FALLBACK_MAX_AGE_MS, TOLERANT_FALLBACK_FUTURE_SKEW_MS, selectReportForSession, selectNewestStrictSessionReport, findLatestReportForSession, expirePersistedReport, checkPersistedReport, canonicalReportHash, canonicalReportHashOfFile, MAX_HASHED_REPORT_BYTES, readReportFileBounded, hashReportFile, verifyApprovedReportHash, } from "./persisted-reports.js";
+export { REPORTS_DIR_ENV, defaultReportsDir, reportsDirForManifest, listPersistedReports, listPersistedReportsBoundedWithSkips, TOLERANT_FALLBACK_MAX_AGE_MS, TOLERANT_FALLBACK_FUTURE_SKEW_MS, selectReportForSession, selectNewestStrictSessionReport, findLatestReportForSession, expirePersistedReport, checkPersistedReport, canonicalReportHash, canonicalReportHashOfFile, MAX_HASHED_REPORT_BYTES, readReportFileBounded, hashReportFile, verifyApprovedReportHash, } from "./persisted-reports.js";
 export { parseApprovalLifecycle } from "./lifecycle.js";
 export { AUTO_APPROVED_BY_PREFIX, CLAUDE_CODE_HARNESS, autoApprovedByFor, parseAutoApprovedBy, autoApprovedLedgerTagFor, parseAutoApprove, permissionModeAllowed, harnessAllowed, AUTO_APPROVE_HARNESS_VALUES, DEFAULT_AUTO_APPROVE_HARNESSES, DEFAULT_REPORT_SCAN_MAX_WAIT_MS, REPORT_SCAN_MAX_WAIT_CEILING_MS, parseReportScanMaxWait, } from "./auto-approve.js";
 // D-004 shipped default (task 8f637efd): the one `auto_approve` snippet

package/dist/policy-packs/builtin/understanding-before-execution/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/index.ts"],"names":[],"mappings":"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"}

package/dist/policy-packs/builtin/understanding-before-execution/persisted-reports.d.ts

@@ -55,16 +55,16 @@ export declare function defaultReportsDir(cwd?: string): string;
 export declare function reportsDirForManifest(manifestPath: string): string;
 /**
  * List persisted reports under `dir`, newest-first by creation time
- * (JSON `createdAt`, falling back to the filename ISO prefix, falling
- * back to mtime). Missing directory returns []. Any I/O error on a
- * single file is silently skipped; the caller falls through to the
- * ledger result.
+ * (JSON `createdAt`, then the filename ISO prefix, then mtime). Missing
+ * directory returns []; an I/O error on a single file skips it. Reads each
+ * regular file IN FULL, so it must not list the agent-writable reports
+ * directory (use {@link listPersistedReportsBoundedWithSkips}); no `src`
+ * caller remains, it stays for its tests and the pack's export surface.
  *
  * Creation time, NOT mtime, is the sort key: `harness approve
  * understanding` rewrites the report it flips, which bumps mtime and
  * made an old just-approved report sort as the freshest
- * (harness-discovery C1). mtime survives only as the last-resort
- * fallback for files that carry neither timestamp.
+ * (harness-discovery C1). mtime is the last-resort fallback.
  */
 export declare function listPersistedReports(dir: string): PersistedReport[];
 /**
@@ -276,6 +276,38 @@ export declare function describeBoundaryExpiry(report: Pick<PersistedReport, "ap
  * producers refuse to approve such a report.
  */
 export declare const MAX_HASHED_REPORT_BYTES: number;
+/**
+ * Budget the gate-read hash scan spends before it gives up (32 MiB), charged
+ * per `*.json` entry as the larger of the bytes read and
+ * {@link MIN_SCAN_ENTRY_COST_BYTES}. The per-file cap bounds one file, not
+ * their number: 160 planted 1 MiB key-heavy files took 15.9 to 17.6 s of scan
+ * time, past the 15 s PreToolUse budget, and a hook past its budget is a
+ * non-blocking error for the runtime (an allow). Charging bytes alone left the
+ * entry count open: entries that cost no bytes (tiny files, directories named
+ * `*.json`, files over the cap, unreadable ones) still cost an open each, and
+ * 400k tiny files took about 22 s of CPU. A scan that spent the budget without
+ * finding every wanted hash stops and the check fails closed with the mismatch
+ * reason. With the floor the scan opens at most 8192 entries and reads about
+ * 32 MiB (the last file read may add up to the 1 MiB per-file cap), whichever
+ * the entries are. Real reports are a few kilobytes, so the budget covers
+ * thousands of them. The scan reads the newest file first, which is where the
+ * approved report usually is.
+ *
+ * This bounds the hash scan only, not the hook as a whole by entry count: the
+ * evidence read that follows a refused marker (shared with the no-marker path,
+ * `listPersistedReportsBounded`) still opens and parses every `*.json` entry,
+ * so a directory of hundreds of thousands of planted entries still takes the
+ * hook past the PreToolUse budget, which the runtime treats as an allow. A
+ * follow-up task bounds that read.
+ */
+export declare const MAX_HASH_SCAN_BYTES: number;
+/**
+ * Least a `*.json` entry is charged against {@link MAX_HASH_SCAN_BYTES}
+ * whatever the read returned (4 KiB, about one real report), so entries that
+ * read nothing or little still spend the budget at a rate that bounds their
+ * count: 32 MiB / 4 KiB = 8192 entries.
+ */
+export declare const MIN_SCAN_ENTRY_COST_BYTES = 4096;
 /** Result of {@link walkContainerDepth}. */
 export interface ContainerDepthWalk {
     /** True when some array/object nests deeper than the walk's `max` levels. */
@@ -317,6 +349,7 @@ export type ReportFileReadFailure = "unreadable" | "not-regular" | "too-large" |
 export type BoundedReportRead = {
     ok: true;
     raw: string;
+    mtimeMs: number;
 } | {
     ok: false;
     reason: ReportFileReadFailure;
@@ -336,8 +369,16 @@ export type BoundedReportRead = {
  * (never more than the cap plus one byte); a file that grows into that byte
  * while being read is refused too. The descriptor is always closed. Never
  * throws.
+ *
+ * `opts.noFollow` adds `O_NOFOLLOW` to the open: a path that is a symbolic
+ * link (whatever it points at, a dangling link included) is refused as
+ * not-regular by the open itself (`ELOOP`), with no earlier `lstat` for a
+ * swap to race. Off by default, so every hook read keeps following links
+ * exactly as before; `harness approve understanding` turns it on.
  */
-export declare function readReportFileBounded(filePath: string): BoundedReportRead;
+export declare function readReportFileBounded(filePath: string, opts?: {
+    noFollow?: boolean;
+}): BoundedReportRead;
 /** Why a report file has no canonical hash. */
 export type UnhashableReportReason = ReportFileReadFailure | "not-json-object" | "too-deep";
 export type ReportFileHash = {
@@ -356,9 +397,13 @@ export type ReportFileHash = {
  * any of these (the `detail` is its message); the gate-read scan counts such
  * a file as one that matches nothing. Never throws.
  */
-export declare function hashReportFile(filePath: string): ReportFileHash;
+export declare function hashReportFile(filePath: string, opts?: {
+    noFollow?: boolean;
+}): ReportFileHash;
 /** Canonical hash of the report file at `filePath` ({@link hashReportFile}); null when it has none. */
-export declare function canonicalReportHashOfFile(filePath: string): string | null;
+export declare function canonicalReportHashOfFile(filePath: string, opts?: {
+    noFollow?: boolean;
+}): string | null;
 /** Marker kind whose signed report hash the gate checks. */
 export type ApprovalMarkerKind = "task" | "session";
 /** One matched marker's signed `reportContentHash`, tagged with its kind. */
@@ -411,11 +456,25 @@ export type ApprovedReportHashVerification = {
  * the "no report file" allow, the same as before this check existed. The
  * marker and the operator's approval itself are untouched in both cases;
  * only the audit trail loses its claim to be the approved content. (3) The
- * cap bounds each file, not their number: the scan time grows with the
- * total volume of report files, so an agent that plants hundreds of
- * megabytes of files just under the cap can still push one scan past the
- * hook's time budget, which the runtime treats as a non-blocking error (the
- * same allow as before this check existed).
+ * cap bounds each file, not their number, so the scan charges every `*.json`
+ * entry at least `MIN_SCAN_ENTRY_COST_BYTES` against `MAX_HASH_SCAN_BYTES`
+ * (bytes read or the floor, whichever is larger, whatever the read returned):
+ * past the budget the check denies with the mismatch reason (fail closed).
+ * That bounds the entries opened (8192) and the bytes read (about 32 MiB, the
+ * last file read may add up to the 1 MiB per-file cap). Three costs remain.
+ * A legitimate approval whose report sits behind that much newer report data
+ * (by name, descending) is denied; re-approving writes a new, newest report
+ * and recovers only when the newer entries are real reports: planted `*.json`
+ * names that sort after the timestamped report names (for example names
+ * starting with a letter) stay newer than any new report and keep denying
+ * until removed. The `readdir` plus name sort of the directory itself are not
+ * charged, so a directory of hundreds of thousands of entries still costs that
+ * listing before the scan starts. And the hash scan is not the whole hook:
+ * the evidence read that follows a refused marker (shared with the no-marker
+ * path, `listPersistedReportsBounded`) still opens and parses every `*.json`
+ * entry, so the hook as a whole is still unbounded by entry count and a
+ * large planted directory runs it past the PreToolUse budget (an allow); a
+ * follow-up task bounds that read.
  *
  * Removing the approved report while other report files remain is a deny:
  * nothing on disk carries the signed content any more. `harness gc --apply`
@@ -428,8 +487,8 @@ export type ApprovedReportHashVerification = {
  * fallback is consulted only when the primary fails the check, so a task
  * marker signed for another report does not hide a session marker that
  * verifies. Unchanged behaviour: a null hash on the accepted marker (no
- * report resolved, or `--force` over a report the producer could not hash:
- * too deeply nested or over the size cap) and a reports directory with no
+ * report resolved, or `--force` over a report nested too deeply to hash,
+ * never one over the size cap) and a reports directory with no
  * `*.json` entry at all both allow. A forced approval of a hashable report
  * signs its hash and is checked like any other.
  *
@@ -439,3 +498,55 @@ export type ApprovedReportHashVerification = {
  * value, so nothing in it needs sanitising.
  */
 export declare function verifyApprovedReportHash(reportsDir: string, primary: MarkerReportBinding, fallback?: MarkerReportBinding | null): ApprovedReportHashVerification;
+/**
+ * Why a `*.json` entry of the reports directory is absent from a bounded
+ * listing: it could not be read through {@link readReportFileBounded}.
+ */
+export interface SkippedReportEntry {
+    filePath: string;
+    reason: ReportFileReadFailure;
+    detail: string;
+}
+/**
+ * {@link listPersistedReports} for every read a PreToolUse hook (or the
+ * PostToolUse boundary) makes of the reports directory. The directory holds
+ * files the gated agent can write, so every entry is opened once through
+ * {@link readReportFileBounded}: non-blocking, typed and sized by `fstat` on
+ * the open descriptor, read through it. A `*.json` entry that is not a
+ * regular file (a FIFO, a directory, a device, a symlink to one of them), is
+ * over `MAX_HASHED_REPORT_BYTES`, cannot be opened or read, or grows while it
+ * is read is left out of `reports`, as if it were not there, and recorded in
+ * `skipped`: it can neither block the hook nor run it out of memory. There is
+ * no separate stat of the path (a symlink flipped to a FIFO between that stat
+ * and the read used to hang the read), and the modification time comes from
+ * the same descriptor.
+ *
+ * A caller that must not let the selection fall back to an older report when
+ * a newer one is unreadable (the auto-approval precondition) declines when
+ * `skipped` is not empty. The operator commands read through this listing as
+ * well, so a planted oversized or non-regular entry cannot crash or hang
+ * them, and they still see it: `harness approve understanding` refuses
+ * while `skipped` is not empty (it passes `refuseSymlinks`, which also
+ * refuses a symbolic link at the open, whatever it points at), and
+ * `harness gc` reports each skipped entry and leaves it in place.
+ *
+ * Placement: this block sits at the end of the file, and
+ * {@link readPersistedReport} takes the already-read text (`boundedRaw`), so
+ * the line numbers the decision record
+ * docs/decisions/2026-08-27-ug-auto-mode-approval.md cites in this file stay
+ * put (tests/decisions-citations-resolve.test.ts pins them).
+ */
+export declare function listPersistedReportsBoundedWithSkips(dir: string, opts?: {
+    refuseSymlinks?: boolean;
+}): {
+    reports: PersistedReport[];
+    skipped: SkippedReportEntry[];
+};
+/**
+ * {@link listPersistedReportsBoundedWithSkips} without the skipped entries,
+ * for the callers that treat a skipped entry as no evidence
+ * ({@link checkPersistedReport}, {@link expirePersistedReport}). Expiry acts
+ * on the newest report that was within the cap, so an oversized newest
+ * approved report is left as it is and the next in-cap one is expired.
+ */
+export declare function listPersistedReportsBounded(dir: string): PersistedReport[];

package/dist/policy-packs/builtin/understanding-before-execution/persisted-reports.js

@@ -65,10 +65,10 @@ function parseFilenameIsoMs(name) {
     const ms = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`);
     return Number.isNaN(ms) ? null : ms;
 }
-function readPersistedReport(filePath, mtimeMs) {
+function readPersistedReport(filePath, mtimeMs, boundedRaw) {
     let raw;
     try {
-        raw = fs.readFileSync(filePath, "utf8");
+        raw = boundedRaw ?? fs.readFileSync(filePath, "utf8");
     }
     catch {
         return null;
@@ -95,16 +95,16 @@ function readPersistedReport(filePath, mtimeMs) {
 }
 /**
  * List persisted reports under `dir`, newest-first by creation time
- * (JSON `createdAt`, falling back to the filename ISO prefix, falling
- * back to mtime). Missing directory returns []. Any I/O error on a
- * single file is silently skipped; the caller falls through to the
- * ledger result.
+ * (JSON `createdAt`, then the filename ISO prefix, then mtime). Missing
+ * directory returns []; an I/O error on a single file skips it. Reads each
+ * regular file IN FULL, so it must not list the agent-writable reports
+ * directory (use {@link listPersistedReportsBoundedWithSkips}); no `src`
+ * caller remains, it stays for its tests and the pack's export surface.
  *
  * Creation time, NOT mtime, is the sort key: `harness approve
  * understanding` rewrites the report it flips, which bumps mtime and
  * made an old just-approved report sort as the freshest
- * (harness-discovery C1). mtime survives only as the last-resort
- * fallback for files that carry neither timestamp.
+ * (harness-discovery C1). mtime is the last-resort fallback.
  */
 export function listPersistedReports(dir) {
     let names;
@@ -296,7 +296,7 @@ export function sanitizeDetailValue(value) {
  * does not escalate into a session-breaking hook failure.
  */
 export function expirePersistedReport(reportsDir, sessionId, now = new Date(), trigger) {
-    const reports = listPersistedReports(reportsDir);
+    const reports = listPersistedReportsBounded(reportsDir);
     if (reports.length === 0) {
         return { ok: false, reason: `no reports under ${reportsDir}` };
     }
@@ -313,13 +313,12 @@ export function expirePersistedReport(reportsDir, sessionId, now = new Date(), t
             reason: `latest report ${sanitizeDetailValue(path.basename(latest.filePath))} already has approvalStatus=${sanitizeDetailValue(latest.approvalStatus ?? "<missing>")}, nothing to expire`,
         };
     }
-    let raw;
-    try {
-        raw = fs.readFileSync(latest.filePath, "utf8");
-    }
-    catch (err) {
-        return { ok: false, reason: `failed to read ${latest.filePath}: ${err.message}` };
+    // Bounded like the listing: the file may have been swapped since.
+    const read = readReportFileBounded(latest.filePath);
+    if (!read.ok) {
+        return { ok: false, reason: `failed to read ${latest.filePath}: ${read.detail}` };
     }
+    const raw = read.raw;
     let parsed;
     try {
         parsed = JSON.parse(raw);
@@ -366,7 +365,7 @@ export function expirePersistedReport(reportsDir, sessionId, now = new Date(), t
  * `understanding-gate approve` CLI, which writes no signed marker).
  */
 export function checkPersistedReport(reportsDir, sessionId) {
-    const reports = listPersistedReports(reportsDir);
+    const reports = listPersistedReportsBounded(reportsDir);
     if (reports.length === 0) {
         return {
             claimsApproved: false,
@@ -457,6 +456,38 @@ const MAX_CANONICAL_REPORT_DEPTH = 64;
  * producers refuse to approve such a report.
  */
 export const MAX_HASHED_REPORT_BYTES = 1024 * 1024;
+/**
+ * Budget the gate-read hash scan spends before it gives up (32 MiB), charged
+ * per `*.json` entry as the larger of the bytes read and
+ * {@link MIN_SCAN_ENTRY_COST_BYTES}. The per-file cap bounds one file, not
+ * their number: 160 planted 1 MiB key-heavy files took 15.9 to 17.6 s of scan
+ * time, past the 15 s PreToolUse budget, and a hook past its budget is a
+ * non-blocking error for the runtime (an allow). Charging bytes alone left the
+ * entry count open: entries that cost no bytes (tiny files, directories named
+ * `*.json`, files over the cap, unreadable ones) still cost an open each, and
+ * 400k tiny files took about 22 s of CPU. A scan that spent the budget without
+ * finding every wanted hash stops and the check fails closed with the mismatch
+ * reason. With the floor the scan opens at most 8192 entries and reads about
+ * 32 MiB (the last file read may add up to the 1 MiB per-file cap), whichever
+ * the entries are. Real reports are a few kilobytes, so the budget covers
+ * thousands of them. The scan reads the newest file first, which is where the
+ * approved report usually is.
+ *
+ * This bounds the hash scan only, not the hook as a whole by entry count: the
+ * evidence read that follows a refused marker (shared with the no-marker path,
+ * `listPersistedReportsBounded`) still opens and parses every `*.json` entry,
+ * so a directory of hundreds of thousands of planted entries still takes the
+ * hook past the PreToolUse budget, which the runtime treats as an allow. A
+ * follow-up task bounds that read.
+ */
+export const MAX_HASH_SCAN_BYTES = 32 * 1024 * 1024;
+/**
+ * Least a `*.json` entry is charged against {@link MAX_HASH_SCAN_BYTES}
+ * whatever the read returned (4 KiB, about one real report), so entries that
+ * read nothing or little still spend the budget at a rate that bounds their
+ * count: 32 MiB / 4 KiB = 8192 entries.
+ */
+export const MIN_SCAN_ENTRY_COST_BYTES = 4096;
 /**
  * Iterative walk over the arrays and objects of `value` (the value itself is
  * level 1) that stops at the first one nested deeper than `max` levels.
@@ -530,6 +561,12 @@ export function canonicalReportHash(report) {
         return null;
     return sha256Hex(JSON.stringify(sortKeysDeep(kept)));
 }
+/** What `readReportFileBounded` returns for a symbolic link when `noFollow` is set. */
+const SYMLINK_REFUSED = {
+    ok: false,
+    reason: "not-regular",
+    detail: "a symbolic link, not a regular file",
+};
 function errorCode(err) {
     const code = err?.code;
     return typeof code === "string" ? code : String(err);
@@ -548,13 +585,23 @@ function errorCode(err) {
  * (never more than the cap plus one byte); a file that grows into that byte
  * while being read is refused too. The descriptor is always closed. Never
  * throws.
+ *
+ * `opts.noFollow` adds `O_NOFOLLOW` to the open: a path that is a symbolic
+ * link (whatever it points at, a dangling link included) is refused as
+ * not-regular by the open itself (`ELOOP`), with no earlier `lstat` for a
+ * swap to race. Off by default, so every hook read keeps following links
+ * exactly as before; `harness approve understanding` turns it on.
  */
-export function readReportFileBounded(filePath) {
+export function readReportFileBounded(filePath, opts = {}) {
     let fd;
     try {
-        fd = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY |
+            fs.constants.O_NONBLOCK |
+            (opts.noFollow === true ? fs.constants.O_NOFOLLOW : 0));
     }
     catch (err) {
+        if (opts.noFollow === true && errorCode(err) === "ELOOP")
+            return SYMLINK_REFUSED;
         return { ok: false, reason: "unreadable", detail: `could not be opened (${errorCode(err)})` };
     }
     try {
@@ -578,7 +625,7 @@ export function readReportFileBounded(filePath) {
         }
         if (total > stat.size)
             return { ok: false, reason: "grew", detail: "grew while being read" };
-        return { ok: true, raw: buf.toString("utf8", 0, total) };
+        return { ok: true, raw: buf.toString("utf8", 0, total), mtimeMs: stat.mtimeMs };
     }
     catch (err) {
         return { ok: false, reason: "unreadable", detail: `could not be read (${errorCode(err)})` };
@@ -600,11 +647,15 @@ export function readReportFileBounded(filePath) {
  * any of these (the `detail` is its message); the gate-read scan counts such
  * a file as one that matches nothing. Never throws.
  */
-export function hashReportFile(filePath) {
-    const read = readReportFileBounded(filePath);
+export function hashReportFile(filePath, opts = {}) {
+    const read = readReportFileBounded(filePath, opts);
     if (!read.ok)
         return read;
-    const parsed = safeJsonParse(read.raw);
+    return hashReportText(read.raw);
+}
+/** {@link hashReportFile} for text already read through {@link readReportFileBounded}. */
+function hashReportText(raw) {
+    const parsed = safeJsonParse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         return { ok: false, reason: "not-json-object", detail: "not a JSON object" };
     }
@@ -615,24 +666,31 @@ export function hashReportFile(filePath) {
     return { ok: true, hash };
 }
 /** Canonical hash of the report file at `filePath` ({@link hashReportFile}); null when it has none. */
-export function canonicalReportHashOfFile(filePath) {
-    const hashed = hashReportFile(filePath);
+export function canonicalReportHashOfFile(filePath, opts = {}) {
+    const hashed = hashReportFile(filePath, opts);
     return hashed.ok ? hashed.hash : null;
 }
 /**
  * Hash every `*.json` entry of `dir` (any session, any `approvalStatus`)
- * through {@link canonicalReportHashOfFile} and report which of the `wanted`
+ * through {@link readReportFileBounded} and report which of the `wanted`
  * hashes occur. Stops as soon as every wanted hash was found. Every entry
  * counts as a report file; one that is not a regular file, is larger than
  * `MAX_HASHED_REPORT_BYTES`, cannot be opened or read, grows while read, is
- * not a JSON object, or nests too deeply matches nothing. The cost is linear
- * in the number and size of the report files (each read at most up to the
- * cap), and the usual allow path scans nearly all of them: the directory
- * listing comes back in name order and report names start with a timestamp,
- * so the approved (newest) report tends to come last.
+ * not a JSON object, or nests too deeply matches nothing. Entries are taken
+ * in descending name order, newest first (report names start with a
+ * timestamp), so the approved report is usually the first file read. Every
+ * entry, whatever its read returned, is charged the larger of the bytes read
+ * and `MIN_SCAN_ENTRY_COST_BYTES`; once the charges reach `MAX_HASH_SCAN_BYTES`
+ * with a wanted hash still unfound the scan stops and sets `budgetExhausted`,
+ * so the number of entries opened and the bytes read (about 32 MiB, the last
+ * file read may add up to the per-file cap) are both bounded by the budget,
+ * however many entries the directory holds. The `readdir` and the name sort
+ * of the directory itself are outside the budget, and so is the evidence read
+ * a refused marker falls through to (`listPersistedReportsBounded`), which
+ * still opens every `*.json` entry.
  */
 function scanReportHashes(dir, wanted) {
-    const scan = { files: 0, matched: new Set() };
+    const scan = { files: 0, matched: new Set(), budgetExhausted: false };
     let names;
     try {
         names = fs.readdirSync(dir);
@@ -640,14 +698,21 @@ function scanReportHashes(dir, wanted) {
     catch {
         return scan;
     }
+    names = names.filter((name) => name.endsWith(".json")).sort().reverse();
+    let hashedBytes = 0; // budget charged so far, see the charge below
     for (const name of names) {
-        if (!name.endsWith(".json"))
-            continue;
-        const full = path.join(dir, name);
         scan.files += 1;
-        const hash = canonicalReportHashOfFile(full);
-        if (hash !== null && wanted.has(hash)) {
-            scan.matched.add(hash);
+        if (hashedBytes >= MAX_HASH_SCAN_BYTES) {
+            scan.budgetExhausted = true;
+            break;
+        }
+        const read = readReportFileBounded(path.join(dir, name));
+        hashedBytes += Math.max(read.ok ? Buffer.byteLength(read.raw) : 0, MIN_SCAN_ENTRY_COST_BYTES);
+        if (!read.ok)
+            continue;
+        const hashed = hashReportText(read.raw);
+        if (hashed.ok && wanted.has(hashed.hash)) {
+            scan.matched.add(hashed.hash);
             if (scan.matched.size === wanted.size)
                 break;
         }
@@ -692,11 +757,25 @@ function scanReportHashes(dir, wanted) {
  * the "no report file" allow, the same as before this check existed. The
  * marker and the operator's approval itself are untouched in both cases;
  * only the audit trail loses its claim to be the approved content. (3) The
- * cap bounds each file, not their number: the scan time grows with the
- * total volume of report files, so an agent that plants hundreds of
- * megabytes of files just under the cap can still push one scan past the
- * hook's time budget, which the runtime treats as a non-blocking error (the
- * same allow as before this check existed).
+ * cap bounds each file, not their number, so the scan charges every `*.json`
+ * entry at least `MIN_SCAN_ENTRY_COST_BYTES` against `MAX_HASH_SCAN_BYTES`
+ * (bytes read or the floor, whichever is larger, whatever the read returned):
+ * past the budget the check denies with the mismatch reason (fail closed).
+ * That bounds the entries opened (8192) and the bytes read (about 32 MiB, the
+ * last file read may add up to the 1 MiB per-file cap). Three costs remain.
+ * A legitimate approval whose report sits behind that much newer report data
+ * (by name, descending) is denied; re-approving writes a new, newest report
+ * and recovers only when the newer entries are real reports: planted `*.json`
+ * names that sort after the timestamped report names (for example names
+ * starting with a letter) stay newer than any new report and keep denying
+ * until removed. The `readdir` plus name sort of the directory itself are not
+ * charged, so a directory of hundreds of thousands of entries still costs that
+ * listing before the scan starts. And the hash scan is not the whole hook:
+ * the evidence read that follows a refused marker (shared with the no-marker
+ * path, `listPersistedReportsBounded`) still opens and parses every `*.json`
+ * entry, so the hook as a whole is still unbounded by entry count and a
+ * large planted directory runs it past the PreToolUse budget (an allow); a
+ * follow-up task bounds that read.
  *
  * Removing the approved report while other report files remain is a deny:
  * nothing on disk carries the signed content any more. `harness gc --apply`
@@ -709,8 +788,8 @@ function scanReportHashes(dir, wanted) {
  * fallback is consulted only when the primary fails the check, so a task
  * marker signed for another report does not hide a session marker that
  * verifies. Unchanged behaviour: a null hash on the accepted marker (no
- * report resolved, or `--force` over a report the producer could not hash:
- * too deeply nested or over the size cap) and a reports directory with no
+ * report resolved, or `--force` over a report nested too deeply to hash,
+ * never one over the size cap) and a reports directory with no
  * `*.json` entry at all both allow. A forced approval of a hashable report
  * signs its hash and is checked like any other.
  *
@@ -744,7 +823,75 @@ export function verifyApprovedReportHash(reportsDir, primary, fallback = null) {
     return {
         ok: false,
         detail: `no report in the reports directory matches the content the ${kinds} signed for ` +
-            `(the approved report was changed or removed after approval); re-run \`harness approve understanding\``,
+            `(the approved report was changed or removed after approval); re-run \`harness approve understanding\`` +
+            (scan.budgetExhausted
+                ? " (the reports directory holds more report data than the gate-read scan budget covers)"
+                : ""),
     };
 }
+/**
+ * {@link listPersistedReports} for every read a PreToolUse hook (or the
+ * PostToolUse boundary) makes of the reports directory. The directory holds
+ * files the gated agent can write, so every entry is opened once through
+ * {@link readReportFileBounded}: non-blocking, typed and sized by `fstat` on
+ * the open descriptor, read through it. A `*.json` entry that is not a
+ * regular file (a FIFO, a directory, a device, a symlink to one of them), is
+ * over `MAX_HASHED_REPORT_BYTES`, cannot be opened or read, or grows while it
+ * is read is left out of `reports`, as if it were not there, and recorded in
+ * `skipped`: it can neither block the hook nor run it out of memory. There is
+ * no separate stat of the path (a symlink flipped to a FIFO between that stat
+ * and the read used to hang the read), and the modification time comes from
+ * the same descriptor.
+ *
+ * A caller that must not let the selection fall back to an older report when
+ * a newer one is unreadable (the auto-approval precondition) declines when
+ * `skipped` is not empty. The operator commands read through this listing as
+ * well, so a planted oversized or non-regular entry cannot crash or hang
+ * them, and they still see it: `harness approve understanding` refuses
+ * while `skipped` is not empty (it passes `refuseSymlinks`, which also
+ * refuses a symbolic link at the open, whatever it points at), and
+ * `harness gc` reports each skipped entry and leaves it in place.
+ *
+ * Placement: this block sits at the end of the file, and
+ * {@link readPersistedReport} takes the already-read text (`boundedRaw`), so
+ * the line numbers the decision record
+ * docs/decisions/2026-08-27-ug-auto-mode-approval.md cites in this file stay
+ * put (tests/decisions-citations-resolve.test.ts pins them).
+ */
+export function listPersistedReportsBoundedWithSkips(dir, opts = {}) {
+    let names = [];
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        // No readable directory: no reports.
+    }
+    const reports = [];
+    const skipped = [];
+    for (const name of names.filter((n) => n.endsWith(".json"))) {
+        const full = path.join(dir, name);
+        // `refuseSymlinks` opens with O_NOFOLLOW, so a link is recorded as skipped
+        // by the open itself and no earlier lstat can race a swap.
+        const read = readReportFileBounded(full, { noFollow: opts.refuseSymlinks === true });
+        if (!read.ok) {
+            skipped.push({ filePath: full, reason: read.reason, detail: read.detail });
+            continue;
+        }
+        const report = readPersistedReport(full, read.mtimeMs, read.raw);
+        if (report !== null)
+            reports.push(report);
+    }
+    reports.sort((a, b) => b.createdAtMs - a.createdAtMs);
+    return { reports, skipped };
+}
+/**
+ * {@link listPersistedReportsBoundedWithSkips} without the skipped entries,
+ * for the callers that treat a skipped entry as no evidence
+ * ({@link checkPersistedReport}, {@link expirePersistedReport}). Expiry acts
+ * on the newest report that was within the cap, so an oversized newest
+ * approved report is left as it is and the next in-cap one is expired.
+ */
+export function listPersistedReportsBounded(dir) {
+    return listPersistedReportsBoundedWithSkips(dir).reports;
+}
 //# sourceMappingURL=persisted-reports.js.map