session-orchestrator 5.4.0 → 5.5.0

package/scripts/lib/vault-mirror/render-learnings.mjs

@@ -1,7 +1,8 @@
 /**
  * render-learnings.mjs — Learning markdown generators for vault-mirror (Issue #283 split).
  *
- * Exports: detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2
+ * Exports: detectLearningSchema, normalizeLearningEntry, generateLearningNote, generateLearningNoteV2,
+ *          sourceRecordValue, learningSourceRecord, sourceRecordLine (#1503)
  */
 
 import { toDate, truncateAtWord, yamlQuoteIfNeeded, subjectToSlug, isValidSlug, buildTag, resolveSourceSessionLink } from './utils.mjs';
@@ -18,6 +19,63 @@ export function detectLearningSchema(entry) {
   return entry && typeof entry.text === 'string' ? 'v2' : 'v1';
 }
 
+/**
+ * Characters a `source-record:` value may carry (#1503). The value is always
+ * written double-quoted, and BOTH readers of it — the vault-sync YAML loader and
+ * the line-based `parseFrontmatter` in utils.mjs, which only strips the
+ * surrounding quotes and never unescapes — must read back exactly the string
+ * that was rendered. Excluding `"`, `\`, whitespace and anything non-ASCII is
+ * what makes that round trip lossless without an escaping scheme. Record uuids,
+ * kebab ids, session uuids and ISO timestamps all fit.
+ */
+const SOURCE_RECORD_RE = /^[A-Za-z0-9][A-Za-z0-9._:+@/-]{0,199}$/;
+
+/**
+ * Normalise one candidate `source-record` value (#1503): the identity of the
+ * JSONL record a vault note was rendered from. Returns `null` for anything that
+ * cannot round-trip through the frontmatter (see {@link SOURCE_RECORD_RE}) — the
+ * line is then omitted and the record-level ownership check is skipped for that
+ * entry, which is the same "absent = allow" reading an old note gets.
+ *
+ * Shared by both renderers so the rendered value and the value process.mjs
+ * compares against come from ONE derivation.
+ *
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function sourceRecordValue(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return SOURCE_RECORD_RE.test(trimmed) ? trimmed : null;
+}
+
+/**
+ * The `source-record` of a learning note: the record's own `id` (a uuid for v1
+ * producers, the kebab id for v2 and for alias producers whose id was derived
+ * from the subject by {@link normalizeLearningEntry}).
+ *
+ * Named ceiling: a derived id IS the subject slug, so two repos holding the same
+ * subject under derived ids render the same `source-record` and this field
+ * cannot tell them apart — `source-repo` and the CLI's repo-root resolution are
+ * what separate those.
+ *
+ * @param {object} entry - normalized learning entry.
+ * @returns {string|null}
+ */
+export function learningSourceRecord(entry) {
+  return sourceRecordValue(entry?.id);
+}
+
+/**
+ * Render the `source-record:` frontmatter line, or `''` when the entry has no
+ * representable record key.
+ * @param {string|null} value - output of {@link sourceRecordValue}.
+ * @returns {string}
+ */
+export function sourceRecordLine(value) {
+  return value === null ? '' : `source-record: "${value}"\n`;
+}
+
 const firstString = (...vals) => vals.find((v) => typeof v === 'string' && v.length > 0);
 
 const joinList = (v) =>
