session-orchestrator 5.7.0 → 5.8.0

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

@@ -1,6 +1,6 @@
 {
-  "generated_at": "2026-10-03T07:30:53.188Z",
-  "head": "0cfbaa2c4fad16d825b94b8000ca8aea3dc9af68",
+  "generated_at": "2026-10-05T10:45:41.038Z",
+  "head": "94dc4a0cf182a06492feb217162d290e9fd0e921",
   "entries": [
     {
       "file": "hooks/_lib/atomic-json.mjs",
@@ -1264,6 +1264,14 @@
         "subagent-telemetry.mjs"
       ]
     },
+    {
+      "file": "scripts/lib/plugin-surface.mjs",
+      "reachable_from": [
+        "on-session-end.mjs",
+        "on-session-start.mjs",
+        "skill-invocation-telemetry.mjs"
+      ]
+    },
     {
       "file": "scripts/lib/plugin-update-banner.mjs",
       "reachable_from": [

package/hooks/hooks-codex.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo '🎯 Session Orchestrator v5.7.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.8.0 — /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 v5.7.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "command": "echo '🎯 Session Orchestrator v5.8.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
             "async": false
           },
           {

package/hooks/post-tool-batch-wave-signal.mjs

@@ -265,6 +265,7 @@ const GIT_OPTS = (projectDir) => ({
   cwd: projectDir,
   encoding: 'utf8',
   timeout: 1_500,
+  maxBuffer: 64 * 1024 * 1024,
   stdio: ['ignore', 'pipe', 'ignore'],
   env: filteredGitEnv(),
 });

package/hooks/post-tooluse-frontend-slop.mjs

@@ -3,6 +3,10 @@
  * post-tooluse-frontend-slop.mjs — PostToolUse hook that runs the deterministic
  * frontend-slop detector on a UI file right after it is edited.
  *
+ * @deprecated since 5.8.0 (#1121) — removal in the next major. An opted-in
+ * repo (`frontend-slop-hook.enabled: true`) gets one stderr notice per run;
+ * behaviour is otherwise unchanged.
+ *
  * Issue #684 (Track 2 / item B). OPT-IN, warn-only, NON-BLOCKING. PostToolUse
  * fires AFTER the edit is already applied, so this hook can never block — it
  * only surfaces an `additionalContext` roll-up of detector findings so the
@@ -15,7 +19,7 @@
  *   4. file_path gate: exit 0 if absent / non-string.
  *   5. Extension gate: exit 0 unless path.extname(file) ∈ SCANNABLE_EXTS (SSOT).
  *   6. Session Config gate: exit 0 unless `frontend-slop-hook.enabled === true`
- *      (OPT-IN — default off).
+ *      (OPT-IN — default off). Enabled → one deprecation line on stderr (#1121).
  *   7. detectFiles([file]) (fail-soft). No findings → exit 0 silently.
  *   8. Output: additionalContext roll-up on stdout (NEVER blocks). Best-effort
  *      orchestrator.frontend_slop.warning event.
@@ -149,6 +153,12 @@ async function main() {
   const config = await loadFrontendSlopHookConfig({ repoRoot: getProjectDir() });
   if (config.enabled !== true) return;
 
+  // #1121: deprecated, not removed. Only opted-in repos hear it, once per run,
+  // on stderr — stdout is the hook-JSON channel the harness parses.
+  process.stderr.write(
+    'ℹ frontend-slop-hook is deprecated, removal in the next major — #1121\n',
+  );
+
   // Run the deterministic detector (fail-soft: unreadable files → []).
   const findings = detectFiles([filePath]);
   if (findings.length === 0) return;

package/hooks/pre-task-scope-disjoint.mjs

@@ -172,12 +172,14 @@
  * ## Observability — the ledger half of #1092
  *
  * Every dispatch DECISION also appends one `orchestrator.wave_dispatch.scope_checked`
- * record to `<session root>/.orchestrator/metrics/events.jsonl` — the root
- * `resolveSessionRoot()` resolves (`scripts/lib/platform.mjs`: the git toplevel
- * of the payload `cwd` — its nearest `.git` ancestor when git cannot answer —
- * but never above a launch dir inside it; so neither the subdirectory a `cd`
- * moved to, #1489 Pkt 6, nor the launch dir a worktree session left), which is
- * also where the ledger and its lock live. The reason it
+ * record to the events ledger of the session root's repo —
+ * `eventsFilePath(sessionRoot)`, which maps a linked worktree to its main
+ * checkout (one ledger per repo, #1514 point 1). The DISPATCH ledger and its
+ * lock stay on the root `resolveSessionRoot()` resolves (`scripts/lib/platform.mjs`: the git
+ * toplevel of the payload `cwd` — its nearest `.git` ancestor when git cannot
+ * answer — but never above a launch dir inside it; so neither the subdirectory
+ * a `cd` moved to, #1489 Pkt 6, nor the launch dir a worktree session left),
+ * and session attribution is still read there. The reason the record
  * exists is matrix rows 5/6: the no-signal ALLOW used to be byte-identical to
  * "the guard never ran", and the in-ledger counter added first is a WAVE tally —
  * it cannot say WHICH dispatch carried a scope. Payload: `wave` (omitted, never

package/monitors/monitors.json

@@ -2,7 +2,7 @@
   {
     "name": "ecosystem-health",
     "command": "node \"${CLAUDE_PLUGIN_ROOT}\"/scripts/lib/ecosystem-health.mjs --watch",
-    "description": "Local state-file watcher: every 900 s it stats and reads ONE file, .orchestrator/metrics/ecosystem-health.jsonl under the plugin root, and emits one NDJSON line per change (appeared / disappeared / changed). No network, no CI or branch probing, no repo enumeration, no Session Config read. Nothing writes that file yet (0 writers, measured 2026-09-18), so every run emits `no-state-yet` and idles until SIGTERM — ceiling and revisit trigger at DEFAULT_INTERVAL_S in scripts/lib/ecosystem-health.mjs. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
+    "description": "Local state-file watcher: every 900 s it stats and reads ONE file, .orchestrator/metrics/ecosystem-health.jsonl under the project dir (getProjectDir, #1517), and emits one NDJSON line per change (appeared / disappeared / changed). No network, no CI or branch probing, no repo enumeration, no Session Config read. Nothing writes that file yet (0 writers, measured 2026-09-18), so every run emits `no-state-yet` and idles until SIGTERM — ceiling and revisit trigger at DEFAULT_INTERVAL_S in scripts/lib/ecosystem-health.mjs. Hung on session-start because the previous trigger (on-skill-invoke:ecosystem-health) was self-referential: it could only start when the ecosystem-health skill ran, and that skill has 0 recorded invocations fleet-wide, so the watcher never started once.",
     "when": "on-skill-invoke:session-start"
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "5.7.0",
+  "version": "5.8.0",
   "description": "Your coding agents get an agreed plan, a check after each round of changes and a handover to the next session. Plan, Go, Close: /session reads your repo and agrees the scope, /go runs the work in waves with your tests and typecheck after each implementation wave, /close runs the full gate, verifies, commits and files the rest as issues. Scope and destructive-command guards, crash-safe resume, learnings you approve. For Claude Code, Codex CLI, Cursor and Pi.",
   "type": "module",
   "homepage": "https://session-orchestrator.com",
@@ -41,6 +41,8 @@
     "output-styles/",
     "monitors/",
     "assets/",
+    "evals/",
+    "!evals/results/**",
     "!assets/marketing/**",
     ".claude-plugin/",
     ".codex-plugin/",

package/pi/prompts/architecture.md

@@ -0,0 +1,11 @@
+---
+description: Use when the user asks to improve architecture, find refactoring opportunities, surface deepening opportunities, consolidate tightly-coupled modules, or make a codebase more testable and AI-navigable. Surfaces shallow modules and hypothetical seams using a precise vocabulary (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality from LANGUAGE.md).
+---
+
+# /architecture
+
+Use the Session Orchestrator skill definition at `skills/architecture/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/eval.md

@@ -1,5 +1,5 @@
 ---
-description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v2 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
+description: "Use this skill to run an honest session-process evaluation (Standard v1, aiat-llm-eval/1.0) — score the last completed orchestrator session against the pre-registered rubric-v3 dimensions, run /eval, evaluate this session, produce an eval report, or re-verify a stored eval run for reproducibility. Deterministic-first with an optional advisory LLM judge; never produces a global score."
 argument-hint: "[--session <id>] [--no-write] [--verify <run-id>]"
 ---
 

package/pi/prompts/tmux-layout.md

@@ -0,0 +1,11 @@
+---
+description: "Use this skill when the operator wants a prepared tmux visualization layout for the session's side-channels (STATE.md tail, CI-watch, events.jsonl tail). Renders a 4-pane default layout or debug layout. Read-only side-channel observability — the coordinator chat stays in the operator's original terminal. Trigger phrases: \"tmux layout\", \"split panes for ci watch\", \"visualize session side-channels\", \"show me state-md tail and ci\"."
+---
+
+# /tmux-layout
+
+Use the Session Orchestrator skill definition at `skills/tmux-layout/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/pi/prompts/write-executable-plan.md

@@ -0,0 +1,11 @@
+---
+description: "Use when you have a PRD or design spec and need a bite-sized, executable implementation plan that any agent can follow without re-deriving structure. Produces `docs/plans/YYYY-MM-DD-<feature>.md` with per-task Files block, complete code per step (no placeholders), and exact verification commands. Rejects \"TBD\", \"TODO\", \"add error handling\", \"similar to Task N\"."
+---
+
+# /write-executable-plan
+
+Use the Session Orchestrator skill definition at `skills/write-executable-plan/SKILL.md`.
+
+Arguments: $@
+
+Read that skill file and follow it exactly. When it references `$ARGUMENTS`, substitute the arguments above. Keep all Session Orchestrator platform fallbacks intact.

package/scripts/backfill-abandoned-sessions.mjs

@@ -42,7 +42,7 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { backfillAbandonedSession, isUuid } from './lib/session-close-backfill.mjs';
-import { SCAN_CHUNK_BYTES, emitEvent, listEventSourcesNewestFirst, tombstoneGap } from './lib/events.mjs';
+import { SCAN_CHUNK_BYTES, emitEvent, eventsFilePath, listEventSourcesNewestFirst, tombstoneGap } from './lib/events.mjs';
 import { ARCHIVE_DIR_NAME } from './lib/events-schema.mjs';
 import { getProjectDir } from './lib/platform.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
@@ -173,7 +173,7 @@ export function planSessions({ repoRoot }) {
  * @returns {{ plan: Array<{ sessionId: string, semanticSessionId: string|null }>, historyGaps: number }}
  */
 function planWithGaps({ repoRoot }) {
-  const eventsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+  const eventsPath = eventsFilePath(repoRoot); // #1514: the repo's one ledger
 
   // Two independent UUID -> semantic bridges (#1167). `lock.acquired` is the
   // original one, but a session that LOST the lock-acquire race never emits it;

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`);