session-orchestrator 3.22.0 → 3.24.0

package/scripts/lib/locks/staging-fence-lock.mjs

@@ -28,6 +28,7 @@ import path from 'node:path';
 import crypto from 'node:crypto';
 
 import { tryAcquireFileLock } from '../file-lock.mjs';
+import { hostnamesMatch, lockHostCandidate, stableHostname } from '../host-identity.mjs';
 import { nowIso, delay, parseLockBody } from './lock-body.mjs';
 
 // ---------------------------------------------------------------------------
@@ -67,7 +68,9 @@ function stagingFenceLockPathFor(repoRoot) {
 function buildStagingFenceLockBody({ holder }) {
   return {
     pid: process.pid,
+    // `host` raw + `host_id` normalised (#1072) — see buildStateLockBody.
     host: os.hostname(),
+    host_id: stableHostname(),
     acquiredAt: nowIso(),
     holder: typeof holder === 'string' && holder.length > 0 ? holder : `pid-${process.pid}`,
   };
@@ -178,7 +181,8 @@ export function releaseStagingFenceLock({ repoRoot, holder } = {}) {
 
   const ownerMatch = typeof holder === 'string' && holder.length > 0
     ? lock.holder === holder
-    : lock.pid === process.pid && lock.host === os.hostname();
+    // #1072: alias-aware host identity, not a raw os.hostname() comparison.
+    : lock.pid === process.pid && hostnamesMatch(lockHostCandidate(lock), os.hostname());
 
   if (!ownerMatch) {
     return { ok: false, reason: 'not-owner' };

package/scripts/lib/locks/state-md-lock.mjs

@@ -41,6 +41,7 @@ import crypto from 'node:crypto';
 
 import { _parseStateMdLock } from '../config/state-md-lock.mjs';
 import { tryAcquireFileLock } from '../file-lock.mjs';
+import { hostnamesMatch, lockHostCandidate, stableHostname } from '../host-identity.mjs';
 import { nowIso, delay, parseLockBody } from './lock-body.mjs';
 
 // ---------------------------------------------------------------------------
@@ -78,7 +79,11 @@ function stateLockPathFor(repoRoot) {
 function buildStateLockBody({ holder }) {
   return {
     pid: process.pid,
+    // `host` raw + `host_id` normalised (#1072). The written body comes from
+    // tryAcquireFileLock, which carries the same pair — this keeps the shape
+    // declared here truthful about what lands on disk.
     host: os.hostname(),
+    host_id: stableHostname(),
     acquiredAt: nowIso(),
     holder: typeof holder === 'string' && holder.length > 0 ? holder : `pid-${process.pid}`,
   };
@@ -224,7 +229,9 @@ export function releaseStateLock({ repoRoot, sessionId, holder } = {}) {
   const expectedHolder = holder ?? sessionId ?? null;
   const ownerMatch = expectedHolder !== null
     ? lock.holder === expectedHolder
-    : lock.pid === process.pid && lock.host === os.hostname();
+    // #1072: alias-aware host identity — a raw comparison strands the lock as
+    // 'not-owner' once os.hostname() flips spelling mid-session.
+    : lock.pid === process.pid && hostnamesMatch(lockHostCandidate(lock), os.hostname());
 
   if (!ownerMatch) {
     return { ok: false, reason: 'not-owner' };

package/scripts/lib/memory-banner.mjs

@@ -27,6 +27,7 @@ import { resolveMemoryDir } from './memory-paths.mjs';
 import { readDreamSignals } from './auto-dream.mjs';
 import { readPeerCards } from './peer-cards/reader.mjs';
 import { surfaceTopN, decayOptsFromConfig } from './learnings/surface.mjs';
+import { countSessionsInJsonl } from './sessions-canonical.mjs';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -259,19 +260,30 @@ export function _formatBanner(inputs) {
 // ---------------------------------------------------------------------------
 
 /**
- * Count lines (newline-terminated entries) in a JSONL file. Missing files
- * resolve to 0; read errors resolve to 0. Empty trailing lines are not
- * counted, matching the JSONL convention.
+ * Count DISTINCT physical sessions in `sessions.jsonl` — the "sessions ever"
+ * stat. Missing files resolve to 0; read errors resolve to 0.
+ *
+ * Identities, not lines (#1167). `sessions.jsonl` is append-only, so one
+ * physical session can occupy two lines (an abandoned stub plus the
+ * authoritative record that supersedes it, or the systemic double-stub pair
+ * from the two backfill writers). Counting lines inflated this stat by exactly
+ * the number of duplicates — 286 lines for 275 sessions in this repo, measured
+ * 2026-09-02.
+ *
+ * The abandoned-session semantic is DELIBERATELY unchanged: an abandoned
+ * session is a real session and still counts. Only DUPLICATE records of ONE
+ * physical session collapse — see `sessions-canonical.mjs`, which is not a
+ * phantom filter.
  *
  * @param {string} filePath
  * @returns {Promise<number>}
  */
-async function countJsonlLines(filePath) {
+async function countSessionIdentities(filePath) {
   if (!existsSync(filePath)) return 0;
   try {
-    const raw = await readFile(filePath, 'utf8');
-    if (raw.length === 0) return 0;
-    return raw.split('\n').filter((l) => l.length > 0).length;
+    // Counting rule (blank/malformed lines, id-less records) lives in
+    // `countSessionsInJsonl`; only the async read is local.
+    return countSessionsInJsonl(await readFile(filePath, 'utf8'));
   } catch {
     return 0;
   }
@@ -308,7 +320,7 @@ async function countMemoryFiles(dir) {
  *
  * @param {object} args
  * @param {string} args.repoRoot — absolute path
- * @param {string} [args.memoryDir] — defaults to `resolveMemoryDir()`
+ * @param {string} [args.memoryDir] — defaults to `resolveMemoryDir(repoRoot)`
  * @param {string} [args.learningsPath] — defaults to `<repoRoot>/.orchestrator/metrics/learnings.jsonl`
  * @param {Date}   [args.now] — injectable clock for tests
  * @param {{enabled?: boolean, 'half-life-days'?: number, 'floor-factor'?: number}} [args.evolveDecay]
@@ -326,9 +338,12 @@ export async function readBannerInputs({ repoRoot, memoryDir, learningsPath, now
   if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
     throw new TypeError('readBannerInputs: repoRoot is required (absolute path)');
   }
+  // #1071: bind the memory dir to the SAME root as learnings/sessions/peer-cards
+  // below. Called with no argument it derived from the ambient `process.cwd()`,
+  // which reported `0 memory files` beside a 245-session count from `repoRoot`.
   const memDir = typeof memoryDir === 'string' && memoryDir.length > 0
     ? memoryDir
-    : resolveMemoryDir();
+    : resolveMemoryDir(repoRoot);
   const learningsFile = typeof learningsPath === 'string' && learningsPath.length > 0
     ? learningsPath
     : path.join(repoRoot, '.orchestrator', 'metrics', 'learnings.jsonl');
@@ -375,7 +390,7 @@ export async function readBannerInputs({ repoRoot, memoryDir, learningsPath, now
     // computed the same way, so we re-derive locally to keep this dependency
     // surface lean and explicit.
     const sessionsPath = path.join(repoRoot, '.orchestrator', 'metrics', 'sessions.jsonl');
-    const sessionsEver = await countJsonlLines(sessionsPath);
+    const sessionsEver = await countSessionIdentities(sessionsPath);
 
     let daysSinceCleanup = null;
     if (typeof signals?.lastCleanupAt === 'string' && signals.lastCleanupAt.length > 0) {

package/scripts/lib/memory-paths.mjs

@@ -15,17 +15,26 @@ import os from 'node:os';
 /**
  * Resolve the project-specific memory directory used by the Claude Code harness.
  *
- * Mirrors the harness convention: `~/.claude/projects/<encoded-cwd>/memory/`
- * where `<encoded-cwd>` is the cwd with BOTH `/` AND `.` replaced by `-`. The
- * dot replacement matters for users with a trailing-`.` in their home dir
- * (e.g. `/Users/<owner>.`) — without it the resolved path diverges from
+ * Mirrors the harness convention: `~/.claude/projects/<encoded-root>/memory/`
+ * where `<encoded-root>` is the project root with BOTH `/` AND `.` replaced by
+ * `-`. The dot replacement matters for users with a trailing-`.` in their home
+ * dir (e.g. `/Users/<owner>.`) — without it the resolved path diverges from
  * what the harness actually wrote.
  *
  * Verified empirically against `~/.claude/projects/` directory naming.
  *
+ * `repoRoot` is explicit (#1071) because every OTHER banner input is already
+ * bound to it: with the memory dir alone derived from the ambient `process.cwd()`,
+ * a caller reading sessions/learnings/peer-cards out of the primary checkout
+ * reported `0 memory files` whenever the process ran from a worktree or a
+ * subdirectory. Defaulted, so existing zero-arg callers keep their behaviour.
+ *
+ * @param {string} [repoRoot] — absolute project root; defaults to `process.cwd()`.
  * @returns {string} Absolute path to the memory directory (not guaranteed to exist).
  */
-export function resolveMemoryDir() {
-  const encoded = process.cwd().replaceAll('/', '-').replaceAll('.', '-');
+export function resolveMemoryDir(repoRoot = process.cwd()) {
+  const root =
+    typeof repoRoot === 'string' && repoRoot.length > 0 ? repoRoot : process.cwd();
+  const encoded = root.replaceAll('/', '-').replaceAll('.', '-');
   return path.join(os.homedir(), '.claude', 'projects', encoded, 'memory');
 }

package/scripts/lib/mode-selector/scoring.mjs

@@ -82,6 +82,57 @@ export function safeBootstrapLock(signals) {
     : null;
 }
 
+/**
+ * Read a session record's completion rate, tolerating both the shape
+ * `sessions.jsonl` actually writes and the legacy flat one.
+ *
+ * Production records nest it: `{effectiveness: {completion_rate: 0.77, …}}`.
+ * The top-level `completion_rate` key is ABSENT — not present-but-null, which
+ * an earlier revision of this comment claimed. Measured 2026-08-28 @ 7daa3d2
+ * over `.orchestrator/metrics/sessions.jsonl` (281 records):
+ * `jq -s '{hasTopLevelKey: ([.[]|select(has("completion_rate"))]|length), …}'`
+ * → `hasTopLevelKey: 0`, `nested: 182`, and 99 records carrying NO completion
+ * rate in either shape. Reading only the flat field therefore made every
+ * average 0 in production — see #1071.
+ *
+ * Precedence mirrors `completionOf()` in
+ * `scripts/lib/evolve/autopilot-effectiveness.mjs`: nested canonical fields
+ * first, flat legacy fields as a backward-compatible fallback for
+ * hand-written/pre-nesting records.
+ *
+ * @param {unknown} session
+ * @returns {number} completion rate, or 0 when unknown
+ */
+function completionRateOf(session) {
+  if (session === null || typeof session !== 'object') return 0;
+  const eff = (session.effectiveness !== null && typeof session.effectiveness === 'object')
+    ? session.effectiveness
+    : {};
+  const raw =
+    eff.completion_rate ?? eff.completion_ratio ?? session.completion_rate ?? session.completion_ratio;
+  return typeof raw === 'number' && !Number.isNaN(raw) ? raw : 0;
+}
+
+/**
+ * Mean completion rate across a session slice. Unknown values contribute 0 and
+ * the divisor stays the slice length — an incomplete slice can never inflate
+ * the average past the >= 0.9 bonus threshold.
+ *
+ * The divisor is the load-bearing half, not the numerator: 99 of the 281
+ * records in production carry no completion rate in EITHER shape (measured
+ * 2026-08-28 @ 7daa3d2), so a divisor of "known values only" would let a single
+ * 1.0 session beside two unknowns score a perfect 1.0 and hand out the trend
+ * bonus on one data point. Pinned by the divisor test in
+ * `tests/lib/mode-selector/scoring.test.mjs`.
+ *
+ * @param {any[]} sessions
+ * @returns {number}
+ */
+function avgCompletionRate(sessions) {
+  if (sessions.length === 0) return 0;
+  return sessions.reduce((sum, s) => sum + completionRateOf(s), 0) / sessions.length;
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -107,9 +158,7 @@ export function computeDelta(candidateMode, signals) {
       (s) => typeof s === 'object' && s !== null && s.session_type === candidateMode,
     );
     if (allMatch) {
-      const avgCompletion =
-        last3.reduce((sum, s) => sum + (typeof s.completion_rate === 'number' ? s.completion_rate : 0), 0) /
-        3;
+      const avgCompletion = avgCompletionRate(last3);
       trendBonus = avgCompletion >= 0.9 ? 0.15 : 0.075;
     }
   }
@@ -151,9 +200,7 @@ export function computeDelta(candidateMode, signals) {
         (s) => typeof s === 'object' && s !== null && s.session_type === otherMode,
       );
       if (allOther) {
-        const avgCompletion =
-          last3.reduce((sum, s) => sum + (typeof s.completion_rate === 'number' ? s.completion_rate : 0), 0) /
-          3;
+        const avgCompletion = avgCompletionRate(last3);
         if (avgCompletion >= 0.9) {
           penalty += 0.10;
           break; // only one other dominant mode possible

package/scripts/lib/peer-discovery.mjs

@@ -100,7 +100,16 @@ function _ageHoursFrom(startedAt, nowMs) {
 /**
  * Map one discoverActiveSessions entry into a provenance-tagged peer.
  *
- * @param {{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string}} s
+ * GH#67 pass-through: `registryOnly` / `lockSuperseded` / `lockOwnerId` are
+ * threaded through UNCHANGED when the upstream entry carries them (registry-
+ * sourced sessions only). Absent stays absent, so a lock-sourced peer object is
+ * byte-identical to the pre-GH#67 shape. `lockSuperseded: true` is a HINT that
+ * a LIVE lock at that repoRoot is owned by a different raw session_id — not a
+ * verdict that the peer is dead (the lock is advisory, #1085). Consumers
+ * deciding a worktree PROMOTION_OFFER downgrade such a peer to an advisory
+ * line; consumers counting or displaying peers keep it.
+ *
+ * @param {{worktreePath:string,sessionId:string,mode:string,startedAt:string,pid:number,host:string,branch:string,registryOnly?:boolean,lockSuperseded?:boolean,lockOwnerId?:string|null}} s
  * @param {number} nowMs
  * @returns {object}
  */
@@ -118,6 +127,10 @@ function _peerFromDiscovered(s, nowMs) {
     worktreePath: s.worktreePath,
   };
   if (ageHours !== undefined) peer.ageHours = ageHours;
+  // GH#67 — additive, absent-stays-absent.
+  if (s.registryOnly !== undefined) peer.registryOnly = s.registryOnly;
+  if (s.lockSuperseded !== undefined) peer.lockSuperseded = s.lockSuperseded;
+  if (s.lockOwnerId !== undefined) peer.lockOwnerId = s.lockOwnerId;
   return peer;
 }
 
@@ -189,7 +202,12 @@ function _discoveredSelfSessionId(mySessionId, repoRoot) {
  *   per-source — only the fields the originating surface can supply are emitted
  *   (no field is advertised that the implementation does not set):
  *     - source 'discovered' (from discoverActiveSessions — lock + registry unified):
- *         { source, sessionId, mode|null, host, pid, worktreePath, ageHours? }
+ *         { source, sessionId, mode|null, host, pid, worktreePath, ageHours?,
+ *           registryOnly?, lockSuperseded?, lockOwnerId? }
+ *       The last three appear ONLY on registry-sourced entries (GH#67
+ *       annotation, passed through verbatim — see `_peerFromDiscovered`).
+ *       `lockSuperseded` is a HINT, never a liveness verdict: no peer is
+ *       dropped on account of it, because the session lock is advisory.
  *     - source 'state-md' (from checkPeerStateMd):
  *         { source, sessionId, mode|null, currentWave, reason, ageHours? }
  */

package/scripts/lib/platform.mjs

@@ -9,6 +9,7 @@
  */
 
 import { existsSync, statSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
 
@@ -42,9 +43,66 @@ function _hasEnvValue(envName) {
 }
 
 /**
- * Walk up the directory tree from startDir looking for marker.
- * Uses path.parse(dir).root so it terminates correctly on Windows ("C:\\")
- * and POSIX ("/").
+ * Absolute home directory, or null when the host cannot report one.
+ * os.homedir() reads $HOME on POSIX and %USERPROFILE% on Windows.
+ *
+ * @returns {string|null}
+ */
+function _homeDir() {
+  try {
+    const home = os.homedir();
+    return home ? path.resolve(home) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when `dir` is the home directory itself or one of its ancestors
+ * ("/", "/Users", "C:\\", …). Unrelated branches of the tree (e.g. "/opt")
+ * are neither — they are walked normally.
+ *
+ * @param {string} dir
+ * @param {string|null} home
+ * @returns {boolean}
+ */
+function _isHomeOrAbove(dir, home) {
+  if (home === null) return false;
+  if (dir === home) return true;
+  // The filesystem root already ends in the separator ("/", "C:\\") — appending
+  // a second one ("//") would make it match nothing and silently exempt the one
+  // directory that is an ancestor of every home.
+  const prefix = dir.endsWith(path.sep) ? dir : dir + path.sep;
+  return home.startsWith(prefix);
+}
+
+/**
+ * Walk up the directory tree from startDir looking for marker, bounded by the
+ * project the walk started in.
+ *
+ * Two boundaries, both load-bearing (#1139) — a marker outside the project can
+ * never describe the project:
+ *
+ *  1. **Repo root.** The first ancestor holding `.git` is the LAST directory
+ *     inspected (inclusive — a marker at the repo root is still found). `.git`
+ *     is a directory in a normal clone and a FILE in a worktree or submodule,
+ *     so existence is checked, not the kind.
+ *  2. **Home directory.** os.homedir() and its ancestors are never inspected —
+ *     even when no repo root was found (cwd outside every checkout). This is
+ *     what stops a stray `~/.pi` / `~/.cursor/rules` / `~/CLAUDE.md` from being
+ *     adopted by every markerless directory on the host: before this boundary
+ *     existed, 63 of 84 telemetry records from Claude Code sessions reported
+ *     `platform=pi` because the walk reached `$HOME` and found `~/.pi` there.
+ *
+ * Named ceiling (BV-004): when a checkout's root IS the home directory (a
+ * dotfiles repo at `$HOME`), boundary 2 wins over boundary 1 and no marker is
+ * detected there — deliberate, because that false positive is silent and
+ * host-wide while the false negative degrades to the documented default
+ * ('claude' for detectPlatform, cwd for resolveProjectDir). Revisit if a
+ * repo-at-$HOME layout ever has to carry orchestrator state.
+ *
+ * Terminates correctly on Windows ("C:\\") and POSIX ("/") via the
+ * parent === dir fixpoint.
  *
  * @param {string} startDir   Absolute directory to begin walking from
  * @param {string} marker     Relative sub-path to look for inside each candidate dir
@@ -53,7 +111,7 @@ function _hasEnvValue(envName) {
  */
 function walkUpFor(startDir, marker, kind) {
   let dir = path.resolve(startDir);
-  const root = path.parse(dir).root; // "/" on POSIX, "C:\\" on Windows
+  const home = _homeDir();
 
   const check = (candidate) => {
     if (!existsSync(candidate)) return false;
@@ -62,16 +120,15 @@ function walkUpFor(startDir, marker, kind) {
     return true; // 'any'
   };
 
-  while (dir !== root) {
+  for (;;) {
+    if (_isHomeOrAbove(dir, home)) break;          // boundary 2 — never inspected
     if (check(path.join(dir, marker))) return dir;
+    if (existsSync(path.join(dir, '.git'))) break; // boundary 1 — repo root was the last candidate
     const parent = path.dirname(dir);
-    if (parent === dir) break; // safety guard — should not happen but protects against edge cases
+    if (parent === dir) break;                     // filesystem root reached
     dir = parent;
   }
 
-  // Check root itself
-  if (check(path.join(root, marker))) return root;
-
   return null;
 }
 
@@ -109,6 +166,12 @@ export function detectPlatform() {
   if (walkUpFor(cwd, path.join('.cursor', 'rules'),  'dir')) return 'cursor';
   if (walkUpFor(cwd, '.pi',                           'dir')) return 'pi';
 
+  // Signal-free fallback, deliberate rather than inherited: Claude Code is the
+  // only harness that drives this code through `hooks.json` without exporting a
+  // platform env var, so it is the harness that actually reaches this line.
+  // Codex, Cursor and pi each set their own env var (step 2) or ship a marker
+  // directory (step 3), so a wrong answer here costs them nothing they had.
+  // No config key for this (BV-001) — SO_PLATFORM already overrides it.
   return 'claude';
 }
 

package/scripts/lib/plugin-root.mjs

@@ -5,20 +5,45 @@
  * provides a deterministic, testable resolution strategy so hook handlers and
  * scripts never silently fall back to an empty path or wrong directory.
  *
- * Fallback order (stops at first success):
- *   1. PLUGIN_ROOT native env var
- *   2. Compatibility root matching explicit SO_PLATFORM
- *   3. Remaining Claude, Codex, Cursor, and Pi compatibility roots
- *   4. Walk up from import.meta.url looking for package.json whose name === "session-orchestrator"
- *   5. Walk up from process.cwd() looking for the same marker
+ * TIER ORDER — SINGLE SOURCE OF TRUTH (stops at first success):
+ *   1.   PLUGIN_ROOT native env var
+ *   2-5. Compatibility roots: the one matching an explicit SO_PLATFORM first,
+ *        then the rest in legacy Claude → Codex → Cursor → Pi order
+ *   6.   Walk up from import.meta.url looking for package.json whose
+ *        name === "session-orchestrator"
+ *   7.   Walk up from process.cwd() looking for the same marker
+ *   8.   Scan the client plugin caches (marketplace install, no env, cwd outside
+ *        any checkout — GH Kanevry/session-orchestrator#64)
  *
- * Throws PluginRootResolutionError when all resolution levels fail.
+ * `.mcp.json`'s bash bootstrap MIRRORS this order and cites this block. It
+ * implements: tiers 1-5 in this exact env order → `git rev-parse
+ * --show-toplevel` (its analogue of tier 7) → `node -e resolvePluginRoot()`
+ * (which runs THIS function, tiers 1-8) → its own cache scan, reachable only
+ * when the module is not node-resolvable at all.
+ *
+ * THE ONE REMAINING DIVERGENCE, stated exactly: **tier 6** — a shell has no
+ * `import.meta.url`, so the walk up from this file's own location has no
+ * analogue there. Everything else is mirrored byte-for-byte in behaviour: the
+ * env list AND its order, the `CODEX_HOME` trim (see `_pluginCacheBases`), the
+ * `package.json{name === "session-orchestrator"}` test (the shell runs the same
+ * `JSON.parse` via `node -e`, not a substring `grep` — a `grep` matched
+ * `"name": "session-orchestrator-fork"` that this function rejects), and the
+ * newest-wins-by-mtime tiebreak (`[ "$c" -nt "$r" ]` is strict, exactly like
+ * the `>` below).
  *
- * Backward compat: without native or explicit platform inputs, compatibility
- * roots retain their legacy Claude → Codex → Cursor → Pi order.
+ * Two divergences that existed until 2026-08-28 and no longer do: the shell
+ * scanned the caches BEFORE the node tier (a host with both a global npm
+ * install and a marketplace cache copy had the shell pick the cache while this
+ * function picked the npm copy), and its env list read `CLAUDE_PLUGIN_ROOT,
+ * CODEX_PLUGIN_ROOT, PLUGIN_ROOT` — a different tier-1 winner, and no
+ * `CURSOR_RULES_DIR`/`PI_PLUGIN_ROOT` at all. When either side's order changes,
+ * change both — the shell is the mirror, this list is the original.
+ *
+ * Throws PluginRootResolutionError when all resolution levels fail.
  */
 
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -157,6 +182,103 @@ function _walkUp(startDir) {
   return null;
 }
 
+/**
+ * Base directories under which a client keeps its plugin cache.
+ *
+ * Measured 2026-08-28 on codex-cli 0.141.0 and Claude Code: an installed
+ * plugin is COPIED (not symlinked) to
+ * `<base>/plugins/cache/<marketplace>/<plugin-name>/<version>/`, e.g.
+ * `~/.codex/plugins/cache/local/session-orchestrator/<version>+codex.<stamp>/`
+ * and `~/.claude/plugins/cache/session-orchestrator/session-orchestrator/3.13.0/`.
+ *
+ * Cursor is deliberately absent: no cache layout was measured for it on this
+ * host (`~/.cursor/plugins/cache` did not exist), and a guessed path would
+ * resolve nothing while implying coverage. Add it once a real install is seen.
+ *
+ * `CODEX_HOME` is TRIMMED before the emptiness test, not merely defaulted.
+ * `||` and shell `${X:-…}` both fire on unset/empty only, so a whitespace-only
+ * value passes straight through and the scan globs a nonsense base
+ * (`.claude/rules/development.md` § Env-var fallback whitespace trap).
+ * `.mcp.json`'s bash bootstrap carries the same trim for the same reason —
+ * before 2026-08-28 it used `${CODEX_HOME:-$HOME/.codex}` and diverged from here on
+ * exactly that input.
+ *
+ * @returns {string[]} Absolute base directories, most-specific client first
+ */
+function _pluginCacheBases() {
+  const home = os.homedir();
+  const codexHome = (process.env.CODEX_HOME || '').trim() || path.join(home, '.codex');
+  return [codexHome, path.join(home, '.claude')];
+}
+
+/**
+ * Scan the client plugin caches for an installed copy of this plugin.
+ *
+ * This is the only level that can succeed for a marketplace install launched
+ * outside any checkout. Measured 2026-08-28 by probing a registered MCP server
+ * from `/tmp` (codex-cli 0.141.0): the child process received NO plugin-root
+ * environment variable (`CLAUDE_PLUGIN_ROOT`, `CODEX_PLUGIN_ROOT`,
+ * `PLUGIN_ROOT` and `CODEX_HOME` were all unset), its `PWD` was the launch
+ * directory, and `HOME` was set — so every earlier level is blind while the
+ * installed copy sits at a well-known path under `HOME`.
+ * See GH Kanevry/session-orchestrator#64.
+ *
+ * Ceiling (BV-004): among valid candidates the newest wins by directory
+ * **mtime**, not by semver. That reads as "the copy the client installed most
+ * recently", which is the intent, and it keeps this resolver free of a semver
+ * parser — a lexical sort would already be wrong today (`3.9.0` sorts above
+ * `3.10.0`). Revisit if a client starts pre-seeding caches it never launches.
+ *
+ * Equal-mtime tiebreak: the comparison is STRICTLY greater, so on a tie the
+ * FIRST candidate in scan order wins — bases in `_pluginCacheBases()` order
+ * (`CODEX_HOME` before `~/.claude`), then `readdirSync` order within each. Two
+ * cache copies sharing an mtime to the millisecond means the same content
+ * installed twice, so the choice is arbitrary rather than wrong; what matters
+ * is that it is DETERMINISTIC and identical to `.mcp.json`'s `[ "$c" -nt "$r" ]`,
+ * which is also strict. Untested by design — a test would pin an arbitrary
+ * choice as a contract.
+ *
+ * @param {string[]} tried  Diagnostic accumulator, appended to on failure
+ * @returns {string|null} Absolute path to the newest cached plugin copy
+ */
+function _scanPluginCaches(tried) {
+  const bases = _pluginCacheBases();
+  let best = null;
+  let bestMtimeMs = -1;
+
+  for (const base of bases) {
+    const cacheDir = path.join(base, 'plugins', 'cache');
+    if (!_isDir(cacheDir)) continue;
+
+    let marketplaces;
+    try { marketplaces = readdirSync(cacheDir); } catch { continue; }
+
+    for (const marketplace of marketplaces) {
+      const pluginDir = path.join(cacheDir, marketplace, 'session-orchestrator');
+      if (!_isDir(pluginDir)) continue;
+
+      let versions;
+      try { versions = readdirSync(pluginDir); } catch { continue; }
+
+      for (const version of versions) {
+        const candidate = path.join(pluginDir, version);
+        // The directory NAME is not proof — a foreign package may sit under a
+        // `session-orchestrator/` marketplace folder. The package.json marker is.
+        if (!_isPluginRoot(candidate)) continue;
+        let mtimeMs;
+        try { mtimeMs = statSync(candidate).mtimeMs; } catch { continue; }
+        if (mtimeMs > bestMtimeMs) { bestMtimeMs = mtimeMs; best = candidate; }
+      }
+    }
+  }
+
+  if (!best) {
+    const globs = bases.map((base) => path.join(base, 'plugins', 'cache', '*', 'session-orchestrator', '*'));
+    tried.push(`plugin caches (${globs.join(', ')}) — no package.json{name:session-orchestrator} found`);
+  }
+  return best;
+}
+
 // ---------------------------------------------------------------------------
 // resolvePluginRoot
 // ---------------------------------------------------------------------------
@@ -164,13 +286,9 @@ function _walkUp(startDir) {
 /**
  * Resolve the absolute path to the session-orchestrator plugin directory.
  *
- * Fallback order:
- *   1. Trimmed native PLUGIN_ROOT when it is an existing directory
- *   2. Compatibility root matching a valid explicit SO_PLATFORM
- *   3. Remaining compatibility roots in legacy order
- *   4. Walk up from import.meta.url (the location of this file) looking for a
- *      package.json with name "session-orchestrator"
- *   5. Walk up from process.cwd() looking for the same marker
+ * Tier order is defined ONCE in this file's top docblock (§ TIER ORDER) and
+ * mirrored by `.mcp.json`'s bash bootstrap. Do not restate it here — a second
+ * copy is what let the two drift.
  *
  * @param {string} [platformHint] Optional compatibility hint for wrapper callers
  * @returns {string} Absolute path to the plugin root
@@ -200,11 +318,17 @@ export function resolvePluginRoot(platformHint) {
   if (byCwd) return byCwd;
   tried.push(`walk from cwd (${process.cwd()}) — no package.json{name:session-orchestrator} found`);
 
+  // Level 8: client plugin caches — the marketplace-install case, where no env
+  // var is provided and the cwd is outside every checkout (#64).
+  const byPluginCache = _scanPluginCaches(tried);
+  if (byPluginCache) return byPluginCache;
+
   throw new PluginRootResolutionError(
     'Could not resolve session-orchestrator plugin root. ' +
     'Set PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT, CODEX_PLUGIN_ROOT, CURSOR_RULES_DIR, or PI_PLUGIN_ROOT ' +
-    'to the plugin directory, or ensure a package.json with name "session-orchestrator" exists in an ' +
-    'ancestor of the cwd or this script. Attempted: ' + tried.join('; '),
+    'to the plugin directory, ensure a package.json with name "session-orchestrator" exists in an ' +
+    'ancestor of the cwd or this script, or (re)install the plugin through your client\'s marketplace ' +
+    'so a cached copy exists. Attempted: ' + tried.join('; '),
     tried,
   );
 }