session-orchestrator 5.3.0 → 5.5.0

package/scripts/lib/owner-yaml.mjs

@@ -36,6 +36,16 @@
  *   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)
+ *   vault-integration:      (optional; host-local switch for the vault-integration gate — SO#1448)
+ *     enabled: boolean      (false = off on this host; true is ignored — the host may not enable)
+ *     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)
+ *   vault-dirs:             (optional list; per-directory vault-dir — agents/vault#319)
+ *     - path: string                       (the vault directory)
+ *       match: { path-prefix: string }     (required; cwd directory prefix, first match wins)
+ *       name: string                       (optional label, defaults to path)
+ *                            precedence env SO_VAULT_DIR > this > paths.vault-dir > committed
  *
  * ── Exports ───────────────────────────────────────────────────────────────────
  *
@@ -44,7 +54,8 @@
  *   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/vaults/baselines) — #820
+ *                                sections (paths/dispatcher/vault-integration/vaults/
+ *                                baselines/vault-dirs) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
  *
@@ -202,9 +213,12 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * sections — currently `scripts/lib/owner-config-banner.mjs`, which derived the
  * #1244 "survived a whole-file discard" set from a hand-mirrored local copy.
  * Frozen so a consumer cannot mutate the shared array.
+ *
+ * `vault-integration` has no `getDefaults()` entry: absent means "no host
+ * override", so a dropped section simply leaves the committed gate in force.
  */
 export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
-  Object.freeze(['paths', 'dispatcher'])
+  Object.freeze(['paths', 'dispatcher', 'vault-integration'])
 );
 
 /**
@@ -213,7 +227,10 @@ export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
  * `parseNamedVaults`/`parseBaselines` — that already drops bad entries with
  * its own WARN). Surfaced here only via `sectionWarnings`, never dropped.
  */
-const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines']);
+const OPTIONAL_LIST_SECTIONS = /** @type {const} */ (['vaults', 'baselines', 'vault-dirs']);
+
+/** Host-settable vault-integration modes (mirrors VAULT_MODE_VALUES in config-schema.mjs). */
+const VALID_VAULT_INTEGRATION_MODES = ['off', 'warn', 'strict'];
 
 /** Canonical validation-order — MUST match the pre-#820 inline validation order. */
 const SECTION_ORDER = /** @type {const} */ ([
@@ -421,6 +438,35 @@ export function validateOwnerSections(obj) {
     sections.dispatcher = { valid: errors.length === 0, errors };
   }
 
+  // ── vault-integration (optional; host-local gate switch — SO#1448) ──────────
+  // STRICT enum validation, unlike `dispatcher`: a typo like `mode: of` must not
+  // fall through to the committed `strict` silently while the operator believes
+  // the host is off. An invalid section is dropped (and reported) on its own —
+  // `paths` and every other section survive (#820 per-section tolerance).
+  {
+    const errors = [];
+    const vi = obj['vault-integration'];
+    if (vi !== undefined && vi !== null) {
+      if (!isPlainObject(vi)) {
+        errors.push('vault-integration must be an object when present');
+      } else {
+        if (vi.enabled !== undefined && vi.enabled !== null && typeof vi.enabled !== 'boolean') {
+          errors.push(`vault-integration.enabled must be a boolean, got: ${typeof vi.enabled}`);
+        }
+        if (
+          vi.mode !== undefined &&
+          vi.mode !== null &&
+          !VALID_VAULT_INTEGRATION_MODES.includes(vi.mode)
+        ) {
+          errors.push(
+            `vault-integration.mode must be one of ${VALID_VAULT_INTEGRATION_MODES.join(', ')}, got: ${JSON.stringify(vi.mode)}`,
+          );
+        }
+      }
+    }
+    sections['vault-integration'] = { 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
@@ -512,6 +558,47 @@ export function validateOwnerSections(obj) {
     sections.baselines = { valid: errors.length === 0, errors };
   }
 
+  // ── vault-dirs (optional; per-directory vault-dir — agents/vault#319) ────────
+  // Same entry shape as baselines: (and parsed by the same parseBaselines() with
+  // section 'vault-dirs'), except `name` is optional. List section: surfaced via
+  // sectionWarnings, never dropped — the resolver drops bad entries itself.
+  {
+    const errors = [];
+    const vaultDirs = obj['vault-dirs'];
+    if (vaultDirs !== undefined && vaultDirs !== null) {
+      if (!Array.isArray(vaultDirs)) {
+        errors.push('vault-dirs must be an array when present');
+      } else {
+        for (let i = 0; i < vaultDirs.length; i++) {
+          const entry = vaultDirs[i];
+          if (!isPlainObject(entry)) {
+            errors.push(`vault-dirs[${i}] must be an object`);
+            continue;
+          }
+          if (typeof entry.path !== 'string' || entry.path.trim() === '') {
+            errors.push(`vault-dirs[${i}].path must be a non-empty string`);
+          }
+          if (
+            entry.name !== undefined &&
+            entry.name !== null &&
+            (typeof entry.name !== 'string' || entry.name.trim() === '')
+          ) {
+            errors.push(`vault-dirs[${i}].name must be a non-empty string when present`);
+          }
+          if (!isPlainObject(entry.match)) {
+            errors.push(`vault-dirs[${i}].match must be an object`);
+          } else if (
+            typeof entry.match['path-prefix'] !== 'string' ||
+            entry.match['path-prefix'].trim() === ''
+          ) {
+            errors.push(`vault-dirs[${i}].match.path-prefix must be a non-empty string`);
+          }
+        }
+      }
+    }
+    sections['vault-dirs'] = { valid: errors.length === 0, errors };
+  }
+
   const errors = SECTION_ORDER.flatMap((name) => sections[name].errors);
   return { sections, errors };
 }
@@ -540,10 +627,10 @@ 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) is instead replaced by its default value — the rest of the
+ * dispatcher, vault-integration) 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) are passed through UNTOUCHED even when strict-invalid — their
+ * baselines, vault-dirs) are passed through UNTOUCHED even when strict-invalid — their
  * consumers already run a lenient parse-at-point-of-use pass — and are
  * surfaced only via `sectionWarnings` (never dropped, never counted towards
  * `'partial'`).
