@gotcos/glasses-server 6.61.7 → 6.63.0

package/server/lib/fork-job-ledger.ts

@@ -0,0 +1,194 @@
+/**
+ * 6.63.0: the durable record of a background fork (`POST .../fork` with a `clientForkId`).
+ *
+ * WHY THIS EXISTS. A fork runs a real model turn in the copy before it can say what it
+ * made, and the attached adapter lets that turn run for 21 minutes. COS Control waited 5,
+ * so on 2026-10-05 a 6.5-minute fork that SUCCEEDED was reported to Miles as "Server
+ * stopped", the card kept pointing at the original thread, and the copy only surfaced in
+ * the server log. A caller that cannot hold a request open for 21 minutes (Control holds
+ * its Work journal lock while it waits; iOS suspends the phone's WebView) needs to start a
+ * fork, get an answer at once, and read the outcome later. That outcome lives here.
+ *
+ * WHAT IT HOLDS. One row per `clientForkId`: `running` until the fork settles, then the
+ * exact status and body the synchronous route would have answered. The FIRST settle wins
+ * and is never overwritten, so a replayed id always sees what its own fork did.
+ *
+ * RESTART. A `running` row written by an earlier server process cannot settle any more:
+ * its promise died with that process, and its child may or may not have made a copy.
+ * `load` turns such rows into the cautious `fork_orphan_possible` answer (not
+ * retryable), which tells the user to look in Sessions before forking again. It never
+ * reports them as failed: a copy may exist.
+ *
+ * PRIVACY. No prompt, no native thread id: the body is the one the route already puts on
+ * the wire (a `forkRef` digest, never an id), and the source is kept only as a digest.
+ */
+import { durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
+
+/** Same shape as a client turn id: what the client mints and can safely echo back. */
+export const CLIENT_FORK_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]{7,63}$/
+
+/** Rows kept. A fork is a user action, so this is weeks of history, and the file stays small. */
+export const MAX_FORK_JOBS = 200
+/** A settled row older than this is dropped on the next write. */
+export const FORK_JOB_TTL_MS = 7 * 24 * 60 * 60_000
+
+export type ForkJobState = 'running' | 'done'
+
+export interface ForkJobRow {
+  clientForkId: string
+  /** `opaqueRevision(targetKey(provider, sourceThreadId))`: which source this job forks, never the id. */
+  source: string
+  provider: string
+  state: ForkJobState
+  acceptedAt: number
+  /** The process that accepted it. A `running` row from another process is interrupted. */
+  instance: string
+  settledAt?: number
+  /** The HTTP status the synchronous route would have answered. */
+  status?: number
+  /** The body the synchronous route would have answered. */
+  result?: Record<string, unknown>
+}
+
+export interface ForkJobPersistence {
+  load: () => unknown
+  save: (rows: ForkJobRow[]) => void
+}
+
+/** The answer an interrupted fork settles to. Copy matches the route's own orphan wording. */
+export const INTERRUPTED_FORK_RESULT: Record<string, unknown> = {
+  forked: false,
+  forkRef: null,
+  sourceIntegrity: null,
+  orphanPossible: true,
+  retryable: false,
+  interrupted: true,
+  reason: 'fork_orphan_possible',
+  reasonCopy: 'The server restarted while COS was making the copy. A copy may exist: look for it in Sessions before forking again.',
+}
+export const INTERRUPTED_FORK_STATUS = 503
+
+function isRow(value: unknown): value is ForkJobRow {
+  if (!value || typeof value !== 'object') return false
+  const r = value as Record<string, unknown>
+  return typeof r.clientForkId === 'string' && CLIENT_FORK_ID_RE.test(r.clientForkId)
+    && typeof r.source === 'string' && typeof r.provider === 'string'
+    && (r.state === 'running' || r.state === 'done')
+    && typeof r.acceptedAt === 'number' && Number.isFinite(r.acceptedAt)
+    && typeof r.instance === 'string'
+    && (r.state === 'running' || (typeof r.status === 'number' && !!r.result && typeof r.result === 'object'))
+}
+
+export type BeginResult =
+  | { kind: 'started'; row: ForkJobRow }
+  /** This id already has a job: the caller replays it and never spawns. */
+  | { kind: 'existing'; row: ForkJobRow }
+  /** The id is already used for a different source thread. */
+  | { kind: 'conflict' }
+  /** The ledger could not be written, so the fork must not start (its outcome would be unreadable). */
+  | { kind: 'unavailable' }
+
+export class ForkJobLedger {
+  private rows = new Map<string, ForkJobRow>()
+
+  constructor(
+    private readonly instance: string,
+    private readonly persistence?: ForkJobPersistence,
+    now: number = Date.now(),
+  ) {
+    let raw: unknown = []
+    try { raw = persistence?.load() ?? [] } catch (error) {
+      console.error(`[fork-job-ledger] load failed: ${error instanceof Error ? error.message : error}`)
+      raw = []
+    }
+    let interrupted = 0
+    for (const value of Array.isArray(raw) ? raw : []) {
+      if (!isRow(value)) continue
+      let row = value
+      if (row.state === 'running' && row.instance !== instance) {
+        row = { ...row, state: 'done', settledAt: now, status: INTERRUPTED_FORK_STATUS, result: { ...INTERRUPTED_FORK_RESULT } }
+        interrupted += 1
+      }
+      this.rows.set(row.clientForkId, row)
+    }
+    if (interrupted > 0) {
+      console.warn(`[fork-job-ledger] ${interrupted} fork job(s) were running when the server last stopped; recorded as orphan-possible`)
+      this.save(now)
+    }
+  }
+
+  get(clientForkId: string): ForkJobRow | null {
+    return this.rows.get(clientForkId) ?? null
+  }
+
+  /** Records a running job. Persisted BEFORE the caller spawns anything. */
+  begin(input: { clientForkId: string; source: string; provider: string }, now: number): BeginResult {
+    const existing = this.rows.get(input.clientForkId)
+    if (existing) return existing.source === input.source ? { kind: 'existing', row: existing } : { kind: 'conflict' }
+    const row: ForkJobRow = {
+      clientForkId: input.clientForkId, source: input.source, provider: input.provider,
+      state: 'running', acceptedAt: now, instance: this.instance,
+    }
+    this.rows.set(row.clientForkId, row)
+    if (!this.save(now)) {
+      this.rows.delete(row.clientForkId)
+      return { kind: 'unavailable' }
+    }
+    return { kind: 'started', row }
+  }
+
+  /** The first settle wins. Returns false if the row is unknown or already settled. */
+  settle(clientForkId: string, status: number, result: Record<string, unknown>, now: number): boolean {
+    const row = this.rows.get(clientForkId)
+    if (!row || row.state !== 'running') return false
+    this.rows.set(clientForkId, { ...row, state: 'done', settledAt: now, status, result })
+    // A failed write keeps the settled row in memory, so this process still answers it.
+    this.save(now)
+    return true
+  }
+
+  /** Running rows in this process (for health). */
+  runningCount(): number {
+    let n = 0
+    for (const row of this.rows.values()) if (row.state === 'running') n += 1
+    return n
+  }
+
+  private save(now: number): boolean {
+    // Drop settled rows past the TTL, then the oldest settled rows past the cap. Running
+    // rows are never dropped: their outcome is still owed to a caller.
+    for (const [id, row] of this.rows) {
+      if (row.state === 'done' && now - (row.settledAt ?? row.acceptedAt) > FORK_JOB_TTL_MS) this.rows.delete(id)
+    }
+    if (this.rows.size > MAX_FORK_JOBS) {
+      const settled = [...this.rows.values()].filter(r => r.state === 'done').sort((a, b) => a.acceptedAt - b.acceptedAt)
+      for (const row of settled) {
+        if (this.rows.size <= MAX_FORK_JOBS) break
+        this.rows.delete(row.clientForkId)
+      }
+    }
+    if (!this.persistence) return true
+    try {
+      this.persistence.save([...this.rows.values()])
+      return true
+    } catch (error) {
+      console.error(`[fork-job-ledger] save failed: ${error instanceof Error ? error.message : error}`)
+      return false
+    }
+  }
+}
+
+/** File persistence: `<data>/fork-jobs.json`, written durably, quarantined if corrupt. */
+export function fileForkJobPersistence(path: string): ForkJobPersistence {
+  return {
+    load: () => {
+      const loaded = loadJsonOrQuarantine<unknown>(path)
+      if (loaded.status === 'corrupt') {
+        console.warn(`[fork-job-ledger] fork job file was corrupt, quarantined as ${loaded.quarantinedAs}`)
+        return []
+      }
+      return loaded.status === 'ok' ? loaded.data : []
+    },
+    save: rows => durableAtomicWriteFileSync(path, `${JSON.stringify(rows)}\n`),
+  }
+}

