@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/canon-registry.js

@@ -0,0 +1,291 @@
+/**
+ * canon-registry.js — COMP-CANON-GUARD S1.
+ *
+ * The single declaration of what is canon: path pattern → writer → typed tools
+ * → enforcement points. Pure, no I/O (shape template: server/mcp-tool-policy.js).
+ *
+ * Consumed by BOTH:
+ *   - lib/mcp-enforcement.js  (the ship-time scan — the 'ship' point)
+ *   - .claude/hooks/canon-guard.mjs  (the write-time PreToolUse hook — 'hook')
+ *
+ * The load-bearing invariant (design Decision 1, corrected in blueprint-s1-s4):
+ * ONE registry does NOT imply ONE coverage. Each entry declares `enforcedBy`,
+ * and every enforcement point consumes only the subset that names it. This is
+ * what keeps the shared registry from locking out paths a point cannot yet
+ * legally guard:
+ *   - docs/judgment/**  is 100% tool-covered (S3 shipped the 8 judgment_* tools
+ *     + regen), so the write-time hook can guard it with no lockout → ['hook'].
+ *   - ROADMAP.md / feature.json have legal mutations NO tool covers yet
+ *     (open a preserved section; edit a feature description — Decision 2), so
+ *     the always-deny hook would lock them out. They stay ['ship'] (their
+ *     existing build-event correlation) until update_feature_fields /
+ *     open_preserved_section + the override land.
+ *
+ * Adding a path here turns on real enforcement — register a path for 'hook'
+ * ONLY once every legal mutation of it has a tool or an override.
+ */
+
+// ── Tool sets ────────────────────────────────────────────────────────────────
+// Moved verbatim from the pre-refactor mcp-enforcement.js literal sets. The
+// contract test pins these against the legacy values.
+const TOOLS_FOR_ROADMAP = ['add_roadmap_entry', 'set_feature_status', 'propose_followup'];
+const TOOLS_FOR_CHANGELOG = ['add_changelog_entry'];
+/** The override's governance state is written only by the grant tool itself. */
+const TOOLS_FOR_OVERRIDE = ['canon_override_grant'];
+const TOOLS_FOR_FEATURE_JSON = [
+  'add_roadmap_entry',
+  'set_feature_status',
+  'link_artifact',
+  'link_features',
+  'record_completion',
+  // COMP-LIFECYCLE-BACKFILL S3-2: writes feature.json through the completion gate via HTTP.
+  'backfill_completion',
+  'propose_followup',
+  // COMP-COVERAGE-GATE C2 (2026-08-24): both write feature.json server-side via
+  // _postLifecycle (server/vision-routes.js:366 status write-back, :451
+  // kill→KILLED) and were missing here. `entry.tools` feeds only the
+  // canon-guard deny message ("use one of these tools instead") — no allow/deny
+  // decision reads it — so this widens no enforcement; it stops the rejection
+  // message from omitting two legitimate alternatives.
+  'complete_feature',
+  'kill_feature',
+];
+
+/**
+ * The eight judgment WRITE tools (COMP-JUDGMENT-WRITER, shipped @751cc96a).
+ * get_judgment_state is read-only and is deliberately NOT here. Every mutation
+ * of docs/judgment/** — records under records/ and the generated projections
+ * (REGISTER/LEDGER/OBJECTIVE/SITUATION/index.md, people/*.md, positions/*.md) —
+ * goes through one of these, which regenerate the projections atomically.
+ */
+export const JUDGMENT_WRITE_TOOLS = [
+  'judgment_position_create',
+  'judgment_position_amend',
+  'judgment_joint_add',
+  'judgment_transition',
+  'judgment_ledger_append',
+  'judgment_person_write',
+  'judgment_situation_write',
+  'judgment_goal_write',
+];
+
+// ── Matchers ─────────────────────────────────────────────────────────────────
+// A matcher is (path, { featuresDir }) => boolean. featuresDir is relative and
+// project-configurable (loadFeaturesDir), so the feature.json matcher is
+// parameterized; fixed-name and docs/judgment matchers ignore it.
+
+function matchExact(name) {
+  return (path) => path === name;
+}
+
+/** startsWith(<featuresDir>/) && endsWith(/feature.json) — mirrors the legacy
+ * isGuardedPath exactly (does NOT require a single-segment middle; that
+ * constraint lives only in code-correlation, below). */
+function matchFeatureJson(path, featuresDir) {
+  if (typeof path !== 'string' || !featuresDir) return false;
+  const prefix = featuresDir.replace(/\/$/, '') + '/';
+  if (!path.startsWith(prefix)) return false;
+  return path.endsWith('/feature.json');
+}
+
+/** Anything under docs/judgment/ (records or projections). Fixed root — matches
+ * lib/judgment-gen.js, which hardcodes docs/judgment/. */
+function matchJudgment(path) {
+  return typeof path === 'string' && path.startsWith('docs/judgment/');
+}
+
+/**
+ * Prefix match on a directory, requiring the separator so that a sibling with
+ * a longer name (`canon-grants-backup/`) cannot masquerade as a child.
+ */
+function matchUnder(dir) {
+  return (path) => typeof path === 'string' && path.startsWith(`${dir}/`);
+}
+
+// ── The registry ─────────────────────────────────────────────────────────────
+
+/**
+ * @typedef {object} CanonEntry
+ * @property {string} id            — stable identifier
+ * @property {string} display       — human-readable path pattern, for status/help output
+ * @property {string} writer        — the module that legitimately produces this path
+ * @property {string[]} tools       — typed tools authorised to write it
+ * @property {Array<'ship'|'hook'|'pre-commit'>} enforcedBy — points that guard it
+ * @property {boolean} [overrideEligible] — may a canon override be granted FOR
+ *   this path? Absent means yes. Set false for the override's own governance
+ *   state, which must be guarded without being grantable.
+ * @property {(path:string, featuresDir:string)=>boolean} matches
+ */
+
+/** @type {CanonEntry[]} */
+const REGISTRY = [
+  {
+    id: 'roadmap',
+    display: 'ROADMAP.md',
+    writer: 'lib/roadmap-gen.js',
+    tools: TOOLS_FOR_ROADMAP,
+    enforcedBy: ['ship'],
+    matches: matchExact('ROADMAP.md'),
+  },
+  {
+    id: 'changelog',
+    display: 'CHANGELOG.md',
+    writer: 'lib/changelog-writer.js',
+    tools: TOOLS_FOR_CHANGELOG,
+    enforcedBy: ['ship'],
+    matches: matchExact('CHANGELOG.md'),
+  },
+  {
+    id: 'feature-json',
+    display: '<features>/*/feature.json',
+    writer: 'lib/feature-writer.js',
+    tools: TOOLS_FOR_FEATURE_JSON,
+    enforcedBy: ['ship'],
+    matches: (path, featuresDir) => matchFeatureJson(path, featuresDir),
+  },
+  {
+    id: 'judgment',
+    display: 'docs/judgment/**',
+    writer: 'lib/judgment-writer.js',
+    tools: JUDGMENT_WRITE_TOOLS,
+    enforcedBy: ['hook'],
+    matches: (path) => matchJudgment(path),
+  },
+
+  // ── Governance class (COMP-CANON-OVERRIDE S1) ──────────────────────────────
+  // The override's own state. Guarded like any canon, and additionally
+  // `overrideEligible: false` so the override cannot be turned on itself:
+  // without this, "hook-registered" and "grantable" are the same set, and an
+  // agent could grant a bypass FOR the bypass ledger and then rewrite it
+  // (gate round 2, finding 2). The grant directory is governance state for the
+  // same reason — unregistered, a raw-written token would be consumable with
+  // no ledger row at all (finding 1).
+  //
+  // Runtime-scoped, like every hook guarantee: `Bash` never reaches this.
+  {
+    id: 'override-ledger',
+    display: '.compose/canon-overrides.jsonl',
+    writer: 'lib/canon-override.js',
+    tools: TOOLS_FOR_OVERRIDE,
+    enforcedBy: ['hook'],
+    overrideEligible: false,
+    matches: matchExact('.compose/canon-overrides.jsonl'),
+  },
+  {
+    id: 'override-attest',
+    display: '.compose/canon-overrides-attest.json',
+    writer: 'lib/canon-override.js',
+    tools: TOOLS_FOR_OVERRIDE,
+    enforcedBy: ['hook'],
+    overrideEligible: false,
+    matches: matchExact('.compose/canon-overrides-attest.json'),
+  },
+  {
+    id: 'override-grants',
+    display: '.compose/data/canon-grants/**',
+    writer: 'lib/canon-override.js',
+    tools: TOOLS_FOR_OVERRIDE,
+    enforcedBy: ['hook'],
+    overrideEligible: false,
+    matches: matchUnder('.compose/data/canon-grants'),
+  },
+];
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the registry entry guarding `path` at enforcement `point`, or null.
+ * Only entries whose `enforcedBy` includes the point are considered — this is
+ * the per-point-subset invariant.
+ *
+ * @param {string} path
+ * @param {{ featuresDir?: string, point: 'ship'|'hook'|'pre-commit' }} opts
+ * @returns {CanonEntry|null}
+ */
+export function matchEntry(path, { featuresDir, point }) {
+  for (const entry of REGISTRY) {
+    if (!entry.enforcedBy.includes(point)) continue;
+    if (entry.matches(path, featuresDir)) return entry;
+  }
+  return null;
+}
+
+/** True if `path` is guarded at `point`. */
+export function isGuarded(path, opts) {
+  return matchEntry(path, opts) !== null;
+}
+
+/**
+ * True if a canon override may be granted for `path` at `point`.
+ *
+ * Deliberately NOT the same predicate as `isGuarded`. Two paths are guarded
+ * but ungrantable:
+ *   - governance state (`overrideEligible: false`) — else the override could
+ *     authorise rewriting its own audit trail;
+ *   - anything not guarded at THIS point — a grant for a ship-only path is
+ *     meaningless, because the hook already allows it, and would write a
+ *     misleading bypass row.
+ * An unguarded path is likewise ineligible: nothing is blocking it, so there
+ * is nothing to override (the lockout invariant).
+ */
+/**
+ * Human-readable path patterns guarded at `point`, for status and help output.
+ * Derived rather than hand-written: a hardcoded string in `compose guard
+ * status` silently under-reported the guarded set the moment S1 widened it.
+ */
+export function guardedDisplaysFor(point) {
+  return REGISTRY.filter((e) => e.enforcedBy.includes(point)).map((e) => e.display);
+}
+
+export function isOverrideEligible(path, opts) {
+  const entry = matchEntry(path, opts);
+  return entry !== null && entry.overrideEligible !== false;
+}
+
+/** The typed tools authorised to write `path` at `point`, or [] if unguarded. */
+export function toolsForPath(path, opts) {
+  const entry = matchEntry(path, opts);
+  return entry ? [...entry.tools] : [];
+}
+
+/**
+ * The feature code for a feature.json path (single-segment middle), else null.
+ * Used for ship-scan code correlation so an event for feature A cannot bless a
+ * dirty edit to feature B's feature.json.
+ *
+ * @param {string} path
+ * @param {{ featuresDir: string }} opts
+ * @returns {string|null}
+ */
+export function featureCodeForPath(path, { featuresDir }) {
+  if (typeof path !== 'string' || !featuresDir) return null;
+  const prefix = featuresDir.replace(/\/$/, '') + '/';
+  if (!path.startsWith(prefix) || !path.endsWith('/feature.json')) return null;
+  const middle = path.slice(prefix.length, -'/feature.json'.length);
+  if (!middle || middle.includes('/')) return null;
+  return middle;
+}
+
+/**
+ * The registry as plain data — `{ id, display, tools }` per entry, deep-copied.
+ *
+ * Exists so COMP-COVERAGE-GATE can cross-check `entry.tools` against the tool
+ * inventory without reaching into `_internals` (which is test-only) and without
+ * being able to mutate the live registry.
+ */
+export function canonEntries() {
+  return REGISTRY.map((e) => ({ id: e.id, display: e.display, tools: [...e.tools] }));
+}
+
+/** The entry ids guarded at `point` (for the contract test + introspection). */
+export function guardedPatternIdsFor(point) {
+  return REGISTRY.filter((e) => e.enforcedBy.includes(point)).map((e) => e.id);
+}
+
+export const _internals = {
+  REGISTRY,
+  TOOLS_FOR_ROADMAP,
+  TOOLS_FOR_CHANGELOG,
+  TOOLS_FOR_FEATURE_JSON,
+  JUDGMENT_WRITE_TOOLS,
+};

