session-orchestrator 5.1.0 → 5.3.0

package/scripts/lib/validate/confidential-names.mjs

@@ -177,6 +177,16 @@ export function inspectConfidentialNames({ namesPath, deps = {} } = {}) {
   // Unconfigured → no list, no noise. This is the normal case for public repos
   // and for any host that has not opted into confidential-name scanning.
   if (typeof namesPath !== 'string' || namesPath.trim() === '') {
+    // UNREACHABLE from the one production caller today (#1273 P1):
+    // `check-owner-leakage.mjs` resolves `namesPath` via `resolveHostPath()`
+    // and returns its own early `disabledReason` on an empty/non-string path
+    // BEFORE ever calling `inspectConfidentialNames` — so in production this
+    // branch never runs. It is reachable only for a direct caller (or a test)
+    // that skips that pre-filter. Kept regardless: `status` is part of the
+    // documented public contract every deep importer may switch on, and
+    // 'unconfigured' is the correct answer for exactly this input shape.
+    // REVISIT TRIGGER (BV-004): the production caller stops pre-filtering an
+    // empty/non-string `namesPath` before calling `inspectConfidentialNames`.
     return { status: 'unconfigured', names: [] };
   }
 

package/scripts/lib/validate-vendored-rules.mjs

@@ -6,9 +6,12 @@
  * Catches vendoring bugs that are invisible at the source-of-truth layer but
  * become live footguns once synced into a target repo:
  *
- *   - `paths:` frontmatter — `rule-loader.mjs` only understands `globs:`; a
- *     `paths:` key is silently ignored, so the rule loads as always-on
- *     instead of the intended glob-scoped subset.
+ *   - `paths:` frontmatter in a `rules/` LIBRARY SOURCE — a vendoring-
+ *     CONVENTION gate, not a loader-compatibility one. Since #795
+ *     `rule-loader.mjs` accepts `paths:` as an alias for `globs:`, so such a
+ *     rule IS glob-scoped; `globs:` stays the canonical form for a rule
+ *     vendored out through the library (#742). See § Scope below — this probe
+ *     never judges a repo's own consolidated `.claude/rules/` files.
  *   - Missing provenance header — `rules-sync.mjs` detects "plugin-owned vs.
  *     local override" purely by checking whether the first line starts with
  *     `PLUGIN_HEADER_PREFIX`. A source file missing that header gets
@@ -31,6 +34,25 @@
  * module imports the already-exported `parseGlobsFrontmatter` from
  * `rule-loader.mjs` directly.
  *
+ * ## Scope: the `rules/` fleet library, never a repo's own `.claude/rules/`
+ *
+ * Every production caller feeds this module SOURCE files from the plugin's
+ * fleet library: `syncRules()` (`rules-sync.mjs`) validates
+ * `<pluginRoot>/rules/<relPath>` for each entry listed in `rules/_index.md`
+ * BEFORE writing the vendored copy into a consumer's `.claude/rules/` — the
+ * written target is never read back through the gate. The CLI's `--dir` is
+ * operator-supplied and means that same library.
+ *
+ * This is load-bearing for `paths-frontmatter`: a repo's own CONSOLIDATED rules
+ * under `.claude/rules/` are `paths:`-canonical by design, because Claude
+ * Code's native loader reads ONLY `paths:` and treats a rule without it as
+ * always-on (`validate/check-rules.mjs` #1108; `docs/rule-authoring.md`
+ * § Consolidated rules point 3). Measured 2026-09-16 in this repo: 10
+ * path-scoped rule files there, 9 of them `paths:`-only. Pointing `--dir` at
+ * such a tree would emit findings that, if obeyed, UNDO that consolidation —
+ * which is also why `check-rules.mjs` deliberately does not duplicate this
+ * probe for `.claude/rules/`.
+ *
  * @module validate-vendored-rules
  */
 
@@ -40,6 +62,7 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { parseGlobsFrontmatter } from './rule-loader.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 // Mirrors rules-sync.mjs's exported PLUGIN_HEADER_PREFIX (rules-sync.mjs
 // line ~13). NOT imported from there on purpose: rules-sync.mjs imports
@@ -478,10 +501,17 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
         // `paths:`-only rule IS glob-scoped. The probe itself stays: it enforces the canonical
         // vendoring form, which is a convention gate, not a loader-compatibility gate. That
         // intent survives #795 and is the subject of the #742 fleet canonicalisation sweep.
+        // SCOPE (2026-09-16): this fires only over `rules/` library sources — the module doc's
+        // § Scope section names every caller. Do NOT re-point it at a repo's own
+        // `.claude/rules/`: those consolidated files are `paths:`-canonical and obeying this
+        // remedy there would undo the consolidation (docs/rule-authoring.md point 3).
         message:
           `${relPath}: frontmatter declares a top-level 'paths:' key. It is a recognized alias ` +
           `for 'globs:' (issue #795), so the rule does load glob-scoped — but 'globs:' is the ` +
-          `canonical form for vendored rules. Migrate to 'globs:' (see issue #742).`,
+          `canonical form for a rule VENDORED OUT through the plugin's rules/ library, which is ` +
+          `this probe's only population. Migrate to 'globs:' (see issue #742). This does NOT ` +
+          `apply to a repo's own consolidated .claude/rules/ files — those are paths:-canonical ` +
+          `(Claude Code's native loader reads only 'paths:') and this gate never scans them.`,
         line: lineWithinFrontmatter(fm.startLine, fm.body, pathsMatch.index),
       });
     }
