fix(#3582): route every hook's compiled-module require through the self-heal build seam (#3629)

* test(3582): failing-first cold-tree coverage and the seam drift lint

On a plugin-channel install the compiled gsd-core/bin/lib/*.cjs are legitimately
absent (ADR-457 build-at-publish; the npm package builds before publishing, a raw
tree materialization never does). gsd-tools.cjs calls ensureRuntimeBuild() before
requiring ./lib; no hook does, so the isolation guard's Cannot-find-module lands in
its fail-closed catch and is misreported as an unreadable dispatch-isolation
configuration, blocking every executor dispatch.

These tests fail on that: cold-tree runs of the isolation guard, statusline, cursor
guard and update worker, plus the seam's actionable build error surfacing instead of
the generic misreport.

Also adds the drift lint the acceptance criteria require, with a fixture proving it
CAN fail — a guard never shown to fail is worthless. It is red here by design: it
flags today's unfixed hooks, which is exactly the defect.

* fix(3582): route every hook's compiled-module require through the self-heal seam

RED proven at 5b174b0d: 11 failures — the cold-tree runs for the isolation guard,
cursor guard and update worker, the fail-closed-with-actionable-message assertion, and
the lint's own real-tree check.

The compiled runtime library is produced by build:lib and gitignored (ADR-457,
build-at-publish). The npm package builds before publishing; a plugin-marketplace or
git-clone install materializes the raw tree and never does, so on that channel those
modules are legitimately absent. The self-heal seam added by #2002 exists to heal exactly
this, and the CLI entrypoint already calls it — no hook did. The isolation guard's
Cannot-find-module therefore landed in its fail-closed catch and was reported as
'could not read or resolve dispatch-isolation configuration', so an ARTIFACT ABSENCE was
misdiagnosed as an unreadable project config and every executor dispatch was blocked.

All SEVEN affected files now call the seam before their first compiled require. The issue
named four; a scan found six; implementing it surfaced a seventh — the shared isolation
sentinel helper, used by BOTH guards, which requires two compiled modules itself and
would have defeated the guards' own fix on a genuinely cold tree. Same defect class, so
fixed here rather than left as a known-broken remainder.

Failure posture is deliberately split by hook kind:
- Gates (agent isolation guard, cursor subagent start) surface the seam's actionable
  build error distinctly instead of swallowing it into the generic text, and stay
  fail-closed — a genuinely unreadable project config still DENIES exactly as before.
- Cosmetic and detached hooks (statusline, update worker, update check, update banner)
  DEGRADE rather than crash: the statusline draws on every render and the worker is a
  detached process, so a build failure there must not take down the prompt.

The npm path is untouched: the seam's already-built fast path returns immediately, so
prebuilt installs pay nothing and behave bit-for-bit as before.

Adds a drift lint, wired into the CI lint chain, so the invariant is enforced rather than
remembered — without it the next hook to add a compiled require reintroduces the class
silently. It is proven able to fail: a fixture hook requiring a compiled module without
the seam is flagged, and one that uses the seam is not. Verified directly — on the
unfixed tree it named all seven offenders; with the fix it passes.

While writing the lint's comment stripper, a naive whole-text block-comment regex ate its
own fixture, because this repo's comments legitimately spell the compiled-lib glob whose
star-slash reads as a comment opener. Rewritten as a line-based scanner with a regression
test pinning that case.

* fix(3582): test the three untested seam call sites and assert typed reason codes

Two independent reviews converged on the same major gap: the fix wired the seam into
seven files but only four had cold-tree tests. The adversarial pass put it plainly —
deleting the shared isolation-sentinel helper's seam call would not have failed any test
in the diff. That file was my own addition beyond the issue's four, so it shipped
untested; that is now closed.

- Shared isolation-sentinel helper: its seam call is only reached when .planning is NOT
  directly under cwd, and every existing cold-tree fixture puts it there, so the early
  return always fired first. Now covered, and proven load-bearing by mutation: with the
  call removed the spy records zero seam invocations and the test fails.
- update-check hook and update-banner hook: cold-tree tests added asserting the DEGRADED
  VERDICT — the fallback cache filename, and silent suppression when the package name
  degrades to null — rather than merely 'did not throw'. The banner hook previously had
  no test file at all.

Standards violation fixed: two tests asserted on free-form prose via assert.match against
a JSON reason string, which CONTRIBUTING bans by name — its own BAD example is exactly
that. The ESLint rule only covers readFileSync/spawnSync text, so tooling did not catch
it. Both isolation guards now emit a machine-readable reason_code from a frozen enum,
following the repo's existing REASON convention, and the tests assert that instead. The
human-readable message is unchanged for operators; only the assertion target moved.

The duplicated degrade boilerplate across the three cosmetic hooks was deliberately NOT
extracted, and the reason is recorded at each site: both viable shapes — a
path-parameterized helper, or a ceremony-only wrapper — defeat the drift lint's per-file
literal co-occurrence check, so extracting would require the lint to special-case its own
helper. Triplication is the lesser evil while the lint stays a co-occurrence scan.

The lint's header now states what it does and does not catch (literal quoted requires
only; hooks/ scan root), so a future reader does not over-trust a guard that a
concatenated path or a require inside a non-hooks helper would evade.

* chore(3582): regenerate the committed install-tree fixtures

Adding a new shipped hook helper changed the install tree, and those fixtures are
committed-and-derived (regen:derived / gen:install-tree), so 12 'install tree — <runtime>'
tests failed on 541a1913. Regenerated rather than hand-edited.

The delta across all 15 runtime fixtures is exactly two lines — the new helper under both
its hooks/ and gsd-hooks/ install paths — and nothing else, so the regeneration pulled in
no unrelated drift.

This is the bookkeeping ripple a new file under hooks/ carries; it was not visible from
lint:ci, which passed both before and after.

* chore(3582): backfill changeset PR number (#3629)

---------

Co-authored-by: sim <sim@local>

tests/check-update-config-dir.test.cjs

@@ -69,13 +69,16 @@ function buildProbeSource(hookPath) {
  * @param {string} opts.cwd - fake cwd (project base) for this run.
  * @param {object} [opts.envOverrides] - applied after HOME/USERPROFILE and
  *   after CLAUDE_CONFIG_DIR is deleted, so a row can reintroduce it.
+ * @param {string} [opts.hookPath] - override the hook under test (defaults to
+ *   the real hooks/gsd-check-update.js). Used by the #3582 cold-tree suite
+ *   below to point at a fixture copy instead.
  */
-function probe({ homeDir, cwd, envOverrides = {} }) {
+function probe({ homeDir, cwd, envOverrides = {}, hookPath = CHECK_UPDATE_PATH }) {
   const childEnv = { ...process.env, HOME: homeDir, USERPROFILE: homeDir };
   delete childEnv.CLAUDE_CONFIG_DIR;
   Object.assign(childEnv, envOverrides);
 
-  const result = runNode(['-e', buildProbeSource(CHECK_UPDATE_PATH)], {
+  const result = runNode(['-e', buildProbeSource(hookPath)], {
     cwd,
     env: childEnv,
     timeoutMs: PROBE_TIMEOUT_MS,
@@ -307,3 +310,39 @@ describe('detectConfigDir runtime behavior (#1860)', () => {
     );
   });
 });
+
+// ─── #3582: cold tree (no gsd-core/bin/lib/*.cjs) — degraded cache filename ─
+//
+// gsd-core/bin/lib/package-identity.cjs is a tsc build artifact (ADR-457),
+// gitignored and absent on a raw plugin-marketplace / git-clone install that
+// never ran `npm run build:lib`. This SessionStart hook degrades to the
+// hardcoded fallback cache filename ('gsd-update-check.json') rather than
+// crash session start (see the hook's own #3582 comment). The DEGRADED
+// VERDICT this test locks is observable via the SAME spawn-env probe seam
+// used above: the GSD_CACHE_FILE env var the hook hands to its worker must
+// end with the fallback literal, not throw and not silently vanish.
+// Simulated hermetically via tests/helpers/cold-runtime-lib-fixture.cjs — the
+// REAL gsd-core/bin/lib/ is never touched.
+describe('gsd-check-update.js: #3582 cold tree — degrades to the fallback cache filename', () => {
+  const { buildColdInstallTree } = require('./helpers/cold-runtime-lib-fixture.cjs');
+
+  test('missing compiled runtime library -> worker still launched, with the hardcoded fallback cache filename', (t) => {
+    const cold = buildColdInstallTree();
+    t.after(cold.cleanup);
+    const home = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-cu-cold-home-')));
+    const project = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-cu-cold-project-')));
+    t.after(() => { cleanup(home); cleanup(project); });
+
+    const result = probe({
+      homeDir: home,
+      cwd: project,
+      hookPath: path.join(cold.hooksDir, 'gsd-check-update.js'),
+    });
+
+    assert.equal(
+      path.basename(result.cache),
+      'gsd-update-check.json',
+      `expected the hardcoded degrade fallback cache filename when package-identity.cjs cannot be built; got: ${result.cache}`,
+    );
+  });
+});

tests/cursor-subagent-isolation.test.cjs

@@ -29,6 +29,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { createTempDir, cleanup } = require('./helpers.cjs');
 const { SENTINEL_RELATIVE_PATH, SENTINEL_STALE_MS } = require('../hooks/lib/isolation-sentinel.js');
+const { REASON_CODE } = require('../hooks/lib/isolation-deny-reason.js');
 const { runNode } = require('./helpers/process-seam.cjs');
 const { gitOrThrow, toLegacyResult } = require('./helpers/git-fixture.cjs');
 const { PROBE_TIMEOUT_MS } = require('./helpers/timeouts.cjs');
@@ -997,3 +998,50 @@ describe('gsd-cursor-subagent-start.js: #3566 — per-install .gsd-runtime marke
     );
   });
 });
