session-orchestrator 5.2.0 → 5.4.0

package/scripts/site-numbers.mjs

@@ -91,6 +91,13 @@
  * silent skip — a generator that quietly stops filling a surface is the exact
  * failure this file exists to end.
  *
+ * ## The sitemap `<lastmod>` (`site/sitemap.xml`, #1484)
+ *
+ * `--write` changes what `/` and `/de` SHOW, so it also dates them in the
+ * sitemap: `lastmod` becomes max(lastmod, the page's own `counted-at` cell).
+ * `--check` reports a `lastmod` older than that cell as drift. Rule, mapping and
+ * reasons: `SITEMAP_PAGES`.
+ *
  * Exit codes (`.claude/rules/cli-design.md`):
  *   0 — no drift (--check) / files updated or already current (--write)
  *   1 — drift found (--check), or a contract violation in either mode
@@ -99,7 +106,7 @@
  */
 
 import { readFileSync, writeFileSync, readdirSync, existsSync, statSync } from 'node:fs';
-import { join, resolve, relative } from 'node:path';
+import { join, resolve, relative, sep } from 'node:path';
 import { execFileSync } from 'node:child_process';
 
 import { writeStdoutLineSync, writeJsonAtomicSync } from './lib/io.mjs';
@@ -963,6 +970,118 @@ export function syncCensusBlocks(siteDir, values, { write = false } = {}) {
   return CENSUS_BLOCK_FILES.map((file) => syncCensusBlock(siteDir, values, { write, file }));
 }
 
+// ---------------------------------------------------------------------------
+// The sitemap <lastmod> in site/sitemap.xml (#1484)
+// ---------------------------------------------------------------------------
+
+/** The sitemap, relative to the SITE directory. */
+export const SITEMAP_FILE = 'sitemap.xml';
+
+/**
+ * Every page ↔ sitemap `<loc>`, explicitly.
+ *
+ * Why the sitemap is this generator's business: `--write` changes what `/` and
+ * `/de` show (version card, number cards, "Counted on … at commit …"), and the
+ * release that ran it left their `lastmod` behind. Measured 2026-10-01: `/`
+ * claimed 2026-09-08 while its content was counted 2026-09-22.
+ *
+ * The rule takes no second clock. A page's `counted-at` cell is the date this
+ * script last changed that page — `rewrite()` stamps every cell in one pass —
+ * so `lastmod` becomes max(lastmod, that cell), and never moves backwards. A
+ * page without a `counted-at` cell (the guide and the legal pages, whose only
+ * cell is the header version) is never dated: a version bump in a page header
+ * is not a content change.
+ *
+ * Unknown either way is an ERROR, never a skip (the `METRIC_IDS` rule): a
+ * sitemap `<loc>` missing here would never be dated, and a page carrying cells
+ * that is missing here would drift unseen.
+ */
+export const SITEMAP_PAGES = Object.freeze([
+  { page: 'index.html', loc: 'https://session-orchestrator.com/' },
+  { page: 'de/index.html', loc: 'https://session-orchestrator.com/de' },
+  { page: 'guide/index.html', loc: 'https://session-orchestrator.com/guide' },
+  { page: 'impressum/index.html', loc: 'https://session-orchestrator.com/impressum' },
+  { page: 'datenschutz/index.html', loc: 'https://session-orchestrator.com/datenschutz' },
+]);
+
+const URL_BLOCK_RE = /<url>([\s\S]*?)<\/url>/g;
+const ISO_DAY_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Judge (and optionally rewrite) the `<lastmod>` of every sitemap entry. Only the
+ * date text of an entry that moves is rewritten; the rest of the file is handed
+ * back byte-for-byte.
+ *
+ * @param {string} siteDir
+ * @param {Array<{page:string, metrics:string[], countedAt:string|null}>} pages
+ *   every HTML file under `siteDir` carrying metric cells: its site-relative path
+ *   (`/`-separated), its metric ids, and its `counted-at` cell as it stands AFTER
+ *   this run (`null` when it has none)
+ * @param {{write?: boolean}} [opts]
+ * @returns {{present:boolean, file:string, errors?:string[],
+ *            drift?:Array<{loc:string, line:number, actual:string, expected:string}>,
+ *            written?:boolean}}
+ */
+export function syncSitemapLastmod(siteDir, pages, { write = false } = {}) {
+  const abs = join(siteDir, SITEMAP_FILE);
+  // Absent file: like the census blocks, not this generator's to create.
+  if (!existsSync(abs) || !statSync(abs).isFile()) return { present: false, file: abs };
+
+  const errors = [];
+  const dated = new Map(); // loc → the counting date its page carries
+  for (const p of pages) {
+    const entry = SITEMAP_PAGES.find((e) => e.page === p.page);
+    if (!entry) {
+      errors.push(
+        `${p.page} carries metric cells but has no sitemap mapping — known pages: ` +
+          SITEMAP_PAGES.map((e) => e.page).join(', '),
+      );
+    } else if (p.countedAt !== null) {
+      if (ISO_DAY_RE.test(p.countedAt)) dated.set(entry.loc, p.countedAt);
+      else errors.push(`${p.page}: counted-at cell "${p.countedAt}" is not a YYYY-MM-DD date`);
+    } else if (p.metrics.some((m) => m !== 'version')) {
+      // Counted cells with no stamp to date them by: their changes would never
+      // reach the sitemap.
+      errors.push(`${p.page} carries counted cells but no counted-at cell — its lastmod cannot be dated`);
+    }
+  }
+
+  const text = readFileSync(abs, 'utf8');
+  const drift = [];
+  const seen = new Set();
+  const next = text.replace(URL_BLOCK_RE, (block, inner, offset) => {
+    const loc = /<loc>([^<]*)<\/loc>/.exec(inner)?.[1].trim();
+    if (loc === undefined || !SITEMAP_PAGES.some((e) => e.loc === loc)) {
+      errors.push(
+        `unknown sitemap <loc> "${loc ?? '(none)'}" — known: ${SITEMAP_PAGES.map((e) => e.loc).join(', ')}`,
+      );
+      return block;
+    }
+    seen.add(loc);
+    const lm = /<lastmod>([^<]*)<\/lastmod>/.exec(block);
+    if (!lm || !ISO_DAY_RE.test(lm[1])) {
+      errors.push(`<lastmod> of ${loc} is missing or not a YYYY-MM-DD date`);
+      return block;
+    }
+    const date = dated.get(loc);
+    // ISO days compare as strings. Never backwards: a lastmod a hand edit dated
+    // after the count stays.
+    if (date === undefined || date <= lm[1]) return block;
+    drift.push({ loc, line: lineOf(text, offset + lm.index), actual: lm[1], expected: date });
+    return `${block.slice(0, lm.index)}<lastmod>${date}</lastmod>${block.slice(lm.index + lm[0].length)}`;
+  });
+  for (const loc of dated.keys()) {
+    if (!seen.has(loc)) errors.push(`${loc} carries a counted-at cell but has no sitemap <url> entry`);
+  }
+
+  const out = { present: true, file: abs, errors, drift, written: false };
+  if (write && errors.length === 0 && next !== text) {
+    writeFileSync(abs, next, 'utf8');
+    out.written = true;
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Markup
 // ---------------------------------------------------------------------------
@@ -1134,6 +1253,7 @@ function printHelp() {
   writeStdoutLineSync('  --check        (default) report drift, change nothing; exit 1 on drift');
   writeStdoutLineSync(`  --write        rewrite the cells in place; also refreshes ${CENSUS_FILE.join('/')}`);
   writeStdoutLineSync('                 (skipped when --site points outside the repo\'s own site/)');
+  writeStdoutLineSync(`                 and dates each counted page's <lastmod> in <site>/${SITEMAP_FILE}`);
   writeStdoutLineSync('  --json         machine-readable envelope on stdout');
   writeStdoutLineSync('  --site <dir>   site directory (default <repo-root>/site)');
   writeStdoutLineSync('  --version      print the package version');
@@ -1208,12 +1328,18 @@ export function main(argv = process.argv.slice(2), env = {}) {
   // the source producing it is corrupt, and writing the rest would be a
   // partial write reported as success.
   let rejectedTotal = 0;
+  // Every page carrying cells, for the sitemap's <lastmod> (syncSitemapLastmod).
+  const pages = [];
 
-  for (const abs of files) {
-    // Repo-relative when the file is inside the repo; absolute otherwise (a
-    // `--site` fixture in $TMPDIR would otherwise render as ../../../../var/...).
+  // Repo-relative when the file is inside the repo; absolute otherwise (a
+  // `--site` fixture in $TMPDIR would otherwise render as ../../../../var/...).
+  const display = (abs) => {
     const r = relative(root, abs);
-    const rel = r && !r.startsWith('..') ? r : abs;
+    return r && !r.startsWith('..') ? r : abs;
+  };
+
+  for (const abs of files) {
+    const rel = display(abs);
     const html = readFileSync(abs, 'utf8');
     const spans = inspectHtml(html, values);
     spanTotal += spans.length;
@@ -1250,6 +1376,16 @@ export function main(argv = process.argv.slice(2), env = {}) {
       }
     }
 
+    if (spans.length > 0) {
+      const stamp = spans.find((s) => s.metric === 'counted-at');
+      pages.push({
+        page: relative(siteDir, abs).split(sep).join('/'),
+        metrics: spans.map((s) => s.metric),
+        // As the page stands AFTER this run: a written file carries every value.
+        countedAt: stamp ? (written > 0 ? values['counted-at'] : stamp.actual.trim()) : null,
+      });
+    }
+
     report.push({
       file: rel,
       spans: spans.length,
@@ -1294,6 +1430,17 @@ export function main(argv = process.argv.slice(2), env = {}) {
   // read `llmsFull`; `censusBlocks` below carries all of them.
   const llms = censusBlocks[CENSUS_BLOCK_FILES.indexOf(LLMS_FULL_FILE)];
 
+  // The sitemap <lastmod>: a date older than the counting stamp on its page is
+  // drift, like a stale number. Written from the pages as they stand after the
+  // loop above, so page and sitemap come from the same run.
+  const sitemap = syncSitemapLastmod(siteDir, pages, { write: args.write });
+  const sitemapRel = display(sitemap.file);
+  for (const e of sitemap.errors ?? []) {
+    stderr(`Error: ${sitemapRel}: ${e}`);
+    contractTotal += 1;
+  }
+  driftTotal += sitemap.drift?.length ?? 0;
+
   // The named silent-failure class: a generator that matches nothing, changes
   // nothing, and reports success. Zero spans means the markup contract is not in
   // the page — that is a defect, in BOTH modes, never a no-op.
@@ -1390,6 +1537,13 @@ export function main(argv = process.argv.slice(2), env = {}) {
             stale: b.stale === true,
             written: b.written === true,
           })),
+          sitemap: {
+            file: sitemap.present ? sitemapRel : null,
+            present: sitemap.present,
+            errors: sitemap.errors ?? [],
+            drift: sitemap.drift ?? [],
+            written: sitemap.written === true,
+          },
           censusWritten,
           ok,
         },
@@ -1404,6 +1558,7 @@ export function main(argv = process.argv.slice(2), env = {}) {
         censusBlocks
           .map((b, i) => (b.written ? ` + ${CENSUS_BLOCK_FILES[i]}` : ''))
           .join('') +
+        (sitemap.written ? ` + ${SITEMAP_FILE}` : '') +
         (censusWritten ? ` + ${CENSUS_FILE.join('/')}` : ''),
     );
   } else {
@@ -1416,6 +1571,9 @@ export function main(argv = process.argv.slice(2), env = {}) {
       }
     }
     for (const l of censusDriftLines) stdout(l);
+    for (const d of sitemap.drift ?? []) {
+      stdout(`DRIFT ${sitemapRel}:${d.line} lastmod ${d.loc}: sitemap says "${d.actual}", page counted "${d.expected}"`);
+    }
     stdout(
       driftTotal === 0 && !noSpans && contractTotal === 0
         ? `site-numbers: ${spanTotal} metric cell(s) current across ${files.length} file(s)`

package/scripts/sweep-expired-learnings.mjs

@@ -37,6 +37,9 @@
  *   --entries PATH    JSONL sidecar holding the caller's next store generation.
  *                      PRUNE ONLY. Must exist, parse cleanly, and hold at least
  *                      one record — absent/malformed/empty all exit 1 untouched.
+ *                      A NEW record (its `id` not in the store) must pass strict
+ *                      `validateLearning()`, else exit 1 untouched (GH#69);
+ *                      records already in the store keep the tolerant path.
  *                      Omitted ⇒ a pure prune+consolidate pass over the on-disk
  *                      store.
  *   --file PATH       Learnings store (default: .orchestrator/metrics/learnings.jsonl)
@@ -61,14 +64,18 @@
  *
  * Exit codes:
  *   0  Success (including no-op when nothing is archive-eligible)
- *   1  Usage/input error (bad flag/value, flag used in the wrong mode, or an
- *      absent/malformed/empty `--entries` sidecar)
+ *   1  Usage/input error (bad flag/value, flag used in the wrong mode, an
+ *      absent/malformed/empty `--entries` sidecar, or a NEW `--entries` record
+ *      that fails strict schema validation — dry run and apply alike)
  *   2  Sweep/prune error (I/O or validation failure inside the lib)
  */
 
 import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { sweepExpiredLearnings, pruneLearnings } from './lib/learnings/expiry-sweep.mjs';
 import { readLearnings } from './lib/learnings/io.mjs';
+import { validateLearning } from './lib/learnings/schema.mjs';
 import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/learnings.jsonl';
@@ -91,11 +98,14 @@ Options:
   --json            Emit a single machine-parseable JSON summary line
   --grace-days N    Days past expiry before archiving (default: ${DEFAULT_GRACE_DAYS}); sweep only
   --entries PATH    JSONL sidecar with the next store generation; prune only.
-                    Must exist, parse cleanly, and hold >= 1 record
+                    Must exist, parse cleanly, and hold >= 1 record; a NEW
+                    record (id not in the store) must pass strict schema
+                    validation, else exit 1 with nothing written
   --file PATH       Learnings store (default: ${DEFAULT_FILE})
   --archive PATH    Archive sidecar (default: ${DEFAULT_ARCHIVE})
 
-Exit codes:  0 success  1 usage/input error  2 sweep/prune error
+Exit codes:  0 success  1 usage/input error (incl. an invalid new --entries record)
+             2 sweep/prune error
 `
   );
 }
@@ -184,7 +194,8 @@ function parseArgs(argv) {
       args.skipped = typeof raw === 'string' ? raw.split(',').filter((s) => s.length > 0) : [];
       args.telemetryExplicit = true;
     } else if (a === '--repo-root') {
-      args.repoRoot = argv[++i];
+      // Absolute on purpose: emitEvent refuses a relative root (#1468).
+      args.repoRoot = path.resolve(argv[++i]);
       args.telemetryExplicit = true;
     } else if (a === '--help' || a === '-h') {
       printHelp();
@@ -308,6 +319,45 @@ async function loadEntriesSidecar(entriesPath) {
   return read.entries;
 }
 
+/**
+ * Strict-validate every `--entries` record the store does not already hold.
+ *
+ * `pruneLearnings()` rewrites through `rewriteLearnings()`, which runs
+ * `legacyTolerant` so records ALREADY in the store (legacy shapes, EventDrop
+ * #386) survive a round-trip. Without this gate the same tolerance admitted
+ * NEW records too — a sidecar record with `scope: "src/app/x.tsx"` and no
+ * `created_at`/`expires_at` was written (GH#69). New = its `id` is absent from
+ * the store; an id-less record counts as known only when an id-less store
+ * record is deep-equal to it (the carry-through case — linear scan over the
+ * id-less subset, fine while such records stay rare; revisit if a store holds
+ * hundreds of them). Runs before any write, in dry run and apply alike.
+ *
+ * @param {object[]} entries - the parsed `--entries` generation
+ * @param {string} filePath - the learnings store
+ */
+async function rejectInvalidNewRecords(entries, filePath) {
+  let store;
+  try {
+    ({ entries: store } = await readLearnings(filePath));
+  } catch (err) {
+    process.stderr.write(`sweep-expired-learnings: prune failed: cannot read ${filePath}: ${err.message}\n`);
+    process.exit(2);
+  }
+  const idOf = (e) => (typeof e?.id === 'string' && e.id.length > 0 ? e.id : null);
+  const storeIds = new Set(store.map(idOf).filter((id) => id !== null));
+  const storeIdless = store.filter((e) => idOf(e) === null);
+  for (const entry of entries) {
+    const id = idOf(entry);
+    const known = id !== null ? storeIds.has(id) : storeIdless.some((s) => isDeepStrictEqual(s, entry));
+    if (known) continue;
+    try {
+      validateLearning(entry);
+    } catch (err) {
+      usageError(`--entries: new record ${id ?? '(no id)'} is invalid: ${err.message} — nothing written`);
+    }
+  }
+}
+
 /**
  * Decision-driven prune + consolidate + rewrite (issue #1017).
  *
@@ -315,6 +365,7 @@ async function loadEntriesSidecar(entriesPath) {
  */
 async function runPrune(args) {
   const entries = args.entries === null ? undefined : await loadEntriesSidecar(args.entries);
+  if (entries !== undefined) await rejectInvalidNewRecords(entries, args.file);
 
   let result;
   try {

package/scripts/sweep-expired-rules.mjs

@@ -29,6 +29,7 @@
  *      per-file error on the `--apply` path)
  */
 
+import path from 'node:path';
 import { emitEvent } from './lib/events.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import {
@@ -100,7 +101,7 @@ export function parseArgs(argv) {
     } else if (a === '--repo-root') {
       const raw = argv[++i];
       if (typeof raw !== 'string' || raw.length === 0) usageError('--repo-root requires a path');
-      args.repoRoot = raw;
+      args.repoRoot = path.resolve(raw);
     } else if (a === '--learnings') {
       const raw = argv[++i];
       if (typeof raw !== 'string' || raw.length === 0) usageError('--learnings requires a path');
@@ -115,15 +116,25 @@ export function parseArgs(argv) {
   return args;
 }
 
-/** Roll the plan up into the summary both output modes render. */
-function summarize(plan, args, applied) {
+/**
+ * Roll the plan up into the summary both output modes render.
+ *
+ * `header_raises` is additive (#1388 P7): a header-raise is an
+ * `action: 'rewrite'` plan carrying `reason: 'header-raise'`, so it was counted
+ * inside `rewrites` and invisible on the human stdout line although `--json`
+ * always carried `plans[].reason`. It is a SUBSET of `rewrites`, never a
+ * sibling category — the two are deliberately not disjoint.
+ */
+export function summarize(plan, args, applied) {
   const counts = { rewrite: 0, delete: 0, keep: 0 };
   for (const p of plan.plans) counts[p.action] = (counts[p.action] ?? 0) + 1;
+  const headerRaises = plan.plans.filter((p) => p.reason === 'header-raise').length;
   return {
     dry_run: args.dryRun,
     grace_days: args.graceDays,
     files_scanned: plan.plans.length,
     rewrites: counts.rewrite,
+    header_raises: headerRaises,
     deletes: counts.delete,
     keeps: counts.keep,
     expired_entries: plan.plans.reduce((n, p) => n + p.expiredPairIds.length, 0),
@@ -163,7 +174,8 @@ async function main(argv) {
   else {
     process.stdout.write(
       `sweep-expired-rules: ${args.dryRun ? 'dry-run' : 'applied'} — ` +
-        `${summary.files_scanned} generated rule file(s), ${summary.rewrites} rewrite(s), ` +
+        `${summary.files_scanned} generated rule file(s), ${summary.rewrites} rewrite(s) ` +
+        `(${summary.header_raises} header-raise(s)), ` +
         `${summary.deletes} delete(s), ${summary.expired_entries} expired entr(ies), ` +
         `${summary.unresolved_pairs} unresolved pair(s), ${summary.skipped.length} skipped, ` +
         `${summary.malformed_lines} malformed learnings line(s)\n`,

package/scripts/validate-plugin.mjs

@@ -433,6 +433,18 @@ if (runCheck('check-dead-bridge.mjs') !== 0) checkFailed = 1;
 process.stdout.write('\n');
 if (runCheck('check-entry-guard.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING (#1422), the complement of the check above: `check-entry-guard`
+// judges the FORM of a guard that already exists, so a registered hook with NO
+// guard at all passes it trivially — the #1393 regression class exactly. This
+// one asks the other half of the question over the union of the four platform
+// manifests: does every registered hook run its entry only under
+// `isMainModule(import.meta.url)` / `invokedAsScript()`, and does no profile
+// gate sit at module top level where its `process.exit(0)` kills a mere
+// importer. Blocking honestly: 27/27 registered hooks were guarded at the
+// moment it landed, because #1393 drained the backlog first.
+process.stdout.write('\n');
+if (runCheck('check-hook-entry-guards.mjs') !== 0) checkFailed = 1;
+
 // FAIL-capable, unlike the WARN-only censuses below: R2+R4 were measured at
 // 1 hit / 1 TP / 0 FP each against the full test corpus, so this check cannot be
 // red on arrival for anything but a real instance of the class. The alternatives
@@ -501,6 +513,13 @@ runStrictShAdvisory();
 // session-end tail phases from their dispatcher.
 if (runCheck('check-skill-links.mjs') !== 0) checkFailed = 1;
 
+// BLOCKING (#1446 / GH#69): instruction prose that tells an agent to write
+// `learnings.jsonl` with a shell `>` / `>>`. The store is gitignored, so a bad
+// write has no VCS restore; the sanctioned writers (`apply-session-learnings.mjs`,
+// `sweep-expired-learnings.mjs --prune`) validate, snapshot `.bak` and archive.
+process.stdout.write('\n');
+if (runCheck('check-learnings-shell-writes.mjs') !== 0) checkFailed = 1;
+
 // WARN-only: a state-mutating `git` call in tests/ that names no target resolves
 // its destination from the ambient cwd (or an inherited GIT_DIR) — the 2026-08-19
 // incident, where fixture commits, a fixture remote and a fixture identity landed

package/scripts/validate-wave-scope.mjs

@@ -69,7 +69,6 @@
  *   2 — I/O error (file not found, unreadable stdin, unreadable sidecar file)
  */
 
-import path from 'node:path';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { warn } from './lib/common.mjs';
@@ -86,6 +85,17 @@ import {
   // which roles are allowed to grant zero paths.
   isReadOnlyWaveRole,
   READ_ONLY_WAVE_ROLES,
+  // #1398 cond. 4 / #1405 / #1406 — THE grading predicate for an absolute Gate 5b
+  // grant. Lives in scope-gate.mjs so this CLI and `hooks/enforce-scope.mjs`
+  // grade one and the same way (BV-003): before the move, only this CLI could
+  // grade at all, so the hook honoured grants the CLI would have refused and a
+  // manifest that skipped the CLI was never graded.
+  gradeScopeEntry,
+  // #1398 cond. 4 — the `resolve` injection the predicate above takes. Moved
+  // into scope-gate.mjs (from a private copy here) once the hot-path cost was
+  // measured rather than assumed, so this CLI and `hooks/enforce-scope.mjs` pass
+  // the SAME resolver and can no longer reach different verdicts for one grant.
+  canonicalizeGrantPrefix,
   // Aliased: `expandTestSiblings` is ALSO the name of the pre-existing
   // boolean parameter threaded through validate()/assertSubsetOrDie for the
   // #970 flag. Aliasing the import avoids shadowing that parameter rather than
@@ -338,79 +348,6 @@ function validateSessionBinding(obj, errors, warnings) {
   }
 }
 
-/**
- * Literal filesystem-root forms — POSIX "/" and the Windows equivalents "\"
- * and a bare drive root ("C:\", "C:\\", ...). Checked independently of
- * `path.isAbsolute()` because that primitive is platform-native: on a POSIX
- * host (this repo's dev/CI hosts) it never reports `C:\` as absolute, so a
- * Windows-literal-root entry would otherwise slip past every check below.
- * @type {ReadonlySet<string>}
- */
-const FILESYSTEM_ROOT_LITERALS = new Set(['/', '\\']);
-const WINDOWS_DRIVE_ROOT_RE = /^[A-Za-z]:\\+$/;
-
-/**
- * @param {string} entry
- * @returns {boolean}
- */
-function isFilesystemRootLiteral(entry) {
-  return FILESYSTEM_ROOT_LITERALS.has(entry) || WINDOWS_DRIVE_ROOT_RE.test(entry);
-}
-
-/**
- * Well-known top-level system/home directories. A FIXED DENYLIST (not a
- * segment-count threshold): the #792 legitimate grant
- * (`/private/tmp/<session>/scratchpad/**`) is itself a single-segment-deep
- * grant under an unusual root ("private"), so any segment-count heuristic
- * tight enough to catch `/etc/**` risks catching that too, or must be tuned
- * loosely enough to leave a gap. A fixed list of the directories a
- * hallucinated/mis-copied wave-scope entry could plausibly land on is
- * predictable, auditable in a one-line diff, and does not touch legitimate
- * deep grants under any other root.
- * @type {ReadonlySet<string>}
- */
-const DENIED_ABSOLUTE_TOP_SEGMENTS = new Set([
-  'etc',
-  'Users',
-  'home',
-  'root',
-  'bin',
-  'sbin',
-  'usr',
-  'System',
-  'var',
-  'boot',
-  'dev',
-  'proc',
-  'sys',
-  'Library',
-  'Applications',
-  'Windows',
-]);
-
-/**
- * The top-level path segment of an absolute POSIX-style entry (the segment
- * immediately after the leading "/"), if it is on the denylist above.
- * @param {string} entry
- * @returns {string|null}
- */
-function deniedTopSegment(entry) {
-  const first = entry.split('/').filter(Boolean)[0];
-  return first && DENIED_ABSOLUTE_TOP_SEGMENTS.has(first) ? first : null;
-}
-
-/**
- * Does this entry contain a glob wildcard? Mirrors this codebase's own glob
- * convention (`isGlobScopeEntry` in scripts/lib/scope-gate.mjs / #796): `*`
- * is the sole wildcard metachar used in allowedPaths/fileScope entries
- * throughout this repo (no `?`/`[]`/`{}` glob syntax is supported or tested
- * anywhere else in scope-gate.mjs or enforce-scope.mjs).
- * @param {string} entry
- * @returns {boolean}
- */
-function hasWildcard(entry) {
-  return entry.includes('*');
-}
 
 /**
  * Validate allowedPaths array: must exist, be an array of non-empty strings,
@@ -463,37 +400,27 @@ function validateAllowedPaths(obj, errors, warnings) {
       errors.push('allowedPaths contains empty string');
       continue;
     }
-    // #870: an explicit absolute entry is a SANCTIONED out-of-repo grant — mirrors
-    // hooks/enforce-scope.mjs Gate 5b (matchesAbsoluteAllowlist), which honours ANY
-    // syntactically-absolute allowedPaths entry (path.isAbsolute) against the
-    // realpath-resolved write candidate. Using `path.isAbsolute` (not a hand-rolled
-    // `startsWith('/')`) keeps the same platform-native semantics Gate 5b uses.
-    // WARN, not reject — the validator must not contradict the hook it validates
-    // for (#792 / #870) — EXCEPT for the narrow catastrophic subclass below
-    // (#870-followup), which hard-rejects regardless of what Gate 5b would do
-    // with it: pre-flight validation exists precisely to catch a grant this bad
-    // before the hook is ever consulted.
-    if (path.isAbsolute(entry) || isFilesystemRootLiteral(entry)) {
-      if (isFilesystemRootLiteral(entry)) {
-        errors.push(
-          `allowedPaths grants the entire filesystem root: ${entry} — refused unconditionally, this can never be a valid wave scope`,
-        );
-      } else {
-        const denied = deniedTopSegment(entry);
-        if (denied) {
-          errors.push(
-            `allowedPaths contains a well-known system/home directory grant: ${entry} (top-level segment "${denied}" is denylisted) — refused, scope a narrower path instead`,
-          );
-        } else if (!hasWildcard(entry)) {
-          errors.push(
-            `allowedPaths contains a bare absolute file grant with no wildcard: ${entry} — a single concrete out-of-repo file has no established legitimate use in this codebase; scope a glob instead`,
-          );
-        } else {
-          warnings.push(
-            `allowedPaths contains an absolute (out-of-repo) path: ${entry} — honoured by hooks/enforce-scope.mjs Gate 5b; verify this grant is intentional`,
-          );
-        }
-      }
+    // #870 / #1398 / #1405 / #1406 — grade the entry as a Gate 5b grant through
+    // the SHARED predicate (`scripts/lib/scope-gate.mjs` gradeScopeEntry), the
+    // same one `hooks/enforce-scope.mjs` Gate 5b calls. Most absolute entries are
+    // a SANCTIONED out-of-repo grant and only WARN — the validator must not
+    // contradict the hook it validates for (#792/#870) — while the catastrophic
+    // subclasses (filesystem root, denylisted system directory in either its
+    // literal or its canonical spelling, a home grant at or above the user level
+    // or into a credential directory, a tilde that nothing expands, and a
+    // non-canonical prefix Gate 5b can never match) hard-reject here, BEFORE the
+    // hook is ever consulted. `null` = an ordinary relative entry, nothing to say.
+    //
+    // SAME PREDICATE, SAME RESOLVER (#1398 cond. 4). The resolver used to live
+    // here, which made the two callers' ARGUMENT shapes differ and let one grant
+    // reach two verdicts (`/tmp/x/**`: hook `warn`, this CLI `error`). Since the
+    // hot-path cost was measured (+0.067 ms per Gate 5b hit — see
+    // {@link canonicalizeGrantPrefix}) both callers pass this exact function, so
+    // the only remaining asymmetry is the CONSEQUENCE: exit-1 refusal here,
+    // allow-with-notice there.
+    const grade = gradeScopeEntry(entry, { resolve: canonicalizeGrantPrefix });
+    if (grade !== null) {
+      (grade.verdict === 'error' ? errors : warnings).push(`allowedPaths ${grade.message}`);
     }
     // Reject path traversal: any `../` segment. INDEPENDENT of the absolute checks
     // above — an absolute entry that ALSO contains `../` must still be rejected

package/scripts/vault-integration-watcher.mjs

@@ -35,6 +35,7 @@ import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-rep
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { resolveRepoSpec, redactUrlCredentials } from './lib/vcs-repo-spec.mjs';
 import { expandTilde } from './lib/common.mjs';
+import { shellQuote } from './lib/sh-quote.mjs';
 
 // ── Argument parsing ──────────────────────────────────────────────────────────
 
@@ -285,7 +286,7 @@ function buildTickBody(issueMap, depIds, verdict, streak, date) {
 function buildFlipBody(repos) {
   // Defense-in-depth: regex+confinement upstream already filter, but shell-quote here
   // makes the embedded bash safe under any future bypass.
-  const repoList = repos.map(r => `'${r.replace(/'/g, "'\\''")}'`).join(' ');
+  const repoList = repos.map(shellQuote).join(' ');
   // The sed/add/commit one-liner targets the project-instruction file. Most
   // ecosystem repos use CLAUDE.md, but Codex-CLI repos use AGENTS.md as a
   // transparent alias — see skills/_shared/instruction-file-resolution.md.