session-orchestrator 4.0.0 → 4.0.1

package/docs/components.md

@@ -52,9 +52,10 @@ Codex uses the curated six-event project subset `SessionStart`, `PreToolUse`, `P
 
 - **Output Styles (3):** `session-report`, `wave-summary`, `finding-report`.
 - **Policy & rules:** `.orchestrator/policy/blocked-commands.json` (destructive-command rules); `.claude/rules/parallel-sessions.md` (PSA-001..PSA-004).
-- **Codex:** `.codex-plugin/plugin.json` (tracked `+codex.<UTC timestamp>` version), compatibility config, agent role definitions, and the public marketplace/add/list lifecycle implemented by `scripts/codex-install.mjs`. Every run refreshes via `plugin add`; hook trust remains an operator decision in a fresh task through `/hooks`.
+- **Codex:** `.codex-plugin/plugin.json` (tracked `+codex.<UTC timestamp>` version), generated command and skill entrypoints under `.codex-plugin/skills/`, compatibility config, agent role definitions, and the public marketplace/add/list lifecycle implemented by `scripts/codex-install.mjs`. `scripts/generate-codex-skills.mjs` produces the name union with commands taking precedence; [Codex usage](codex-setup.md#usage) explains selection. Every installer run refreshes via `plugin add`; hook trust remains an operator decision in a fresh task through `/hooks`.
+- **Cursor:** `.cursor-plugin/plugin.json` registers canonical skills and `.mcp.json` using Cursor's native manifest format. Additional native component discovery is explicitly disabled; `scripts/cursor-install.mjs` supplies the existing command and hook adapters. The former standard root manifest was moved to prevent [Codex manifest interception](codex-setup.md#manifest-compatibility).
 - **Pi:** `package.json` `pi` manifest, `pi/extensions/session-orchestrator.ts` bridge, `hooks/hooks-pi.json`, `scripts/pi-install.mjs`.
-- **Portable cross-harness surface (generated, never hand-edited):** root `AGENTS.md` (byte-identical copy of `CLAUDE.md`), root `plugin.json` ([agent-plugins.org](https://agent-plugins.org) 1.0.0 schema), and `.agents/skills/<name>/SKILL.md` — a mirror of all 43 skills carrying only spec-legal frontmatter plus a pointer body (progressive disclosure; the mirror never duplicates the canonical instructions). Written by `scripts/generate-agents-skills.mjs`, drift-checked via its `--check` form inside `scripts/validate-plugin.mjs`.
+- **Portable cross-harness surface (generated, never hand-edited):** root `AGENTS.md` (byte-identical copy of `CLAUDE.md`) and `.agents/skills/<name>/SKILL.md` — mirrors carrying only spec-legal frontmatter plus a pointer body. These two surfaces are written by `scripts/generate-agents-skills.mjs` and drift-checked via its `--check` form inside `scripts/validate-plugin.mjs`. Native plugin manifests are maintained separately, with versions updated by `scripts/release.mjs`.
 - **Scripts:** deterministic CLI tools (parse-config, run-quality-gate, validate-wave-scope, validate-plugin, token-audit, autopilot) plus shared lib under `scripts/lib/*.mjs`, all covered by the vitest suite.
 
 ## `/harness-audit` — Anthropic large-codebase rubric

package/docs/instruction-delivery.md

@@ -688,11 +688,18 @@ agentskills.io permits outside Claude Code (`name`, `description`, `license`,
 `skills/<name>/SKILL.md`, never a copy of it — progressive disclosure keeps the
 whole mirror at 47,380 bytes across 43 files.
 
-Root `plugin.json` (agent-plugins.org 1.0.0) is the third artefact of the same
-surface. It is the **third** manifest carrying a version, alongside
-`.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`, while the release
-script bumps only `package.json` — `scripts/lib/validate/check-agents-skills.mjs`
-asserts all of them agree.
+These are the two artifacts emitted by `scripts/generate-agents-skills.mjs`. Plugin
+manifests are maintained separately under `.claude-plugin/`, `.codex-plugin/` and
+`.cursor-plugin/`; `scripts/release.mjs` updates their versions with `package.json`.
+The initial 4.0.0 standard root `plugin.json` was moved to the native Cursor location
+because it intercepted Codex's skill path and version selection; see
+[Codex manifest compatibility](codex-setup.md#manifest-compatibility).
+
+Codex has a separate generated surface: `scripts/generate-codex-skills.mjs` writes
+`.codex-plugin/skills/` from the union of canonical command and skill names. Commands
+win same-name overlaps, and each adapter reads the canonical document before dispatch.
+The portable `.agents/skills/` mirrors continue to reference canonical skills directly;
+they do not replace the installed Codex command entrypoints.
 
 ## Learnings Index (selected for your file scope)
 

package/docs/migration-v4.md

@@ -24,7 +24,7 @@ change list: [CHANGELOG.md](../CHANGELOG.md).
 | `.claude/rules/` | 61 files (43 generated) | 26 files (43 generated → 8 thematic) |
 | Turn-stop event | `orchestrator.session.stopped` | `orchestrator.turn.stopped` (both emitted until 2027-03-06) |
 | Telemetry field | `fleet` | `fleet_self_declared` (both sent until 2027-03-06) |
-| Cross-harness manifest | none | root `AGENTS.md` + root `plugin.json` + `.agents/skills/` |
+| Cross-harness integration | native manifests | generated root `AGENTS.md` + `.agents/skills/`; separate Claude, Codex and Cursor manifests |
 | Session shapes | `housekeeping` / `feature` / `deep` | unchanged, plus the `ultradeep` PROFILE over `deep` |
 | Runtime | Node 24+, npm | unchanged |
 
@@ -126,6 +126,17 @@ New in 4.0.0 and relevant here: this repository now ships a **root `AGENTS.md`**
 instructions from `AGENTS.md` found nothing in this repo. If you keep your own
 `AGENTS.md`, nothing changes for you.
 
+The Codex command integration uses generated skills: search for `go` or `close` in the
+picker and select the **Session Orchestrator** entry, or invoke `$session-orchestrator:go` and
+`$session-orchestrator:close`. Refresh the installed plugin as above and restart Codex if
+the new entries do not appear. The native `/goal` command is separate.
+
+The initial 4.0.0 root Agent Plugins `plugin.json` has been replaced by a native Cursor
+manifest. Read-only probes on Codex 0.153.3 and desktop runtime 0.153.4 showed that the
+standard root manifest overrides Codex's declared skill directory and cache version.
+The separate native manifests avoid that conflict; details are in
+[Codex manifest compatibility](codex-setup.md#manifest-compatibility).
+
 ### 3c. Cursor IDE
 
 ```bash
@@ -145,8 +156,12 @@ But the three retired commands do **not** disappear from `.cursor/commands/` on
 `hooks.json` written before 4.0.0 is never synchronised with a new hook event automatically.
 Both need the manual step in § 5 ("Cursor still shows the removed commands") below.
 
-A root `plugin.json` following the [agent-plugins.org](https://agent-plugins.org) 1.0.0
-schema now ships as well, for Cursor's plugin system.
+Cursor's plugin metadata now lives at `.cursor-plugin/plugin.json`, replacing the initial
+4.0.0 standard root `plugin.json`. The native manifest retains the canonical skills and
+MCP paths and explicitly disables additional component discovery; the installer above
+continues to supply commands and hooks. The shape follows the
+[official Cursor manifest reference](https://cursor.com/docs/reference/plugins); native
+Cursor loading was not runtime-tested during this compatibility repair.
 
 ### 3d. Pi
 
@@ -260,6 +275,11 @@ for f in autopilot-multi contract-version-bump journey-audit; do
 done
 ```
 
+`[ -L "$p" ]` checks the destination's TYPE, not who created it — it removes any symlink at that
+path regardless of origin. If you separately symlinked your own command under one of these three
+names, this recipe deletes that symlink too; a regular (non-symlink) file is the only thing it
+leaves untouched.
+
 Then restart Cursor. Same story for `.cursor/hooks.json`: the installer skips it outright once
 it exists (`:139-140`), so a `hooks.json` written before 4.0.0 is never re-synced with a new hook
 event automatically — re-check it by hand (diff it against a fresh `node scripts/cursor-install.mjs`
@@ -317,12 +337,16 @@ What you get back, and what you do not:
 - **The removed skills, commands and scripts come back with the checkout.** They were deleted
   from the repository, not from your disk history.
 - **What does NOT roll back automatically** is anything an installer wrote into YOUR project:
-  `.cursor/commands/`, `.cursor/hooks.json`, Pi settings. Both `cursor-install.mjs` and
-  `pi-install.mjs` skip any destination that already exists — a symlink or a file
-  (`scripts/cursor-install.mjs:69-73`; the `hooks.json` writer at `:139-140`) — so re-running
-  the installer from the 3.24.0 checkout only **adds** files missing from your project. It does
-  not restore a symlink you removed yourself, and it does not resync an existing `hooks.json` or
-  Pi settings file. To get those back: remove the stale file first (§ "Cursor still shows the
+  `.cursor/commands/`, `.cursor/hooks.json`, Pi settings. The two installers behave
+  differently: `cursor-install.mjs` skips any destination that already exists — a symlink or a
+  file (`scripts/cursor-install.mjs:69-73`; the `hooks.json` writer at `:139-140`) — and
+  re-creates only the ones that are MISSING, so re-running it from the 3.24.0 checkout only
+  **adds** command links missing from your project; it does not restore a link you removed
+  yourself and does not resync an existing `hooks.json`.
+  `pi-install.mjs --settings-only` **does** rewrite the Pi settings file: it reads it, upserts
+  this package's entry and writes it back (`scripts/pi-install.mjs` `upsertPackage` /
+  `writeSettings`), so re-running it from the 3.24.0 checkout re-points Pi at that checkout.
+  For Cursor, to get a removed link back: delete the stale file first (§ "Cursor still shows the
   removed commands" has a safe, symlink-only removal recipe), then re-run the installer with
   your project path, as shown above.
 

package/hooks/_lib/hook-import-set.json

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-09-06T19:04:31.959Z",
-  "head": "bc49301b3eed05b5b235376ecec4a931522d26bf",
+  "generated_at": "2026-09-07T18:36:32.142Z",
+  "head": "a244b8707aa5bb650673fce2e6cf548564b43e58",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -1274,7 +1274,8 @@
       "file": "scripts/lib/session-schema/constants.mjs",
       "reachable_from": [
         "on-session-end.mjs",
-        "on-session-start.mjs"
+        "on-session-start.mjs",
+        "skill-invocation-telemetry.mjs"
       ]
     },
     {

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.0.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.0.1 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v4.0.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v4.0.1 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

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.0.1",
   "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/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/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 ?? '')
   : [];