@opengsd/gsd-core 1.10.0 → 1.12.0

package/gsd-core/bin/lib/broken-windows.cjs

@@ -20,9 +20,9 @@
  *   ---
  *   # Broken Windows Ledger
  *   <human-readable prose>
- *   ```json
+ *   ````json
  *   [ <entries array, canonical JSON> ]
- *   ```
+ *   ````
  *
  * Frontmatter holds scalar counts (the FAST path the ship gate reads via jq
  * without parsing JSON). The JSON code block is the AUTHORITATIVE entries
@@ -56,6 +56,8 @@ exports.markWaived = markWaived;
 exports.markFixed = markFixed;
 exports.parseLedger = parseLedger;
 exports.renderLedger = renderLedger;
+exports.renderTable = renderTable;
+exports.extractTableRegion = extractTableRegion;
 exports.cmdWindowsStatus = cmdWindowsStatus;
 exports.cmdWindowsAppend = cmdWindowsAppend;
 exports.cmdWindowsWaive = cmdWindowsWaive;
@@ -84,6 +86,10 @@ exports.REASON = Object.freeze({
     WINDOWS_INVALID_ID: 'windows_invalid_id',
     WINDOWS_APPEND_MISSING_FIELD: 'windows_append_missing_field',
     WINDOWS_USAGE: 'windows_usage',
+    // #3689: the rendered markdown table disagreed with the fenced JSON (the
+    // sole source of truth) at the pre-write seam — refuse rather than silently
+    // reconcile by overwriting the operator's hand-edit or dropping a row.
+    WINDOWS_LEDGER_TABLE_DRIFT: 'windows_ledger_table_drift',
 });
 /** Allowed window kinds. Aligned with the issue's enumerated sources. */
 exports.KINDS = Object.freeze([
@@ -286,6 +292,79 @@ function markFixed(ledger, id, opts = { now: new Date().toISOString() }) {
 const JSON_FENCE_OPEN = '````json';
 const JSON_FENCE_CLOSE = '````';
 const FORBIDDEN_BACKTICK_RUN = '````';
+/**
+ * #3689: the ledger table's fixed header row literal. `renderTable` emits it
+ * on both the empty and non-empty branches; `extractTableRegion` anchors on
+ * it to bound the table region. Hoisted to one constant so the two surfaces
+ * cannot drift (see "Generative Fix Divergence" — CONTRIBUTING.md).
+ */
+const TABLE_HEADER_LINE = '| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |';
+/**
+ * Locate the entries JSON block by CommonMark fence rules rather than a fixed
+ * literal width. Both parseJsonBlock (strict) and writeLedgerAtomic's #2893
+ * prose preservation (lenient) go through this one function so read tolerance
+ * and splice tolerance cannot drift (#3657). A backtick-only line can never
+ * occur inside a body: JSON.stringify renders strings single-line-escaped, so
+ * an inline run inside a description is never a close-fence candidate.
+ *
+ * Disambiguation (#3657 security review): an entry description may contain
+ * newlines and 3-backtick runs (append validation rejects only 4+ runs), and
+ * renderTable renders descriptions into the prose ABOVE the JSON block — so
+ * hostile or accidental text can plant a second json fence above the real
+ * one. renderLedger always emits the entries block as the FINAL fenced
+ * section, so spans are scanned in REVERSE: prefer the latest span whose
+ * entries length equals the frontmatter total_count (the real block always
+ * satisfies it — parseLedger cross-checks that invariant), else the latest
+ * span whose body is a JSON array, else the first span so corrupt bodies keep
+ * their fail-closed parse errors. A mirror planted below with identical
+ * length and identical entries is indistinguishable by construction — and
+ * harmless.
+ */
+function locateJsonBlock(raw, expectedTotal) {
+    const spans = [];
+    for (const open of raw.matchAll(/^(`{3,})json[ \t]*\r?$/gm)) {
+        const width = open[1].length;
+        const bodyStart = (open.index ?? 0) + open[0].length;
+        for (const close of raw.slice(bodyStart).matchAll(/^(`{3,})[ \t]*\r?$/gm)) {
+            if (close[1].length < width)
+                continue;
+            const bodyEnd = bodyStart + (close.index ?? 0);
+            const closeLineEnd = raw.indexOf('\n', bodyEnd);
+            spans.push({
+                bodyStart,
+                bodyEnd,
+                afterClose: closeLineEnd === -1 ? raw.length : closeLineEnd + 1,
+            });
+            break; // CommonMark: the first qualifying close ends this fence block
+        }
+    }
+    if (spans.length === 0) {
+        const sawOpen = /^(`{3,})json[ \t]*\r?$/m.test(raw);
+        return { ok: false, reason: sawOpen ? 'unterminated' : 'missing-open' };
+    }
+    const parseBody = (s) => {
+        try {
+            return JSON.parse(raw.slice(s.bodyStart, s.bodyEnd).trim());
+        }
+        catch {
+            return undefined;
+        }
+    };
+    if (expectedTotal !== undefined) {
+        for (let i = spans.length - 1; i >= 0; i--) {
+            const body = parseBody(spans[i]);
+            if (Array.isArray(body) && body.length === expectedTotal) {
+                return { ok: true, span: spans[i] };
+            }
+        }
+    }
+    for (let i = spans.length - 1; i >= 0; i--) {
+        if (Array.isArray(parseBody(spans[i]))) {
+            return { ok: true, span: spans[i] };
+        }
+    }
+    return { ok: true, span: spans[0] };
+}
 /**
  * Minimal strict frontmatter parser for flat scalar keys. Only supports the
  * shape this module emits: `key: <number|string>` per line. Throws on any
@@ -333,16 +412,14 @@ function parseFrontmatterStrict(raw) {
     }
     return out;
 }
-function parseJsonBlock(raw) {
-    const start = raw.indexOf(JSON_FENCE_OPEN);
-    if (start === -1) {
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, 'Ledger missing JSON code block for entries.');
-    }
-    const end = raw.indexOf(JSON_FENCE_CLOSE, start + JSON_FENCE_OPEN.length);
-    if (end === -1) {
-        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, 'Ledger JSON code block not terminated.');
+function parseJsonBlock(raw, expectedTotal) {
+    const span = locateJsonBlock(raw, expectedTotal);
+    if (!span.ok) {
+        throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, span.reason === 'missing-open'
+            ? 'Ledger missing JSON code block for entries.'
+            : 'Ledger JSON code block not terminated.');
     }
-    const jsonText = raw.slice(start + JSON_FENCE_OPEN.length, end).trim();
+    const jsonText = raw.slice(span.span.bodyStart, span.span.bodyEnd).trim();
     let parsed;
     try {
         parsed = JSON.parse(jsonText);
@@ -415,7 +492,7 @@ function parseLedger(raw) {
     if (typeof fm.last_updated !== 'string') {
         throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger last_updated must be a string; got ${JSON.stringify(fm.last_updated)}.`);
     }
-    const entries = parseJsonBlock(raw);
+    const entries = parseJsonBlock(raw, typeof fm.total_count === 'number' ? fm.total_count : undefined);
     const ledger = {
         schema_version: exports.SCHEMA_VERSION,
         open_count: typeof fm.open_count === 'number' ? fm.open_count : 0,
@@ -464,13 +541,13 @@ function renderLedger(ledger) {
 function renderTable(entries) {
     if (entries.length === 0) {
         return [
-            '| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |',
+            TABLE_HEADER_LINE,
             '|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|',
             '| _(none)_ |  |  |  |  | _No windows recorded._ |  |  |  |  |',
         ].join('\n');
     }
     const rows = [
-        '| id | phase | kind | file | line | description | status | reason | recorded_at | resolved_at |',
+        TABLE_HEADER_LINE,
         '|----|-------|------|------|------|-------------|--------|--------|-------------|-------------|',
     ];
     for (const e of entries) {
@@ -491,6 +568,119 @@ function renderTable(entries) {
     }
     return rows.join('\n');
 }
+/**
+ * #3689: extract the exact markdown table region a rendered ledger emits —
+ * the text `renderTable` produced, byte-for-byte — from a raw ledger file.
+ * Used by `writeLedgerAtomic`'s drift guard to compare the on-disk table
+ * against `renderTable(<on-disk JSON entries>)` without a table parser.
+ *
+ * Locates the JSON block with the same tolerant `locateJsonBlock` helper the
+ * rest of the module uses (#3657), so a formatter-normalized 3-backtick
+ * fence still resolves. Everything before the opening fence line, with
+ * trailing blank lines dropped, is the candidate region.
+ *
+ * #3689: the region is bounded by finding the LAST occurrence of the fixed
+ * `TABLE_HEADER_LINE` literal (anchored at a line start) within that
+ * candidate text, then taking everything from there through its end — NOT
+ * by scanning backward for a contiguous run of `|`-prefixed lines. A `|`
+ * prefix scan cannot bound the region: `validateDescription` rejects only
+ * empty strings and 4-backtick runs, so a description may contain a raw
+ * `\n`, and `renderTable`'s `cell()` escapes `\` and `|` but not newlines.
+ * Such a description renders a row that physically spans multiple file
+ * lines, and the continuation line does not start with `|` — a prefix scan
+ * either truncates the table or, when the row's tail is the last pre-fence
+ * line, returns null immediately, bricking every subsequent write with
+ * `WINDOWS_LEDGER_TABLE_DRIFT` on a ledger nobody hand-edited. Anchoring on
+ * the header instead includes any such row whole, so `renderTable`
+ * regenerates byte-identical text for it and the drift comparison passes.
+ *
+ * Returns null when the JSON block cannot be located, or no header line is
+ * present.
+ *
+ * `expectedTotal` (#3689 review finding 2) is threaded straight into
+ * `locateJsonBlock` so callers with trailing prose can disambiguate the real
+ * ledger block from an unrelated fenced JSON array a user pasted below the
+ * closing fence — without it, `locateJsonBlock`'s no-hint fallback picks the
+ * LATEST array-shaped span, which is the prose block, not the ledger, and
+ * every drift comparison then binds to the wrong table/JSON pairing.
+ */
+function extractTableRegion(raw, expectedTotal) {
+    const span = locateJsonBlock(raw, expectedTotal);
+    if (!span.ok)
+        return null;
+    // bodyStart sits right before the newline (or CR) ending the opening fence
+    // line; walk back to the start of that line.
+    const fenceLineStart = raw.lastIndexOf('\n', span.span.bodyStart - 1) + 1;
+    const before = raw.slice(0, fenceLineStart).replace(/\r\n/g, '\n');
+    let trimmedEnd = before.length;
+    while (trimmedEnd > 0 && before[trimmedEnd - 1] === '\n') {
+        trimmedEnd--;
+    }
+    const candidate = before.slice(0, trimmedEnd);
+    // Find the LAST occurrence of TABLE_HEADER_LINE anchored at a line start —
+    // a plain string scan rather than a regex, since the module is a leaf
+    // (imports only node:fs/node:path) and cannot pull in the shared
+    // escapeRegex() helper for a one-off fixed-literal search.
+    let headerIndex = -1;
+    let searchFrom = candidate.length;
+    for (;;) {
+        const idx = candidate.lastIndexOf(TABLE_HEADER_LINE, searchFrom);
+        if (idx === -1)
+            break;
+        const atLineStart = idx === 0 || candidate[idx - 1] === '\n';
+        const atLineEnd = idx + TABLE_HEADER_LINE.length === candidate.length ||
+            candidate[idx + TABLE_HEADER_LINE.length] === '\n';
+        if (atLineStart && atLineEnd) {
+            headerIndex = idx;
+            break;
+        }
+        // #3689: lastIndexOf clamps a negative position into [0, length] per
+        // spec, so `searchFrom = -1` would re-search from 0 and re-find the same
+        // rejected match at idx===0 forever. Stop explicitly once there is
+        // nowhere left to search — this makes the bound strictly decrease each
+        // iteration, so the loop terminates within candidate.length steps.
+        if (idx === 0)
+            break;
+        searchFrom = idx - 1;
+    }
+    if (headerIndex === -1)
+        return null;
+    return candidate.slice(headerIndex);
+}
+/**
+ * #3689: diff two `renderTable` outputs by row id (the first cell of each
+ * data row), skipping the header + separator lines (always exactly two).
+ * A row whose line text differs between the two tables, or that is present
+ * in only one of them, contributes its id to the result — this is what lets
+ * the drift-guard error message name the specific drifted/table-only row(s)
+ * rather than just saying "the table disagrees".
+ */
+function diffTableRowIds(expectedTable, actualTable) {
+    const rowId = (line) => (line.split('|')[1] ?? '').trim();
+    const dataRows = (table) => {
+        const lines = table.split('\n');
+        const map = new Map();
+        for (let i = 2; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line.startsWith('|'))
+                continue;
+            map.set(rowId(line), line);
+        }
+        return map;
+    };
+    const expectedRows = dataRows(expectedTable);
+    const actualRows = dataRows(actualTable);
+    const ids = new Set();
+    for (const [id, line] of expectedRows) {
+        if (actualRows.get(id) !== line)
+            ids.add(id);
+    }
+    for (const id of actualRows.keys()) {
+        if (!expectedRows.has(id))
+            ids.add(id);
+    }
+    return Array.from(ids).sort();
+}
 // ─── I/O entry points ──────────────────────────────────────────────────────
 function ledgerPath(cwd) {
     return node_path_1.default.join(cwd, '.planning', exports.LEDGER_FILE_NAME);
@@ -569,23 +759,111 @@ function writeLedgerAtomic(cwd, ledger) {
     // trailing prose that users may have written below the closing fence.
     // Without this, every append/waive/fixed silently destroys that prose.
     let trailingProse = '';
+    // #3689: read the pre-image once into `existing` outside the catch, rather
+    // than doing every subsequent step inside a bare try/catch, so that a
+    // WindowsError thrown by the drift guard below propagates instead of being
+    // swallowed by the ENOENT handler meant only for "no ledger yet".
+    let existing = null;
     try {
-        const existing = node_fs_1.default.readFileSync(p, 'utf8');
-        // #2893: search for the CLOSING fence starting AFTER the opening fence,
-        // mirroring parseJsonBlock — indexOf(JSON_FENCE_CLOSE) alone would match
-        // the opening fence ('````json' starts with '````').
-        const openIdx = existing.indexOf(JSON_FENCE_OPEN);
-        if (openIdx !== -1) {
-            const fenceEnd = existing.indexOf(JSON_FENCE_CLOSE, openIdx + JSON_FENCE_OPEN.length);
-            if (fenceEnd !== -1) {
-                const afterFence = existing.slice(fenceEnd + JSON_FENCE_CLOSE.length);
-                // Drop leading newlines; keep the rest as prose.
-                trailingProse = afterFence.replace(/^\n+/, '');
-            }
+        existing = node_fs_1.default.readFileSync(p, 'utf8');
+    }
+    catch (e) {
+        // #1950-H2 / #3689: ENOENT is the only "no ledger yet" case — mirror
+        // readLedgerOrNull's discipline exactly. A bare catch here would let
+        // EACCES/EIO/ENOTDIR/etc. fall through as "no pre-image", silently
+        // skipping BOTH the #2893 prose preservation and the drift guard below
+        // and proceeding to overwrite an unreadable file — a guard bypassable by
+        // making the pre-image unreadable is not a guard.
+        const code = (e && typeof e === 'object' && 'code' in e)
+            ? String(e.code)
+            : '';
+        if (code !== 'ENOENT') {
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Could not read ledger at ${p} (${code || 'unknown fs error'}): ${e.message}.`);
         }
+        // File doesn't exist yet (first write) — no prose to preserve, and
+        // nothing on disk to disagree with, so the drift guard below is skipped.
     }
-    catch {
-        // File doesn't exist yet (first write) — no prose to preserve.
+    if (existing !== null) {
+        // #3689 review finding 2 / #3689 bug discovery: both the #2893 prose
+        // span AND the drift guard below must disambiguate `locateJsonBlock`
+        // against the SAME pre-image ledger block, so this is computed ONCE,
+        // hoisted above both uses. expectedTotal MUST be derived from the
+        // PRE-IMAGE's own frontmatter (never `ledger.total_count`, which is
+        // already post-mutation — e.g. N+1 on an append): #2893 exists precisely
+        // because operators may paste prose below the closing fence, and that
+        // prose can itself contain a fenced JSON array of a different length.
+        // Passing the post-mutation total here (as a since-fixed #3689 review
+        // pass once did for the guard alone) makes locateJsonBlock's expectedTotal
+        // scan find nothing against the pre-image — no span has N+1 entries yet —
+        // so it silently falls through to the no-hint fallback, which binds to
+        // the LATEST array-shaped span: the prose block, not the ledger. Left
+        // unfixed, that means the #2893 prose-preservation span itself would
+        // resolve to the prose fence's `afterClose`, silently dropping
+        // everything between the real ledger block and the prose block —
+        // including the operator's own prose ABOVE that array — on every
+        // append. This is exactly the failure #2893 was written to prevent,
+        // reintroduced through the disambiguation hint; it is caught here by
+        // deriving the hint from the pre-image, not the post-mutation ledger,
+        // for BOTH call sites below. If the pre-image frontmatter cannot be
+        // parsed unambiguously, that is itself the ambiguous case — fail closed
+        // rather than falling back to the no-hint scan.
+        let preImageExpectedTotal;
+        try {
+            const preFm = parseFrontmatterStrict(existing);
+            if (typeof preFm.total_count !== 'number' || !Number.isInteger(preFm.total_count)) {
+                throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger frontmatter total_count in ${p} is not an integer; refusing to write — ` +
+                    'the ledger JSON block cannot be identified unambiguously.');
+            }
+            preImageExpectedTotal = preFm.total_count;
+        }
+        catch (e) {
+            if (e instanceof WindowsError)
+                throw e;
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, `Ledger frontmatter in ${p} could not be parsed (${e.message}); refusing ` +
+                'to write — the ledger JSON block cannot be identified unambiguously.');
+        }
+        // #2893: search for the CLOSING fence starting AFTER the opening fence.
+        // The span is located with the same tolerant + disambiguated fence rules
+        // parseJsonBlock uses (#3657), so a formatter-normalized 3-backtick ledger
+        // keeps its prose too — a literal-width search here would find no block
+        // and silently drop everything below the ledger on the next write. The
+        // hint passed here is `preImageExpectedTotal` (pre-image derived, see
+        // above) — NOT `ledger.total_count` — so this binds to the same span the
+        // drift guard below does.
+        const span = locateJsonBlock(existing, preImageExpectedTotal);
+        if (span.ok) {
+            const afterFence = existing.slice(span.span.afterClose);
+            // Drop leading newlines; keep the rest as prose.
+            trailingProse = afterFence.replace(/^(?:\r?\n)+/, '');
+        }
+        // #3689 review finding 2: refuse the write if the on-disk table has
+        // drifted from the on-disk JSON — the source of truth — BEFORE anything
+        // is regenerated. Baseline is the ON-DISK entries, not `ledger` (already
+        // the post-mutation state: an appended entry or a changed status);
+        // comparing against `ledger` would report drift on every legitimate
+        // write.
+        const onDiskEntries = parseJsonBlock(existing, preImageExpectedTotal);
+        const expectedTable = renderTable(onDiskEntries);
+        const actualTable = extractTableRegion(existing, preImageExpectedTotal);
+        if (actualTable === null) {
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_TABLE_DRIFT, `Ledger table region could not be located in ${p}; refusing to write. Edit the ` +
+                'fenced JSON block directly — the sole source of truth — or delete the corrupted ' +
+                'table region and let gsd-tools regenerate it; never hand-edit the rendered table.');
+        }
+        if (actualTable !== expectedTable) {
+            const driftedIds = diffTableRowIds(expectedTable, actualTable);
+            // #3689 review finding 3: a header/separator-only drift (e.g. a
+            // hand-edited column name or mangled separator) produces no data-row
+            // diffs, so driftedIds is empty — naming nothing would read "...for
+            // row id(s): .". Say what actually differs instead.
+            const driftDescription = driftedIds.length > 0
+                ? `for row id(s): ${driftedIds.join(', ')}`
+                : "in its header or separator row (no data row differs from the expected rendering)";
+            throw new WindowsError(exports.REASON.WINDOWS_LEDGER_TABLE_DRIFT, `Ledger table in ${p} disagrees with the fenced JSON entries (the sole source of ` +
+                `truth) ${driftDescription}. Edit the fenced JSON block ` +
+                'directly, or discard the table edit and re-run the command so gsd-tools ' +
+                'regenerates the table; never hand-edit the rendered table.');
+        }
     }
     const rendered = renderLedger(ledger);
     const content = trailingProse ? `${rendered}${trailingProse}` : rendered;

package/gsd-core/bin/lib/capability-consent.cjs

@@ -16,8 +16,9 @@
  * project ledger — `'' === ''` is no binding) NOR to the `disclosureSignature` alone (which covers
  * only executable surfaces, so a declarative-only cap has a constant signature and a repo-write
  * attacker could swap `capability.json` for a malicious gate/contribution while consent still
- * matched). `bundleContentHash` is recomputed by the loader at load over EVERY file in the bundle
- * (manifest AND artifacts AND identity), so any tamper — declarative-only swap, hook-script edit,
+ * matched). `bundleContentHash` is recomputed by the loader at load over the bundle (manifest AND
+ * artifacts AND identity), excluding only derived Python bytecode/cache noise (#3631 — see
+ * `bundleContentHash`'s own doc comment), so any tamper — declarative-only swap, hook-script edit,
  * empty-integrity local install — changes the hash and leaves the cap inactive. `integrity` and
  * `disclosureSignature` remain on the record for the human disclosure + re-consent-on-executable-
  * change UX (TRUST-2); they are NO LONGER the security binding.
@@ -182,10 +183,31 @@ function normalizeSepBytes(rel) {
 }
 /**
  * Recursively collect every REGULAR file AND every DIRECTORY under `absDir` as RAW-BYTE POSIX-relative
- * paths (`rel`, relative to the bundle root), refusing to follow symlinks out of the bundle. Bounded:
- * throws if the entry count or total byte size exceeds the caps (fail closed — a hostile/runaway tree
- * never hashes unbounded content). A non-regular entry encountered IN the tree (FIFO/device) is a
- * fail-closed throw — a bundle must be plain files and directories.
+ * paths (`rel`, relative to the bundle root), refusing to follow symlinks out of the bundle. Two
+ * NARROW, RECURSION-PRESERVING exclusions apply (#3631, amended after two orthogonal reviews found the
+ * original wholesale-skip UNSAFE — see the doc comment on `bundleContentHash` for the full rationale
+ * and the accepted residual risk):
+ *
+ *   1. A DIRECTORY whose basename is exactly `__pycache__` or `.pytest_cache`: its own TAG_DIR marker
+ *      is SUPPRESSED (not pushed), but it is STILL RECURSED INTO — every child that is not itself
+ *      excluded is still hashed. Suppressing only the marker is what keeps an empty/all-excluded such
+ *      directory from moving the digest; recursing is what closes the original hole (H1): skipping
+ *      recursion made an excluded directory an unbounded, permanently-unhashed region a manifest could
+ *      point a hook `script` at (`__pycache__/run.js`) to install benign, then rewrite freely post-consent.
+ *   2. A FILE whose name ends `.pyc` or `.pyo` is excluded ONLY when its PARENT directory's basename is
+ *      exactly `__pycache__` (checked byte-exact, never `.pytest_cache`) — a `.pyc`/`.pyo` anywhere else
+ *      (bundle root, `scripts/`, a directory literally named `cache.pyc`, etc.) is hashed normally,
+ *      because a sourceless legacy `.pyc` there IS importable and executable (H2).
+ *
+ * A regular FILE literally named `__pycache__` or `.pytest_cache` is NOT excluded (only a DIRECTORY of
+ * that basename gets marker-suppression) — it is hashed like any other file. A DIRECTORY literally
+ * named `x.pyc` is NOT excluded either — the suffix rule only ever applies to files. All exclusion
+ * checks run strictly AFTER the lstat-backed symlink/non-regular rejections below, so a symlink or
+ * device masquerading under an excluded name is still fail-closed rejected rather than silently
+ * skipped. Bounded: throws if the entry count or total byte size exceeds the caps (fail closed — a
+ * hostile/runaway tree never hashes unbounded content); an excluded entry still counts toward BOTH
+ * caps (the caps guard the walk itself, not the digest). A non-regular entry encountered IN the tree
+ * (FIFO/device) is a fail-closed throw — a bundle must be plain files and directories.
  *
  * #1459 finding 2 (MED/HIGH, ROUND 6): the enumeration ITSELF is bounded. Instead of
  * `fs.readdirSync` (which loads + sorts a WHOLE directory before the count cap — so a malicious bundle
@@ -204,11 +226,72 @@ function normalizeSepBytes(rel) {
  * abs/rel paths are concatenated at the BYTE level, so an invalid-UTF-8 filename is never lossily
  * decoded — two filenames that differ only in invalid bytes produce distinct rel byte strings.
  *
- * @param absDir  the absolute directory to scan, as RAW BYTES (Buffer).
- * @param relDir  the relpath of `absDir` from the bundle root, as RAW BYTES (Buffer; empty at the root).
- * @param count   the CUMULATIVE entry counter shared across the whole recursive walk (fail-closed at the cap).
+ * @param absDir       the absolute directory to scan, as RAW BYTES (Buffer).
+ * @param relDir       the relpath of `absDir` from the bundle root, as RAW BYTES (Buffer; empty at the root).
+ * @param dirBasename  the basename of `absDir` itself, as RAW BYTES (Buffer) — the PARENT basename every
+ *                      entry collected at this level shares. Threaded down so a `.pyc`/`.pyo` FILE can be
+ *                      excluded only when ITS parent is exactly `__pycache__` (empty at the bundle root).
+ * @param count        the CUMULATIVE entry counter shared across the whole recursive walk (fail-closed at the cap).
+ */
+// #3631 (amended — see bundleContentHash's doc comment for the H1/H2 rationale and accepted residual
+// risk): basename rules for what is excluded FROM THE DIGEST. They are NOT excluded from the walk's
+// resource caps — see the count.n / total.bytes accounting below, which still sees every excluded
+// entry.
+//
+// Exact byte comparison, case-sensitive, deliberately: CPython always writes a lowercase
+// `__pycache__` directory, so byte-exact matching keeps the digest identical across case-insensitive
+// filesystems (e.g. default macOS/Windows) instead of varying with how a name happens to be spelled
+// on disk.
+//
+// DELIBERATELY NOT on this list: node_modules, dist, build, or similar. Those hold code that is
+// actually required/executed at runtime, so excluding them from the digest would stop consent from
+// binding executable content — turning a usability bug (noisy re-consent prompts) into a
+// supply-chain hole (a swapped dependency that never re-triggers consent).
+/** Directory basenames whose TAG_DIR marker is suppressed — but the directory is STILL RECURSED INTO. */
+const PYCACHE_DIR_BASENAMES = [
+    Buffer.from('__pycache__'),
+    Buffer.from('.pytest_cache'),
+];
+/** FILE-name suffixes excluded ONLY when the file's parent directory basename is `__pycache__` (see below). */
+const PYCACHE_FILE_SUFFIXES = [
+    Buffer.from('.pyc'),
+    Buffer.from('.pyo'),
+];
+/** The one parent directory basename that gates the `.pyc`/`.pyo` FILE-suffix exclusion — never `.pytest_cache`. */
+const PYCACHE_PARENT_BASENAME = Buffer.from('__pycache__');
+/**
+ * True when `name` (a raw-byte dirent basename) is a DIRECTORY whose TAG_DIR marker must be
+ * suppressed — `__pycache__` or `.pytest_cache`, exact byte match. The caller still recurses into it;
+ * this predicate answers ONLY "skip the marker", never "skip the subtree".
+ */
+function isPycacheDirBasename(name) {
+    for (const exact of PYCACHE_DIR_BASENAMES) {
+        if (Buffer.compare(name, exact) === 0)
+            return true;
+    }
+    return false;
+}
+/** True when raw-byte basename `name` ends in `.pyc` or `.pyo` (byte-suffix match, never utf8-decoded). */
+function hasPycacheFileSuffix(name) {
+    for (const suffix of PYCACHE_FILE_SUFFIXES) {
+        if (name.length >= suffix.length && Buffer.compare(name.subarray(name.length - suffix.length), suffix) === 0) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when a FILE with basename `name`, inside a directory whose OWN basename is `dirBasename`, must
+ * be excluded from the digest: a `.pyc`/`.pyo` suffix whose parent directory basename is exactly
+ * `__pycache__` (byte-exact — never `.pytest_cache`, so a `.pyc` sitting directly inside a
+ * `.pytest_cache` dir is still hashed). A `.pyc`/`.pyo` file anywhere else — bundle root, `scripts/`,
+ * a directory literally named `cache.pyc`, etc. — is NOT excluded (H2): a sourceless legacy `.pyc`
+ * there is importable and executable, so it must stay bound to consent.
  */
-function collectBundleEntries(absDir, relDir, acc, total, count) {
+function isExcludedFileBasename(name, dirBasename) {
+    return hasPycacheFileSuffix(name) && Buffer.compare(dirBasename, PYCACHE_PARENT_BASENAME) === 0;
+}
+function collectBundleEntries(absDir, relDir, dirBasename, acc, total, count) {
     let dir;
     try {
         // RAW-BYTE streaming open: dirent names are Buffers (encoding: 'buffer'), so an invalid-UTF-8
@@ -269,19 +352,35 @@ function collectBundleEntries(absDir, relDir, acc, total, count) {
             throw new Error(`bundleContentHash: refusing to hash a symlink in the bundle: "${abs.toString('utf8')}"`);
         }
         if (st.isDirectory()) {
+            // #3631 (amended, H1): exclusion is checked HERE — after the symlink fail-closed throw above —
+            // so a symlink named e.g. "__pycache__" or "x.pyc" is never silently skipped; only a REAL
+            // (lstat-confirmed) dir/file can be excluded. An excluded directory's own dirent was already
+            // counted toward count.n above (the cap guards the walk itself). Only the TAG_DIR MARKER is
+            // suppressed for `__pycache__`/`.pytest_cache` — the directory is ALWAYS recursed into so every
+            // non-excluded child underneath is still hashed (closing H1: no unbounded unhashed region).
+            if (isPycacheDirBasename(name)) {
+                collectBundleEntries(abs, rel, name, acc, total, count);
+                continue;
+            }
             // Emit a typed DIR marker for THIS directory (so an empty dir is bound), then recurse into it.
             acc.push({ abs, rel, kind: 'dir' });
-            collectBundleEntries(abs, rel, acc, total, count);
+            collectBundleEntries(abs, rel, name, acc, total, count);
             continue;
         }
         if (!st.isFile()) {
             throw new Error(`bundleContentHash: refusing to hash a non-regular file in the bundle: "${abs.toString('utf8')}"`);
         }
-        acc.push({ abs, rel, kind: 'file' });
+        // #3631: an excluded FILE (a __pycache__/*.pyc or *.pyo) still counts its bytes toward the
+        // total-size cap below — exclusion answers "does this bind the digest?", not "is this safe to
+        // read unbounded?" — so it must never become a way to smuggle unbounded bytes past
+        // BUNDLE_MAX_TOTAL_BYTES.
         total.bytes += st.size;
         if (total.bytes > BUNDLE_MAX_TOTAL_BYTES) {
             throw new Error(`bundleContentHash: bundle size exceeds ${BUNDLE_MAX_TOTAL_BYTES} bytes (refusing)`);
         }
+        if (isExcludedFileBasename(name, dirBasename))
+            continue;
+        acc.push({ abs, rel, kind: 'file' });
     }
 }
 /** Encode an unsigned 32-bit length as 4 big-endian bytes (the path-length frame). */
@@ -304,8 +403,39 @@ const TAG_FILE = Buffer.from([0x01]);
 const TAG_DIR = Buffer.from([0x02]);
 /**
  * The recomputed full-bundle content hash (#1459 CB-1/CB-2/TRUST2-5) — the SECURITY BINDING. A
- * `sha512-<base64>` over a DETERMINISTIC, INJECTIVE, LOSSLESS serialization of EVERY regular file
- * AND directory under `capDir` (recursively).
+ * `sha512-<base64>` over a DETERMINISTIC, INJECTIVE, LOSSLESS serialization of every regular file
+ * AND directory under `capDir` (recursively), with two NARROW exclusions (#3631, amended after two
+ * orthogonal reviews found the original wholesale directory-skip UNSAFE):
+ *   - A `__pycache__` or `.pytest_cache` DIRECTORY's own TAG_DIR marker is suppressed, but it is
+ *     ALWAYS recursed into — every non-excluded child underneath is still hashed.
+ *   - A `.pyc`/`.pyo` FILE is excluded ONLY when its immediate parent directory's basename is exactly
+ *     `__pycache__`; a `.pyc`/`.pyo` anywhere else (bundle root, `scripts/`, etc.) is hashed normally,
+ *     since a sourceless legacy `.pyc` there is importable and executable.
+ * `node_modules`, `dist`, `build`, and similar are deliberately NOT excluded: their contents are
+ * executed/required at runtime, so dropping them from the digest would stop consent from binding
+ * executable content.
+ *
+ * ACCEPTED RESIDUAL RISK (documented, not a defect to re-litigate): CPython's default `.pyc`
+ * invalidation (timestamp-based) validates a cached bytecode file against its SOURCE's mtime and size
+ * only — NOT against the source's content — and both mtime and size are attacker-settable by whoever
+ * can already write to the bundle. So a forged `__pycache__/mod.cpython-3XX.pyc` whose header mtime/size
+ * were copied from an unmodified, still-hashed `mod.py` will execute without moving this digest. Before
+ * this exclusion existed that write was detected (any file under `__pycache__` moved the hash); after
+ * it, it is not, for files matching the narrow `__pycache__/*.pyc` shape above. This is accepted
+ * deliberately — the alternative (H1's original wholesale skip, or hashing every regenerated bytecode
+ * file) either reopens an unbounded unhashed region or makes consent fire on routine bytecode caching —
+ * and is bounded by: (1) the attacker must already have POST-CONSENT write access to the bundle; (2)
+ * everything outside `__pycache__/*.pyc` — including sourceless legacy `.pyc`/`.pyo` files anywhere
+ * else — remains hashed. NOT a bound, despite `isSafeHookScriptPath` (capability-lifecycle.cts /
+ * capability-validator.cjs) rejecting a manifest-declared hook `script` that names a
+ * `__pycache__`/`.pytest_cache` segment or ends `.pyc`/`.pyo`: the excluded region is still reachable
+ * by ONE HOP of indirection from any hashed, consent-covered script — a `require`/`import` of a
+ * `__pycache__/*.pyc` module path is not itself a declared script and the validator never sees it —
+ * so a hashed `hooks/run.js` can load a `__pycache__/mod.pyc` whose bytes are then free to change
+ * post-consent with the digest unmoved. The validator guard raises the bar for DECLARED surfaces; it
+ * does not contain the risk. KNOWN LIMITATION: `.pytest_cache`'s CONTENTS still change the digest as
+ * normal files — only its directory marker is suppressed, so this residual risk does NOT extend to
+ * `.pytest_cache`.
  *
  * Canonicalization (#1459 findings 1 + 4 — the prior `relpath + NUL + content + NUL` over utf8-decoded
  * STRINGS was non-injective, lossy in CONTENT, AND lossy in the PATH component):
@@ -333,8 +463,12 @@ const TAG_DIR = Buffer.from([0x02]);
 function bundleContentHash(capDir) {
     // Resolve to an absolute path, then carry it as RAW BYTES so the walk never lossily decodes a name.
     const rootBytes = Buffer.from(node_path_1.default.resolve(capDir));
+    // The root's own basename is threaded as the initial `dirBasename` so the parent-basename check for
+    // a `.pyc`/`.pyo` FILE applies even to a file placed DIRECTLY at the bundle root (root literally
+    // named `__pycache__` is the only case this matters for, and it is a correct, if exotic, match).
+    const rootBasename = Buffer.from(node_path_1.default.basename(node_path_1.default.resolve(capDir)));
     const entries = [];
-    collectBundleEntries(rootBytes, Buffer.alloc(0), entries, { bytes: 0 }, { n: 0 });
+    collectBundleEntries(rootBytes, Buffer.alloc(0), rootBasename, entries, { bytes: 0 }, { n: 0 });
     // Sort by the raw-byte (separator-normalized) relpath so the digest is identical on Windows and POSIX,
     // and is independent of the on-disk creation/readdir order. Tie-break on kind so a (degenerate, never
     // produced on a real fs) file-and-dir same-relpath pair still has a stable order.