session-orchestrator 4.0.0 → 4.0.1

package/scripts/lib/validate/check-codex-skills.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Independently inspect Codex discovery artifacts; generator freshness alone
+// cannot detect a generator that consistently emits an invalid skill contract.
+import { existsSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import yaml from 'js-yaml';
+
+const SKILL_ROOT = '.codex-plugin/skills';
+const FRONTMATTER_KEYS = new Set([
+  'name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools',
+]);
+
+/** @param {unknown} value */
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Read emitted artifacts against their source contract without importing the
+ * generator or comparing its prose. Paths are resolved as installed files.
+ * @param {string} pluginRoot
+ * @returns {{skills: string[], violations: string[]}}
+ */
+export function validateCodexSkills(pluginRoot) {
+  const root = realpathSync(pluginRoot);
+  const violations = [];
+  const sources = new Map();
+  const skills = [];
+  const label = (file) => relative(root, file).split(sep).join('/');
+
+  function text(file) {
+    try {
+      const actual = realpathSync(file);
+      if (!actual.startsWith(`${root}${sep}`)) {
+        violations.push(`${label(file)}: outside the plugin package`);
+        return null;
+      }
+      return readFileSync(file, 'utf8');
+    } catch (error) {
+      violations.push(`${label(file)}: missing or unreadable (${error.code ?? error.message})`);
+      return null;
+    }
+  }
+
+  function mapping(raw, file) {
+    if (raw === null) return null;
+    try {
+      const parsed = yaml.load(raw, { schema: yaml.CORE_SCHEMA });
+      if (!isRecord(parsed)) throw new Error('expected a YAML mapping');
+      return parsed;
+    } catch (error) {
+      violations.push(`${label(file)}: invalid YAML (${error.message.split('\n')[0]})`);
+      return null;
+    }
+  }
+
+  function frontmatter(file) {
+    const raw = text(file);
+    if (raw === null) return null;
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+    if (!match) {
+      violations.push(`${label(file)}: missing YAML frontmatter`);
+      return null;
+    }
+    const fm = mapping(match[1], file);
+    return fm && { fm, body: raw.slice(match[0].length) };
+  }
+
+  // Codex's Agent Plugins loader fixes skills to ./skills; its native overlay
+  // cannot override skills or version. A valid native manifest alone is not
+  // enough when a standard root manifest intercepts discovery (CLI 0.153.3/4).
+  const rootManifestFile = join(root, 'plugin.json');
+  if (existsSync(rootManifestFile)) {
+    try {
+      const manifest = JSON.parse(text(rootManifestFile));
+      if (typeof manifest?.$schema === 'string' && manifest.$schema.startsWith('https://agent-plugins.org/schemas/')) {
+        violations.push('Root Agent Plugins manifest overrides native Codex skills and cache version; use the native harness manifests');
+      }
+    } catch (error) {
+      violations.push(`Root plugin manifest: invalid JSON (${error.message})`);
+    }
+  }
+
+  const manifestFile = join(root, '.codex-plugin/plugin.json');
+  try {
+    const raw = text(manifestFile);
+    const manifest = raw === null ? null : JSON.parse(raw);
+    if (manifest?.skills !== `./${SKILL_ROOT}/`) {
+      violations.push(`Codex manifest skills must register only ./${SKILL_ROOT}/`);
+    }
+    if (!Array.isArray(manifest?.commands) || manifest.commands.length !== 0) {
+      violations.push('Codex manifest commands must be an explicit empty array to disable automatic command migration');
+    }
+  } catch (error) {
+    violations.push(`Codex manifest: invalid JSON (${error.message})`);
+  }
+
+  // Skill first, command second: a command owns the public entry on overlap.
+  for (const kind of ['skill', 'command']) {
+    const directory = join(root, kind === 'skill' ? 'skills' : 'commands');
+    if (!existsSync(directory)) {
+      violations.push(`${label(directory)}: canonical source directory is missing`);
+      continue;
+    }
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const name = kind === 'command' ? entry.name.replace(/\.md$/, '') : entry.name;
+      if (name.startsWith('.') || name.startsWith('_')) continue;
+      if (kind === 'command' && !entry.name.endsWith('.md')) continue;
+      const file = kind === 'command' ? join(directory, entry.name) : join(directory, name, 'SKILL.md');
+      if (kind === 'skill' && !existsSync(file)) continue;
+      const source = frontmatter(file);
+      sources.set(name, { kind, file, fm: source?.fm });
+    }
+  }
+  if (sources.size === 0) violations.push('No canonical commands or skills found');
+
+  const generated = join(root, SKILL_ROOT);
+  const actualNames = existsSync(generated)
+    ? readdirSync(generated, { withFileTypes: true })
+      .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && existsSync(join(generated, entry.name, 'SKILL.md')))
+      .map((entry) => entry.name)
+    : [];
+  for (const name of [...new Set([...sources.keys(), ...actualNames])].sort()) {
+    const source = sources.get(name);
+    if (!source) {
+      violations.push(`${SKILL_ROOT}/${name}: no canonical source`);
+      continue;
+    }
+    const file = join(generated, name, 'SKILL.md');
+    const artifact = frontmatter(file);
+    if (!artifact) continue;
+    skills.push(name);
+    const { fm, body } = artifact;
+    if (fm.name !== name) violations.push(`${label(file)}: name must equal ${name}`);
+    if (typeof fm.description !== 'string' || !fm.description.trim() || fm.description.length > 1024) {
+      violations.push(`${label(file)}: description must be a non-empty string of at most 1024 characters`);
+    }
+    for (const key of Object.keys(fm)) {
+      if (!FRONTMATTER_KEYS.has(key)) violations.push(`${label(file)}: unsupported frontmatter key ${key}`);
+    }
+    if (fm.metadata !== undefined && (!isRecord(fm.metadata) || Object.values(fm.metadata).some((value) => typeof value !== 'string'))) {
+      violations.push(`${label(file)}: metadata must contain string values`);
+    }
+    const links = [...body.matchAll(/\]\(([^\s)]+)\)/g)].map((match) => match[1]);
+    if (!links.some((target) => !target.includes(':') && !target.startsWith('/') && resolve(dirname(file), target) === source.file)) {
+      violations.push(`${label(file)}: missing canonical link to ${label(source.file)}`);
+    }
+    if (source.kind === 'command' && source.fm) {
+      const disabled = source.fm['disable-model-invocation'];
+      if (disabled !== undefined && typeof disabled !== 'boolean') {
+        violations.push(`${label(source.file)}: disable-model-invocation must be boolean`);
+      }
+      const policyFile = join(generated, name, 'agents/openai.yaml');
+      const sidecar = mapping(text(policyFile), policyFile);
+      if (sidecar && (typeof sidecar.policy?.allow_implicit_invocation !== 'boolean'
+        || sidecar.policy.allow_implicit_invocation !== (disabled !== true))) {
+        violations.push(`${label(policyFile)}: allow_implicit_invocation must preserve the command's boolean policy`);
+      }
+    }
+  }
+  return { skills, violations };
+}
+
+async function main(pluginRoot) {
+  if (!pluginRoot) throw new Error('Usage: check-codex-skills.mjs <plugin-root>');
+  console.log('--- Check: Codex command skills and generated freshness ---');
+  const { skills, violations } = validateCodexSkills(pluginRoot);
+  if (violations.length === 0) {
+    // Invoke the function directly: a child CLI that silently skips its entry
+    // point must never turn a missing freshness comparison into success.
+    const { generateCodexSurface } = await import('../../generate-codex-skills.mjs');
+    const fresh = generateCodexSurface({ pluginRoot, check: true });
+    if (!fresh.ok || !Array.isArray(fresh.files) || fresh.files.length === 0) {
+      violations.push(...(fresh.drift ?? []), ...(fresh.errors ?? []));
+      if (violations.length === 0) violations.push('Codex generator did not report a successful artifact comparison');
+    }
+  }
+  for (const violation of violations) console.log(`  FAIL: ${violation}`);
+  if (violations.length === 0) console.log(`  PASS: ${skills.length} unique Codex skills, command policies and generated files in sync`);
+  console.log(`Results: ${violations.length === 0 ? 1 : 0} passed, ${violations.length} failed`);
+  if (violations.length) console.log('Remedy: node scripts/generate-codex-skills.mjs');
+  process.exitCode = violations.length ? 1 : 0;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  main(process.argv[2]).catch((error) => {
+    console.error(`FAIL: Codex skills check: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

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

@@ -751,7 +751,7 @@ function rawConfidentialNamesKeyState(ownerYamlPath) {
  * be called only from runScan() — NOT at module top-level. This module is
  * dual-mode (CLI entry point AND importable library, `isMain` guard); a top-level
  * fs read would fire on every library import (e.g. pseudonym-map.mjs importing
- * isOwnerLeakySegment). loadConfidentialNames caches per path, so calling this
+ * isOwnerLeakySegment). inspectConfidentialNames caches per path, so calling this
  * once per scan reads the file at most once.
  *
  * STANDALONE-SAFE: the two host-local helper modules are DYNAMICALLY imported
@@ -803,7 +803,26 @@ async function getConfidentialNamePatterns() {
     };
   } catch (err) {
     if (err?.code === 'ERR_MODULE_NOT_FOUND' && isMissingDirectSibling(err)) {
-      // (a) standalone single-file vendoring — the documented degrade.
+      // (a) standalone single-file vendoring. The degrade is documented — but it
+      // must not swallow a CP11 that the operator DID configure (GitLab #1262).
+      // No helper resolved here, so the only configuration signal still readable
+      // is the raw env var: a literal mirror of ENV_KEYS['confidential-names-file']
+      // in scripts/lib/config/host-paths.mjs, which cannot be imported on this
+      // branch by construction.
+      //
+      // LIMIT (named, not hidden): an owner.yaml-configured names file is
+      // STRUCTURALLY undetectable in a standalone copy — resolveOwnerYamlPath()
+      // lives in the very module chain that failed to resolve, so there is no way
+      // to learn that owner.yaml even exists, let alone what it configures. Only
+      // the env route can fail closed here; the owner.yaml route degrades inert.
+      const envNamesPath = process.env.SO_CONFIDENTIAL_NAMES_FILE;
+      if (typeof envNamesPath === 'string' && envNamesPath.trim() !== '') {
+        return {
+          patterns: [],
+          disabledReason:
+            'CP11 configured via SO_CONFIDENTIAL_NAMES_FILE but the confidential-names helpers are not resolvable (standalone copy) — failing closed',
+        };
+      }
       return {
         patterns: [],
         inertWarn: 'CP11 inert — confidential-names helpers not resolvable (standalone copy)',
@@ -815,35 +834,60 @@ async function getConfidentialNamePatterns() {
 
   try {
     const { loadHostPaths, resolveHostPath } = helpers.hostPaths;
-    const { loadConfidentialNames } = helpers.confidentialNames;
-    const { loadOwnerConfig, resolveOwnerYamlPath } = helpers.ownerYaml;
+    const { inspectConfidentialNames } = helpers.confidentialNames;
+    const { resolveOwnerYamlPath } = helpers.ownerYaml;
+
+    // ONE owner.yaml load. Since #1251 loadHostPaths() passes the loader's own
+    // health (source / reason / droppedSections) straight through, so the
+    // env>owner.yaml>default precedence and the load's diagnosis come from the
+    // same read — no second loadOwnerConfig() call to recover what was discarded.
+    const hostCtx = loadHostPaths();
+
+    // FAIL-CLOSED on an unknowable load (LOW-2). `loadHostPaths` has its own
+    // defensive catch that swallows a THROWING owner loader and returns
+    // `{ ownerConfig: undefined, env, source: undefined, reason: undefined }`.
+    // Without this branch that shape resolves `namesPath` to '' , fires no
+    // reason branch, and returns `{ patterns: [] }` — a silent PASS.
+    // Only the throw produces all-undefined: `loadOwnerConfig` returns
+    // `{ config: getDefaults(), source: 'defaults', errors: [] }` for a
+    // genuinely ABSENT owner.yaml (owner-yaml.mjs:587-590) and `source:
+    // 'defaults'` with a `reason` for every read/parse failure — so a missing
+    // file keeps taking the normal path below. Latent today (the loader
+    // returns on every error path), load-bearing if that ever changes.
+    if (
+      hostCtx.ownerConfig === undefined &&
+      hostCtx.source === undefined &&
+      hostCtx.reason === undefined
+    ) {
+      return {
+        patterns: [],
+        disabledReason:
+          'CP11 could not determine whether a confidential-names file is configured (owner config loader failed) — failing closed',
+      };
+    }
 
-    // Load owner.yaml ONCE and hand the same result to loadHostPaths, so the
-    // env>owner.yaml>default precedence is unchanged while the load's own health
-    // (reason / droppedSections) stays visible here.
-    const owner = loadOwnerConfig();
-    const namesPath = resolveHostPath('confidential-names-file', '', loadHostPaths({ ownerLoader: () => owner }));
+    const namesPath = resolveHostPath('confidential-names-file', '', hostCtx);
 
     if (typeof namesPath !== 'string' || namesPath.trim() === '') {
       // Nothing resolves a names file. That is either (b) — genuinely
       // unconfigured — or a state in which the answer is UNKNOWABLE because the
       // owner.yaml that would carry it could not be read. Unknowable is (c).
       if (existsSync(resolveOwnerYamlPath())) {
-        if (owner.reason === 'yaml-parser-missing') {
+        if (hostCtx.reason === 'yaml-parser-missing') {
           return {
             patterns: [],
             disabledReason:
               "owner.yaml exists but 'js-yaml' is not installed, so a configured confidential-names-file cannot be resolved (run 'npm install')",
           };
         }
-        if (owner.reason === 'unparseable') {
+        if (hostCtx.reason === 'unparseable') {
           return {
             patterns: [],
             disabledReason:
               'owner.yaml exists but could not be parsed, so a configured confidential-names-file cannot be resolved',
           };
         }
-        if (owner.droppedSections?.some((d) => d.section === 'paths')) {
+        if (hostCtx.droppedSections?.some((d) => d.section === 'paths')) {
           // The paths: section was replaced by its default because SOME key in it
           // is invalid — which says nothing yet about whether CP11 was configured.
           // Re-read the RAW file for that one key (the loader does not expose it on
@@ -875,15 +919,37 @@ async function getConfidentialNamePatterns() {
       return { patterns: [] }; // (b) the ~99% default — inactive, silent.
     }
 
-    // A names file IS configured. loadConfidentialNames() returns null for BOTH
-    // "unusable" and "deliberately empty list", so classify the file first — an
-    // empty list is an operator choice (inactive, silent), a missing/malformed
-    // one is (c).
-    const unusable = classifyNamesFile(namesPath);
-    if (unusable) return { patterns: [], disabledReason: unusable };
-
-    const names = loadConfidentialNames({ namesPath });
-    if (!names) return { patterns: [] }; // readable, well-formed, zero usable entries.
+    // A names file IS configured. Since #1250 the loader REPORTS the class it
+    // used to collapse into `null`, so the verdict reads straight off `status` —
+    // no second read of the file to re-derive it. Only `[]` ('empty') is an
+    // operator choice (inactive, silent); 'missing'/'malformed'/'all-dropped'
+    // mean a configured guard cannot run, which is (c) and fails closed. The
+    // reasons carry no path (see above). `inspectConfidentialNames` is the
+    // discriminated entry point; `loadConfidentialNames` keeps its 4.0.0
+    // `string[] | null` shape for external deep-importers and cannot express
+    // this distinction.
+    const { status, names } = inspectConfidentialNames({ namesPath });
+    if (status === 'missing') {
+      return { patterns: [], disabledReason: 'a confidential-names-file is configured but does not exist' };
+    }
+    if (status === 'malformed') {
+      return {
+        patterns: [],
+        disabledReason: 'the configured confidential-names-file is unreadable or not a JSON array of names',
+      };
+    }
+    if (status === 'all-dropped') {
+      // W4 finding F3 (fail-open): the file listed entries and validation rejected
+      // every one of them (non-strings, blanks, over-long). That is a CORRUPTED
+      // list, not the `[]` opt-out — CP11 would run with zero patterns and report
+      // the clean verdict it never earned. Same class as 'malformed'.
+      return {
+        patterns: [],
+        disabledReason:
+          'every entry in the configured confidential-names-file was rejected as invalid or oversized',
+      };
+    }
+    if (status !== 'ok') return { patterns: [] }; // 'empty' — the operator's `[]` opt-out.
     return { patterns: names.map((name) => new RegExp(`\\b${escapeRegex(name)}\\b`, 'i')) };
   } catch (err) {
     // The helpers resolved but something below threw. CP11 cannot run — fail closed.
@@ -891,40 +957,6 @@ async function getConfidentialNamePatterns() {
   }
 }
 
-/**
- * Classify a CONFIGURED confidential-names file as usable or not.
- *
- * `loadConfidentialNames()` collapses "file missing / unreadable / malformed /
- * not an array" and "well-formed but empty" into one `null` return, which is
- * exactly the distinction CP11's fail-closed verdict turns on. Rather than widen
- * that module's contract (it has four other consumers of its `null`), this reads
- * the file once more for classification only. It never returns file CONTENT — the
- * reason string carries the error CLASS alone, matching the confidential-names
- * privacy invariant and the no-path rule above.
- *
- * @param {string} namesPath
- * @returns {string|null} a reason string when unusable, null when usable.
- */
-function classifyNamesFile(namesPath) {
-  let raw;
-  try {
-    if (!existsSync(namesPath)) {
-      return 'a confidential-names-file is configured but does not exist';
-    }
-    raw = readFileSync(namesPath, 'utf8');
-  } catch (err) {
-    return `the configured confidential-names-file is unreadable (${err?.name ?? 'Error'})`;
-  }
-  try {
-    if (!Array.isArray(JSON.parse(raw))) {
-      return 'the configured confidential-names-file is not a JSON array';
-    }
-  } catch (err) {
-    return `the configured confidential-names-file contains malformed JSON (${err?.name ?? 'Error'})`;
-  }
-  return null;
-}
-
 // ---------------------------------------------------------------------------
 // Text-scan extension allowlist (spec A.2)
 // ---------------------------------------------------------------------------
@@ -1077,6 +1109,10 @@ function isAllowlisted(relPath, line) {
     'site/index.html',
     'site/impressum/index.html',
     'site/datenschutz/index.html',
+    // The German landing page (2026-09-07 redesign) carries the same publisher
+    // identity (JSON-LD @id + footer rel="author") as site/index.html. Exact
+    // path, never a site/de/ prefix — site/guide/index.html stays outside.
+    'site/de/index.html',
   ]);
   const inAllowlistedFile = ALLOWLISTED_URL_PATHS.has(norm);
 

package/scripts/lib/validate/check-skill-links.mjs

@@ -43,13 +43,36 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, relative, sep } from 'node:path';
 
-/** Surfaces whose markdown is instruction, i.e. read and acted on. */
-export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules']);
+/**
+ * Surfaces whose markdown is instruction, i.e. read and acted on.
+ *
+ * `docs/` joined the list in #1258 after the annotate-before-widen step the sibling
+ * `check-skill-script-paths.mjs` ran for #1208: a read-only re-scan (`dirs: ['docs']`,
+ * 2026-09-07) returned 92 files / 111 relative links / 8 findings — six of them GitLab
+ * `-/issues/N` renderer links now carved out by `SKIP_TARGET`, two of them genuinely dangling
+ * links to PRDs that had been archived to the private Meta-Vault. Both classes were resolved
+ * before the widening, so the widening itself lands at 0 findings.
+ */
+export const SCAN_DIRS = Object.freeze(['skills', 'commands', 'agents', '.claude/rules', 'docs']);
 
 /** Path segments that end the walk: vendored or machine-owned trees, never instruction. */
 export const PRUNE_DIRS = new Set(['node_modules', '.git', 'coverage', 'dist', '.pnpm']);
 
-const SKIP_TARGET = /^(https?:|mailto:|#|\/)/i;
+/**
+ * Targets this checker never resolves against the filesystem.
+ *
+ * The `-/issues/N` · `-/merge_requests/N` branch is a GitLab RENDERER convention, not a link
+ * defect: `../../../-/issues/174` is how a doc nested two levels deep points at the project's
+ * issue tracker, and GitLab resolves it correctly in its own Markdown view. It leaves the repo
+ * by construction, so a filesystem checker can only ever call it dangling. Measured 2026-09-07:
+ * 6 of the 8 `docs/` findings were exactly this shape, all in `docs/owner-config-schema.md`.
+ *
+ * The branch is anchored at BOTH ends. Left-unanchored it would still be a carve-out, but
+ * right-unanchored it swallowed every path that merely PASSES THROUGH such a segment —
+ * `docs/-/issues/12/../../secrets.md` is a genuinely dangling link and was SKIPped. The
+ * optional trailing `#note_123` is kept because GitLab issue links legitimately carry one.
+ */
+const SKIP_TARGET = /^(https?:|mailto:|#|\/)|(^|\/)-\/(issues|merge_requests)\/\d+(#[\w-]*)?$/i;
 const LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
 const INLINE_CODE_RE = /(`+)[^`]*?\1/g;
 
@@ -89,11 +112,15 @@ function fencedLineNumbers(text) {
  * these four directories would also be checked — there are none, and one would be a finding worth
  * seeing anyway.
  *
+ * @param {string} repoRoot
+ * @param {{dirs?: readonly string[]}} [options] `dirs` defaults to {@link SCAN_DIRS}; it exists so
+ *   an annotate-before-widen dry-run over a candidate surface needs no re-implementation of this
+ *   predicate (same shape as `scanSkillScriptPaths({ dirs })`).
  * @returns {string[]} repo-relative paths, sorted for stable output
  */
-export function listMarkdown(repoRoot) {
+export function listMarkdown(repoRoot, { dirs = SCAN_DIRS } = {}) {
   const out = [];
-  for (const dir of SCAN_DIRS) {
+  for (const dir of dirs) {
     const abs = join(repoRoot, dir);
     let entries;
     try { entries = readdirSync(abs, { recursive: true, withFileTypes: true }); } catch { continue; }
@@ -112,12 +139,15 @@ export function listMarkdown(repoRoot) {
 }
 
 /**
+ * @param {string} [repoRoot]
+ * @param {{dirs?: readonly string[]}} [options] `dirs` defaults to {@link SCAN_DIRS} — see
+ *   {@link listMarkdown}.
  * @returns {{ok: boolean, checked: number, files: number, findings: Array<{file: string, line: number, target: string}>}}
  */
-export function checkSkillLinks(repoRoot = process.cwd()) {
+export function checkSkillLinks(repoRoot = process.cwd(), { dirs = SCAN_DIRS } = {}) {
   const findings = [];
   let checked = 0;
-  const files = listMarkdown(repoRoot);
+  const files = listMarkdown(repoRoot, { dirs });
 
   for (const rel of files) {
     const abs = join(repoRoot, rel);