session-orchestrator 5.12.0 → 5.13.0

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

@@ -15,7 +15,7 @@
  * via `.passthrough()`, and it is NOT rewritten retroactively by this change.
  */
 
-import { toDate, buildTag, slugifyIdSafe } from './utils.mjs';
+import { toDate, buildTag, slugifyIdSafe, noteIdFor, yamlNoteId } from './utils.mjs';
 import { stableHostname } from '../host-identity.mjs';
 import { sourceRecordValue, sourceRecordLine } from './render-learnings.mjs';
 import { sessionNarrativeText } from './retention.mjs';
@@ -118,38 +118,17 @@ function waveCount(value) {
 }
 
 /**
- * ── RENDERABLE ⊋ SCHEMA-VALID (#964) ───────────────────────────────────────
- *
- * Each generator gates on its own required-field list. Before #964 all three
- * lists were function-local `const`s with no stated relationship to
- * `REQUIRED_FIELDS` (scripts/lib/session-schema/constants.mjs) — the write-path
- * schema — which made five independent notions of "a valid session record" in
- * one codebase, drifting silently. They are lifted here, exported, and pinned
- * against `REQUIRED_FIELDS` by a mechanical superset test in
- * tests/lib/vault-mirror/render-sessions.test.mjs.
- *
- * The relationship is deliberately asymmetric, not a duplicate:
- *
- *   `REQUIRED_FIELDS`  — "this record is well-formed". The writer
- *     (scripts/emit-session.mjs) REFUSES a record that fails it.
- *   these lists        — "this record renders into a note a human can read".
- *     vault-mirror SKIPS a record that fails them; the record stays valid.
- *
- * Collapsing the two would destroy that distinction. Hence `effectiveness`:
- * optional to the writer (a record lacking it is fine), required by the v1
- * renderer (a note reading `planned=n/a, completed=n/a, carryover=n/a,
- * rate=n/a` is worse than no note — indistinguishable from a real session whose
- * metrics happened to be absent).
- *
- * The predicate here is VALUE presence (`null`/`undefined` both fail); the
- * validator's is KEY presence. See `_validateRequiredFields` for why.
+ * ── RENDERABLE AND SCHEMA-VALID (#1575) ───────────────────────────────────
+ *
+ * The generators retain route-specific required-field lists. V1 requires the
+ * canonical REQUIRED_FIELDS; legacy V2/V3 derive aggregates from other shapes
+ * and cannot be emitted by the canonical writer. Effectiveness is optional
+ * and nullable in every route, matching the writer. Unknown metrics render
+ * n/a; a measured zero remains zero. Malformed non-object metrics still fail.
+ * Required fields use VALUE presence; the validator separately checks types.
  */
 