+
+// ─── #3582: cold tree (no gsd-core/bin/lib/*.cjs) — self-heal surfacing ────
+//
+// Mirrors tests/gsd-agent-isolation-guard.test.cjs's identical #3582 case for
+// the sibling Claude guard. evaluateRootIsolation now calls
+// ensureRuntimeBuild() immediately after the GSD-project existence check —
+// before resolveFallbackIsolation's runtime-name-policy.cjs/
+// capability-registry.cjs requires or resolveIsolationEvidence's
+// runtime-homes.cjs/worktree-safety.cjs requires — so a missing compiled
+// runtime library denies with the seam's own actionable message rather than
+// the generic "could not read or resolve ... configuration" text (#3050).
+// Simulated hermetically via tests/helpers/cold-runtime-lib-fixture.cjs — the
+// REAL gsd-core/bin/lib/ is never touched.
+describe('gsd-cursor-subagent-start.js: #3582 cold tree — RuntimeBuildError surfaces distinctly', () => {
+  const { buildColdInstallTree } = require('./helpers/cold-runtime-lib-fixture.cjs');
+
+  test('missing compiled runtime library -> DENY (fail-closed) with the seam\'s own actionable message, not the generic config-unreadable text', (t) => {
+    const cold = buildColdInstallTree();
+    t.after(cold.cleanup);
+    const project = createTempDir('gsd-cs-cold-');
+    t.after(() => cleanup(project));
+    fs.mkdirSync(path.join(project, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(project, '.planning', 'config.json'), JSON.stringify({ runtime: 'cursor' }));
+
+    const env = { ...process.env };
+    delete env.GSD_RUNTIME;
+    delete env.CURSOR_CONFIG_DIR;
+    const r = toLegacyResult(runNode([path.join(cold.hooksDir, 'gsd-cursor-subagent-start.js')], {
+      input: JSON.stringify(subagentPayload([project])),
+      cwd: require('node:os').tmpdir(),
+      env,
+      timeoutMs: PROBE_TIMEOUT_MS,
+    }));
+    assert.equal(r.status, 0, `this hook always exits 0; stdout: ${r.stdout} stderr: ${r.stderr}`);
+    const out = JSON.parse(r.stdout);
+    assert.equal(out.permission, 'deny');
+    // Typed reason code (CONTRIBUTING.md "Prohibited: Raw Text Matching on
+    // Test Outputs" — assert the stable code, not the free-form
+    // `user_message` prose). RUNTIME_BUILD_FAILED and CONFIG_UNREADABLE are
+    // distinct codes, so this equality check itself proves the build
+    // failure is NOT misreported as the generic unreadable-config case.
+    assert.equal(out.reason_code, REASON_CODE.RUNTIME_BUILD_FAILED);
+    // `user_message` remains free-form operator-facing text — not asserted here.
+    assert.equal(typeof out.user_message, 'string');
+    assert.ok(out.user_message.length > 0);
+  });
+});

tests/fixtures/install-tree/antigravity.json

@@ -398,6 +398,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/augment.json

@@ -469,6 +469,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/claude-local.json

@@ -469,6 +469,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/claude.json

@@ -398,6 +398,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/codebuddy.json

@@ -469,6 +469,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/cursor.json

@@ -375,6 +375,7 @@
   "hooks/gsd-cursor-subagent-start.js",
   "hooks/gsd-cursor-subagent-stop.js",
   "hooks/lib/cursor-workspace.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/package.json",
   "scripts/changeset/README.md",

tests/fixtures/install-tree/hermes.json

@@ -398,6 +398,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/kilo.json

@@ -469,6 +469,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/kimi-code.json

@@ -399,6 +399,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/opencode.json

@@ -469,6 +469,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/fixtures/install-tree/pi.json

@@ -366,6 +366,7 @@
   "gsd-hooks/lib/git-cmd.js",
   "gsd-hooks/lib/gsd-graphify-rebuild.sh",
   "gsd-hooks/lib/injection-patterns.js",
+  "gsd-hooks/lib/isolation-deny-reason.js",
   "gsd-hooks/lib/isolation-sentinel.js",
   "gsd-hooks/managed-hooks-registry.cjs",
   "gsd-hooks/package.json",

tests/fixtures/install-tree/qwen.json

@@ -398,6 +398,7 @@
   "hooks/lib/git-cmd.js",
   "hooks/lib/gsd-graphify-rebuild.sh",
   "hooks/lib/injection-patterns.js",
+  "hooks/lib/isolation-deny-reason.js",
   "hooks/lib/isolation-sentinel.js",
   "hooks/managed-hooks-registry.cjs",
   "hooks/package.json",

tests/gsd-agent-isolation-guard.test.cjs

@@ -54,6 +54,7 @@ const { toLegacyResult, gitOrThrow } = require('./helpers/git-fixture.cjs');
 const { PROBE_TIMEOUT_MS } = require('./helpers/timeouts.cjs');
 const { createTempDir, createTempProject, runGsdTools, cleanup } = require('./helpers.cjs');
 const { SENTINEL_RELATIVE_PATH, SENTINEL_STALE_MS, readSentinel } = require('../hooks/lib/isolation-sentinel.js');
+const { REASON_CODE } = require('../hooks/lib/isolation-deny-reason.js');
 const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');
 
 const HOOK_PATH = path.join(__dirname, '..', 'hooks', 'gsd-agent-isolation-guard.js');
@@ -1271,3 +1272,52 @@ describe('#2486 regression: inspect-dispatch-isolation is the sentinel-free read
     assert.ok(inspectedJson.exec, 'precondition: this branch actually populates exec, so the comparison means something');
   });
 });
