session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/rule-loader.mjs

@@ -220,6 +220,28 @@ const SCALAR_META_KEYS = new Set([
  * @param {string} contents - raw file contents
  * @returns {{ globs: string[] | null, meta: Record<string, unknown> }}
  */
+/**
+ * Undo the ONE quoting style the renderer emits for a scalar (#1041 follow-up).
+ *
+ * `scripts/lib/reconcile/renderer.mjs` serialises `description:` through
+ * js-yaml, which picks SINGLE-quote style whenever the plain form would be
+ * ambiguous (a `: ` inside) and escapes an interior `'` as `''`. A bare
+ * leading/trailing-quote strip then returns `it''s` for `it's` — measured
+ * 2026-08-23 on 40 of 146 live learning insights carrying both characters.
+ * Single-quoted: strip + un-double. Double-quoted: strip + unescape `\"` and
+ * `\\`. Unquoted: returned verbatim (the pre-#1041 behaviour, unchanged).
+ */
+function unquoteYamlScalar(valuePart) {
+  const v = valuePart.trim();
+  if (v.length >= 2 && v.startsWith("'") && v.endsWith("'")) {
+    return v.slice(1, -1).replace(/''/g, "'");
+  }
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    return v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  }
+  return v.replace(/^["']|["']$/g, '');
+}
+
 export function parseGlobsFrontmatter(contents) {
   const match = FRONTMATTER_RE.exec(stripLeadingProvenanceHeader(contents));
   if (!match) return { globs: null, meta: {} };
@@ -299,7 +321,7 @@ export function parseGlobsFrontmatter(contents) {
     } else if (SCALAR_META_KEYS.has(key)) {
       // Scalar activation key (issue #694). Strip surrounding quotes, then
       // apply per-key coercion. Empty values are skipped (key not present).
-      const stripped = valuePart.replace(/^["']|["']$/g, '');
+      const stripped = unquoteYamlScalar(valuePart);
       if (stripped === '') continue;
       if (key === 'alwaysApply' || key === 'auto-generated') {
         if (stripped === 'true') meta[key] = true;
@@ -468,7 +490,20 @@ export function loadApplicableRules({
   try {
     entries = readdirSync(rulesDir);
   } catch (err) {
-    process.stderr.write(`[rule-loader] Cannot read rulesDir ${rulesDir}: ${err.message}\n`);
+    // Category separation, not channel muting (`.claude/rules/development.md`
+    // § Guard & Threshold Design). An absent `.claude/rules/` (ENOENT), or a
+    // plain file sitting where that directory would be (ENOTDIR), is the
+    // NORMAL state of every repo that has not adopted the rules layer — a
+    // legitimate empty corpus, not a diagnosable fault. Diagnosing it made
+    // every stderr guard around the callers unusable: `instruction-budget-
+    // guard.mjs` calls this function three times unconditionally, so ONE probe
+    // run emitted the same non-finding three times (#1132).
+    // EACCES/EPERM — and anything else — stay genuinely diagnosable and keep
+    // the line. Both branches still `return []`, so no caller's control flow
+    // changes; only the side effect is gated.
+    if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') {
+      process.stderr.write(`[rule-loader] Cannot read rulesDir ${rulesDir}: ${err.message}\n`);
+    }
     return [];
   }
 

package/scripts/lib/rules-sync.mjs

@@ -9,7 +9,13 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, basename, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { validateRuleContent } from './validate-vendored-rules.mjs';
+import { validateRuleContent, scanVendoringLeaks } from './validate-vendored-rules.mjs';
+
+// The vendoring sanitizer (issue #1098) lives in validate-vendored-rules.mjs —
+// it has that module's shape ("judge one rule file → findings") and its
+// standalone CLI needs it too. Re-exported here so importers that predate the
+// move (and this file's own tests) keep resolving it from rules-sync.mjs.
+export { scanVendoringLeaks };
 
 // Exported (issue #722 Epic A Wave 2) for external consumers (e.g. tests).
 // NOT imported by validate-vendored-rules.mjs — that module imports
@@ -188,6 +194,19 @@ function escapeRegex(s) {
  * at least one concrete bullet entry. This keeps `/bootstrap --sync-rules`
  * ready for future opt-in categories without requiring CLI changes.
  *
+ * Vendoring sanitizer (issue #1098): every source file that reaches the write
+ * decision is additionally scanned by `scanVendoringLeaks()`, and its findings
+ * are collected into the additive `sanitizer[]` array. This runs in
+ * **report-only mode, always** — it never rewrites content, never skips a
+ * write, and never contributes to `errors[]`. That default is deliberate and
+ * matches the existing CLI contract: `rules-sync.mjs`'s exit code is driven by
+ * `errors[]` alone, so adding `sanitizer[]` extends the JSON envelope without
+ * changing any exit code or write decision an existing caller depends on.
+ * Silent stripping was rejected outright — it would change a rule's meaning at
+ * vendoring time, invisibly to author and consumer alike. There is no opt-out
+ * flag because the scan is read-only and free relative to the file read it
+ * piggybacks on.
+ *
  * @param {{
  *   pluginRoot: string,
  *   repoRoot: string,
@@ -202,7 +221,8 @@ function escapeRegex(s) {
  *   skipped: Array<string|{file: string, reason: string}>,
  *   preserved: string[],
  *   errors: Array<{file: string, reason: string}>,
- *   warnings: Array<{file: string, reason: string}>
+ *   warnings: Array<{file: string, reason: string}>,
+ *   sanitizer: Array<{file: string, line: number, kind: string, text: string}>
  * }}
  */
 export function syncRules({
@@ -219,20 +239,21 @@ export function syncRules({
   const preserved = [];
   const errors = [];
   const warnings = [];
+  const sanitizer = [];
 
   if (!pluginRoot || typeof pluginRoot !== 'string') {
     errors.push({ file: '_index.md', reason: 'pluginRoot not provided' });
-    return { written, skipped, preserved, errors, warnings };
+    return { written, skipped, preserved, errors, warnings, sanitizer };
   }
   if (!repoRoot || typeof repoRoot !== 'string') {
     errors.push({ file: '_index.md', reason: 'repoRoot not provided' });
-    return { written, skipped, preserved, errors, warnings };
+    return { written, skipped, preserved, errors, warnings, sanitizer };
   }
 
   const indexPath = join(pluginRoot, 'rules', '_index.md');
   if (!existsSync(indexPath)) {
     errors.push({ file: '_index.md', reason: `_index.md not found at ${indexPath}` });
-    return { written, skipped, preserved, errors, warnings };
+    return { written, skipped, preserved, errors, warnings, sanitizer };
   }
 
   let indexContent;
@@ -240,7 +261,7 @@ export function syncRules({
     indexContent = readFileSync(indexPath, 'utf8');
   } catch (err) {
     errors.push({ file: '_index.md', reason: `failed to read _index.md: ${err.message}` });
-    return { written, skipped, preserved, errors, warnings };
+    return { written, skipped, preserved, errors, warnings, sanitizer };
   }
 
   const selectedCategories = Array.isArray(categories)
@@ -248,6 +269,14 @@ export function syncRules({
     : listManifestCategories(indexContent);
   const entries = parseIndex(indexContent, selectedCategories);
 
+  // Resolvability for the See-Also sanitizer is judged against the FULL
+  // manifest, not `selectedCategories`: an archetype-scoped rule is a
+  // legitimate citation target in every repo whose archetype matches, so
+  // narrowing this to the current selection would report false leaks.
+  const manifestBasenames = new Set(
+    parseIndex(indexContent, listManifestCategories(indexContent)).map((e) => basename(e.relPath)),
+  );
+
   if (entries.length === 0) {
     // No sources resolved — could be empty categories or malformed index
     for (const cat of selectedCategories.length > 0 ? selectedCategories : ['<none>']) {
@@ -256,7 +285,7 @@ export function syncRules({
         reason: `no sources resolved for category '${cat}' in _index.md`,
       });
     }
-    return { written, skipped, preserved, errors, warnings };
+    return { written, skipped, preserved, errors, warnings, sanitizer };
   }
 
   const targetDir = join(repoRoot, '.claude', 'rules');
@@ -304,6 +333,13 @@ export function syncRules({
       continue;
     }
 
+    // Vendoring sanitizer (issue #1098) — report-only, never mutates
+    // srcContent. Deliberately placed BEFORE the validation gate so a file
+    // that fails validation still reports its leaks in one pass.
+    sanitizer.push(
+      ...scanVendoringLeaks({ content: srcContent, relPath, pluginRoot, manifestBasenames }),
+    );
+
     // Pre-write validation gate (issue #722 Epic A Wave 2). Runs BEFORE the
     // existsSync(targetPath) write-decision branch below, so a validation
     // failure skips the write regardless of whether the target already
@@ -376,7 +412,7 @@ export function syncRules({
     }
   }
 
-  return { written, skipped, preserved, errors, warnings };
+  return { written, skipped, preserved, errors, warnings, sanitizer };
 }
 
 // ── CLI ───────────────────────────────────────────────────────────────────────
@@ -432,6 +468,13 @@ if (isMain) {
 
   process.stdout.write(JSON.stringify(result, null, 2) + '\n');
 
+  // Vendoring sanitizer (issue #1098) — surfaced on stderr so the operator sees
+  // it without parsing the JSON envelope. Report-only by construction: it never
+  // enters errors[] and never changes the exit code below.
+  for (const f of result.sanitizer) {
+    process.stderr.write(`rules-sync: sanitizer ${f.kind} ${f.file}:${f.line} — ${f.text}\n`);
+  }
+
   if (result.errors.length > 0) {
     process.exit(1);
   }

package/scripts/lib/scope-gate.mjs

@@ -918,6 +918,28 @@ export function suggestForScopeViolation(relPath, allowedCsv) {
   );
 }
 
+/**
+ * Prefix that marks an aggregate-sidecar record as a PEER SESSION's declared
+ * scope rather than one of this wave's own agents (#1195).
+ *
+ * SSOT: this constant lives here — in the module both the `--union` helper and
+ * `hooks/post-bash-write-verify.mjs` already import — so the union exclusion
+ * below and the hook's peer-write notice can never disagree about what a peer
+ * record IS.
+ */
+export const PEER_RECORD_PREFIX = 'peer-session-';
+
+/**
+ * Is this record id a PEER SESSION's record (see {@link PEER_RECORD_PREFIX})?
+ * Fail-closed: a non-string id is not a peer record.
+ *
+ * @param {unknown} id
+ * @returns {boolean}
+ */
+export function isPeerRecordId(id) {
+  return typeof id === 'string' && id.startsWith(PEER_RECORD_PREFIX);
+}
+
 /**
  * Merge many agents' declared file scopes into ONE deduplicated, order-stable
  * list — the mechanical form of "allowedPaths is the UNION of all agent file
@@ -943,6 +965,19 @@ export function suggestForScopeViolation(relPath, allowedCsv) {
  * non-array / non-object members and non-string, empty entries are skipped.
  * Pure, sync, no I/O — hook-safe per the module header.
  *
+ * PEER RECORDS ARE EXCLUDED (#1195 follow-through). A record whose id starts
+ * with `peer-session-` declares a territory NO agent of this wave may write —
+ * it exists so a peer's paths take part in the DISJOINTNESS check and so
+ * `hooks/post-bash-write-verify.mjs` can name a peer write instead of alarming
+ * about it. Unioning it into `allowedPaths` would do the exact inverse: Gate 7
+ * (`hooks/enforce-scope.mjs`) would GRANT every agent of the wave write access
+ * to the peer's files, and the hook's peer branch would become dead code (a
+ * peer path can only reach it while it is OUTSIDE `allowedPaths`). The
+ * exclusion lives HERE — the one helper `--union` runs — rather than in the
+ * CLI, so every consumer of the union inherits it.
+ * `findScopeCollisions` deliberately does NOT filter: a peer/agent path
+ * collision is a real collision and must surface.
+ *
  * @param {Array<string[]|{id?: string, files?: string[]}>} scopes
  * @returns {string[]} deduplicated union in first-seen order
  */
@@ -954,6 +989,7 @@ export function unionFileScopes(scopes) {
     let files = null;
     if (Array.isArray(scope)) files = scope;
     else if (scope !== null && typeof scope === 'object' && Array.isArray(scope.files)) {
+      if (isPeerRecordId(scope.id)) continue;
       files = scope.files;
     }
     if (files === null) continue;
@@ -992,6 +1028,90 @@ function literalScopeSuffix(entry) {
   return star === -1 ? null : entry.slice(star + 1);
 }
 
+/**
+ * Segments of a scope entry, with the implicit recursion of a trailing `/` made
+ * EXPLICIT as a `**` segment (`tests/` → `['tests', '**']`).
+ *
+ * Load-bearing: {@link pathMatchesPattern} matches a `dir/` prefix with
+ * `startsWith`, i.e. at ANY depth. Splitting `tests/` naively yields a trailing
+ * EMPTY segment, which {@link globsDisagreeOnLiteralSegment} would then compare
+ * against `lib` as if the entry ended there — turning `tests/` vs
+ * `tests/lib/*.mjs` into a false "disjoint".
+ *
+ * @param {string} entry
+ * @returns {string[]}
+ */
+function scopeEntrySegments(entry) {
+  const segs = entry.split('/');
+  if (segs.length > 1 && segs[segs.length - 1] === '') segs[segs.length - 1] = '**';
+  return segs;
+}
+
+/**
+ * Is this segment a PLAIN literal — one that can only match the byte-identical
+ * path segment? Deliberately conservative: `*`, `**`, `?`, `{a,b}` and `[...]`
+ * all count as "could match anything", and an empty segment does too.
+ * @param {string} seg
+ * @returns {boolean}
+ */
+function isPlainLiteralSegment(seg) {
+  return seg.length > 0 && !/[*?{}[\]]/.test(seg);
+}
+
+/**
+ * Do two glob entries carry PLAIN LITERAL segments that DISAGREE at an aligned
+ * position? If so no path can satisfy both, and the pair is disjoint however
+ * much literal prefix and suffix they share (#1130).
+ *
+ * Alignment is exact — and only within the two scans below. Every segment that
+ * is not `**` consumes EXACTLY ONE path segment (`*` compiles to `[^/]*`, which
+ * never crosses `/`; `?`/`{}`/`[]` are regex-ESCAPED by
+ * {@link pathMatchesPattern}, so they are literal text). `**` is the only
+ * variable-width segment, so each scan walks inward from one end and STOPS at
+ * the first `**` on either side — past that wall, positions no longer
+ * correspond. That is why the #1130 pair is decided from the TAIL:
+ * `scripts/**\/reconcile/*.mjs` vs `scripts/**\/learnings/*.mjs` share the
+ * `scripts` head and the `*.mjs` tail, and `reconcile` vs `learnings` is the
+ * first aligned position inward from the tail.
+ *
+ * CEILING (BV-004) — literal-vs-literal ONLY. A `{a,b}`, `?` or `[...]` segment
+ * is treated as "could match anything" and proves nothing, so
+ * `scripts/**\/{reconcile,x}/*.mjs` vs `scripts/**\/learnings/*.mjs` still
+ * reports a collision even though this dialect escapes braces into literal
+ * text. That over-approximation is the SAFE direction for a collision gate (a
+ * reported non-collision costs a coordinator one re-plan; a missed one is the
+ * #1020 incident). Revisit only if {@link pathMatchesPattern} gains real brace
+ * or char-class expansion — then those segments become enumerable and can be
+ * compared set-wise instead of being waved through.
+ *
+ * @param {string} x
+ * @param {string} y
+ * @returns {boolean} true when the two entries provably cannot match one path
+ */
+function globsDisagreeOnLiteralSegment(x, y) {
+  const xs = scopeEntrySegments(x);
+  const ys = scopeEntrySegments(y);
+  const isWall = (seg) => seg.includes('**');
+  const disagree = (a, b) =>
+    isPlainLiteralSegment(a) && isPlainLiteralSegment(b) && a !== b;
+
+  // Scan inward from the HEAD, stopping at the first `**` wall.
+  for (let k = 0; k < xs.length && k < ys.length; k++) {
+    if (isWall(xs[k]) || isWall(ys[k])) break;
+    if (disagree(xs[k], ys[k])) return true;
+  }
+  // Scan inward from the TAIL, same wall rule. Independent of the head scan:
+  // either end can carry the deciding literal, and #1130's does not sit at the
+  // head (both entries begin `scripts/**`).
+  for (let k = 0; k < xs.length && k < ys.length; k++) {
+    const xv = xs[xs.length - 1 - k];
+    const yv = ys[ys.length - 1 - k];
+    if (isWall(xv) || isWall(yv)) break;
+    if (disagree(xv, yv)) return true;
+  }
+  return false;
+}
+
 /**
  * Normalize the `agentScopes` input of {@link findScopeCollisions} into
  * `{id, declaredId, files}` records. Never throws; malformed members are
@@ -1072,6 +1192,12 @@ function classifyEntryCollision(x, y, expand) {
   ) {
     return null;
   }
+  // Prefix + suffix say nothing about the MIDDLE, so `scripts/**\/reconcile/
+  // *.mjs` vs `scripts/**\/learnings/*.mjs` passed every check above and was
+  // reported as a collision (#1130, reproduced 2026-08-24 @ f0766e1). One
+  // aligned pair of DISAGREEING plain literals settles it — see the ceiling
+  // note on the helper for what it deliberately does not decide.
+  if (globsDisagreeOnLiteralSegment(x, y)) return null;
   return 'glob-prefix';
 }