session-orchestrator 5.7.0 → 5.9.0

package/scripts/backfill-sessions.mjs

@@ -28,8 +28,9 @@
  *   {"mode":"dry-run|apply|mark-deprecated-only","total":N,"rewritten":N,"deprecated":N,"unchanged":N,"backup":"<path>|null"}
  */
 
-import { readFileSync, writeFileSync, renameSync, copyFileSync, existsSync } from 'node:fs';
-import { join, dirname, basename } from 'node:path';
+import { readFileSync, copyFileSync, existsSync } from 'node:fs';
+import { basename } from 'node:path';
+import { atomicWriteWithBackup, envelopeToError } from './lib/io.mjs';
 import { validateSession, normalizeSession, ValidationError } from './lib/session-schema.mjs';
 
 const DEFAULT_FILE = '.orchestrator/metrics/sessions.jsonl';
@@ -253,17 +254,18 @@ async function main() {
   // by a pre-write copy-to-backup. This eliminates the crash window where the
   // canonical path could be briefly missing if the rename dance were split:
   //   1. copyFileSync: canonical → .bak-<ISO>  (backup; canonical still present)
-  //   2. writeFileSync: rewritten → tmp        (new content; canonical still present)
-  //   3. renameSync: tmp → canonical           (atomic replace per POSIX)
+  //   2+3. atomicWriteWithBackup: rewritten → tmp → rename over canonical
+  //        (atomic replace per POSIX; the helper unlinks its tmp on failure)
   // At every point between steps, the canonical file exists and holds either
   // the old content or the new content. Recovery artifact: .bak-<ISO>.
   const iso = new Date().toISOString().replace(/[:.]/g, '-');
   const backupPath = `${args.file}.bak-${iso}`;
-  const tmpPath = join(dirname(args.file), `.${basename(args.file)}.tmp-${process.pid}`);
   try {
     copyFileSync(args.file, backupPath);
-    writeFileSync(tmpPath, rewritten.join('\n') + '\n', 'utf8');
-    renameSync(tmpPath, args.file);
+    const res = atomicWriteWithBackup(args.file, rewritten.join('\n') + '\n', {
+      tmpPrefix: `.${basename(args.file)}.tmp`,
+    });
+    if (!res.ok) throw envelopeToError(res);
     summary.backup = backupPath;
   } catch (err) {
     const recoveryHint = existsSync(backupPath)

package/scripts/codex-install.mjs

@@ -2,22 +2,31 @@
 /**
  * Install Session Orchestrator through Codex's public plugin lifecycle.
  *
+ * The marketplace reads the host-local packed copy (`npm pack` of this clone,
+ * with runtime dependencies, under ~/.cache/session-orchestrator/plugin-package),
+ * never the clone itself: a marketplace on the working checkout copied all of
+ * it into the Codex plugin cache — 15742 files, `.env.local`, `.orchestrator/`
+ * and `tests/` included (#1518, measured 2026-10-03).
+ *
  * Exit codes:
  *   0 — installed, enabled, and verified
  *   1 — argument or user-correctable environment error
  *   2 — system, upstream command/JSON, or runtime postcondition failure
  */
 
-import { readFileSync } from 'node:fs';
+import { readFileSync, realpathSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
 import { validateCodexPluginContract } from './lib/codex/plugin-contract.mjs';
+import { resolveStageDir, stagePackage } from './lib/plugin-package-stage.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = path.dirname(__filename);
 const SO_ROOT = path.dirname(SCRIPT_DIR);
+const STAGE_DIR = resolveStageDir();
 
 const MIN_CODEX_VERSION = [0, 144, 4];
 const MARKETPLACE_NAME = 'kanevry';
@@ -166,27 +175,28 @@ function requireStableFeature(features, name) {
   }
 }
 
-function readLocalJson(relativePath, label) {
+function readLocalJson(relativePath, label, root = SO_ROOT) {
   try {
-    return JSON.parse(readFileSync(path.join(SO_ROOT, relativePath), 'utf8'));
+    return JSON.parse(readFileSync(path.join(root, relativePath), 'utf8'));
   } catch (error) {
     throw new InstallerError(`Cannot read valid ${label}: ${error.message}`);
   }
 }
 
-function readBaseVersion() {
-  const packageJson = readLocalJson('package.json', 'package.json');
+function readBaseVersion(root = SO_ROOT) {
+  const packageJson = readLocalJson('package.json', 'package.json', root);
   if (typeof packageJson.version !== 'string' || packageJson.version.trim() === '') {
     throw new InstallerError('package.json must contain a non-empty version string.');
   }
   return packageJson.version;
 }
 
-function validateLocalContract() {
-  const expectedBaseVersion = readBaseVersion();
-  const manifest = readLocalJson(path.join('.codex-plugin', 'plugin.json'), 'Codex plugin manifest');
+/** Validates the plugin Codex will actually install: the staged packed copy. */
+function validateLocalContract(root) {
+  const expectedBaseVersion = readBaseVersion(root);
+  const manifest = readLocalJson(path.join('.codex-plugin', 'plugin.json'), 'Codex plugin manifest', root);
   const verdict = validateCodexPluginContract({
-    pluginRoot: SO_ROOT,
+    pluginRoot: root,
     expectedBaseVersion,
   });
 
@@ -210,12 +220,34 @@ function requireArray(value, label) {
   return value;
 }
 
+const realOrResolved = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+
 function sameLocalPath(left, right) {
-  return typeof left === 'string' && path.resolve(left) === path.resolve(right);
+  return typeof left === 'string' && realOrResolved(left) === realOrResolved(right);
+}
+
+function marketplaceSource(entry) {
+  return { sourceType: entry.marketplaceSource?.sourceType, source: entry.marketplaceSource?.source ?? entry.root };
 }
 
 function assertMarketplaceCompatible(payload) {
   const marketplaces = requireArray(payload.marketplaces, 'marketplaces');
+  // Any local marketplace on the working checkout copies all of it into the
+  // plugin cache (#1518) — refuse, naming the one-time re-registration.
+  const onCheckout = marketplaces.filter((entry) => {
+    if (!isRecord(entry)) return false;
+    const { sourceType, source } = marketplaceSource(entry);
+    return sourceType === 'local' && sameLocalPath(source, SO_ROOT);
+  });
+  if (onCheckout.length > 0) {
+    const removes = onCheckout.map((entry) => `codex plugin marketplace remove ${String(entry.name)}`).join(' && ');
+    throw new InstallerError(
+      `Marketplace ${onCheckout.map((entry) => `'${String(entry.name)}'`).join(', ')} reads this clone '${SO_ROOT}' — `
+      + `the Codex plugin cache becomes a full copy incl. .env.local (#1518). Re-register once: `
+      + `${removes} && node scripts/codex-install.mjs (it adds the packed copy at '${STAGE_DIR}').`,
+      ERROR_CATEGORIES.USER,
+    );
+  }
   const matches = marketplaces.filter((entry) => isRecord(entry) && entry.name === MARKETPLACE_NAME);
 
   if (matches.length > 1) {
@@ -227,28 +259,61 @@ function assertMarketplaceCompatible(payload) {
   }
   if (matches.length === 0) return;
 
-  const existing = matches[0];
-  const sourceType = existing.marketplaceSource?.sourceType;
-  const source = existing.marketplaceSource?.source ?? existing.root;
-  if (sourceType !== 'local' || !sameLocalPath(source, SO_ROOT)) {
+  const { sourceType, source } = marketplaceSource(matches[0]);
+  if (sourceType !== 'local' || !sameLocalPath(source, STAGE_DIR)) {
     throw new InstallerError(
       `Marketplace '${MARKETPLACE_NAME}' already points to '${String(source)}' (${String(sourceType)}), `
-      + `not '${SO_ROOT}'. Resolve the conflict manually after reviewing `
+      + `not '${STAGE_DIR}'. Resolve the conflict manually after reviewing `
       + `'codex plugin marketplace list --json'; this installer will not remove or replace it.`,
       ERROR_CATEGORIES.USER,
     );
   }
 }
 
+/**
+ * Codex's personal marketplace (`~/.agents/plugins/marketplace.json`, paths
+ * relative to the home dir) may list a plugin that resolves to this clone — on
+ * the reference host `~/plugins/session-orchestrator` is a symlink to the main
+ * checkout, and the resulting `session-orchestrator@local` cache held
+ * `.env.local` (#1518). That catalog belongs to the operator, so this is a
+ * read-only hint naming the cleanup, never a refusal or an edit.
+ */
+function printPersonalMarketplaceHint(json) {
+  const home = os.homedir();
+  const catalog = path.join(home, '.agents', 'plugins', 'marketplace.json');
+  let plugins;
+  try {
+    plugins = JSON.parse(readFileSync(catalog, 'utf8')).plugins;
+  } catch {
+    return;
+  }
+  if (!Array.isArray(plugins)) return;
+  const hits = plugins.filter((plugin) => (
+    isRecord(plugin) && typeof plugin.source?.path === 'string'
+    && sameLocalPath(path.resolve(home, plugin.source.path), SO_ROOT)
+  ));
+  for (const plugin of hits) {
+    const linked = path.resolve(home, plugin.source.path);
+    const message = `Hint: ${catalog} lists '${String(plugin.name)}' at '${linked}', which resolves to this clone — `
+      + `its Codex cache copies the whole checkout incl. .env.local (#1518). Cleanup, once: `
+      + `(1) let this installer finish (it removes ${PLUGIN_NAME}@local after a healthy install); `
+      + `(2) remove that entry from ${catalog}; (3) delete the link '${linked}' if it is a symlink; `
+      + `(4) after restarting Codex, delete the old cache folders under ~/.codex/plugins/cache/local/ `
+      + `(${PLUGIN_NAME}/ and any plugin-install-*/ or plugin-backup-*/ holding ${PLUGIN_NAME}).`;
+    if (json) process.stderr.write(`${message}\n`);
+    else progress(json, message);
+  }
+}
+
 function assertMarketplaceAddResult(payload) {
   if (payload.marketplaceName !== MARKETPLACE_NAME) {
     throw new InstallerError(
       `Marketplace add returned '${String(payload.marketplaceName)}', expected '${MARKETPLACE_NAME}'.`,
     );
   }
-  if (!sameLocalPath(payload.installedRoot, SO_ROOT)) {
+  if (!sameLocalPath(payload.installedRoot, STAGE_DIR)) {
     throw new InstallerError(
-      `Marketplace add returned root '${String(payload.installedRoot)}', expected '${SO_ROOT}'.`,
+      `Marketplace add returned root '${String(payload.installedRoot)}', expected '${STAGE_DIR}'.`,
     );
   }
   if (typeof payload.alreadyAdded !== 'boolean') {
@@ -336,18 +401,38 @@ function install({ json }) {
   requireStableFeature(features, 'hooks');
   progress(json, 'Features: plugins stable true; hooks stable true');
 
-  const expectedVersion = validateLocalContract();
-  progress(json, `Local contract: valid (${expectedVersion})`);
-
   const marketplaceList = runCodexJson(
     ['plugin', 'marketplace', 'list', '--json'],
     'Marketplace list',
   );
+  // Checked before staging: a refused install must not replace the stage dir.
   assertMarketplaceCompatible(marketplaceList);
 
-  progress(json, `Marketplace: adding '${SO_ROOT}'`);
+  printPersonalMarketplaceHint(json);
+
+  // The contract is checked on the new copy BEFORE it replaces the shared
+  // stage: an invalid copy must never become what Claude Code or Codex reads.
+  let expectedVersion;
+  const staged = stagePackage({
+    soRoot: SO_ROOT,
+    stageDir: STAGE_DIR,
+    installDeps: true,
+    log: (line) => progress(json, `Package: ${line}`),
+    validate: (dir) => {
+      try {
+        expectedVersion = validateLocalContract(dir);
+        return { ok: true };
+      } catch (error) {
+        return { ok: false, detail: error.message };
+      }
+    },
+  });
+  if (!staged.ok) throw new InstallerError(`Cannot stage the packed copy: ${staged.detail}`);
+  progress(json, `Local contract: valid (${expectedVersion})`);
+
+  progress(json, `Marketplace: adding '${STAGE_DIR}'`);
   const marketplaceAdd = runCodexJson(
-    ['plugin', 'marketplace', 'add', SO_ROOT, '--json'],
+    ['plugin', 'marketplace', 'add', STAGE_DIR, '--json'],
     'Marketplace add',
   );
   assertMarketplaceAddResult(marketplaceAdd);
@@ -399,7 +484,7 @@ function install({ json }) {
     ok: true,
     codexVersion: formatVersion(version),
     marketplace: MARKETPLACE_NAME,
-    marketplaceSource: SO_ROOT,
+    marketplaceSource: STAGE_DIR,
     marketplaceAlreadyAdded: marketplaceAdd.alreadyAdded,
     pluginId: PLUGIN_ID,
     pluginVersion: expectedVersion,

package/scripts/emit-session.mjs

@@ -29,6 +29,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { resolveEventsLedgerRoot } from './lib/platform.mjs';
 import { appendJsonl } from './lib/common.mjs';
 import {
   MEMORY_CLEANUP_EVENT,
@@ -49,6 +50,18 @@ import {
 } from './lib/session-schema.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 
+/**
+ * The events ledger beside `sessionsFile` — mapped to the main checkout when the
+ * metrics dir sits in a LINKED git worktree (#1514 point 1: one ledger per repo,
+ * the one the hooks write). Identity everywhere else, including a tmp fixture.
+ *
+ * @param {string} sessionsFile
+ * @returns {string}
+ */
+function siblingEventsFile(sessionsFile) {
+  return join(resolveEventsLedgerRoot(dirname(sessionsFile)), 'events.jsonl');
+}
+
 export { serializeSessionLineChecked };
 
 // A FULL object name only (SHA-1 or SHA-256 repo). A short sha or a symbolic
@@ -314,7 +327,7 @@ async function main() {
   const alreadyStamped =
     typeof repaired.memory_cleanup_at === 'string' && repaired.memory_cleanup_at.length > 0;
   if (!alreadyStamped) {
-    const eventsFile = join(dirname(args.file), 'events.jsonl');
+    const eventsFile = siblingEventsFile(args.file);
     const signal = deriveMemoryCleanupSignal({
       eventsFile,
       sessionId: repaired.session_id,
@@ -455,7 +468,7 @@ async function main() {
   // without one the fallback cannot run, which is exactly when silence hid it.
   if (!hasOwn('session_start_ref')) {
     const headSha = ownUuid !== null
-      ? readOwnStartHeadSha(join(dirname(args.file), 'events.jsonl'), ownUuid)
+      ? readOwnStartHeadSha(siblingEventsFile(args.file), ownUuid)
       : null;
     if (headSha !== null) {
       repaired = { ...repaired, session_start_ref: headSha };

package/scripts/fleet-auflagen.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * fleet-auflagen.mjs — read this session's navigator conditions ("Auflagen")
+ * and accept them only when they belong to this repo (#1520, navigator#190).
+ *
+ * Thin CLI over `readAuflagen()` in `scripts/lib/fleet-protocol.mjs`, called by
+ * session-start Phase 7.6 after the check-in.
+ *
+ * Usage:
+ *   node scripts/fleet-auflagen.mjs <session_id>
+ *
+ * The own repo is `CLAUDE_PROJECT_DIR` (trimmed) or the working directory.
+ *
+ * stdout: one JSON line — `{ state: 'absent' }`, `{ state: 'accepted', auflagen }`
+ * or `{ state: 'rejected', reason }`. A rejected file counts as absent: the
+ * Standard-Auflagen apply. On rejection a WARN line goes to stderr.
+ *
+ * Exit codes:
+ *   0 — any of the three states (rejection is a result, not an error)
+ *   2 — usage error (no session id)
+ */
+
+import { readAuflagen } from './lib/fleet-protocol.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const PREFIX = 'fleet-auflagen:';
+
+/** @returns {Promise<number>} exit code */
+async function main() {
+  const sessionId = process.argv[2];
+  if (!sessionId) {
+    process.stderr.write(`${PREFIX} usage: fleet-auflagen.mjs <session_id>\n`);
+    return 2;
+  }
+  const repoRoot = (process.env.CLAUDE_PROJECT_DIR || '').trim() || process.cwd();
+  const result = await readAuflagen(sessionId, { repoRoot });
+  if (result.state === 'rejected') {
+    process.stderr.write(
+      `${PREFIX} WARN: auflagen file ignored (${result.reason}) — treated as absent, Standard-Auflagen apply\n`,
+    );
+  }
+  process.stdout.write(JSON.stringify(result) + '\n');
+  return 0;
+}
+
+if (isMainModule(import.meta.url)) {
+  main().then(
+    (code) => { process.exitCode = code; },
+    (err) => {
+      process.stderr.write(`${PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exitCode = 1;
+    },
+  );
+}

package/scripts/generate-agents-skills.mjs

@@ -54,7 +54,8 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import yaml from 'js-yaml';
-import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
+import { isUserInvocableSkill } from './lib/user-invocable-skills.mjs';
+import { listCommandFiles, listSkillDirs } from './lib/plugin-surface.mjs';
 
 const POLICY_MARKER = '# Generated by scripts/generate-agents-skills.mjs; do not edit.\n';
 
@@ -185,7 +186,9 @@ export function renderMirror(skillName, portableFm, canonical = `skills/${skillN
     '',
     'Read the linked document in full and follow its complete workflow, including prechecks and stop conditions. Resolve its 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 and relative links in the canonical document from its own directory. Keep the user’s project as the target of project operations.',
   ];
-  if (command || isUserInvocableValue(portableFm.metadata?.['user-invocable'])) lines.push(
+  // The source `user-invocable` travels as a string in `metadata`; absent there
+  // means absent in the source, which Claude Code reads as invocable (#1515).
+  if (command || isUserInvocableSkill(portableFm.metadata ?? {})) 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. Pass command arguments through structured tool parameters or safely quoted individual arguments.',
   );
@@ -211,24 +214,14 @@ function readFrontmatter(absPath) {
 
 /** List `skills/<name>` directories that carry a SKILL.md, sorted. */
 export function listSourceSkills(pluginRoot) {
-  const dir = path.join(pluginRoot, 'skills');
-  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
-  return readdirSync(dir, { withFileTypes: true })
-    .filter((e) => e.isDirectory() && !e.name.startsWith('.') && !e.name.startsWith('_'))
-    .map((e) => e.name)
-    .filter((n) => existsSync(path.join(dir, n, 'SKILL.md')))
-    .sort();
+  return listSkillDirs(pluginRoot);
 }
 
 /** Union of canonical skills and commands, preserving command precedence. */
 function listSourceEntries(pluginRoot) {
   const sources = new Map(listSourceSkills(pluginRoot).map((name) => [name, `skills/${name}/SKILL.md`]));
-  const commands = path.join(pluginRoot, 'commands');
-  if (existsSync(commands) && statSync(commands).isDirectory()) {
-    for (const entry of readdirSync(commands, { withFileTypes: true })) {
-      if (!entry.isFile() || !entry.name.endsWith('.md') || /^[._]/.test(entry.name)) continue;
-      sources.set(entry.name.slice(0, -3), `commands/${entry.name}`);
-    }
+  for (const file of listCommandFiles(pluginRoot)) {
+    sources.set(file.slice(0, -3), `commands/${file}`);
   }
   return sources;
 }
@@ -250,7 +243,7 @@ function invocationPolicy(pluginRoot, name, canonical, fm) {
         return native.policy.allow_implicit_invocation;
       }
     }
-    if (!isUserInvocableValue(fm['user-invocable'], canonical)) return undefined;
+    if (!isUserInvocableSkill(fm, canonical)) return undefined;
   }
   if (Object.hasOwn(fm, 'disable-model-invocation') && typeof fm['disable-model-invocation'] !== 'boolean') {
     throw new Error(`${canonical}: disable-model-invocation must be a boolean`);

package/scripts/generate-codex-skills.mjs

@@ -9,7 +9,8 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import yaml from 'js-yaml';
 import { toPortableFrontmatter } from './generate-agents-skills.mjs';
-import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
+import { isUserInvocableSkill } from './lib/user-invocable-skills.mjs';
+import { isHiddenSourceName } from './lib/plugin-surface.mjs';
 
 const OUTPUT = '.codex-plugin/skills';
 const MARKER = 'Generated by scripts/generate-codex-skills.mjs; do not edit.';
@@ -56,7 +57,8 @@ function validateFrontmatter(fm, name, path) {
 
 /**
  * The repo-wide marker for "operator-facing slash command" — delegated to
- * `isUserInvocableValue`, the ONE normaliser, so this generator, the Cursor and
+ * `isUserInvocableSkill` (absent key = invocable, #1515; values via the ONE
+ * normaliser `isUserInvocableValue`), so this generator, the Cursor and
  * Pi generators and the counters cannot disagree about a quoted or cased value.
  *
  * @param {Record<string, unknown>} fm
@@ -64,7 +66,7 @@ function validateFrontmatter(fm, name, path) {
  * @returns {boolean}
  */
 function isUserInvocable(fm, path) {
-  return isUserInvocableValue(fm?.['user-invocable'], path);
+  return isUserInvocableSkill(fm, path);
 }
 
 /** Existing native policy is meaningful; Claude's user-invocable flag is not a substitute. */
@@ -92,7 +94,7 @@ function readSources(root) {
     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;
+      if (isHiddenSourceName(entry.name)) 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;
@@ -106,7 +108,7 @@ function readSources(root) {
       catch (error) { throw new Error(`${path}: invalid YAML: ${error.message}`, { cause: error }); }
       validateFrontmatter(fm, name, path);
       // Policy precedence for a skill: a native `agents/openai.yaml` wins; else
-      // an explicitly user-invocable skill (a slash command that used to be a
+      // a user-invocable skill (key `true` or absent; a slash command that used to be a
       // `commands/*.md` file) derives it from `disable-model-invocation` exactly
       // as command sources do; a library skill emits no policy.
       const policy = command
@@ -161,7 +163,7 @@ function renderSkill(source, warnings) {
     '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.',
   ];
   // `$ARGUMENTS` semantics belong to every OPERATOR-FACING document — a
-  // `commands/*.md`, and equally a skill that declares `user-invocable: true`
+  // `commands/*.md`, and equally a skill whose `user-invocable` is `true` (or absent)
   // and references `$ARGUMENTS` in its own body. Gating them on `source.command`
   // alone silently dropped the argument-handling contract from every command
   // body that was folded into its same-named skill.

package/scripts/generate-cursor-adapter.mjs

@@ -27,7 +27,8 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { isUserInvocableValue } from './lib/user-invocable-skills.mjs';
+import { isUserInvocableSkill, isUserInvocableValue } from './lib/user-invocable-skills.mjs';
+import { listCommandFiles, listSkillDirs, parseFrontmatter } from './lib/plugin-surface.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = path.dirname(__filename);
@@ -46,73 +47,6 @@ function isDir(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
 }
 
-function commandFiles() {
-  if (!existsSync(COMMANDS_DIR)) return [];
-  return readdirSync(COMMANDS_DIR)
-    .filter((name) => name.endsWith('.md'))
-    .sort();
-}
-
-function skillDirs() {
-  if (!existsSync(SKILLS_DIR)) return [];
-  return readdirSync(SKILLS_DIR)
-    .filter((name) => isDir(path.join(SKILLS_DIR, name)) && existsSync(path.join(SKILLS_DIR, name, 'SKILL.md')))
-    .sort();
-}
-
-/**
- * Parse YAML-ish frontmatter including `>` / `|` folded scalars.
- *
- * A UTF-8 BOM before the opening `---`, or CRLF line endings, used to make the
- * two probes below miss the block entirely: the file parsed as "no
- * frontmatter", so every flag in it (`user-invocable`,
- * `disable-model-invocation`) silently disappeared and the skill was demoted
- * out of `.cursor/commands/` with no diagnostic anywhere. Both are normalised
- * away first — the same treatment `parseAgentFrontmatter`
- * (`scripts/lib/agent-frontmatter.mjs`) gives them.
- *
- * NOT replaced by the shared `parseSkillFrontmatter`: that one returns the
- * `__BLOCK_SCALAR__` sentinel for a `description: >`, which is the form every
- * merged skill actually uses — routing through it would emit the sentinel as
- * the wrapper description.
- *
- * @param {string} content
- * @returns {Record<string, string>}
- */
-function parseFrontmatter(content) {
-  const text = (content.charCodeAt(0) === 0xfeff ? content.slice(1) : content).replace(/\r\n?/g, '\n');
-  if (!text.startsWith('---\n')) return {};
-  const end = text.indexOf('\n---\n', 4);
-  if (end === -1) return {};
-
-  const lines = text.slice(4, end).split('\n');
-  const fields = {};
-  let i = 0;
-  while (i < lines.length) {
-    const match = lines[i].match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
-    if (!match) {
-      i += 1;
-      continue;
-    }
-    const key = match[1];
-    const raw = match[2];
-    if (raw === '>' || raw === '| ' || raw === '|' || raw === '>-' || raw === '|-') {
-      const folded = [];
-      i += 1;
-      while (i < lines.length && (lines[i].startsWith(' ') || lines[i].startsWith('\t') || lines[i] === '')) {
-        folded.push(lines[i].replace(/^\s+/, ''));
-        i += 1;
-      }
-      const joiner = raw.startsWith('|') ? '\n' : ' ';
-      fields[key] = folded.filter(Boolean).join(joiner).trim();
-      continue;
-    }
-    fields[key] = raw.replace(/^["']|["']$/g, '');
-    i += 1;
-  }
-  return fields;
-}
-
 /**
  * Values that YAML would read as a non-string scalar even though every
  * character in them is "safe". `argument-hint: no` is a boolean, not the
@@ -194,8 +128,9 @@ Cursor has no Skill tool. When the command says to invoke a skill, Read \`skills
 /**
  * Skills that declare themselves operator-facing slash commands.
  *
- * The predicate is `isUserInvocableValue` from `scripts/lib/user-invocable-skills.mjs`
- * — the ONE normaliser for this marker, shared with the Pi and Codex generators
+ * The predicate is `isUserInvocableSkill` from `scripts/lib/user-invocable-skills.mjs`
+ * (absent key = invocable, #1515) over the ONE value normaliser `isUserInvocableValue`,
+ * shared with the Pi and Codex generators
  * and with every counter. The private copy this replaced read only a
  * whitespace-trimmed bare `true`, so `True` and `true # note` were demoted HERE
  * while the shared counter listed them as commands; the SKILL.md path is passed
@@ -204,7 +139,7 @@ Cursor has no Skill tool. When the command says to invoke a skill, Read \`skills
  * @returns {string[]} skill names, sorted
  */
 function userInvocableSkills() {
-  return skillDirs().filter((name) => skillFlags(name).userInvocable);
+  return listSkillDirs(ROOT).filter((name) => skillFlags(name).userInvocable);
 }
 
 /**
@@ -225,7 +160,7 @@ function skillFlags(skillName) {
   if (cached) return cached;
   const file = path.join(SKILLS_DIR, skillName, 'SKILL.md');
   const fields = parseFrontmatter(readFileSync(file, 'utf8'));
-  const userInvocable = isUserInvocableValue(fields['user-invocable'], file, 'user-invocable');
+  const userInvocable = isUserInvocableSkill(fields, file);
   const sourceDisablesModel = isUserInvocableValue(
     fields['disable-model-invocation'], file, 'disable-model-invocation',
   );
@@ -375,7 +310,7 @@ Cursor has no Skill tool. Treat "invoke the ${skillName} skill" as: Read \`skill
  */
 function expectedCommands() {
   const commands = new Map();
-  for (const commandFile of commandFiles()) {
+  for (const commandFile of listCommandFiles(ROOT)) {
     commands.set(commandFile, renderCommand(commandFile));
   }
 
@@ -401,7 +336,7 @@ function expectedCommands() {
 
 function expectedSkills() {
   const skills = new Map();
-  for (const skillName of skillDirs()) {
+  for (const skillName of listSkillDirs(ROOT)) {
     skills.set(skillName, renderSkill(skillName));
   }
   return skills;