session-orchestrator 4.0.1 → 4.2.0

package/scripts/lib/project-hygiene.mjs

@@ -44,6 +44,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
+import yaml from 'js-yaml';
+import { tokenizeCommand, splitChainSegments, resolveSegmentVerb } from './command-blocker.mjs';
 
 /** Commits past the newest tag before release hygiene is worth mentioning. */
 export const DEFAULT_RELEASE_DRIFT_COMMITS = 50;
@@ -408,8 +410,8 @@ export function checkStaleArtifacts(repoRoot, ageDays = DEFAULT_ARTIFACT_AGE_DAY
 /**
  * H4 — CI configuration hygiene.
  *
- * Measured 5/6. Reports only what is decidable by presence, never by parsing
- * pipeline semantics. The dependency-audit gap is the load-bearing one: three
+ * Measured 5/6. Checks locally declared executable commands without evaluating
+ * pipeline conditions or external includes. The dependency-audit gap is the load-bearing one: three
  * of the tested repos carried known-vulnerable dependencies that no pipeline
  * would ever surface.
  *
@@ -438,19 +440,21 @@ export function checkCiConfig(repoRoot) {
     return findings;
   }
 
-  let ciText = '';
-  if (hasGitlab) ciText += safeRead(gitlabCi);
+  const ciConfigs = [];
+  if (hasGitlab) ciConfigs.push({ text: safeRead(gitlabCi), platform: 'gitlab' });
   if (hasGithub) {
     try {
       for (const f of readdirSync(ghWorkflows)) {
-        if (f.endsWith('.yml') || f.endsWith('.yaml')) ciText += safeRead(join(ghWorkflows, f));
+        if (f.endsWith('.yml') || f.endsWith('.yaml')) {
+          ciConfigs.push({ text: safeRead(join(ghWorkflows, f)), platform: 'github' });
+        }
       }
     } catch {
       /* unreadable workflows dir — fall through with what we have */
     }
   }
 
