session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/own-lock-root.mjs

@@ -0,0 +1,95 @@
+/**
+ * own-lock-root.mjs — the checkout whose `.orchestrator/session.lock` carries a
+ * given RAW session id, for scripts that run outside a hook (#1730).
+ *
+ * A hook knows its session from the payload and asks `resolveOwnLockRoot`
+ * (`hooks/_lib/hook-root.mjs`). A script run by the coordinator does not: it
+ * gets a `cwd`, and the cwd is often the wrong tree. A session that works in a
+ * linked worktree by `cd` keeps its lock in the main checkout; one that took its
+ * lock in a worktree runs Bash from the main checkout, because the shell cwd
+ * resets there. Reading at `process.cwd()` then answers "no lock" (#1730 Pkt 1:
+ * `/close` released nothing and exited 0) or "no agents" (Pkt 2: the HUD).
+ *
+ * Candidates, in order; the first whose lock carries the id wins:
+ *   1. `registry`      — the host registry entry's `session_root`, via the
+ *                        hook readers' own `resolveOwnLockRoot`;
+ *   2. `cwd`           — the checkout holding `cwd`;
+ *   3. `main-checkout` — the main checkout of that repository;
+ *   4. `worktree`      — a registered linked worktree of it (`registeredWorktreeRoots`).
+ * No candidate → `{ root: <checkout of cwd>, source: 'none' }`: the pre-#1730
+ * answer, so a caller that found nothing behaves as it did before.
+ *
+ * Only a lock that carries the id counts. A registry pointer, a STATE.md or a
+ * `current-session.json` alone proves nothing: they can name a peer.
+ *
+ * Spawn-free (fs reads only), never throws.
+ *
+ * Exports: resolveOwnLockRootFor, registrySessionRoot.
+ */
+
+import { readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+
+import { resolveOwnLockRoot } from '../../hooks/_lib/hook-root.mjs';
+import { dotGitAncestor, registeredWorktreeRoots, resolveEventsLedgerRoot } from './platform.mjs';
+import { activeDir } from './session-registry.mjs';
+import { readLockDetailed } from './session-lock.mjs';
+import { parseSessionId } from './session-id.mjs';
+
+/** @param {string} root @param {string} id */
+function lockCarries(root, id) {
+  const detail = readLockDetailed({ repoRoot: root });
+  return detail.status === 'ok' && detail.lock.session_id === id;
+}
+
+/** @param {string} p */
+function canonical(p) {
+  try { return realpathSync.native(p); } catch { return path.resolve(p); }
+}
+
+/**
+ * `session_root` of the host registry entry of `id`, or `null` when there is
+ * no entry, it cannot be read, or the value is no absolute path. A pointer
+ * only — the caller decides whether a lock there belongs to `id`.
+ *
+ * @param {string} id  raw session id (UUID)
+ * @returns {string|null}
+ */
+export function registrySessionRoot(id) {
+  if (parseSessionId(id)?.format !== 'uuid') return null;
+  try {
+    const entry = JSON.parse(readFileSync(path.join(activeDir(), `${id}.json`), 'utf8'));
+    const root = entry?.session_root;
+    return typeof root === 'string' && path.isAbsolute(root) ? root : null;
+  } catch { return null; }
+}
+
+/**
+ * Where THIS session's lock is (see the module doc for the candidate order).
+ *
+ * @param {{ sessionId?: string|null, cwd?: string }} [opts]
+ * @returns {{ root: string, source: 'registry'|'cwd'|'main-checkout'|'worktree'|'none' }}
+ */
+export function resolveOwnLockRootFor({ sessionId = null, cwd = process.cwd() } = {}) {
+  const dir = path.resolve(typeof cwd === 'string' && cwd !== '' ? cwd : process.cwd());
+  const top = dotGitAncestor(dir) || dir;
+  if (parseSessionId(sessionId)?.format !== 'uuid') return { root: top, source: 'none' };
+
+  const viaHook = resolveOwnLockRoot({ session_id: sessionId, cwd: dir }, top);
+  if (lockCarries(viaHook, sessionId)) {
+    return { root: viaHook, source: canonical(viaHook) === canonical(top) ? 'cwd' : 'registry' };
+  }
+
+  const main = resolveEventsLedgerRoot(top);
+  if (canonical(main) !== canonical(top) && lockCarries(main, sessionId)) {
+    return { root: main, source: 'main-checkout' };
+  }
+
+  // Sorted, so two linked worktrees that both carry the id (an anomaly: one
+  // raw session, two locks) always resolve to the same one.
+  const { roots } = registeredWorktreeRoots(canonical(path.join(main, '.git')));
+  for (const root of roots.sort()) {
+    if (canonical(root) !== canonical(top) && lockCarries(root, sessionId)) return { root, source: 'worktree' };
+  }
+  return { root: top, source: 'none' };
+}

package/scripts/lib/owner-interview.mjs

@@ -35,7 +35,7 @@
  */
 
 import { randomBytes } from 'node:crypto';
-import { existsSync, copyFileSync } from 'node:fs';
+import { existsSync, copyFileSync, chmodSync } from 'node:fs';
 import {
   resolveOwnerYamlPath,
   validateOwnerConfig,
@@ -274,6 +274,7 @@ export function runOwnerInterview(opts = {}) {
     const backupPath = `${filePath}.bak-${timestamp}`;
     try {
       copyFileSync(filePath, backupPath);
+      try { chmodSync(backupPath, 0o600); } catch { /* best effort */ } // copy keeps a loose source mode (#1632)
     } catch {
       // Non-fatal: continue even if backup fails (file might be unreadable)
     }

package/scripts/lib/owner-yaml.mjs

@@ -33,6 +33,11 @@
  *                                  owner-leakage scanner's CP11 rule matches against tracked files.
  *                                  The names live in the referenced file ONLY — NEVER inline in
  *                                  owner.yaml. Never committed; env SO_CONFIDENTIAL_NAMES_FILE overrides.)
+ *     projects-root: string ('' = no override; #1562 — host-local cross-repo confinement / scan
+ *                                  root, default ~/Projects. A leading ~ expands to the home
+ *                                  directory; a value that is not absolute after expansion is
+ *                                  ignored with a WARN by getConfinementRoot (config/cross-repo.mjs).
+ *                                  Never committed; env SO_PROJECTS_ROOT overrides.)
  *   dispatcher:             (optional; host-local cross-repo dispatcher autonomy override — #679)
  *     autonomy: string      ('' = no override; resolver enum off | advisory | autonomous-gated;
  *                            precedence env SO_DISPATCHER_AUTONOMY > this > committed > off)
@@ -41,6 +46,14 @@
  *     mode: 'off' | 'warn' | 'strict'  (applied only when weaker than the committed mode;
  *                            precedence env SO_VAULT_INTEGRATION > this > committed.
  *                            An invalid value drops ONLY this section, see loadOwnerConfig)
+ *   learnings:              (optional; host-local learnings-store role — #1516)
+ *     store-role: 'writer' | 'inbox'  (absent = writer; inbox = this host only appends
+ *                            to learnings-inbox.jsonl and never rewrites learnings.jsonl.
+ *                            precedence env SO_LEARNINGS_STORE_ROLE > this > writer.
+ *                            An empty `learnings:` is absent. An invalid value or any
+ *                            other key drops ONLY this section, see loadOwnerConfig;
+ *                            the store-role resolver then reads the role as invalid and
+ *                            canonical-store writes refuse — it never falls back to writer)
  *   drift-check:            (optional; host-local path exceptions — #937)
  *     foreign-host-prefixes: string[] (narrow absolute directory prefixes;
  *                            missing matching paths warn, unmatched paths error)
@@ -57,7 +70,7 @@
  *   validateOwnerSections(obj) — pure validation, no I/O; bucketed per section (#820)
  *   validateOwnerConfig(obj)   — pure validation, no I/O; thin wrapper over validateOwnerSections
  *   loadOwnerConfig({path?})   — reads file; per-section tolerance for OPTIONAL
- *                                sections (paths/dispatcher/vault-integration/drift-check/vaults/
+ *                                sections (paths/dispatcher/vault-integration/drift-check/learnings/vaults/
  *                                baselines/vault-dirs) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
@@ -80,7 +93,7 @@
  * WARN naming `npm install` as the fix.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { createRequire } from 'node:module';
 import { resolvePrivateConfigDir } from './config/private-config-dir.mjs';
@@ -219,9 +232,10 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  *
  * `vault-integration` has no `getDefaults()` entry: absent means "no host
  * override", so a dropped section simply leaves the committed gate in force.
+ * `learnings` (#1516) likewise has none: absent means the `writer` role.
  */
 export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
-  Object.freeze(['paths', 'dispatcher', 'vault-integration', 'drift-check'])
+  Object.freeze(['paths', 'dispatcher', 'vault-integration', 'drift-check', 'learnings'])
 );
 
 /**
@@ -235,6 +249,13 @@ const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines', 'va
 /** Host-settable vault-integration modes (mirrors VAULT_MODE_VALUES in config-schema.mjs). */
 const VALID_VAULT_INTEGRATION_MODES = ['off', 'warn', 'strict'];
 
+/**
+ * Host-settable learnings-store roles (#1516). Mirrors STORE_ROLES in
+ * learnings/store-role.mjs — duplicated, not imported, because this module is
+ * on the hook import graph and must stay import-light.
+ */
+const VALID_LEARNINGS_STORE_ROLES = ['writer', 'inbox'];
+
 /** Canonical validation-order — MUST match the pre-#820 inline validation order. */
 const SECTION_ORDER = /** @type {const} */ ([
   ...REQUIRED_SECTIONS,
@@ -283,6 +304,7 @@ export function getDefaults() {
       'baseline-path': '',
       'namespace-map-path': '',
       'confidential-names-file': '',
+      'projects-root': '',
     },
     dispatcher: {
       autonomy: '',
@@ -435,7 +457,7 @@ export function validateOwnerSections(obj) {
       if (!isPlainObject(paths)) {
         errors.push('paths must be an object when present');
       } else {
-        for (const key of ['vault-dir', 'baseline-path', 'namespace-map-path', 'confidential-names-file']) {
+        for (const key of ['vault-dir', 'baseline-path', 'namespace-map-path', 'confidential-names-file', 'projects-root']) {
           const v = paths[key];
           if (v !== undefined && v !== null && typeof v !== 'string') {
             errors.push(`paths.${key} must be a string`);
@@ -497,6 +519,41 @@ export function validateOwnerSections(obj) {
     sections['vault-integration'] = { valid: errors.length === 0, errors };
   }
 
+  // ── learnings (optional; host-local store role — #1516) ─────────────────────
+  // STRICT enum like vault-integration: an invalid `learnings` section (typo
+  // `store-role: inbx`) is dropped here like any optional section. The store-
+  // role resolver (learnings/store-role.mjs) sees the key in the raw file and
+  // treats present-but-dropped as `invalid`, so canonical-store writes refuse
+  // instead of the host silently staying a writer that rewrites a synced store.
+  {
+    const errors = [];
+    const lr = obj.learnings;
+    if (lr !== undefined && lr !== null) {
+      if (!isPlainObject(lr)) {
+        errors.push('learnings must be an object when present');
+      } else {
+        // A misspelt key (`store_role: inbox`) must not read as "store-role
+        // absent" and fall back to writer (#1686): any key but `store-role`
+        // invalidates the section, so the resolver reports the role invalid.
+        for (const key of Object.keys(lr)) {
+          if (key !== 'store-role') {
+            errors.push(`learnings has unknown key ${JSON.stringify(key)} (only store-role is allowed)`);
+          }
+        }
+        if (
+          lr['store-role'] !== undefined &&
+          lr['store-role'] !== null &&
+          !VALID_LEARNINGS_STORE_ROLES.includes(lr['store-role'])
+        ) {
+          errors.push(
+            `learnings.store-role must be one of ${VALID_LEARNINGS_STORE_ROLES.join(', ')}, got: ${JSON.stringify(lr['store-role'])}`,
+          );
+        }
+      }
+    }
+    sections.learnings = { valid: errors.length === 0, errors };
+  }
+
   // ── vaults (optional; N named vaults for walk-up resolution — #700) ──────────
   // Drop-and-WARN on malformed entries is handled by parseNamedVaults() in
   // named-vault-resolver.mjs. Here we only validate the container shape to
@@ -657,7 +714,7 @@ export function validateOwnerConfig(obj) {
  * Per-section tolerance (#820): an invalid REQUIRED section (owner, tone,
  * efficiency, hardware-sharing) still discards the whole file (legacy
  * behaviour, unchanged). An invalid OPTIONAL object section (paths,
- * dispatcher, vault-integration, drift-check) is instead replaced by its default value — the rest of the
+ * dispatcher, vault-integration, drift-check, learnings) is instead replaced by its default value — the rest of the
  * file survives, `source` becomes `'partial'`, and the drop is reported via
  * `droppedSections` + a stderr WARN. OPTIONAL list sections (vaults,
  * baselines, vault-dirs) are passed through UNTOUCHED even when strict-invalid — their
@@ -863,7 +920,10 @@ export function writeOwnerConfig(config, opts = {}) {
 
   const dir = dirname(filePath);
   try {
-    mkdirSync(dir, { recursive: true });
+    // 0o700 on every level this call creates: under umask 000 (WSL default) a
+    // bare mkdir left the private config dir 0777, and check-owner-leakage then
+    // refuses every owner policy beside it (#1629). An EXISTING dir keeps its mode.
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
   } catch (err) {
     return {
       written: false,
@@ -891,7 +951,10 @@ export function writeOwnerConfig(config, opts = {}) {
   }
 
   try {
-    writeFileSync(filePath, yamlStr, 'utf8');
+    writeFileSync(filePath, yamlStr, { encoding: 'utf8', mode: 0o600 });
+    // mode only applies on creation; an owner.yaml left 0666 by an older
+    // writer would stay rewritable by other users (paths.*, salt) (#1632).
+    try { chmodSync(filePath, 0o600); } catch { /* best effort */ }
   } catch (err) {
     return { written: false, errors: [`failed to write owner.yaml: ${err.message}`] };
   }

package/scripts/lib/platform.mjs

@@ -148,10 +148,47 @@ function walkUpFor(startDir, marker, kind) {
  * 1. Trimmed allowlisted SO_PLATFORM explicit override
  * 2. Compatibility env vars: CLAUDE_PLUGIN_ROOT → "claude", CODEX_PLUGIN_ROOT → "codex",
  *    CURSOR_RULES_DIR → "cursor", PI_PLUGIN_ROOT → "pi"
- * 3. Filesystem walk from CWD looking for marker dirs:
+ * 3. Harness shell marker: CODEX_THREAD_ID → "codex", even when Claude Code
+ *    markers are present too
+ * 4. Filesystem walk from CWD looking for marker dirs:
  *    .claude-plugin → "claude", .codex-plugin → "codex", .cursor/rules → "cursor",
  *    .pi → "pi"
- * 4. Default: "claude"
+ * 5. Default: "claude"
+ *
+ * Step 3 exists because step 4 describes the REPO, not the harness: an agent
+ * Bash shell usually lacks the step-2 plugin-root vars, and a repo that ships
+ * both .claude-plugin and .codex-plugin resolved a Codex shell as "claude"
+ * (#1636). CODEX_THREAD_ID is set by Codex CLI for its exec_command shells
+ * (0.160.0 binary strings; ~/.codex/sessions transcripts of 2026-10 read it as
+ * their own thread id).
+ *
+ * Only Codex's marker decides, by design:
+ * - Claude Code's shell markers (CLAUDECODE, CLAUDE_CODE_ENTRYPOINT) do NOT:
+ *   a harness started by hand from a Claude Code shell (e.g. cursor-agent or pi)
+ *   inherits them and has no evidenced marker of its own, so it would read
+ *   "claude" where the walk answers "cursor"/"pi". Foreign dispatch is immune:
+ *   it passes only FOREIGN_ENV_ALLOWLIST (wave-executor/foreign-dispatch.mjs:119).
+ *   Claude hooks still decide at step 2 via CLAUDE_PLUGIN_ROOT.
+ * - CLAUDE_CODE_SESSION_ID never decides: every nested harness inherits it (the
+ *   #1636 trigger).
+ * - Cursor and pi have no evidenced shell marker (CURSOR_PLUGIN_ROOT is set by
+ *   our own hook bridge, not by Cursor) and stay on steps 2/4.
+ *
+ * Named ceiling (BV-004): the dominant nesting here is Codex launched FROM a
+ * Claude Code shell (lead/headless runs), so CODEX_THREAD_ID wins over Claude
+ * markers. The reverse nesting — Claude, Cursor or pi launched from a Codex
+ * shell — inherits CODEX_THREAD_ID and reads "codex". For Claude that means
+ * agent-shell scripts cannot close its .claude/STATE.md via
+ * markStateMdCompletedOnDisk (WARN "session-id is not this process's",
+ * state-md/frontmatter-mutators.mjs:249), the /close pre-check
+ * (scripts/close-precheck.mjs run without --state-dir, resolving via
+ * resolveStateDir in scripts/lib/session-end/close-precheck.mjs) reads
+ * .codex/STATE.md, answers `no-state` and stops with "No active session
+ * found" instead of running session-end, and scripts/tmux-layout.mjs watches
+ * the wrong state dir. Its hooks are
+ * unaffected (step 2, CLAUDE_PLUGIN_ROOT). Revisit on a measured
+ * mis-detection of that kind, or when a harness exports a marker naming itself
+ * as the innermost one.
  *
  * @returns {"claude"|"codex"|"cursor"|"pi"}
  */
@@ -164,6 +201,10 @@ export function detectPlatform() {
   if (_hasEnvValue('CURSOR_RULES_DIR')) return 'cursor';
   if (_hasEnvValue('PI_PLUGIN_ROOT')) return 'pi';
 
+  // Step 3 — the one harness shell marker that may decide. See the JSDoc above
+  // for why Claude's own markers deliberately do not.
+  if (_hasEnvValue('CODEX_THREAD_ID')) return 'codex';
+
   const cwd = process.cwd();
 
   if (walkUpFor(cwd, '.claude-plugin',               'dir')) return 'claude';
@@ -421,14 +462,14 @@ function _isStrictlyInside(child, parent) {
  * would let any directory that lacks one become the deciding root.
  *
  * Ceilings (BV-004):
- *  - An agent of a session that ENTERED a worktree is still unenforced, as before
- *    #1492: its worktree sits under the launch checkout (measured: session
+ *  - An agent of a session that ENTERED a worktree lands, via this lift, on the
+ *    launch root, where that session has no manifest (measured: session
  *    0d5e4fc3, 2026-09-25 — cwd `<main>/.claude/worktrees/landing-produktschau`,
- *    agent worktreePath `<main>/.claude/worktrees/agent-acd5bfd0aa590e2e8`), so
- *    the lift lands on the launch root, where that session has no manifest.
- *    Fixing it needs a design (e.g. find the manifest bound to the payload
- *    `session_id` among the repo's worktrees). Revisit when an entered-worktree
- *    session dispatches `isolation: "worktree"` agents under a manifest.
+ *    agent worktreePath `<main>/.claude/worktrees/agent-acd5bfd0aa590e2e8`).
+ *    This function alone does not close that; `resolveScopeContext()` in
+ *    `scope-gate.mjs` does (#1504, d99e6be1): for an isolated agent without a
+ *    local manifest it searches the repo's registered worktrees
+ *    (`registeredWorktreeRoots`) for the manifest bound to the own session id.
  *  - Rung 2 is `cd`-relocatable: a session whose `cwd` sits in ANOTHER repo (a
  *    submodule, a nested or sibling checkout) is checked against that repo's
  *    manifest — usually none, so its gates allow — where the launch dir's
@@ -527,6 +568,51 @@ export function registeredWorktreeRoots(commonDir) {
   finally { if (dir) dir.closeSync(); }
 }
 
+/**
+ * The spot in ANOTHER working copy of the launch root's repository that matches
+ * the launch root — `<cwd's linked worktree>/<launchRoot relative to its own
+ * checkout>` — or `''` (#1605). The one candidate a lifecycle hook may move a
+ * session's own state (`session.lock`, `current-session.json`) to after
+ * `EnterWorktree`, where `$CLAUDE_PROJECT_DIR` still names the launch checkout.
+ *
+ * Non-empty ONLY when ALL hold:
+ *  - `cwd` is absolute and sits in a LINKED worktree whose `.git` pointer is
+ *    confirmed by git's back-pointer (`worktreeBinding`), so a copied or forged
+ *    `.git` file (`gitdir: <main>/.git/worktrees/<name>`) lends no authority;
+ *  - that worktree is not a harness subagent worktree (`agent-<hex>`, the shape
+ *    `resolveSessionRoot` lifts) and not the launch root's own checkout;
+ *  - its common dir is the launch checkout's (its own `.git` directory for a
+ *    main checkout, the verified binding for a linked one) — same repository;
+ *  - the mapped spot exists as a directory.
+ * A main checkout is never an answer: its `.git` is a directory, which
+ * `worktreeBinding` rejects. Spawn-free; never throws.
+ *
+ * Ceiling (BV-004): a launch in a subdirectory the worktree lacks (untracked in
+ * the launch checkout) answers `''`, so that session keeps the launch root.
+ * Revisit when a session launched in such a subdirectory reports #1605.
+ *
+ * @param {string|undefined} cwd       the hook payload's `cwd`
+ * @param {string} launchRoot          the launch root (`resolveProjectDir()`)
+ * @returns {string}  Absolute path, or `''`
+ */
+export function linkedWorktreeSpot(cwd, launchRoot) {
+  if (typeof cwd !== 'string' || cwd.trim() === '' || !path.isAbsolute(cwd)) return '';
+  if (typeof launchRoot !== 'string' || launchRoot === '') return '';
+  const cwdCopy = dotGitAncestor(cwd);
+  const launchCopy = dotGitAncestor(launchRoot);
+  if (!cwdCopy || !launchCopy || _liftHarnessAgentWorktree(cwdCopy) !== cwdCopy) return '';
+  try {
+    const target = worktreeBinding(cwdCopy);
+    if (_canonical(cwdCopy) === _canonical(launchCopy)) return '';
+    const launchDotGit = path.join(launchCopy, '.git');
+    const launchCommon = lstatSync(launchDotGit).isDirectory()
+      ? _canonical(launchDotGit) : worktreeBinding(launchCopy).commonDir;
+    if (target.commonDir !== launchCommon) return '';
+    const spot = path.join(cwdCopy, path.relative(launchCopy, launchRoot));
+    return statSync(spot).isDirectory() ? spot : '';
+  } catch { return ''; }
+}
+
 // ---------------------------------------------------------------------------
 // resolveEventsLedgerRoot (#1514 point 1)
 // ---------------------------------------------------------------------------
@@ -611,6 +697,18 @@ function _inMainCheckout(dir) {
  * `repoRoot` given: the same mapping applied to that root — for a caller that
  * holds a repo root and wants THE ledger of that repo.
  *
+ * Fallback to the unmapped root (decided on #1592, behaviour unchanged): it is
+ * the right answer for a plain checkout (it IS the main one), a non-git
+ * directory, a submodule and a bare repo's worktree (no main checkout exists).
+ * The one lossy case is a linked worktree whose git metadata is unreadable or
+ * stale (main checkout moved/deleted before `git worktree repair`): its ledger
+ * then stays local. Not fail-closed on purpose: this runs on every hook event,
+ * and every writer and reader resolves through this same function, so both
+ * sides still agree on one file — no split. Ceiling: such a worktree's records
+ * stay out of the main ledger until merged by hand. Revisit when a
+ * `.orchestrator/metrics/sessions.jsonl` inside a linked worktree is found
+ * growing after #1584.
+ *
  * @param {string} [repoRoot]  an explicit root to map (skips the env/cwd rungs)
  * @param {string} [cwd=process.cwd()]
  * @returns {string}  Absolute path
@@ -630,6 +728,60 @@ export function resolveEventsLedgerRoot(repoRoot, cwd = process.cwd()) {
   return main || getProjectDir();
 }
 
+/**
+ * Why the linked worktree rooted at `root` has NO main checkout to map to, or
+ * `''` when it is no linked worktree or maps fine (#1666). A linked worktree
+ * is recognised by its `.git` FILE pointing at a gitdir that carries a
+ * `commondir` file — a submodule's gitdir has none, so a submodule stays `''`
+ * (it is its own repo, its root IS the right ledger root). Spawn-free, never
+ * throws.
+ *
+ * @param {string} root  a directory holding a `.git` entry
+ * @returns {string}
+ */
+function _unmappedLinkedWorktreeReason(root) {
+  if (_mainCheckoutOfLinkedWorktree(root)) return '';
+  try {
+    const dotGit = path.join(root, '.git');
+    if (!statSync(dotGit).isFile()) return '';
+    const match = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGit, 'utf8'));
+    if (!match) return '';
+    const gitDir = path.resolve(root, match[1]);
+    if (!existsSync(gitDir)) return `linked worktree git metadata unreadable (${gitDir} missing)`;
+    if (!existsSync(path.join(gitDir, 'commondir'))) return ''; // a submodule
+    return 'linked worktree whose common git dir is not named .git (separate-git-dir or bare repo): no main checkout';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * {@link resolveEventsLedgerRoot} plus whether it reached a MAIN checkout (#1666).
+ *
+ * `resolved: false` only when the directory the resolver mapped sits in a
+ * LINKED git worktree that has no main checkout to map to (`git init
+ * --separate-git-dir`, a bare repo's worktree, stale worktree metadata) — the
+ * resolver then falls back to the worktree itself. A plain checkout, a
+ * submodule and a non-git directory report `resolved: true`: their root is the
+ * right ledger root. Readers keep using {@link resolveEventsLedgerRoot}; a
+ * WRITER of a tracked-by-accident ledger (the session-close backfill, #1660)
+ * consults this and refuses to write into the worktree.
+ *
+ * @param {string} [repoRoot]  same as {@link resolveEventsLedgerRoot}
+ * @param {string} [cwd=process.cwd()]
+ * @returns {{ root: string, resolved: boolean, reason: string }}
+ */
+export function explainEventsLedgerRoot(repoRoot, cwd = process.cwd()) {
+  const root = resolveEventsLedgerRoot(repoRoot, cwd);
+  let mapped;
+  if (typeof repoRoot === 'string' && repoRoot.trim() !== '') mapped = path.resolve(repoRoot);
+  else if (launchDirFromEnv() !== '') mapped = path.resolve(launchDirFromEnv());
+  else mapped = path.resolve(cwd);
+  const ancestor = dotGitAncestor(mapped);
+  const reason = ancestor ? _unmappedLinkedWorktreeReason(ancestor) : '';
+  return { root, resolved: reason === '', reason };
+}
+
 // ---------------------------------------------------------------------------
 // resolveStateDir
 // ---------------------------------------------------------------------------

package/scripts/lib/plugin-update-banner.mjs

@@ -39,6 +39,7 @@
  * @module scripts/lib/plugin-update-banner
  */
 
+import { httpRequest } from './http-request.mjs';
 import { readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 
@@ -207,7 +208,7 @@ async function resolveLatestVersion({ cacheDir, now, fetchImpl }) {
   // either returns or assigns, so a `= null` seed would be dead (no-useless-assignment).
   let version;
   try {
-    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), timeoutMs: FETCH_TIMEOUT_MS });
     if (!res || res.ok !== true) return null;
     const body = await res.json();
     if (typeof body?.version !== 'string' || body.version.length === 0) return null;
@@ -235,13 +236,13 @@ async function resolveLatestVersion({ cacheDir, now, fetchImpl }) {
  * The four platforms this probe has a SOURCED update recipe for. Each string
  * is quoted from the doc that actually documents it, never invented:
  *
- *   - claude: README.md §"Upgrade" (`/plugin update ...`).
+ *   - claude: docs/install.md §"Upgrade" (`/plugin update ...`).
  *   - codex:  docs/codex-setup.md §"Refresh and Explicit Cache Invalidation" —
  *             the short-form marketplace install path, labelled Recommended
  *             there (`codex plugin marketplace upgrade` + `codex plugin add`).
  *   - cursor: README.md's per-platform install row + docs/cursor-setup.md —
  *             re-running the same install script is the documented recipe
- *             (README §"Upgrade": "...followed by the same install
+ *             (docs/install.md §"Upgrade": "...followed by the same install
  *             script you originally ran").
  *   - pi:     the PRIMARY install path is `pi install npm:session-orchestrator`
  *             (docs/pi-setup.md §"Option 1", `docs/pi-setup.md:16`), not the
@@ -262,7 +263,7 @@ async function resolveLatestVersion({ cacheDir, now, fetchImpl }) {
 const PLATFORM_UPDATE_INSTRUCTIONS = {
   claude:
     '/plugin update session-orchestrator@kanevry, then restart Claude Code ' +
-    '(from a clone: `npm run update:local` also installs the deps Claude Code refuses — docs/install.md § Upgrade)',
+    '(also installed in Codex? run `npm run update:local` from a clone — the Codex copy stays old otherwise, and it installs the deps Claude Code refuses — docs/install.md § Upgrade)',
   codex:
     'run `codex plugin marketplace upgrade kanevry && codex plugin add session-orchestrator@kanevry` ' +
     '(docs/codex-setup.md), then restart Codex',
@@ -298,11 +299,14 @@ const GENERIC_UPDATE_INSTRUCTION = 'run `npm update -g session-orchestrator`';
  * tracks its closure — adding platform.mjs as a dependency here is a
  * wave-scope change, not a two-line addition, so the fallback stays local
  * exactly like `isTruthyFlag` above (same rationale, same precedent).
- * `detectPlatform()`'s third step — a filesystem walk from `cwd` for marker
- * directories — is left out on purpose: it needs `node:fs`/`node:path`
- * traversal this probe has no other reason to carry, and every non-Claude
- * harness already sets its own compat env var, so the walk would only ever
- * re-confirm the same `'claude'` default this function already falls back to.
+ * `detectPlatform()`'s step 3 (`CODEX_THREAD_ID`) and step 4 (a filesystem
+ * walk from `cwd` for marker directories) are left out on purpose. The walk
+ * needs `node:fs`/`node:path` traversal this probe has no other reason to
+ * carry, and every non-Claude harness already sets its own compat env var, so
+ * it would only re-confirm the `'claude'` default this function falls back to.
+ * Skipping step 3 is harmless: the only caller, `hooks/on-session-start.mjs`
+ * (`checkPluginUpdate` call ~:1232), passes the platform its own full
+ * `detectPlatform()` run resolved, so this fallback does not run there.
  *
  * @param {Record<string,string|undefined>} env
  * @returns {"claude"|"codex"|"cursor"|"pi"}
@@ -344,7 +348,7 @@ function resolvePlatformFromEnv(env) {
  *   without a cache this probe would issue one npm request per session start.
  * @param {Record<string,string|undefined>} [opts.env]  Defaults to `process.env`.
  * @param {number} [opts.now]  Injected clock (ms). Defaults to `Date.now()`.
- * @param {Function} [opts.fetchImpl]  Injected fetch. Defaults to `globalThis.fetch`.
+ * @param {Function} [opts.fetchImpl]  Injected fetch. Defaults to the Stdlib HTTP helper.
  * @param {"claude"|"codex"|"cursor"|"pi"} [opts.platform]  The harness driving
  *   this session, when the caller already knows it (the SessionStart hook
  *   computes this once and could pass it straight through). Falls back to
@@ -370,7 +374,7 @@ export async function checkPluginUpdate({
   const installedParts = parseSemver(installed);
   if (installedParts === null) return null;
 
-  const fetcher = typeof fetchImpl === 'function' ? fetchImpl : globalThis.fetch;
+  const fetcher = typeof fetchImpl === 'function' ? fetchImpl : httpRequest;
   if (typeof fetcher !== 'function') return null;
 
   const latest = await resolveLatestVersion({ cacheDir, now, fetchImpl: fetcher });