session-orchestrator 5.6.0 → 5.8.0

package/scripts/mcp-server.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/** Native, dependency-free MCP stdio transport. No shell, WSL, or jq required. */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { isSessionConfigHeading } from './lib/config/section-extractor.mjs';
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const SERVER_INFO = { name: 'session-orchestrator', version: '2.0.0' };
+const TOOLS = [
+  {
+    name: 'session_config',
+    description: 'Reads Session Config section from the project instruction file (CLAUDE.md or AGENTS.md alias)',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'session_metrics',
+    description: 'Reads the last 5 REAL session metrics entries from .orchestrator/metrics/sessions.jsonl (abandoned phantom stubs excluded)',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+];
+const textContent = (text) => ({ content: [{ type: 'text', text }] });
+const errorResponse = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+
+/** Resolve the caller's repository without passing native paths through a shell. */
+export function resolveProjectRoot(cwd = process.cwd()) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd, encoding: 'utf8', windowsHide: true, timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function isFile(path, nonempty = false) {
+  try {
+    const stat = statSync(path);
+    return stat.isFile() && (!nonempty || stat.size > 0);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+    throw error;
+  }
+}
+
+/** Read the same raw config body as the legacy shell tool (including comments). */
+export function readSessionConfig(root) {
+  const file = ['CLAUDE.md', 'AGENTS.md'].map((name) => join(root, name))
+    .find((path) => isFile(path, true));
+  if (!file) return `No CLAUDE.md or AGENTS.md found at ${root}`;
+  const body = [];
+  let inSection = false;
+  for (const line of readFileSync(file, 'utf8').split('\n')) {
+    if (isSessionConfigHeading(line)) {
+      inSection = true;
+    } else if (line.startsWith('## ')) {
+      inSection = false;
+    } else if (inSection) {
+      body.push(line);
+    }
+  }
+  // Shell command substitution removes LF bytes, not spaces or CR bytes.
+  return body.join('\n').replace(/\n+$/, '') || `No '## Session Config' section found in ${file}`;
+}
+
+/** Read the last five real records, with whole-ledger stub count and token coverage. */
+export function readSessionMetrics(root) {
+  const file = ['.orchestrator', '.claude'].map((dir) => join(root, dir, 'metrics', 'sessions.jsonl'))
+    .find((path) => isFile(path));
+  if (!file) return 'No metrics found (checked .orchestrator/metrics/ and .claude/metrics/)';
+  const entries = [];
+  let stubCount = 0;
+  for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+    let record;
+    try { record = JSON.parse(line); } catch { continue; }
+    // Torn writes and non-record JSON must not hide subsequent valid sessions.
+    if (!record || typeof record !== 'object' || Array.isArray(record)) continue;
+    if (record.status === 'abandoned') { stubCount++; continue; }
+    entries.push(record);
+    if (entries.length > 5) entries.shift();
+  }
+  if (!entries.length) {
+    return stubCount ? `No real sessions (abandoned stubs excluded: ${stubCount})`
+      : 'No metrics found (file is empty)';
+  }
+  const record = entries.findLast((entry) => (entry.total_token_input !== null && entry.total_token_input !== undefined)
+    || (entry.total_token_output !== null && entry.total_token_output !== undefined));
+  const coverage = record?.subagents_with_tokens ?? 0;
+  const summary = record
+    ? `tokens: ${record.total_token_input ?? '?'} in / ${record.total_token_output ?? '?'} out`
+      + ` (coverage: ${coverage} subagents)`
+      + (coverage === 0 ? ' ⚠ partial — subagent token data missing; total is not a reliable cost estimate' : '')
+      + ` [session: ${record.session_id ?? 'unknown'}]`
+    : 'tokens: no token data in last 5 sessions (subagent telemetry not yet captured)';
+  return entries.map((entry) => JSON.stringify(entry)).join('\n')
+    + `\n\nabandoned stubs excluded: ${stubCount}\n\n--- token summary ---\n${summary}`;
+}
+
+/** Handle one JSON-RPC line. null means a notification or blank line, not a reply. */
+export function handleLine(line, { cwd = process.cwd(), resolveRoot = resolveProjectRoot } = {}) {
+  if (!line.trim()) return null;
+  let request;
+  try { request = JSON.parse(line); } catch { return errorResponse(null, -32700, 'Parse error'); }
+  if (!request || typeof request !== 'object' || Array.isArray(request)) {
+    return errorResponse(null, -32600, 'Invalid Request');
+  }
+  const hasId = Object.hasOwn(request, 'id');
+  const validId = request.id === null || typeof request.id === 'string' || typeof request.id === 'number';
+  const id = hasId && validId ? request.id : null;
+  if (request.jsonrpc !== '2.0' || typeof request.method !== 'string' || (hasId && !validId)) {
+    return errorResponse(id, -32600, 'Invalid Request');
+  }
+  if (!hasId || request.method.startsWith('notifications/')) return null;
+  let result;
+  switch (request.method) {
+    case 'initialize':
+      result = { protocolVersion: '2024-11-05', capabilities: { tools: {} }, serverInfo: SERVER_INFO };
+      break;
+    case 'tools/list':
+      result = { tools: TOOLS };
+      break;
+    case 'tools/call': {
+      const name = request.params?.name;
+      if (typeof name !== 'string') return errorResponse(id, -32602, 'Invalid tool name');
+      if (!TOOLS.some((tool) => tool.name === name)) return errorResponse(id, -32602, `Unknown tool: ${name}`);
+      try {
+        const root = resolveRoot(cwd);
+        result = textContent(root
+          ? (name === 'session_config' ? readSessionConfig(root) : readSessionMetrics(root))
+          : 'Error: not inside a git repository');
+      } catch {
+        return errorResponse(id, -32603, 'Unable to read session data');
+      }
+      break;
+    }
+    default:
+      return errorResponse(id, -32601, `Method not found: ${request.method}`);
+  }
+  return { jsonrpc: '2.0', id, result };
+}
+
+/** Start newline-delimited JSON-RPC on the supplied streams. */
+export async function serve({ input = process.stdin, output = process.stdout, cwd = process.cwd() } = {}) {
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  for await (const line of lines) {
+    const response = handleLine(line, { cwd });
+    if (response) output.write(`${JSON.stringify(response)}\n`);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  serve().catch(() => {
+    process.stderr.write('session-orchestrator: MCP stdio transport failed.\n');
+    process.exitCode = 2;
+  });
+}

package/scripts/migrate-sessions-jsonl.mjs

@@ -38,8 +38,9 @@
  *    "already_canonical":N,"unmappable":N,"parse_errors":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';
 import { isMainModule } from './lib/is-main-module.mjs';
 
@@ -422,11 +423,12 @@ async function main() {
   // Atomic write: backup → tmp → rename
   const iso = new Date().toISOString().replace(/[:.]/g, '-');
   const backupPath = `${args.file}.bak-${iso}`;
-  const tmpPath = join(dirname(args.file), `.${basename(args.file)}.migrate-tmp-${process.pid}`);
   try {
     copyFileSync(args.file, backupPath);
-    writeFileSync(tmpPath, outputLines.join('\n') + '\n', 'utf8');
-    renameSync(tmpPath, args.file);
+    const res = atomicWriteWithBackup(args.file, outputLines.join('\n') + '\n', {
+      tmpPrefix: `.${basename(args.file)}.tmp`,
+    });
+    if (!res.ok) throw envelopeToError(res);
     summary.backup = backupPath;
   } catch (err) {
     const hint = existsSync(backupPath)

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-applicable-rules.mjs

@@ -98,9 +98,9 @@
 import { parseArgs } from 'node:util';
 import { readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
-import { createHash } from 'node:crypto';
 
 import { findProjectRoot } from './lib/common.mjs';
+import { deriveFenceToken } from './lib/reconcile/sanitize.mjs';
 import { loadApplicableRules } from './lib/rule-loader.mjs';
 import { readHostClass } from './lib/autopilot/telemetry.mjs';
 import { resolveStateArtifactPath, resolveStateMdPath } from './lib/state-md.mjs';
@@ -218,30 +218,6 @@ function neutraliseWrapperForgeries(text) {
   return out;
 }
 
-/**
- * Derive this block's fence token from its own payload.
- *
- * Deterministic by construction (same input → same token), so the CLI's stdout
- * stays reproducible. The re-derivation loop makes the absence guarantee
- * STRUCTURAL rather than probabilistic: a token that literally occurred in the
- * payload would be forgeable in a closing tag, so we re-hash with a counter
- * until it does not occur. Each iteration is a fresh 32-bit draw against a
- * fixed payload, so termination is immediate in practice; the cap exists only
- * so a pathological input cannot spin, and its fallback (the full 64-hex
- * digest, which no realistic rule body contains) still satisfies the guarantee.
- *
- * @param {string} payload - the concatenated rule bodies this token must fence
- * @returns {string} a hex token provably absent from `payload`
- */
-function deriveFenceToken(payload) {
-  const digest = (salt) => createHash('sha256').update(`${salt}\n${payload}`).digest('hex');
-  for (let salt = 0; salt < 64; salt++) {
-    const token = digest(salt).slice(0, 8);
-    if (!payload.includes(token)) return token;
-  }
-  return digest(64);
-}
-
 /**
  * Render a rule's `src` attribute: repo-relative (an absolute path would print
  * the operator's home directory into every agent prompt) and reduced to a

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/release.mjs

@@ -387,6 +387,10 @@ const INTENTIONAL_TEST_ASSET_PATHS = new Set([
 // `scripts/lib/locks/index.mjs` is the one-cycle deprecation shim (5.2.0 CHANGELOG, Changed): its
 // runtime warning names the version it was deprecated IN, so it legitimately carries the previous
 // release literal until its 6.0.0 removal — version history by construction, not drift.
+// `site/_census.json` is deliberately NOT allowlisted: it carries a `"version"` field that
+// `--set-version` re-stamps (scripts/site-numbers.mjs --write, see the post-bump hint in main()),
+// so leaving it under the drift sweep makes the sweep double as its staleness gate — a census
+// not re-stamped after a bump fails `--check` instead of shipping the previous version.
 export const HISTORY_ALLOWLIST = /^(CHANGELOG\.md|README\.md|scripts\/lib\/locks\/index\.mjs|CLAUDE\.md|AGENTS\.md|CONTRIBUTING\.md|NOTICE|\.husky\/pre-push|docs\/|tests\/|skills\/npm-publish\/|skills\/architecture\/references\/domain-model\.md|skills\/autopilot\/SKILL\.md|scripts\/release\.mjs|\.orchestrator\/|site\/leaderboard\.json|site\/guide\/index\.html|site\/llms-full\.txt|skills\/release\/SKILL\.md|marketing\/remotion\/(?:README\.md|campaign\.json|render-receipt\.json|src\/ReleaseFilm\.tsx)$)/;
 
 /** Pure check over packed-entry lines. Returns violations: {name, line}[]. */

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)) {