@@ -658,6 +745,14 @@ export function loadOwnerConfig(opts = {}) {
         discardDropped.push({ section: name, errors: sec.errors });
       }
     }
+    // `vault-dirs:` (agents/vault#319) survives the discard too, raw — exactly as
+    // on the required-valid branch below; parseBaselines() drops bad entries at
+    // point-of-use. Dropping it would hand a repo under a declared prefix the
+    // host-wide `paths.vault-dir` (which DOES survive above): the silent vault
+    // override #319 exists to prevent, triggered by an unrelated `tone:` typo.
+    if (parsed['vault-dirs'] !== undefined && parsed['vault-dirs'] !== null) {
+      discardConfig['vault-dirs'] = parsed['vault-dirs'];
+    }
     const discardResult = { config: discardConfig, source: 'defaults', errors: allErrors };
     if (discardDropped.length > 0) discardResult.droppedSections = discardDropped;
     return discardResult;
@@ -673,7 +768,10 @@ export function loadOwnerConfig(opts = {}) {
   for (const name of OPTIONAL_OBJECT_SECTIONS) {
     const sec = sections[name];
     if (sec && !sec.valid) {
-      config[name] = defaults[name];
+      // A section without a default (vault-integration) is removed, not set to
+      // `undefined`: js-yaml's dump rejects undefined values on a write-back.
+      if (defaults[name] === undefined) delete config[name];
+      else config[name] = defaults[name];
       droppedSections.push({ section: name, errors: sec.errors });
       const firstError = sec.errors[0] ?? 'invalid section';
       console.warn(

package/scripts/lib/persona-panel/catalog-loader.mjs

@@ -261,7 +261,7 @@ export function validatePersonaSpec(rawSpec, sourcePath) {
       pushError(
         'model',
         'enum',
-        `model must be one of ${[...ALLOWED_MODEL_ALIASES].join('|')} or a full model ID like "claude-opus-4-7" (got ${JSON.stringify(m)})`,
+        `model must be one of ${[...ALLOWED_MODEL_ALIASES].join('|')} or a full model ID like "claude-opus-5-5" (got ${JSON.stringify(m)})`,
       );
     }
   }

package/scripts/lib/platform.mjs

@@ -8,12 +8,12 @@
  *   - plain constants (no filesystem work): SO_SHARED_DIR, SO_OS, SO_IS_WINDOWS,
  *     SO_IS_WSL, SO_PATH_SEP
  *   - pure resolvers: detectPlatform, resolvePluginRoot, resolveProjectDir,
- *     resolveStateDir, resolveConfigFile
+ *     resolveSessionRoot, resolveStateDir, resolveConfigFile
  *
  * NOTHING in this module touches the filesystem at import time.
  */
 
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, realpathSync, statSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
@@ -249,6 +249,210 @@ export function resolveProjectDir(platform) {
   return cwd;
 }
 
+// ---------------------------------------------------------------------------
+// resolveSessionRoot (#1492)
+// ---------------------------------------------------------------------------
+
+/**
+ * Basename of a worktree the HARNESS creates for an `isolation: "worktree"`
+ * subagent: `agent-` + the agent id. Measured 2026-10-02 over this host's
+ * transcripts: 13481 `.claude/worktrees/agent-<hex>` hits, every agent id of the
+ * form `a` + 16 hex (`agent-a00828908cdd83bd8`). A worktree a SESSION enters
+ * (`EnterWorktree`, `claude --worktree <name>`) lives in the same directory under
+ * a chosen name (`landing-produktschau`, `s71-politur`), so the name is the only
+ * discriminator the path offers.
+ */
+const HARNESS_AGENT_WORKTREE_RE = /^agent-[0-9a-f]{8,}$/;
+
+/**
+ * The first non-blank launch-dir env var, in `resolveProjectDir()` order, or `''`.
+ * Trimmed: a whitespace-only value is truthy and would otherwise win
+ * (`development.md` § Error Handling, env-var fallback whitespace trap).
+ *
+ * The ONE definition of "the launch dir the harness states": the clamp in
+ * {@link resolveSessionRoot} and the relocation trace in `hooks/enforce-scope.mjs`
+ * must read the same chain, so a second copy of it is a second definition.
+ *
+ * @returns {string}
+ */
+export function launchDirFromEnv() {
+  for (const name of ['CLAUDE_PROJECT_DIR', 'CODEX_PROJECT_DIR', 'CURSOR_PROJECT_DIR', 'PI_PROJECT_DIR']) {
+    const value = (process.env[name] || '').trim();
+    if (value !== '') return value;
+  }
+  return '';
+}
+
+/**
+ * The nearest directory at or above `cwd` holding a `.git` entry — a directory,
+ * or the FILE a linked worktree carries — or `''` when none does. Git's own repo
+ * discovery walks up looking for exactly this entry, so where git answers, both
+ * agree (measured 2026-10-02: same answer, 0.017 ms here vs 4.57 ms for a
+ * `git rev-parse --show-toplevel` spawn). Existence only — the entry is not
+ * validated, which git would do.
+ *
+ * Not `walkUpFor(cwd, '.git', 'any')`: its home-directory boundary exists for
+ * PLATFORM markers (#1139); a repo whose root is `$HOME` is still a repo root.
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function dotGitAncestor(cwd) {
+  for (let dir = path.resolve(cwd); ; dir = path.dirname(dir)) {
+    if (existsSync(path.join(dir, '.git'))) return dir;
+    if (path.dirname(dir) === dir) return '';
+  }
+}
+
+/**
+ * `<P>` when `root` is a harness subagent worktree `<P>/.claude/worktrees/agent-<hex>`
+ * whose parent `<P>` is itself a working copy; otherwise `root` unchanged.
+ *
+ * @param {string} root
+ * @returns {string}
+ */
+function _liftHarnessAgentWorktree(root) {
+  if (!HARNESS_AGENT_WORKTREE_RE.test(path.basename(root))) return root;
+  const worktreesDir = path.dirname(root);
+  if (path.basename(worktreesDir) !== 'worktrees') return root;
+  const stateDir = path.dirname(worktreesDir);
+  if (path.basename(stateDir) !== '.claude') return root;
+  const parent = path.dirname(stateDir);
+  return existsSync(path.join(parent, '.git')) ? parent : root;
+}
+
+/**
+ * The NATIVE realpath, or the resolved spelling when the path does not exist.
+ *
+ * `realpathSync.native`, not the JS `realpathSync`: on a case-insensitive
+ * volume (APFS default) the JS form resolves symlinks but keeps the CALLER's
+ * letter case, so `/users/me/repo` stayed `/users/…` beside the git-found
+ * `/Users/…`, `path.relative` answered `../../users/…` and the clamp was
+ * skipped (#1504 point 8, measured 2026-10-03 on a home dir typed lowercase:
+ * JS `/users/<me>`, native `/Users/<me>`). Every comparison in the clamp chain
+ * goes through this one function — mixing the two forms re-opens the split.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function _canonical(p) {
+  try { return realpathSync.native(p); } catch { return path.resolve(p); }
+}
+
+/**
+ * Is `child` a STRICT descendant of `parent` (never `parent` itself)? Both sides
+ * canonical, so macOS `/tmp` vs `/private/tmp` cannot split one directory in two.
+ *
+ * @param {string} child
+ * @param {string} parent
+ * @returns {boolean}
+ */
+function _isStrictlyInside(child, parent) {
+  const rel = path.relative(_canonical(parent), _canonical(child));
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+
+/**
+ * The SESSION ROOT (#1492) — the working copy whose control files belong to the
+ * session a hook fires in: `wave-scope.json`, the `.orchestrator/` ledgers, the
+ * event records. One resolver for every hook that reads them (enforce-scope,
+ * enforce-commands, post-bash-write-verify, pre-task-scope-disjoint).
+ *
+ * NOT the launch dir whenever the session works elsewhere: `$CLAUDE_PROJECT_DIR`
+ * stays on the dir the session was LAUNCHED in after it enters a worktree
+ * (docs/en/hooks § "Worktrees are different"), while the coordinator writes
+ * `wave-scope.json` into that worktree. Read from the launch dir, the manifest
+ * was absent and every scope gate allowed everything for the whole session,
+ * silently (#1492, measured in session main-2026-10-02-session-21); preferred
+ * for the dispatch ledger it also gave every worktree session of one launch dir
+ * ONE shared ledger and the wave key `w?` (measured on be6a2e3e).
+ *
+ * NOT the payload `cwd` itself: it follows the session's `cd` (docs/en/hooks
+ * § "cwd follows Claude"), and a `cd sub` must not move the session's state into
+ * `<root>/sub` — a second, empty ledger whose collisions were allowed (#1489 Pkt 6).
+ *
+ * NEVER ABOVE the launch dir: a session launched in a repo SUBDIRECTORY (a
+ * monorepo package, a project under a git-tracked `$HOME`) keeps its manifest
+ * there. The repo root above it holds none, so resolving to it switched every
+ * scope gate off (review HIGH-1 on 4fdbc469, measured DENY → ALLOW).
+ *
+ * Precedence:
+ *   1. no payload `cwd` → `resolveProjectDir()`, the pre-#1492 answer unchanged;
+ *   2. the repo root of `cwd` — `toplevel` when the caller already holds
+ *      `git rev-parse --show-toplevel` of it, else the nearest `.git` ancestor
+ *      (`dotGitAncestor`), which answers the same without a spawn, so neither a
+ *      timed-out git (review MED on 63f35e8c) nor a hot-path budget can send a
+ *      worktree session back to the launch dir — lifted to `<P>` when it is a
+ *      harness subagent worktree `<P>/.claude/worktrees/agent-<hex>` (below),
+ *      then replaced by the launch dir from env (`launchDirFromEnv`) when it
+ *      lies strictly ABOVE it;
+ *   3. the launch dir from env (`CLAUDE_PROJECT_DIR` → `CODEX_PROJECT_DIR` →
+ *      `CURSOR_PROJECT_DIR` → `PI_PROJECT_DIR`), only when `cwd` is in no repo;
+ *   4. `cwd`.
+ *
+ * The clamp reads the SAME launch-dir chain as rung 3, not `$CLAUDE_PROJECT_DIR`
+ * alone. The Cursor and Pi bridges delete `CLAUDE_PROJECT_DIR` and set their
+ * own `*_PROJECT_DIR` to the payload `cwd` on every call (`cursor-hook-bridge.mjs`,
+ * `pi-hook-bridge.mjs`); a clamp on `$CLAUDE_PROJECT_DIR` alone therefore never
+ * fired there, and a Cursor/Pi workspace in a repo SUBDIRECTORY climbed to the
+ * repo root, found no manifest and allowed every write (review HIGH-1 on
+ * b57e572c, measured end-to-end through `cursor-hook-bridge.mjs`: DENY at
+ * ff3e43b5 → ALLOW). For a Claude session nothing changes — `$CLAUDE_PROJECT_DIR`
+ * is first in the chain. For a bridge session the answer is the payload `cwd`
+ * whenever it sits in a repo, which is exactly what the bridges resolved before
+ * #1492 (`resolveProjectDir()` → their `*_PROJECT_DIR` → the payload `cwd`).
+ * The clamp does not ask whether `cwd` lies inside the launch dir: an
+ * `isolation: "worktree"` agent's `cwd` never does, and it must clamp too (see
+ * THE LIFT).
+ *
+ * THE LIFT. An `isolation: "worktree"` subagent's hook payload carries the
+ * worktree the harness made for it, `<P>/.claude/worktrees/agent-<hex>`. That
+ * worktree is a repo root of its own and holds no manifest, so rung 2 alone
+ * would disarm scope enforcement for every such agent. The harness puts it under
+ * the LAUNCH checkout, so `<P>` is what `$CLAUDE_PROJECT_DIR` resolved to before
+ * #1492 — the lift keeps exactly that, and the clamp keeps it for a launch in a
+ * subdirectory of `<P>`. It is keyed on the PATH SHAPE, never on which candidate
+ * holds a manifest: a root picked because a control file is readable there
+ * 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
+ *    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.
+ *  - 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
+ *    manifest used to apply. Same relocation `pre-task-scope-disjoint` has
+ *    keyed its ledger on since #1489. Revisit if an `orchestrator.scope.*`
+ *    record or a review ever shows an out-of-scope write made after such a `cd`.
+ *  - A session worktree NAMED like a harness one (`agent-` + 8 or more hex) is
+ *    lifted to its parent — the pre-#1492 launch-dir behaviour for that one
+ *    session, not a new failure. Revisit if the harness changes its naming.
+ *  - A Cursor/Pi bridge session follows its payload `cwd`, as it did before
+ *    #1492: the bridges hand over no launch dir distinct from that `cwd`, so a
+ *    bridge session whose `cwd` moves into a subdirectory without a manifest is
+ *    unenforced there. Not a new failure — the pre-#1492 bridge answer. Revisit
+ *    when a bridge hands over a stable workspace root separately from the
+ *    payload `cwd` — then clamp on that instead.
+ *
+ * @param {string|undefined} cwd       the hook payload's `cwd`
+ * @param {string} [toplevel]          `git rev-parse --show-toplevel` of `cwd`, `''` when unknown
+ * @returns {string}  Absolute path
+ */
+export function resolveSessionRoot(cwd, toplevel = '') {
+  if (typeof cwd !== 'string' || cwd.trim() === '') return resolveProjectDir();
+  const repoRoot = (typeof toplevel === 'string' ? toplevel : '') || dotGitAncestor(cwd);
+  if (!repoRoot) return launchDirFromEnv() || cwd;
+  const root = _liftHarnessAgentWorktree(repoRoot);
+  const launch = launchDirFromEnv();
+  return launch !== '' && _isStrictlyInside(launch, root) ? launch : root;
+}
+
 // ---------------------------------------------------------------------------
 // resolveStateDir
 // ---------------------------------------------------------------------------

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

@@ -260,7 +260,9 @@ async function resolveLatestVersion({ cacheDir, now, fetchImpl }) {
  * @type {Record<"claude"|"codex"|"cursor"|"pi", string>}
  */
 const PLATFORM_UPDATE_INSTRUCTIONS = {
-  claude: '/plugin update session-orchestrator@kanevry, then restart Claude Code',
+  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)',
   codex:
     'run `codex plugin marketplace upgrade kanevry && codex plugin add session-orchestrator@kanevry` ' +
     '(docs/codex-setup.md), then restart Codex',