-/**
- * v1 — the only generator reachable from a write-path-valid record (measured:
- * 205/205 live ledger records at HEAD 730ee9d route v1). Its list is
- * `REQUIRED_FIELDS` plus `effectiveness`, i.e. a strict superset.
- */
+/** V1 uses the canonical required-field set without requiring optional metrics. */
 export const RENDERABLE_SESSION_FIELDS_V1 = Object.freeze([
   'session_id',
   'session_type',
@@ -160,7 +139,6 @@ export const RENDERABLE_SESSION_FIELDS_V1 = Object.freeze([
   'total_files_changed',
   'agent_summary',
   'waves',
-  'effectiveness',
 ]);
 
 /**
@@ -183,7 +161,6 @@ export const RENDERABLE_SESSION_FIELDS_V2 = Object.freeze([
   'completed_at',
   'waves',
   'files_changed',
-  'effectiveness',
 ]);
 
 /**
@@ -200,9 +177,18 @@ export const RENDERABLE_SESSION_FIELDS_V3 = Object.freeze([
   'started_at',
   'completed_at',
   'waves',
-  'effectiveness',
 ]);
 
+/** Optional metrics share the writer's object-or-null contract in all routes. */
+function sessionEffectiveness(entry) {
+  const value = entry.effectiveness;
+  if (value === undefined || value === null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${entry.session_id})`);
+  }
+  return value;
+}
+
 /**
  * Session-ledger status → vault-frontmatter status mapping (#909).
  *
@@ -422,12 +408,9 @@ export function generateSessionNote(entry, options = {}) {
     total_files_changed,
     agent_summary,
     waves,
-    effectiveness,
   } = entry;
 
-  if (typeof effectiveness !== 'object' || effectiveness === null) {
-    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${session_id})`);
-  }
+  const effectiveness = sessionEffectiveness(entry);
   if (typeof agent_summary !== 'object' || agent_summary === null) {
     throw new Error(`vault-mirror: session entry missing nested field 'agent_summary' (session_id=${session_id})`);
   }
@@ -463,7 +446,7 @@ export function generateSessionNote(entry, options = {}) {
   // and cap the combined tag at 64 chars so the frontmatter passes the vault
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
-  const noteId = slugifyIdSafe(session_id) ?? session_id;
+  const noteId = noteIdFor(options.repoNs, slugifyIdSafe(session_id) ?? session_id);
   // #909: the real ledger status, mapped into the vault enum — never hard-coded.
   const vaultStatus = vaultStatusForSession(entry);
   const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
@@ -554,7 +537,7 @@ export function generateSessionNote(entry, options = {}) {
   const { repoNs } = options;
 
   return `---
-id: ${noteId}
+id: ${yamlNoteId(noteId)}
 type: session
 title: ${title}
 status: ${vaultStatus}
@@ -592,11 +575,9 @@ export function generateSessionNoteV2(entry, options = {}) {
   if (!Array.isArray(entry.waves)) {
     throw new Error(`vault-mirror: session entry 'waves' must be an array (session_id=${entry.session_id})`);
   }
-  if (typeof entry.effectiveness !== 'object' || entry.effectiveness === null) {
-    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${entry.session_id})`);
-  }
+  const effectiveness = sessionEffectiveness(entry);
 
-  const { session_id, session_type, started_at, completed_at, duration_seconds, branch, planned_issues, waves, files_changed, issues_closed, issues_created, effectiveness } = entry;
+  const { session_id, session_type, started_at, completed_at, duration_seconds, branch, planned_issues, waves, files_changed, issues_closed, issues_created } = entry;
 
   const created = toDate(started_at);
   const updated = toDate(completed_at);
@@ -620,7 +601,7 @@ export function generateSessionNoteV2(entry, options = {}) {
   // and cap the combined tag at 64 chars so the frontmatter passes the vault
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
-  const noteId = slugifyIdSafe(session_id) ?? session_id;
+  const noteId = noteIdFor(options.repoNs, slugifyIdSafe(session_id) ?? session_id);
   // #909: the real ledger status, mapped into the vault enum — never hard-coded.
   const vaultStatus = vaultStatusForSession(entry);
   const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
@@ -641,7 +622,7 @@ export function generateSessionNoteV2(entry, options = {}) {
   const { repoNs } = options;
 
   return `---
-id: ${noteId}
+id: ${yamlNoteId(noteId)}
 type: session
 title: ${title}
 status: ${vaultStatus}
@@ -690,14 +671,12 @@ export function generateSessionNoteV3(entry, options = {}) {
   if (typeof entry.waves !== 'number') {
     throw new Error(`vault-mirror: session entry 'waves' must be a number (session_id=${entry.session_id})`);
   }
-  if (typeof entry.effectiveness !== 'object' || entry.effectiveness === null) {
-    throw new Error(`vault-mirror: session entry missing nested field 'effectiveness' (session_id=${entry.session_id})`);
-  }
+  const effectiveness = sessionEffectiveness(entry);
 
   const {
     session_id, session_type, platform, branch, started_at, completed_at,
     duration_minutes, duration_seconds, waves, agents_dispatched, agent_summary,
-    planned_issues, effectiveness, commits, issues_closed, issues_created,
+    planned_issues, commits, issues_closed, issues_created,
     follow_ups_filed, tests_total_pre, tests_total_post, tests_added,
   } = entry;
 
@@ -727,8 +706,12 @@ export function generateSessionNoteV3(entry, options = {}) {
   const failed = as.failed ?? MISSING_VALUE;
   const spiral = as.spiral ?? MISSING_VALUE;
 
+  // A qualified cross-repo reference (`group/repo#n`, #1603) already carries
+  // its own `#`; only a bare number gets the prefix.
   const fmtIssues = (list) =>
-    Array.isArray(list) && list.length ? list.map((i) => `#${i}`).join(', ') : '—';
+    Array.isArray(list) && list.length
+      ? list.map((i) => (typeof i === 'number' ? `#${i}` : String(i))).join(', ')
+      : '—';
   const closedList = fmtIssues(issues_closed);
   const createdList = fmtIssues(issues_created);
   const followList = fmtIssues(follow_ups_filed);
@@ -752,7 +735,7 @@ export function generateSessionNoteV3(entry, options = {}) {
   // and cap the combined tag at 64 chars so the frontmatter passes the vault
   // tagPathRegex. The `id` is likewise slugified to a kebab slug below —
   // entry.session_id may carry an ISO-timestamp uppercase `T`/`:`/`.`/`Z`.
-  const noteId = slugifyIdSafe(session_id) ?? session_id;
+  const noteId = noteIdFor(options.repoNs, slugifyIdSafe(session_id) ?? session_id);
   // #909: the real ledger status, mapped into the vault enum — never hard-coded.
   const vaultStatus = vaultStatusForSession(entry);
   const tags = `[${buildTag(['session', session_type])}, ${buildTag(['status', vaultStatus])}]`;
@@ -768,7 +751,7 @@ export function generateSessionNoteV3(entry, options = {}) {
   const { repoNs } = options;
 
   return `---
-id: ${noteId}
+id: ${yamlNoteId(noteId)}
 type: session
 title: ${title}
 status: ${vaultStatus}

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

@@ -34,7 +34,7 @@
 import { readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { subjectToSlug } from './utils.mjs';
+import { subjectToSlug, noteIdFor, yamlNoteId } from './utils.mjs';
 
 /** The generator marker every mirror-written note carries. */
 export const GENERATOR_MARKER = 'session-orchestrator-vault-mirror@1';
@@ -367,7 +367,7 @@ export function renderRollup(existing, rows, { ns, month }) {
     .map((r) => `| ${r.date} | \`${r.id}\` | ${r.type} | ${r.waves} | ${r.agents} | ${r.files} |`)
     .join('\n');
   return `---
-id: ${idSlug}
+id: ${yamlNoteId(noteIdFor(null, idSlug))}
 type: session
 title: "Sessions ${month} (${label}, metrics only)"
 status: verified

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

@@ -144,6 +144,85 @@ export function slugifyIdSafe(input) {
   return slug.length >= 2 ? slug : `${slug}-x`;
 }
 
+/** The vault-sync schema's `id` cap (`skills/vault-sync/validator.mjs`, `.max(128)`). */
+export const NOTE_ID_MAX_LENGTH = 128;
+
+/**
+ * The frontmatter `id` of a generated note (#1601, #1602). The FILENAME slug
+ * stays the note's identity on disk (paths never change); the `id` adds the
+ * repo namespace so it is unique across the vault's per-repo folders — a
+ * session id or learning subject recurs across repos — and is capped at
+ * {@link NOTE_ID_MAX_LENGTH}. An over-long id keeps a 119-char prefix plus an
+ * 8-hex SHA-256 suffix of the FULL id, so two long subjects sharing a prefix
+ * stay distinct. Deterministic: the same `(repoNs, slug)` always yields the
+ * same id. Without a namespace (vault-less callers, unit tests) the slug is
+ * only capped.
+ *
+ * BV-004 ceiling: the separator is a single `-` (the schema slug forbids
+ * `--`), so namespace `a` + slug `b-c` and namespace `a-b` + slug `c` render
+ * the same id. Revisit-Trigger: the vault validator reports a duplicate id
+ * whose two notes sit in different namespace folders.
+ *
+ * @param {string|null|undefined} repoNs - the resolved repo namespace folder.
+ * @param {string} slug - the note's filename slug (or rendered session slug).
+ * @returns {string}
+ */
+export function noteIdFor(repoNs, slug) {
+  const base = String(slug ?? '');
+  const ns = typeof repoNs === 'string' && repoNs.length > 0 ? (isValidSlug(repoNs) ? repoNs : legacySubjectToSlug(repoNs)) : '';
+  const full = ns ? `${ns}-${base}` : base;
+  if (full.length <= NOTE_ID_MAX_LENGTH) return full;
+  const suffix = digestSha256Short(full);
+  return `${full.slice(0, NOTE_ID_MAX_LENGTH - suffix.length - 1).replace(/-+$/, '')}-${suffix}`;
+}
+
+/**
+ * Does a note's frontmatter `id` name the note `slug`? Accepts both the
+ * pre-#1601 id (the bare slug — a numeric one parses as the same string here,
+ * `parseFrontmatter` keeps scalars verbatim) and the current {@link noteIdFor}
+ * form, so notes written before the id change keep their ownership evidence.
+ *
+ * @param {unknown} fmId
+ * @param {string} slug
+ * @param {string|null|undefined} repoNs
+ * @returns {boolean}
+ */
+export function noteIdMatches(fmId, slug, repoNs) {
+  return typeof fmId === 'string' && (fmId === slug || fmId === noteIdFor(repoNs, slug));
+}
+
+/**
+ * The `id:` frontmatter value, always a double-quoted YAML string (#1601): an
+ * unquoted all-digit id (`id: 433`) parses as a NUMBER under a real YAML parser
+ * and fails the schema's `z.string()`.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function yamlNoteId(id) {
+  return JSON.stringify(String(id));
+}
+
+/**
+ * Replace the frontmatter `id:` line of a note — used when a displaced note
+ * moves to its disambiguated name (#1506.2), whose `id` must match the file,
+ * and by the id migration (#1601, `migrate-ids.mjs`). Only the `id:` line
+ * INSIDE the leading frontmatter block changes; every other byte — body,
+ * other fields, `[REDACTED]` spans (#1025) — is kept verbatim. A note without
+ * a frontmatter `id:` line is returned unchanged.
+ * @param {string} content
+ * @param {string} id
+ * @returns {string}
+ */
+export function withNoteId(content, id) {
+  if (!content.startsWith('---')) return content;
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) return content;
+  const head = content.slice(0, end);
+  const nextHead = head.replace(/^id:.*$/m, `id: ${yamlNoteId(id)}`);
+  return nextHead === head ? content : nextHead + content.slice(end);
+}
+
 /** Derive the first 8 chars of a UUID (strip hyphens, take first 8 hex chars). */
 export function uuidPrefix8(id) {
   return id.replace(/-/g, '').slice(0, 8);

package/scripts/lib/vault-staleness-banner.mjs

@@ -23,7 +23,7 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import path from 'node:path';
+import { resolveLedgerPath } from './ledger-path.mjs';
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
@@ -95,12 +95,9 @@ export function checkVaultStaleness({ repoRoot, now = Date.now() } = {}) {
   try {
     if (!repoRoot || typeof repoRoot !== 'string') return null;
 
-    const jsonlPath = path.join(
-      repoRoot,
-      '.orchestrator',
-      'metrics',
-      'vault-staleness.jsonl',
-    );
+    // #1722: the ledger the probe writes (skills/discovery/probes/vault-staleness.mjs)
+    // — the main checkout's when repoRoot is a linked worktree that ignores it.
+    const jsonlPath = resolveLedgerPath('.orchestrator/metrics/vault-staleness.jsonl', repoRoot);
 
     if (!existsSync(jsonlPath)) return null;
 

package/scripts/lib/vault-status/board-writer.mjs

@@ -1339,7 +1339,8 @@ export function buildSweepRepos(candidates, { thisRepoRoot } = {}) {
  * @param {object} [opts]
  * @param {string} opts.repoRoot — the calling repo (always included in the sweep).
  * @param {string} [opts.startDir] — enumeration root; omitted in production so
- *   {@link enumerateCandidates} defaults to `getConfinementRoot()` (~/Projects).
+ *   {@link enumerateCandidates} defaults to `getConfinementRoot()` (~/Projects
+ *   unless the host sets `projects-root`, #1562).
  *   Test seam only — do NOT compute `path.dirname(repoRoot)` here.
  * @param {Date|number} [opts.now] — clock seam. A `Date` is used as-is; a finite
  *   number is treated as epoch-ms (matching {@link collectRows}'s own

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

@@ -31,12 +31,15 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { emitEvent, sessionAttribution } from '../events.mjs';
-import { parseStateMd, parseMissionStatus, resolveStateMdPath } from '../state-md.mjs';
+import { parseStateMd, parseMissionStatus } from '../state-md.mjs';
+import { resolveStateMdWriteTarget, warnForeignStateMd } from '../state-md/frontmatter-mutators.mjs';
 import {
   parseFrontmatter,
   toDate,
   yamlQuoteIfNeeded,
   subjectToSlug,
+  noteIdFor,
+  yamlNoteId,
 } from '../vault-mirror/utils.mjs';
 import { matchesModuloRedaction } from '../vault-mirror/process.mjs';
 import { readConfigFile, parseSessionConfig } from '../config.mjs';
@@ -317,7 +320,7 @@ export function renderNarrative(opts) {
 
   // Frontmatter — `_generator` LAST (markdown-writer / render-sessions convention).
   lines.push('---');
-  lines.push(`id: ${noteId}`);
+  lines.push(`id: ${yamlNoteId(noteIdFor(null, noteId))}`);
   lines.push('type: session');
   lines.push(`title: ${title}`);
   lines.push(`created: ${createdValue}`);
@@ -380,6 +383,31 @@ export function resolveNarrativePath(vaultDir, repoSlug) {
   return path.join(vaultDir, '01-projects', repoSlug, '_session-narrative.md');
 }
 
+/**
+ * The `created` date of the narrative already at `outputPath` when THIS generator
+ * wrote it (#1602; same rule as board-writer.mjs). A hand-authored or foreign
+ * file, a missing one, or a malformed date yields `undefined` — the render then
+ * stamps today, exactly as on a first write. A read failure is not fatal here:
+ * `writeNarrative` reads the file again and owns that error contract.
+ *
+ * @param {string} outputPath
+ * @param {{ readFileSync?: Function, existsSync?: Function }} [injectedFs]
+ * @returns {string|undefined} `YYYY-MM-DD`
+ */
+function existingNarrativeCreated(outputPath, injectedFs) {
+  const fsExists = injectedFs?.existsSync ?? existsSync;
+  const fsReadFile = injectedFs?.readFileSync ?? readFileSync;
+  try {
+    if (!fsExists(outputPath)) return undefined;
+    const fm = parseFrontmatter(fsReadFile(outputPath, 'utf8'));
+    if (fm?.['_generator'] !== GENERATOR_MARKER) return undefined;
+    const created = fm['created'];
+    return typeof created === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(created) ? created : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 // ── Idempotent write ─────────────────────────────────────────────────────────────
 
 /**
@@ -393,6 +421,26 @@ function normalizeUpdated(content) {
   return content.replace(/^(updated:\s*)(.+)$/m, `$1${UPDATED_PLACEHOLDER}`);
 }
 
+/**
+ * The comparison form of a narrative for the noop check: {@link normalizeUpdated}
+ * plus the `id:` line dropped to a bare `id:` (#1601, release-review HOCH 2).
+ * The id differs between generations of the renderer in more than one way: the
+ * render now quotes it (`id: "x"`) where older files carry `id: x`, and
+ * `noteIdFor` caps it, so a pre-cap file can carry a longer value. Any such
+ * difference made the whole document "changed", which skipped the `[REDACTED]`
+ * comparison below and rewrote the file — with the raw secret whenever it was
+ * missing from the current env (#1025). The id is derived from the note's
+ * path, not from its content, so no id difference may ever trigger a rewrite;
+ * a schema-breaking id on disk is the job of `vault-mirror/migrate-ids.mjs`,
+ * which changes that one line and nothing else.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function normalizeForNoopCompare(content) {
+  return normalizeUpdated(content).replace(/^id:.*$/m, 'id:');
+}
+
 /**
  * Write the narrative file with idempotency guards (mirrors gitlab-portfolio
  * markdown-writer.mjs contract).
@@ -501,8 +549,9 @@ export function writeNarrative(opts) {
       // #1025 — identical once every `[REDACTED]` span already on disk is read
       // as a wildcard. See the guard-order note above for why the second arm is
       // load-bearing rather than a nicety.
-      const existingNormalized = normalizeUpdated(existingContent);
-      const candidateNormalized = normalizeUpdated(content);
+      // #1601: the id line is left out of the compare — see normalizeForNoopCompare.
+      const existingNormalized = normalizeForNoopCompare(existingContent);
+      const candidateNormalized = normalizeForNoopCompare(content);
       if (
         existingNormalized === candidateNormalized ||
         matchesModuloRedaction(existingNormalized, candidateNormalized)
@@ -963,8 +1012,15 @@ async function runNarrativeMirror(opts) {
     return { result: { action: 'skipped-invalid-path', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
   }
 
-  // Read STATE.md (best-effort; absent STATE.md → nothing to mirror).
-  const stateMdPath = resolveStateMdPath(repoRoot);
+  // Read STATE.md (best-effort; absent STATE.md → nothing to mirror). #1622:
+  // another platform's STATE.md not proven to be this process's counts as absent.
+  // #1640: `rejected` is also set when the target ITSELF is foreign
+  // (`blocked`) — never read and mirror that file either.
+  const { path: stateMdPath, rejected } = resolveStateMdWriteTarget(repoRoot);
+  if (rejected) {
+    warnForeignStateMd('mirrorNarrative', rejected, stateMdPath);
+    return { result: { action: 'skipped-no-statemd', path: outputPath }, needleCount: masker.needleCount, hits: 0, dryRun };
+  }
   let stateContents;
   try {
     stateContents = await readFile(stateMdPath, 'utf8');
@@ -976,7 +1032,10 @@ async function runNarrativeMirror(opts) {
   // parse (so `[REDACTED]` can never break it) and before the render, the
   // idempotency comparison and the write. See maskNarrative above.
   const { narrative, hits } = maskNarrative(extractNarrative(stateContents), masker);
-  const content = renderNarrative({ repo: repoName, narrative, now });
+  // #1602: `created` is the day the narrative was FIRST written — carried over
+  // from the file on disk, so only `updated` moves between runs.
+  const createdIso = existingNarrativeCreated(outputPath, injectedFs);
+  const content = renderNarrative({ repo: repoName, narrative, now, createdIso });
 
   // `chars` measures the document THIS call rendered — so it is present on
   // `skipped-noop` and `dry-run` too, where the render happened but nothing

package/scripts/lib/wave-executor/foreign-dispatch.mjs

@@ -80,6 +80,25 @@ import {
  * ever observed writing outside its worktree despite this flag, the sandbox is
  * not the boundary it is assumed to be here and the `hookTampering` check below
  * becomes the only defence rather than the backstop.
+ *
+ * `--disable-codebase-ref` keeps the CLI from starting its codebase index
+ * (#1683). Without it every run leaves a `worker-server` and an
+ * `npx typescript-language-server --stdio` pair behind; they detach via setsid,
+ * so the timeout kill in `runChild` never reaches them. Measured 2026-10-19 on
+ * cursor-agent 2026.10.01-e373342: 3 orphans per run without the flag, 0 with
+ * it, same answer either way. The foreign agent loses semantic search and
+ * LSP-backed lints; read and grep stay, and the Claude diff review remains the
+ * quality anchor. Named ceiling (BV-004): the flag is registered in the CLI but
+ * missing from `--help`, so a release may drop it silently. Revisit trigger: a
+ * `worker-server` or `typescript-language-server` with PPID 1 after a dispatch.
+ *
+ * The hidden `--disable-indexing` flag is deliberately absent (#1687): it only
+ * gates the codebase sync inside that same `worker-server`, which this argv
+ * never starts. Measured 2026-10-20 on cursor-agent 2026.10.01-e373342 with
+ * per-process `nettop` against a 1.5 MB throwaway repo: 52–71 KB out per run
+ * with or without the flag, no worker-server, while a 1.5 MB loopback control
+ * read back as exactly 1,500,000 bytes. Revisit trigger: a dispatch whose
+ * outbound volume grows with the worktree size.
  * @type {readonly string[]}
  */
 export const FOREIGN_AGENT_BASE_ARGS = Object.freeze([
@@ -87,6 +106,7 @@ export const FOREIGN_AGENT_BASE_ARGS = Object.freeze([
   '--force',
   '--sandbox',
   'enabled',
+  '--disable-codebase-ref',
 ]);
 
 /**

package/scripts/lib/win-process-tree.mjs

@@ -0,0 +1,137 @@
+/** Windows tree cleanup: PowerShell 5.1 CIM identities, then taskkill and readback. */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+// Ceiling per native call: 5 s. Revisit if measured CIM startup exceeds this;
+// a hung PowerShell must never hang gate cleanup (including the exit handler).
+const OPTIONS = { encoding: 'utf8', shell: false, windowsHide: true, timeout: 5000, maxBuffer: 16 * 1024 * 1024 };
+const system32 = () => path.join(process.env.SystemRoot || 'C:\\Windows', 'System32');
+
+function readWindowsProcesses(spawnSyncFn = spawnSync) {
+  const result = spawnSyncFn(
+    path.join(system32(), 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+    ['-NoProfile', '-NonInteractive', '-Command', 'Get-CimInstance Win32_Process | Select-Object ProcessId,ParentProcessId,CreationDate | ConvertTo-Json -Compress'],
+    OPTIONS,
+  );
+  if (result.error || result.status !== 0) throw new Error('CIM snapshot failed');
+  let parsed;
+  try {
+    parsed = JSON.parse(String(result.stdout));
+  } catch {
+    // A truncated or banner-polluted snapshot is "not measurable", never "no processes".
+    throw new Error('CIM snapshot output is not JSON');
+  }
+  const rows = Array.isArray(parsed) ? parsed : [parsed];
+  if (!rows.length || rows.some(p => !p || !Number.isInteger(p.ProcessId)
+    || !Number.isInteger(p.ParentProcessId))) {
+    throw new Error('CIM snapshot has no usable process identities');
+  }
+  return rows;
+}
+
+// PowerShell 5.1 ConvertTo-Json uses /Date(epoch milliseconds)/.
+// Other formats (including WMI dates) remain explicitly unmeasurable.
+function creationMs(row) {
+  const match = /^\/Date\((-?\d+)\)\/$/.exec(row?.CreationDate);
+  return match && Number.isFinite(Number(match[1])) ? Number(match[1]) : null;
+}
+
+function descendantIds(rows, seeds) {
+  const ids = new Set(seeds);
+  let size;
+  do {
+    size = ids.size;
+    for (const p of rows) if (ids.has(p.ParentProcessId)) ids.add(p.ProcessId);
+  } while (ids.size !== size);
+  return ids;
+}
+
+/** Same synchronous primitive for timeout and process-exit cleanup.
+ * A live ChildProcess holds libuv's Windows handle, preventing root PID reuse.
+ * After exit, only dated descendants may be targeted; the root is never killed.
+ * null survivors means unmeasurable, never a successful empty measurement.
+ */
+export function killWindowsProcessTree(pid, {
+  spawnSyncFn = spawnSync,
+  snapshotFn = () => readWindowsProcesses(spawnSyncFn),
+  child,
+  spawnedAtMs,
+  verifyTree = true,
+} = {}) {
+  const base = { signalsSent: [], aborted: null };
+  const unknown = reason => ({ ...base, ok: false, survivors: null, error: `nicht messbar auf win32: ${reason}` });
+  const rootHeld = child?.exitCode === null && child?.signalCode === null;
+  let killError = null;
+  const kill = (target, tree = true) => {
+    base.signalsSent.push('taskkill');
+    try {
+      const args = tree ? ['/PID', String(target), '/T', '/F'] : ['/PID', String(target), '/F'];
+      const result = spawnSyncFn(path.join(system32(), 'taskkill.exe'), args, OPTIONS);
+      if (result.error || result.status !== 0) killError = result.error?.message ?? `taskkill exit ${result.status}`;
+    } catch (err) { killError = String(err); }
+  };
+  if (!verifyTree) {
+    if (rootHeld) kill(pid);
+    return unknown(`nicht gemessen (verifyTree: false)${killError ? `; ${killError}` : ''}`);
+  }
+
+  let before;
+  let measurementError;
+  try {
+    before = snapshotFn();
+    if (!Array.isArray(before)) throw Error('invalid snapshot');
+  } catch (err) { measurementError = err; }
+  if (measurementError) {
+    if (rootHeld) kill(pid);
+    return unknown(measurementError);
+  }
+  const ids = descendantIds(before, [pid]);
+  const floor = Number.isFinite(spawnedAtMs) ? spawnedAtMs - 2000 : null;
+  let targets = before.filter(p => ids.has(p.ProcessId));
+  if (!rootHeld) {
+    targets = targets.filter(p => p.ProcessId !== pid);
+    if (floor === null || targets.some(p => creationMs(p) === null)) return unknown('missing descendant CreationDate or spawnedAtMs');
+    targets = targets.filter(p => creationMs(p) >= floor);
+    for (const p of targets) kill(p.ProcessId);
+  } else {
+    // Windows never rewrites ParentProcessId when a parent dies, so a process
+    // older than our root can still name the root's (reused) PID as its parent
+    // (Opus review M2, #1612). Such a process is not ours: drop it from the
+    // targets, and when one exists, end ours one by one without /T so
+    // taskkill's own PPID walk cannot reach it.
+    const rootBorn = creationMs(targets.find(p => p.ProcessId === pid)) ?? floor;
+    const stale = rootBorn === null ? [] : targets.filter(p => p.ProcessId !== pid
+      && creationMs(p) !== null && creationMs(p) < rootBorn);
+    if (stale.length === 0) {
+      kill(pid);
+    } else {
+      targets = targets.filter(p => !stale.includes(p));
+      for (const p of targets) kill(p.ProcessId, false);
+    }
+  }
+
+  let after;
+  try {
+    after = snapshotFn();
+    if (!Array.isArray(after)) throw Error('invalid snapshot');
+  } catch (err) { return unknown(err); }
+  if ((rootHeld && !targets.some(p => p.ProcessId === pid))
+    || targets.some(p => creationMs(p) === null)
+    || after.some(p => targets.some(q => q.ProcessId === p.ProcessId) && creationMs(p) === null)) {
+    return unknown('missing tree identity');
+  }
+  const survivors = new Set(targets.filter(p => after.some(q =>
+    q.ProcessId === p.ProcessId && q.CreationDate === p.CreationDate)).map(p => p.ProcessId));
+
+  // Include descendants born during taskkill, following parents through both
+  // snapshots even when an intermediate parent has already disappeared.
+  const treeIds = new Set([pid, ...targets.map(p => p.ProcessId)]);
+  const related = descendantIds([...before, ...after], treeIds);
+  for (const p of after) {
+    if (p.ProcessId === pid || !related.has(p.ParentProcessId)) continue;
+    const date = creationMs(p);
+    if (date === null || floor === null) return unknown('missing descendant CreationDate or spawnedAtMs');
+    if (date >= floor) survivors.add(p.ProcessId);
+  }
+  return { ...base, ok: survivors.size === 0 && !killError, survivors: [...survivors], error: killError };
+}

package/scripts/lib/workspace.mjs

@@ -13,7 +13,7 @@
 import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
-import { $ } from 'zx';
+import { $ } from './zx.mjs';
 import { listWorktrees } from './worktree.mjs';
 
 // Do not spam stdout/stderr with git command echoes.

package/scripts/lib/worktree/constants.mjs

@@ -7,7 +7,7 @@
  * Side effect: configures zx to suppress git command echoes on load.
  */
 
-import { $ } from 'zx';
+import { $ } from '../zx.mjs';
 
 // Do not spam stdout/stderr with git command echoes.
 $.verbose = false;