package/server/lib/fork-thread.ts

@@ -78,7 +78,6 @@ import {
   buildAttachedEnv,
   classifyStderr,
   extractNativeIdsFromLine,
-  isAttachedPermissionPolicy,
   resolveProviderBinary,
   type AttachedChildProcess,
   type AttachedSpawnRequest,
@@ -86,19 +85,34 @@ import {
   type BinaryResolution,
 } from './attached-provider-adapter.js'
 import { findBannedPermissionArg } from './banned-permission-args.js'
+import { PROVIDER_AUTH_RE, PROVIDER_OVERFLOW_RE, PROVIDER_QUOTA_RE } from './provider-failure-text.js'
+import { cursorIsolationUnavailableError, cursorSpawnEnv, isCursorIsolationUnavailable, releaseCursorSpawnOnExit } from './cursor-spawn-env.js'
 
 /**
- * Providers that can be forked. A strict subset of the attached set.
+ * Providers that can be forked.
  *
- * Cursor can Continue (ask-mode resume) and cannot Fork: Agent CLI has no
- * `--fork-session` equivalent, and advertising Fork on Cursor would 404 the
- * only remaining write path for that row if Continue were also hidden.
+ * 6.62.0 (D4, plan 3.7): Cursor's Agent CLI has no `--fork-session`, so its "fork" is a
+ * NEW chat seeded with a bounded context bundle the caller built ("New session with this
+ * context"). It is read-only (`--mode ask`, never `--force`) and stays under the full ban,
+ * like every other fork (B3).
  */
 export type ForkProvider = ForkableProvider
 
-/** Same one-member policy as the attached path. An omitted policy is refused. */
+/** The model a Cursor fork runs when the caller names none (or one that is not a slug). */
+export const CURSOR_FORK_FALLBACK_MODEL = 'composer-2.5-fast'
+const CURSOR_SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,99}$/i
+
+/**
+ * One member, and it stays `read_only` (plan v3, B3): D1 widened CONTINUE to the session's
+ * own posture, never Fork. Every fork, Cursor's included, is read-only. Its own predicate
+ * since 6.62.0, when the attached path's policy word became `session_posture`.
+ */
 export type ForkPermissionPolicy = 'read_only'
 