+
+// ─── #3582: cold tree (no gsd-core/bin/lib/*.cjs) — self-heal surfacing ────
+//
+// gsd-core/bin/lib/*.cjs are tsc build artifacts (ADR-457), gitignored and
+// absent on a raw plugin-marketplace / git-clone install that never ran
+// `npm run build:lib`. Before #3582, resolveRegistryIsolation's
+// require('../gsd-core/bin/lib/runtime-name-policy.cjs') threw a bare
+// "Cannot find module", which resolveIsolationState's catch folded into the
+// SAME generic "could not read or resolve ... configuration" reason as an
+// unreadable config.json (row 8/12 above) — a misreport of a completely
+// different failure (#3050 lesson). The fix: resolveRegistryIsolation now
+// calls ensureRuntimeBuild() first; a RuntimeBuildError surfaces its own
+// actionable message instead. Simulated hermetically via a fixture install
+// tree that copies hooks/ + the seam module but never gsd-core/bin/lib/ or
+// tsconfig.build.json (tests/helpers/cold-runtime-lib-fixture.cjs) — the
+// REAL gsd-core/bin/lib/ is never touched.
+describe('gsd-agent-isolation-guard.js: #3582 cold tree — RuntimeBuildError surfaces distinctly', () => {
+  const { buildColdInstallTree } = require('./helpers/cold-runtime-lib-fixture.cjs');
+
+  test('missing compiled runtime library -> DENY (fail-closed) with the seam\'s own actionable message, not the generic config-unreadable text', (t) => {
+    const cold = buildColdInstallTree();
+    t.after(cold.cleanup);
+    const project = mkProject('gsd-aig-cold-');
+    t.after(() => cleanup(project));
+    writeConfig(project, JSON.stringify({ runtime: 'claude' }));
+
+    const env = { ...process.env };
+    delete env.GSD_RUNTIME;
+    const r = runHookSeam(path.join(cold.hooksDir, 'gsd-agent-isolation-guard.js'), [], {
+      input: JSON.stringify(agentPayload()),
+      cwd: project,
+      env,
+      timeoutMs: PROBE_TIMEOUT_MS,
+    });
+    const result = toLegacyResult(r);
+    assert.equal(result.status, 2, `expected fail-closed DENY; stdout: ${result.stdout} stderr: ${result.stderr}`);
+    const out = JSON.parse(result.stdout);
+    assert.equal(out.decision, 'block');
+    // Typed reason code (CONTRIBUTING.md "Prohibited: Raw Text Matching on
+    // Test Outputs" — assert the stable code, not the free-form `reason`
+    // prose). RUNTIME_BUILD_FAILED and CONFIG_UNREADABLE are distinct codes,
+    // so this equality check itself proves the build failure is NOT
+    // misreported as the generic unreadable-config case (rows 8/12 above).
+    assert.equal(out.reason_code, REASON_CODE.RUNTIME_BUILD_FAILED);
+    // `reason` remains free-form operator-facing text — not asserted here.
+    assert.equal(typeof out.reason, 'string');
+    assert.ok(out.reason.length > 0);
+  });
+});

