session-orchestrator 5.2.0 → 5.3.0

package/scripts/lib/scope-gate.mjs

@@ -11,7 +11,7 @@
  * invariant for all exports below — see #554 A2.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 
 import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
@@ -1678,6 +1678,610 @@ function clockAgeMs(file, field, now) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Absolute-grant grading (#1398 cond. 4, #1405, #1406)
+// ---------------------------------------------------------------------------
+//
+// ONE grading predicate, TWO consumers (BV-003). It lived in
+// `scripts/validate-wave-scope.mjs` as four module-local helpers, where only the
+// pre-dispatch CLI could reach it — so `hooks/enforce-scope.mjs` Gate 5b honoured
+// grants the validator would have refused, and a manifest that never went through
+// the CLI was never graded at all. Both now call {@link gradeScopeEntry}:
+//
+//   - the VALIDATOR turns an `error` verdict into exit 1 (pre-dispatch refusal),
+//     passing an fs-backed `resolve` so the canonicalisation below is real;
+//   - the HOOK keeps ALLOWING exactly what it allows today and emits ONE WARN
+//     when the grant it just matched grades `error`. It passes NO resolver — see
+//     the ceiling on `opts.resolve`.
+//
+// ## Why canonicalisation is the ROOT fix, not two more denylist strings (#1405)
+//
+// Gate 5b matches the REALPATH-RESOLVED write candidate (enforce-scope.mjs
+// SECURITY-REQ-03) against the raw allowedPaths entry. So the set of files a
+// grant reaches is decided by the CANONICAL spelling, while the validator graded
+// the LITERAL one. Measured on this host 2026-09-20 (`fs.realpathSync`):
+// `/etc` → `/private/etc`, `/var` → `/private/var`, `/tmp` → `/private/tmp`.
+// Two opposite defects followed from that one gap:
+//
+//   - `/private/etc/**` and `/private/var/**` passed with a WARN although they
+//     grant exactly what the denylisted `/etc/**` and `/var/**` grant, because
+//     the denylist only ever saw the top segment `private`;
+//   - `/tmp/x/**` passed and was advertised as "honoured by Gate 5b" although the
+//     hook can never match it — the candidate arrives as `/private/tmp/x/a.md`
+//     and `pathMatchesPattern('/private/tmp/x/a.md', '/tmp/x/**') === false`. A
+//     grant that matches nothing is not a safe grant, it is a silent no-op that
+//     reads as permission.
+//
+// Adding `private/etc` and `private/var` to the denylist would have fixed the
+// first pair on macOS only, and nothing at all of the second. Resolving the
+// grant's literal prefix the same direction the hook resolves candidates fixes
+// both, and degrades to today's behaviour wherever a prefix does not exist.
+//
+// ## Named ceilings (BV-004)
+//
+//   - HOME grants (`/Users/…`, `/home/…`) are graded by SHAPE and RETURN before
+//     canonicalisation. Deliberate: that is the one root where a legitimate
+//     out-of-repo grant is routine, and the shape rule must not become
+//     platform-dependent (on macOS `fs.realpathSync('/home')` is
+//     `/System/Volumes/Data/home`, whose top segment is denylisted — grading a
+//     Linux-home grant against that would refuse it on a macOS coordinator and
+//     accept it on a Linux one). Revisit trigger: the first home grant Gate 5b
+//     provably never matches because the home itself is a symlink.
+//   - With NO `resolve` the grader is PURE and grades the literal spelling only.
+//     NO PRODUCTION CALLER IS IN THAT SHAPE ANY MORE (#1398 cond. 4, closed
+//     2026-09-21): `hooks/enforce-scope.mjs` Gate 5b was the one resolver-free
+//     caller, and it now passes {@link canonicalizeGrantPrefix} — the same
+//     function `scripts/validate-wave-scope.mjs` passes — because the revisit
+//     trigger below was MET. Measured A/B in one process, 200 repetitions,
+//     median: the hook grades ONE grant per Gate 5b hit, +0.067 ms and 15
+//     `realpathSync` calls, against a 5 ms decision threshold; the live 64-entry
+//     manifest cost 0 syscalls (0 absolute entries — only an absolute grant
+//     reaches the resolver at all). That closed the last verdict divergence,
+//     `/tmp/x/**` (1 of the 9 #1398 probes), which no literal list could reach.
+//     The resolver-free shape remains SUPPORTED and tested — it is what a
+//     caller with no filesystem gets — and it keeps every literal-spelling
+//     verdict (`/etc/**`, `/Users/<u>/.ssh/**`, `/Users/<u>/**`). Since #1418 it
+//     ALSO reaches the first canonical-alias class, because the two spellings
+//     macOS actually mints (`/private/etc`, `/private/var`) are on
+//     DENIED_ABSOLUTE_ALIAS_ROOTS as literals. Those entries STAY: they cost
+//     zero syscalls and they are the only thing standing between a
+//     hypothetical future resolver-free caller and a hole on this platform
+//     (measured 2026-09-20 @ 7e110a2a). What such a caller still cannot reach is
+//     the SECOND class, `non-canonical` (`/tmp/x/**`) — no literal list
+//     substitutes for the realpath call — which is why the hook now makes it.
+//     Revisit trigger: a caller that CANNOT supply a resolver (no filesystem, or
+//     a hot path measured expensive on its own host) — it is back to the
+//     residual above, one missing NOTICE, never a wider allow.
+// ---------------------------------------------------------------------------
+
+/**
+ * Well-known top-level system directories a wave scope may never grant.
+ *
+ * A FIXED DENYLIST, not a segment-count threshold: the #792 legitimate grant
+ * (`/private/tmp/<session>/scratchpad/**`) is itself a shallow grant under an
+ * unusual root ("private"), so any depth heuristic tight enough to catch
+ * `/etc/**` would catch that too.
+ *
+ * `Users` and `home` are deliberately ABSENT (#1398/#1402): they are the only two
+ * roots under which a legitimate grant is routine, and denying them flat made the
+ * validator contradict the hook it validates for. {@link classifyHomeGrant}
+ * grades them by shape instead.
+ * @type {ReadonlyArray<string>}
+ */
+const DENIED_ABSOLUTE_TOP_SEGMENTS = Object.freeze([
+  'etc',
+  'root',
+  'bin',
+  'sbin',
+  'usr',
+  'System',
+  'var',
+  'boot',
+  'dev',
+  'proc',
+  'sys',
+  'Library',
+  'Applications',
+  'Windows',
+]);
+
+/**
+ * macOS symlink ALIASES of the denylisted roots above, spelled literally.
+ *
+ * `fs.realpathSync('/etc')` is `/private/etc` and `/var` → `/private/var` on
+ * this platform, and Gate 5b matches the REALPATH-RESOLVED write candidate — so
+ * `/private/etc/**` is the spelling that actually reaches everything under
+ * `/etc`, while `/etc/**` reaches nothing there. {@link gradeScopeEntry}'s
+ * canonical rung catches both, but ONLY when a resolver is passed, and
+ * `hooks/enforce-scope.mjs` passes none (PreToolUse hot path). Listing the two
+ * aliases literally gives the resolver-free caller the same verdict at ZERO
+ * syscalls. Measured 2026-09-20 @ 7e110a2a, before: hook `warn/absolute` vs.
+ * validator `error/denied-system-dir` for both entries — the feature was inert
+ * on the only platform that mints these spellings.
+ *
+ * `private/tmp` is deliberately ABSENT, and the omission is load-bearing: `tmp`
+ * is not on the denylist either, because `/private/tmp/<session>/scratchpad/**`
+ * is the #792 SANCTIONED grant. Aliasing it would refuse the one out-of-repo
+ * grant this file exists to permit.
+ *
+ * Named ceiling (BV-004): a literal list covers the two aliases this platform
+ * mints and nothing else — a host whose `/usr` is a symlink still needs the
+ * resolver to be graded. Revisit trigger: the first denylisted root that gains
+ * a symlink alias on any platform the fleet runs on.
+ * @type {ReadonlyArray<string>}
+ */
+const DENIED_ABSOLUTE_ALIAS_ROOTS = Object.freeze(['private/etc', 'private/var']);
+
+/**
+ * Case-fold a path or path segment for comparison against the sets below.
+ *
+ * Every comparison here MUST go through this: the classification is a proxy for
+ * what the FILESYSTEM will resolve, and the two default filesystems this repo
+ * runs on (APFS on macOS, NTFS on Windows) are case-INSENSITIVE while neither
+ * `path.posix.normalize` nor `fs.realpath()` corrects the spelling. Measured
+ * 2026-09-19: `/Users/<u>/.ssh` and `/users/<u>/.ssh` report the SAME inode, as
+ * do `/Users/<u>/Library/Keychains` and `/users/<u>/library/Keychains`.
+ *
+ * `'en-US'` is pinned explicitly: the host locale must not decide a security
+ * verdict (a Turkish default locale folds `I` to `ı`, taking `LIBRARY` out of
+ * the match).
+ *
+ * Named ceiling (BV-004): folding is strictly STRICTER on a case-SENSITIVE
+ * filesystem, where `/library` really is a different directory from `/Library`.
+ * Revisit trigger: the first legitimate grant refused for that reason.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function foldPath(value) {
+  return value.toLocaleLowerCase('en-US');
+}
+
+/**
+ * A root followed by a separator, used to split a root-wide grant from its tail.
+ * The optional drive designator is what makes this independent of
+ * `path.isAbsolute()`, which is platform-native: on a POSIX host it never
+ * reports `C:\…` as absolute, so a Windows root grant would slip past ungraded.
+ */
+const FILESYSTEM_ROOT_PREFIX_RE = /^(?:[A-Za-z]:)?[\\/]+/;
+
+/**
+ * Does this entry grant the WHOLE filesystem — the bare root, or any spelling
+ * that differs from it only by wildcard segments?
+ *
+ * The literal-only predecessor was the wrong way round (measured 2026-09-20 @
+ * 7e110a2a): `gradeScopeEntry('/')` → `error/filesystem-root` and `/etc/**` →
+ * `error/denied-system-dir`, while `/**` — which `pathMatchesPattern` matches
+ * for EVERY path at Gate 5b, i.e. strictly wider than both — graded
+ * `warn/absolute`. The check that refused the root was literal; the thing that
+ * granted the root was a glob.
+ *
+ * NOT root-wide, and deliberately so: any entry naming a literal segment after
+ * the root (`/etc/**`, `/Users/<u>/**`, or a leading `**` followed by a literal
+ * segment). Those are deep globs and keep their own, narrower verdicts.
+ *
+ * @param {string} entry
+ * @returns {boolean}
+ */
+function isFilesystemRootGrant(entry) {
+  const root = FILESYSTEM_ROOT_PREFIX_RE.exec(entry);
+  if (root === null) return false;
+  const tail = entry.slice(root[0].length);
+  if (tail.length === 0) return true;
+  // An empty segment comes from a doubled or trailing separator ("//**", "/**/"),
+  // which widens nothing; any other non-wildcard segment narrows the grant.
+  return tail.split(/[\\/]+/).every((seg) => seg === '' || seg === '*' || seg === '**');
+}
+
+/**
+ * Top-level segments that open a HOME directory rather than a system one —
+ * macOS (`/Users/<user>`) and Linux (`/home/<user>`). Stored FOLDED.
+ * @type {ReadonlySet<string>}
+ */
+const HOME_TOP_SEGMENTS = new Set(['users', 'home']);
+
+/**
+ * How many LITERAL segments a home grant must name before its first wildcard:
+ * `<home-root>` / `<user>` / `<one directory>` = 3. Two is the bare home itself,
+ * and a wildcard inside those three widens the grant to a whole home.
+ */
+const HOME_MIN_LITERAL_SEGMENTS = 3;
+
+/**
+ * The ONE dot-directory carve-out (#1406) and the depth that buys it.
+ *
+ * `~/.cache/<project>/…` is where a study contract keeps its data and where the
+ * hook honours the path today; `~/.cache/**` itself is not — it is every tool's
+ * cache on the host, including credential caches. Four literal segments
+ * (`/Users` / `<user>` / `.cache` / `<project>`) is the narrowest rule that
+ * separates the two. Every OTHER dot-directory and `Library` stay refused at any
+ * depth: `.ssh`, `.aws`, `.gnupg`, `.config`, `.claude`, `.codex` carry
+ * credentials or the agent guards themselves at their FIRST level, so no depth
+ * makes them safe.
+ */
+const CACHE_CARVEOUT_SEGMENT = '.cache';
+const CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS = 4;
+
+/**
+ * Home subdirectories that carry credentials, tokens, or the agent guards
+ * themselves. ONE predicate rather than a list, because the list is open-ended
+ * and every omission is a live credential store: any dot-prefixed directory
+ * (`.ssh`, `.aws`, `.gnupg`, `.config` — which holds tokens AND `owner.yaml` —
+ * `.claude`, `.codex`, `.cursor`, `.docker`, `.npmrc`, `.netrc`) plus macOS
+ * `Library` (whose `Keychains` subtree carries no leading dot).
+ * @param {string} segment
+ * @returns {boolean}
+ */
+function isSensitiveHomeSegment(segment) {
+  return segment.startsWith('.') || foldPath(segment) === 'library';
+}
+
+/**
+ * Is `candidate` the directory `root` itself, or below it? Fold-compared, and
+ * anchored on a `/` boundary so `/system-backup` is not read as being under
+ * `/system`.
+ * @param {string} candidate
+ * @param {string} root
+ * @returns {boolean}
+ */
+function isUnderRoot(candidate, root) {
+  const c = foldPath(candidate);
+  const r = foldPath(root);
+  if (r === '/') return c.startsWith('/');
+  return c === r || c.startsWith(`${r}/`);
+}
+
+/**
+ * The denylisted system directory this prefix sits under, or `null`.
+ *
+ * `resolveRoot` is applied to each denied root before the comparison, so the
+ * CANONICAL pass catches `/private/etc` (= `realpath('/etc')`) without the
+ * denylist having to spell out a second, platform-specific alias for every
+ * entry. With the identity resolver this is the plain literal check.
+ *
+ * The {@link DENIED_ABSOLUTE_ALIAS_ROOTS} pass is NOT routed through
+ * `resolveRoot`: those entries are already the canonical spelling, so resolving
+ * them buys nothing and would spend the syscall the resolver-free caller exists
+ * to avoid.
+ *
+ * @param {string} prefix — an absolute, `.`-normalized literal path prefix
+ * @param {(p: string) => string} resolveRoot
+ * @returns {string|null} the denylisted root (canonical casing, no leading `/`)
+ *   that matched
+ */
+function deniedRootFor(prefix, resolveRoot) {
+  for (const segment of DENIED_ABSOLUTE_TOP_SEGMENTS) {
+    if (isUnderRoot(prefix, resolveRoot(`/${segment}`))) return segment;
+  }
+  for (const alias of DENIED_ABSOLUTE_ALIAS_ROOTS) {
+    if (isUnderRoot(prefix, `/${alias}`)) return alias;
+  }
+  return null;
+}
+
+/**
+ * The LITERAL prefix of an absolute grant — everything before its first segment
+ * carrying a `*` (`/private/tmp/x/**` → `/private/tmp/x`, `/Users/*\/p/**` →
+ * `/Users`, `/etc/passwd` → `/etc/passwd`). `/` when the first segment already
+ * globs. This, never the raw entry, is what gets canonicalised: the wildcard
+ * part has no filesystem identity.
+ * @param {string} normalizedEntry
+ * @returns {string}
+ */
+function literalGrantPrefix(normalizedEntry) {
+  const kept = [];
+  for (const segment of normalizedEntry.split('/')) {
+    if (segment.includes('*')) break;
+    kept.push(segment);
+  }
+  const prefix = kept.join('/');
+  return prefix.length === 0 ? '/' : prefix;
+}
+
+/**
+ * Grade an absolute entry whose top-level segment is a home root.
+ *
+ * The rule is SHAPE-based, not identity-based, because the hook grants by shape:
+ * Gate 5b feeds the entry straight to {@link pathMatchesPattern}, where a
+ * wildcard in an early segment silently widens the grant. Measured 2026-09-19:
+ * `/Users/alice/**` matches `/Users/alice/.ssh/authorized_keys`, and a bare `*`
+ * as the third segment matches `/Users/alice/.ssh/id` — a wildcard there reaches
+ * dot-directories. So the depth is counted over the LITERAL prefix, never over
+ * the raw segment count.
+ *
+ * Named ceiling (BV-004): only the FIRST directory below the home is checked for
+ * sensitivity. A dot-directory DEEPER in the tree (`…/vault/.git/hooks/**`) stays
+ * ungated, because at that depth the grant is already scoped to one project the
+ * operator named explicitly. Revisit trigger: the first time a wave legitimately
+ * needs a grant INTO a foreign repo.
+ *
+ * @param {string} normalizedEntry — the entry with `.` segments collapsed, so a
+ *   `/Users/./alice/.ssh` cannot shift the literal prefix and hide a
+ *   dot-directory at index 2.
+ * @returns {{verdict: 'error'|'warn', reason: string}|null} null when the entry
+ *   is not a home grant at all.
+ */
+function classifyHomeGrant(normalizedEntry) {
+  const segments = normalizedEntry.split('/').filter(Boolean);
+  if (segments.length === 0 || !HOME_TOP_SEGMENTS.has(foldPath(segments[0]))) return null;
+
+  /** Literal prefix: the segments before the first one carrying a wildcard. */
+  const literal = [];
+  for (const segment of segments) {
+    if (segment.includes('*')) break;
+    literal.push(segment);
+  }
+
+  if (literal.length < HOME_MIN_LITERAL_SEGMENTS) {
+    return {
+      verdict: 'error',
+      reason:
+        `grants a home directory at or above the user level — a home grant must name at least ` +
+        `${HOME_MIN_LITERAL_SEGMENTS} literal path segments before its first wildcard ` +
+        `(e.g. /Users/<user>/<project>/**); this one names ${literal.length}, so Gate 5b would ` +
+        `honour it across the whole home (measured: /Users/<user>/** matches ~/.ssh/authorized_keys)`,
+    };
+  }
+
+  const firstBelowHome = literal[HOME_MIN_LITERAL_SEGMENTS - 1];
+  // #1406 — the one carve-out, and it is a DEPTH rule, not a name on a list:
+  // `~/.cache/**` stays refused, `~/.cache/<project>/…` is honoured.
+  const cacheCarveout =
+    foldPath(firstBelowHome) === CACHE_CARVEOUT_SEGMENT &&
+    literal.length >= CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS;
+  if (!cacheCarveout && isSensitiveHomeSegment(firstBelowHome)) {
+    return {
+      verdict: 'error',
+      reason:
+        `grants a sensitive home subdirectory ("${firstBelowHome}") — dot-directories and Library ` +
+        `hold credentials, tokens, owner.yaml and the agent guards themselves; scope a project ` +
+        `directory instead (the sole exception is ~/.cache/<project>/…, which must name at least ` +
+        `${CACHE_CARVEOUT_MIN_LITERAL_SEGMENTS} literal segments — #1406)`,
+    };
+  }
+
+  return { verdict: 'warn', reason: 'home-directory grant honoured by Gate 5b' };
+}
+
+/**
+ * One process resolves the same ~14 denylist roots for every absolute grant it
+ * grades; the cache keeps that at one `realpathSync` per distinct path.
+ *
+ * Named ceiling (BV-004): process-lifetime, never invalidated. Both real callers
+ * are one-shot processes (a PreToolUse hook, a CLI run), where a mount changing
+ * mid-process is not a case. Revisit trigger: the first long-running consumer —
+ * it needs a fresh map per call, not this one.
+ * @type {Map<string, string>}
+ */
+const CANONICAL_PREFIX_CACHE = new Map();
+
+/**
+ * Memoized canonicaliser for the LITERAL prefix of an absolute grant — the
+ * `resolve` injection {@link gradeScopeEntry} needs (#1405).
+ *
+ * THE DIRECTION MATTERS: `hooks/enforce-scope.mjs` Gate 5b matches the
+ * REALPATH-RESOLVED write candidate (SECURITY-REQ-03) against the raw
+ * allowedPaths entry, so the files a grant actually reaches are decided by the
+ * canonical spelling. Grading the literal one let `/private/etc/**` pass while
+ * `/etc/**` was refused (same directory on macOS — `realpath('/etc')` is
+ * `/private/etc`), and let `/tmp/x/**` pass while the hook could never match it.
+ * Resolving HERE, the same direction the hook resolves candidates, is the root
+ * fix; adding two more denylist strings would have been neither.
+ *
+ * WHY IT LIVES IN THE HOOK-SAFE MODULE (#1398 cond. 4). It was kept in the CLI
+ * layer on the assumption that ~14 `realpathSync` calls are too expensive for a
+ * PreToolUse hot path. Measured 2026-09-21 on this host (A/B in one process, 200
+ * repetitions, median) that assumption does not hold, and the split it bought
+ * was a live verdict divergence:
+ *   - the hook grades exactly ONE grant per Gate 5b hit (the entry that matched
+ *     the write candidate), not the whole manifest: **+0.067 ms**, 15
+ *     `realpathSync` calls — 75× under the 5 ms decision threshold;
+ *   - the whole 9-grant probe set of #1398: **+0.154 ms**;
+ *   - the live 64-entry manifest of this session: **0** `realpathSync` calls,
+ *     because 0 of its entries are absolute. Only an absolute grant reaches the
+ *     resolver at all, and Gate 5b only runs for an out-of-repo write.
+ * The module header's "no I/O at import time" is untouched: this is I/O inside a
+ * function, exactly as {@link findScopeFile} already does with `existsSync`.
+ *
+ * PURE ENOUGH FOR LINUX CI: a prefix that does not exist never throws — the walk
+ * climbs to the nearest existing ancestor and re-attaches the missing suffix (the
+ * same strategy `hooks/enforce-scope.mjs` uses for a Write to a not-yet-existing
+ * file), and a wholly unresolvable path returns the input unchanged. On Linux
+ * `/etc` and `/var` are not symlinks, so the canonical pass is a no-op there and
+ * the literal verdicts carry the whole load.
+ *
+ * @param {string} absPath
+ * @returns {string}
+ */
+export function canonicalizeGrantPrefix(absPath) {
+  const cached = CANONICAL_PREFIX_CACHE.get(absPath);
+  if (cached !== undefined) return cached;
+
+  // Assigned on BOTH loop exits (resolved, or nothing on this branch resolves);
+  // an initializer here would be dead — see the eslint `no-useless-assignment`
+  // rule, which is on in this repo.
+  let result;
+  let current = absPath;
+  const missing = [];
+  for (;;) {
+    try {
+      const real = realpathSync(current).split(path.sep).join('/');
+      const suffix = [...missing].reverse().join('/');
+      result = suffix.length === 0 ? real : `${real === '/' ? '' : real}/${suffix}`;
+      break;
+    } catch {
+      const parent = path.posix.dirname(current);
+      if (parent === current) {
+        result = absPath; // nothing on this branch resolves — keep the literal
+        break;
+      }
+      missing.push(path.posix.basename(current));
+      current = parent;
+    }
+  }
+
+  CANONICAL_PREFIX_CACHE.set(absPath, result);
+  return result;
+}
+
+/**
+ * Grade ONE `allowedPaths` / fileScope entry as a Gate 5b grant.
+ *
+ * The single grading predicate shared by `scripts/validate-wave-scope.mjs`
+ * (refuses `error` before dispatch) and `hooks/enforce-scope.mjs` Gate 5b (WARNs
+ * on `error`, never denies). See the section block above for the design.
+ *
+ * Verdict order — each rung is load-bearing:
+ *   1. a tilde entry (`~/…`) — NOTHING in the scope chain expands it (#1405.3),
+ *      so it grants nothing while reading like a grant;
+ *   2. a filesystem-root grant — the bare root, where `pathMatchesPattern(p, '/')`
+ *      is `true` for every path (the `dir/` prefix branch), AND every spelling
+ *      that adds only wildcards to it (`/**`, `/*`, `C:\**`), which reaches the
+ *      same set through the glob branch;
+ *   3. non-absolute entries are not ours to grade → `null`;
+ *   4. the denylisted system roots, LITERAL spelling;
+ *   5. home grants, by shape — these RETURN, see the ceiling above;
+ *   6. the denylisted system roots, CANONICAL spelling (#1405.1);
+ *   7. a literal prefix that is not canonical — Gate 5b can never match it
+ *      (#1405.2);
+ *   8. otherwise a WARN, split only so the narrowest shape (a concrete absolute
+ *      file) says so.
+ *
+ * Pure with no `opts.resolve`; never throws (a throwing resolver degrades to the
+ * literal spelling). Returns `null` for every ordinary relative entry.
+ *
+ * @param {string} entry
+ * @param {{resolve?: (absPath: string) => string}} [opts] — canonicaliser for an
+ *   absolute path; MUST tolerate a non-existent path (resolve the nearest
+ *   existing ancestor, or return the input unchanged).
+ * @returns {{verdict: 'error'|'warn', code: string, message: string}|null}
+ */
+export function gradeScopeEntry(entry, opts = {}) {
+  if (typeof entry !== 'string' || entry.length === 0) return null;
+  const bag = opts !== null && typeof opts === 'object' ? opts : {};
+  const resolver = typeof bag.resolve === 'function' ? bag.resolve : null;
+  /** @param {string} p @returns {string} */
+  const canonicalize = (p) => {
+    if (resolver === null) return p;
+    try {
+      const resolved = resolver(p);
+      return typeof resolved === 'string' && resolved.length > 0 ? resolved : p;
+    } catch {
+      return p;
+    }
+  };
+
+  if (entry === '~' || entry.startsWith('~/')) {
+    return {
+      verdict: 'error',
+      code: 'tilde',
+      message:
+        `contains a tilde path: ${entry} — the tilde is NOT expanded by hooks/enforce-scope.mjs ` +
+        `Gate 5b, nor anywhere else in the scope chain, so this entry matches nothing while ` +
+        `reading like a grant; write the expanded absolute path instead`,
+    };
+  }
+
+  if (isFilesystemRootGrant(entry)) {
+    return {
+      verdict: 'error',
+      code: 'filesystem-root',
+      message:
+        `grants the entire filesystem root: ${entry} — refused unconditionally, this can never ` +
+        `be a valid wave scope (a root followed only by wildcards reaches every path Gate 5b ` +
+        `can see, exactly as the bare root does)`,
+    };
+  }
+
+  if (!path.isAbsolute(entry)) return null;
+
+  // `.` segments are collapsed BEFORE any classification (#1398): without it,
+  // `/Users/./alice/.ssh/**` has a literal prefix whose third element is
+  // "alice", so the dot-directory sits at index 3 and the sensitivity check
+  // misses it. `..` needs no handling — the caller's traversal check rejects
+  // any entry containing `../`, whatever else it is.
+  const normalized = path.posix.normalize(entry);
+  const literalPrefix = literalGrantPrefix(normalized);
+
+  const deniedLiteral = deniedRootFor(literalPrefix, (p) => p);
+  if (deniedLiteral !== null) {
+    return {
+      verdict: 'error',
+      code: 'denied-system-dir',
+      message:
+        `contains a well-known system/home directory grant: ${entry} ` +
+        `(denylisted system root "/${deniedLiteral}") — refused, scope a narrower path instead`,
+    };
+  }
+
+  const home = classifyHomeGrant(normalized);
+  if (home !== null) {
+    return home.verdict === 'error'
+      ? { verdict: 'error', code: 'home-grant', message: `${home.reason}: ${entry}` }
+      : {
+          verdict: 'warn',
+          code: 'home-grant',
+          message:
+            `contains an absolute (out-of-repo) path: ${entry} — ${home.reason}; ` +
+            `verify this grant is intentional`,
+        };
+  }
+
+  const canonicalPrefix = canonicalize(literalPrefix);
+
+  const deniedCanonical = deniedRootFor(canonicalPrefix, canonicalize);
+  if (deniedCanonical !== null) {
+    return {
+      verdict: 'error',
+      code: 'denied-system-dir',
+      message:
+        `contains a well-known system/home directory grant: ${entry} — its literal prefix ` +
+        `"${literalPrefix}" resolves to "${canonicalPrefix}", inside the denylisted system ` +
+        `directory "${deniedCanonical}"; Gate 5b matches the REALPATH-resolved write candidate, ` +
+        `so this spelling grants exactly what "/${deniedCanonical}/**" grants — refused, scope a ` +
+        `narrower path instead`,
+    };
+  }
+
+  if (canonicalPrefix !== literalPrefix) {
+    return {
+      verdict: 'error',
+      code: 'non-canonical',
+      message:
+        `contains a non-canonical absolute path: ${entry} — hooks/enforce-scope.mjs Gate 5b ` +
+        `matches the REALPATH-resolved write candidate, which never carries this spelling ` +
+        `("${literalPrefix}" resolves to "${canonicalPrefix}"), so this grant can match NOTHING; ` +
+        `write ${canonicalPrefix}${normalized.slice(literalPrefix.length)} instead`,
+    };
+  }
+
+  // KNOWN DIVERGENCE, carried over from #1402 and still message-only: `*` is the
+  // sole wildcard this check knows, while {@link isGlobScopeEntry} ALSO counts a
+  // trailing `/` and {@link pathMatchesPattern} honours that directory-prefix
+  // form. So `/private/tmp/x/` reads as "no wildcard" here and is described as an
+  // exact-path match although it grants a whole subtree. Both branches only WARN,
+  // so the cost is one wrong sentence on stderr and no verdict — which is why it
+  // is reported rather than patched. Revisit if either branch ever hard-rejects.
+  if (!entry.includes('*')) {
+    return {
+      verdict: 'warn',
+      code: 'bare-absolute-file',
+      message:
+        `contains a bare absolute file grant with no wildcard: ${entry} — honoured by ` +
+        `hooks/enforce-scope.mjs Gate 5b as an exact-path match (the narrowest possible grant); ` +
+        `verify this grant is intentional`,
+    };
+  }
+
+  return {
+    verdict: 'warn',
+    code: 'absolute',
+    message:
+      `contains an absolute (out-of-repo) path: ${entry} — honoured by hooks/enforce-scope.mjs ` +
+      `Gate 5b; verify this grant is intentional`,
+  };
+}
+
 /**
  * Absolute epoch-ms at which this session started, or `null` when no clock is
  * readable — the value {@link classifyEmptyScope} compares a manifest's mtime