session-orchestrator 4.0.0 → 4.1.0

package/hooks/on-stop.mjs

@@ -48,7 +48,7 @@ import { AGENT_ID_RE, resolveSubagentSidecar } from './_lib/subagent-paths.mjs';
 if (!shouldRunHook('on-stop')) process.exit(0);
 
 import { emitEvent } from '../scripts/lib/events.mjs';
-import { getProjectDir } from '../scripts/lib/platform.mjs';
+import { detectPlatform, getProjectDir } from '../scripts/lib/platform.mjs';
 import { parseSessionId } from '../scripts/lib/session-id.mjs';
 import { heartbeat, logSweepEvent } from '../scripts/lib/session-registry.mjs';
 import { readLock, updateHeartbeat } from '../scripts/lib/session-lock.mjs';
@@ -772,7 +772,7 @@ async function main() {
       await handleStop(input);
     } finally {
       // terminalSequence is only meaningful for Stop (session-level) events.
-      process.stdout.write(buildTerminalSequenceJson());
+      process.stdout.write(buildTerminalSequenceJson(detectPlatform()));
     }
   }
 }
@@ -781,15 +781,36 @@ async function main() {
 // terminal notification
 // ---------------------------------------------------------------------------
 
+/**
+ * Display label per harness, keyed exactly like PLATFORM_UPDATE_INSTRUCTIONS in
+ * `scripts/lib/plugin-update-banner.mjs`.
+ * @type {Record<string, string>}
+ */
+const PLATFORM_NOTIFY_LABELS = {
+  claude: 'Claude Code',
+  codex:  'Codex',
+  cursor: 'Cursor',
+  pi:     'Pi',
+};
+
 /**
  * Emit a cross-platform desktop notification via the CC 2.1.141+ terminalSequence
  * output field. Supports OSC 9 (iTerm2, Windows Terminal, WezTerm, ConEmu) and
  * OSC 777 (Ghostty, urxvt, Warp). Both sequences are emitted together; unsupported
  * terminals silently ignore. Returns the JSON string to write to stdout.
+ * Pure: the caller resolves the platform, so this stays unit-testable.
+ * @param {string} [platform] - resolved harness key ('claude'|'codex'|'cursor'|'pi')
  * @returns {string}
  */
-function buildTerminalSequenceJson() {
-  const title = 'Claude Code';
+function buildTerminalSequenceJson(platform) {
+  // #1254: the notification LABEL follows the harness the session runs on.
+  // This is NOT in tension with the "Do NOT add a platform-detecting deregister
+  // branch here" note above — that note is scoped to DEREGISTRATION (the
+  // two-teardown-paths shape Epic #583 removed); a display label has no
+  // teardown semantics at all. Keys mirror PLATFORM_UPDATE_INSTRUCTIONS in
+  // scripts/lib/plugin-update-banner.mjs; unknown/undefined falls back to
+  // 'Claude Code' (the same signal-free default detectPlatform() returns).
+  const title = PLATFORM_NOTIFY_LABELS[platform] ?? 'Claude Code';
   const body  = 'Session stopped — your turn';
   const osc9   = `\x1b]9;${title}: ${body}\x07`;
   const osc777 = `\x1b]777;notify;${title};${body}\x07`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -25,7 +25,6 @@
     ".mcp.json",
     "AGENTS.md",
     "CHANGELOG.md",
-    "plugin.json",
     "pi/",
     "skills/",
     "agents/",
@@ -39,6 +38,7 @@
     "assets/",
     ".claude-plugin/",
     ".codex-plugin/",
+    ".cursor-plugin/",
     ".agents/",
     ".cursor/",
     ".orchestrator/policy/",

package/scripts/ci/assert-coverage-green.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Repository CI only: requires the checkout's Vitest config and dev dependencies.
+// Test-result JSON does not prove coverage. Check the structured coverage summary
+// against the same global percentage thresholds Vitest uses before writing a marker.
+// The caller removes both reports and the marker before starting the current run.
+
+import { readFileSync } from 'node:fs';
+import config from '../../vitest.config.mjs';
+
+const metrics = ['lines', 'functions', 'statements', 'branches'];
+const [summaryPath = 'coverage/coverage-summary.json', xmlPath = 'coverage/cobertura-coverage.xml'] = process.argv.slice(2);
+
+function requireValid(condition, reason) {
+  if (!condition) throw new Error(reason);
+}
+
+// Check completeness of the XML emitted by the configured Istanbul reporter.
+// This is an artifact check, not a DTD/schema evaluator; never fetch the DOCTYPE.
+function checkCobertura(xml, total) {
+  const stack = [];
+  let root;
+  let hasClassLine = false;
+  const parts = xml.match(/<[^>]*>|[^<]+/g) ?? [];
+  requireValid(parts.join('') === xml, 'malformed Cobertura artifact');
+  for (const part of parts) {
+    if (/^<\?xml\s[^<>]*\?>$|^<!DOCTYPE coverage SYSTEM "[^"<>]*">$/.test(part)) {
+      requireValid(!root, 'unexpected Cobertura declaration');
+      continue;
+    }
+    if (!part.startsWith('<')) {
+      requireValid(!part.trim() || stack.at(-1) === 'source', 'unexpected Cobertura content');
+      continue;
+    }
+    const tag = part.match(/^<(\/?)([A-Za-z][\w.-]*)((?:\s+[\w:-]+="[^"<>]*")*)\s*(\/?)>$/);
+    requireValid(tag, 'malformed Cobertura tag');
+    const [, closing, name, attributes, selfClosing] = tag;
+    if (closing) {
+      requireValid(!attributes && !selfClosing && stack.pop() === name, 'unbalanced Cobertura tags');
+    } else {
+      const entries = [...attributes.matchAll(/([\w:-]+)="([^"]*)"/g)].map((match) => [match[1], match[2]]);
+      requireValid(new Set(entries.map(([key]) => key)).size === entries.length, 'duplicate Cobertura attributes');
+      const values = Object.fromEntries(entries);
+      if (stack.length === 0) {
+        requireValid(!root && name === 'coverage' && !selfClosing, 'invalid Cobertura root');
+        root = values;
+      }
+      const path = [...stack, name].join('/');
+      if (path === 'coverage/packages/package/classes/class') {
+        requireValid(typeof values.filename === 'string' && values.filename.trim(), 'Cobertura class is missing a filename');
+      }
+      if (path === 'coverage/packages/package/classes/class/lines/line') {
+        requireValid(/^\d+$/.test(values.number) && Number(values.number) > 0
+          && /^\d+$/.test(values.hits), 'invalid Cobertura line record');
+        hasClassLine = true;
+      }
+      if (!selfClosing) stack.push(name);
+    }
+  }
+  requireValid(root && stack.length === 0, 'empty or incomplete Cobertura artifact');
+  requireValid(total.lines.total === 0 || hasClassLine, 'Cobertura artifact contains no class line records');
+  for (const [attribute, expected] of Object.entries({
+    'lines-valid': total.lines.total,
+    'lines-covered': total.lines.covered,
+    'line-rate': total.lines.pct / 100,
+    'branches-valid': total.branches.total,
+    'branches-covered': total.branches.covered,
+    'branch-rate': total.branches.pct / 100,
+  })) {
+    requireValid(root[attribute] !== undefined && root[attribute] !== ''
+      && Number(root[attribute]) === expected, `Cobertura ${attribute} disagrees with coverage summary`);
+  }
+}
+
+try {
+  const thresholds = config.test?.coverage?.thresholds;
+  requireValid(thresholds && Object.keys(thresholds).every((key) => metrics.includes(key)),
+    'unsupported coverage thresholds: expected global percentage thresholds');
+  const { total } = JSON.parse(readFileSync(summaryPath, 'utf8'));
+  requireValid(total && typeof total === 'object', 'missing coverage totals');
+  for (const metric of metrics) {
+    const threshold = thresholds[metric];
+    requireValid(Number.isFinite(threshold) && threshold >= 0 && threshold <= 100,
+      `missing or invalid configured ${metric} threshold`);
+    const data = total[metric];
+    requireValid(data && ['total', 'covered', 'skipped'].every((key) => Number.isSafeInteger(data[key]) && data[key] >= 0)
+      && data.total > 0 && data.covered <= data.total && data.skipped <= data.total
+      && Number.isFinite(data.pct) && data.pct >= 0 && data.pct <= 100,
+    `missing or invalid ${metric} coverage data`);
+    // Istanbul truncates percentages to two decimals; compare the reported
+    // percentage (Vitest's threshold input) only after checking its counters.
+    const percentage = Math.floor((100000 * data.covered / data.total) / 10) / 100;
+    requireValid(data.pct === percentage, `inconsistent ${metric} coverage percentage`);
+    requireValid(data.pct >= threshold, `${metric} coverage ${data.pct}% is below configured ${threshold}%`);
+  }
+  checkCobertura(readFileSync(xmlPath, 'utf8'), total);
+  console.log(`[ci] coverage verified: ${metrics.map((metric) => `${metric}=${total[metric].pct}%`).join(' ')}`);
+} catch (error) {
+  console.error(`[ci] coverage NOT VERIFIED: ${error.message}`);
+  process.exitCode = 1;
+}

package/scripts/generate-codex-skills.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+/**
+ * Generate the Codex discovery surface from commands/ and skills/.
+ * Commands own overlapping public names; canonical workflow bodies stay in place.
+ * Usage: node scripts/generate-codex-skills.mjs [--plugin-root <dir>] [--check] [--json]
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'js-yaml';
+import { toPortableFrontmatter } from './generate-agents-skills.mjs';
+
+const OUTPUT = '.codex-plugin/skills';
+const MARKER = 'Generated by scripts/generate-codex-skills.mjs; do not edit.';
+
+/** @typedef {{name: string, path: string, command: boolean, fm: Record<string, unknown>, policy?: boolean}} Source */
+
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** @param {unknown} fm @param {string} name @param {string} path */
+function validateFrontmatter(fm, name, path) {
+  const fail = (message) => { throw new Error(`${path}: ${message}`); };
+  if (!isRecord(fm)) fail('YAML frontmatter must be a mapping');
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name) || name.length > 64) fail('name must be kebab-case, at most 64 characters');
+  if (Object.hasOwn(fm, 'name') && fm.name !== name) fail('name must match its file or directory name');
+  if (typeof fm.description !== 'string' || !fm.description.trim() || fm.description.trim().length > 1024) {
+    fail('description must be a non-empty string of at most 1024 characters');
+  }
+  for (const key of ['disable-model-invocation', 'user-invocable']) {
+    if (Object.hasOwn(fm, key) && typeof fm[key] !== 'boolean') fail(`${key} must be a boolean`);
+  }
+  for (const key of ['argument-hint', 'license', 'compatibility']) {
+    if (Object.hasOwn(fm, key) && typeof fm[key] !== 'string') fail(`${key} must be a string`);
+  }
+  if (Object.hasOwn(fm, 'metadata') && !isRecord(fm.metadata)) fail('metadata must be a mapping');
+  for (const key of ['allowed-tools', 'tools']) {
+    if (!Object.hasOwn(fm, key)) continue;
+    const value = fm[key];
+    if (!(typeof value === 'string' || (Array.isArray(value) && value.every((item) => typeof item === 'string' && item.trim())))) {
+      fail(`${key} must be a string or an array of non-empty strings`);
+    }
+  }
+}
+
+/** Existing native policy is meaningful; Claude's user-invocable flag is not a substitute. */
+function readNativePolicy(root, name) {
+  const path = `skills/${name}/agents/openai.yaml`;
+  if (!existsSync(join(root, path))) return undefined;
+  let native;
+  try { native = yaml.load(readFileSync(join(root, path), 'utf8'), { schema: yaml.CORE_SCHEMA }); }
+  catch (error) { throw new Error(`${path}: invalid YAML: ${error.message}`, { cause: error }); }
+  if (!isRecord(native) || (Object.hasOwn(native, 'policy') && !isRecord(native.policy))) {
+    throw new Error(`${path}: native skill metadata and policy must be mappings`);
+  }
+  if (!native.policy || !Object.hasOwn(native.policy, 'allow_implicit_invocation')) return undefined;
+  if (typeof native.policy.allow_implicit_invocation !== 'boolean') {
+    throw new Error(`${path}: policy.allow_implicit_invocation must be a boolean`);
+  }
+  return native.policy.allow_implicit_invocation;
+}
+
+/** @param {string} root @returns {Source[]} */
+function readSources(root) {
+  /** @type {Source[]} */
+  const sources = [];
+  for (const directory of ['skills', 'commands']) {
+    const directoryPath = join(root, directory);
+    if (!existsSync(directoryPath)) continue;
+    for (const entry of readdirSync(directoryPath, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || entry.name.startsWith('_')) continue;
+      const command = directory === 'commands';
+      if (command ? !entry.isFile() || !entry.name.endsWith('.md') : !entry.isDirectory()) continue;
+      const name = command ? entry.name.slice(0, -3) : entry.name;
+      const path = command ? `commands/${name}.md` : `skills/${name}/SKILL.md`;
+      if (!existsSync(join(root, path))) continue;
+      const raw = readFileSync(join(root, path), 'utf8');
+      const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+      if (!match) throw new Error(`${path}: missing YAML frontmatter`);
+      let fm;
+      try { fm = yaml.load(match[1], { schema: yaml.CORE_SCHEMA }); }
+      catch (error) { throw new Error(`${path}: invalid YAML: ${error.message}`, { cause: error }); }
+      validateFrontmatter(fm, name, path);
+      sources.push({ name, path, command, fm, policy: command ? fm['disable-model-invocation'] !== true : readNativePolicy(root, name) });
+    }
+  }
+  return sources;
+}
+
+/** Only these two artifact shapes and their exact ownership marker belong to this generator. */
+function isOwned(path, raw) {
+  if (/^\.codex-plugin\/skills\/[^/]+\/SKILL\.md$/.test(path)) return raw.includes(`\n<!-- ${MARKER} -->\n`);
+  return /^\.codex-plugin\/skills\/[^/]+\/agents\/openai\.yaml$/.test(path) && raw.startsWith(`# ${MARKER}\n`);
+}
+
+/** Read the tree without following symlinks, before any updates are permitted. */
+function readOutput(root, directory = OUTPUT) {
+  const absolute = join(root, directory);
+  if (!existsSync(absolute)) return [];
+  if (!lstatSync(absolute).isDirectory() || lstatSync(absolute).isSymbolicLink()) {
+    throw new Error(`${directory}: generated directory must be a real directory`);
+  }
+  const files = [];
+  for (const entry of readdirSync(absolute, { withFileTypes: true })) {
+    const path = `${directory}/${entry.name}`;
+    if (entry.isSymbolicLink()) throw new Error(`${path}: refusing to follow a symlink in the generated surface`);
+    if (entry.isDirectory()) files.push(...readOutput(root, path));
+    else if (entry.isFile()) files.push({ path, raw: readFileSync(join(root, path), 'utf8') });
+    else throw new Error(`${path}: unsupported file type in generated surface`);
+  }
+  return files;
+}
+
+/** @param {Source} source @param {string[]} warnings */
+function renderSkill(source, warnings) {
+  const projected = toPortableFrontmatter({ ...source.fm, name: source.name }, source.name);
+  warnings.push(...projected.warnings);
+  const lines = [
+    '---',
+    yaml.dump(projected.fm, { lineWidth: -1, noRefs: true }).trimEnd(),
+    '---',
+    '',
+    `<!-- ${MARKER} -->`,
+    '',
+    `# ${source.name}`,
+    '',
+    `Read [\`${source.path}\`](../../../${source.path}) in full before taking any action, then follow its complete workflow.`,
+    'The linked document is authoritative, including its prechecks, argument rules, and stop conditions.',
+    '',
+    'Resolve this link relative to this SKILL.md, not the project working directory. The plugin root is three directories above this file. Resolve package paths such as `skills/` and `scripts/` from that root; resolve relative links inside the canonical document from its own directory. Keep the user’s project as the target of project operations.',
+  ];
+  if (source.command) lines.push(
+    '',
+    '`$ARGUMENTS` means the trailing user input after the selected command skill, or an empty string when absent. Preserve flags, quoted text, and Unicode as data. Do not perform global substitution in the command document, shell expansion on the argument string, or execution of that string as shell code. When the workflow needs a command, pass its arguments through structured tool parameters or safely quoted individual arguments.',
+    '',
+    'Read the full command before invoking an internal skill. An instruction to invoke a skill (including `session-orchestrator:<name>` or the `Skill` tool) means read and follow the canonical `skills/<name>/SKILL.md` beneath the plugin root. Do not redispatch the public command adapter: a same-named command and internal skill are distinct documents, and redispatch would recurse.',
+  );
+  lines.push('', 'Regenerate with `node scripts/generate-codex-skills.mjs`.', '');
+  return lines.join('\n');
+}
+
+/**
+ * @param {{pluginRoot: string, check?: boolean}} options
+ * @returns {{ok: boolean, skills: string[], files: string[], written: string[], drift: string[], warnings: string[], errors: string[]}}
+ */
+export function generateCodexSurface({ pluginRoot, check = false }) {
+  const result = { ok: true, skills: [], files: [], written: [], drift: [], warnings: [], errors: [] };
+  try {
+    if (!existsSync(pluginRoot) || !statSync(pluginRoot).isDirectory()) throw new Error(`${pluginRoot}: plugin root must be an existing directory`);
+    const sources = new Map(readSources(pluginRoot).map((source) => [source.name, source]));
+    result.skills = [...sources.keys()].sort();
+    const artifacts = new Map();
+    for (const name of result.skills) {
+      const source = sources.get(name);
+      artifacts.set(`${OUTPUT}/${name}/SKILL.md`, renderSkill(source, result.warnings));
+      if (source.policy !== undefined) artifacts.set(`${OUTPUT}/${name}/agents/openai.yaml`, [
+        `# ${MARKER}`,
+        yaml.dump({
+          interface: { display_name: name },
+          policy: { allow_implicit_invocation: source.policy },
+        }, { lineWidth: -1, noRefs: true }).trimEnd(),
+        '',
+      ].join('\n'));
+    }
+    result.files = [...artifacts.keys()];
+
+    // Preflight every destination and existing artifact before the first mutation.
+    // A conflict or invalid source must never leave a partly refreshed surface.
+    for (const path of [`${OUTPUT}/.preflight`, ...result.files]) {
+      const destination = join(pluginRoot, path);
+      if (artifacts.has(path) && existsSync(destination) && !lstatSync(destination).isFile()) {
+        throw new Error(`${path}: generated artifact must be a regular file`);
+      }
+      let parent = dirname(path);
+      while (parent !== '.') {
+        const absolute = join(pluginRoot, parent);
+        if (existsSync(absolute) && (!lstatSync(absolute).isDirectory() || lstatSync(absolute).isSymbolicLink())) {
+          throw new Error(`${parent}: generated directory must be a real directory`);
+        }
+        parent = dirname(parent);
+      }
+    }
+    const obsolete = [];
+    for (const { path, raw } of readOutput(pluginRoot)) {
+      if (artifacts.has(path)) {
+        if (!isOwned(path, raw)) throw new Error(`${path}: refusing to overwrite an unrelated artifact without the generated marker`);
+      } else if (isOwned(path, raw)) obsolete.push(path);
+      else result.warnings.push(`${path}: retained unrelated file`);
+    }
+
+    for (const [path, content] of artifacts) {
+      const absolute = join(pluginRoot, path);
+      if (existsSync(absolute) && readFileSync(absolute, 'utf8') === content) continue;
+      if (check) result.drift.push(`${path} is missing or stale`);
+      else {
+        mkdirSync(dirname(absolute), { recursive: true });
+        writeFileSync(absolute, content);
+        result.written.push(path);
+      }
+    }
+    for (const path of obsolete) {
+      if (check) result.drift.push(`${path} is obsolete`);
+      else {
+        unlinkSync(join(pluginRoot, path));
+        result.written.push(`removed ${path}`);
+        let parent = dirname(path);
+        while (parent !== OUTPUT && readdirSync(join(pluginRoot, parent)).length === 0) {
+          rmdirSync(join(pluginRoot, parent));
+          parent = dirname(parent);
+        }
+      }
+    }
+  } catch (error) {
+    result.errors.push(error.message);
+  }
+  result.ok = result.errors.length === 0 && result.drift.length === 0;
+  return result;
+}
+
+function runCli() {
+  let pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  let check = false;
+  let json = false;
+  const args = process.argv.slice(2);
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--check') check = true;
+    else if (args[i] === '--json') json = true;
+    else if (args[i] === '--plugin-root' && args[i + 1]) pluginRoot = resolve(args[++i]);
+    else if (args[i] === '--help') {
+      process.stdout.write('Usage: generate-codex-skills.mjs [--plugin-root <dir>] [--check] [--json]\n');
+      return;
+    } else {
+      process.stderr.write(`Unknown or incomplete argument: ${args[i]}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const result = generateCodexSurface({ pluginRoot, check });
+  if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else {
+    process.stdout.write(`codex-surface: ${result.files.length} artefact(s), ${result.ok ? (check ? 'in sync' : 'generated') : 'failed'}\n`);
+    for (const message of [...result.errors, ...result.drift, ...result.warnings]) process.stderr.write(`${message}\n`);
+  }
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) runCli();

package/scripts/generate-hook-import-set.mjs

@@ -17,8 +17,11 @@
  *
  * Usage:
  *   node scripts/generate-hook-import-set.mjs [--plugin-root <dir>] [--out <file>] [--check]
+ *   node scripts/generate-hook-import-set.mjs --help
  *
- * Exit codes: 0 = written / in sync; 1 = drift (with --check) or usage error.
+ * Exit codes: 0 = written / in sync (or --help); 1 = drift (with --check);
+ * 2 = usage error (unknown flag, or a valued flag missing its value) — the
+ * write is NEVER performed on a usage error.
  */
 
 import { readFileSync, writeFileSync, existsSync, statSync, realpathSync } from 'node:fs';
@@ -178,19 +181,59 @@ export function buildArtifact(pluginRoot) {
 // CLI
 // ---------------------------------------------------------------------------
 
+const USAGE = [
+  'Usage: node scripts/generate-hook-import-set.mjs [--plugin-root <dir>] [--out <file>] [--check]',
+  '',
+  '  --plugin-root <dir>  repository/plugin root to crawl (default: the repo this script lives in)',
+  '  --out <file>         artefact path (default: <plugin-root>/hooks/_lib/hook-import-set.json)',
+  '  --check              re-crawl and diff against the committed artefact instead of writing',
+  '  --help, -h           print this help',
+  '',
+  'Exit codes: 0 = written / in sync; 1 = drift (with --check); 2 = usage error.',
+].join('\n');
+
 /**
  * @param {string[]} argv
  * @returns {number} process exit code
  */
 export function main(argv) {
   const args = argv.slice(2);
-  const flag = (name) => {
-    const i = args.indexOf(name);
-    return i >= 0 && i + 1 < args.length ? args[i + 1] : null;
-  };
-  const pluginRoot = path.resolve(flag('--plugin-root') ?? path.resolve(import.meta.dirname, '..'));
-  const out = path.resolve(flag('--out') ?? path.join(pluginRoot, 'hooks', '_lib', 'hook-import-set.json'));
-  const check = args.includes('--check');
+
+  /** @type {{'--plugin-root': string|null, '--out': string|null}} */
+  const valued = { '--plugin-root': null, '--out': null };
+  let check = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--help' || arg === '-h') {
+      process.stdout.write(`${USAGE}\n`);
+      return 0;
+    }
+    if (arg === '--check') {
+      check = true;
+      continue;
+    }
+    if (arg === '--plugin-root' || arg === '--out') {
+      // A valued flag whose value is missing — or whose "value" is the next FLAG
+      // — is a usage error, not a silent default. Without the leading-dash test,
+      // `--out --check` swallows `--check` as the artefact path: checking is
+      // disabled, the WRITE branch runs, and a file literally named `--check`
+      // lands in the cwd.
+      const value = args[i + 1];
+      if (value === undefined || value.startsWith('-')) {
+        process.stderr.write(`✗ hook-import-set: ${arg} requires a value\n${USAGE}\n`);
+        return 2;
+      }
+      valued[arg] = value;
+      i += 1;
+      continue;
+    }
+    process.stderr.write(`✗ hook-import-set: unknown argument "${arg}"\n${USAGE}\n`);
+    return 2;
+  }
+
+  const pluginRoot = path.resolve(valued['--plugin-root'] ?? path.resolve(import.meta.dirname, '..'));
+  const out = path.resolve(valued['--out'] ?? path.join(pluginRoot, 'hooks', '_lib', 'hook-import-set.json'));
 
   const fresh = buildArtifact(pluginRoot);
 

package/scripts/lib/codex/plugin-contract.mjs

@@ -7,6 +7,7 @@ const MANIFEST_KEYS = new Set([
   'description',
   'keywords',
   'skills',
+  'commands',
   'mcpServers',
   'apps',
   'hooks',
@@ -206,6 +207,11 @@ function validateManifest(manifest, root, expectedBaseVersion, errors) {
   validatePathCollection(manifest.skills, '$.manifest.skills', 'directory', root, errors, {
     required: true,
   });
+  // Native [] suppresses Codex's conventional commands/ fallback. Nonempty
+  // paths would register automatic aliases beside our generated skill surface.
+  if (Object.hasOwn(manifest, 'commands') && (!Array.isArray(manifest.commands) || manifest.commands.length !== 0)) {
+    addError(errors, '$.manifest.commands', 'disabled-command-discovery', 'commands must be an empty array to disable automatic command conversion');
+  }
   validateMcpServers(manifest.mcpServers, root, errors);
   if (manifest.apps !== undefined) {
     validateContractPath(manifest.apps, '$.manifest.apps', 'file', root, errors);

package/scripts/lib/config/host-paths.mjs

@@ -40,17 +40,33 @@ const ENV_KEYS = /** @type {const} */ ({
  * merged with defaults, so a real owner.yaml without a `paths:` section yields
  * `ownerConfig.paths === undefined`. Callers must read defensively.
  *
- * @param {{ env?: Record<string, string|undefined>, ownerLoader?: () => { config: object } }} [opts]
- * @returns {{ ownerConfig: object|undefined, env: Record<string, string|undefined> }}
+ * HEALTH PASSTHROUGH (#1251): the owner loader reports HOW its result came about
+ * (`source`, `reason`, `droppedSections`). Discarding those forced callers that
+ * need them — CP11 in check-owner-leakage.mjs is the live one — to load owner.yaml
+ * a SECOND time just to see the health of the load this function already did. They
+ * are passed through verbatim; `ownerConfig` and `env` keep their exact prior
+ * meaning, so callers reading only those two (scripts/lib/config.mjs,
+ * scripts/lib/vault-mirror/namespace.mjs) are unaffected. On a throwing loader all
+ * three health fields stay `undefined`, exactly like `ownerConfig`.
+ *
+ * @param {{ env?: Record<string, string|undefined>, ownerLoader?: () => { config: object, source?: string, reason?: string, droppedSections?: Array<{section: string, errors: string[]}> } }} [opts]
+ * @returns {{ ownerConfig: object|undefined, env: Record<string, string|undefined>, source: string|undefined, reason: string|undefined, droppedSections: Array<{section: string, errors: string[]}>|undefined }}
  */
 export function loadHostPaths({ env = process.env, ownerLoader = loadOwnerConfig } = {}) {
   let ownerConfig;
+  let source;
+  let reason;
+  let droppedSections;
   try {
-    ownerConfig = ownerLoader().config;
+    const loaded = ownerLoader();
+    ownerConfig = loaded?.config;
+    source = loaded?.source;
+    reason = loaded?.reason;
+    droppedSections = loaded?.droppedSections;
   } catch {
     ownerConfig = undefined;
   }
-  return { ownerConfig, env };
+  return { ownerConfig, env, source, reason, droppedSections };
 }
 
 /**

package/scripts/lib/events.mjs

@@ -27,8 +27,8 @@
  *   3. **Never a peer's id (#1123).** A shared working copy means
  *      `session.lock` can name a PEER session that won the acquire race. The
  *      lock alone therefore does not prove ownership; the fill happens only
- *      when a PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID`, or a hook payload's
- *      `session_id`) equals the lock's raw `session_id`. STATE.md is NOT a
+ *      when a confirmed native PROCESS-LOCAL id (`CLAUDE_CODE_SESSION_ID` or
+ *      `CODEX_THREAD_ID`) equals the lock's raw `session_id`. STATE.md is NOT a
  *      witness here (#1177 FX1): it is a shared working-copy file written by
  *      the lock holder, so under a peer-owned lock both agreed about the peer
  *      and the union stamped the peer's ids. See {@link attributionForRecord}.
@@ -124,7 +124,7 @@ const STATE_DIR_CANDIDATES = ['.claude', '.codex', '.cursor', '.pi'];
  * when one exists it decides alone.**
  *
  *   - No lock (CI, a bare script) → `{}`. Nothing to attribute to.
- *   - No process-local id (`CLAUDE_CODE_SESSION_ID` absent) → `{}`. Ownership is
+ *   - No confirmed process-local id (absent or ambiguous native env) → `{}`. Ownership is
  *     UNPROVEN, and an unproven attribution is exactly the peer-id write #1123
  *     forbids; an absent key costs a correlation, a wrong key costs a false one.
  *   - A process-local id that equals the lock's raw `session_id` → fill BOTH

package/scripts/lib/gates/gate-full.mjs

@@ -72,9 +72,13 @@ const testCounts =
 // no name is what made the 2026-09-06 pre-push block unusable —
 // `files_failed: 1` out of 662, and reconstructing WHICH file cost a manual
 // re-materialisation of the tracked tree. An EMPTY array here is meaningful and
-// is NOT the absent case: it says the file-level summary was parsed and no path
-// could be read out of it (a non-vitest reporter, a truncated capture), which
-// is a parser gap worth seeing — the unmeasured case is the absent key.
+// is NOT the absent case: it means vitest reported file-level failures but the
+// file-name parser (`extractFailedTestFiles`) matched none of them out of the
+// captured output — a parser gap worth seeing. The consumer,
+// `failedFilesFromGateStdout()` in `scripts/run-quality-gate.mjs`, normalizes
+// this `[]` to `null` (same as the true-absent case) before it reaches its own
+// caller — so this array's "parsed but empty" distinction is visible here, in
+// this envelope, and nowhere downstream.
 const failedTestFiles = testResult.status === 'fail'
   ? extractFailedTestFiles(testResult.fullOutput ?? testResult.output ?? '')
   : [];

package/scripts/lib/owner-config-banner.mjs

@@ -36,14 +36,12 @@
  *  - Issue #820.
  */
 
-import { loadOwnerConfig, resolveOwnerYamlPath, getDefaults } from './owner-yaml.mjs';
-
-/**
- * OPTIONAL object sections (mirrors `owner-yaml.mjs`'s internal, unexported
- * `OPTIONAL_OBJECT_SECTIONS`) — the only sections the #1244 discard-branch
- * merge rule can carry through a whole-file discard.
- */
-const OPTIONAL_OBJECT_SECTION_NAMES = /** @type {const} */ (['paths', 'dispatcher']);
+import {
+  loadOwnerConfig,
+  resolveOwnerYamlPath,
+  getDefaults,
+  OPTIONAL_OBJECT_SECTIONS,
+} from './owner-yaml.mjs';
 
 /**
  * Format a `{ section, errors }` entry into a short `"name" (first error)` tag.
@@ -111,7 +109,7 @@ export function checkOwnerConfig({ loader = loadOwnerConfig } = {}) {
       const survivedSections = [];
       if (result.config && typeof result.config === 'object') {
         const defaults = getDefaults();
-        for (const name of OPTIONAL_OBJECT_SECTION_NAMES) {
+        for (const name of OPTIONAL_OBJECT_SECTIONS) {
           if (JSON.stringify(result.config[name]) !== JSON.stringify(defaults[name])) {
             survivedSections.push(name);
           }

package/scripts/lib/owner-yaml.mjs

@@ -196,8 +196,15 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * OPTIONAL object sections (#820) — a malformed entry is replaced by its
  * `getDefaults()` value and reported via `droppedSections` + a stderr WARN,
  * but does NOT discard the rest of the file.
+ *
+ * Exported (#1262.4) as the SSOT for consumers that must iterate exactly these
+ * sections — currently `scripts/lib/owner-config-banner.mjs`, which derived the
+ * #1244 "survived a whole-file discard" set from a hand-mirrored local copy.
+ * Frozen so a consumer cannot mutate the shared array.
  */
-const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (['paths', 'dispatcher']);
+export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
+  Object.freeze(['paths', 'dispatcher'])
+);
 
 /**
  * OPTIONAL list sections (#820) — malformed entries are passed through