tests/gsd-check-update-worker-platform-gate.test.cjs

@@ -88,6 +88,62 @@ describe('worker delegates the npm spawn (does not re-open the gate, #498)', ()
   });
 });
 
+// ─── #3582: cold tree (no gsd-core/bin/lib/*.cjs) — degrade, not crash ─────
+//
+// gsd-core/bin/lib/semver-compare.cjs, package-identity.cjs, and (via
+// check-latest-version.cjs's own transitive requires) gsd-core/bin/lib/
+// cli-exit.cjs + shell-command-projection.cjs are tsc build artifacts
+// (ADR-457), gitignored and absent on a raw plugin-marketplace / git-clone
+// install that never ran `npm run build:lib`. This worker is a DETACHED
+// SessionStart background process (spawned with stdio: 'ignore' by
+// hooks/gsd-check-update.js) — before #3582 a missing library crashed the
+// worker at module load with no visible signal (stderr discarded by the
+// parent) and no cache-file write at all, so the statusline/banner would
+// silently never see an update signal. The fix wraps ensureRuntimeBuild()
+// and the three compiled-lib requires in one try/catch and degrades to
+// no-signal fallbacks (isSemverNewer -> false, checkLatestVersion -> not ok,
+// PACKAGE_NAME -> null) on failure — the worker still runs to completion and
+// writes a result cache record. Simulated hermetically via a fixture install
+// tree that copies hooks/ + the seam module but never gsd-core/bin/lib/ or
+// tsconfig.build.json (tests/helpers/cold-runtime-lib-fixture.cjs) — the REAL
+// gsd-core/bin/lib/ is never touched.
+{
+  const { describe, test } = require('node:test');
+  const assert = require('node:assert/strict');
+  const fs = require('node:fs');
+  const path = require('node:path');
+  const { runHook: runHookSeam } = require('./helpers/process-seam.cjs');
+  const { buildColdInstallTree } = require('./helpers/cold-runtime-lib-fixture.cjs');
+  const { createTempDir, cleanup } = require('./helpers.cjs');
+
+  describe('gsd-check-update-worker.js: #3582 cold tree — degrade, not crash', () => {
+    test('missing compiled runtime library -> worker still writes a degraded result cache, no crash', (t) => {
+      const cold = buildColdInstallTree();
+      t.after(cold.cleanup);
+      const cacheDir = createTempDir('gsd-worker-cold-');
+      t.after(() => cleanup(cacheDir));
+      const cacheFile = path.join(cacheDir, 'cache.json');
+
+      const env = {
+        ...process.env,
+        GSD_CACHE_FILE: cacheFile,
+        GSD_PROJECT_VERSION_FILE: path.join(cacheDir, 'no-such-project', 'VERSION'),
+        GSD_GLOBAL_VERSION_FILE: path.join(cacheDir, 'no-such-global', 'VERSION'),
+      };
+      const r = runHookSeam(path.join(cold.hooksDir, 'gsd-check-update-worker.js'), [], {
+        env,
+        timeoutMs: 8000,
+      });
+      assert.equal(r.exitCode, 0, `worker must exit 0 on a build failure; stderr: ${r.stderr}`);
+      assert.ok(fs.existsSync(cacheFile), 'worker must still reach the end and write a cache record');
+      const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
+      assert.equal(cache.package_name, null, 'degraded package_name must be null (no-signal, never a stale/foreign value)');
+      assert.ok(!cache.update_available, 'degraded update_available must be falsy');
+      assert.equal(cache.installed, '0.0.0', 'installed detection is unaffected by the compiled-lib degrade');
+    });
+  });
+}
+
 
 // ────────────────────────────────────────────────────────────────────────
 // Folded from tests/bug-2992-check-latest-version.test.cjs — consolidation epic #1969 (B5 #1974)
@@ -783,6 +839,58 @@ describe('gsd-update-banner.js end-to-end', () => {
   });
 });
 
+// ─── #3582: cold tree (no gsd-core/bin/lib/*.cjs) — degrade, not crash ─────
+//
+// gsd-core/bin/lib/package-identity.cjs is a tsc build artifact (ADR-457),
+// gitignored and absent on a raw plugin-marketplace / git-clone install that
+// never ran `npm run build:lib`. This is an opt-in SessionStart hook — a
+// build failure must degrade (PACKAGE_NAME stays null), not crash session
+// start. The DEGRADED VERDICT this locks: buildBannerOutput's own lineage
+// guard (`!cache.package_name || cache.package_name !== PACKAGE_NAME`)
+// unconditionally distrusts ANY cache once PACKAGE_NAME is null, so even a
+// cache written by a healthy worker (real package_name, update_available:
+// true) must be suppressed rather than surfaced — the hook stays SILENT
+// (exit 0, empty stdout), never a crash and never a stale/wrong banner.
+// Simulated hermetically via tests/helpers/cold-runtime-lib-fixture.cjs — the
+// REAL gsd-core/bin/lib/ is never touched.
+describe('gsd-update-banner.js: #3582 cold tree — degrades to silent, never crashes', () => {
+  const { buildColdInstallTree } = require('./helpers/cold-runtime-lib-fixture.cjs');
+
+  test('missing compiled runtime library -> exits 0 with empty stdout even for an otherwise-valid update-available cache', (t) => {
+    const cold = buildColdInstallTree();
+    t.after(cold.cleanup);
+    const home = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-banner-cold-home-'));
+    t.after(() => cleanup(home));
+    fs.mkdirSync(path.join(home, '.cache', 'gsd'), { recursive: true });
+    // The generic fallback filename the hook's own #3582 degrade uses when
+    // package-identity.cjs cannot be built (mirrors gsd-check-update.js's
+    // identical fallback literal) — this is the SAME cache path a degraded
+    // worker would also have written to.
+    fs.writeFileSync(
+      path.join(home, '.cache', 'gsd', 'gsd-update-check.json'),
+      JSON.stringify({
+        update_available: true,
+        installed: '1.39.0',
+        latest: '1.40.0',
+        package_name: '@opengsd/gsd-core',
+      }),
+    );
+
+    const r = seamRunHook(path.join(cold.hooksDir, 'gsd-update-banner.js'), [], {
+      env: { ...process.env, HOME: home, USERPROFILE: home },
+      timeoutMs: 10_000,
+    });
+
+    assert.equal(r.exitCode, 0, `hook must exit 0 on a build failure; stderr: ${r.stderr}`);
+    assert.equal(
+      r.stdout.trim(),
+      '',
+      'a cold tree must silently suppress the banner (PACKAGE_NAME degrades to null, ' +
+        'so the lineage guard distrusts every cache) rather than crash or print stale content',
+    );
+  });
+});
+
 // ─── Install.js wiring: prompt + SessionStart entry registration ────────────
 //
 // These tests load bin/install.js as a module via GSD_TEST_MODE and assert on