@@ -112,6 +170,9 @@ export function generateLearningNote(entry, slug, opts = {}) {
   // vault-sync schema declares source-repo OPTIONAL).
   const sourceRepoLine =
     typeof opts.repoNs === 'string' && opts.repoNs.length > 0 ? `source-repo: ${opts.repoNs}\n` : '';
+  // #1503: the record this note was rendered from — process.mjs refuses to
+  // overwrite a note whose `source-record` names a different record.
+  const recordLine = sourceRecordLine(learningSourceRecord(entry));
 
   // source_session is emitted as an Obsidian wikilink ONLY when source_session
   // resolves to a real, mirror-able session id (semantic or UUID-v4). Anything
@@ -132,7 +193,7 @@ created: ${created}
 updated: ${updated}
 tags: ${tags}
 source_session: ${sourceSessionLink}
-${expiresLine}${sourceRepoLine}_generator: ${GENERATOR_MARKER}
+${expiresLine}${sourceRepoLine}${recordLine}_generator: ${GENERATOR_MARKER}
 ---
 
 # ${titleRaw}
@@ -176,6 +237,8 @@ export function generateLearningNoteV2(entry, slug, opts = {}) {
   // opts.repoNs (see generateLearningNote for the full contract). Backward-compatible.
   const sourceRepoLine =
     typeof opts.repoNs === 'string' && opts.repoNs.length > 0 ? `source-repo: ${opts.repoNs}\n` : '';
+  // #1503: see generateLearningNote.
+  const recordLine = sourceRecordLine(learningSourceRecord(entry));
 
   return `---
 id: ${slug}
@@ -185,7 +248,7 @@ status: ${status}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
-${sourceRepoLine}_generator: ${GENERATOR_MARKER}
+${sourceRepoLine}${recordLine}_generator: ${GENERATOR_MARKER}
 ---
 
 # ${titleRaw}

package/scripts/lib/vault-mirror/render-sessions.mjs

@@ -1,7 +1,8 @@
 /**
  * render-sessions.mjs — Session markdown generators for vault-mirror (Issue #283 split).
  *
- * Exports: detectSessionSchema, normalizeSessionEntry, generateSessionNote, generateSessionNoteV2, generateSessionNoteV3
+ * Exports: detectSessionSchema, normalizeSessionEntry, generateSessionNote, generateSessionNoteV2, generateSessionNoteV3,
+ *          sessionSourceRecord (#1503)
  *
  * #732: all three generators accept `options.repoNs` (the leak-guarded /
  * pseudonym-mapped namespace segment from resolveRepoNamespace(), threaded
@@ -15,6 +16,7 @@
  */
 
 import { toDate, buildTag, slugifyIdSafe } from './utils.mjs';
+import { sourceRecordValue, sourceRecordLine } from './render-learnings.mjs';
 
 const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
 
@@ -282,6 +284,28 @@ function fmLine(key, value) {
   return `${key}: ${value}\n`;
 }
 
+/**
+ * The `source-record` of a session note (#1503): the physical session the note
+ * was rendered from — `raw_session_id` (the harness's session uuid) when the
+ * record carries one, else `started_at`. `session_id` itself cannot serve: it is
+ * the FILENAME, and semantic ids such as `main-2026-10-02-session-1` recur across
+ * repos by construction, which is exactly the collision this field exists to
+ * detect. All three generators require `started_at`, so every renderable record
+ * has a key.
+ *
+ * Named ceiling: a record whose key changes between runs — a later backfill
+ * adding `raw_session_id` to a record first mirrored under its `started_at` —
+ * reads as a different record, and process.mjs then refuses the rewrite
+ * (`skipped-foreign-owner`, visible on stdout). Revisit if that is ever observed
+ * on a same-repo record.
+ *
+ * @param {object} entry - normalized session entry.
+ * @returns {string|null}
+ */
+export function sessionSourceRecord(entry) {
+  return sourceRecordValue(entry?.raw_session_id) ?? sourceRecordValue(entry?.started_at);
+}
+
 /**
  * Session JSONL has three producer schemas in production:
  *   v1 (legacy):  total_waves, total_agents, total_files_changed, agent_summary, waves[{agent_count, files_changed, quality}]
@@ -521,7 +545,7 @@ status: ${vaultStatus}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
-${fmLine('source-repo', repoNs)}_generator: ${GENERATOR_MARKER}
+${fmLine('source-repo', repoNs)}${sourceRecordLine(sessionSourceRecord(entry))}_generator: ${GENERATOR_MARKER}
 ---
 
 # Session ${session_id}
@@ -606,7 +630,7 @@ status: ${vaultStatus}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
-${fmLine('source-repo', repoNs)}_generator: ${GENERATOR_MARKER}
+${fmLine('source-repo', repoNs)}${sourceRecordLine(sessionSourceRecord(entry))}_generator: ${GENERATOR_MARKER}
 ---
 
 # Session ${session_id}
@@ -731,7 +755,7 @@ status: ${vaultStatus}
 created: ${created}
 updated: ${updated}
 tags: ${tags}
-${fmLine('source-repo', repoNs)}_generator: ${GENERATOR_MARKER}
+${fmLine('source-repo', repoNs)}${sourceRecordLine(sessionSourceRecord(entry))}_generator: ${GENERATOR_MARKER}
 ---
 
 # Session ${session_id}

package/scripts/lib/vault-mirror/telemetry.mjs

@@ -15,6 +15,12 @@
  *     a `--kind session` line whose `session_id` a later line in the same
  *     source superseded, so it was never dispatched. It carries `record_id`
  *     and `line` and never `path` — no target file exists for it.
+ *     `skipped-foreign-owner` (#1503) is another: the generator note at the
+ *     target path names a different owner (a `source-record` the writer's
+ *     ledger does not carry, or a different session id), so it was left
+ *     untouched — unless it still leaks a secret, which is healed over the
+ *     guard. It carries the refused note's `path` and a constant `reason`
+ *     (`source-record mismatch` / `id mismatch`).
  *   - `orchestrator.vault.mirror_run_completed` — ONE record per CLI run,
  *     carrying the DENOMINATOR (`total` plus the per-class counts).
  *
@@ -25,8 +31,8 @@
  * "a rule you cannot falsify is not a rule"). The run event is emitted
  * unconditionally — including on every abort path, where it carries an
  * `aborted` discriminator (`missing-vault-dir` | `vault-not-canonical` |
- * `missing-source` | `malformed-json` | `filesystem-error` |
- * `unexpected-error`). So `total: 0` is a MEASURED zero, a partial count is a
+ * `missing-source` | `source-repo-mismatch` | `malformed-json` |
+ * `filesystem-error` | `unexpected-error`). So `total: 0` is a MEASURED zero, a partial count is a
  * LABELLED partial rather than a silent one, and the record's absence — and
  * nothing else — is the broken-emitter signal.
  *
@@ -36,9 +42,10 @@
  *
  * Ledger destination: `emitEvent` is called 2-arg, so every event from one run
  * resolves the SAME destination (`SO_PROJECT_DIR`, i.e. `CLAUDE_PROJECT_DIR` or
- * the CWD walk-up) as the masker emit. This CLI has no repo-root flag and
- * deriving one from `--source` would split a single run's telemetry across two
- * ledgers.
+ * the CWD walk-up) as the masker emit. The repo root that decides the vault
+ * NAMESPACE (#1503: `--repo-root`, else the git repo containing `--source`) is
+ * deliberately NOT used for the ledger — routing telemetry by it would split a
+ * single run's records across two ledgers.
  */
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
@@ -166,7 +173,7 @@ export async function emitMirrorEvent({
  * @param {number} opts.updated — entries whose action was `updated`.
  * @param {number} opts.skipped — entries skipped for a NON-failure reason
  *   (`skipped-noop`, `skipped-handwritten`, `skipped-quality-low`,
- *   `skipped-collision-resolved`, `skipped-abandoned`,
+ *   `skipped-collision-resolved`, `skipped-foreign-owner`, `skipped-abandoned`,
  *   `skipped-duplicate-session`). The last one (#1291) is what keeps
  *   `created + updated + skipped + failed === total` true for a `--kind
  *   session` run whose dedup pass collapsed a duplicate `session_id` line.
@@ -176,13 +183,13 @@ export async function emitMirrorEvent({
  * @param {Record<string, number>} [opts.actionBreakdown] — per-action counts;
  *   only actions observed at least once appear.
  * @param {boolean} opts.dryRun — whether this run wrote anything at all.
- * @param {'missing-vault-dir'|'vault-not-canonical'|'missing-source'|'malformed-json'|'filesystem-error'|'unexpected-error'} [opts.aborted]
+ * @param {'missing-vault-dir'|'vault-not-canonical'|'missing-source'|'source-repo-mismatch'|'malformed-json'|'filesystem-error'|'unexpected-error'} [opts.aborted]
  *   Present ONLY when the run exited before its normal tail. OMITTED on a
  *   complete run — absent means "ran to the end", never "unknown". The first
- *   three values are PRE-LOOP aborts (#1151): the run never reached its first
- *   entry, so all five counters are `0` and that zero is the point — without a
- *   record, a mirror that never started is indistinguishable from one that was
- *   never invoked.
+ *   four values are PRE-LOOP aborts (#1151, #1503): the run never reached its
+ *   first entry, so all five counters are `0` and that zero is the point —
+ *   without a record, a mirror that never started is indistinguishable from one
+ *   that was never invoked.
  * @returns {Promise<void>}
  */
 export async function emitMirrorRunEvent({

package/scripts/lib/vault-status/board-writer.mjs

@@ -360,8 +360,12 @@ export async function collectRows({ repos, now = new Date(), registry, priorStat
       ? lock.mode
       : (registryEntry && registryEntry.mode ? registryEntry.mode : null);
 
+    // The "Last heartbeat" column shows a heartbeat or nothing: a lock without
+    // `last_heartbeat` renders '—', never its `started_at` under that label
+    // (#595 sunset, 2026-10-02 — `isLockLive()` already calls it not live, so
+    // the status derivation below treats it as a dead lease).
     const heartbeat = lock
-      ? (lock.last_heartbeat ?? lock.started_at ?? null)
+      ? (lock.last_heartbeat ?? null)
       : (registryEntry ? (registryEntry.last_heartbeat ?? null) : null);
 
     // ── Status derivation ──

package/scripts/lib/vcs-repo-spec.mjs

@@ -160,6 +160,14 @@ export function stripUrlCredentials(url) {
  * `--repo <spec>` override path, which bypasses the source-level strip in
  * {@link resolveRawRemoteUrl}. Never throws; a non-string returns unchanged.
  *
+ * Scope is CREDENTIALS only, as {@link userinfoIsCredential} classifies them.
+ * A bare login on a non-HTTP scheme (`ssh://alice@host/…`) is left verbatim,
+ * the URL path is never touched (`ssh://***@host/home/alice/vault` keeps the
+ * remote home dir), and the scp-like `user@host:path` form is not matched at
+ * all. So this is NOT the scp-consistent origin renderer: `describeOriginForLog`
+ * (`named-vault-resolver.mjs`) redacts every non-`git` login in both forms and
+ * hides a home-dir path (#1490) — use that for a git origin in a log line.
+ *
  * @param {string} text
  * @returns {string}
  */

package/scripts/materialize-wave-scope.mjs

@@ -26,7 +26,7 @@ import { existsSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { writeJsonAtomicSync } from './lib/io.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
-import { isPeerRecordId } from './lib/scope-gate.mjs';
+import { COORDINATOR_RECORD_ID, isCoordinatorRecordId, isPeerRecordId } from './lib/scope-gate.mjs';
 import { SCOPE_MATERIALIZED_EVENT, scopeDigest } from './lib/scope-echo.mjs';
 import {
   MANIFEST_SESSION_KEYS,
@@ -214,8 +214,8 @@ export function validateScopeRecords(value) {
       throw new InputError(`record #${recordIndex} has duplicate id (case-insensitive): ${record.id}`);
     }
     seenIds.add(idKey);
-    if (idKey === 'coordinator') {
-      if (record.id !== 'coordinator') {
+    if (idKey === COORDINATOR_RECORD_ID) {
+      if (!isCoordinatorRecordId(record.id)) {
         throw new InputError(`record #${recordIndex} id must be exactly coordinator (lowercase)`);
       }
       coordinatorCount++;
@@ -537,7 +537,10 @@ export function transportObservable(pluginRoot = resolve(import.meta.dirname, '.
 async function emitScopeMaterialized({ stateDir, wave, records }) {
   try {
     const repoRoot = dirname(resolve(stateDir));
-    const agentRecords = records.filter((r) => !isPeerRecordId(r.id));
+    // Dispatched agents only: a peer's record gets no per-agent file, and the
+    // coordinator's is a declaration no dispatch carries — counted, its empty
+    // `files` (the common case) read as "two agents share one scope" (#1493.2).
+    const agentRecords = records.filter((r) => !isPeerRecordId(r.id) && !isCoordinatorRecordId(r.id));
     const digests = new Set();
     for (const record of agentRecords) {
       if (Array.isArray(record.files) && record.files.length > 0) digests.add(scopeDigest(record.files));

package/scripts/release.mjs

@@ -1681,6 +1681,7 @@ export function printPublishOutcome(outcome, target, io = {}) {
   log('\nPost-release checklist (manual):');
   log('  1. Rotate/delete the npm token: https://www.npmjs.com/settings/<user>/tokens');
   log('  2. pi.dev gallery indexes asynchronously — do not block on it.');
+  log('  3. Install the release on this host: npm run update:local -- --skip-pull, then restart the harness.');
   return 0;
 }
 

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

@@ -502,12 +502,24 @@ process.stderr.write(
     `${aggregate.totalStillInvalidPost} still-invalid\n`
 );
 
+let exitCode = 0;
 if (lockFailedRepos.length > 0) {
   process.stderr.write(
     `run-migrate-v2: ERROR learnings store lock not acquired, nothing written in ${lockFailedRepos.length} repo(s): ` +
       `${lockFailedRepos.join(', ')}\n`
   );
-  process.exit(2);
+  exitCode = 2;
 }
 
-process.exit(0);
+// #1487.15: every other `status: 'error'` (read failed / write failed) is an
+// I/O error too — exit 2 as the header and --help document, never 0.
+const ioFailed = results.filter((r) => r.status === 'error' && !lockFailedRepos.includes(r.repo));
+if (ioFailed.length > 0) {
+  process.stderr.write(
+    `run-migrate-v2: ERROR I/O error in ${ioFailed.length} repo(s): ` +
+      `${ioFailed.map((r) => `${r.repo} (${r.error})`).join(', ')}\n`
+  );
+  exitCode = 2;
+}
+
+process.exit(exitCode);

package/scripts/run-quality-gate.mjs

@@ -55,8 +55,8 @@ import {
   resolveGateTimeoutMs,
 } from './lib/gates/gate-helpers.mjs';
 import { buildCommandSignature, spawnInGroup } from './lib/process-group.mjs';
-import { readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
-import { findScopeFile } from './lib/scope-gate.mjs';
+import { classifyManifestSession, readProcessLocalSessionIds } from './lib/session-identity/own-session.mjs';
+import { findOwnScopeFile } from './lib/scope-gate.mjs';
 import { gateKillFields } from './lib/quality-gate.mjs';
 import { isMainModule } from './lib/is-main-module.mjs';
 import { shellQuote } from './lib/sh-quote.mjs';
@@ -271,8 +271,10 @@ function resolveLedgerRoot(value) {
  *
  * Mirrors `resolveWave()` in `hooks/pre-bash-memory-propose-audit.mjs` — the
  * same `.{pi,cursor,codex,claude}/wave-scope.json` precedence via
- * {@link findScopeFile} — with ONE deliberate difference: the hook returns `0`
- * for "no wave-scope file", this returns `null`.
+ * {@link findOwnScopeFile}, skipping a PEER session's manifest in the same
+ * working copy (#1504: a peer-only result is no wave of ours, never the peer's
+ * number) — with ONE deliberate difference: the hook returns `0` for "no
+ * wave-scope file", this returns `null`.
  *
  * Absent is not zero. A human running `npm run quality-gate` from a `git push`
  * has no wave at all, and that is the common case; publishing `wave_number: 0`
@@ -289,7 +291,8 @@ function resolveLedgerRoot(value) {
  */
 function resolveWaveNumber(projectDir) {
   try {
-    const waveFile = findScopeFile(projectDir);
+    const ownIds = new Set(readProcessLocalSessionIds({ env: process.env, hookInput: null }));
+    const { path: waveFile } = findOwnScopeFile(projectDir, ownIds, classifyManifestSession);
     if (!waveFile || !existsSync(waveFile)) return null;
     const wave = JSON.parse(readFileSync(waveFile, 'utf8'))?.wave;
     if (typeof wave !== 'number' || !Number.isFinite(wave) || wave <= 0) return null;

package/scripts/self-update.mjs

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * Bring every LOCAL install of Session Orchestrator to the newest version in
+ * one command: this clone, the Claude Code plugin, and the Codex plugin.
+ *
+ * WHY THIS EXISTS: an update was three independent manual acts, and the
+ * second one has a silent hole. Measured 2026-10-02 (5.3.0 → 5.4.0, Claude
+ * Code 2.1.287): `claude plugin update` succeeded but left the cache WITHOUT
+ * node_modules — `claude plugin list --json` carried
+ * `noteDetails: [{type: "dependencies-refused"}]` because package.json sets
+ * `overrides`. Hooks survive that (no static third-party imports), skill
+ * scripts and the MCP server do not. This script reads that state back and
+ * installs the runtime dependencies itself.
+ *
+ * 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.
+ *   3. codex   — only if the plugin is already installed in Codex: re-run
+ *                scripts/codex-install.mjs (refreshes the installed bundle).
+ *
+ * Never deletes an old plugin cache directory: the running session still
+ * loads it until the harness restarts.
+ *
+ * Exit codes: 0 all steps ok/skipped · 1 usage error · 2 a step failed.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+import { isMainModule } from './lib/is-main-module.mjs';
+
+const SO_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const PLUGIN_ID = 'session-orchestrator@kanevry';
+const MARKETPLACE = 'kanevry';
+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;
+
+/**
+ * Pick the session-orchestrator entry from `claude plugin list --json`.
+ * Accepts both the bare-array and the `{plugins: [...]}` shape.
+ * @param {unknown} listJson
+ * @returns {{version?: string, installPath?: string, enabled?: boolean, noteDetails?: Array<{type?: string}>} | null}
+ */
+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)
+    ?? null;
+}
+
+/**
+ * Runtime dependencies of the package at `dir` that have no directory under
+ * `dir/node_modules`. A presence check, not a version check: its job is to
+ * catch the harness having skipped the install entirely.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+export function missingRuntimeDeps(dir) {
+  const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  return Object.keys(pkg.dependencies ?? {})
+    .filter((name) => !existsSync(path.join(dir, 'node_modules', name)));
+}
+
+function parseArguments(argv) {
+  const opts = { dryRun: false, json: false, skipPull: false, help: false };
+  for (const arg of argv) {
+    if (arg === '--dry-run') opts.dryRun = true;
+    else if (arg === '--json') opts.json = true;
+    else if (arg === '--skip-pull') opts.skipPull = true;
+    else if (arg === '--help' || arg === '-h') opts.help = true;
+    else throw Object.assign(new Error(`Unknown argument '${arg}'. Run with --help.`), { usage: true });
+  }
+  return opts;
+}
+
+const HELP = `Usage: node scripts/self-update.mjs [--dry-run] [--skip-pull] [--json]
+
+Update this clone, the Claude Code plugin and (if installed) the Codex plugin
+to the newest Session Orchestrator, and verify each one afterwards.
+
+  --dry-run    Print what would run; change nothing
+  --skip-pull  Leave the clone as it is (e.g. right after a release)
+  --json       Print the per-step result as JSON
+`;
+
+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 } = {}) {
+    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 });
+    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)}` };
+    }
+    return { ok: true, stdout: r.stdout };
+  }
+  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 updateRepo({ run, log }, opts) {
+  if (opts.skipPull) return { step: 'repo', status: 'skipped', detail: '--skip-pull' };
+  const before = run('git', ['rev-parse', 'HEAD'], { mutates: false });
+  if (!before.ok) return { step: 'repo', status: 'failed', detail: before.detail };
+  const branch = run('git', ['branch', '--show-current'], { mutates: false }).stdout?.trim();
+  if (branch !== 'main') {
+    return { step: 'repo', status: 'failed', detail: `clone is on '${branch}', not main — switch or use --skip-pull` };
+  }
+  log('repo: fetching origin and fast-forwarding main');
+  for (const [cmd, args] of [['git', ['fetch', 'origin']], ['git', ['merge', '--ff-only', 'origin/main']]]) {
+    const r = run(cmd, args);
+    if (!r.ok) return { step: 'repo', status: 'failed', detail: r.detail };
+  }
+  const after = run('git', ['rev-parse', 'HEAD'], { mutates: false });
+  const moved = before.stdout !== after.stdout;
+  if (moved || !existsSync(path.join(SO_ROOT, 'node_modules'))) {
+    const r = run('npm', ['ci']);
+    if (!r.ok) return { step: 'repo', status: 'failed', detail: r.detail };
+  }
+  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 };
+  }
+  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}` };
+  }
+  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}` };
+  }
+  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 };
+    const still = opts.dryRun ? [] : missingRuntimeDeps(entry.installPath);
+    if (still.length > 0) return { step: 'claude', status: 'failed', detail: `still missing after npm ci: ${still.join(', ')}` };
+  }
+  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` : '';
+  return {
+    step: 'claude',
+    status: 'ok',
+    detail: `${entry.version}${missing.length ? `, installed ${missing.length} missing deps` : ''}${lag}`,
+  };
+}
+
+function updateCodex({ run, log }, opts) {
+  if (!onPath('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)) {
+    return { step: 'codex', status: 'skipped', detail: 'plugin not installed in Codex (install: node scripts/codex-install.mjs)' };
+  }
+  log('codex: re-running codex-install');
+  const r = run(process.execPath, [path.join(SO_ROOT, 'scripts', 'codex-install.mjs'), '--json']);
+  if (!r.ok) return { step: 'codex', status: 'failed', detail: r.detail };
+  if (opts.dryRun) return { step: 'codex', status: 'ok', detail: 'dry-run' };
+  try {
+    return { step: 'codex', status: 'ok', detail: JSON.parse(r.stdout).pluginVersion };
+  } catch {
+    return { step: 'codex', status: 'ok', detail: 'installed (version not reported)' };
+  }
+}
+
+function main(opts) {
+  const io = makeRunner(opts);
+  const results = [];
+  // Order matters: the Codex installer installs FROM this clone, so the clone
+  // must be current first. A failed repo step stops the chain for that reason.
+  results.push(updateRepo(io, opts));
+  if (results[0].status !== 'failed') {
+    results.push(updateClaude(io, opts));
+    results.push(updateCodex(io, opts));
+  }
+  const ok = results.every((r) => r.status !== 'failed');
+  if (opts.json) {
+    process.stdout.write(`${JSON.stringify({ ok, dryRun: opts.dryRun, results }, null, 2)}\n`);
+  } else {
+    io.log('');
+    for (const r of results) io.log(`  ${r.status.padEnd(7)} ${r.step.padEnd(7)} ${r.detail}`);
+    io.log(ok
+      ? '\nRestart Claude Code / Codex to load the new version. Old cache folders stay until then — delete them only after the restart.'
+      : '\nA step failed (a failed repo step skips the plugin steps). Fix it and re-run — every step is idempotent.');
+  }
+  return ok ? 0 : 2;
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const opts = parseArguments(process.argv.slice(2));
+    if (opts.help) process.stdout.write(HELP);
+    else process.exitCode = main(opts);
+  } catch (error) {
+    process.stderr.write(`ERROR: ${error.message}\n`);
+    process.exitCode = error.usage ? 1 : 2;
+  }
+}