@@ -587,8 +617,9 @@ export function validateRuleContent({ content, relPath, targetRoot = null, requi
 }
 
 /**
- * Validates every `*.md` rule file under `dir`, recursively (skips dotfiles
- * and `_index.md`).
+ * Validates every `*.md` rule file under `dir`, recursively (skips dotfiles,
+ * `_index.md` and `README.md` — neither is a vendored rule: `rules-sync.mjs`
+ * vendors only the entries listed in `_index.md`, #1164).
  *
  * When `pluginRoot` is given, every scanned file is additionally passed through
  * `scanVendoringLeaks()` and the findings are collected into the additive
@@ -612,7 +643,7 @@ export function validateRulesDir({ dir, targetRoot = null, requireProvenance = f
       const absPath = join(absDir, entry.name);
       if (entry.isDirectory()) {
         files.push(...collectRuleFiles(absPath));
-      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_index.md') {
+      } else if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_index.md' && entry.name !== 'README.md') {
         files.push(relative(dir, absPath).replace(/\\/g, '/'));
       }
     }
@@ -652,11 +683,7 @@ export function validateRulesDir({ dir, targetRoot = null, requireProvenance = f
 
 const __filename = fileURLToPath(import.meta.url);
 
-const isMain =
-  typeof process !== 'undefined' &&
-  process.argv[1] !== null &&
-  process.argv[1] !== undefined &&
-  resolve(process.argv[1]) === resolve(__filename);
+const isMain =isMainModule(import.meta.url);
 
 /**
  * @param {{ ok: boolean, files: Array<{ file: string, violations: RuleViolation[] }>, errorCount: number, warnCount: number }} result

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

@@ -5,10 +5,18 @@
  * vault writes under `40-learnings/<repoNs>/` and `50-sessions/<repoNs>/`.
  *
  * Contract:
- *   resolveRepoNamespace({ vaultName?, cwd? }) → string
+ *   resolveRepoNamespace({ vaultName?, repoRoot? }) → string
  *
- *   - Pure + deterministic (given the same git remote / cwd / vaultName input,
- *     and the same host-local pseudonym map).
+ *   - Pure + deterministic (given the same vaultName, the same `.vault.yaml`
+ *     under `repoRoot`, the same git remote, and the same host-local pseudonym
+ *     map).
+ *   - `repoRoot` (#1389) selects the directory whose `.vault.yaml` is read;
+ *     it defaults to `process.cwd()`. Named limit: it scopes ONLY that lookup —
+ *     the {@link deriveRepo} fallback still resolves from the process cwd and
+ *     is cached per process, so a `repoRoot` that differs from the cwd AND has
+ *     no declared slug falls back to the cwd's git identity. Every production
+ *     caller passes its own cwd today; revisit if a caller ever mirrors a repo
+ *     other than the one it runs in.
  *   - Returns a lowercase kebab slug safe for use as a filesystem path segment.
  *   - Host-local pseudonym mapping (Epic #725 D5): consulted ONLY at the redaction
  *     site (only when a segment is owner-leaky). If such a repo (raw or sanitised)
@@ -47,6 +55,7 @@ import { isOwnerLeakySegment } from '../../lib/validate/check-owner-leakage.mjs'
 import { loadPseudonymMap } from './pseudonym-map.mjs';
 import { loadHostPaths, resolveHostPath } from '../config/host-paths.mjs';
 import { isQueryFailure, resolvePreferredRemote } from '../vcs-repo-spec.mjs';
+import { readVaultSlug } from '../vault-yaml.mjs';
 
 // ── Lazy pseudonym-map path resolution (Epic #725 D5) ────────────────────────
 // The map path comes from env SO_NAMESPACE_MAP > owner.yaml paths.namespace-map-path
@@ -237,19 +246,48 @@ function lookupPseudonym(base, seg) {
  *
  * @param {object}  [opts]
  * @param {string|null} [opts.vaultName] - Optional override for the repo identifier.
- *   When non-empty and non-whitespace, used in place of the git-derived repo name.
- *   When absent, the namespace is derived from the git origin via deriveRepo().
+ *   When non-empty and non-whitespace, used in place of the declared/git-derived
+ *   repo name. When absent, the base is the repo's declared `.vault.yaml`
+ *   `metadata.slug` (#1131), else the git origin via deriveRepo().
+ * @param {string|null} [opts.repoRoot] - Directory whose `.vault.yaml` supplies
+ *   the declared slug (#1389). `undefined`/`null` → `process.cwd()`. Does NOT
+ *   redirect the deriveRepo() fallback (see the module header's named limit).
  * @returns {string} A single kebab-slug path segment, e.g. 'session-orchestrator'.
  *   Special returns:
  *   - 'unknown-repo'  — slug derivation produced an empty string.
  *   - 'redacted-repo' — the raw or slugified value matched an owner-leakage pattern
  *     (CP1 personal home path / CP6 private slug / CP10 personal name in Projects path).
  */
-export function resolveRepoNamespace({ vaultName = null } = {}) {
-  // Choose the base identifier: explicit override first, then git-derived.
+export function resolveRepoNamespace({ vaultName = null, repoRoot = null } = {}) {
+  // Choose the base identifier. Precedence: explicit `vaultName` override >
+  // the repo's declared `.vault.yaml` `metadata.slug` (#1131) > git-derived.
+  //
+  // WHY the slug sits HERE and not in deriveRepo(): deriveRepo() is the RAW
+  // repo IDENTITY (`org/repo`) and has consumers that want exactly that and
+  // nothing else — `vault-relocation-rules.mjs`, `relocate-vault-corpus.mjs`,
+  // `named-vault-resolver.mjs` (which documents the `org/repo-name` format).
+  // #1131 concerns the vault FOLDER namespace, which is what THIS function
+  // decides, so the lookup belongs at this candidate-selection point.
+  //
+  // Note what this placement does NOT buy: the `source-repo:` frontmatter is
+  // this function's output, not deriveRepo()'s (#732; process.mjs deliberately
+  // shares ONE value between the write path and the rendered field), so a repo
+  // whose declared slug differs from its derived name gets a new `source-repo`
+  // either way. That is inherent to moving the folder, not a side effect of
+  // where the lookup lives.
+  //
+  // It sits BELOW `vaultName` (an explicit per-call/operator override must stay
+  // honourable) and ABOVE derivation (a declared registration beats a guess from
+  // the remote URL or the checkout directory: the remote answers "where does
+  // this code live?", the slug answers "which vault project IS this?", and a
+  // host-side rename legitimately diverges the two). It sits ABOVE the leak
+  // guard below deliberately — a declared slug is operator data flowing into a
+  // written path and is checked by CP1/CP6/CP10 and the pseudonym map exactly
+  // like any git-derived identifier.
+  const declaredSlug = readVaultSlug(repoRoot ?? process.cwd());
   const base = (vaultName && typeof vaultName === 'string' && vaultName.trim())
     ? vaultName.trim()
-    : deriveRepo();
+    : (declaredSlug ?? deriveRepo());
 
   // Sanitise: collapse to last path segment, lowercase, strip non-[a-z0-9-].
   const seg = subjectToSlug(base);

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

@@ -666,8 +666,12 @@ export async function processLearning(rawEntry, _lineNum, ctx) {
     });
   }
 
-  // #660: namespace new writes under a per-repo subdirectory.
-  const repoNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null });
+  // #660: namespace new writes under a per-repo subdirectory. #1389: `ctx.repoRoot`
+  // is optional — absent, resolveRepoNamespace falls back to process.cwd().
+  const repoNs = resolveRepoNamespace({
+    vaultName: ctx?.vaultName ?? null,
+    repoRoot: ctx?.repoRoot ?? null,
+  });
   // #725 D2: thread the resolved repo namespace into the learning frontmatter as
   // `source-repo` for cross-repo attribution. repoNs is already sanitised +
   // leak-guarded by resolveRepoNamespace, so it is safe to interpolate as-is. The