tests/gsd-statusline.test.cjs

@@ -2415,3 +2415,49 @@ describe('evaluateUpdateCache lineage guard', () => {
 });
   });
 }
+
+// ─── #3582: cold tree (no gsd-core/bin/lib/*.cjs) — degrade, not crash ─────
+//
+// gsd-core/bin/lib/semver-compare.cjs, package-identity.cjs,
+// state-document.cjs, active-workstream-store.cjs, and planning-workspace.cjs
+// are tsc build artifacts (ADR-457), gitignored and absent on a raw
+// plugin-marketplace / git-clone install that never ran `npm run build:lib`.
+// The statusline renders on EVERY prompt — before #3582 a missing library
+// crashed the whole hook process at module load (bare "Cannot find module"),
+// so Claude Code's statusline would show nothing AND emit a visible error on
+// every single render. The fix: the spawned-as-a-script path
+// (`require.main === module`) calls ensureRuntimeBuild() first and, on
+// failure, writes empty stdout and exits 0 — the SAME quiet no-signal
+// behavior every other internal failure in this hook already degrades to
+// (see e.g. the `try { ... } catch (e) { /* Silent fail */ }` wrapping
+// runStatusline's own body). Simulated hermetically via a fixture install
+// tree that copies hooks/ + the seam module but never gsd-core/bin/lib/ or
+// tsconfig.build.json (tests/helpers/cold-runtime-lib-fixture.cjs) — the REAL
+// gsd-core/bin/lib/ is never touched.
+{
+  const { describe, test } = require('node:test');
+  const assert = require('node:assert/strict');
+  const os = require('node:os');
+  const path = require('node:path');
+  const { runHook: runHookSeam } = require('./helpers/process-seam.cjs');
+  const { buildColdInstallTree } = require('./helpers/cold-runtime-lib-fixture.cjs');
+
+  describe('gsd-statusline.js: #3582 cold tree — degrade to empty output, exit 0', () => {
+    test('missing compiled runtime library -> empty stdout, exit 0, no crash', (t) => {
+      const cold = buildColdInstallTree();
+      t.after(cold.cleanup);
+
+      const payload = JSON.stringify({
+        model: { display_name: 'Claude' },
+        workspace: { current_dir: os.tmpdir() },
+        session_id: `test-3582-${Date.now()}`,
+      });
+      const r = runHookSeam(path.join(cold.hooksDir, 'gsd-statusline.js'), [], {
+        input: payload,
+        timeoutMs: 4000,
+      });
+      assert.equal(r.exitCode, 0, `must exit 0 on a build failure; stdout: ${r.stdout} stderr: ${r.stderr}`);
+      assert.equal(r.stdout, '', 'must degrade to empty output, not throw a stack trace to stdout');
+    });
+  });
+}

tests/helpers/cold-runtime-lib-fixture.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+ * Build a hermetic "cold tree" install fixture for #3582 — a copy of hooks/
+ * plus gsd-core/bin/ensure-runtime-build.cjs with the compiled
+ * gsd-core/bin/lib/*.cjs directory and tsconfig.build.json deliberately
+ * ABSENT, mirroring a raw plugin-marketplace / git-clone install that never
+ * ran `npm run build:lib`.
+ *
+ * Deliberately NOT `tests/helpers/copy-script-fixture.cjs`'s
+ * `copyScriptWithDeps`: that helper walks the require graph and copies every
+ * dependency it finds — including gsd-core/bin/lib/*.cjs, which exist in
+ * THIS repo's already-built tree — so it would faithfully reproduce a WARM
+ * tree, the opposite of what a cold-tree test needs. This helper copies only
+ * hooks/ and the seam module itself, and never touches gsd-core/bin/lib/ or
+ * tsconfig.build.json — so `ensureRuntimeBuild()` inside the fixture
+ * deterministically throws `RuntimeBuildError` ("tsconfig.build.json not
+ * found") the first time any fixture hook reaches it, without ever deleting
+ * or touching the real repo's gsd-core/bin/lib/.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * @param {(dir: string) => void} [t.after]  optional node:test `t` for auto-cleanup registration; caller may also ignore and use the returned `cleanup`.
+ * @returns {{ dir: string, hooksDir: string, cleanup: () => void }}
+ */
+function buildColdInstallTree() {
+  const dir = fs.mkdtempSync(path.join(require('node:os').tmpdir(), 'gsd-cold-tree-'));
+
+  // hooks/ — entire directory (top-level hook scripts + hooks/lib/*.js +
+  // managed-hooks-registry.cjs + hooks.json). hooks/dist/ (gitignored,
+  // build-hooks.js output) is excluded — it is not present in a raw
+  // marketplace checkout either.
+  fs.cpSync(path.join(REPO_ROOT, 'hooks'), path.join(dir, 'hooks'), {
+    recursive: true,
+    filter: (src) => path.basename(src) !== 'dist',
+  });
+
+  // gsd-core/bin/ensure-runtime-build.cjs — the seam itself. Deliberately
+  // NOT gsd-core/bin/lib/ (absent — isBuilt() reads false) and NOT
+  // tsconfig.build.json at the fixture root (absent — ensureRuntimeBuild's
+  // "cannot auto-build" branch fires deterministically).
+  fs.mkdirSync(path.join(dir, 'gsd-core', 'bin'), { recursive: true });
+  fs.copyFileSync(
+    path.join(REPO_ROOT, 'gsd-core', 'bin', 'ensure-runtime-build.cjs'),
+    path.join(dir, 'gsd-core', 'bin', 'ensure-runtime-build.cjs'),
+  );
+
+  function cleanup() {
+    fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3 });
+  }
+
+  return { dir, hooksDir: path.join(dir, 'hooks'), cleanup };
+}
+
+module.exports = { buildColdInstallTree, REPO_ROOT };

