session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/validate/check-owner-leakage.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { readFileSync, readdirSync, statSync, existsSync, realpathSync, lstatSync, openSync, fstatSync, closeSync, constants } from 'node:fs';
+import { readFileSync, readdirSync, statSync, existsSync, realpathSync, lstatSync, openSync, fstatSync, closeSync, readSync, constants } from 'node:fs';
 import { join, extname, relative, basename, sep, resolve, dirname, isAbsolute } from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { argv } from 'node:process';
@@ -21,18 +21,75 @@ const isMain =
 
 const pluginRoot = argv[2] ? canonicalPath(resolve(argv[2])) : argv[2];
 const includeUntracked = argv.slice(3).includes('--include-untracked');
-const requireOwnerPatterns = argv.slice(3).includes('--require-owner-patterns');
+// --public-export (#1631): the root is a curated public snapshot. Adds the path check against
+// the export policy and implies --require-owner-patterns (a public tree is never scanned blind).
+const publicExport = argv.slice(3).includes('--public-export');
+const requireOwnerPatterns = argv.slice(3).includes('--require-owner-patterns') || publicExport;
 const packedIndex = argv.indexOf('--packed-files');
 const packedInventoryPath = packedIndex >= 0 ? argv[packedIndex + 1] : null;
 if (isMain && packedIndex >= 0 && (!packedInventoryPath || packedInventoryPath.startsWith('--'))) {
   console.error('packed-files requires an inventory path'); process.exit(1);
 }
 if (isMain && !pluginRoot) {
-  console.error('Usage: check-owner-leakage.mjs <plugin-root> [--include-untracked]');
+  console.error('Usage: check-owner-leakage.mjs <plugin-root> [--include-untracked] [--require-owner-patterns] [--public-export]');
   process.exit(1);
 }
 
 // Host policy stays outside source and package; this file remains standalone.
+
+// Public-export policy (#1631, #1594). Lives here, not in scripts/lib/github-export.mjs,
+// because vendored copies carry this file alone; the export CLI imports it from here.
+export const PUBLIC_EXPORT_POLICY_FILE = '.orchestrator/policy/public-export.json';
+
+/**
+ * Validate a public-export policy document.
+ * Each `exclude[].path` is an exact repo-relative file, or a directory prefix ending in
+ * `/` — no globs, no absolute paths, no `.`/`..` segments.
+ * @param {unknown} policy parsed JSON
+ * @returns {{ ok: true, excludes: string[] } | { ok: false, reason: string }}
+ */
+export function validatePublicExportPolicy(policy) {
+  if (!policy || typeof policy !== 'object' || Array.isArray(policy) || policy.version !== 1) return { ok: false, reason: 'policy must be an object with version 1' };
+  if (!Array.isArray(policy.exclude) || policy.exclude.length === 0) return { ok: false, reason: 'exclude must be a non-empty array' };
+  const excludes = [];
+  for (const entry of policy.exclude) {
+    const p = entry?.path;
+    if (typeof p !== 'string' || !p || p.startsWith('/') || /[*?[\]{}\\]/.test(p) || [...p].some((c) => c.charCodeAt(0) < 32)
+      || p.replace(/\/$/, '').split('/').some((part) => !part || part === '.' || part === '..')) {
+      return { ok: false, reason: 'invalid exclude path (exact file or dir prefix ending in "/", no globs)' };
+    }
+    excludes.push(p);
+  }
+  return { ok: true, excludes };
+}
+
+/**
+ * Read and validate `<root>/.orchestrator/policy/public-export.json`.
+ * @param {string} root
+ * @returns {{ ok: true, excludes: string[] } | { ok: false, reason: string }}
+ */
+export function loadPublicExportPolicy(root) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(join(root, PUBLIC_EXPORT_POLICY_FILE), 'utf8'));
+  } catch (err) {
+    return { ok: false, reason: err?.code === 'ENOENT' ? `${PUBLIC_EXPORT_POLICY_FILE} missing` : `${PUBLIC_EXPORT_POLICY_FILE} unreadable or not JSON` };
+  }
+  return validatePublicExportPolicy(parsed);
+}
+
+/**
+ * True when a repo-relative path falls under a public-export exclude. A directory
+ * prefix matches only at a path boundary: `docs/audits/` excludes `docs/audits/x.md`
+ * but never the sibling `docs/auditsX.md`.
+ * @param {string} relPath forward-slash repo-relative path
+ * @param {string[]} excludes
+ * @returns {boolean}
+ */
+export function isPublicExportExcluded(relPath, excludes) {
+  const norm = relPath.replace(/\\/g, '/');
+  return excludes.some((p) => (p.endsWith('/') ? norm.startsWith(p) : norm === p));
+}
 export const VAULT_CLEAR_SLUGS = new Set();
 
 // Mirrors the zero-import private-config-dir resolver because vendored copies carry this file alone.