-  if (ciText && !/\b(npm|pnpm|yarn) audit\b|pip-audit|cargo audit|osv-scanner|dependency.?check/i.test(ciText)) {
+  if (ciConfigs.some(({ text }) => text) && !ciConfigs.some(hasAuditStep)) {
     findings.push({
       check: 'ci-audit-job',
       fixable: true,
@@ -461,6 +465,178 @@ export function checkCiConfig(repoRoot) {
   return findings;
 }
 
+const GITLAB_COMMAND_FIELDS = ['script', 'before_script', 'after_script'];
+const GITLAB_GLOBAL_FIELDS = new Set([
+  'stages', 'types', 'variables', 'default', 'include', 'workflow',
+  'image', 'services', 'cache', 'before_script', 'after_script', 'spec',
+]);
+const GITLAB_REFERENCE = Symbol('gitlab-reference');
+const GITLAB_SCHEMA = yaml.DEFAULT_SCHEMA.extend([
+  new yaml.Type('!reference', {
+    kind: 'sequence',
+    construct: (path) => ({ [GITLAB_REFERENCE]: path }),
+  }),
+]);
+const AUDIT_VALUE_FLAGS = new Set([
+  '--filter', '-F', '--dir', '-C', '--prefix', '--cwd', '--registry',
+  '--userconfig', '--globalconfig', '--workspace', '-w', '--cache', '--pm-on-fail',
+]);
+const AUDIT_BOOLEAN_FLAGS = new Set([
+  '-r', '--recursive', '-s', '--silent', '-g', '--global', '--workspaces', '--offline',
+]);
+
+/** Inspect executable job/step locations, never arbitrary keys named run/script. */
+function hasAuditStep({ text, platform }) {
+  let config;
+  try {
+    if (platform === 'gitlab') {
+      const documents = yaml.loadAll(text, undefined, { schema: GITLAB_SCHEMA });
+      if (documents.length === 1) {
+        [config] = documents;
+      } else if (documents.length === 2 && isConfigMap(documents[0])
+        && Object.keys(documents[0]).length === 1 && isConfigMap(documents[0].spec)) {
+        // GitLab permits a spec header followed by --- and the job document.
+        // Header input defaults are data; unrelated multi-document YAML is ambiguous.
+        [, config] = documents;
+      } else {
+        return false;
+      }
+    } else {
+      config = yaml.load(text);
+    }
+  } catch {
+    return false;
+  }
+  if (!isConfigMap(config)) return false;
+  if (platform === 'github') {
+    if (!isConfigMap(config.jobs)) return false;
+    return Object.values(config.jobs).some((job) => isConfigMap(job)
+      && job.if !== false && Array.isArray(job.steps)
+      && job.steps.some((step) => isConfigMap(step) && step.if !== false
+        && typeof step.run === 'string' && hasAuditCommand(step.run)));
+  }
+
+  return Object.keys(config).some((name) => {
+    if (name.startsWith('.') || GITLAB_GLOBAL_FIELDS.has(name)) return false;
+    const job = resolveGitlabJob(config, name);
+    if (!job?.script || job.when === 'never') return false;
+    return GITLAB_COMMAND_FIELDS.some((field) => {
+      let commands = job[field];
+      if (!Object.hasOwn(job, field) && field !== 'script') {
+        const inherit = job.inherit?.default;
+        if (inherit === false || (Array.isArray(inherit) && !inherit.includes(field))) return false;
+        commands = Object.hasOwn(config.default ?? {}, field) ? config.default[field] : config[field];
+      }
+      return hasGitlabAuditCommands(commands, config);
+    });
+  });
+}
+
+function isConfigMap(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && !Object.hasOwn(value, GITLAB_REFERENCE);
+}
+
+/** Local extends uses later-parent/child replacement for command arrays. */
+function resolveGitlabJob(config, name, seen = new Set()) {
+  if (typeof name !== 'string' || !Object.hasOwn(config, name)
+    || !isConfigMap(config[name]) || seen.has(name)) return null;
+  seen.add(name);
+  const job = config[name];
+  let merged = {};
+  const parents = Array.isArray(job.extends) ? job.extends : [job.extends];
+  for (const parent of parents.filter((entry) => entry !== undefined)) {
+    const inherited = resolveGitlabJob(config, parent, seen);
+    // An unresolved later parent may override earlier commands. Only fields
+    // supplied by later local parents or the job itself remain evidence.
+    merged = inherited ? mergeGitlabJob(merged, inherited) : {};
+  }
+  seen.delete(name);
+  return mergeGitlabJob(merged, job);
+}
+
+function mergeGitlabJob(parent, child) {
+  const merged = { ...parent, ...child };
+  // Command fields replace wholesale; inherit is a map, so its default flag
+  // survives a child that overrides only inherit.variables.
+  if (isConfigMap(parent.inherit) && isConfigMap(child.inherit)) {
+    merged.inherit = { ...parent.inherit, ...child.inherit };
+  }
+  return merged;
+}
+
+/** Resolve only command strings/arrays and local !reference paths, with cycle guards. */
+function hasGitlabAuditCommands(commands, config) {
+  const seen = new WeakSet();
+  function visit(value) {
+    if (typeof value === 'string') return hasAuditCommand(value);
+    if (!value || typeof value !== 'object' || seen.has(value)) return false;
+    seen.add(value);
+    let found = false;
+    if (Array.isArray(value)) {
+      found = value.some(visit);
+    } else if (Array.isArray(value[GITLAB_REFERENCE])) {
+      let target = config;
+      for (const key of value[GITLAB_REFERENCE]) {
+        target = target && typeof target === 'object' && Object.hasOwn(target, key) ? target[key] : undefined;
+      }
+      found = visit(target);
+    }
+    seen.delete(value);
+    return found;
+  }
+  return visit(commands);
+}
+
+/**
+ * Bounded command recognition: wrappers and options may precede the audit
+ * subcommand, but another verb (install/run/echo) ends the search. Unknown
+ * value-taking flags and commands hidden in external includes are not resolved.
+ */
+function hasAuditCommand(command) {
+  return splitChainSegments(tokenizeCommand(command)).some((segment) => hasAuditSegment(segment));
+}
+
+function hasAuditSegment(segment, depth = 0) {
+  const resolved = resolveSegmentVerb(segment);
+  if (resolved.alt) return false;
+  let { verb, index } = resolved;
+  if (resolved.payloads.length > 0) {
+    if (depth >= 3 || resolved.payloads.length !== 1) return false;
+    const tokens = tokenizeCommand(resolved.payloads[0]);
+    const parts = splitChainSegments(tokens);
+    // env -S splits argv; it does not execute shell operators. Restrict this
+    // reuse of the shared tokenizer to one plain command with no redirects.
+    if (parts.length !== 1 || parts[0].length !== tokens.length
+      || tokens.some((token) => token.redirect)) return false;
+    const trailingArgs = index < 0 ? [] : segment.slice(index);
+    return hasAuditSegment([...tokens, ...trailingArgs], depth + 1);
+  }
+  if (verb === 'corepack' || verb === 'npx') {
+    index++;
+    while (['-y', '--yes', '--no-install', '--'].includes(segment[index]?.text)) index++;
+    verb = segment[index]?.text;
+  }
+  if (segment.slice(index + 1).some((token) => ['-h', '--help', '--version'].includes(token.text))) return false;
+  if (/^(?:pip-audit|osv-scanner|dependency-check(?:\.sh)?)$/.test(verb ?? '')) return true;
+  if (!/^(?:npm|pnpm|yarn|bun)(?:@[\w.+-]+)?$/.test(verb ?? '') && verb !== 'cargo') return false;
+  let i = index + 1;
+  while (segment[i]?.text.startsWith('-')) {
+    const flag = segment[i].text;
+    if (flag === '--') { i++; break; }
+    if (AUDIT_VALUE_FLAGS.has(flag)) {
+      if (!segment[i + 1] || segment[i + 1].redirect) return false;
+      i += 2;
+    } else if (AUDIT_BOOLEAN_FLAGS.has(flag) || /^--[\w-]+=/.test(flag)) {
+      i++;
+    } else {
+      return false;
+    }
+  }
+  if (/^yarn(?:@|$)/.test(verb) && segment[i]?.text === 'npm') i++;
+  return segment[i]?.text === 'audit';
+}
+
 /** @param {string} p @returns {string} */
 function safeRead(p) {
   try {

package/scripts/lib/quality-gate.mjs

@@ -117,16 +117,18 @@ function resolveRepoRoot(explicit) {
  * Closed set of `degraded` reasons for {@link loadCommandsFromSessionConfigDetailed}.
  *
  * Its own enum, deliberately not shared with `ci-status-banner.mjs`'s
- * `DEGRADED_REASONS`: the members below are exactly the three ways THIS
+ * `DEGRADED_REASONS`: the members below are the ways THIS
  * config-read can fail, and an enum whose members are not exhaustively
  * reachable cannot be switched on exhaustively.
  *
+ *   - `invalid-repo-root` — no non-blank string root was supplied.
  *   - `script-missing` — `scripts/parse-config.mjs` is not on disk.
  *   - `spawn-failed`   — the subprocess exited non-zero, timed out, or wrote
  *                        nothing to stdout.
  *   - `parse-error`    — stdout was not parseable JSON (or the read threw).
  */
 export const CONFIG_READ_DEGRADED_REASONS = Object.freeze([
+  'invalid-repo-root',
   'script-missing',
   'spawn-failed',
   'parse-error',
@@ -168,13 +170,18 @@ function sessionConfigFileExists(repoRoot) {
  * `degraded` is OMITTED, not set to null, on the success path, so a strict
  * `toEqual({commands: {…}})` pin holds for every readable config.
  *
- * Never throws.
+ * Requires an explicit, non-blank repository root; callers that intend cwd
+ * must resolve that default before invoking this loader. Never throws.
  *
  * @param {string} repoRoot
  * @returns {{commands: {lint?: string, typecheck?: string, test?: string},
- *            degraded?: 'script-missing'|'spawn-failed'|'parse-error'}}
+ *            degraded?: 'invalid-repo-root'|'script-missing'|'spawn-failed'|'parse-error'}}
  */
 export function loadCommandsFromSessionConfigDetailed(repoRoot) {
+  // Node inherits cwd for undefined/null, which would read another repo's config.
+  if (typeof repoRoot !== 'string' || !repoRoot.trim()) {
+    return { commands: {}, degraded: 'invalid-repo-root' };
+  }
   try {
     const scriptPath = join(
       dirname(fileURLToPath(import.meta.url)),
@@ -229,9 +236,9 @@ export function loadCommandsFromSessionConfigDetailed(repoRoot) {
  * Returns a partial object — keys that fail to resolve are simply absent
  * (the caller falls through to DEFAULT_COMMANDS for those).
  *
- * Thin wrapper over {@link loadCommandsFromSessionConfigDetailed}; byte-identical
- * return value for every input, including every failure path. Callers that need
- * to tell a failed read from an empty config use the detailed variant.
+ * Returns the commands half of {@link loadCommandsFromSessionConfigDetailed},
+ * including an empty object for an invalid root. Callers that need to tell a
+ * failed read from an empty config use the detailed variant.
  *
  * Never throws.
  *

package/scripts/lib/resource-probe/evaluate.mjs

@@ -61,6 +61,14 @@
  * of starts is a broken instrument to be re-aimed, not a policy to obey.
  */
 
+// `session-shape.mjs` is the ONE exported `agents-per-wave` resolver; this
+// module used to carry a private third copy. Import-graph note (this file is
+// hook-reachable via `hooks/_lib/hook-import-set.json`): `session-shape.mjs`
+// statically imports only `session-schema/constants.mjs`, a pure-data leaf, and
+// defers `events.mjs` to a lazy `await import()` — so nothing runs at module
+// load here that did not run before.
+import { resolveAgentCap } from '../session-shape.mjs';
+
 // ---------------------------------------------------------------------------
 // Verdict precedence helper
 // ---------------------------------------------------------------------------
@@ -252,29 +260,19 @@ function concurrencySignal(snapshot, concWarn) {
 }
 
 /**
- * Resolve an `agentsPerWave` option value into a plain numeric cap, or `null`
- * when no cap should apply. Mirrors `resolveApwCap()` in
- * `../wave-resource-gate.mjs` — kept as a local pure helper here rather than
- * a cross-module import since both sites are ≤10 lines and evolve
- * independently per their own gate's options shape.
+ * The session type this module resolves `agents-per-wave` FOR: none.
  *
- * `evaluate()` has no session-mode input in scope, so the object shape
- * resolves to `cap.default` — the documented HR-003 convention writes the
- * override as `<default> (mode: <higher-ceiling>)`, i.e. `default` is the
- * MORE restrictive of the pair, so this can only under-apply a looser
- * mode-specific ceiling, never let a heavy repo exceed its base cap.
+ * `evaluate()` has no session-mode input in scope, so it deliberately asks
+ * `resolveAgentCap` for no type and takes the `.default` fallback. The HR-003
+ * convention writes the override as `<default> (mode: <higher-ceiling>)`, i.e.
+ * `default` is the MORE restrictive of the pair — under-applying a looser
+ * mode-specific ceiling is safe, while passing a guessed `'deep'` here would
+ * silently RAISE a heavy repo's ceiling to the deep override on a loaded host.
+ * Naming the absence is what keeps that from being written by accident.
  *
- * @param {number|{default: number, [mode: string]: number}|*} cap
- * @returns {number|null}
+ * @type {undefined}
  */
-function resolveAgentsPerWaveCap(cap) {
-  if (typeof cap === 'number') return Number.isFinite(cap) ? cap : null;
-  if (cap !== null && typeof cap === 'object' && !Array.isArray(cap)) {
-    const def = cap.default;
-    return typeof def === 'number' && Number.isFinite(def) ? def : null;
-  }
-  return null;
-}
+const MODE_BLIND_SESSION_TYPE = undefined;
 
 /**
  * Evaluate a snapshot against `resource-thresholds` (from Session Config #166)
@@ -423,7 +421,7 @@ export function evaluate(snapshot, thresholds, options = {}) {
   // the live-probe signals already computed.
   // ---------------------------------------------------------------------------
   const { heavyRepo, agentsPerWave } = options;
-  const resolvedApwCap = resolveAgentsPerWaveCap(agentsPerWave);
+  const resolvedApwCap = resolveAgentCap(agentsPerWave, MODE_BLIND_SESSION_TYPE);
   if (heavyRepo === true && resolvedApwCap !== null) {
     cap = cap === null ? resolvedApwCap : Math.min(cap, resolvedApwCap);
   }

package/scripts/lib/rules-sync.mjs

@@ -121,7 +121,7 @@ function listManifestCategories(indexContent) {
  * @param {string|null} explicitArchetype
  * @returns {{archetype: string|null, known: boolean}}
  */
-function resolveArchetype(repoRoot, explicitArchetype) {
+export function resolveArchetype(repoRoot, explicitArchetype) {
   if (explicitArchetype) {
     return { archetype: explicitArchetype.trim().toLowerCase(), known: true };
   }
@@ -194,6 +194,12 @@ function escapeRegex(s) {
  * at least one concrete bullet entry. This keeps `/bootstrap --sync-rules`
  * ready for future opt-in categories without requiring CLI changes.
  *
+ * `requiredBasenames` optionally adds explicitly required manifest entries,
+ * regardless of category or archetype scope. The caller supplies this data;
+ * this synchronous writer performs no external lookup. Every requested name
+ * must resolve uniquely in the full manifest before ANY file is written.
+ * Source validation, provenance, local overrides and dry-run still apply.
+ *
  * 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
@@ -214,7 +220,8 @@ function escapeRegex(s) {
  *   dryRun?: boolean,
  *   validate?: boolean,
  *   requireProvenance?: boolean,
- *   archetype?: string|null
+ *   archetype?: string|null,
+ *   requiredBasenames?: string[]|null
  * }} opts
  * @returns {{
  *   written: string[],
@@ -233,6 +240,7 @@ export function syncRules({
   validate = true,
   requireProvenance = true,
   archetype = null,
+  requiredBasenames = null,
 } = {}) {
   const written = [];
   const skipped = [];
@@ -268,13 +276,35 @@ export function syncRules({
     ? categories
     : listManifestCategories(indexContent);
   const entries = parseIndex(indexContent, selectedCategories);
+  const fullManifest = parseIndex(indexContent, listManifestCategories(indexContent));
+  const required = new Set();
+  if (requiredBasenames !== null) {
+    if (!Array.isArray(requiredBasenames)) {
+      errors.push({ file: '_index.md', reason: 'requiredBasenames must be an array of unique manifest basenames' });
+    } else {
+      for (const name of requiredBasenames) {
+        if (typeof name !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]*\.md$/.test(name) || required.has(name)) {
+          errors.push({ file: '_index.md', reason: 'invalid or duplicate required basename' });
+          continue;
+        }
+        required.add(name);
+        const matching = fullManifest.filter((entry) => basename(entry.relPath) === name);
+        if (matching.length !== 1) {
+          errors.push({ file: name, reason: 'required basename must resolve uniquely in _index.md' });
+        } else if (!entries.some((entry) => entry.relPath === matching[0].relPath)) {
+          entries.push(matching[0]);
+        }
+      }
+    }
+    if (errors.length > 0) return { written, skipped, preserved, errors, warnings, sanitizer };
+  }
 
   // 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)),
+    fullManifest.map((e) => basename(e.relPath)),
   );
 
   if (entries.length === 0) {
@@ -297,7 +327,7 @@ export function syncRules({
 
     // Archetype filter (issue #722 Epic A Wave 3) — evaluated before any
     // file IO, so a skip never triggers a spurious "source file not found".
-    if (archetypes !== null) {
+    if (archetypes !== null && !required.has(basename(relPath))) {
       if (!resolvedArchetype.known) {
         skipped.push({ file: relPath, reason: 'archetype-unknown' });
         continue;