@@ -898,7 +902,10 @@ export async function processSession(rawEntry, _lineNum, ctx) {
   // owner-leaky repo's real name reached the vault through the session-note
   // frontmatter even though the directory AND the learning `source-repo` field
   // were already pseudonym-mapped/redacted (#732 leak-guard bypass).
-  const repoNs = resolveRepoNamespace({ vaultName: ctx?.vaultName ?? null });
+  const repoNs = resolveRepoNamespace({
+    vaultName: ctx?.vaultName ?? null,
+    repoRoot: ctx?.repoRoot ?? null,
+  });
 
   // Quality gate (PRD F1.2): skip sessions whose rendered narrative is too short.
   // Measure on the rendered markdown body so the check is schema-agnostic across

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

@@ -476,14 +476,24 @@ export function generateSessionNote(entry, options = {}) {
       // #1276: lifecycle-only records omit every older count alias. Started
       // measures participation; completed/planned-only counts retain their
       // labels so a plan or a completion count never claims dispatch coverage.
-      const completedAgents = waveCount(w.agent_count_completed);
-      const plannedAgents = waveCount(w.agent_count_planned);
+      // The `agents_*` triple is the same lifecycle measurement under the
+      // de-underscored producer spelling: `metrics-collection.md` documents
+      // `agent_count_{planned,started,completed}`, but the live ledger carries
+      // one session (`main-2026-09-18-session-1`, 5 waves, measured 2026-09-18
+      // over `.orchestrator/metrics/sessions.jsonl`) whose waves emit only
+      // `agents_planned` / `agents_started` / `agents_completed` — every one of
+      // its 15 counts rendered `?` beside a real number, exactly the #1074 bug
+      // class. Each alias sits at the precedence of its documented twin, so no
+      // cell that already rendered a value can change.
+      const completedAgents = waveCount(w.agent_count_completed) ?? waveCount(w.agents_completed);
+      const plannedAgents = waveCount(w.agent_count_planned) ?? waveCount(w.agents_planned);
       const agentsCell =
         waveCount(w.agent_count) ??
         waveCount(w.agents) ??
         waveCount(w.agents_dispatched) ??
         waveCount(w.dispatched) ??
         waveCount(w.agent_count_started) ??
+        waveCount(w.agents_started) ??
         (completedAgents === undefined ? undefined : `${completedAgents} completed`) ??
         (plannedAgents === undefined ? MISSING_CELL : `${plannedAgents} planned`);
       const filesCell = waveCount(w.files_changed) ?? waveCount(w.files) ?? MISSING_CELL;

package/scripts/lib/vault-status/narrative-mirror.mjs

@@ -43,6 +43,7 @@ import { readConfigFile, parseSessionConfig } from '../config.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { createSecretValueMasker } from '../secret-masker.mjs';
 import { expandTilde } from '../common.mjs';
+import { readVaultSlug } from '../vault-yaml.mjs';
 
 /** Frontmatter sentinel that identifies generator-owned narrative files. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-status-narrative@1';
@@ -869,15 +870,29 @@ async function runNarrativeMirror(opts) {
 
   // Defense-in-depth: when the caller omits (or passes an empty) `repo`, derive
   // it from the operator-configured `vault-name` override (#660/#832) when set,
-  // else the repoRoot basename — never silently mis-file under 'unknown' (#675
-  // review). Precedence: explicit `repo` opt > `vault-name` > basename.
+  // else the `.vault.yaml` slug (#1131), else the repoRoot basename — never
+  // silently mis-file under 'unknown' (#675 review).
   const vaultNameOverride =
     typeof vaultIntegration['vault-name'] === 'string' && vaultIntegration['vault-name'].trim()
       ? vaultIntegration['vault-name'].trim()
       : null;
-  const repoName = (typeof repo === 'string' && repo.trim().length > 0)
+  const explicitName = (typeof repo === 'string' && repo.trim().length > 0)
     ? repo
-    : vaultNameOverride ?? path.basename(path.resolve(repoRoot));
+    : vaultNameOverride;
+
+  // #1131: with NO explicit override, the repo's own `.vault.yaml`
+  // `metadata.slug` — the CANONICAL vault registration — outranks the
+  // directory basename. Precedence: explicit `repo` opt > `vault-name` >
+  // `.vault.yaml` slug > basename.
+  //
+  // WHY the two overrides still win: both are things a CALLER/operator states
+  // for THIS call (`repo` is only ever passed to override the derived name —
+  // the sole production caller, `skills/session-end/session-metrics-write.md`,
+  // passes `repoRoot` alone), so honouring the file over them would make an
+  // explicit override unhonourable. The file wins over the basename, which is
+  // a guess nobody stated.
+  const vaultYamlSlug = explicitName ? null : readVaultSlug(repoRoot);
+  const repoName = explicitName ?? vaultYamlSlug ?? path.basename(path.resolve(repoRoot));
 
   const rawVaultDir = vaultIntegration['vault-dir'];
   if (!rawVaultDir || typeof rawVaultDir !== 'string') {
@@ -886,10 +901,19 @@ async function runNarrativeMirror(opts) {
 
   const vaultDir = path.resolve(expandTilde(rawVaultDir));
   const candidateSlug = subjectToSlug(repoName) || 'unknown';
-  // Loose-match against existing 01-projects/ folders before minting a new
-  // slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
+  // A declared `.vault.yaml` slug needs no healing — it IS the canonical folder
+  // name, so resolveLooseSlug is SKIPPED for it. Running the healer over it
+  // would re-open the bug this fixes: a vault that also carries an unhealed
+  // legacy folder (e.g. `foobarapp` beside the declared `foo-bar-app`) makes
+  // the loose match ambiguous, and ambiguity falls back to the candidate —
+  // which is how a duplicate pair, once created, keeps being written to.
+  //
+  // Otherwise: loose-match against existing 01-projects/ folders before minting
+  // a new slug (issue #829 Finding 3) — see resolveLooseSlug for the ambiguity
   // rules. Falls through to `candidateSlug` unchanged on any read failure.
-  const repoSlug = resolveLooseSlug(vaultDir, candidateSlug, { readdirSync: injectedFs?.readdirSync });
+  const repoSlug = vaultYamlSlug
+    ? candidateSlug
+    : resolveLooseSlug(vaultDir, candidateSlug, { readdirSync: injectedFs?.readdirSync });
   const outputPath = resolveNarrativePath(vaultDir, repoSlug);
 
   // Defense-in-depth: ensure the resolved file stays inside the vault root.

package/scripts/lib/vault-yaml.mjs

@@ -0,0 +1,118 @@
+/**
+ * vault-yaml.mjs — Reader for a repo's `.vault.yaml` registration slug (#1131).
+ *
+ * A repo registered in the Meta-Vault carries `.vault.yaml` at its root, whose
+ * `metadata.slug` is the CANONICAL vault slug for that project — the name of
+ * its `01-projects/<slug>/` folder. Until #1131 nothing READ that key: every
+ * vault writer derived the slug from the checkout DIRECTORY name instead
+ * (`scripts/lib/vault-status/narrative-mirror.mjs` via `subjectToSlug`,
+ * `scripts/lib/vault-mirror/namespace.mjs` via `basename(process.cwd())`), so a
+ * repo whose directory name differs lexically from its registered slug had its
+ * narrative and its learnings/sessions filed under a second, wrong folder — and
+ * the loose-slug healer in narrative-mirror (#829) only repairs case and
+ * punctuation drift, never a genuinely different name.
+ *
+ * Exports:
+ *   VAULT_YAML_FILE — the basename this module reads
+ *   readVaultSlug   — repoRoot → validated `metadata.slug` string, or null
+ *
+ * Contract: NEVER throws. Absent file, unreadable file, malformed YAML, missing
+ * key, non-string value, or a value that fails the repo's slug predicate all
+ * return `null`, leaving every caller on its pre-#1131 derivation chain.
+ *
+ * Import closure is deliberately tiny (`node:fs`, `node:path`, `node:module`,
+ * `./vault-mirror/utils.mjs`) — `namespace.mjs` is documented as a leaf-ward
+ * module and must stay one.
+ */
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+import { isValidSlug } from './vault-mirror/utils.mjs';
+
+/** Basename of the per-repo vault registration file. */
+export const VAULT_YAML_FILE = '.vault.yaml';
+
+// ── Lazy js-yaml resolution ──────────────────────────────────────────────────
+//
+// Same shape (and same reason) as `getYaml()` in scripts/lib/owner-yaml.mjs:
+// a static `import yaml from 'js-yaml'` crashes any consumer running without
+// `node_modules`, at MODULE LOAD, where the failure is not catchable. Both
+// consumers of this reader are synchronous, so `createRequire` — not
+// `await import()` — is the resolution mechanism.
+
+/** @type {null | false | { load: Function }} */
+let _yaml = null;
+let _yamlWarned = false;
+
+function getYaml() {
+  if (_yaml !== null) return _yaml === false ? null : _yaml;
+  try {
+    _yaml = createRequire(import.meta.url)('js-yaml');
+  } catch {
+    _yaml = false;
+  }
+  return _yaml === false ? null : _yaml;
+}
+
+/**
+ * One-per-process actionable WARN, emitted ONLY when a `.vault.yaml` actually
+ * exists and could therefore have changed the resolved slug. A repo without the
+ * file loses nothing by the parser being absent, so it stays silent.
+ */
+function warnYamlMissing() {
+  if (_yamlWarned) return;
+  _yamlWarned = true;
+  process.stderr.write(
+    "WARN vault-yaml: 'js-yaml' is not installed — .vault.yaml cannot be parsed; " +
+      'the vault slug falls back to the directory-derived name (run \'npm install\' in the plugin directory)\n',
+  );
+}
+
+/**
+ * Read the canonical vault slug declared at `metadata.slug` in
+ * `<repoRoot>/.vault.yaml`.
+ *
+ * The value becomes a FILESYSTEM PATH SEGMENT under the operator's vault, so it
+ * is validated with the repo's existing slug predicate ({@link isValidSlug},
+ * `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`) rather than trusted. That rejects `/`, `..`,
+ * leading dots, whitespace and uppercase — this validation is a trust-boundary
+ * control, not hygiene: `.vault.yaml` is repo-supplied data, and a slug such as
+ * `../../etc` would otherwise escape the vault root.
+ *
+ * @param {string} repoRoot - absolute or relative path to the repository root.
+ * @returns {string|null} the validated slug, or `null` when it cannot be read.
+ */
+export function readVaultSlug(repoRoot) {
+  if (typeof repoRoot !== 'string' || repoRoot.trim() === '') return null;
+
+  let text;
+  try {
+    text = readFileSync(path.join(repoRoot, VAULT_YAML_FILE), 'utf8');
+  } catch {
+    // Absent, unreadable, a directory, … — all "no declared slug".
+    return null;
+  }
+
+  const yaml = getYaml();
+  if (!yaml) {
+    warnYamlMissing();
+    return null;
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(text);
+  } catch {
+    // Malformed YAML must never break a vault write.
+    return null;
+  }
+
+  if (!doc || typeof doc !== 'object') return null;
+  const metadata = doc.metadata;
+  if (!metadata || typeof metadata !== 'object') return null;
+
+  const slug = metadata.slug;
+  return isValidSlug(slug) ? slug : null;
+}

package/scripts/lib/wave-transcript-tail.mjs

@@ -55,12 +55,12 @@ import {
 } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, relative, isAbsolute } from 'node:path';
-import { pathToFileURL } from 'node:url';
 
 import { emitEvent, sessionAttribution } from './events.mjs';
 import { tryAcquireFileLock, releaseFileLock } from './file-lock.mjs';
 import { readLock, isLockLive } from './session-lock.mjs';
 import { resolveSubagentSidecar } from '../../hooks/_lib/subagent-paths.mjs';
+import { isMainModule } from './is-main-module.mjs';
 
 const DEFAULT_INTERVAL_S = 2;
 const EVENTS_FILE_REL = '.orchestrator/metrics/events.jsonl';
@@ -998,6 +998,6 @@ function main() {
 
 // Run only when executed as a script — importing for unit tests must not parse
 // vitest's argv and exit 1.
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+if (isMainModule(import.meta.url)) {
   main();
 }

package/scripts/lib/worktree/lifecycle.mjs

@@ -46,6 +46,15 @@ async function _exists(p) {
   }
 }
 
+/**
+ * The one directory session-orchestrator worktrees may live in.
+ * Host-shared: several sessions run concurrently against the same base.
+ * @returns {string}
+ */
+function _worktreeBaseDir() {
+  return path.join(os.tmpdir(), 'so-worktrees');
+}
+
 /**
  * Compute the standard branch name and tmp path for a given suffix.
  * @param {string} suffix
@@ -53,10 +62,146 @@ async function _exists(p) {
  */
 function _worktreeInfo(suffix) {
   const branch = `so-worktree-${suffix}`;
-  const wtPath = path.join(os.tmpdir(), 'so-worktrees', branch);
+  const wtPath = path.join(_worktreeBaseDir(), branch);
   return { branch, wtPath };
 }
 
+/**
+ * Resolve symlinks, returning null when the path does not exist.
+ * @param {string} p
+ * @returns {Promise<string|null>}
+ */
+async function _realpathOrNull(p) {
+  try {
+    return await fs.realpath(p);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True when `wtPath` is NOT a live working tree of any repository — i.e. either
+ * it carries no `.git` entry at all, or its `.git` file points at an
+ * administrative directory that no longer exists (the registration was dropped).
+ *
+ * A directory whose registration is intact is never an orphan: `git worktree
+ * remove --force` handles that case, so this predicate is what keeps a live
+ * worktree — including one owned by a PEER session, or by another repository —
+ * out of the delete path below.
+ *
+ * @param {string} wtPath
+ * @returns {Promise<boolean>}
+ */
+async function _isUnregisteredWorktreeDir(wtPath) {
+  const dotGit = path.join(wtPath, '.git');
+  let st;
+  try {
+    st = await fs.lstat(dotGit);
+  } catch {
+    return true; // No .git entry — not a working tree of anything.
+  }
+  // A real .git DIRECTORY means a full repository lives here; never ours to delete.
+  if (!st.isFile()) return false;
+
+  const content = await fs.readFile(dotGit, 'utf8').catch(() => '');
+  const match = /^gitdir:\s*(.+)$/m.exec(content);
+  if (!match) return false; // Unparseable — treat as live, refuse.
+
+  const adminDir = path.resolve(wtPath, match[1].trim());
+  // Admin dir still present → git knows this worktree → not an orphan.
+  return !(await _exists(adminDir));
+}
+
+/**
+ * Remove an ORPHAN worktree directory (issue #984).
+ *
+ * An interrupted `removeWorktree` drops the git registration first and can die
+ * before the directory is gone. `git worktree add` then fails with
+ * "'…' already exists" while `git worktree remove --force` fails with
+ * "'…' is not a working tree" (swallowed by nothrow) — the retry loops on the
+ * same error until someone deletes the directory by hand.
+ *
+ * SAFETY — this is a recursive delete inside library code, so every condition
+ * below is asserted in code before `fs.rm` runs. Any failed condition returns
+ * false and leaves the directory alone (the retry then fails with git's own
+ * error, which is the pre-#984 behaviour):
+ *   1. `wtPath` itself is a real directory and NOT a symlink — the LEAF is never
+ *      followed. (A symlink one level up is covered by condition 2.)
+ *   2. The literal base `<os.tmpdir()>/so-worktrees` is itself a real directory
+ *      and NOT a symlink. The base lives on a host-shared /tmp where a co-tenant
+ *      can pre-create it; without this check the realpath of a planted base
+ *      symlink BECOMES the delete root, so a `so-worktree-*` directory anywhere
+ *      on the filesystem would qualify.
+ *   3. The REALPATH of `wtPath` is a DIRECT child of the REALPATH of that base
+ *      — both sides resolved, because macOS resolves /tmp → /private/tmp and
+ *      os.tmpdir() itself may be a symlinked path.
+ *   4. The resolved basename starts with `so-worktree-`.
+ *   5. It is not a live working tree of ANY repository (see above).
+ * Note what is NOT asserted: an intermediate component of `wtPath` other than
+ * the base cannot exist — the path is `<base>/so-worktree-<suffix>`, computed by
+ * `_worktreeInfo`, never caller-supplied.
+ * `git worktree prune` is deliberately NOT used: it is repo-global and would
+ * drop a peer session's stale registration.
+ *
+ * CEILING (BV-004): the delete is bounded to one directory directly under the
+ * fixed base `<os.tmpdir()>/so-worktrees` whose name carries the `so-worktree-`
+ * prefix. Revisit when worktree paths become caller-supplied (the
+ * `validateWorkspacePath` follow-up noted above) or move out of os.tmpdir() —
+ * at that point the containment base is no longer a constant and must be passed
+ * in and validated by the caller.
+ *
+ * @param {string} wtPath
+ * @returns {Promise<boolean>} true when a directory was actually removed.
+ */
+async function _removeOrphanWorktreeDir(wtPath) {
+  let lst;
+  try {
+    lst = await fs.lstat(wtPath);
+  } catch {
+    return false; // Nothing there.
+  }
+  if (lst.isSymbolicLink() || !lst.isDirectory()) return false;
+
+  // The containment BASE must be a real directory too: on a host-shared /tmp a
+  // co-tenant can pre-create `<os.tmpdir()>/so-worktrees` as a symlink, and a
+  // realpath-resolved base would then relocate the delete root off-tmpdir.
+  const baseDir = _worktreeBaseDir();
+  let baseLst;
+  try {
+    baseLst = await fs.lstat(baseDir);
+  } catch {
+    return false; // No base directory — nothing under it to remove.
+  }
+  if (baseLst.isSymbolicLink() || !baseLst.isDirectory()) return false;
+
+  const realWt = await _realpathOrNull(wtPath);
+  const realBase = await _realpathOrNull(baseDir);
+  if (!realWt || !realBase) return false;
+  if (!isPathInside(realWt, realBase)) return false;
+  // Direct child only — matches the CEILING below; no nested path qualifies.
+  if (path.dirname(realWt) !== realBase) return false;
+  if (!path.basename(realWt).startsWith('so-worktree-')) return false;
+
+  if (!(await _isUnregisteredWorktreeDir(realWt))) return false;
+
+  // RACE WINDOW (accepted, #1390 P7): `_isUnregisteredWorktreeDir` above and
+  // `fs.rm` below are two separate syscalls, not one atomic check-then-act.
+  // Both plausible racers here are session-orchestrator sessions on the SAME
+  // host, contending over the same `<os.tmpdir()>/so-worktrees` base: one
+  // could register (`git worktree add`) or delete `realWt` in the gap between
+  // the two calls. No lock primitive guards this sub-millisecond window
+  // between our own sessions — the worst case is a benign retry (the caller's
+  // `git worktree add` above already retries once on failure), never data
+  // loss, because neither racer ever touches a path outside its own
+  // `so-worktree-*` name.
+  // REVISIT TRIGGER (BV-004): an UNRELATED process gains the ability to
+  // create or delete `so-worktree-*` directories under this base — at that
+  // point the race is no longer bounded to our own retry semantics and this
+  // window needs an actual lock, not an accepted gap.
+  await fs.rm(realWt, { recursive: true, force: true });
+  return true;
+}
+
 // ---------------------------------------------------------------------------
 // validateWorkspacePath
 // ---------------------------------------------------------------------------
@@ -136,6 +281,13 @@ export async function createWorktree(suffix, baseRef = 'HEAD', options = {}) {
     await nothrow(git`git worktree remove ${wtPath} --force`);
     await nothrow(git`git branch -D ${branch}`);
 
+    // Still on disk after the remove attempt → git has no registration for it
+    // (issue #984). Delete the orphan directory under the guards documented on
+    // _removeOrphanWorktreeDir; a live/registered worktree never reaches here.
+    if (await _exists(wtPath)) {
+      await _removeOrphanWorktreeDir(wtPath);
+    }
+
     try {
       await git`git worktree add -b ${branch} ${wtPath} ${baseRef}`;
     } catch (secondErr) {