package/lib/cli-commands.js

@@ -0,0 +1,144 @@
+/**
+ * cli-commands.js — COMP-AUDIT-13: the single source of truth for compose's
+ * top-level command surface.
+ *
+ * `compose --help` (bin/compose.js) and the Command Index in docs/cli.md are
+ * both rendered from COMMANDS here, so installed capability can never again be
+ * invisible unless a command is missing from this table — and a drift-guard test
+ * (test/cli-commands.test.js) asserts this table matches the real dispatch
+ * branches in bin/compose.js in both directions.
+ *
+ * To add a command: add its `cmd === '<name>'` branch in bin/compose.js AND a
+ * row here. The test fails until both exist.
+ */
+
+/**
+ * @typedef {Object} Command
+ * @property {string} name        Canonical command token (matches `cmd === '<name>'`)
+ * @property {string[]} aliases   Alternate tokens that dispatch the same command
+ * @property {string} group       Display group (must be one of COMMAND_GROUPS)
+ * @property {string} summary     One-line description (help + docs index)
+ */
+
+/** Ordered display groups. */
+export const COMMAND_GROUPS = [
+  'Getting started',
+  'Features & roadmap',
+  'Build & implement',
+  'Lifecycle, gates & review',
+  'Vision, ideas & tracking',
+  'App, integrations & runtime',
+  'Maintenance & info',
+];
+
+/** @type {Command[]} */
+export const COMMANDS = [
+  // Getting started
+  { name: 'init', aliases: [], group: 'Getting started', summary: 'Initialize Compose in the current project' },
+  { name: 'setup', aliases: ['sync'], group: 'Getting started', summary: 'Install/sync global Compose skills' },
+  { name: 'install', aliases: [], group: 'Getting started', summary: 'Legacy bootstrap — runs init + setup' },
+  { name: 'import', aliases: [], group: 'Getting started', summary: 'Scan an existing project and generate a structured analysis' },
+  { name: 'doctor', aliases: [], group: 'Getting started', summary: 'Check external skill dependencies' },
+  { name: 'update', aliases: ['upgrade'], group: 'Getting started', summary: 'Pull latest compose, reinstall deps, refresh global skill' },
+
+  // Features & roadmap
+  { name: 'new', aliases: [], group: 'Features & roadmap', summary: 'Kickoff a product (research, brainstorm, roadmap, scaffold)' },
+  { name: 'feature', aliases: [], group: 'Features & roadmap', summary: 'Add a single feature (folder, design seed, ROADMAP entry)' },
+  { name: 'roadmap', aliases: [], group: 'Features & roadmap', summary: 'Show roadmap status; generate/migrate/check ROADMAP.md' },
+  { name: 'triage', aliases: [], group: 'Features & roadmap', summary: 'Analyze a feature and recommend a build profile' },
+  { name: 'qa-scope', aliases: [], group: 'Features & roadmap', summary: "Show affected routes from a feature's changed files" },
+
+  // Build & implement
+  { name: 'build', aliases: [], group: 'Build & implement', summary: 'Run a feature through the headless lifecycle' },
+  { name: 'fix', aliases: [], group: 'Build & implement', summary: 'Run a bug through the headless bug-fix lifecycle' },
+  { name: 'plan', aliases: [], group: 'Build & implement', summary: 'Plan work into a structured roadmap from a prompt' },
+  { name: 'gsd', aliases: [], group: 'Build & implement', summary: 'Per-task fresh-context dispatch from a blueprint + Boundary Map' },
+  { name: 'pipeline', aliases: [], group: 'Build & implement', summary: 'View and edit the build pipeline' },
+  { name: 'experiment', aliases: [], group: 'Build & implement', summary: 'Run an A/B model experiment from a spec' },
+
+  // Lifecycle, gates & review
+  { name: 'gates', aliases: ['gate'], group: 'Lifecycle, gates & review', summary: 'List and resolve pending gates' },
+  { name: 'loops', aliases: [], group: 'Lifecycle, gates & review', summary: 'Manage iteration loops for a feature' },
+  { name: 'guard', aliases: [], group: 'Lifecycle, gates & review', summary: 'Manage the canon guard and drift detection' },
+  { name: 'validate', aliases: [], group: 'Lifecycle, gates & review', summary: 'Validate feature/project artifacts against contracts' },
+  { name: 'record-completion', aliases: [], group: 'Lifecycle, gates & review', summary: 'Record a completion bound to a commit SHA (flips status to COMPLETE)' },
+  { name: 'lineage', aliases: [], group: 'Lifecycle, gates & review', summary: 'PROV-O artifact lineage: stamp | stale | show' },
+  { name: 'context', aliases: [], group: 'Lifecycle, gates & review', summary: 'Show the build decision log' },
+
+  // Vision, ideas & tracking
+  { name: 'items', aliases: [], group: 'Vision, ideas & tracking', summary: 'List vision items from local state (no server)' },
+  { name: 'ideabox', aliases: [], group: 'Vision, ideas & tracking', summary: 'Capture, review, and promote product ideas' },
+  { name: 'judgment', aliases: [], group: 'Vision, ideas & tracking', summary: "Judgment records: trace a position's causal ancestry" },
+  { name: 'metrics', aliases: [], group: 'Vision, ideas & tracking', summary: 'Report dispatch, settlement, and triage metrics' },
+  { name: 'tracker', aliases: [], group: 'Vision, ideas & tracking', summary: 'Tracker provider status and op-log sync' },
+
+  // App, integrations & runtime
+  { name: 'start', aliases: [], group: 'App, integrations & runtime', summary: 'Start the compose app (UI + API) for this project' },
+  { name: 'remote', aliases: [], group: 'App, integrations & runtime', summary: 'Manage remote access: pair, list, revoke, status' },
+  { name: 'smartmemory', aliases: [], group: 'App, integrations & runtime', summary: 'Sync feature-events/journal/artifacts into SmartMemory' },
+
+  // Maintenance & info
+  { name: 'migrate-state', aliases: [], group: 'Maintenance & info', summary: 'Run pending feature.json state migrations' },
+  { name: 'migrate-anon', aliases: [], group: 'Maintenance & info', summary: 'Promote anonymous ROADMAP rows to typed features (interactive)' },
+  { name: 'hooks', aliases: [], group: 'Maintenance & info', summary: 'Manage Claude Code hooks (install | uninstall | status)' },
+  { name: 'version', aliases: ['--version', '-V'], group: 'Maintenance & info', summary: 'Print compose version, git SHA, and install root' },
+];
+
+/** Every token (names + aliases) that should dispatch to a command. */
+export function allCommandTokens() {
+  return COMMANDS.flatMap((c) => [c.name, ...c.aliases]);
+}
+
+/** A command's display label: `name` plus any aliases, e.g. `setup, sync`. */
+function labelOf(cmd) {
+  return cmd.aliases.length ? `${cmd.name}, ${cmd.aliases.join(', ')}` : cmd.name;
+}
+
+/**
+ * Render the grouped `compose --help` body from COMMANDS.
+ * @returns {string}
+ */
+export function renderHelp() {
+  const lines = ['Usage: compose <command>', ''];
+  const width = Math.max(...COMMANDS.map((c) => labelOf(c).length));
+  for (const group of COMMAND_GROUPS) {
+    const inGroup = COMMANDS.filter((c) => c.group === group);
+    if (!inGroup.length) continue;
+    lines.push(`${group}:`);
+    for (const cmd of inGroup) {
+      lines.push(`  ${labelOf(cmd).padEnd(width)}  ${cmd.summary}`);
+    }
+    lines.push('');
+  }
+  lines.push('Run `compose <command> --help` (or see docs/cli.md) for command details.');
+  return lines.join('\n');
+}
+
+/**
+ * Render the docs/cli.md Command Index — a complete, grouped table generated
+ * from COMMANDS. The completeness test in test/cli-commands.test.js asserts
+ * every command appears in cli.md, so this table cannot silently omit one.
+ * @returns {string}
+ */
+export function renderCommandIndex() {
+  const out = [
+    '## Command Index',
+    '',
+    '<!-- Generated from lib/cli-commands.js (COMP-AUDIT-13). Every shipped command appears here. -->',
+    '',
+  ];
+  for (const group of COMMAND_GROUPS) {
+    const inGroup = COMMANDS.filter((c) => c.group === group);
+    if (!inGroup.length) continue;
+    out.push(`### ${group}`, '', '| Command | Summary |', '|---|---|');
+    for (const cmd of inGroup) {
+      const label = cmd.aliases.length
+        ? `\`compose ${cmd.name}\` (alias: ${cmd.aliases.map((a) => `\`${a}\``).join(', ')})`
+        : `\`compose ${cmd.name}\``;
+      // Escape pipes so a summary like "stamp | stale | show" can't break the table.
+      out.push(`| ${label} | ${cmd.summary.replace(/\|/g, '\\|')} |`);
+    }
+    out.push('');
+  }
+  return out.join('\n');
+}

