session-orchestrator 5.7.0 → 5.8.0

package/scripts/migrate-vault-paths.mjs

@@ -58,6 +58,7 @@ import {
 } from './lib/vault-migration-rules.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -529,12 +530,14 @@ function findHits(filePath, content) {
 }
 
 /**
- * Atomic write: write to <path>.migrate-tmp, then rename.
+ * Atomic write via `atomicWriteText` (`<dir>/.<name>.tmp.<hex>`, then rename);
+ * throws with the original message and `code` on failure.
  */
 async function atomicWrite(filePath, content) {
-  const tmp = `${filePath}.migrate-tmp-${process.pid}-${Date.now()}`;
-  await fs.writeFile(tmp, content, 'utf8');
-  await fs.rename(tmp, filePath);
+  const res = await atomicWriteText(filePath, content, {
+    tmpPrefix: `.${path.basename(filePath)}.tmp`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 }
 
 /**

package/scripts/print-learnings-index.mjs

@@ -101,6 +101,7 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { findProjectRoot } from './lib/common.mjs';
+import { eventsFilePath } from './lib/events.mjs';
 import { resolveStateArtifactPath } from './lib/state-md.mjs';
 import {
   CANDIDATE_POOL_SIZE,
@@ -249,7 +250,7 @@ const repoRoot = findProjectRoot(process.cwd());
 const learningsPath = opts.learnings
   ? opts.learnings
   : join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
-const eventsPath = join(repoRoot, '.orchestrator', 'metrics', 'events.jsonl');
+const eventsPath = eventsFilePath(repoRoot); // #1514 point 1: the repo's one ledger
 // #1019 — the natively-delivered rule corpus. Every `.claude/rules/*.md` reaches
 // a dispatched agent in FULL through Claude Code's own project-instruction
 // loading (`docs/instruction-delivery.md` §1: the `globs:`/`tier:` frontmatter is

package/scripts/relocate-vault-corpus.mjs

@@ -55,6 +55,7 @@ import {
 import { buildBackfillIndex, parseSessionId } from './lib/vault-repo-backfill.mjs';
 import { parseColumnFlags, CliFlagError } from './lib/cli-flags.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
+import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -693,7 +694,6 @@ async function writeManifest({ vaultDir, derivableOnly, summary, moves }) {
 
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
   const manifestPath = path.join(manifestDir, `relocation-manifest-${ts}.json`);
-  const tmpPath = `${manifestPath}.tmp-${process.pid}`;
 
   // Store vault-relative paths in the manifest
   const movesRel = moves.map((m) => ({
@@ -714,8 +714,10 @@ async function writeManifest({ vaultDir, derivableOnly, summary, moves }) {
     moves: movesRel,
   };
 
-  await fs.writeFile(tmpPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
-  await fs.rename(tmpPath, manifestPath);
+  const res = await atomicWriteText(manifestPath, JSON.stringify(manifest, null, 2) + '\n', {
+    tmpPrefix: `.${path.basename(manifestPath)}.tmp`,
+  });
+  if (!res.ok) throw envelopeToError(res);
 
   return manifestPath;
 }

package/scripts/run-migrate-v2-cross-repo.mjs

@@ -32,9 +32,9 @@
  *      with the next repo, and exits 2 at the end
  */
 
-import { existsSync, readFileSync, writeFileSync, copyFileSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
 import { mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 import {
   migrateLegacyLearning,
@@ -43,6 +43,7 @@ import {
 import { LearningsLockError, withLearningsLock } from './lib/learnings/io.mjs';
 import { getCrossRepoProjects, getConfinementRoot } from './lib/config/cross-repo.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
+import { atomicWriteWithBackup, envelopeToError } from './lib/io.mjs';
 
 const LEARNINGS_REL = '.orchestrator/metrics/learnings.jsonl';
 
@@ -316,12 +317,13 @@ function migrateStore(repoPath, learningsPath, apply) {
     try {
       // Backup original
       copyFileSync(learningsPath, backupPath);
-      // Write migrated content atomically
+      // Write migrated content atomically (own backup above keeps its
+      // `.bak-cross-repo-migrate-<ms>` schema, so the helper takes none)
       const body = outputLines.join('\n') + '\n';
-      const tmpPath = `${learningsPath}.migrate-cross-repo-tmp-${process.pid}-${timestamp}`;
-      mkdirSync(dirname(learningsPath), { recursive: true });
-      writeFileSync(tmpPath, body, 'utf8');
-      renameSync(tmpPath, learningsPath);
+      const res = atomicWriteWithBackup(learningsPath, body, {
+        tmpPrefix: `.${basename(learningsPath)}.tmp`,
+      });
+      if (!res.ok) throw envelopeToError(res);
     } catch (err) {
       return {
         repo: repoPath,

package/scripts/self-update.mjs

@@ -15,10 +15,19 @@
  * Steps (each skipped when its harness is not installed on this host):
  *   1. repo    — `git fetch origin` + `git merge --ff-only origin/main`, then
  *                `npm ci` when HEAD moved or node_modules is missing.
- *   2. claude  — marketplace update + plugin update, then verify version and
- *                runtime dependencies in the reported installPath.
+ *   2. claude  — `npm pack` this clone and extract it into STAGE_DIR, then
+ *                marketplace update + plugin update, then verify version and
+ *                runtime dependencies in the reported installPath. The
+ *                marketplace must read STAGE_DIR, not this clone: a directory
+ *                marketplace on the working checkout copied ALL of it into the
+ *                plugin cache — 7557 files instead of 1164, `.env.local`
+ *                (NPM_TOKEN) and `.orchestrator/` included (#1515, measured
+ *                2026-10-03). The step refuses, naming the remove + add
+ *                commands, while ANY directory marketplace reads this clone;
+ *                GitHub/npm sources update as before, with a one-line hint.
  *   3. codex   — only if the plugin is already installed in Codex: re-run
- *                scripts/codex-install.mjs (refreshes the installed bundle).
+ *                scripts/codex-install.mjs, which installs from the same
+ *                packed STAGE_DIR (#1518), never from this clone.
  *
  * Never deletes an old plugin cache directory: the running session still
  * loads it until the harness restarts.
@@ -26,20 +35,78 @@
  * Exit codes: 0 all steps ok/skipped · 1 usage error · 2 a step failed.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { commandOnPath, spawnNativeSync } from './lib/native-command.mjs';
 import { fileURLToPath } from 'node:url';
 
 import { isMainModule } from './lib/is-main-module.mjs';
+import { resolveStageDir, stagePackage } from './lib/plugin-package-stage.mjs';
 
 const SO_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+// Codex install id; the Claude id is read from the installed entry, because
+// the marketplace name is whatever the host registered (`kanevry` per
+// .claude-plugin/marketplace.json, `session-orchestrator` on older hosts).
 const PLUGIN_ID = 'session-orchestrator@kanevry';
-const MARKETPLACE = 'kanevry';
+const PLUGIN_NAME = 'session-orchestrator';
 const COMMAND_TIMEOUT_MS = 300_000;
 // `codex plugin list --available --json` is 2.56 MB on a host with several
 // marketplaces (measured 2026-10-02); the 1 MiB default fails with ENOBUFS.
 const MAX_BUFFER = 64 * 1024 * 1024;
+/** Host-local copy of the packed package; the marketplace reads this, never the clone. */
+const STAGE_DIR = resolveStageDir();
+
+/**
+ * Claude Code config dir: CLAUDE_CONFIG_DIR when absolute, else ~/.claude. A
+ * relative value is ignored like a relative XDG_CACHE_HOME — resolved against
+ * whatever cwd this script runs in, it would point the marketplace guard at a
+ * file that does not exist and let the update run unguarded (#1519).
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {string} [home]
+ * @returns {{dir: string, ignored: string | null}}
+ */
+export function resolveClaudeConfigDir(env = process.env, home = os.homedir()) {
+  const raw = (env.CLAUDE_CONFIG_DIR || '').trim();
+  if (path.isAbsolute(raw)) return { dir: raw, ignored: null };
+  return { dir: path.join(home, '.claude'), ignored: raw || null };
+}
+
+const CLAUDE_CONFIG = resolveClaudeConfigDir();
+const KNOWN_MARKETPLACES = path.join(CLAUDE_CONFIG.dir, 'plugins', 'known_marketplaces.json');
+
+const realOrResolved = (p) => { try { return realpathSync(p); } catch { return path.resolve(p); } };
+
+/**
+ * Registered Claude Code marketplaces from `known_marketplaces.json`, read
+ * defensively: a missing or unparseable file yields `null`, never a throw.
+ * @param {string} file
+ * @returns {Array<{name: string, source: string | undefined, path: string | undefined}> | null}
+ */
+export function readKnownMarketplaces(file) {
+  let raw;
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  return Object.entries(raw).map(([name, v]) => ({
+    name,
+    source: typeof v?.source?.source === 'string' ? v.source.source : undefined,
+    path: typeof v?.source?.path === 'string' ? v.source.path : undefined,
+  }));
+}
+
+/**
+ * Names of the `directory` marketplaces that read `dir` (realpath-compared) —
+ * whatever they are called.
+ * @param {ReturnType<typeof readKnownMarketplaces>} known
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function directoryMarketplacesOn(known, dir) {
+  const target = realOrResolved(dir);
+  return (known ?? [])
+    .filter((m) => m.source === 'directory' && m.path && realOrResolved(m.path) === target)
+    .map((m) => m.name);
+}
 
 /**
  * Pick the session-orchestrator entry from `claude plugin list --json`.
@@ -50,8 +117,9 @@ const MAX_BUFFER = 64 * 1024 * 1024;
 export function findClaudeEntry(listJson) {
   const entries = Array.isArray(listJson) ? listJson : listJson?.plugins;
   if (!Array.isArray(entries)) return null;
-  return entries.find((e) => e?.id === PLUGIN_ID && e?.scope === 'user')
-    ?? entries.find((e) => e?.id === PLUGIN_ID)
+  const ours = (e) => typeof e?.id === 'string' && e.id.startsWith(`${PLUGIN_NAME}@`);
+  return entries.find((e) => ours(e) && e?.scope === 'user')
+    ?? entries.find(ours)
     ?? null;
 }
 
@@ -90,16 +158,16 @@ to the newest Session Orchestrator, and verify each one afterwards.
   --json       Print the per-step result as JSON
 `;
 
-function makeRunner({ dryRun, json }) {
+export function makeRunner({ dryRun, json }) {
   const log = (line) => { if (!json) process.stdout.write(`${line}\n`); };
   /** Run a command; read-only queries also run under --dry-run. */
-  function run(cmd, args, { cwd = SO_ROOT, mutates = true } = {}) {
+  function run(cmd, args, { cwd = SO_ROOT, mutates = true, env } = {}) {
     const shown = `${cmd} ${args.join(' ')}`;
     if (dryRun && mutates) {
       log(`  [dry-run] ${shown}${cwd === SO_ROOT ? '' : `   (in ${cwd})`}`);
       return { ok: true, stdout: '' };
     }
-    const r = spawnSync(cmd, args, { cwd, encoding: 'utf8', timeout: COMMAND_TIMEOUT_MS, maxBuffer: MAX_BUFFER });
+    const r = spawnNativeSync(cmd, args, { cwd, env, encoding: 'utf8', timeout: COMMAND_TIMEOUT_MS, maxBuffer: MAX_BUFFER });
     if (r.error) return { ok: false, detail: `${shown}: ${r.error.message}` };
     if (r.status !== 0) {
       return { ok: false, detail: `${shown} exited ${r.status}: ${(r.stderr || r.stdout || '').trim().slice(-400)}` };
@@ -109,12 +177,8 @@ function makeRunner({ dryRun, json }) {
   return { run, log };
 }
 
-function onPath(bin) {
-  return spawnSync('which', [bin], { encoding: 'utf8' }).status === 0;
-}
-
-function repoVersion() {
-  return JSON.parse(readFileSync(path.join(SO_ROOT, 'package.json'), 'utf8')).version;
+function repoVersion(root = SO_ROOT) {
+  return JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).version;
 }
 
 function updateRepo({ run, log }, opts) {
@@ -139,36 +203,112 @@ function updateRepo({ run, log }, opts) {
   return { step: 'repo', status: 'ok', detail: `${repoVersion()}${moved ? ' (updated)' : ' (already current)'}` };
 }
 
-function updateClaude({ run, log }, opts) {
-  if (!onPath('claude')) return { step: 'claude', status: 'skipped', detail: 'claude not on PATH' };
-  log('claude: refreshing marketplace and plugin');
-  for (const args of [['plugin', 'marketplace', 'update', MARKETPLACE], ['plugin', 'update', PLUGIN_ID]]) {
-    const r = run('claude', args);
-    if (!r.ok) return { step: 'claude', status: 'failed', detail: r.detail };
+/** Marketplace name the packed copy registers under (its own marketplace.json). */
+function packedMarketplaceName(root) {
+  try {
+    return JSON.parse(readFileSync(path.join(root, '.claude-plugin', 'marketplace.json'), 'utf8')).name || 'kanevry';
+  } catch {
+    return 'kanevry';
+  }
+}
+
+/**
+ * The Claude Code step. `ctx` exists for tests (tmp config dir, tmp clone,
+ * no PATH lookup); production passes nothing.
+ */
+export function updateClaude({ run, log }, opts, ctx = {}) {
+  const {
+    soRoot = SO_ROOT,
+    stageDir = STAGE_DIR,
+    knownMarketplacesFile = KNOWN_MARKETPLACES,
+    ignoredConfigDir = CLAUDE_CONFIG.ignored,
+    hasClaude = () => commandOnPath('claude'),
+  } = ctx;
+  const fail = (detail) => ({ step: 'claude', status: 'failed', detail });
+  if (!hasClaude()) return { step: 'claude', status: 'skipped', detail: 'claude not on PATH' };
+  if (ignoredConfigDir) {
+    log(`claude: ignoring relative CLAUDE_CONFIG_DIR '${ignoredConfigDir}' — reading ${knownMarketplacesFile}`);
+  }
+  const stage = () => stagePackage({
+    soRoot, stageDir, run, log: (line) => log(`claude: ${line}`), dryRun: opts.dryRun,
+  });
+
+  const parseEntry = (r) => {
+    if (!r.ok) return { error: r.detail };
+    try { return { entry: findClaudeEntry(JSON.parse(r.stdout)) }; } catch (e) {
+      return { error: `plugin list --json unparseable: ${e.message}` };
+    }
+  };
+  // Installed-check first: with nothing installed there is nothing to guard,
+  // and the refusal below would replace the host's stage dir for no install (#1519).
+  const before = parseEntry(run('claude', ['plugin', 'list', '--json'], { mutates: false }));
+  if (before.error) return fail(before.error);
+  if (!before.entry) return { step: 'claude', status: 'skipped', detail: `${PLUGIN_NAME} not installed` };
+
+  const known = readKnownMarketplaces(knownMarketplacesFile);
+  const leaking = directoryMarketplacesOn(known, soRoot);
+  if (leaking.length > 0) {
+    // Stage first so the `add` target named below exists.
+    const staged = stage();
+    const packedName = packedMarketplaceName(soRoot);
+    // A marketplace already holding the packed copy's name (e.g. a GitHub
+    // `kanevry`) would make `marketplace add <stage>` fail on the taken name.
+    const sameName = known?.find((m) => m.name === packedName);
+    const nameTaken = sameName && !leaking.includes(packedName)
+      && !(sameName.source === 'directory' && sameName.path && realOrResolved(sameName.path) === realOrResolved(stageDir));
+    const removes = [...leaking, ...(nameTaken ? [packedName] : [])]
+      .map((n) => `claude plugin marketplace remove ${n}`).join(' && ');
+    return fail(
+      `directory marketplace ${leaking.map((n) => `'${n}'`).join(', ')} reads this clone — the plugin cache `
+      + `becomes a full copy incl. .env.local (#1515). Re-register once: ${removes} && `
+      + `claude plugin marketplace add ${stageDir} && claude plugin install ${PLUGIN_NAME}@${packedName}`
+      + (staged.ok ? '' : ` (staging failed: ${staged.detail})`),
+    );
   }
-  const list = run('claude', ['plugin', 'list', '--json'], { mutates: false });
-  if (!list.ok) return { step: 'claude', status: 'failed', detail: list.detail };
-  let entry;
-  try { entry = findClaudeEntry(JSON.parse(list.stdout)); } catch (e) {
-    return { step: 'claude', status: 'failed', detail: `plugin list --json unparseable: ${e.message}` };
+
+  const pluginId = before.entry.id;
+  const marketplace = pluginId.slice(pluginId.indexOf('@') + 1);
+  const reg = known?.find((m) => m.name === marketplace);
+  const fromStage = reg?.source === 'directory' && !!reg.path && realOrResolved(reg.path) === realOrResolved(stageDir);
+
+  if (fromStage) {
+    const staged = stage();
+    if (!staged.ok) return fail(staged.detail);
+  } else {
+    log(known
+      ? `claude: marketplace '${marketplace}' reads ${reg?.path ?? reg?.source ?? 'an unknown source'}; to install this clone instead, register the packed copy at ${stageDir}`
+      : `claude: ${knownMarketplacesFile} unreadable — cannot check the marketplace source; the packed-copy path is ${stageDir}`);
   }
-  if (!entry) return { step: 'claude', status: 'skipped', detail: `${PLUGIN_ID} not installed` };
-  if (!entry.installPath || !existsSync(entry.installPath)) {
-    return { step: 'claude', status: 'failed', detail: `installPath missing: ${entry.installPath}` };
+
+  log(`claude: refreshing marketplace '${marketplace}' and plugin ${pluginId}`);
+  for (const args of [['plugin', 'marketplace', 'update', marketplace], ['plugin', 'update', pluginId]]) {
+    const r = run('claude', args);
+    if (!r.ok) return fail(r.detail);
   }
+  const after = parseEntry(run('claude', ['plugin', 'list', '--json'], { mutates: false }));
+  if (after.error) return fail(after.error);
+  const entry = after.entry;
+  if (!entry) return fail(`${pluginId} disappeared from plugin list after the update`);
+  if (!entry.installPath || !existsSync(entry.installPath)) return fail(`installPath missing: ${entry.installPath}`);
   const missing = missingRuntimeDeps(entry.installPath);
   if (missing.length > 0) {
     const refused = (entry.noteDetails ?? []).some((n) => n?.type === 'dependencies-refused');
     log(`claude: ${missing.length} runtime deps missing${refused ? ' (harness refused the install)' : ''} — installing`);
-    const r = run('npm', ['ci', '--omit=dev'], { cwd: entry.installPath });
-    if (!r.ok) return { step: 'claude', status: 'failed', detail: r.detail };
+    // The packed copy carries no .npmrc, so the repo's ignore-scripts=true
+    // (SEC-020) has to travel as a flag.
+    const r = run('npm', ['ci', '--omit=dev', '--ignore-scripts'], { cwd: entry.installPath });
+    if (!r.ok) return fail(r.detail);
     const still = opts.dryRun ? [] : missingRuntimeDeps(entry.installPath);
-    if (still.length > 0) return { step: 'claude', status: 'failed', detail: `still missing after npm ci: ${still.join(', ')}` };
+    if (still.length > 0) return fail(`still missing after npm ci: ${still.join(', ')}`);
+  }
+  const want = repoVersion(soRoot);
+  if (entry.version !== want && fromStage && !opts.dryRun) {
+    // The source IS this clone's packed copy, so a different version means
+    // the update did not take effect — not that a remote is behind.
+    return fail(`update did not take effect: installed ${entry.version}, packed ${want}`);
   }
-  const want = repoVersion();
-  // The marketplace tracks GitHub main, so it can trail this clone until the
-  // release is pushed — report it, do not fail on it.
-  const lag = entry.version !== want ? `; clone is ${want} — marketplace not yet at it` : '';
+  const lag = entry.version !== want && !fromStage
+    ? `; clone is ${want} — marketplace '${marketplace}' source is not at it yet` : '';
   return {
     step: 'claude',
     status: 'ok',
@@ -177,7 +317,7 @@ function updateClaude({ run, log }, opts) {
 }
 
 function updateCodex({ run, log }, opts) {
-  if (!onPath('codex')) return { step: 'codex', status: 'skipped', detail: 'codex not on PATH' };
+  if (!commandOnPath('codex')) return { step: 'codex', status: 'skipped', detail: 'codex not on PATH' };
   const list = run('codex', ['plugin', 'list'], { mutates: false });
   if (!list.ok) return { step: 'codex', status: 'failed', detail: list.detail };
   if (!new RegExp(`^${PLUGIN_ID}\\s+installed`, 'm').test(list.stdout)) {

package/scripts/site-numbers.mjs

@@ -178,8 +178,9 @@ export function countSkills(root) {
 }
 
 /**
- * The product's "slash commands" number: `commands/*.md` ∪ skills carrying an
- * EXPLICIT `user-invocable: true`, deduplicated by name.
+ * The product's "slash commands" number: `commands/*.md` ∪ skills whose
+ * `user-invocable` is `true` or ABSENT (Claude Code lists a keyless skill in the
+ * `/` picker — #1515), deduplicated by name.
  *
  * NOT `ls commands/*.md | wc -l` any more, and the change is not cosmetic. After
  * the 2026-09-16 fold (#1370) `commands/` holds two files — `session` and
@@ -435,7 +436,7 @@ export const METRIC_DEFS = Object.freeze([
     id: 'commands',
     provenance: false,
     source:
-      'ls commands/*.md | wc -l  +  grep -l "^user-invocable: true" skills/*/SKILL.md | wc -l   (union by name — see countCommands)',
+      'ls commands/*.md | wc -l  +  grep -L "^user-invocable: *false" skills/*/SKILL.md | wc -l   (union by name; a skill without the key counts, as in Claude Code — see countCommands)',
     compute: (root) => fmtCount(countCommands(root)),
   },
   {

package/scripts/sweep-expired-learnings.mjs

@@ -123,7 +123,7 @@
  */
 
 import { existsSync, realpathSync, statSync } from 'node:fs';
-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import {
@@ -135,6 +135,7 @@ import {
   warnUnparseableLines,
 } from './lib/learnings/expiry-sweep.mjs';
 import { readLearningsSnapshot, parseLearningsText } from './lib/learnings/io.mjs';
+import { atomicWriteText, envelopeToError } from './lib/io.mjs';
 import { validateLearning } from './lib/learnings/schema.mjs';
 import { validatePathInsideProject } from './lib/path-utils.mjs';
 import { emitEvolveCompleted } from './lib/learnings/evolve-telemetry.mjs';
@@ -668,9 +669,10 @@ async function runSnapshot(args) {
       ...snap.entries.map((e) => JSON.stringify(e)),
     ];
     await mkdir(path.dirname(args.snapshot), { recursive: true });
-    const tmp = `${args.snapshot}.tmp-${process.pid}`;
-    await writeFile(tmp, lines.join('\n') + '\n', 'utf8');
-    await rename(tmp, args.snapshot);
+    const res = await atomicWriteText(args.snapshot, lines.join('\n') + '\n', {
+      tmpPrefix: `.${path.basename(args.snapshot)}.tmp`,
+    });
+    if (!res.ok) throw envelopeToError(res);
   } catch (err) {
     process.stderr.write(`sweep-expired-learnings: snapshot failed: ${err.message}\n`);
     process.exit(2);

package/scripts/sync-vault-schema.mjs

@@ -26,13 +26,9 @@
  *   2 — missing file
  *   3 — malformed sentinels (only one of begin/end present)
  *
- * Vendor-ahead state (2026-05-23, #503, I5):
- *   The vaultNoteTypeSchema enum in validator.mjs currently includes
- *   `peer-card` which is NOT yet present in the canonical
- *   projects-baseline source. Until #503 lands upstream, `--check` will
- *   report drift; this is expected and is tracked as upstream-sync-debt
- *   in the #503 PRD (W5 F2 docs agent owns the PRD update). Once
- *   upstream catches up, `--write` will become a no-op (idempotent).
+ * The #503 vendor-ahead state (`peer-card` in validator.mjs before the
+ * canonical source carried it) is resolved: projects-baseline has
+ * `peer-card`, and `--check` passed against baseline `9108018` (2026-10-04).
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';

package/scripts/windows-setup.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/** Opt-in native MCP configuration for an installed Windows plugin. */
+import { copyFileSync, existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+export function configureNativeMcp(pluginRoot, { node = process.execPath, platform = process.platform } = {}) {
+  if (platform !== 'win32') throw new Error('This setup is for native Windows only.');
+  const root = realpathSync(pluginRoot);
+  if (existsSync(path.join(root, '.git'))) throw new Error('Refusing to configure a Git checkout.');
+  const segments = root.split(path.sep);
+  const inCache = segments.some((segment, index) =>
+    segment === 'plugins' && segments[index + 1] === 'cache' && index + 2 < segments.length);
+  if (!inCache) throw new Error('Expected an installed plugin inside plugins/cache.');
+  const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+  if (pkg.name !== 'session-orchestrator') throw new Error('Expected a session-orchestrator plugin directory.');
+  const server = path.join(root, 'scripts', 'mcp-server.mjs');
+  if (!existsSync(server)) throw new Error('Native MCP server is missing; install the updated package first.');
+  const file = path.join(root, '.mcp.json');
+  const raw = readFileSync(file, 'utf8');
+  const config = JSON.parse(raw);
+  const current = config.mcpServers?.['session-orchestrator'];
+  if (!current || typeof current !== 'object') throw new Error('Expected session-orchestrator MCP configuration.');
+  if (current.command === node && current.args?.length === 1 && current.args[0] === server) {
+    return { changed: false, file };
+  }
+  const backup = `${file}.before-windows-setup`;
+  if (existsSync(backup)) throw new Error(`Backup already exists: ${backup}; inspect it before reconfiguring.`);
+  config.mcpServers['session-orchestrator'] = { ...current, command: node, args: [server] };
+  copyFileSync(file, backup);
+  const temporary = `${file}.windows-setup-${process.pid}`;
+  writeFileSync(temporary, `${JSON.stringify(config, null, 2)}\n`, { flag: 'wx' });
+  renameSync(temporary, file);
+  return { changed: true, file, backup };
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    if (process.argv.length !== 3) throw new Error('Usage: node scripts/windows-setup.mjs <installed-plugin-directory>');
+    process.stdout.write(`${JSON.stringify(configureNativeMcp(process.argv[2]))}\n`);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/skills/_shared/fleet-protocol.md

@@ -103,6 +103,14 @@ Bedingungen, die der Navigator einer Session schreibt (z. B. Agent-Caps, volle P
 Offload-Regel, Merge- und Zeitregeln, Besitzkonflikte); Inhalt und Form gehören dem Navigator. Die
 Session **liest** die Datei; sie wartet auf keine Nachricht. Keine Auflage ist eine Freigabe.
 
+**Pflichtfeld `repo`** (#1520, navigator#190): absoluter Pfad auf Toplevel oder git-common-dir des
+Ziel-Repos. Der Dateiname ist die semantische Session-ID, und die kollidiert über Repos hinweg.
+Gelesen wird über `node scripts/fleet-auflagen.mjs <session_id>` (Code: `readAuflagen()`); die
+Datei gilt nur, wenn `repo` und das eigene Repo auf dasselbe `git rev-parse --path-format=absolute
+--git-common-dir` auflösen, ein Worktree passt also zu seinem Haupt-Checkout. Fehlt das Feld, passt
+es nicht oder ist die Datei unlesbar: fail-closed, WARN auf stderr, die Datei zählt als nicht
+vorhanden, die Standard-Auflagen gelten.
+
 **Standard-Auflagen (konservative Stufe).** Sie gelten ab `fallback_due_at` (stdout der
 Check-in-CLI), wenn bis dahin keine Auflagen-Datei liegt. Die Frist rechnet `fallbackDueAt()`:
 `CHECKIN_FALLBACK_MIN` = 10 Minuten nach `checkin.zeit`, solange ein Navigator aktiv ist; ohne

package/skills/architecture/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: architecture
 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).
+user-invocable: true
 model: inherit
 derived-from: mattpocock/skills@90ea8ee
 license: MIT

package/skills/bootstrap/_shared-template.md

@@ -342,7 +342,7 @@ On Codex CLI / Cursor IDE, substitute `.codex/` or `.cursor/` for `.claude/` per
 
 Applied by Fast Step 3 (so by every tier), by the Upgrade Flow and by the Refresh-Lock Flow in `SKILL.md` — the last two because a repo bootstrapped before this step existed never gets it otherwise: both flows write no `.gitignore` of their own.
 
-`.orchestrator/` itself stays versioned: `bootstrap.lock`, `policy/`, `steering/`, `peers/` and the `.orchestrator/metrics/*.jsonl` ledgers are durable project data. What the plugin writes there at runtime is per-process state or a per-run artifact that a `git add -A` would otherwise commit — the session lock is rewritten on every SessionStart, every store rewrite leaves a full backup copy of the ledger beside it, the auto-dream sidecar is a full replacement body of the operator's private MEMORY.md, and the quality-gate and ux-grill artifacts can carry secrets or a rendered password. Each pattern below names one writer's file, its `.acquire` guard where it has one, and its own temp files (left behind only by a crash mid-write). Rotated and archived ledger copies (`*.jsonl.[0-9]*`, `*.jsonl.archive-*`, `metrics/_archive/`) are not on this list: they carry ledger history, and whether that is versioned is the consumer's call.
+`.orchestrator/` itself stays versioned: `bootstrap.lock`, `policy/`, `steering/`, `peers/` and the `.orchestrator/metrics/*.jsonl` ledgers are durable project data. What the plugin writes there at runtime is per-process state or a per-run artifact that a `git add -A` would otherwise commit — the session lock is rewritten on every SessionStart, every store rewrite leaves a full backup copy of the ledger beside it, the auto-dream sidecar is a full replacement body of the operator's private MEMORY.md, and the quality-gate and ux-grill artifacts can carry secrets or a rendered password. Each pattern below names one writer's file, its `.acquire` guard where it has one, and its own temp files (left behind only by a crash mid-write). Rotated and archived ledger copies (`*.jsonl.[0-9]*`, `*.jsonl.archive-*`, `metrics/_archive/`) are ignored too (owner decision 2026-10-03, #1507 Pkt 4): the live `*.jsonl` ledger is the versioned record, and the rotated history beside it is not.
 
 | Pattern(s) | Written by |
 |---|---|
@@ -360,7 +360,9 @@ Applied by Fast Step 3 (so by every tier), by the Upgrade Flow and by the Refres
 | `.orchestrator/staging-fence/` | the staging-fence commit mutex and intent log |
 | `.orchestrator/tmp/` | machine-local scratch: lock-reaper archives of reaped session locks (`tmp/reaped-locks/`, carrying host name, pid and session ids), worktree metadata (`tmp/worktree-meta/`), the orphan-reaper throttle marker (`tmp/reaper-last-scan`) |
 | `.orchestrator/metrics/*.jsonl.bak.*` | the legacy evolve backup `learnings.jsonl.bak.evolve-<ts>`, a full store copy still on disk in older repos (`scripts/lib/learnings/io.mjs`) |
+| `.orchestrator/metrics/*.jsonl.[0-9]*`, `.orchestrator/metrics/*.jsonl.archive-*`, `.orchestrator/metrics/_archive/` | rotated ledger history of the events log (`scripts/lib/events.mjs`): the legacy numbered `events.jsonl.<n>` slots, older `*.jsonl.archive-*` copies and the `_archive/` directory of rotated `events-<first>_<last>.jsonl` files (`scripts/lib/events-schema.mjs`); the live `*.jsonl` ledgers stay versioned |
 | `.orchestrator/metrics/*.jsonl.tmp-*` | atomic-write temp files of the ledgers (`scripts/lib/autopilot/telemetry.mjs`), left behind only by a crash |
+| `.orchestrator/metrics/.*.tmp.*` | temp files of the shared atomic writers (`scripts/lib/io.mjs`, named `.<base>.tmp.<hex>`), left behind only by a crash |
 | `.orchestrator/pending-dream.md` | the auto-dream sidecar — a full replacement body of the private MEMORY.md (`scripts/lib/auto-dream.mjs`) |
 | `.orchestrator/dialectic-pending.md`, `.orchestrator/dialectic-last-run`, `.orchestrator/consumed/` | the auto-dialectic sidecar, its last-run timestamp and the archive of consumed sidecars (`scripts/lib/auto-dialectic.mjs`) |
 | `.orchestrator/promoted-from.json` | the worktree-promotion marker, a per-worktree fact (`scripts/lib/autopilot/worktree-pipeline.mjs`, read by `scripts/lib/session-end/worktree-cleanup.mjs`) |
@@ -396,7 +398,8 @@ _GI_PATTERNS=(
   '.orchestrator/metrics/proposals-write.lock*' '.orchestrator/metrics/.proposals-write.lock.*'
   '.orchestrator/staging-fence/'
   '.orchestrator/tmp/'
-  '.orchestrator/metrics/*.jsonl.bak.*' '.orchestrator/metrics/*.jsonl.tmp-*'
+  '.orchestrator/metrics/*.jsonl.bak.*' '.orchestrator/metrics/*.jsonl.tmp-*' '.orchestrator/metrics/.*.tmp.*'
+  '.orchestrator/metrics/*.jsonl.[0-9]*' '.orchestrator/metrics/*.jsonl.archive-*' '.orchestrator/metrics/_archive/'
   '.orchestrator/pending-dream.md'
   '.orchestrator/dialectic-pending.md' '.orchestrator/dialectic-last-run' '.orchestrator/consumed/'
   '.orchestrator/promoted-from.json'

package/skills/claude-md-drift-check/SKILL.md

@@ -9,6 +9,7 @@ description: >
   globs), and docs-parity (docs/components.md count-claims vs on-disk counts, template-vs-reference
   config-key parity, stale .claude/metrics/ paths). Full per-check spec in the body table. Invoked as an
   opt-in session-end phase; mirrors vault-sync's lean JSON+exit-code contract.
+user-invocable: false
 model: haiku
 ---
 
@@ -37,7 +38,7 @@ PHASE 1 IMPLEMENTED (2026-04-19). Session-end opt-in quality gate. Upstream of `
 | 2 | `project-count-sync` | Hardcoded "N registered" / "N projects" claims next to `01-projects/` | compare to `ls -d 01-projects/*/` |
 | 3 | `issue-reference-freshness` | `#NN` in forward-looking sections (What's Next, Backlog, Open Issues, Offene Themen, Todo, Next Steps) | `glab issue view NN --repo <origin>` |
 | 4 | `session-file-existence` | `50-sessions/YYYY-MM-DD-*.md` references anywhere in scope | `existsSync(vault/50-sessions/<file>)` |
-| 5 | `command-count` | "N commands" / "N /commands" claims in prose | compare to the name-deduplicated union of `commands/*.md` and skills with explicit `user-invocable: true`; skipped only when both directories are absent |
+| 5 | `command-count` | "N commands" / "N /commands" claims in prose | compare to the name-deduplicated union of `commands/*.md` and skills whose `user-invocable` is `true` or absent (Claude Code picker semantics, #1515); skipped only when both directories are absent |
 | 6 | `session-config-parity` | Top-level keys under `## Session Config` in `CLAUDE.md` / `AGENTS.md` | diff against `docs/session-config-template.md`; a missing MANDATORY (minimal-baseline) key is an error, a missing OPT-IN-baseline-only key is a note, a local key absent from the template's Session Config blocks is a warning |
 | 7 | `vault-dir-parity` | `vault-integration.vault-dir` in BOTH `CLAUDE.md` AND `AGENTS.md` | reuse `_parseVaultIntegration`; flag when the two files disagree. Short-circuits to PASS when the two are the SAME file by construction (symlink / same inode / byte-identical generated copy) |
 | 8 | `generated-rule-staleness` *(WARN only)* | `.claude/rules/*.md` with `auto-generated: true` frontmatter | extract `learning-key`; WARN when the key is absent from `.orchestrator/metrics/learnings.jsonl` or its learning's `expires_at` is in the past; skipped silently when no auto-generated rules exist |
@@ -61,6 +62,8 @@ A local CLAUDE.md / AGENTS.md that omits any of these surfaces a `session-config
 
 Check 7 (issue #600) is the **only** check that intentionally reads BOTH instruction files rather than the single alias-resolved one. The alias rule (CLAUDE.md wins ties, AGENTS.md is the Codex alias) means `resolveInstructionFile()` picks exactly one — so a repo carrying both files can silently let `AGENTS.md` drift out of sync with `CLAUDE.md`. A sibling project ran for weeks with a correct `vault-integration.vault-dir` in `CLAUDE.md` and a dead path in `AGENTS.md`. Check 7 reads `vault-integration.vault-dir` from each file (reusing the `_parseVaultIntegration` parser from `scripts/lib/config/vault-integration.mjs` — no hand-rolled YAML) and flags a `vault-dir-parity` error when the two values diverge (the error is attributed to `AGENTS.md`, the secondary alias, and names both values). The check skips gracefully when only one instruction file is present (nothing to compare), when neither file declares a `vault-integration:` block, or when explicitly disabled via `--skip-vault-dir-parity`. Two files that both omit `vault-dir` (both unset) agree and pass.
 
+**Runtime override caveat.** `SO_CONFIG_FILE=AGENTS.md` reads a config-free `@CLAUDE.md` pointer as raw text; `parse-config.mjs` does not follow its import. Check 7 accepting that pointer does not prove an effective runtime config. Set the override to the config-bearing file (for example, `SO_CONFIG_FILE=CLAUDE.md`).
+
 **Alias-by-construction short-circuit.** Since this repo's root `AGENTS.md` became a GENERATED byte-identical copy of `CLAUDE.md` (`scripts/generate-agents-skills.mjs`), Check 7 no longer skips here — it RUNS on every invocation. Two files that cannot disagree have nothing to diff, so the check reports parity as satisfied without deriving one: `instructionFilesAreAliased()` recognises a symlink resolving to the same path, the same inode/device (hardlink or already-resolved symlink), and byte-identical content. Branch order is load-bearing: the "neither file has a `vault-integration:` block" skip is evaluated FIRST, because an absent subject is a different (and more informative) outcome than "the files cannot disagree". The error class the check exists for is untouched — two INDEPENDENT files that declare different `vault-dir` values still produce the `vault-dir-parity` error attributed to `AGENTS.md`.
 
 The same predicate guards Check 9's probe 2a, which iterates `['CLAUDE.md', 'AGENTS.md']`: with an aliased `AGENTS.md` it scans `CLAUDE.md` only, because otherwise every dangling `.claude/rules/*.md` citation would be reported TWICE — one defect, two errors, and in `--mode strict` a doubled blocking surface against a file the operator is not allowed to edit.