+export function isForkPermissionPolicy(value: unknown): value is ForkPermissionPolicy {
+  return value === 'read_only'
+}
+
 /** Terminal reason on failure. Never carries prompt, transcript or provider text. */
 export type ForkFailure =
   | 'invalid_provider'
@@ -192,6 +206,70 @@ export interface ForkFailureResult {
 
 export type ForkResult = ForkSuccess | ForkFailureResult
 
+/**
+ * Why the provider itself refused the turn, read from its own error event. An enum
+ * only: the provider's sentence never leaves this module. On 2026-10-05 a complete
+ * 14.8 MB copy's first turn was refused "Prompt is too long", and the route could
+ * only say "COS lost track of the copy": every refusal after the prompt was
+ * written looked the same.
+ */
+export type ForkProviderFailure = 'context_too_long' | 'provider_limit' | 'provider_auth'
+export const FORK_PROVIDER_FAILURES: readonly ForkProviderFailure[] = ['context_too_long', 'provider_limit', 'provider_auth']
+
+export function classifyProviderErrorText(text: string): ForkProviderFailure | null {
+  const sample = text.slice(0, 8_000)
+  // Overflow first: "Prompt is too long" can share a line with a usage hint.
+  if (PROVIDER_OVERFLOW_RE.test(sample)) return 'context_too_long'
+  if (PROVIDER_QUOTA_RE.test(sample)) return 'provider_limit'
+  if (PROVIDER_AUTH_RE.test(sample)) return 'provider_auth'
+  return null
+}
+
+/**
+ * One stdout line, judged only when it is an error carrier: Claude's stream-json
+ * `result` with `is_error`, an assistant event with `error` / `isApiErrorMessage`,
+ * or a Codex/Cursor `error` / `turn.failed` event. Ordinary assistant text that
+ * merely mentions a limit is never read.
+ */
+export function classifyProviderOutputLine(line: string): ForkProviderFailure | null {
+  return readProviderOutputLine(line)?.cause ?? null
+}
+
+/**
+ * The cause on one stdout line, and whether the line is the provider's FINAL verdict
+ * (Claude's `result` with `is_error`, Codex's `turn.failed`). A terminal verdict beats
+ * anything earlier. A retry notice is not a verdict at all: the Claude CLI writes
+ * `{type:"system",subtype:"api_retry",error:"overloaded"|"rate_limit"}` and Codex
+ * writes `{type:"error",message:"Reconnecting... 1/5 (… 429 …)"}` for retries that
+ * may recover, and the first-carrier rule turned a recovered 529 followed by
+ * "Prompt is too long" into "usage limit" (6.62.1 QA).
+ */
+export function readProviderOutputLine(line: string): { cause: ForkProviderFailure | null; terminal: boolean } | null {
+  if (!line || line.length > 2_000_000 || line[0] !== '{') return null
+  let j: any
+  try { j = JSON.parse(line) } catch { return null }
+  if (!j || typeof j !== 'object') return null
+  if (j.type === 'system' && j.subtype === 'api_retry') return null
+  if (j.type === 'error' && typeof j.message === 'string' && /\b(?:reconnecting|retrying)\b/i.test(j.message)) return null
+  const terminal = (j.type === 'result' && j.is_error === true) || j.type === 'turn.failed'
+  const carrier = terminal || j.isApiErrorMessage === true || typeof j.error === 'string' || j.type === 'error'
+  if (!carrier) return null
+  return { cause: providerCauseOf(j), terminal }
+}
+
+function providerCauseOf(j: any): ForkProviderFailure | null {
+  if (j.error === 'rate_limit' || j.apiErrorStatus === 429) return 'provider_limit'
+  if (j.error === 'authentication_failed') return 'provider_auth'
+  const parts: string[] = []
+  const add = (v: unknown) => { if (typeof v === 'string') parts.push(v.slice(0, 2_000)) }
+  add(j.result); add(j.error); add(j.message)
+  if (j.error && typeof j.error === 'object') add(j.error.message)
+  const content = j.message && typeof j.message === 'object' ? j.message.content : null
+  if (typeof content === 'string') add(content)
+  else if (Array.isArray(content)) for (const c of content.slice(0, 8)) add(c?.text)
+  return classifyProviderErrorText(parts.join('\n'))
+}
+
 /**
  * Might this call have left a thread behind that nobody can name?
  *
@@ -251,6 +329,25 @@ export function buildClaudeForkArgs(nativeThreadId: string): string[] {
  * `--ephemeral` is deliberately absent: a fork that is not written to disk is not a
  * thread the user can go back to, which is the entire deliverable.
  */
+/**
+ * Cursor: `agent -p --mode ask --model <slug> --output-format stream-json --trust
+ * --workspace <ws>`, prompt (the context bundle, then the message) on stdin.
+ *
+ * NO `--resume`: there is nothing to resume into, the source chat is only read (by the
+ * caller, for the bundle). NO `--force`: a fork is read-only (B3). The new chat's id comes
+ * back as `session_id` on the stream, and the exactly-one-new-id rule below holds as is.
+ */
+export function buildCursorForkArgs(cwd: string, model: string): string[] {
+  return [
+    '-p',
+    '--mode', 'ask',
+    '--model', model,
+    '--output-format', 'stream-json',
+    '--trust',
+    '--workspace', cwd,
+  ]
+}
+
 export function buildCodexForkArgs(nativeThreadId: string, cwd: string): string[] {
   return [
     'exec',
@@ -274,10 +371,15 @@ export function buildCodexForkArgs(nativeThreadId: string, cwd: string): string[
  * model against the user's workspace, so it needs the same list the attached path
  * has — and needs it to keep being the same list after someone edits one of them.
  */
-function buildForkArgs(provider: ForkProvider, nativeThreadId: string, cwd: string): string[] {
-  const args = provider === 'claude'
-    ? buildClaudeForkArgs(nativeThreadId)
-    : buildCodexForkArgs(nativeThreadId, cwd)
+function buildForkArgs(provider: ForkProvider, nativeThreadId: string, cwd: string, cursorModel?: string): string[] {
+  // An explicit branch per provider: until 6.62.0 a ternary sent anything that was not
+  // Claude down the Codex path, which for Cursor would have been a `codex` argv.
+  let args: string[]
+  if (provider === 'claude') args = buildClaudeForkArgs(nativeThreadId)
+  else if (provider === 'codex') args = buildCodexForkArgs(nativeThreadId, cwd)
+  else if (provider === 'cursor') args = buildCursorForkArgs(cwd, cursorModel ?? CURSOR_FORK_FALLBACK_MODEL)
+  else throw new Error('fork argv: unknown provider')
+  // NO allowance, ever: every fork stays under the full ban.
   const banned = findBannedPermissionArg(args)
   if (banned !== null) {
     // The flag name only. Never the argv, which carries the thread id and the cwd.
@@ -395,7 +497,7 @@ export interface ForkDeps {
    * Exists ONLY so a test can hand back an argv carrying a banned permission flag
    * and prove the fork is refused with zero spawns. Production never sets it.
    */
-  buildArgs?: (provider: ForkProvider, nativeThreadId: string, cwd: string) => string[]
+  buildArgs?: (provider: ForkProvider, nativeThreadId: string, cwd: string, cursorModel?: string) => string[]
 }
 
 export interface ForkRequest {
@@ -404,6 +506,12 @@ export interface ForkRequest {
   prompt: unknown
   cwd: unknown
   policy: unknown
+  /**
+   * 6.62.0: the Cursor fork's model, a flat slug (the session's own, validated by the
+   * caller against the installed list). Ignored for Claude and Codex, whose forks keep
+   * their source's model. Absent or not a slug: `CURSOR_FORK_FALLBACK_MODEL`.
+   */
+  cursorModel?: unknown
   deps: ForkDeps
   /** Wall-clock budget for the provider run. Omitted uses the attached default. */
   timeoutMs?: number
@@ -541,7 +649,7 @@ async function run(request: ForkRequest, deps: ForkDeps, startedAt: number): Pro
 
   const base = { provider, sourceNativeThreadId }
 
-  if (!isAttachedPermissionPolicy(request.policy)) {
+  if (!isForkPermissionPolicy(request.policy)) {
     // Includes `undefined`. An omitted policy is not a request for the safest one;
     // it is a caller that has not decided.
     return fail('unsupported_policy', 'none', { ...base, durationMs: duration() })
@@ -602,9 +710,12 @@ async function run(request: ForkRequest, deps: ForkDeps, startedAt: number): Pro
   const watermarkBefore = readWatermark(deps, provider, sourceNativeThreadId)
 
   // --- 4. Spawn ---------------------------------------------------------------
+  const cursorModel = provider === 'cursor' && typeof request.cursorModel === 'string' && CURSOR_SLUG_RE.test(request.cursorModel)
+    ? request.cursorModel
+    : undefined
   let args: string[]
   try {
-    args = (deps.buildArgs ?? buildForkArgs)(provider, sourceNativeThreadId, cwd)
+    args = (deps.buildArgs ?? buildForkArgs)(provider, sourceNativeThreadId, cwd, cursorModel)
   } catch {
     return fail('unsupported_policy', 'none', { ...base, detail: 'argv_build_failed', durationMs: duration() })
   }
@@ -617,10 +728,11 @@ async function run(request: ForkRequest, deps: ForkDeps, startedAt: number): Pro
 
   let child: AttachedChildProcess
   try {
-    child = deps.spawn({ binaryPath, args, cwd, env: buildAttachedEnv() })
-  } catch {
+    child = deps.spawn({ binaryPath, args, cwd, env: buildAttachedEnv(), provider })
+  } catch (error) {
     // Includes ENOENT. No process exists, so no thread can have been created.
-    return fail('spawn_failed', 'none', { ...base, detail: 'threw', durationMs: duration() })
+    const detail = isCursorIsolationUnavailable(error) ? 'cursor_isolation_unavailable' : 'threw'
+    return fail('spawn_failed', 'none', { ...base, detail, durationMs: duration() })
   }
   if (!child || typeof child !== 'object' || typeof child.on !== 'function') {
     return fail('spawn_failed', 'none', { ...base, detail: 'no_child', durationMs: duration() })
@@ -730,6 +842,14 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
     let stderrSample = ''
     let forkState: ForkState = 'none'
     let exitCode: number | null = null
+    let providerFailure: ForkProviderFailure | null = null
+    let terminalFailure: ForkProviderFailure | null = null
+    const noteProviderLine = (line: string) => {
+      const read = readProviderOutputLine(line)
+      if (!read?.cause) return
+      if (read.terminal) terminalFailure = read.cause   // the last verdict wins
+      else providerFailure ??= read.cause
+    }
     let settled = false
     let timedOut = false
     let spawnErrored = false
@@ -779,6 +899,7 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
           for (const id of extractNativeIdsFromLine(line)) {
             if (!observedIds.includes(id)) observedIds.push(id)
           }
+          noteProviderLine(line)
         }
         // Deliberately nothing else: no text, no tool calls, no transcript. This
         // module cannot leak what it never held.
@@ -805,12 +926,22 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
         for (const id of extractNativeIdsFromLine(stdoutTail)) {
           if (!observedIds.includes(id)) observedIds.push(id)
         }
+        noteProviderLine(stdoutTail)
         stdoutTail = ''
       }
 
-      if (timedOut) return settleFailure('timeout')
+      // After the prompt was written a copy may exist. When the provider named exactly
+      // one new thread, carry it, so the route can point at the copy instead of
+      // telling the user it may exist somewhere (2026-10-05).
+      const copyId = (): string | null => {
+        if (forkState !== 'possible') return null
+        const verdict = selectForkedId(observedIds, sourceNativeThreadId)
+        return verdict.ok ? verdict.newNativeThreadId : null
+      }
+      const cause = (): string | null => terminalFailure ?? providerFailure ?? classifyProviderErrorText(stderrSample)
+      if (timedOut) return settleFailure('timeout', { newNativeThreadId: copyId() })
       if (spawnErrored) return settleFailure('spawn_failed', { detail: 'child_error' })
-      if (exitCode !== 0) return settleFailure('provider_exit_nonzero')
+      if (exitCode !== 0) return settleFailure('provider_exit_nonzero', { newNativeThreadId: copyId(), detail: cause() })
 
       const verdict = selectForkedId(observedIds, sourceNativeThreadId)
       if (!verdict.ok) {
@@ -930,13 +1061,26 @@ export function realForkDeps(
   return {
     now: () => Date.now(),
     resolveBinary: provider => resolveProviderBinary(provider),
-    spawn: request => nodeSpawn(request.binaryPath, [...request.args], {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      cwd: request.cwd,
-      env: request.env,
-      // Group leader, so the whole provider tree can be signalled on timeout.
-      detached: true,
-    }) as unknown as AttachedChildProcess,
+    spawn: request => {
+      // 6.62.0 (plan 3.4): the Cursor fork's `--model` must not rewrite the CLI default.
+      const isolation = request.provider === 'cursor' ? cursorSpawnEnv({ baseEnv: request.env }) : null
+      // 6.62.0 /qa (W6): a fork never falls back to the shared Cursor config.
+      if (isolation && !isolation.isolated) throw cursorIsolationUnavailableError()
+      try {
+        const child = nodeSpawn(request.binaryPath, [...request.args], {
+          stdio: ['pipe', 'pipe', 'pipe'],
+          cwd: request.cwd,
+          env: isolation ? isolation.env : request.env,
+          // Group leader, so the whole provider tree can be signalled on timeout.
+          detached: true,
+        })
+        if (isolation) releaseCursorSpawnOnExit(child, isolation)
+        return child as unknown as AttachedChildProcess
+      } catch (error) {
+        isolation?.release()
+        throw error
+      }
+    },
     processStartMs: pid => realProcessStartMs(pid),
     recordSpawn: (pid, startMs) => recordCosSpawn(pid, startMs),
     releaseSpawn: pid => releaseCosSpawn(pid),

package/server/lib/health-static-probes.ts

@@ -1,4 +1,5 @@
 import { execFile } from 'node:child_process'
+import { cursorSpawnEnv } from './cursor-spawn-env.js'
 import { resolveProviderBinary } from './provider-binary.js'
 import { PYTHON_BIN } from './python-bridge.js'
 import {
@@ -77,17 +78,26 @@ function cacheTtlMs(): number {
   return Number.isFinite(raw) && raw >= 0 ? Math.floor(raw) : DEFAULT_CACHE_TTL_MS
 }
 
-function execute(file: string, args: string[]): Promise<{ stdout: string; stderr: string }> {
+function execute(file: string, args: string[], options: { cursorIsolation?: boolean } = {}): Promise<{ stdout: string; stderr: string }> {
   return new Promise((resolve, reject) => {
-    execFile(file, args, {
-      encoding: 'utf8',
-      timeout: PROBE_TIMEOUT_MS,
-      maxBuffer: 256 * 1024,
-      killSignal: 'SIGKILL',
-    }, (error, stdout, stderr) => {
-      if (error) return reject(error)
-      resolve({ stdout: String(stdout), stderr: String(stderr) })
-    })
+    // 6.62.0 (plan 3.4): every `agent` spawn runs on a config dir of its own.
+    const isolation = options.cursorIsolation === true ? cursorSpawnEnv() : null
+    try {
+      execFile(file, args, {
+        encoding: 'utf8',
+        timeout: PROBE_TIMEOUT_MS,
+        maxBuffer: 256 * 1024,
+        killSignal: 'SIGKILL',
+        ...(isolation ? { env: isolation.env } : {}),
+      }, (error, stdout, stderr) => {
+        isolation?.release()
+        if (error) return reject(error)
+        resolve({ stdout: String(stdout), stderr: String(stderr) })
+      })
+    } catch (error) {
+      isolation?.release()
+      reject(error)
+    }
   })
 }
 
@@ -143,7 +153,7 @@ async function probeCursor(): Promise<{ value: string; available: boolean }> {
   const agentBinary = resolveAgentBinary()
   if (!agentBinary) return { value: 'error', available: false }
   try {
-    const result = await execute(agentBinary, ['about'])
+    const result = await execute(agentBinary, ['about'], { cursorIsolation: true })
     const combined = `${result.stdout}\n${result.stderr}`.trim()
     const version = parseCursorAboutVersion(combined)
     // Catalog discovery is authenticated downstream truth and can take up to

package/server/lib/lens-gist-engines.ts

@@ -18,7 +18,8 @@
 // dictation cleaner ships (no `--tools ""`) wrote a 26.5k-token cache of tool definitions.
 // Codex and Cursor carry 11 to 17k tokens of their own harness on every call.
 
-import { spawn } from 'node:child_process'
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { cursorSpawnEnv, releaseCursorSpawnOnExit } from './cursor-spawn-env.js'
 import { mkdtempSync, rmSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
@@ -119,14 +120,24 @@ interface ProcessResult {
 export function runProcess(
   binary: string,
   args: string[],
-  opts: { stdin: string; cwd: string; timeoutMs: number; label: string },
+  opts: { stdin: string; cwd: string; timeoutMs: number; label: string; cursorIsolation?: boolean },
 ): Promise<ProcessResult> {
   return new Promise((resolve, reject) => {
     let stdout = ''
     let stderr = ''
     let settled = false
     let killTimer: NodeJS.Timeout | null = null
-    const proc = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'], env: lensGistChildEnv(binary), cwd: opts.cwd })
+    // 6.62.0 (plan 3.4): a Cursor child gets its own config dir, so `--model` cannot
+    // rewrite the person's CLI default (C9). Removed when the child exits.
+    const isolation = opts.cursorIsolation === true ? cursorSpawnEnv({ baseEnv: lensGistChildEnv(binary) }) : null
+    let proc: ChildProcessWithoutNullStreams
+    try {
+      proc = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'], env: isolation ? isolation.env : lensGistChildEnv(binary), cwd: opts.cwd })
+    } catch (error) {
+      isolation?.release()
+      throw error
+    }
+    if (isolation) releaseCursorSpawnOnExit(proc, isolation)
     const finish = (fn: () => void) => {
       if (settled) return
       settled = true
@@ -319,7 +330,7 @@ async function runCli(
 ): Promise<LensGistEngineRun> {
   const binary = binaryFor(provider)
   const result = await withScratchWorkspace(workspace =>
-    runProcess(binary, args(workspace), { stdin: prompt, cwd: workspace, timeoutMs: opts.timeoutMs, label: provider }))
+    runProcess(binary, args(workspace), { stdin: prompt, cwd: workspace, timeoutMs: opts.timeoutMs, label: provider, cursorIsolation: provider === 'cursor' }))
   const providerText = `${result.stdout}\n${result.stderr}`
   if (result.code !== 0) {
     // Codex reports its failure as a JSON event AND a non-zero exit; the event says why.

package/server/lib/lens-gist.ts

@@ -937,7 +937,7 @@ async function cursorGistModels(): Promise<string[]> {
   const binary = resolveProviderBinary('cursor')
   if (!binary.ok) return []
   try {
-    const result = await runProcess(binary.path, ['models'], { stdin: '', cwd: homedir(), timeoutMs: 15_000, label: 'cursor models' })
+    const result = await runProcess(binary.path, ['models'], { stdin: '', cwd: homedir(), timeoutMs: 15_000, label: 'cursor models', cursorIsolation: true })
     const ids = result.code === 0 ? parseAgentModelsText(result.stdout).map(m => m.id).filter(isLensGistModelName) : []
     if (ids.length) cursorModels = { at: Date.now(), ids }
     return ids

package/server/lib/live-cues-cursor.ts

@@ -13,6 +13,7 @@ import {
   extractCursorResponseText,
 } from './cursor-bridge.js'
 import { resolveAgentBinary } from './cursor-model-catalog.js'
+import { cursorSpawnEnv, releaseCursorSpawnOnExit } from './cursor-spawn-env.js'
 import { classifyCursorError, getCursorExecutionCwd } from './cursor-run-ledger.js'
 import { terminalProviderAuthFailure } from './provider-terminal-error.js'
 import { terminateProviderProcess } from './provider-process-lifecycle.js'
@@ -70,12 +71,21 @@ export async function composerAsk(input: {
     // detached: the CLI gets its own process group so a timeout kill reaches
     // tool grandchildren. This is NEW relative to cursor-bridge (which spawns
     // attached) — the shutdown path in the engine must also kill this tree.
-    const proc = spawn(agentBinary, args, {
-      stdio: ['pipe', 'pipe', 'pipe'],
-      env,
-      cwd: workspace,
-      detached: true,
-    })
+    // 6.62.0 (plan 3.4): `--model` here must not rewrite the person's CLI default (C9).
+    const isolation = cursorSpawnEnv({ baseEnv: env })
+    let proc: ReturnType<typeof spawn>
+    try {
+      proc = spawn(agentBinary, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: isolation.env,
+        cwd: workspace,
+        detached: true,
+      })
+    } catch (error) {
+      isolation.release()
+      throw error
+    }
+    releaseCursorSpawnOnExit(proc, isolation)
     input.onProcess?.(proc)
 
     const finish = (result: ComposerAskResult) => {