@gotcos/glasses-server 6.61.7 → 6.62.1

package/server/lib/cursor-session-model.ts

@@ -0,0 +1,339 @@
+// Which model a Cursor session runs on, read from Cursor's own stores (6.62.0, plans 1.8 + 3.3).
+//
+// WHY. `agent -p --resume <id>` WITHOUT `--model` runs the GLOBAL CLI default, not the
+// chat's model (canary C5: a composer chat resumed as grok when the default was grok). So
+// a Continue that keeps the session's model has to read it and pass it. Flat slugs only:
+// bracket ids (`grok-4.7[effort=low,fast=true]`) fail pre-flight (C5d).
+//
+// TWO STORES, TWO READS.
+//   IDE composer  `globalStorage/state.vscdb`, table `cursorDiskKV`, key
+//                 `composerData:<id>`, field `modelConfig` = `{modelName, selectedModels:
+//                 [{modelId, parameters: [{id: 'reasoning_effort', value}, {id: 'fast'}]}]}`.
+//                 The database is 8.9 GB: EXACT keys only, never a LIKE scan, in a query of
+//                 its OWN (never shared with the names query, so a slow read here cannot blank
+//                 the titles), 2 s timeout, 60 s cache per id (validation W17: 18 ms for 20).
+//   CLI chat      `~/.cursor/chats/<hash>/<id>/store.db`: the newest blob naming
+//                 `providerOptions.cursor.modelName`, already a flat slug. Opened
+//                 `?mode=ro&immutable=1` (plain `mode=ro` fails SQLITE_CANTOPEN on these),
+//                 which ignores the WAL, so the answer can trail by one turn. Cached on the
+//                 file's (mtime, size). Its `meta` row also says whether COS created the chat
+//                 in Ask mode, which a Run Everything Continue must name (W14).
+//
+// Every failure is "unknown": the field is omitted and the Continue falls back to
+// composer-2.5-fast with a note. A read here never blocks a list.
+
+import { execFile } from 'node:child_process'
+import { statSync } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import { isValidNativeThreadId } from './native-thread-id.js'
+
+
+export const SQLITE3_BIN = '/usr/bin/sqlite3'
+export const COMPOSER_MODEL_TTL_MS = 60_000
+export const COMPOSER_MODEL_TIMEOUT_MS = 2_000
+/** Keep the IN list bounded; a list page asks for at most a few dozen composers. */
+const MAX_COMPOSER_IDS_PER_QUERY = 64
+const MAX_CACHE_ENTRIES = 512
+
+/** The fallback model when a session's own model cannot be read or is not listed. */
+export const CURSOR_CONTINUE_FALLBACK_MODEL = 'composer-2.5-fast'
+
+export interface CursorModelConfig {
+  modelName?: unknown
+  maxMode?: unknown
+  selectedModels?: unknown
+}
+
+export interface ComposerFacts {
+  modelConfig: CursorModelConfig | null
+  /** `workspaceIdentifier.uri.fsPath`: the folder the composer runs in, when recorded. */
+  workspace: string | null
+}
+
+const SLUG_PART_RE = /^[a-z0-9][a-z0-9.]*$/i
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/i
+
+function paramValue(parameters: unknown, id: string): string | null {
+  if (!Array.isArray(parameters)) return null
+  for (const entry of parameters) {
+    if (!entry || typeof entry !== 'object') continue
+    const row = entry as { id?: unknown; value?: unknown }
+    if (row.id !== id) continue
+    if (typeof row.value === 'string') return row.value.trim()
+    if (typeof row.value === 'boolean') return row.value ? 'true' : 'false'
+  }
+  return null
+}
+
+/**
+ * Flat slugs for an IDE composer's model, most specific first: family, then
+ * `-<reasoning_effort>`, then `-fast` (`grok-4.7` + xhigh + fast = `grok-4.7-xhigh-fast`).
+ * The caller validates against the full `agent models` list and takes the first listed.
+ */
+export function cursorSlugCandidates(config: CursorModelConfig | null | undefined): string[] {
+  if (!config || typeof config !== 'object') return []
+  const selected = Array.isArray(config.selectedModels) ? config.selectedModels[0] as { modelId?: unknown; parameters?: unknown } | undefined : undefined
+  const family = typeof selected?.modelId === 'string' && selected.modelId.trim()
+    ? selected.modelId.trim()
+    : typeof config.modelName === 'string' ? config.modelName.trim() : ''
+  if (!family || !SLUG_RE.test(family)) return []
+  const effort = paramValue(selected?.parameters, 'reasoning_effort')
+  const fastRaw = paramValue(selected?.parameters, 'fast') ?? paramValue(selected?.parameters, 'speed')
+  const fast = fastRaw === 'true' || fastRaw === 'fast'
+  const usableEffort = effort && SLUG_PART_RE.test(effort) ? effort.toLowerCase() : null
+  const out: string[] = []
+  const push = (slug: string) => { if (SLUG_RE.test(slug) && !out.includes(slug)) out.push(slug) }
+  if (usableEffort && fast) push(`${family}-${usableEffort}-fast`)
+  if (usableEffort) push(`${family}-${usableEffort}`)
+  if (fast) push(`${family}-fast`)
+  push(family)
+  return out
+}
+
+/** The first candidate the installed Cursor lists, or null. */
+export function pickListedCursorModel(candidates: readonly string[], isKnown: (id: string) => boolean): string | null {
+  for (const candidate of candidates) {
+    try {
+      if (isKnown(candidate)) return candidate
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+// ---------------------------------------------------------------------------
+// IDE composer: state.vscdb
+// ---------------------------------------------------------------------------
+
+const composerCache = new Map<string, { at: number; facts: ComposerFacts | null }>()
+
+/** Tests only. */
+export function __resetCursorSessionModelCachesForTests(): void {
+  composerCache.clear()
+  chatCache.clear()
+  cursorModelReadStats.composerQueries = 0
+  cursorModelReadStats.chatQueries = 0
+  cursorModelReadStats.composerFailures = 0
+  cursorModelReadStats.chatFailures = 0
+  chatFailures.clear()
+}
+
+export const cursorModelReadStats = { composerQueries: 0, chatQueries: 0, composerFailures: 0, chatFailures: 0 }
+
+export type SqliteRunner = (args: readonly string[], timeoutMs: number) => Promise<string>
+
+/**
+ * 6.62.0 /qa (W7): the sqlite3 children COS has running right now. They hold a chat's
+ * `store.db` open for a moment, and the busy probe must not mistake COS's own read for a run.
+ */
+const sqliteReaders = new Set<number>()
+export function activeSqliteReaderPids(): number[] {
+  return [...sqliteReaders]
+}
+
+export const realSqliteRunner: SqliteRunner = (args, timeoutMs) => new Promise((resolve, reject) => {
+  const child = execFile(SQLITE3_BIN, [...args], { timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8' }, (error, stdout) => {
+    if (typeof child.pid === 'number') sqliteReaders.delete(child.pid)
+    if (error) reject(error)
+    else resolve(String(stdout))
+  })
+  if (typeof child.pid === 'number') sqliteReaders.add(child.pid)
+})
+
+function parseJsonText(value: unknown): unknown {
+  if (typeof value !== 'string' || value.length === 0) return null
+  try {
+    return JSON.parse(value)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Model config and workspace for each composer id, from ONE exact-key query. Ids that are
+ * not native thread ids are dropped before they reach SQL. Cached 60 s per id, including a
+ * miss, so a composer with no row is not re-queried on every poll.
+ */
+export async function readComposerFacts(
+  ids: readonly string[],
+  dbPath: string,
+  options: { now?: number; run?: SqliteRunner } = {},
+): Promise<Map<string, ComposerFacts | null>> {
+  const now = options.now ?? Date.now()
+  const out = new Map<string, ComposerFacts | null>()
+  const wanted: string[] = []
+  for (const raw of ids) {
+    const id = typeof raw === 'string' ? raw.toLowerCase() : ''
+    if (!isValidNativeThreadId(id) || out.has(id) || wanted.includes(id)) continue
+    const hit = composerCache.get(id)
+    if (hit && now - hit.at < COMPOSER_MODEL_TTL_MS) out.set(id, hit.facts)
+    else if (wanted.length < MAX_COMPOSER_IDS_PER_QUERY) wanted.push(id)
+  }
+  if (wanted.length === 0 || !dbPath) return out
+  try {
+    const st = await stat(dbPath)
+    if (!st.isFile()) return out
+  } catch {
+    return out
+  }
+  const keys = wanted.map(id => `'composerData:${id}'`).join(',')
+  const sql = `SELECT key AS k, json_extract(value, '$.modelConfig') AS mc, json_extract(value, '$.workspaceIdentifier.uri.fsPath') AS ws FROM cursorDiskKV WHERE key IN (${keys})`
+  // 6.62.0 /qa (W11): a FAILED read is cached for the same 60 s as an answer, so a locked
+  // or slow database costs one 2 s wait per minute, not one per poll.
+  const rememberMiss = (): Map<string, ComposerFacts | null> => {
+    cursorModelReadStats.composerFailures += 1
+    for (const id of wanted) {
+      composerCache.delete(id)
+      composerCache.set(id, { at: now, facts: null })
+      out.set(id, null)
+    }
+    return out
+  }
+  let stdout: string
+  try {
+    cursorModelReadStats.composerQueries += 1
+    stdout = await (options.run ?? realSqliteRunner)(['-readonly', '-json', dbPath, sql], COMPOSER_MODEL_TIMEOUT_MS)
+  } catch {
+    return rememberMiss()
+  }
+  const found = new Map<string, ComposerFacts>()
+  try {
+    const rows = JSON.parse(stdout.trim() || '[]') as Array<{ k?: unknown; mc?: unknown; ws?: unknown }>
+    for (const row of Array.isArray(rows) ? rows : []) {
+      const key = typeof row.k === 'string' ? row.k : ''
+      const id = key.startsWith('composerData:') ? key.slice('composerData:'.length).toLowerCase() : ''
+      if (!isValidNativeThreadId(id)) continue
+      const mc = parseJsonText(row.mc)
+      found.set(id, {
+        modelConfig: mc && typeof mc === 'object' && !Array.isArray(mc) ? mc as CursorModelConfig : null,
+        workspace: typeof row.ws === 'string' && row.ws.startsWith('/') && !row.ws.includes('\0') ? row.ws : null,
+      })
+    }
+  } catch {
+    return rememberMiss()
+  }
+  for (const id of wanted) {
+    const facts = found.get(id) ?? null
+    composerCache.delete(id)
+    composerCache.set(id, { at: now, facts })
+    out.set(id, facts)
+  }
+  while (composerCache.size > MAX_CACHE_ENTRIES) {
+    const oldest = composerCache.keys().next()
+    if (oldest.done) break
+    composerCache.delete(oldest.value)
+  }
+  return out
+}
+
+// ---------------------------------------------------------------------------
+// CLI chat: store.db
+// ---------------------------------------------------------------------------
+
+export interface CliChatFacts {
+  /** The newest `providerOptions.cursor.modelName`, a flat slug. */
+  model: string | null
+  /** The chat's `meta` mode (`ask`, `default`, …). */
+  mode: string | null
+}
+
+const chatCache = new Map<string, { mtimeMs: number; size: number; facts: CliChatFacts | null }>()
+/** 6.62.0 /qa (W11): when a chat's read last FAILED; a failure is not retried for 60 s. */
+const chatFailures = new Map<string, number>()
+const MODEL_NAME_RE = /"modelName"\s*:\s*"([^"\\]{1,100})"/g
+
+function hexToText(hex: string): string | null {
+  const clean = hex.trim()
+  if (!/^[0-9a-f]*$/i.test(clean) || clean.length % 2 !== 0) return null
+  try {
+    return Buffer.from(clean, 'hex').toString('utf8')
+  } catch {
+    return null
+  }
+}
+
+/** The chat's model and mode, or null when `store.db` cannot be read. */
+export async function readCliChatFacts(
+  chatDir: string,
+  options: { run?: SqliteRunner; now?: number } = {},
+): Promise<CliChatFacts | null> {
+  if (typeof chatDir !== 'string' || !chatDir.startsWith('/')) return null
+  const dbPath = join(chatDir, 'store.db')
+  let mtimeMs: number
+  let size: number
+  try {
+    const st = await stat(dbPath)
+    if (!st.isFile()) return null
+    mtimeMs = st.mtimeMs
+    size = st.size
+  } catch {
+    return null
+  }
+  const hit = chatCache.get(dbPath)
+  if (hit && hit.mtimeMs === mtimeMs && hit.size === size) return hit.facts
+  const failedAt = chatFailures.get(dbPath)
+  const now = options.now ?? Date.now()
+  if (failedAt !== undefined && now - failedAt < COMPOSER_MODEL_TTL_MS) return null
+  // A URI, so the path is percent-encoded: a chat dir under a folder with spaces is ordinary.
+  const uri = `file:${encodeURI(dbPath).replace(/\?/g, '%3F').replace(/#/g, '%23')}?mode=ro&immutable=1`
+  const run = options.run ?? realSqliteRunner
+  let facts: CliChatFacts | null = null
+  try {
+    cursorModelReadStats.chatQueries += 1
+    const blob = await run([uri, "SELECT CAST(data AS TEXT) FROM blobs WHERE instr(CAST(data AS TEXT), '\"modelName\"') > 0 ORDER BY rowid DESC LIMIT 1"], COMPOSER_MODEL_TIMEOUT_MS)
+    let model: string | null = null
+    for (const match of blob.matchAll(MODEL_NAME_RE)) {
+      const candidate = match[1]!.trim()
+      if (SLUG_RE.test(candidate)) model = candidate
+    }
+    let mode: string | null = null
+    try {
+      // The CLI stores the meta row as HEX of its JSON (measured on CLI 2026.10.01); a row
+      // written as plain JSON is read as it is.
+      const raw = (await run([uri, "SELECT CAST(value AS TEXT) FROM meta ORDER BY rowid ASC LIMIT 1"], COMPOSER_MODEL_TIMEOUT_MS)).trim()
+      const text = raw.startsWith('{') ? raw : hexToText(raw)
+      const meta = parseJsonText(text ?? '') as { mode?: unknown } | null
+      if (meta && typeof meta.mode === 'string' && /^[a-z-]{1,24}$/i.test(meta.mode)) mode = meta.mode.toLowerCase()
+    } catch {
+      mode = null
+    }
+    facts = { model, mode }
+  } catch {
+    cursorModelReadStats.chatFailures += 1
+    chatFailures.delete(dbPath)
+    chatFailures.set(dbPath, now)
+    while (chatFailures.size > MAX_CACHE_ENTRIES) {
+      const oldest = chatFailures.keys().next()
+      if (oldest.done) break
+      chatFailures.delete(oldest.value)
+    }
+    return null
+  }
+  chatFailures.delete(dbPath)
+  chatCache.delete(dbPath)
+  chatCache.set(dbPath, { mtimeMs, size, facts })
+  while (chatCache.size > MAX_CACHE_ENTRIES) {
+    const oldest = chatCache.keys().next()
+    if (oldest.done) break
+    chatCache.delete(oldest.value)
+  }
+  return facts
+}
+
+/**
+ * The most recent write to a CLI chat (its `store.db`, the WAL beside it, or its agent
+ * transcript), in epoch ms, or null. SYNCHRONOUS: the occupancy gate it feeds is.
+ */
+export function cliChatLastWriteMs(chatDir: string, transcriptPath: string | null): number | null {
+  let latest: number | null = null
+  for (const path of [join(chatDir, 'store.db'), join(chatDir, 'store.db-wal'), transcriptPath]) {
+    if (!path) continue
+    try {
+      const mtimeMs = statSync(path).mtimeMs
+      if (latest === null || mtimeMs > latest) latest = mtimeMs
+    } catch { /* absent is fine */ }
+  }
+  return latest
+}

package/server/lib/cursor-spawn-env.ts

@@ -0,0 +1,210 @@
+// Every Cursor `agent` spawn gets a config dir of its own (6.62.0, plan 3.4, canaries C9/K1).
+//
+// WHY. The CLI REWRITES `~/.cursor/cli-config.json` (`model`, `selectedModel`,
+// `modelParameters`, `modelSelectionHistory`) whenever a run passes `--model` (C9,
+// confirmed twice). COS passes `--model` on Continue, Messages, reviews, Live Cues and
+// the lens gist, so every one of those silently changed the person's own CLI default.
+//
+// THE FIX, AS K1 PROVED IT (2026-10-05 09:21): `CURSOR_CONFIG_DIR` = a fresh per-spawn
+// dir (0700) holding a COPY of `cli-config.json` (so auth and permissions follow the
+// person's current config), with symlinks to `~/.cursor/{chats,hooks.json,mcp.json,
+// plugins,skills-cursor}` so a `--resume` finds the chat, the COS observer still fires,
+// and MCP servers still load. The rewrite lands in the copy, and the copy is deleted when
+// the child exits.
+//
+// PER SPAWN, NEVER SHARED. One shared dir races between overlapping spawns (and the CLI
+// already leaves `cli-config.json.*.tmp` files behind by the thousand). `mkdtemp` gives
+// each child its own.
+//
+// CHILD ENV ONLY. `CURSOR_CONFIG_DIR` is set on the env object handed to the spawn, never
+// on `process.env`: the server's own later reads must keep seeing the person's real dir.
+//
+// SYMLINKS ARE NEVER FOLLOWED ON CLEANUP. `release` unlinks each link by name first, then
+// removes the dir. Deleting through `chats` would delete the person's chats.
+//
+// `dictation-clean.ts` is exempt: it builds a STRICTER per-spawn profile of its own (no
+// MCP, no hooks, no inherited permissions), which this must not loosen.
+
+import { copyFileSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, unlinkSync, chmodSync, statSync, existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * What K1 linked, plus `agents` and `plans` (6.62.0 /qa W6), each only when it exists. The
+ * census test and `bin/cli.cjs` read this exact list.
+ */
+export const CURSOR_SPAWN_LINKS = ['chats', 'hooks.json', 'mcp.json', 'plugins', 'skills-cursor', 'agents', 'plans'] as const
+
+/**
+ * 6.62.0 /qa (W6): the code a spawn that MUST be isolated (a Continue, a fork) throws when it
+ * cannot be: those paths refuse with an honest reason instead of falling back to the shared
+ * config, where `--model` (and Run Everything's own config writes) would land in the
+ * person's real CLI default. Every other spawn may still fail open, and logs it.
+ */
+export const CURSOR_ISOLATION_UNAVAILABLE = 'COS_CURSOR_ISOLATION_UNAVAILABLE'
+
+export function cursorIsolationUnavailableError(): Error & { code: string } {
+  const error = new Error('Cursor spawn isolation unavailable') as Error & { code: string }
+  error.code = CURSOR_ISOLATION_UNAVAILABLE
+  return error
+}
+
+export function isCursorIsolationUnavailable(error: unknown): boolean {
+  return !!error && typeof error === 'object' && (error as { code?: unknown }).code === CURSOR_ISOLATION_UNAVAILABLE
+}
+
+/** A spawn dir older than this belongs to a server that died mid-run; a Continue lasts 30 min at most. */
+export const CURSOR_SPAWN_STALE_MS = 6 * 60 * 60_000
+
+const SPAWN_PREFIX = 'spawn-'
+
+export interface CursorSpawnEnvOptions {
+  /** The env the caller built for the child (already stripped as it wants). Default `process.env`. */
+  baseEnv?: NodeJS.ProcessEnv
+  /** The person's Cursor config dir. Default: `CURSOR_CONFIG_DIR` of the server, else `~/.cursor`. */
+  sourceDir?: string
+  /** Where per-spawn dirs live. Default `~/.cos-glasses/cursor-cli`. */
+  root?: string
+  now?: number
+}
+
+export interface CursorSpawnIsolation {
+  /** The child's env. Carries `CURSOR_CONFIG_DIR` only when `isolated`. */
+  env: NodeJS.ProcessEnv
+  dir: string | null
+  isolated: boolean
+  /** Idempotent. Unlinks the links by name, then removes the dir. */
+  release: () => void
+}
+
+export const cursorSpawnStats = { created: 0, released: 0, failed: 0, swept: 0 }
+
+/**
+ * `~/.cos-glasses/cursor-cli`. `COS_CURSOR_SPAWN_ROOT` and `COS_CURSOR_SPAWN_SOURCE` exist
+ * for the test config only (vitest.config.ts), so no suite that drives a Cursor spawn path
+ * can read the live ~/.cursor or write under the live ~/.cos-glasses. Production sets neither.
+ */
+export function cursorSpawnRoot(): string {
+  return process.env.COS_CURSOR_SPAWN_ROOT?.trim() || join(homedir(), '.cos-glasses', 'cursor-cli')
+}
+
+export function defaultCursorSourceDir(env: NodeJS.ProcessEnv = process.env): string {
+  return process.env.COS_CURSOR_SPAWN_SOURCE?.trim() || env.CURSOR_CONFIG_DIR?.trim() || join(homedir(), '.cursor')
+}
+
+/** Remove one spawn dir without ever following a link out of it. */
+export function removeCursorSpawnDir(dir: string): void {
+  for (const name of CURSOR_SPAWN_LINKS) {
+    const path = join(dir, name)
+    try {
+      if (lstatSync(path).isSymbolicLink()) unlinkSync(path)
+    } catch { /* absent */ }
+  }
+  // Anything else the CLI made in here is its own (the rewritten config, a stats cache).
+  // A link the CLI made under another name is unlinked, not followed, by rmSync.
+  rmSync(dir, { recursive: true, force: true })
+}
+
+/** Remove spawn dirs a dead server left behind. Never touches anything not named `spawn-*`. */
+export function sweepStaleCursorSpawnDirs(root = cursorSpawnRoot(), now = Date.now(), maxAgeMs = CURSOR_SPAWN_STALE_MS): number {
+  let names: string[]
+  try { names = readdirSync(root) } catch { return 0 }
+  let removed = 0
+  for (const name of names) {
+    if (!name.startsWith(SPAWN_PREFIX)) continue
+    const dir = join(root, name)
+    try {
+      const st = lstatSync(dir)
+      if (!st.isDirectory() || now - st.mtimeMs < maxAgeMs) continue
+      removeCursorSpawnDir(dir)
+      removed++
+    } catch { /* gone, or not ours to judge */ }
+  }
+  cursorSpawnStats.swept += removed
+  return removed
+}
+
+let lastSweepAt = 0
+
+/**
+ * A config dir for ONE Cursor child. On any failure the child runs with the caller's env
+ * unchanged (`isolated: false`): the 6.61 behaviour, logged and counted, never a refused
+ * spawn, because a broken scratch dir must not take Continue or Messages down with it.
+ */
+export function cursorSpawnEnv(options: CursorSpawnEnvOptions = {}): CursorSpawnIsolation {
+  const baseEnv = options.baseEnv ?? process.env
+  const root = options.root ?? cursorSpawnRoot()
+  const sourceDir = options.sourceDir ?? defaultCursorSourceDir(baseEnv)
+  const now = options.now ?? Date.now()
+  if (now - lastSweepAt > 10 * 60_000) {
+    lastSweepAt = now
+    try { sweepStaleCursorSpawnDirs(root, now) } catch { /* best effort */ }
+  }
+  let dir: string | null = null
+  try {
+    mkdirSync(root, { recursive: true, mode: 0o700 })
+    dir = mkdtempSync(join(root, SPAWN_PREFIX))
+    chmodSync(dir, 0o700)
+    const config = join(sourceDir, 'cli-config.json')
+    if (existsSync(config)) {
+      copyFileSync(config, join(dir, 'cli-config.json'))
+      chmodSync(join(dir, 'cli-config.json'), 0o600)
+    }
+    // `chats` must exist at the source: without it the CLI would write a new chat into this
+    // dir, and the dir is deleted when the child exits.
+    try {
+      if (!existsSync(join(sourceDir, 'chats'))) mkdirSync(join(sourceDir, 'chats'), { recursive: true, mode: 0o700 })
+    } catch { /* the link below still points at where the chats belong */ }
+    for (const name of CURSOR_SPAWN_LINKS) {
+      const target = join(sourceDir, name)
+      try {
+        statSync(target)
+      } catch {
+        continue
+      }
+      symlinkSync(target, join(dir, name))
+    }
+  } catch (error) {
+    cursorSpawnStats.failed += 1
+    console.warn(`[cursor-spawn-env] isolation unavailable, child uses the shared config: ${error instanceof Error ? (error as NodeJS.ErrnoException).code ?? error.message : error}`)
+    if (dir) {
+      try { removeCursorSpawnDir(dir) } catch { /* best effort */ }
+    }
+    return { env: { ...baseEnv }, dir: null, isolated: false, release: () => {} }
+  }
+  cursorSpawnStats.created += 1
+  const env: NodeJS.ProcessEnv = { ...baseEnv, CURSOR_CONFIG_DIR: dir }
+  let released = false
+  const isolatedDir = dir
+  return {
+    env,
+    dir: isolatedDir,
+    isolated: true,
+    release: () => {
+      if (released) return
+      released = true
+      try {
+        removeCursorSpawnDir(isolatedDir)
+        cursorSpawnStats.released += 1
+      } catch (error) {
+        console.warn(`[cursor-spawn-env] cleanup failed: ${error instanceof Error ? error.message : error}`)
+      }
+    },
+  }
+}
+
+/**
+ * Release the isolation when the child is done: on `close`, or on an `error` from a child
+ * that never started (no pid). An `error` from a RUNNING child (a failed kill) is not the
+ * end of it, and pulling its config dir out from under it mid-run would be.
+ */
+export function releaseCursorSpawnOnExit(
+  child: { pid?: number; once?: (event: string, listener: (...args: any[]) => void) => unknown; on: (event: string, listener: (...args: any[]) => void) => unknown },
+  isolation: CursorSpawnIsolation,
+): void {
+  const listen = typeof child.once === 'function' ? child.once.bind(child) : child.on.bind(child)
+  listen('close', () => isolation.release())
+  listen('error', () => {
+    if (typeof child.pid !== 'number') isolation.release()
+  })
+}