@@ -47,12 +104,24 @@ function policySource(env = process.env) {
   const dir = own || (xdg ? join(xdg, 'session-orchestrator') : join(homedir(), '.config', 'session-orchestrator'));
   return (env.SO_OWNER_PATTERNS_FILE || '').trim() || join(dir, 'owner-patterns.json');
 }
+// #1629: a refused DIRECTORY is a host-setup fault (umask 000 leaves the dir 0777), not a
+// leak — it carries the dir so the one-time warning can name it instead of a bare CP1.
+function unsafeDir(dir, st) {
+  return Object.assign(new Error('unsafe-dir'), { dir, why: st.isSymbolicLink() ? 'a symlink' : !st.isDirectory() ? 'not a directory' : `mode ${(st.mode & 0o777).toString(8)}, writable by group/others` });
+}
 function checkedHostFile(filename) {
   if (!isAbsolute(filename)) throw new Error('unsafe');
+  // Windows has no POSIX mode bits: Node reports 0o666 (0o444 read-only) for every
+  // file and directory, so the group/other-write and 0600 checks below would refuse
+  // EVERY policy file there (measured on Windows 11, #1612). They apply on POSIX only;
+  // the symlink, hard-link, repo-ancestor and size checks still apply everywhere.
+  // Ceiling (BV-004): Windows ACLs are not inspected — revisit if the policy file
+  // ever carries secrets rather than private names.
+  const posixModes = process.platform !== 'win32';
   // Canonical OS aliases (/tmp on macOS) are allowed above the private source parent.
   let cursor = dirname(filename);
   const parent = lstatSync(cursor);
-  if (!parent.isDirectory() || parent.isSymbolicLink() || (parent.mode & 0o022)) throw new Error('unsafe');
+  if (!parent.isDirectory() || parent.isSymbolicLink() || (posixModes && (parent.mode & 0o022))) throw unsafeDir(cursor, parent);
   const canonicalParent = realpathSync(cursor);
   // Reject repo-local data even if ignored; walk every ancestor for a .git marker.
   cursor = canonicalParent;
@@ -64,27 +133,50 @@ function checkedHostFile(filename) {
   cursor = dirname(filename);
   while (cursor !== dirname(cursor)) {
     const st = lstatSync(cursor);
-    if ((st.isSymbolicLink() && st.uid !== 0) || (st.uid !== 0 && (st.mode & 0o022))) throw new Error('unsafe');
+    if ((st.isSymbolicLink() && st.uid !== 0) || (posixModes && st.uid !== 0 && (st.mode & 0o022))) throw unsafeDir(cursor, st);
     cursor = dirname(cursor);
   }
   const st = lstatSync(filename);
-  if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o7777) !== 0o600 || st.nlink !== 1 || (typeof process.getuid === 'function' && st.uid !== process.getuid())) throw new Error('unsafe');
+  if (!st.isFile() || st.isSymbolicLink() || (posixModes && (st.mode & 0o7777) !== 0o600) || st.nlink !== 1 || (typeof process.getuid === 'function' && st.uid !== process.getuid())) throw new Error('unsafe');
   if (st.size > POLICY_LIMIT_BYTES) throw new Error('invalid');
   const fd = openSync(filename, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
   try {
     const opened = fstatSync(fd);
-    if (!opened.isFile() || opened.ino !== st.ino || opened.dev !== st.dev || (opened.mode & 0o7777) !== 0o600 || opened.size > POLICY_LIMIT_BYTES) throw new Error('unsafe');
+    if (!opened.isFile() || opened.ino !== st.ino || opened.dev !== st.dev || (posixModes && (opened.mode & 0o7777) !== 0o600) || opened.size > POLICY_LIMIT_BYTES) throw new Error('unsafe');
     const raw = readFileSync(fd, 'utf8');
     if (Buffer.byteLength(raw) > POLICY_LIMIT_BYTES) throw new Error('invalid');
     return raw;
   } finally { closeSync(fd); }
 }
