@gotcos/glasses-server 6.61.7 → 6.63.0

package/server/lib/occupancy-probes.ts

@@ -53,7 +53,8 @@ import { basename, join, resolve } from 'node:path'
 import { NATIVE_THREAD_ID_RE } from './native-thread-id.js'
 import { transcriptPathFor, type NativeHeadDeps } from './native-head.js'
 import { parseProcStartUtcMs, type OccupancyDirs, type OccupancyProbes } from './thread-occupancy.js'
-import { resolveCursorAgentSession } from './cursor-agent-store.js'
+import { cursorTranscriptPath, resolveCursorAgentSession } from './cursor-agent-store.js'
+import { activeSqliteReaderPids, cliChatLastWriteMs } from './cursor-session-model.js'
 
 // Re-exported rather than reimplemented. `claudeSessionsDir` already encodes the
 // COS_CLAUDE_SESSIONS_DIR -> CLAUDE_CONFIG_DIR -> ~/.claude precedence AND is the
@@ -348,6 +349,39 @@ export function readFile(path: string): string | null {
  * other id validator (`SAFE_ID_RE`) permits `/` and `.`. If that validation is
  * ever dropped upstream, this refuses rather than probing an arbitrary path.
  */
+/**
+ * 6.62.0 /qa (W7): one bounded `lsof` on a Cursor CLI chat's `store.db`. A process that
+ * holds it open and is not COS (not the server, not a COS child, not one of COS's own
+ * short sqlite3 reads) is a run working that chat right now, at the desk or in a terminal
+ * `agent`, even when it has written nothing for 30 s. Null: lsof could not tell (timeout,
+ * missing, refused); the caller then falls back to the 30 s write rule and this logs it.
+ */
+export const CURSOR_CHAT_HOLDER_TIMEOUT_MS = 3_000
+export const cursorChatHolderStats = { probes: 0, held: 0, failed: 0 }
+
+export function cursorChatForeignHolder(
+  chatDir: string,
+  ownPids: () => Iterable<number>,
+  run: (bin: string, args: string[], timeoutMs: number) => ProbeOutcome = runProbe,
+): boolean | null {
+  if (typeof chatDir !== 'string' || !chatDir.startsWith('/') || chatDir.includes('\0')) return null
+  const path = join(chatDir, 'store.db')
+  cursorChatHolderStats.probes += 1
+  let pids: number[]
+  try {
+    pids = interpretLockHolders(run(LSOF_BIN, ['-w', '-t', '--', path], CURSOR_CHAT_HOLDER_TIMEOUT_MS), path)
+  } catch (error) {
+    cursorChatHolderStats.failed += 1
+    console.warn(`[occupancy-probes] cursor chat holder probe failed, the 30 s write rule decides: ${error instanceof Error ? error.message : error}`)
+    return null
+  }
+  const own = new Set<number>([process.pid])
+  try { for (const pid of ownPids()) own.add(pid) } catch { /* the ledger is advisory here */ }
+  const held = pids.some(pid => !own.has(pid))
+  if (held) cursorChatHolderStats.held += 1
+  return held
+}
+
 export function lockHolders(path: string): number[] {
   if (typeof path !== 'string' || path.length === 0 || path.includes('\0')) {
     throw new Error('lockHolders: refusing an unusable path')
@@ -728,6 +762,16 @@ export function realOccupancyProbes(ledger: SpawnLedgerAccessor): OccupancyProbe
     lockHolders,
     cosSpawnedPids: () => sanitizeLedger(ledger()),
     cursorAgentSession: (threadId, chatsDir) => resolveCursorAgentSession(threadId, chatsDir),
+    // 6.62.0 /qa (W7): positive evidence first: a non-COS process holding the chat open.
+    cursorChatForeignHolder: chatDir => cursorChatForeignHolder(chatDir, () => [
+      ...sanitizeLedger(ledger()).keys(),
+      ...activeSqliteReaderPids(),
+    ]),
+    // 6.62.0 (W14): the CLI chat busy window reads the chat's own files.
+    cursorChatLastWriteMs: (chatDir, threadId) => cliChatLastWriteMs(
+      chatDir,
+      cursorTranscriptPath(threadId, join(process.env.COS_AGENT_SESSIONS_HOME?.trim() || homedir(), '.cursor', 'projects')),
+    ),
     // transcriptMtimeMs is DELIBERATELY absent here. See `withTranscriptClock`.
   }
 }

package/server/lib/permission-broker.ts

@@ -112,7 +112,7 @@
 import { execFile } from 'node:child_process'
 import { randomBytes } from 'node:crypto'
 import { boundForRedaction } from './activity-preview.js'
-import { toolFingerprint, SESSION_ID_RE, type HookEnvelope } from './session-hook-events.js'
+import { inferHookProvider, toolFingerprint, SESSION_ID_RE, type HookEnvelope } from './session-hook-events.js'
 import { ASK_USER_QUESTION_TOOL, type SessionSignalStore } from './session-signal-store.js'
 
 // ---------------------------------------------------------------------------
@@ -302,6 +302,11 @@ export interface PermissionRequestFacts {
    * received it (its second argument). Null for an earlier script or block: `holdCeilingS`.
    */
   hookWaitS: number | null
+  /**
+   * 6.62.0 (plan 3.10): the engine that asked, from the envelope's stamp (the Codex command
+   * writes one) or the payload. Cursor never reaches here (`cursor` refusal above).
+   */
+  provider?: 'claude' | 'codex'
 }
 
 export type EnvelopeVerdict =
@@ -329,7 +334,7 @@ function readPermissionRequestEnvelope(body: unknown): EnvelopeRead {
   const hookWaitS = typeof wait === 'number' && Number.isInteger(wait) && wait > 0 && wait <= HOOK_WAIT_STAMP_MAX_S ? wait : null
   return {
     ok: true,
-    facts: { sessionId: p.session_id.toLowerCase(), toolName: p.tool_name, toolInput: p.tool_input, hookStartedAtMs: ts, hookWaitS },
+    facts: { sessionId: p.session_id.toLowerCase(), toolName: p.tool_name, toolInput: p.tool_input, hookStartedAtMs: ts, hookWaitS, provider: inferHookProvider(body.provider, p) === 'codex' ? 'codex' : 'claude' },
   }
 }
 
@@ -457,9 +462,16 @@ export const CANCEL_DENY_MESSAGE = 'Cancelled from COS'
  * 6.53.0: a held prompt whose run was cancelled from the lens. Deny with `interrupt: true`,
  * so Claude ends the RUN rather than trying something else in place of this tool. The one
  * case where a broker reply interrupts, and only ever from `cancelSession`.
+ *
+ * 6.62.0 (W20, C2): never for Codex. Its PermissionRequest refuses `interrupt` (it fails
+ * closed on the field), so a Codex prompt gets the plain deny; the halt marker stops the run
+ * at its next command.
  */
-export function cancelHookOutput(): Record<string, unknown> {
-  return { hookSpecificOutput: { hookEventName: 'PermissionRequest', decision: { behavior: 'deny', message: CANCEL_DENY_MESSAGE, interrupt: true } } }
+export function cancelHookOutput(provider: 'claude' | 'codex' = 'claude'): Record<string, unknown> {
+  const decision = provider === 'codex'
+    ? { behavior: 'deny', message: CANCEL_DENY_MESSAGE }
+    : { behavior: 'deny', message: CANCEL_DENY_MESSAGE, interrupt: true }
+  return { hookSpecificOutput: { hookEventName: 'PermissionRequest', decision } }
 }
 
 /** A tool approval: allow once, or deny with the one message. Never a rule. */
@@ -819,6 +831,8 @@ type Chosen = { answers: Record<string, string[]> } | { decision: 'allow' | 'den
 interface BrokerItem {
   id: string
   sessionId: string
+  /** 6.62.0: the engine that asked (plan 3.10); every view says it. */
+  provider: 'claude' | 'codex'
   kind: BrokerItemKind
   toolName: string
   toolInput: Record<string, unknown>
@@ -849,7 +863,7 @@ interface BrokerItem {
 export interface SessionQuestionView {
   id: string
   sessionId: string
-  provider: 'claude'
+  provider: 'claude' | 'codex'
   kind: BrokerItemKind
   tool: string
   createdAt: string
@@ -872,7 +886,7 @@ export interface SessionQuestionView {
 export interface SettledQuestionView {
   id: string
   sessionId: string
-  provider: 'claude'
+  provider: 'claude' | 'codex'
   kind: BrokerItemKind
   tool: string
   createdAt: string
@@ -1213,6 +1227,7 @@ export class PermissionBroker {
     const item: BrokerItem = {
       id,
       sessionId: facts.sessionId,
+      provider: facts.provider ?? 'claude',
       kind: request.kind,
       toolName: facts.toolName,
       // Only a question needs its input again (the answer is built on it). An approval's
@@ -1289,7 +1304,7 @@ export class PermissionBroker {
       views.push({
         id: item.id,
         sessionId: item.sessionId,
-        provider: 'claude',
+        provider: item.provider,
         kind: item.kind,
         tool: item.toolName,
         createdAt: new Date(item.createdAt).toISOString(),
@@ -1321,7 +1336,7 @@ export class PermissionBroker {
     return listed.map(item => ({
       id: item.id,
       sessionId: item.sessionId,
-      provider: 'claude' as const,
+      provider: item.provider,
       kind: item.kind,
       tool: item.toolName,
       createdAt: new Date(item.createdAt).toISOString(),
@@ -1444,7 +1459,7 @@ export class PermissionBroker {
     let denied = 0
     for (const item of [...this.items.values()]) {
       if (item.state !== 'pending' || item.sessionId !== wanted) continue
-      if (!item.channel || !item.channel.writable() || !item.channel.reply(cancelHookOutput())) {
+      if (!item.channel || !item.channel.writable() || !item.channel.reply(cancelHookOutput(item.provider))) {
         this.settle(item, 'hook_gone')
         continue
       }

package/server/lib/provider-actions.ts

@@ -0,0 +1,149 @@
+// What each provider can DO through COS (6.62.0, plan 3.11): `providers.<p>.act`.
+//
+// One object per provider, published on /api/health and /api/models (the phone reads the
+// second). Every entry is `{ supported }`, and every `supported: false` carries a reason
+// code, so a client never has to invent copy for a missing capability. Computed per request
+// from the same live flags the routes decide with; this module decides nothing itself.
+//
+// The observation half (`providers.<p>.observe`, plan 1.10) is published by the hooks
+// work; `mergeProviderSections` joins the two under one `providers` key so neither
+// spread can overwrite the other.
+
+import { continueFullPermissionsEnabled } from './continue-plan.js'
+import { permissionBrokerHealthFields } from './permission-broker.js'
+import { continueLiveEnabled } from './session-peer-inbox-deps.js'
+import { codexLiveQueueEnabled } from './codex-live-queue.js'
+
+export type ProviderName = 'claude' | 'codex' | 'cursor'
+
+export interface ProviderCapability {
+  supported: boolean
+  /** Present exactly when `supported` is false: a stable, enum-like code. */
+  reason?: string
+  /** Optional qualifier on a supported entry (`new_session`, `next_command`). */
+  mode?: string
+}
+
+export interface ProviderAct {
+  continueIdle: ProviderCapability
+  continueBusy: ProviderCapability
+  fork: ProviderCapability
+  cancelDesk: ProviderCapability
+  approvals: ProviderCapability
+  nativeQueue: ProviderCapability
+  keepModel: ProviderCapability
+  permissions: ProviderCapability
+}
+
+export interface ProviderActInput {
+  /** `threadAttachCapability().enabled`: the write routes exist. */
+  attachEnabled: boolean
+  /** `threadForkProviders`. */
+  forkProviders: readonly string[]
+  /** `features.sessionCancel`, whatever keys this build publishes there. */
+  sessionCancel: Record<string, unknown> | null | undefined
+  /** The permission broker is on (`permissionBroker.enabled`). */
+  brokerEnabled: boolean
+  /** `COS_CONTINUE_LIVE` (Claude's live hop). */
+  continueLive: boolean
+  /** `COS_CODEX_LIVE_QUEUE` (Codex's app-queue hop, idle and busy). */
+  codexLiveQueue: boolean
+  env?: NodeJS.ProcessEnv
+}
+
+const yes = (mode?: string): ProviderCapability => (mode ? { supported: true, mode } : { supported: true })
+const no = (reason: string): ProviderCapability => ({ supported: false, reason })
+
+/** The three `act` objects. Pure over its input. */
+export function providerActs(input: ProviderActInput): Record<ProviderName, ProviderAct> {
+  const full = continueFullPermissionsEnabled(input.env)
+  const attach = input.attachEnabled === true
+  const cancel = input.sessionCancel ?? {}
+  const continueIdle = (mode?: string) => (attach ? yes(mode) : no('attach_disabled'))
+  const fork = (provider: ProviderName, mode?: string) =>
+    (input.forkProviders.includes(provider) ? yes(mode) : no('fork_unsupported'))
+  const desk = (key: string) => (cancel[key] === true ? yes('next_command') : no('hooks_not_ready'))
+  return {
+    claude: {
+      continueIdle: continueIdle(input.continueLive ? 'live' : 'resume'),
+      // A busy Claude session takes no outside turn mid-run; the turn waits for its Stop.
+      continueBusy: no('queued_until_turn_end'),
+      fork: fork('claude'),
+      cancelDesk: desk('deskClaude'),
+      approvals: input.brokerEnabled ? yes() : no('broker_off'),
+      nativeQueue: no('engine_limit'),
+      keepModel: yes(),
+      permissions: yes('session'),
+    },
+    codex: {
+      continueIdle: continueIdle(input.codexLiveQueue ? 'app_queue' : 'resume'),
+      continueBusy: !attach ? no('attach_disabled') : input.codexLiveQueue ? yes('app_queue') : no('codex_live_queue_off'),
+      fork: fork('codex'),
+      cancelDesk: desk('deskCodex'),
+      // The broker takes Codex PermissionRequests; Desktop threads run approval `never`.
+      approvals: input.brokerEnabled ? yes('on_request_only') : no('broker_off'),
+      nativeQueue: yes(),
+      keepModel: full ? yes() : no('full_permissions_off'),
+      permissions: full ? yes('session_posture') : no('full_permissions_off'),
+    },
+    cursor: {
+      // An idle IDE composer cannot take a message from outside; a CLI chat can.
+      continueIdle: attach ? yes('cli_chat_only') : no('attach_disabled'),
+      continueBusy: no('queued_until_turn_end'),
+      fork: fork('cursor', 'new_session'),
+      cancelDesk: desk('deskCursor'),
+      // Cursor approvals cannot be answered remotely in `-p` (canary C3a).
+      approvals: no('engine_limit'),
+      nativeQueue: no('engine_limit'),
+      keepModel: full ? yes() : no('full_permissions_off'),
+      permissions: full ? yes('run_everything') : no('full_permissions_off'),
+    },
+  }
+}
+
+/** `{ claude: { act }, codex: { act }, cursor: { act } }`, ready to merge. */
+export function providerActSections(input: ProviderActInput): Record<ProviderName, { act: ProviderAct }> {
+  const acts = providerActs(input)
+  return { claude: { act: acts.claude }, codex: { act: acts.codex }, cursor: { act: acts.cursor } }
+}
+
+/**
+ * Join per-provider sections (`act` from here, `observe` from the hooks work) into ONE
+ * `providers` object. Later sections add keys; they never replace a provider wholesale.
+ */
+export function mergeProviderSections(
+  ...sections: Array<Partial<Record<string, Record<string, unknown>>> | null | undefined>
+): Record<string, Record<string, unknown>> {
+  const out: Record<string, Record<string, unknown>> = {}
+  for (const section of sections) {
+    if (!section) continue
+    for (const [provider, fields] of Object.entries(section)) {
+      if (!fields || typeof fields !== 'object') continue
+      out[provider] = { ...(out[provider] ?? {}), ...fields }
+    }
+  }
+  return out
+}
+
+/**
+ * The live input, read from the same flags the routes decide with. Separate from the pure
+ * `providerActs` so tests drive every branch without the environment.
+ */
+export function liveProviderActInput(base: {
+  attachEnabled: boolean
+  forkProviders: readonly string[]
+  sessionCancel: Record<string, unknown> | null | undefined
+}): ProviderActInput {
+  let brokerEnabled = false
+  try {
+    brokerEnabled = permissionBrokerHealthFields().permissionBroker?.enabled === true
+  } catch {
+    brokerEnabled = false
+  }
+  return {
+    ...base,
+    brokerEnabled,
+    continueLive: continueLiveEnabled(),
+    codexLiveQueue: codexLiveQueueEnabled(),
+  }
+}

package/server/lib/provider-failure-text.ts

@@ -0,0 +1,27 @@
+/**
+ * A provider's own words for why it refused a turn. The ONE copy of these patterns:
+ * provider proof, the lens gist (via provider-proof), fork classification and the
+ * query-job error code all read them, so a usage limit is named the same everywhere.
+ * 6.62.1 moved them here so low-level modules can import them without the proof's
+ * process machinery. Leaf module: no imports.
+ */
+export const PROVIDER_QUOTA_RE = /usage[ _]limit|hit your (?:usage |session )?limit|session limit|rate.?limit|too many requests|\b429\b|\bquota\b|resets? (?:at|in) |over capacity|overloaded|\b529\b|plan limit/i
+export const PROVIDER_AUTH_RE = /not logged in|please (?:log ?in|sign in)|invalid api key|authentication|unauthori[sz]ed|\b401\b|\b403\b|login required|token (?:has )?expired|no credentials/i
+export const PROVIDER_OVERFLOW_RE = /prompt is too long|context window|too many tokens|exceeds the (?:model|context)/i
+
+/** Codes a provider bridge raises when it has nothing better to say. Only these are upgraded. */
+const GENERIC_CODES = new Set(['query_job_failed', 'claude.error', 'codex.error', 'cursor.error', 'provider_exit_nonzero'])
+
+/**
+ * A generic failure whose message carries the provider's reason gets a code a client
+ * can act on: Work showed "claude.error / query_job_failed" for "You've hit your
+ * session limit · resets 4pm" on 2026-10-05, so it offered the same exhausted provider.
+ */
+export function providerFailureCode(code: string, message: string): string {
+  if (!GENERIC_CODES.has(code)) return code
+  const sample = message.slice(0, 8_000)
+  if (PROVIDER_OVERFLOW_RE.test(sample)) return 'provider_context_too_long'
+  if (PROVIDER_QUOTA_RE.test(sample)) return 'provider_limit'
+  if (PROVIDER_AUTH_RE.test(sample)) return 'provider_auth'
+  return code
+}

package/server/lib/provider-observe.ts

@@ -0,0 +1,212 @@
+// What COS can SEE of each engine's sessions (6.62.0, provider parity), for `/api/health`.
+//
+// Two jobs. First, the Codex hooks and the Cursor observer as health fields beside the Claude
+// ones (`sessionHooks.codex`, `sessionHooks.cursorObserver`). Claude's `sessionHooks.state`,
+// `installed` and `hookHaltReady` are untouched and stay Claude-only (B2): Control 0.5.254
+// keys its banner and its Install check off them.
+//
+// Second, `providers.<engine>.observe`: one short source code per observation (hooks, live
+// state, child agents, compaction, reasoning), so a client can say why a row is quiet. Each is
+// the name of the evidence, or `none`.
+//
+// READ FROM A SNAPSHOT, NEVER ON THE HEALTH REQUEST. Codex's trust needs a spawn of its
+// app-server, and the files live in the user's home. The composition root starts a background
+// refresh (`startProviderObserveRefresh`); the install routes refresh after they write. A
+// process that never started it (every test) reports `checkedAt: null` and reads no home file.
+
+import { CODEX_TRUST_REFRESH_MS, cachedCodexHookTrust, codexHookStatus, codexPresent, refreshCodexHookTrust, type CodexHookStatus, type CodexHookTrust } from './codex-hooks-installer.js'
+import { sweepStaleCursorSpawnDirs } from './cursor-spawn-env.js'
+import { cursorObserverStatus } from './cursor-observer-installer.js'
+import { setCodexDeskCancelReady } from './session-cancel.js'
+
+export interface CodexHooksHealth {
+  /** Codex's binary resolves and it has a home. Nothing else here is read when it is not. */
+  present: boolean
+  installed: boolean
+  /** The install state word (`CodexHookStatus.state`), or null when Codex is not present. */
+  state: CodexHookStatus['state'] | null
+  /**
+   * Codex's own word through `hooks/list` (K3): the newest answer for CODEX_TRUST_CACHE_MS, kept
+   * through a failed read (QA W4); `unknown` until read, past the TTL, or when not installed.
+   */
+  trust: CodexHookTrust
+  /**
+   * QA W4: why `trust` says what it says when it is not a fresh answer: the newest read's failure
+   * code (`timeout`, `rpc_error`, `spawn_failed`, `no_binary`), `not_listed`, `stale`,
+   * `unchecked`, or `not_installed`. Null for a fresh answer.
+   */
+  trustReason: string | null
+  /** The stable script is this package's: the only script whose Codex halt reply Codex honours. */
+  scriptOk: boolean
+  /** When the file status was last read; null when this process never read it. */
+  checkedAt: string | null
+  trustCheckedAt: string | null
+}
+
+export interface CursorObserverHealth {
+  installed: boolean
+  /** The node binary the observer commands name still exists (W18). */
+  nodeOk: boolean
+  checkedAt: string | null
+}
+
+interface Snapshot {
+  codex: { present: boolean; status: CodexHookStatus | null; at: number } | null
+  cursor: { installed: boolean; nodeOk: boolean; at: number } | null
+}
+
+const snapshot: Snapshot = { codex: null, cursor: null }
+
+/** Re-read both files now (cheap: two small JSON files and two hashes). Trust is separate. */
+export function refreshProviderHookFiles(nowMs = Date.now()): void {
+  try {
+    const present = codexPresent()
+    snapshot.codex = { present, status: present ? codexHookStatus() : null, at: nowMs }
+  } catch { /* the previous snapshot stands */ }
+  try {
+    const cursor = cursorObserverStatus()
+    snapshot.cursor = { installed: cursor.installed, nodeOk: cursor.nodeOk, at: nowMs }
+  } catch { /* the previous snapshot stands */ }
+}
+
+const iso = (ms: number | null | undefined) => (typeof ms === 'number' ? new Date(ms).toISOString() : null)
+
+export function codexHooksHealthField(nowMs = Date.now()): CodexHooksHealth {
+  const codex = snapshot.codex
+  const trust = cachedCodexHookTrust(nowMs)
+  return {
+    present: codex?.present === true,
+    installed: codex?.status?.installed === true,
+    state: codex?.status?.state ?? null,
+    trust: codex?.status?.installed === true ? trust.trust : 'unknown',
+    trustReason: codex?.status?.installed === true ? trust.trustReason : 'not_installed',
+    scriptOk: codex?.status?.scriptOk === true,
+    checkedAt: iso(codex?.at),
+    trustCheckedAt: iso(trust.checkedAt),
+  }
+}
+
+export function cursorObserverHealthField(): CursorObserverHealth {
+  const cursor = snapshot.cursor
+  return { installed: cursor?.installed === true, nodeOk: cursor?.nodeOk === true, checkedAt: iso(cursor?.at) }
+}
+
+/**
+ * 6.62.0 (plan 3.8): can the Codex hooks stop a desk Codex run right now? Installed, trusted by
+ * Codex itself, and this package's script (whose Codex reply is the deny-only one).
+ */
+export function codexDeskHaltReady(nowMs = Date.now()): boolean {
+  const field = codexHooksHealthField(nowMs)
+  return field.present && field.installed && field.scriptOk && (field.trust === 'trusted' || field.trust === 'managed')
+}
+
+export type ObserveSource = string
+
+export interface ProviderObserve {
+  /** The hook pipeline this engine's sessions report through: a state word, or `none`. */
+  hooks: ObserveSource
+  /** Where a row's running/idle comes from. */
+  liveState: ObserveSource
+  /** Where child agents are counted from. */
+  children: ObserveSource
+  /** Where "compacting context" comes from. */
+  compaction: ObserveSource
+  /** Where the reasoning line on the live feed comes from. */
+  reasoning: ObserveSource
+}
+
+/**
+ * `providers.<engine>.observe` (plan 1.10). `claudeHooks` is Claude's install state word and
+ * whether its hooks can stop a run (they are what Cursor runs too).
+ */
+export function providerObserveFields(claudeHooks: { state: string; ready: boolean }, nowMs = Date.now()): Record<'claude' | 'codex' | 'cursor', { observe: ProviderObserve }> {
+  const codex = codexHooksHealthField(nowMs)
+  const cursor = cursorObserverHealthField()
+  const codexHooksRun = codex.installed && (codex.trust === 'trusted' || codex.trust === 'managed')
+  return {
+    claude: {
+      observe: {
+        hooks: claudeHooks.state,
+        liveState: claudeHooks.ready ? 'hook' : 'registry',
+        children: claudeHooks.ready ? 'hook' : 'none',
+        compaction: claudeHooks.ready ? 'hook' : 'none',
+        // By design: Claude's thinking blocks are never put on the lens (session-stream-events).
+        reasoning: 'none',
+      },
+    },
+    codex: {
+      observe: {
+        hooks: !codex.present ? 'absent' : codex.installed ? codex.trust : (codex.state ?? 'unknown'),
+        liveState: codexHooksRun ? 'hook' : 'transcript',
+        children: 'state_db',
+        // The rollout writes a compaction only when it is over; only the hook sees one start.
+        compaction: codexHooksRun ? 'hook' : 'rollout_end',
+        reasoning: 'rollout',
+      },
+    },
+    cursor: {
+      observe: {
+        hooks: claudeHooks.ready ? 'claude_hooks' : claudeHooks.state,
+        liveState: claudeHooks.ready ? 'hook' : 'file_time',
+        children: cursor.installed && cursor.nodeOk ? 'observer' : 'none',
+        compaction: cursor.installed && cursor.nodeOk ? 'observer' : 'none',
+        reasoning: cursor.installed && cursor.nodeOk ? 'observer' : 'none',
+      },
+    },
+  }
+}
+
+/** File status every half minute; Codex trust every CODEX_TRUST_REFRESH_MS (a third of its cache window). */
+export const PROVIDER_FILES_REFRESH_MS = 30_000
+
+let refreshTimer: ReturnType<typeof setInterval> | null = null
+let lastTrustAt = 0
+
+/**
+ * The composition root's background refresh. Never on a request path; never in a test that
+ * does not call it. The trust read runs only while our hooks are installed in Codex's file.
+ */
+export function startProviderObserveRefresh(): () => void {
+  // The desk cancel reads Codex readiness from the same snapshot health shows (plan 3.8).
+  setCodexDeskCancelReady(() => codexDeskHaltReady())
+  // QA W20: per-spawn Cursor config folders a crash or a restart left behind are reaped at
+  // boot, not only when the next Cursor spawn happens to run.
+  try {
+    const swept = sweepStaleCursorSpawnDirs()
+    if (swept > 0) console.log(`[provider-observe] removed ${swept} stale Cursor spawn folder(s)`)
+  } catch (error) {
+    console.warn(`[provider-observe] Cursor spawn sweep skipped: ${error instanceof Error ? error.name : 'error'}`)
+  }
+  const tick = () => {
+    refreshProviderHookFiles()
+    const now = Date.now()
+    if (snapshot.codex?.status?.installed === true && now - lastTrustAt >= CODEX_TRUST_REFRESH_MS) {
+      lastTrustAt = now
+      void refreshCodexHookTrust().catch(() => { /* the last answer stands */ })
+    }
+  }
+  tick()
+  refreshTimer = setInterval(tick, PROVIDER_FILES_REFRESH_MS)
+  refreshTimer.unref?.()
+  return () => { if (refreshTimer) clearInterval(refreshTimer); refreshTimer = null }
+}
+
+/**
+ * After an install or uninstall: the files now, and a FRESH trust read in the background. A read
+ * already in flight began before the write and is superseded, never reused (QA W4).
+ */
+export function refreshAfterInstall(): void {
+  refreshProviderHookFiles()
+  if (snapshot.codex?.status?.installed === true) {
+    lastTrustAt = Date.now()
+    void refreshCodexHookTrust({ fresh: true }).catch(() => { /* the last answer stands */ })
+  }
+}
+
+export function __resetProviderObserveForTests(): void {
+  snapshot.codex = null
+  snapshot.cursor = null
+  lastTrustAt = 0
+  if (refreshTimer) clearInterval(refreshTimer)
+  refreshTimer = null
+}

package/server/lib/provider-proof.ts

@@ -1,7 +1,11 @@
 import { spawn } from 'node:child_process'
 import { cosBrainDir } from './launch-dir.js'
 import { resolveAgentBinary } from './cursor-model-catalog.js'
+import { cursorSpawnEnv, releaseCursorSpawnOnExit } from './cursor-spawn-env.js'
 import { terminateProviderProcess } from './provider-process-lifecycle.js'
+import { PROVIDER_AUTH_RE, PROVIDER_OVERFLOW_RE, PROVIDER_QUOTA_RE } from './provider-failure-text.js'
+
+export { PROVIDER_AUTH_RE, PROVIDER_OVERFLOW_RE, PROVIDER_QUOTA_RE }
 
 export type ProofProvider = 'claude' | 'codex' | 'cursor'
 export const PROOF_PROVIDERS: readonly ProofProvider[] = ['claude', 'codex', 'cursor']
@@ -54,12 +58,17 @@ export const CLAUDE_SAFE_MODE_ENV = 'CLAUDE_CODE_SAFE_MODE'
 
 type TerminationReason = 'timeout' | 'abort' | null
 
+function spawnPiped(command: string, args: string[], cwd: string, env: NodeJS.ProcessEnv) {
+  return spawn(command, args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true })
+}
+
 export function runBounded(
   command: string,
   args: string[],
   input: string,
   timeoutMs = 120_000,
   signal?: AbortSignal,
+  options: { cursorIsolation?: boolean } = {},
 ): Promise<ProcessResult> {
   return new Promise((resolvePromise) => {
     if (signal?.aborted) {
@@ -69,12 +78,17 @@ export function runBounded(
     const env = { ...process.env }
     delete env.CLAUDECODE
     env[CLAUDE_SAFE_MODE_ENV] = '1'
-    const child = spawn(command, args, {
-      cwd: cosBrainDir() ?? process.cwd(),
-      env,
-      stdio: ['pipe', 'pipe', 'pipe'],
-      detached: true,
-    })
+    // 6.62.0 (plan 3.4): the Cursor proof runs on a config dir of its own, like every
+    // other `agent` spawn, so Update Server's proof cannot touch the person's CLI default.
+    const isolation = options.cursorIsolation === true ? cursorSpawnEnv({ baseEnv: env }) : null
+    let child: ReturnType<typeof spawnPiped>
+    try {
+      child = spawnPiped(command, args, cosBrainDir() ?? process.cwd(), isolation ? isolation.env : env)
+    } catch (error) {
+      isolation?.release()
+      throw error
+    }
+    if (isolation) releaseCursorSpawnOnExit(child, isolation)
     let stdout = ''
     let stderr = ''
     let settled = false
@@ -194,11 +208,6 @@ function safeProofError(result: ProcessResult): string {
   return 'provider returned no valid proof response'
 }
 
-/** A provider's own words for a spent session, usage, rate or capacity limit. Also the lens
- * gist's (lens-gist-engines.ts), so both read a limit the same way. */
-export const PROVIDER_QUOTA_RE = /usage[ _]limit|hit your (?:usage |session )?limit|session limit|rate.?limit|too many requests|\b429\b|\bquota\b|resets? (?:at|in) |over capacity|overloaded|\b529\b|plan limit/i
-const AUTH_RE = /not logged in|please (?:log ?in|sign in)|invalid api key|authentication|unauthori[sz]ed|\b401\b|\b403\b|login required|token (?:has )?expired|no credentials/i
-const OVERFLOW_RE = /prompt is too long|context window|too many tokens|exceeds the (?:model|context)/i
 const MISSING_RE = /ENOENT|command not found|no such file/i
 
 /** Vendor text the provider printed, so the code can be derived without ever
@@ -210,9 +219,9 @@ export function classifyProofFailure(result: ProcessResult, answer: string, expe
   if (result.timedOut) return 'provider_timeout'
   const haystack = `${result.stderr}\n${result.stdout}`.slice(0, 40_000)
   if (result.code === null && MISSING_RE.test(haystack)) return 'provider_missing'
-  if (OVERFLOW_RE.test(haystack)) return 'provider_context_overflow'
+  if (PROVIDER_OVERFLOW_RE.test(haystack)) return 'provider_context_overflow'
   if (PROVIDER_QUOTA_RE.test(haystack)) return 'provider_quota'
-  if (AUTH_RE.test(haystack)) return 'provider_auth'
+  if (PROVIDER_AUTH_RE.test(haystack)) return 'provider_auth'
   if (result.code === 0) return answer === expected ? 'provider_failed' : 'provider_bad_answer'
   return 'provider_failed'
 }
@@ -286,7 +295,7 @@ async function executeProof(provider: ProofProvider, signal?: AbortSignal): Prom
   } else {
     const binary = resolveAgentBinary()
     result = binary
-      ? await runBounded(binary, cursorProofArgs(), PROOF_PROMPT, CURSOR_PROOF_TIMEOUT_MS, signal)
+      ? await runBounded(binary, cursorProofArgs(), PROOF_PROMPT, CURSOR_PROOF_TIMEOUT_MS, signal, { cursorIsolation: true })
       : { code: null, stdout: '', stderr: 'ENOENT: cursor agent binary not found', timedOut: false, aborted: false }
   }
   const text = provider === 'claude'