tests/isolation-sentinel.test.cjs

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Tests for hooks/lib/isolation-sentinel.js's resolveSentinelRoot() — specifically
+ * the #3582 self-heal call it makes before resolving a linked-worktree/ancestor
+ * project root. That call is reached ONLY when '.planning' is NOT directly under
+ * the cwd passed in (the early return at the top of the function fires first
+ * otherwise).
+ *
+ * #3582 review finding 1a: every existing #3582 cold-tree fixture
+ * (tests/helpers/cold-runtime-lib-fixture.cjs) puts '.planning' directly under
+ * the fixture project root, so none of them ever reach this branch — deleting
+ * the seam call would fail nothing in those suites. The one existing test that
+ * DOES pass a cwd whose '.planning' is not directly present
+ * (tests/gsd-agent-isolation-guard.test.cjs's "#3045 MINOR" linked-worktree
+ * test) runs against the REAL, already-built dev tree, where
+ * ensureRuntimeBuild() is a fast successful no-op — removing the seam call
+ * there would not change that test's outcome either, since the next require
+ * (worktree-safety.cjs) would resolve identically either way.
+ *
+ * This file closes that gap. Rather than a real tsc build (which would need
+ * this repo's own node_modules/typescript to be reachable from a throwaway
+ * fixture root, or a directory symlink into it — the latter a privileged,
+ * CI-unsafe operation on Windows per tests/ensure-runtime-build.test.cjs's own
+ * comment), it substitutes the THREE modules resolveSentinelRoot requires
+ * (the seam itself, worktree-safety.cjs, project-root.cjs) via require.cache,
+ * keyed by their real resolved absolute paths. This directly OBSERVES whether
+ * the seam call ran (a spy counter), rather than inferring it from a return
+ * value that a missing call could coincidentally also produce — and never
+ * touches gsd-core/bin/lib on disk. Injected cache entries are restored (or
+ * deleted, if absent beforehand) in `t.after()` so no other test sharing this
+ * worker process ever observes the substitution.
+ *
+ * Mutation check performed while authoring this test (not re-run on every CI
+ * pass — see the assertions' own doc comments): removing the two-line seam
+ * call from resolveSentinelRoot makes `seamCalls` stay 0 and
+ * `worktreeSafetyCalls` become 1 (the fake, reachable stub now answers), so
+ * this test fails exactly when the fix regresses.
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { cleanup } = require('./helpers.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const SENTINEL_MODULE_PATH = path.join(REPO_ROOT, 'hooks', 'lib', 'isolation-sentinel.js');
+const SEAM_PATH = require.resolve(path.join(REPO_ROOT, 'gsd-core', 'bin', 'ensure-runtime-build.cjs'));
+const WORKTREE_SAFETY_PATH = require.resolve(path.join(REPO_ROOT, 'gsd-core', 'bin', 'lib', 'worktree-safety.cjs'));
+const PROJECT_ROOT_PATH = require.resolve(path.join(REPO_ROOT, 'gsd-core', 'bin', 'lib', 'project-root.cjs'));
+const SENTINEL_RESOLVED = require.resolve(SENTINEL_MODULE_PATH);
+
+/** Minimal shape Node's Module cache expects; only `.exports` is read by require(). */
+function fakeModule(filename, exportsObj) {
+  return { id: filename, filename, loaded: true, exports: exportsObj, children: [], paths: [] };
+}
+
+describe('hooks/lib/isolation-sentinel.js: resolveSentinelRoot self-heal reachability (#3582 review finding 1a)', () => {
+  test('the seam call fires — and short-circuits the downstream requires — when .planning is not directly under cwd', (t) => {
+    const savedSeam = require.cache[SEAM_PATH];
+    const savedWorktreeSafety = require.cache[WORKTREE_SAFETY_PATH];
+    const savedProjectRoot = require.cache[PROJECT_ROOT_PATH];
+    const savedSentinel = require.cache[SENTINEL_RESOLVED];
+
+    t.after(() => {
+      const restore = (key, saved) => { if (saved) require.cache[key] = saved; else delete require.cache[key]; };
+      restore(SEAM_PATH, savedSeam);
+      restore(WORKTREE_SAFETY_PATH, savedWorktreeSafety);
+      restore(PROJECT_ROOT_PATH, savedProjectRoot);
+      restore(SENTINEL_RESOLVED, savedSentinel);
+    });
+
+    let seamCalls = 0;
+    let worktreeSafetyCalls = 0;
+    let projectRootCalls = 0;
+
+    class FakeRuntimeBuildError extends Error {}
+    require.cache[SEAM_PATH] = fakeModule(SEAM_PATH, {
+      RuntimeBuildError: FakeRuntimeBuildError,
+      ensureRuntimeBuild: () => {
+        seamCalls += 1;
+        throw new FakeRuntimeBuildError('fake cold-tree build failure (#3582 reachability test)');
+      },
+    });
+    require.cache[WORKTREE_SAFETY_PATH] = fakeModule(WORKTREE_SAFETY_PATH, {
+      resolveWorktreeRoot: () => {
+        worktreeSafetyCalls += 1;
+        return { root: 'SHOULD-NOT-BE-REACHED' };
+      },
+    });
+    require.cache[PROJECT_ROOT_PATH] = fakeModule(PROJECT_ROOT_PATH, {
+      findProjectRoot: () => {
+        projectRootCalls += 1;
+        return 'SHOULD-NOT-BE-REACHED';
+      },
+    });
+    // Fresh require of isolation-sentinel.js itself — not strictly required
+    // (its own three requires live inside the function body and are
+    // re-evaluated on every call regardless of module-cache state), but keeps
+    // this test independent of whatever load order other files in the same
+    // worker already forced.
+    delete require.cache[SENTINEL_RESOLVED];
+    const { resolveSentinelRoot } = require(SENTINEL_MODULE_PATH);
+
+    const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-iso-sentinel-reach-'));
+    t.after(() => cleanup(cwd));
+    assert.equal(
+      fs.existsSync(path.join(cwd, '.planning')),
+      false,
+      'precondition: no .planning directly under cwd, so the early return must NOT fire',
+    );
+
+    const result = resolveSentinelRoot(cwd);
+
+    assert.equal(seamCalls, 1, 'ensureRuntimeBuild() must be called exactly once when .planning is not directly under cwd');
+    assert.equal(worktreeSafetyCalls, 0, 'a thrown RuntimeBuildError must short-circuit before resolveWorktreeRoot is ever reached');
+    assert.equal(projectRootCalls, 0, 'a thrown RuntimeBuildError must short-circuit before findProjectRoot is ever reached');
+    assert.equal(result, cwd, 'resolveSentinelRoot degrades to the raw cwd on a build failure, same as any other resolution failure');
+  });
+});

tests/lint-hooks-runtime-build-seam.test.cjs

@@ -0,0 +1,255 @@
+'use strict';
+
+/**
+ * Tests for `scripts/lint-hooks-runtime-build-seam.cjs` — the CI guard that
+ * every `hooks/**` file requiring a compiled `gsd-core/bin/lib/*.cjs` module
+ * must also self-heal via `ensureRuntimeBuild()` first (#3582).
+ *
+ * Mirrors the sibling `lint-*-drift.cjs` test convention (see e.g.
+ * `tests/lint-planning-artifact-writer-drift.test.cjs`): pure-function unit
+ * tests against in-memory strings for the fast cases, plus an on-disk
+ * fixture-tree test (via `scanRepo`) proving the guard genuinely detects a
+ * real violating file — "a ratchet that has never been proven to fail is
+ * worthless" (CLAUDE.md).
+ */
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  scanFile,
+  scanRepo,
+  stripComments,
+} = require('../scripts/lint-hooks-runtime-build-seam.cjs');
+const { createTempDir, cleanup } = require('./helpers.cjs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+
+// ─── Case 1: the guard passes clean against the REAL hooks/ tree ───────────
+
+describe('scanRepo — real hooks/ tree', () => {
+  test('reports zero violations against the actual hooks/ tree', () => {
+    const violations = scanRepo(REPO_ROOT);
+    assert.deepStrictEqual(
+      violations,
+      [],
+      `unexpected hooks/ runtime-build-seam violation(s): ${JSON.stringify(violations, null, 2)}`,
+    );
+  });
+
+  test('the real tree has REAL compiled-lib requires (the detector is not silently inert)', () => {
+    // A detector that never matches anything would also report zero
+    // violations. Prove it actually found the six #3582 hook files' real
+    // gsd-core/bin/lib/*.cjs requires and confirmed each is seam-wired.
+    const hookFiles = [
+      'gsd-agent-isolation-guard.js',
+      'gsd-cursor-subagent-start.js',
+      'gsd-statusline.js',
+      'gsd-check-update-worker.js',
+      'gsd-check-update.js',
+      'gsd-update-banner.js',
+    ];
+    for (const name of hookFiles) {
+      const text = fs.readFileSync(path.join(REPO_ROOT, 'hooks', name), 'utf8');
+      const { compiledLibRequires, hasSeamRequire, hasSeamCall } = scanFile(text);
+      assert.ok(compiledLibRequires.length > 0, `${name}: expected at least one compiled-lib require`);
+      assert.ok(hasSeamRequire, `${name}: expected a require of ensure-runtime-build.cjs`);
+      assert.ok(hasSeamCall, `${name}: expected an ensureRuntimeBuild(...) call`);
+    }
+  });
+});
+
+// ─── Case 2: pure-function unit tests (in-memory strings) ─────────────────
+
+describe('scanFile — pure detection', () => {
+  test('a file with no compiled-lib require has nothing to check', () => {
+    const text = "'use strict';\nconst fs = require('fs');\nmodule.exports = {};\n";
+    const { compiledLibRequires } = scanFile(text);
+    assert.deepStrictEqual(compiledLibRequires, []);
+  });
+
+  test('a compiled-lib require with NO seam require/call is detected', () => {
+    const text = [
+      "'use strict';",
+      "const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');",
+      'module.exports = { runtimes };',
+      '',
+    ].join('\n');
+    const { compiledLibRequires, hasSeamRequire, hasSeamCall } = scanFile(text);
+    assert.deepStrictEqual(compiledLibRequires, ['../gsd-core/bin/lib/capability-registry.cjs']);
+    assert.equal(hasSeamRequire, false);
+    assert.equal(hasSeamCall, false);
+  });
+
+  test('a compiled-lib require WITH a seam require + call is not flagged', () => {
+    const text = [
+      "'use strict';",
+      "const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');",
+      'function f() {',
+      '  ensureRuntimeBuild();',
+      "  const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');",
+      '  return runtimes;',
+      '}',
+      'module.exports = { f };',
+      '',
+    ].join('\n');
+    const { compiledLibRequires, hasSeamRequire, hasSeamCall } = scanFile(text);
+    assert.deepStrictEqual(compiledLibRequires, ['../gsd-core/bin/lib/capability-registry.cjs']);
+    assert.equal(hasSeamRequire, true);
+    assert.equal(hasSeamCall, true);
+  });
+
+  test('a seam REQUIRE with no CALL still counts as missing (import-only bypass)', () => {
+    const text = [
+      "'use strict';",
+      // Imported but never invoked — must not satisfy the guard.
+      "const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');",
+      "const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');",
+      'module.exports = { runtimes, ensureRuntimeBuild };',
+      '',
+    ].join('\n');
+    const { hasSeamRequire, hasSeamCall } = scanFile(text);
+    assert.equal(hasSeamRequire, true);
+    assert.equal(hasSeamCall, false);
+  });
+
+  test('a real require() inside a // comment is NOT counted (comment-only mention)', () => {
+    const text = [
+      "'use strict';",
+      "// example: require('../gsd-core/bin/lib/capability-registry.cjs')",
+      "const fs = require('fs');",
+      '',
+    ].join('\n');
+    const { compiledLibRequires } = scanFile(text);
+    assert.deepStrictEqual(compiledLibRequires, []);
+  });
+
+  // Regression: this repo's own hook comments legitimately spell the glob
+  // `gsd-core/bin/lib/*.cjs` inside a `//` line — a `/` immediately followed
+  // by `*` forms a bare `/*` token. A naive whole-text
+  // `/\*[\s\S]*?\*\//g` block-comment stripper reads that as an OPENING
+  // block comment and silently deletes everything up to the next unrelated
+  // `*/` later in the file — including real require() lines. Caught while
+  // authoring this guard (it ate its own seam require in
+  // hooks/gsd-agent-isolation-guard.js); locked here so it cannot regress.
+  test('a `//` comment containing a glob like lib/*.cjs does not swallow later real code', () => {
+    const text = [
+      "'use strict';",
+      '// gsd-core/bin/lib/*.cjs (foo.cjs, bar.cjs) are compiled artifacts.',
+      "const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');",
+      'function f() {',
+      '  ensureRuntimeBuild();',
+      "  const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');",
+      '  return runtimes;',
+      '}',
+      '/* a real, later, unrelated block comment */',
+      'module.exports = { f };',
+      '',
+    ].join('\n');
+    const stripped = stripComments(text);
+    assert.ok(
+      stripped.includes("require('../gsd-core/bin/ensure-runtime-build.cjs')"),
+      'the seam require must survive comment-stripping',
+    );
+    assert.ok(stripped.includes('ensureRuntimeBuild();'), 'the seam call must survive comment-stripping');
+    const { compiledLibRequires, hasSeamRequire, hasSeamCall } = scanFile(text);
+    assert.deepStrictEqual(compiledLibRequires, ['../gsd-core/bin/lib/capability-registry.cjs']);
+    assert.equal(hasSeamRequire, true);
+    assert.equal(hasSeamCall, true);
+  });
+
+  test('a genuine multi-line block comment is still stripped (no false-positive require inside it)', () => {
+    const text = [
+      "'use strict';",
+      '/**',
+      " * Example: require('../gsd-core/bin/lib/capability-registry.cjs') is",
+      ' * mentioned here only as documentation prose.',
+      ' */',
+      "const fs = require('fs');",
+      '',
+    ].join('\n');
+    const { compiledLibRequires } = scanFile(text);
+    assert.deepStrictEqual(compiledLibRequires, []);
+  });
+});
+
+// ─── Case 3: on-disk fixture tree via scanRepo — proves the guard CAN fail ─
+
+describe('scanRepo — on-disk fixture tree (proves the guard is not vacuous)', () => {
+  function writeFixtureTree(dir, { withSeam }) {
+    const hooksDir = path.join(dir, 'hooks');
+    fs.mkdirSync(hooksDir, { recursive: true });
+    const badLines = [
+      "'use strict';",
+      "const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');",
+      'module.exports = { runtimes };',
+      '',
+    ];
+    fs.writeFileSync(path.join(hooksDir, 'bad-hook.js'), badLines.join('\n'));
+
+    const goodLines = withSeam
+      ? [
+          "'use strict';",
+          "const { ensureRuntimeBuild } = require('../gsd-core/bin/ensure-runtime-build.cjs');",
+          'ensureRuntimeBuild();',
+          "const { runtimes } = require('../gsd-core/bin/lib/capability-registry.cjs');",
+          'module.exports = { runtimes };',
+          '',
+        ]
+      : [
+          "'use strict';",
+          "const fs = require('fs');",
+          'module.exports = { fs };',
+          '',
+        ];
+    fs.writeFileSync(path.join(hooksDir, 'good-hook.js'), goodLines.join('\n'));
+
+    // hooks/dist/ is the generated build-output copy — never scanned, even
+    // when it contains an identical un-sealed require.
+    const distDir = path.join(hooksDir, 'dist');
+    fs.mkdirSync(distDir, { recursive: true });
+    fs.writeFileSync(path.join(distDir, 'bad-hook.js'), badLines.join('\n'));
+  }
+
+  test('a fixture hook requiring a compiled module with NO seam is FLAGGED', (t) => {
+    const dir = createTempDir('gsd-lint-hooks-seam-');
+    t.after(() => cleanup(dir));
+    writeFixtureTree(dir, { withSeam: true });
+
+    const violations = scanRepo(dir);
+    const files = violations.map((v) => v.file);
+    assert.ok(files.includes('hooks/bad-hook.js'), `expected hooks/bad-hook.js flagged, got: ${JSON.stringify(files)}`);
+    assert.ok(
+      !files.includes('hooks/good-hook.js'),
+      `hooks/good-hook.js (seam-wired) must NOT be flagged, got: ${JSON.stringify(files)}`,
+    );
+    const bad = violations.find((v) => v.file === 'hooks/bad-hook.js');
+    assert.deepStrictEqual(bad.compiledLibRequires, ['../gsd-core/bin/lib/capability-registry.cjs']);
+    assert.ok(bad.missing.length > 0);
+  });
+
+  test('hooks/dist/ (generated build-output copy) is never scanned, even with the same violation', (t) => {
+    const dir = createTempDir('gsd-lint-hooks-seam-dist-');
+    t.after(() => cleanup(dir));
+    writeFixtureTree(dir, { withSeam: true });
+
+    const violations = scanRepo(dir);
+    const files = violations.map((v) => v.file);
+    assert.ok(
+      !files.some((f) => f.startsWith('hooks/dist/')),
+      `hooks/dist/ must be excluded from the scan, got: ${JSON.stringify(files)}`,
+    );
+  });
+
+  test('a fixture tree with NO offending hooks reports zero violations (no false positive)', (t) => {
+    const dir = createTempDir('gsd-lint-hooks-seam-clean-');
+    t.after(() => cleanup(dir));
+    writeFixtureTree(dir, { withSeam: false });
+    fs.unlinkSync(path.join(dir, 'hooks', 'bad-hook.js'));
+
+    const violations = scanRepo(dir);
+    assert.deepStrictEqual(violations, []);
+  });
+});