session-orchestrator 3.21.0 → 3.23.0

package/scripts/lib/owner-interview.mjs

@@ -13,10 +13,16 @@
  *     to AskUserQuestion in the coordinator. Each object has the shape:
  *       { question, header, options: [{ label, description }], multiSelect }
  *
+ *   optionValue(label)
+ *     Maps a displayed option label to the value stored in owner.yaml by
+ *     stripping the trailing `(Recommended)` marker. The label and the stored
+ *     value are deliberately NOT the same string — see the function comment.
+ *
  *   applyInterviewAnswers(answers, { path? } = {})
  *     Accepts an array of selected option labels (one per question, same order
- *     as getInterviewQuestions()), validates the result against validateOwnerConfig,
- *     and writes owner.yaml via writeOwnerConfig.
+ *     as getInterviewQuestions()), resolves each through optionValue(), validates
+ *     the result against validateOwnerConfig, and writes owner.yaml via
+ *     writeOwnerConfig.
  *     Returns { ok, path, errors }.
  *
  *   runOwnerInterview({ skipIfExists?, force?, path? } = {})
@@ -37,6 +43,40 @@ import {
   getDefaults,
 } from './owner-yaml.mjs';
 
+// ---------------------------------------------------------------------------
+// Label ←→ stored value
+// ---------------------------------------------------------------------------
+
+/**
+ * A trailing recommendation marker on an option LABEL — the display half of a
+ * label, never part of the stored value.
+ *
+ * Anchored at the end and non-greedy about whitespace so it can only ever strip
+ * a suffix; a value that merely CONTAINS the word (there is none today) survives.
+ */
+const RECOMMENDED_SUFFIX = /\s*\((?:Recommended|Empfohlen|Default)\)\s*$/u;
+
+/**
+ * Map an AUQ option label back to the value that is written to owner.yaml.
+ *
+ * The label and the stored value used to be the SAME string, which made the
+ * label unchangeable: `applyInterviewAnswers()` matches the answer against
+ * closed enums (`['direct','neutral','friendly']` and friends) and falls back to
+ * a default on any miss. Adding the `(Recommended)` marker AUQ-003 requires
+ * would therefore have turned a picked `direct` into a silently-stored
+ * `neutral` — a wrong answer written to disk with no error anywhere.
+ *
+ * Splitting the two keeps the label free for the operator and the value pinned
+ * to the enum. Everything before the marker is the value, verbatim.
+ *
+ * @param {unknown} label — the option label as selected by the operator
+ * @returns {string} the enum value to store, or '' for a non-string input
+ */
+export function optionValue(label) {
+  if (typeof label !== 'string') return '';
+  return label.replace(RECOMMENDED_SUFFIX, '').trim();
+}
+
 // ---------------------------------------------------------------------------
 // Question definitions
 // ---------------------------------------------------------------------------