+// Redacted label for a refused directory: env-var name or `~`-relative, never the raw path
+// (a custom SO_CONFIG_HOME may carry private names). Ancestors render as `<label>/..`.
+function configDirLabel(dir, filename, env) {
+  const patterns = (env.SO_OWNER_PATTERNS_FILE || '').trim(), own = (env.SO_CONFIG_HOME || '').trim(), xdg = (env.XDG_CONFIG_HOME || '').trim();
+  const [base, label] = patterns ? [dirname(filename), 'dirname($SO_OWNER_PATTERNS_FILE)'] : own ? [own, '$SO_CONFIG_HOME'] : xdg ? [join(xdg, 'session-orchestrator'), '$XDG_CONFIG_HOME/session-orchestrator'] : [homedir(), '~'];
+  const rel = relative(base, dir);
+  if (!rel) return label;
+  return rel.split(sep).every((part) => part === '..') || label === '~' && !rel.startsWith('..') ? `${label}/${rel.split(sep).join('/')}` : 'an ancestor directory of the owner policy';
+}
+const warnedUnsafeDirs = new Set();
+function warnUnsafeConfigDir(err, filename, env) {
+  if (warnedUnsafeDirs.has(err.dir)) return;
+  warnedUnsafeDirs.add(err.dir);
+  const label = configDirLabel(err.dir, filename, env);
+  // chmod cannot repair a symlink or a non-directory — name the fix that works.
+  const fix = err.why === 'a symlink' ? `replace the symlink ${label} with a real directory (mode 700)`
+    : err.why === 'not a directory' ? `replace ${label} with a real directory (mode 700)`
+    : err.dir === dirname(filename) ? `chmod 700 ${label}` : `chmod go-w ${label}`;
+  console.error(`WARN owner-patterns: unsafe config directory ${label} (${err.why}); owner policy not loaded, so every segment fails closed as CP1 — not a leak. Fix: ${fix}`);
+}
 export function inspectOwnerPatterns({ filePath, env = process.env, refresh = false } = {}) {
   const filename = filePath ?? policySource(env);
   if (!refresh && ownerCache?.filename === filename) return ownerCache.result;
   let result;
   try {
-    const policy = JSON.parse(checkedHostFile(filename));
+    // #1613: Windows PowerShell 5.1 (`Set-Content -Encoding utf8`) writes a UTF-8 BOM,
+    // which JSON.parse rejects — strip it so such a policy is not read as invalid.
+    const raw = checkedHostFile(filename);
+    const policy = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
     if (!policy || Array.isArray(policy) || policy.version !== 1 || Object.keys(policy).some((key) => key !== 'version' && !POLICY_KEYS.includes(key))) throw new Error('invalid');
     for (const key of POLICY_KEYS) {
       if (!Object.hasOwn(policy, key)) policy[key] = [];
@@ -94,7 +186,13 @@ export function inspectOwnerPatterns({ filePath, env = process.env, refresh = fa
     if (!POLICY_KEYS.slice(0, 6).concat('personalNames').some((key) => policy[key].length)) throw new Error('invalid');
     result = { status: 'ok', policy };
   } catch (err) {
-    result = { status: err.code === 'ENOENT' ? 'missing' : err.message === 'unsafe' || err.code === 'ELOOP' ? 'unsafe' : 'invalid', reason: err.code ?? (err.message === 'unsafe' ? 'unsafe-source' : 'invalid-source') };
+    if (err.message === 'unsafe-dir') {
+      // Fail-closed unchanged: an unsafe directory never supplies (or waives) a policy.
+      result = { status: 'unsafe', reason: 'unsafe-config-dir' };
+      warnUnsafeConfigDir(err, filename, env);
+    } else {
+      result = { status: err.code === 'ENOENT' ? 'missing' : err.message === 'unsafe' || err.code === 'ELOOP' ? 'unsafe' : 'invalid', reason: err.code ?? (err.message === 'unsafe' ? 'unsafe-source' : 'invalid-source') };
+    }
   }
   ownerCache = {filename, result};
   VAULT_CLEAR_SLUGS.clear();
@@ -394,9 +492,14 @@ export async function getConfidentialNamePatterns({ loadHostPaths } = {}) {
 const TEXT_EXTS = new Set([
   '.md',
   '.mdx',
+  '.mdc',
   '.mjs',
+  '.cjs',
   '.js',
   '.ts',
+  '.tsx',
+  '.py',
+  '.toml',
   '.json',
   '.jsonl',
   '.yml',
@@ -411,11 +514,41 @@ const TEXT_EXTS = new Set([
 
 const DOTFILE_ALLOWLIST = new Set(['.env.example', '.nvmrc', '.vault.yaml']);
 
+const BINARY_SNIFF_BYTES = 8192;
+
+/**
+ * Cheap binary sniff for extensionless files (LICENSE, Dockerfile, .husky hooks,
+ * fixture launchers): a NUL byte in the first 8 KB means binary, the same
+ * heuristic git uses. An unreadable file counts as text so the scan loop
+ * reports it as "file unreadable" instead of skipping it silently.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function looksLikeText(filePath) {
+  let fd;
+  try {
+    fd = openSync(filePath, 'r');
+    const buf = Buffer.alloc(BINARY_SNIFF_BYTES);
+    const n = readSync(fd, buf, 0, BINARY_SNIFF_BYTES, 0);
+    return !buf.subarray(0, n).includes(0);
+  } catch {
+    return true;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+// Formats that are binary by definition: never scanned, whatever their first bytes look like.
+const BINARY_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.avif', '.ico', '.icns', '.pdf', '.woff', '.woff2', '.ttf', '.otf', '.eot', '.zip', '.gz', '.tgz', '.bz2', '.xz', '.7z', '.mp3', '.mp4', '.mov', '.webm', '.wav', '.ogg', '.wasm']);
+
 function isTextFile(filePath) {
   const base = basename(filePath);
   if (DOTFILE_ALLOWLIST.has(base)) return true;
   const ext = extname(filePath);
-  return ext ? TEXT_EXTS.has(ext) : false;
+  // A listed extension is text; any other file (no extension, or an unknown one such as .tmpl,
+  // .template, .lock) is scanned unless it looks binary, so a new text format is never skipped.
+  if (TEXT_EXTS.has(ext)) return true;
+  return !BINARY_EXTS.has(ext.toLowerCase()) && looksLikeText(filePath);
 }
 
 function getTrackedFiles() {
@@ -534,7 +667,9 @@ const SELF_EXCLUSIONS = new Set([
 const scanFiles = textFiles.filter((f) => {
   const rel = relative(pluginRoot, f).replace(/\\/g, '/');
   if (!packedInventoryPath && rel.startsWith('.orchestrator/audits/')) return false;
-  if (!packedInventoryPath && SELF_EXCLUSIONS.has(rel)) return false;
+  // --public-export scans everything that ships: these self-exclusions exist for the
+  // private repo's own CI, and a public snapshot must not carry their literals unscanned.
+  if (!packedInventoryPath && !publicExport && SELF_EXCLUSIONS.has(rel)) return false;
   return true;
 });
 
@@ -548,6 +683,19 @@ if (cp11.disabledReason) {
   fail(`<scan-wide> — CP11 (guard disabled): ${cp11.disabledReason}`);
 }
 
+// --public-export: path-based, because a content pattern cannot recognise e.g. a
+// preference card or an audit report. Runs over ALL tracked files, not only text files.
+if (publicExport) {
+  const exportPolicy = loadPublicExportPolicy(pluginRoot);
+  if (!exportPolicy.ok) {
+    fail(`<scan-wide> — PX (public-export policy unavailable): ${exportPolicy.reason}`);
+  } else {
+    const leakedPaths = allFiles.map((f) => relative(pluginRoot, f).replace(/\\/g, '/')).filter((rel) => isPublicExportExcluded(rel, exportPolicy.excludes));
+    for (const rel of leakedPaths) fail(`${safeDiagnosticPath(rel, cp11Patterns)} — PX (path excluded from public export)`);
+    if (leakedPaths.length === 0) pass(`no public-export excluded path among ${allFiles.length} files`);
+  }
+}
+
 const violations = [];
 
 for (const filePath of scanFiles) {

package/scripts/lib/validate/check-test-posix-shell.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * check-test-posix-shell.mjs — tests must not spawn a POSIX shell by bare name.
+ *
+ * WHY. On native Windows `sh` is not on PATH and `bash` resolves to
+ * C:\Windows\System32\bash.exe, which is WSL and cannot see Windows paths
+ * (measured 2026-10-22 on the Windows 11 test PC, `where sh & where bash`,
+ * SO#1613). A test that runs `spawnSync('sh', …)` or `execFileSync('/bin/bash', …)`
+ * is therefore red on Windows for a reason that has nothing to do with the code
+ * under test. The native run at fd8d3673 counted 301 red tests in exactly this
+ * class; the same session moved ~25 test files to `posixShell()` from
+ * `tests/_helpers/posix-shell.mjs`, which returns the name unchanged off Windows
+ * and Git Bash's sh.exe/bash.exe on win32. This check keeps the class from
+ * coming back.
+ *
+ * RULE. In tracked `tests/**\/*.mjs`, a finding is:
+ *  - a call to `spawn` / `spawnSync` / `execFile` / `execFileSync` (bare or as a
+ *    member, e.g. `cp.spawnSync`) whose FIRST argument is the string literal
+ *    `sh`, `bash`, `/bin/sh` or `/bin/bash` in any quote style;
+ *  - a call to `exec` / `execSync` whose command string literal starts with
+ *    `sh `, `bash `, `/bin/sh ` or `/bin/bash `.
+ * A call through `posixShell(...)` is never a finding (its first argument is not
+ * a literal). `tests/_helpers/posix-shell.mjs` itself is exempt.
+ *
+ * METHOD. Textual, over the shared lexer `scripts/lib/js-mask.mjs`: the call
+ * name and its opening quote are matched on the fully masked source (comments
+ * and literal interiors blanked), so a commented-out spawn and fixture source
+ * embedded in a template literal are not scanned as code; the literal VALUE is
+ * then read at the same offset from the comments-only mask (offsets are
+ * preserved by both modes).
+ * Named ceiling (BV-004): a shell name passed through a variable
+ * (`const SH = 'sh'; spawnSync(SH, …)`) is not seen. REVISIT if a native
+ * Windows run shows that shape red.
+ *
+ * BASELINE. Three files are changed by open merge requests (!239/!237, !240) at the
+ * time this check landed, so the #1613 session left them untouched; each is
+ * baselined below (WARN, not FAIL) and gets converted after those MRs land. An
+ * entry whose file no longer has a finding FAILs as `baseline-stale` so a
+ * converted file does not leave a permanent exemption behind; an entry with an
+ * empty reason FAILs as `baseline-missing-reason` (same discipline as
+ * `check-hooks-emit-event-guard.mjs`). Every other site FAILs.
+ *
+ * Usage: check-test-posix-shell.mjs <repo-root>
+ * Output: `  PASS: …` / `  WARN: …` / `  FAIL: …` lines, then
+ * `Results: N passed, M failed`. Exit 0 = clean (baselined WARNs allowed),
+ * 1 = at least one new finding or baseline defect, 2 = tool error.
+ *
+ * Import-safety: importing this module executes nothing — the isMain guard at
+ * the bottom is the only side-effecting path.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { maskSource } from '../js-mask.mjs';
+import { listRepoFiles } from './repo-files.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+
+const SCAN_DIR = 'tests';
+
+/** The helper that resolves the shell; it may name the shells itself. */
+const EXEMPT_FILES = new Set(['tests/_helpers/posix-shell.mjs']);
+
+/**
+ * Baseline — Map<repo-relative file, reason>. Keyed per file, not per line:
+ * the open MRs reshape these files, and a line key would silently stop matching.
+ */
+const BASELINE_FILES = new Map([
+  [
+    'tests/skills/tmux-layout.test.mjs',
+    '#1613: file is changed by an open MR (!240); convert to posixShell() after it lands',
+  ],
+  [
+    'tests/so-hud/rules.test.mjs',
+    '#1613: file is changed by an open MR (!239/!237); convert to posixShell() after it lands',
+  ],
+  [
+    'tests/scripts/sweep-expired-learnings-cli.test.mjs',
+    '#1613: file is changed by an open MR (!239/!237); convert to posixShell() after it lands',
+  ],
+]);
+
+const SHELL_NAMES = new Set(['sh', 'bash', '/bin/sh', '/bin/bash']);
+const SHELL_COMMAND_PREFIX_RE = /^(?:\/bin\/)?(?:sh|bash) /;
+
+/** Call name plus open paren plus a quote, on the masked source. */
+const CALL_RE = /\b(spawn|spawnSync|execFile|execFileSync|exec|execSync)\s*\(\s*(['"`])/g;
+
+/**
+ * Read the string literal that opens at `start` (a quote char) in `text`.
+ *
+ * @param {string} text comments-only masked source
+ * @param {number} start offset of the opening quote
+ * @returns {string | null} the literal's value, or null when it is not a
+ *   single-line literal without `${` interpolation
+ */
+function literalAt(text, start) {
+  const quote = text[start];
+  const end = text.indexOf(quote, start + 1);
+  if (end === -1) return null;
+  const value = text.slice(start + 1, end);
+  if (value.includes('\n') || value.includes('${')) return null;
+  return value;
+}
+
+/**
+ * Find bare-shell spawn call sites in one source text.
+ *
+ * @param {string} source
+ * @returns {{line: number, call: string, shell: string}[]}
+ */
+export function findBareShellCalls(source) {
+  const masked = maskSource(source);
+  const literals = maskSource(source, { keepLiterals: true });
+  /** @type {{line: number, call: string, shell: string}[]} */
+  const calls = [];
+  for (const m of masked.matchAll(CALL_RE)) {
+    const call = m[1];
+    const quoteAt = m.index + m[0].length - 1;
+    const value = literalAt(literals, quoteAt);
+    if (value === null) continue;
+    const isExecFamily = call === 'exec' || call === 'execSync';
+    const hit = isExecFamily ? SHELL_COMMAND_PREFIX_RE.test(value) : SHELL_NAMES.has(value);
+    if (!hit) continue;
+    const line = source.slice(0, m.index).split('\n').length;
+    calls.push({ line, call, shell: isExecFamily ? value.split(' ')[0] : value });
+  }
+  return calls;
+}
+
+/**
+ * @typedef {{kind: 'bare-shell', file: string, line: number, call: string, shell: string, baselined: boolean}} ShellFinding
+ * @typedef {{kind: 'baseline-stale' | 'baseline-missing-reason', file: string, message: string}} BaselineFinding
+ */
+
+/**
+ * Scan tracked `tests/**\/*.mjs` under `repoRoot`.
+ *
+ * @param {string} repoRoot
+ * @param {{baseline?: Map<string, string>}} [options] `baseline` defaults to the
+ *   shipped {@link BASELINE_FILES}; injectable so tests exercise the baseline
+ *   paths against a tmp fixture.
+ * @returns {{findings: (ShellFinding | BaselineFinding)[], readErrors: {file: string, message: string}[]}}
+ */
+export function scanTestPosixShell(repoRoot, { baseline = BASELINE_FILES } = {}) {
+  const files = listRepoFiles(repoRoot, { dirs: [SCAN_DIR], exts: ['mjs'] });
+  /** @type {(ShellFinding | BaselineFinding)[]} */
+  const findings = [];
+  /** @type {{file: string, message: string}[]} */
+  const readErrors = [];
+  /** @type {Set<string>} */
+  const matchedBaseline = new Set();
+
+  for (const absFile of files) {
+    const rel = path.relative(repoRoot, absFile).split(path.sep).join('/');
+    if (EXEMPT_FILES.has(rel)) continue;
+    let source;
+    try {
+      source = readFileSync(absFile, 'utf8');
+    } catch (err) {
+      readErrors.push({ file: rel, message: `unreadable: ${err?.message ?? String(err)}` });
+      continue;
+    }
+    if (!/\b(?:spawn|exec)/.test(source)) continue; // cheap textual pre-filter
+
+    const calls = findBareShellCalls(source);
+    if (calls.length === 0) continue;
+    const baselined = baseline.has(rel);
+    if (baselined) {
+      matchedBaseline.add(rel);
+      if (String(baseline.get(rel) ?? '').trim() === '') {
+        findings.push({
+          kind: 'baseline-missing-reason',
+          file: rel,
+          message: 'baseline entry has no reason — name the linked issue or remove the entry',
+        });
+      }
+    }
+    for (const c of calls) findings.push({ kind: 'bare-shell', file: rel, ...c, baselined });
+  }
+
+  for (const file of baseline.keys()) {
+    if (matchedBaseline.has(file)) continue;
+    findings.push({
+      kind: 'baseline-stale',
+      file,
+      message: 'baseline entry no longer has a bare shell spawn (converted or removed) — remove the entry',
+    });
+  }
+
+  return { findings, readErrors };
+}
+
+/**
+ * Run the check and print the validate-plugin line vocabulary.
+ *
+ * @param {string} repoRoot
+ * @param {{baseline?: Map<string, string>}} [options] forwarded to {@link scanTestPosixShell}
+ * @returns {number} 0 = clean, 1 = new finding(s), 2 = tool error
+ */
+export function runCheckTestPosixShell(repoRoot, options) {
+  console.log('--- Check: tests spawn a POSIX shell via posixShell(), not by bare name (#1613) ---');
+
+  const { findings, readErrors } = scanTestPosixShell(repoRoot, options);
+  if (readErrors.length > 0) {
+    for (const e of readErrors) console.log(`  FAIL: ${e.file} — ${e.message}`);
+    console.log('');
+    console.log(`Results: 0 passed, ${readErrors.length} failed`);
+    return 2;
+  }
+
+  const shellFindings = /** @type {ShellFinding[]} */ (findings.filter((f) => f.kind === 'bare-shell'));
+  const baselineIssues = /** @type {BaselineFinding[]} */ (findings.filter((f) => f.kind !== 'bare-shell'));
+  const fresh = shellFindings.filter((f) => !f.baselined);
+  const old = shellFindings.filter((f) => f.baselined);
+
+  if (fresh.length === 0 && baselineIssues.length === 0) {
+    console.log(
+      old.length === 0
+        ? '  PASS: no test spawns sh/bash by bare name'
+        : `  PASS: no NEW bare sh/bash spawn in tests/ (${old.length} pre-existing, baselined — see #1613)`,
+    );
+  }
+  for (const f of old) {
+    console.log(`  WARN: ${f.file}:${f.line} — ${f.call}('${f.shell}' …) by bare name (baselined #1613, file is in an open MR)`);
+  }
+  for (const f of fresh) {
+    console.log(
+      `  FAIL: ${f.file}:${f.line} — ${f.call}('${f.shell}' …) by bare name; on native Windows sh is not on PATH and bash is WSL — use posixShell() from tests/_helpers/posix-shell.mjs`,
+    );
+  }
+  for (const f of baselineIssues) console.log(`  FAIL: ${f.file} — ${f.message} (${f.kind})`);
+
+  const failCount = fresh.length + baselineIssues.length;
+  console.log('');
+  console.log(`Results: ${failCount === 0 ? 1 : 0} passed, ${failCount} failed`);
+  return failCount > 0 ? 1 : 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  const root = process.argv[2];
+  if (!root) {
+    console.error('Usage: check-test-posix-shell.mjs <repo-root>');
+    process.exit(2);
+  }
+  process.exit(runCheckTestPosixShell(path.resolve(root)));
+}

package/scripts/lib/validate/check-unwired-features.mjs

@@ -292,6 +292,8 @@ import path from 'node:path';
 
 import { sizingSubject } from '../learnings/sizing-subject.mjs';
 import { isMainModule } from '../is-main-module.mjs';
+import { resolveLedgerPath } from '../ledger-path.mjs';
+import { resolveEventsLedgerRoot } from '../platform.mjs';
 
 /** Documented config surface — every `yaml` fence in this file is a declaration. */
 const TEMPLATE_REL = 'docs/session-config-template.md';
@@ -1248,7 +1250,7 @@ export function collectHandKeyedLearningSubjects(pluginRoot) {
   let judged = 0;
   let unattributed = 0;
 
-  const learnings = readJsonl(path.join(pluginRoot, LEARNINGS_REL));
+  const learnings = readJsonl(resolveLedgerPath(LEARNINGS_REL, pluginRoot));
   if (learnings.length === 0) return { findings, scanned: { judged, unattributed } };
 
   // A session record can be addressed by either identity form (see
@@ -1257,7 +1259,7 @@ export function collectHandKeyedLearningSubjects(pluginRoot) {
   // a resolvable record is never mis-counted as unattributed.
   /** @type {Map<string, Record<string, unknown>>} */
   const sessionsById = new Map();
-  for (const record of readJsonl(path.join(pluginRoot, SESSIONS_REL))) {
+  for (const record of readJsonl(path.join(resolveEventsLedgerRoot(pluginRoot), SESSIONS_REL))) {
     for (const field of ['session_id', 'semantic_session_id']) {
       const id = record[field];
       if (typeof id === 'string' && id !== '' && !sessionsById.has(id)) sessionsById.set(id, record);

package/scripts/lib/validate/check-vcs-repo-flag-positional.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Separate WARN-only check for gh pr commands rejected with --repo/-R (#1024).
+ * Shares corpus discovery and call-shape parsing with the bare-repo census,
+ * but its findings advise naming the PR or dropping the flag, never adding it.
+ * Coverage ceilings (literal argv, shell fences/strings) are shared with that census.
+ */
+import path from 'node:path';
+import { inspectVcsRepoFlag } from './check-vcs-repo-flag.mjs';
+import { isMainModule } from '../is-main-module.mjs';
+
+/** @param {string} pluginRoot independent check envelope */
+export function inspectVcsRepoFlagPositional(pluginRoot) {
+  const result = inspectVcsRepoFlag(pluginRoot, { rejected: true });
+  return {
+    ok: result.ok,
+    toolError: result.toolError,
+    summary: {
+      filesScanned: result.summary.filesScanned,
+      unresolvedArgv: result.summary.unresolvedArgv,
+      findings: result.findings.length,
+      byKind: result.summary.byKind,
+    },
+    findings: result.findings,
+  };
+}
+
+if (isMainModule(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const usage =
+    'Usage: check-vcs-repo-flag-positional.mjs [<plugin-root>] [--json]\n' +
+    'Exit: 0 check completed (findings WARN-only) · 1 usage error · 2 tool error';
+  const unknown = args.filter((arg) => arg.startsWith('-') && !['--json', '--help'].includes(arg));
+  const roots = args.filter((arg) => !arg.startsWith('-'));
+  if (unknown.length || roots.length > 1) {
+    console.error(usage);
+    process.exitCode = 1;
+  } else if (args.includes('--help')) {
+    console.log(usage);
+  } else {
+    const result = inspectVcsRepoFlagPositional(path.resolve(roots[0] ?? process.cwd()));
+    if (args.includes('--json')) console.log(JSON.stringify(result, null, 2));
+    else {
+      console.log('--- Check: --repo/-R requiring a PR positional (WARN-only) ---');
+      for (const finding of result.findings) {
+        console.log(
+          `  ${result.toolError ? 'FAIL' : 'WARN'}: [${finding.kind}] ${finding.file}:${finding.line} — ${finding.message}`,
+        );
+      }
+      if (!result.toolError)
+        console.log(
+          `  PASS: scanned ${result.summary.filesScanned} file(s), ${result.findings.length} rejected repo flag(s), ${result.summary.unresolvedArgv} variable argv array(s) unjudged`,
+        );
+      console.log(`Results: ${result.toolError ? '0 passed, 1 failed' : '1 passed, 0 failed'}`);
+    }
+    process.exitCode = result.toolError ? 2 : 0;
+  }
+}