package/lib/codex-preflight.js

@@ -21,10 +21,12 @@
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 
 export const PROBE_SENTINEL = 'COMPOSE_CODEX_PROBE_OK';
-const WORKTREE_BASE = join(homedir(), '.stratum', 'worktrees');
+const WORKTREE_BASE = process.env.NODE_TEST_CONTEXT
+  ? join(tmpdir(), 'compose-test-worktrees', 'codex-preflight')
+  : join(homedir(), '.stratum', 'worktrees');
 const PROBE_CACHE = 'codex-worktree-probe.json';
 // Bound the probe's agent run so a wedged Codex CLI can't hang the whole build
 // before the flow even starts. On timeout we reject → the finally cleanup runs.
@@ -63,13 +65,25 @@ function isGitRepo(cwd) {
  *
  * @param {object} args
  * @param {string} args.cwd       repo working directory
+ * @param {string} args.projectCwd project root used for dispatch telemetry
+ * @param {string} args.buildId    current Compose build identifier
+ * @param {string} args.featureCode current feature code
  * @param {object} args.stratum   stratum client (uses runAgentText('codex', ...))
  * @param {string} args.dataDir   .compose/data dir for the per-repo cache
  * @param {string} args.ts        caller-supplied timestamp string (unique worktree name)
  * @param {boolean} [args.force]  ignore the cache and re-probe
  * @returns {Promise<{ok: boolean, reason: string, cached?: boolean, skipped?: boolean}>}
  */
-export async function preflightCodexWorktreeProbe({ cwd, stratum, dataDir, ts, force = false }) {
+export async function preflightCodexWorktreeProbe({
+  cwd,
+  projectCwd,
+  buildId,
+  featureCode,
+  stratum,
+  dataDir,
+  ts,
+  force = false,
+}) {
   if (process.env.COMPOSE_SKIP_CODEX_PROBE) {
     return { ok: true, skipped: true, reason: 'COMPOSE_SKIP_CODEX_PROBE set — probe skipped' };
   }
@@ -101,21 +115,40 @@ export async function preflightCodexWorktreeProbe({ cwd, stratum, dataDir, ts, f
   // Unique per-run filename so a file committed in the repo (carried into the
   // detached worktree from HEAD) can never make the probe false-pass.
   const probeName = `codex-probe-${ts}.txt`;
+  let terminationUnconfirmed = false;
   try {
     const prompt =
       `Write a file named ${probeName} in the current working directory whose exact ` +
       `contents are the single line: ${PROBE_SENTINEL}\n` +
       `Do nothing else. This is an environment write-probe.`;
     try {
-      // Bound the agent run — a hang here would otherwise stall the build and skip
-      // the finally cleanup. On timeout the race rejects and we fall to the catch.
-      await Promise.race([
-        stratum.runAgentText('codex', prompt, { cwd: wtPath }),
-        new Promise((_, reject) =>
-          setTimeout(() => reject(new Error(`probe timed out after ${PROBE_AGENT_TIMEOUT_MS}ms`)), PROBE_AGENT_TIMEOUT_MS).unref?.()
-        ),
-      ]);
+      // Wait for acknowledged termination before removing the worktree. A
+      // Promise.race timeout could delete it while the agent was still writing.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), PROBE_AGENT_TIMEOUT_MS);
+      timer.unref?.();
+      try {
+        await stratum.runAgentText('codex', prompt, {
+          cwd: wtPath,
+          sandboxMode: 'workspace-write',
+          signal: controller.signal,
+          telemetry: {
+            site: 'preflight',
+            project_cwd: projectCwd,
+            build_id: buildId,
+            feature_code: featureCode,
+          },
+        });
+      } finally {
+        clearTimeout(timer);
+      }
     } catch (err) {
+      if (['CANCELLATION_UNCONFIRMED', 'CANCELLATION_TEARDOWN_TIMEOUT'].includes(err?.code)) {
+        terminationUnconfirmed = true;
+        err.worktreePath = wtPath;
+        err.message += `; probe worktree retained at ${wtPath}`;
+        throw err;
+      }
       const result = { ok: false, reason: `Codex agent run failed/timed out inside the worktree: ${err?.message ?? err}` };
       writeProbeCache(dataDir, result);
       return result;
@@ -131,10 +164,12 @@ export async function preflightCodexWorktreeProbe({ cwd, stratum, dataDir, ts, f
     writeProbeCache(dataDir, result);
     return result;
   } finally {
-    try {
-      execSync(`git worktree remove "${wtPath}" --force`, { cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe' });
-    } catch {
-      try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* give up */ }
+    if (!terminationUnconfirmed) {
+      try {
+        execSync(`git worktree remove "${wtPath}" --force`, { cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe' });
+      } catch {
+        try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* give up */ }
+      }
     }
   }
 }