@@ -50,51 +90,51 @@ import {
 export function getInterviewQuestions() {
   return [
     {
-      question: 'Which language should the assistant use for its responses?',
-      header: 'Owner Interview — Language (1/5)',
+      question: 'Which language should the assistant answer in?',
+      header: 'Language 1/5',
       options: [
-        { label: 'de', description: 'German — responses, narration, and questions in Deutsch.' },
-        { label: 'en', description: 'English — responses, narration, and questions in English.' },
-        { label: 'other', description: 'Other — write your ISO-639-1 code when prompted.' },
+        { label: 'de', description: 'German — answers, narration and questions all in Deutsch.' },
+        { label: 'en', description: 'English — answers, narration and questions all in English.' },
+        { label: 'other', description: 'Stored as English either way — only de and en are accepted. Change it later in owner.yaml (your settings file).' },
       ],
       multiSelect: false,
     },
     {
-      question: 'What communication tone style do you prefer?',
-      header: 'Owner Interview — Tone Style (2/5)',
+      question: 'How should the assistant talk to you?',
+      header: 'Tone 2/5',
       options: [
-        { label: 'direct', description: '(Recommended for pros) No filler phrases, straight to the point.' },
-        { label: 'neutral', description: 'Balanced: professional without being terse.' },
-        { label: 'friendly', description: 'Warm and conversational — good for exploratory sessions.' },
+        { label: 'direct (Recommended)', description: 'No filler, no praise, straight to the point — fastest to read once you know the project.' },
+        { label: 'neutral', description: 'Professional without being terse. Pick this if direct reads too blunt.' },
+        { label: 'friendly', description: 'Warm and conversational. Costs a few lines per answer, and suits open-ended exploration.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'How much output should the assistant produce by default?',
-      header: 'Owner Interview — Output Level (3/5)',
+      question: 'How much should the assistant write by default?',
+      header: 'Output 3/5',
       options: [
-        { label: 'lite', description: 'Verbose mode — articles, explanations, and context kept. Good for learning.' },
-        { label: 'full', description: '(Default) Terse but complete. Narration trimmed, data preserved.' },
-        { label: 'ultra', description: 'Telegraphic — code and decisions only, no narration.' },
+        { label: 'full (Recommended)', description: 'Terse but complete: narration trimmed, every fact kept. Safe default — you lose words, never data.' },
+        { label: 'lite', description: 'Keeps the explanations and background too. Slower to read, better while the codebase is still new to you.' },
+        { label: 'ultra', description: 'Code and decisions only, no narration. You will have to ask why more often.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'How should the assistant handle preamble before taking actions?',
-      header: 'Owner Interview — Preamble (4/5)',
+      question: 'How much should the assistant explain before it starts working?',
+      header: 'Preamble 4/5',
       options: [
-        { label: 'minimal', description: 'One-line status updates only. Jump straight to execution.' },
-        { label: 'verbose', description: 'Explain plan + rationale before each major action.' },
+        { label: 'minimal (Recommended)', description: 'One line of status, then it works. Safe default — you can still ask for the reasoning afterwards.' },
+        { label: 'verbose', description: 'Plan and reasoning before each major action. Costs a few lines every step.' },
       ],
       multiSelect: false,
     },
     {
-      question: 'Hardware-sharing consent: may the plugin share anonymized hardware patterns to improve resource defaults? (Issue #173 C4)',
-      header: 'Owner Interview — Hardware Sharing Consent (5/5)',
+      question: 'May the plugin share anonymized hardware data to improve its resource defaults?',
+      header: 'Sharing 5/5',
       options: [
-        { label: 'No', description: '(Default) No data is shared. Fully private.' },
-        { label: 'Yes', description: 'Share anonymized patterns (hashed, no PII). Helps tune wave/session defaults.' },
-        { label: 'Preview', description: 'Show exactly what would be shared before deciding.' },
+        { label: 'No (Recommended)', description: 'Nothing leaves this machine. Safe default — you can switch it on later without redoing this interview.' },
+        { label: 'Yes', description: 'Shares hashed hardware patterns — never file names, paths or content. Helps tune the wave and session defaults.' },
+        { label: 'Preview', description: 'Shows exactly what would be sent, then asks again. Costs one extra step.' },
       ],
       multiSelect: false,
     },
@@ -108,12 +148,15 @@ export function getInterviewQuestions() {
 /**
  * Map interview answer labels to an owner.yaml config object and write it.
  *
+ * Each answer is the LABEL the operator picked, which may carry a trailing
+ * `(Recommended)` marker; optionValue() strips it before the enum match below.
+ *
  * @param {string[]} answers - Array of selected option labels, one per question (5 total).
- *   answers[0] = language label ('de' | 'en' | free-text)
- *   answers[1] = tone style label
- *   answers[2] = output level label
- *   answers[3] = preamble label
- *   answers[4] = hardware-sharing label ('Yes' | 'No' | 'Preview')
+ *   answers[0] = language label ('de' | 'en' | 'other')
+ *   answers[1] = tone style label ('direct' | 'neutral' | 'friendly', ± marker)
+ *   answers[2] = output level label ('full' | 'lite' | 'ultra', ± marker)
+ *   answers[3] = preamble label ('minimal' | 'verbose', ± marker)
+ *   answers[4] = hardware-sharing label ('Yes' | 'No' | 'Preview', ± marker)
  * @param {{ path?: string }} [opts]
  * @returns {{ ok: boolean, path: string, errors: string[] }}
  */
@@ -124,7 +167,10 @@ export function applyInterviewAnswers(answers, opts = {}) {
     return { ok: false, path: filePath, errors: ['applyInterviewAnswers requires exactly 5 answers'] };
   }
 
-  const [langRaw, toneRaw, outputLevelRaw, preambleRaw, hwConsentRaw] = answers;
+  // Strip the display-only `(Recommended)` marker before matching against the
+  // enums below — see optionValue(). A non-string answer becomes '' and falls
+  // through to the same default it always did.
+  const [langRaw, toneRaw, outputLevelRaw, preambleRaw, hwConsentRaw] = answers.map(optionValue);
 
   // --- Language ---
   // Accept 'de', 'en', or treat anything else as a free-text language code.

package/scripts/lib/peer-discovery.mjs

@@ -67,6 +67,7 @@ import { discoverActiveSessions } from './session-discovery.mjs';
 import { readLock, isLockLive, LOCK_PATH } from './session-lock.mjs';
 import { checkPeerStateMd } from './state-md-peer-guard.mjs';
 import { listWorktreesChecked } from './worktree/listing.mjs';
+import { parseSessionId } from './session-id.mjs';
 
 /** Closed enum of provenance sources. */
 const SOURCE_DISCOVERED = 'discovered'; // lock + registry unified (irreversibly merged upstream)
@@ -120,24 +121,64 @@ function _peerFromDiscovered(s, nowMs) {
   return peer;
 }
 
+/**
+ * Resolve a semantic hint to the concrete local raw ID for discovered surfaces.
+ *
+ * Semantic labels are attribution, not ownership. A mapping is usable only when
+ * current-session.json names the hint and its raw id exactly matches the local
+ * readable session.lock. Otherwise return null so a potentially foreign record
+ * stays visible. Raw caller ids retain the legacy direct comparison unchanged.
+ *
+ * This is a consistency check on two repo-global files, NOT a proof of ownership;
+ * a colliding semantic label from a foreign live session satisfies it. See the
+ * call site in findPeers for the measured case and why it is not closed here.
+ *
+ * @param {string|null} mySessionId
+ * @param {string} repoRoot
+ * @returns {string|null}
+ */
+function _discoveredSelfSessionId(mySessionId, repoRoot) {
+  if (typeof mySessionId !== 'string' || mySessionId.length === 0) return null;
+  if (parseSessionId(mySessionId)?.format !== 'semantic') return mySessionId;
+
+  try {
+    const raw = fs.readFileSync(
+      path.join(repoRoot, '.orchestrator', 'current-session.json'),
+      'utf8',
+    );
+    const current = JSON.parse(raw);
+    const lock = readLock({ repoRoot });
+    if (
+      current &&
+      typeof current === 'object' &&
+      !Array.isArray(current) &&
+      typeof current.session_id === 'string' &&
+      current.session_id.length > 0 &&
+      current.semantic_session_id === mySessionId &&
+      lock !== null &&
+      typeof lock.session_id === 'string' &&
+      lock.session_id === current.session_id
+    ) {
+      return lock.session_id;
+    }
+  } catch {
+    // Missing or malformed local state cannot prove a semantic alias.
+  }
+  return null;
+}
+
 /**
  * findPeers — union of all 3 peer-discovery surfaces, fail-open per surface.
  *
  * @param {string} repoRoot  Absolute path to the repository root.
  * @param {object} [opts] passthrough seams shared with the underlying surfaces.
- * @param {string|null} [opts.mySessionId]      Current session id, used for
- *   self-exclusion on BOTH surfaces — but the two surfaces read different
- *   id-spaces. Surface A+B (discoverActiveSessions) compares against
- *   `session_id` from session.lock / the host registry, which is ALWAYS the
- *   UUID (never `semantic_session_id` — see session-lock.mjs). Surface C
- *   (checkPeerStateMd) compares against STATE.md's `session:` frontmatter
- *   field, which callers may populate with either id-space as long as it is
- *   the SAME id-space `mySessionId` was derived from (see the PRECONDITION
- *   note in state-md-peer-guard.mjs). Passing a semantic id here self-excludes
- *   correctly on Surface C but NOT on Surface A+B (the UUID lock/registry
- *   entry for the same session will still surface as a 'discovered' peer of
- *   itself) — callers that need both surfaces to self-exclude MUST pass the
- *   UUID.
+ * @param {string|null} [opts.mySessionId]      Current session id hint. Raw
+ *   ids self-exclude directly on Surface A+B. A semantic hint maps to a raw
+ *   discovered-surface id only after the local current-session.json semantic
+ *   label matches it AND that file's raw id exactly equals local
+ *   session.lock.session_id. Missing, malformed, or mismatched local state
+ *   maps nothing, leaving discovered entries visible. Surface C receives this
+ *   original hint unchanged and compares it to STATE.md's `session:` field.
  * @param {number}      [opts.now]              ms-since-epoch (test seam for freshness/age).
  * @param {number}      [opts.freshnessMin]     Registry-entry freshness threshold (minutes).
  * @param {number}      [opts.maxAgeHours]      STATE.md abandonment threshold (hours).
@@ -155,6 +196,7 @@ function _peerFromDiscovered(s, nowMs) {
 export async function findPeers(repoRoot, opts = {}) {
   const nowMs = typeof opts.now === 'number' ? opts.now : Date.now();
   const mySessionId = opts.mySessionId ?? null;
+  const discoveredSelfSessionId = _discoveredSelfSessionId(mySessionId, repoRoot);
 
   const peers = [];
 
@@ -172,15 +214,24 @@ export async function findPeers(repoRoot, opts = {}) {
     });
     if (Array.isArray(discovered)) {
       for (const s of discovered) {
-        // Self-exclusion (#798): discoverActiveSessions has no notion of "my
-        // session" — it returns every live lock/registry entry, including the
-        // caller's own SessionStart-hook heartbeat. Exclude it here so it
-        // never surfaces as a source:'discovered' peer of itself. Mirrors the
-        // same guard in session-registry.mjs detectPeers() and
-        // hooks/on-session-start.mjs. `mySessionId === null` needs no special
-        // case: `!==` against a string sessionId is always true when
-        // mySessionId is null, so a foreign entry is never filtered.
-        if (s && typeof s.sessionId === 'string' && s.sessionId !== mySessionId) {
+        // Self-exclusion (#798, #1085): discovered entries carry raw ids. A
+        // semantic caller hint filters one such id only after the local raw
+        // binding was verified above.
+        //
+        // The binding proves CONSISTENCY of the two local files, not OWNERSHIP.
+        // Both are repo-global, so if a foreign live session wrote them last and
+        // its semantic label collides with this hint (labels like
+        // `main-2026-08-21-session-2` are routinely shared — see
+        // hooks/on-session-start.mjs), that foreign raw id is filtered and the
+        // peer PSA-002 exists to surface goes missing. Measured 2026-08-21:
+        // null hint -> peer visible, colliding semantic hint -> peers: [].
+        // Closing it needs a per-process ownership proof, not a stronger read
+        // of the same two files.
+        if (
+          s &&
+          typeof s.sessionId === 'string' &&
+          s.sessionId !== discoveredSelfSessionId
+        ) {
           peers.push(_peerFromDiscovered(s, nowMs));
         }
       }

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,
   );
 }