@gotcos/glasses-server 6.61.7 → 6.63.0

package/server/routes/agent-session-bindings.ts

@@ -121,13 +121,17 @@ import {
   type BindingState,
   type NativeBinding,
 } from '../lib/agent-session-binding-store.js'
+import { boundedContinueNote, CONTINUE_NOTE_HEADER, continueNoteAcknowledged, fallbackContinueNote } from '../lib/continue-plan.js'
 import type { RegistryCheck, RegistryRejection, RegistryResult } from '../lib/agent-session-binding-registry.js'
 import { recordCosSpawn, releaseCosSpawn } from '../lib/agent-session-ownership-store.js'
 import { isValidNativeThreadId } from '../lib/native-thread-id.js'
+import { FORK_PROVIDER_FAILURES, type ForkProviderFailure } from '../lib/fork-thread.js'
+import { CLIENT_FORK_ID_RE, ForkJobLedger, type ForkJobRow } from '../lib/fork-job-ledger.js'
 import { PEER_VERIFY_TIMEOUT_MS } from '../lib/session-peer-inbox.js'
 import {
   CANCEL_QUEUE_HOLD_MS,
   CLIENT_CANCEL_ID_RE,
+  DESK_RUN_EFFECT_COPY,
   cancelRefusalCopy,
   cancelTargetFor,
   type CancelFacts,
@@ -257,6 +261,11 @@ export interface AttachedTurnRequest {
    * simply never calls it.
    */
   onSpawn: (pid: number) => boolean
+  /**
+   * 6.62.0 /qa (Q3): the client sent `X-COS-Continue-Note: 1`, i.e. it shows `continue_note`.
+   * Only then may a Cursor Continue run Run Everything; otherwise it keeps the 6.61 Ask posture.
+   */
+  continueNoteAck?: boolean
   /**
    * 6.53.0: aborted by POST .../cancel. The adapter checks it before the spawn and
    * before the prompt write, and stops the child's process group after. Optional so an
@@ -370,6 +379,29 @@ export interface AgentSessionBindingsDeps {
    */
   deliverCodexLiveTurn?: (request: { provider: string; sessionId: string; prompt: string; foreignHolder: boolean }) => Promise<{ ok: boolean; reason: string; verifiedBy?: string | null; queuedId?: string | null }>
 
+  /**
+   * 6.62.0 (plan 3.6, W8): may a BUSY Codex thread the Codex app holds take a turn through
+   * that app's own queue right now? Production: `COS_CODEX_LIVE_QUEUE` is on AND the COS
+   * queue for the thread is empty (so a new turn never jumps one already waiting). Absent
+   * or anything but `true`: a busy holder refuses `native_thread_working`, as in 6.61.
+   */
+  busyCodexHop?: (threadId: string) => boolean
+
+  /**
+   * 6.62.0 (plan 3.12): what a Continue on this thread would run with, in 60 characters
+   * or less (`session-continue-facts.ts`). Added to the attachability verdict as
+   * `continue_note`. Optional; absent, null, slow (past `CONTINUE_NOTE_BUDGET_MS`) or a
+   * throw omits the field, and the verdict is unchanged.
+   */
+  continueNote?: (provider: BindableProvider, threadId: string, options?: { noteAck: boolean }) => Promise<string | null> | string | null
+
+  /**
+   * 6.62.0 /qa (W9): the note when `continueNote` misses its budget, throws, or answers
+   * nothing usable, so a Cursor Continue never runs Run Everything unannounced. Defaults to
+   * `fallbackContinueNote` with this process's environment.
+   */
+  continueNoteFallback?: (provider: BindableProvider, options: { noteAck: boolean }) => string | null
+
   /**
    * The self-recursion ledger. Defaults to the real process-wide one.
    *
@@ -406,7 +438,7 @@ export interface AgentSessionBindingsDeps {
    * write a NEW session rather than the one asked for, which for a fork means the
    * copy silently lands in the wrong project.
    */
-  resolveForkWorkspace?: (provider: BindableProvider, nativeThreadId: string) => string | null
+  resolveForkWorkspace?: (provider: BindableProvider, nativeThreadId: string) => string | null | Promise<string | null>
 
   /**
    * Where an opaque fork reference is exchanged for the thread it names.
@@ -417,6 +449,13 @@ export interface AgentSessionBindingsDeps {
    */
   forkRefs?: ForkRefStore
 
+  /**
+   * 6.63.0: where a background fork (`clientForkId` in the body) records its outcome for
+   * `GET /agent-session-forks/:clientForkId`. Defaults to an in-memory ledger per router;
+   * the server wires the durable one (`<data>/fork-jobs.json`).
+   */
+  forkJobs?: ForkJobLedger
+
   /** Lease TTL for a new binding. */
   attachTtlMs?: number
   /** Upper bound on one prompt. A prompt is not a payload. */
@@ -459,7 +498,7 @@ export interface CancelDeps {
    * have reached) the open session. Writes the halt marker, and re-arms it once when that
    * turn's own UserPromptSubmit deletes it (`haltHandedOffTurn`). False: not armed.
    */
-  haltHandedOffTurn?: (sessionId: string, marker: { at: number; clientCancelId: string }, turn: { prompt: string; sentAt: number; unverified?: boolean }) => boolean
+  haltHandedOffTurn?: (sessionId: string, marker: { at: number; clientCancelId: string }, turn: { prompt: string; sentAt: number; unverified?: boolean; verbatim?: boolean; deferMarker?: boolean }) => boolean
   /** Append to `data/session-cancel.jsonl`. */
   ledger?: (row: SessionCancelLedgerRow) => void
 }
@@ -597,6 +636,13 @@ export type WriteRefusal =
   | 'fork_failed'
   | 'fork_source_mutated'
   | 'fork_orphan_possible'
+  // 6.62.1 (2026-10-05): the copy exists and is named, but the provider refused its
+  // first turn. Each says WHY, because the next step differs: a smaller source, a
+  // reset, or a sign-in. None is retryable: a retry makes another full copy.
+  | 'fork_turn_failed'
+  | 'fork_context_too_long'
+  | 'fork_provider_limit'
+  | 'fork_provider_auth'
 
 /**
  * Footer copy for the refusals that are not occupancy reasons.
@@ -680,8 +726,18 @@ export const WRITE_REASON_COPY: Record<Exclude<WriteRefusal, OccupancyReason>, s
   // touches it.
   fork_source_mutated:
     'The original thread changed while COS was copying it. Open the original on your Mac and check it before doing anything else.',
+  // 6.62.1: no "untouched" here. This outcome is reached exactly when COS could not
+  // read the copy's result, so it cannot vouch for anything after the spawn either.
   fork_orphan_possible:
-    'COS lost track of the copy it was making. Your original is untouched, but a partial copy may exist on your Mac.',
+    'COS did not get an answer from the copy it was making. A copy may exist on your Mac; check your sessions before forking again.',
+  fork_turn_failed:
+    'COS made the copy, but the assistant did not answer in it. Open the copy to see why before trying again.',
+  fork_context_too_long:
+    'This conversation is too long to continue in a copy: the assistant refused it as too long. Start a new session with the task instead.',
+  fork_provider_limit:
+    'The assistant hit its usage limit, so the copy got no answer. Try again after the limit resets, or start a new session with another assistant.',
+  fork_provider_auth:
+    'The assistant needs you to sign in again on this Mac before COS can copy this conversation.',
 }
 
 export function writeReasonCopy(reason: WriteRefusal): string {
@@ -814,7 +870,7 @@ export function projectAttachability(verdict: Occupancy): AttachabilityBody {
   const owners = Array.isArray(verdict?.owners) ? verdict.owners : null
   // Strictly `=== true`. An idleHolder of 1, 'yes', or {} is a malformed verdict,
   // and a malformed verdict must not buy an exemption.
-  const foreignOwnerDeclared = verdict?.idleHolder === true
+  const foreignOwnerDeclared = verdict?.idleHolder === true || verdict?.busyHolder === true
   const sound =
     verdict?.attachable === true &&
     verdict.reason === null &&
@@ -1412,9 +1468,23 @@ export class ForkRefStore {
 export type ForkOutcome =
   | { kind: 'created'; newNativeThreadId: string; integrity: 'verified_unchanged' | 'unverified' }
   | { kind: 'mutated' }
-  | { kind: 'orphan_possible' }
+  // 6.62.1: the copy is named but its first turn failed; `cause` is the provider's own
+  // reason when its error event said one.
+  | { kind: 'turn_failed'; newNativeThreadId: string; cause: ForkProviderFailure | null }
+  | { kind: 'orphan_possible'; cause?: ForkProviderFailure | null }
   | { kind: 'failed' }
 
+const forkProviderFailure = (detail: unknown): ForkProviderFailure | null =>
+  typeof detail === 'string' && (FORK_PROVIDER_FAILURES as readonly string[]).includes(detail) ? detail as ForkProviderFailure : null
+
+/** The refusal reason for a provider-stated cause, or the generic one. */
+export function forkFailureReason(cause: ForkProviderFailure | null | undefined, generic: WriteRefusal): WriteRefusal {
+  if (cause === 'context_too_long') return 'fork_context_too_long'
+  if (cause === 'provider_limit') return 'fork_provider_limit'
+  if (cause === 'provider_auth') return 'fork_provider_auth'
+  return generic
+}
+
 /**
  * Read a fork result without believing anything it did not say.
  *
@@ -1427,7 +1497,7 @@ export type ForkOutcome =
  */
 export function classifyFork(result: unknown, sourceNativeThreadId: string): ForkOutcome {
   if (!result || typeof result !== 'object' || Array.isArray(result)) return { kind: 'orphan_possible' }
-  const { ok, newNativeThreadId, sourceIntegrity, forkState, reason } = result as Record<string, unknown>
+  const { ok, newNativeThreadId, sourceIntegrity, forkState, reason, detail } = result as Record<string, unknown>
 
   if (ok === true) {
     // The single invariant this route re-checks itself rather than inheriting.
@@ -1449,11 +1519,35 @@ export function classifyFork(result: unknown, sourceNativeThreadId: string): For
     if (reason === 'source_thread_mutated' || sourceIntegrity === 'mutated') return { kind: 'mutated' }
     // Only an explicit "no child was created" earns the clean failure.
     if (forkState === 'none') return { kind: 'failed' }
+    // 6.62.1: a named copy is not an orphan. Same id rules as success: valid, and
+    // never the source (that would be an append reported as a copy).
+    if (isValidNativeThreadId(newNativeThreadId) && newNativeThreadId !== sourceNativeThreadId) {
+      return { kind: 'turn_failed', newNativeThreadId, cause: forkProviderFailure(detail) }
+    }
+    return { kind: 'orphan_possible', cause: forkProviderFailure(detail) }
   }
   return { kind: 'orphan_possible' }
 }
 
 export const FORKED_COPY = 'Copied into a new thread. Your original is untouched.'
+/** 6.63.0: the 202 for a background fork. The outcome is read from the status route. */
+export const FORK_RUNNING_COPY = 'COS is making the copy and sending your instruction. This can take several minutes.'
+export const FORK_JOB_UNKNOWN_COPY = 'This server has no record of that fork. Look for the copy in Sessions before forking again.'
+
+/** What a background fork's id answers right now: running, or the recorded outcome. */
+export function projectForkJob(row: ForkJobRow): { status: number; body: Record<string, unknown> } {
+  if (row.state === 'running') {
+    return { status: 200, body: { state: 'running', clientForkId: row.clientForkId, acceptedAt: row.acceptedAt, reasonCopy: FORK_RUNNING_COPY } }
+  }
+  // `status` is the ORIGINAL answer's code, surfaced under its own name: a refused fork
+  // read back correctly is a successful read.
+  return {
+    status: 200,
+    body: { ...(row.result ?? {}), state: 'done', clientForkId: row.clientForkId, recordedStatus: row.status ?? null, polled: true },
+  }
+}
+/** 6.62.1: `unverified` must never be rendered as confirmed untouched (see the success body). */
+export const FORKED_COPY_UNVERIFIED = 'Copied into a new thread. COS could not re-read your original afterwards to confirm it is unchanged.'
 
 /**
  * Both fingerprints present, bounded, and strings.
@@ -1500,6 +1594,12 @@ export const TURN_SENT_CODEX_QUEUE_COPY = 'Queued in the Codex app. It runs when
  */
 export const LIVE_VERIFY_BUDGET_MS = PEER_VERIFY_TIMEOUT_MS
 
+/**
+ * 6.62.0: how long the attachability verdict waits for its `continue_note`. The verdict is
+ * a menu-open read; a cold Codex posture scan or a busy Cursor database must not hold it.
+ */
+export const CONTINUE_NOTE_BUDGET_MS = 1_500
+
 /**
  * The 202 copy. Says QUEUED and not sent, because at this instant the provider has
  * not been spawned — claiming otherwise would be the same silent-success lie the
@@ -1572,6 +1672,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
   // One per router. Injectable so the follow-on (attach accepting a `forkRef`)
   // shares this instance rather than standing up a second, disconnected one.
   const forkRefs = deps?.forkRefs instanceof ForkRefStore ? deps.forkRefs : new ForkRefStore()
+  const forkJobs = deps?.forkJobs instanceof ForkJobLedger ? deps.forkJobs : new ForkJobLedger(randomUUID())
   const attachTtlMs =
     Number.isFinite(deps?.attachTtlMs) && (deps.attachTtlMs as number) > 0
       ? (deps.attachTtlMs as number)
@@ -1623,6 +1724,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     }
     return {
       provider,
+      threadId,
       cosTurnInFlight,
       runningOutsideCos,
       hooksEnabled: cancelProbe(() => cancelDeps.hooksEnabled?.() === true, false),
@@ -1660,7 +1762,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     provider: string,
     threadId: string,
     reached: 'none' | 'reached' | 'maybe',
-    turn: { prompt: string; sentAt: number },
+    turn: { prompt: string; sentAt: number; busy?: boolean },
   ): void => {
     const latch = entry.latched
     if (latch === null) return
@@ -1673,6 +1775,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     if (reached !== 'none') {
       target = cancelTargetFor({
         provider,
+        threadId,
         cosTurnInFlight: false,
         runningOutsideCos: true,
         hooksEnabled: cancelProbe(() => cancelDeps.hooksEnabled?.() === true, false),
@@ -1685,6 +1788,13 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           prompt: turn.prompt,
           sentAt: turn.sentAt,
           unverified: reached === 'maybe',
+          // 6.62.0 (plan 3.6): a Codex turn went into the app's own queue, which hands its
+          // text to the session's UserPromptSubmit as is: matched verbatim, no peer unwrap.
+          ...(provider === 'codex' ? { verbatim: true } : {}),
+          // 6.62.0 /qa (W3): on a BUSY hop the session is still running Miles's OWN desk turn.
+          // A marker written now would stop that turn at its next tool, so only the re-arm is
+          // registered: the marker lands on the delivered turn's own UserPromptSubmit.
+          ...(turn.busy === true ? { deferMarker: true } : {}),
         }) === true, false)
         if (armed) {
           const settledPermissions = cancelProbe(() => cancelDeps.settlePermissions?.(threadId) ?? 0, 0)
@@ -1692,6 +1802,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
             cancelled: true,
             target,
             effective: 'next_tool_call',
+            effectCopy: DESK_RUN_EFFECT_COPY,
             ...common,
             settledPermissions: Number.isInteger(settledPermissions) && settledPermissions > 0 ? settledPermissions : 0,
           }
@@ -1743,8 +1854,29 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       return { attachable: false, owners: [], reason: 'probe_failed' }
     }
   }
+  /**
+   * 6.62.0 (plan 3.6, W8): a WORKING Codex holder that is not ours, on a thread the hop may
+   * take, reads attachable through a declared `busyHolder`. Shared by the probe, attach and
+   * turns, so all three agree. Anything less than every condition keeps the verdict as is.
+   */
+  const withBusyCodexHop = (provider: string, threadId: string, detected: Occupancy): Occupancy => {
+    if (provider !== 'codex' || detected.attachable || detected.reason !== 'native_thread_working') return detected
+    if (typeof deps.deliverCodexLiveTurn !== 'function' || typeof deps.busyCodexHop !== 'function') return detected
+    const owners = Array.isArray(detected.owners) ? detected.owners : []
+    if (!owners.some(owner => owner?.selfOwned !== true && owner?.source === 'codex-writer-lock')) return detected
+    let allowed = false
+    try {
+      allowed = deps.busyCodexHop(threadId) === true
+    } catch (error) {
+      console.error(`[agent-session-bindings] busy codex hop check threw: ${error instanceof Error ? error.message : error}`)
+      allowed = false
+    }
+    return allowed ? { attachable: true, owners, reason: null, busyHolder: true } : detected
+  }
+  const routeOccupancy = (provider: string, threadId: string): Occupancy =>
+    withBusyCodexHop(provider, threadId, detectOccupancy(provider, threadId))
   const runOccupancy = (provider: string, threadId: string): AttachabilityBody =>
-    projectAttachability(detectOccupancy(provider, threadId))
+    projectAttachability(routeOccupancy(provider, threadId))
 
   const refuseAttach = (res: Response, reason: WriteRefusal): void => {
     res.status(refusalStatus(reason)).json({
@@ -1853,7 +1985,46 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     res.json({ released: true, target, provider: outcome.row.provider })
   })
 
-  router.get('/agent-sessions/:provider/:threadId/attachability', (req, res) => {
+  /**
+   * 6.62.0 (plan 3.12): `continue_note` for the verdict, bounded in time and length. 6.62.0
+   * /qa (W9): a read that misses the budget, throws, or answers nothing usable gets the
+   * provider's fixed note instead, never no note (Claude has none either way).
+   */
+  const continueNoteFor = async (provider: string, threadId: string, noteAck: boolean): Promise<{ continue_note?: string }> => {
+    const read = deps.continueNote
+    if (typeof read !== 'function' || !isBindableProvider(provider) || !isValidNativeThreadId(threadId)) return {}
+    const fallback = (): { continue_note?: string } => {
+      let note: string | null = null
+      try {
+        note = deps.continueNoteFallback
+          ? deps.continueNoteFallback(provider, { noteAck })
+          : fallbackContinueNote(provider, { noteAck })
+      } catch {
+        note = null
+      }
+      const bounded = boundedContinueNote(note)
+      return bounded ? { continue_note: bounded } : {}
+    }
+    let timer: ReturnType<typeof setTimeout> | null = null
+    let missed = false
+    try {
+      const note = await Promise.race([
+        Promise.resolve(read(provider, threadId, { noteAck })),
+        new Promise<null>(resolve => { timer = setTimeout(() => { missed = true; resolve(null) }, CONTINUE_NOTE_BUDGET_MS) }),
+      ])
+      const bounded = boundedContinueNote(note)
+      if (bounded) return { continue_note: bounded }
+      if (missed) console.warn(`[agent-session-bindings] continue note missed its ${CONTINUE_NOTE_BUDGET_MS} ms budget provider=${provider}: fixed note sent`)
+      return fallback()
+    } catch (error) {
+      console.error(`[agent-session-bindings] continue note failed: ${error instanceof Error ? error.message : error}`)
+      return fallback()
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  router.get('/agent-sessions/:provider/:threadId/attachability', async (req, res) => {
     // An occupancy verdict is a liveness answer with a lifetime of roughly now.
     // A cached `attachable: true` is indistinguishable from a stale one, which is
     // the whole failure this feature exists to prevent.
@@ -1899,7 +2070,17 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     // truncated-id hole opened. The tests pin the ordering behaviorally instead:
     // probes that throw on every call still return `unsupported_provider` /
     // `invalid_thread_id`, which is only possible if nothing was probed.
-    res.json(withCancel(runOccupancy(provider, threadId)))
+    // 6.62.0 /qa (Q2): the busy Codex hop makes the verdict attachable, but a desk run IS
+    // working on that thread, so the cancel row reads the RAW reason. Built from the verdict's
+    // reason, the lens hid Cancel run on every busy Codex Desktop thread.
+    const detected = routeOccupancy(provider, threadId)
+    const verdictBody = projectAttachability(detected)
+    const cancelReason = detected.busyHolder === true ? 'native_thread_working' : verdictBody.reason
+    res.json({
+      ...verdictBody,
+      cancel: cancelFieldFor(provider, threadId, cancelReason),
+      ...(await continueNoteFor(provider, threadId, continueNoteAcknowledged(req.headers[CONTINUE_NOTE_HEADER]))),
+    })
   })
 
   // ------------------------------------------------------------------ cancel
@@ -1989,7 +2170,11 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         activeEntry.controller.abort()
         // Noted as what the run becomes if the hop lands it: a desk run (Claude) or one only
         // its app can stop. Either way only the engine's own end discounts its open turn.
-        cancelProbe(() => cancelDeps.noteCancelled?.(provider, threadId, now, provider === 'claude' ? 'desk_run' : 'unsupported'), undefined)
+        // 6.62.0: a landed Codex or Cursor hop is a desk run COS can stop when that engine's
+        // hooks can (cancelTargetFor's own rule); Claude keeps its 6.53.3 answer unchanged.
+        const landedAs = provider === 'claude' ? 'desk_run'
+          : cancelTargetFor({ ...cancelFactsFor(provider, threadId, null), cosTurnInFlight: false, runningOutsideCos: true }) === 'desk_run' ? 'desk_run' : 'unsupported'
+        cancelProbe(() => cancelDeps.noteCancelled?.(provider, threadId, now, landedAs), undefined)
       }
       activeEntry.latched.replayKeys.push(replayKey)
       return answer(202, 'cos_turn', 'accepted', {
@@ -2034,6 +2219,8 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         cancelled: true,
         target,
         effective: 'next_tool_call',
+        // 6.62.0 (plan 3.8): the words for what the tap did, the same for every engine.
+        effectCopy: DESK_RUN_EFFECT_COPY,
         queuedHeld: queuedHeld(),
         queuedHoldMs: CANCEL_QUEUE_HOLD_MS,
         settledPermissions: Number.isInteger(settledPermissions) && settledPermissions > 0 ? settledPermissions : 0,
@@ -2281,10 +2468,23 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
 
     /** The per-source serialisation claim, released in the finally. */
     let claimedForkKey: string | null = null
+    /**
+     * 6.63.0: set once a background fork has answered 202. From then on the ledger is the
+     * ONLY channel for the outcome, exactly like a queued turn: `answer` settles it there.
+     */
+    let backgroundForkId: string | null = null
 
-    const refuseFork = (reason: WriteRefusal, extra: Record<string, unknown> = {}): void => {
+    const answer = (status: number, payload: Record<string, unknown>): void => {
+      if (backgroundForkId !== null) {
+        forkJobs.settle(backgroundForkId, status, payload, readNow() ?? Date.now())
+        return
+      }
       if (res.headersSent) return
-      res.status(refusalStatus(reason)).json({
+      res.status(status).json(payload)
+    }
+
+    const refuseFork = (reason: WriteRefusal, extra: Record<string, unknown> = {}): void => {
+      answer(refusalStatus(reason), {
         forked: false,
         forkRef: null,
         sourceIntegrity: null,
@@ -2298,6 +2498,16 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       })
     }
 
+    /** Answers a known background fork id with its job, never a second spawn. */
+    const replayForkJob = (row: ForkJobRow): void => {
+      const projected = projectForkJob(row)
+      res.status(row.state === 'running' ? 202 : projected.status).json({
+        ...projected.body,
+        accepted: row.state === 'running' ? true : undefined,
+        replayed: true,
+      })
+    }
+
     try {
       const fork = deps.forkThread
       if (typeof fork !== 'function') return refuseFork('fork_unwired')
@@ -2315,6 +2525,12 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (typeof prompt !== 'string' || prompt.trim().length === 0 || prompt.length > maxPromptChars) {
         return refuseFork('invalid_request')
       }
+      // 6.63.0: optional. With it, the fork answers 202 once every gate has passed and runs
+      // in the background; without it, the route behaves exactly as before.
+      const clientForkId = body.clientForkId
+      if (clientForkId !== undefined && (typeof clientForkId !== 'string' || !CLIENT_FORK_ID_RE.test(clientForkId))) {
+        return refuseFork('invalid_request')
+      }
 
       const providerParam = String(req.params.provider ?? '')
       const threadIdParam = String(req.params.threadId ?? '')
@@ -2324,6 +2540,14 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (!isForkableProvider(providerParam)) return refuseFork('fork_unsupported_provider')
       if (!isValidNativeThreadId(threadIdParam)) return refuseFork('fork_invalid_thread_id')
 
+      // A repeat of a known id replays its job and never spawns: a client that lost the
+      // 202 (or restarted) must be able to resend without making a second copy.
+      const forkSource = opaqueRevision(targetKey(providerParam, threadIdParam))
+      if (typeof clientForkId === 'string') {
+        const known = forkJobs.get(clientForkId)
+        if (known) return known.source === forkSource ? replayForkJob(known) : refuseFork('invalid_request')
+      }
+
       const now = readNow()
       if (now === null) return refuseFork('fork_failed')
 
@@ -2331,7 +2555,9 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (typeof resolveWorkspace !== 'function') return refuseFork('fork_workspace_unresolvable')
       let cwd: string | null = null
       try {
-        cwd = resolveWorkspace(providerParam, threadIdParam)
+        // 6.62.0: may answer later (a Cursor IDE composer's folder is read from Cursor's own
+        // store). Still before the claim below, which stays the last synchronous step.
+        cwd = await resolveWorkspace(providerParam, threadIdParam)
       } catch (error) {
         console.error(`[agent-session-bindings] fork workspace resolve threw: ${error instanceof Error ? error.message : error}`)
         cwd = null
@@ -2350,9 +2576,36 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       // continuation or be blocked by one — `targetKey` is length-prefixed and
       // therefore unambiguous, and this prefix cannot collide with one.
       const forkKey = `fork:${targetKey(providerParam, threadIdParam)}`
-      if (!guard.tryClaim(forkKey, forkKey)) return refuseFork('fork_in_progress')
+      if (!guard.tryClaim(forkKey, forkKey)) {
+        // The same id arriving twice while the first is still resolving its workspace: the
+        // first holds the claim and has begun the job by now, so replay it.
+        const raced = typeof clientForkId === 'string' ? forkJobs.get(clientForkId) : null
+        if (raced && raced.source === forkSource) return replayForkJob(raced)
+        return refuseFork('fork_in_progress')
+      }
       claimedForkKey = forkKey
 
+      if (typeof clientForkId === 'string') {
+        // Recorded BEFORE the spawn and before the 202: a job the ledger cannot hold would
+        // have an outcome nobody can read, so it does not start.
+        const begun = forkJobs.begin({ clientForkId, source: forkSource, provider: providerParam }, now)
+        if (begun.kind === 'existing') return replayForkJob(begun.row)
+        if (begun.kind !== 'started') return refuseFork(begun.kind === 'conflict' ? 'invalid_request' : 'fork_failed')
+        res.status(202).json({
+          accepted: true,
+          state: 'running',
+          clientForkId,
+          forked: null,
+          forkRef: null,
+          orphanPossible: false,
+          retryable: false,
+          reason: null,
+          reasonCopy: FORK_RUNNING_COPY,
+        })
+        backgroundForkId = clientForkId
+        console.log(`[agent-session-bindings] fork accepted provider=${providerParam} background=true`)
+      }
+
       let raw: unknown
       try {
         raw = await fork({
@@ -2371,14 +2624,32 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       }
 
       const outcome = classifyFork(raw, threadIdParam)
+      {
+        // 6.62.1: one line per attempt. On 2026-10-05 a fork's real cause existed only
+        // in the copy's transcript; nothing reached the server log. Enums and numbers
+        // only: no prompt, no provider text, no thread id.
+        const r = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
+        console.log(`[agent-session-bindings] fork outcome provider=${providerParam} outcome=${outcome.kind} cause=${forkProviderFailure(r.detail) ?? 'none'} exit=${typeof r.exitCode === 'number' && Number.isFinite(r.exitCode) ? r.exitCode : 'none'} ms=${typeof r.durationMs === 'number' && Number.isFinite(r.durationMs) ? r.durationMs : 'unknown'}`)
+      }
 
       if (outcome.kind === 'mutated') {
         // The original moved. Loudest outcome in the feature, and not retryable:
         // the user needs to look at their own thread before anything else touches it.
         return refuseFork('fork_source_mutated', { orphanPossible: true, retryable: false })
       }
+      if (outcome.kind === 'turn_failed') {
+        // The copy exists and Control can open it (the helper resolves the digest to the
+        // local transcript). Not an orphan, and not retryable: another try copies again.
+        const copyRef = forkRefs.remember(providerParam, outcome.newNativeThreadId, now)
+        return refuseFork(forkFailureReason(outcome.cause, 'fork_turn_failed'), {
+          forkRef: copyRef, turnFailed: true, failureClass: outcome.cause, orphanPossible: false, retryable: false,
+        })
+      }
       if (outcome.kind === 'orphan_possible') {
-        return refuseFork('fork_orphan_possible', { orphanPossible: true })
+        const cause = outcome.cause ?? null
+        return refuseFork(forkFailureReason(cause, 'fork_orphan_possible'), {
+          orphanPossible: true, failureClass: cause, retryable: cause === null,
+        })
       }
       if (outcome.kind === 'failed') return refuseFork('fork_failed')
 
@@ -2386,10 +2657,10 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       // a fresh fork exactly as for an existing thread.
       const forkRef = forkRefs.remember(providerParam, outcome.newNativeThreadId, now)
 
-      res.status(201).json({
+      answer(201, {
         forked: true,
         reason: null,
-        reasonCopy: FORKED_COPY,
+        reasonCopy: outcome.integrity === 'verified_unchanged' ? FORKED_COPY : FORKED_COPY_UNVERIFIED,
         forkRef,
         // Reported, never assumed. `unverified` means COS could not read the
         // original at both ends — which is not the same as, and must never be
@@ -2404,7 +2675,39 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       refuseFork('fork_orphan_possible', { orphanPossible: true })
     } finally {
       if (claimedForkKey !== null) guard.release(claimedForkKey, claimedForkKey)
+      // A background job must never be left `running` by a path that forgot to answer:
+      // its caller would poll a fork that can no longer finish. Cautious outcome only.
+      if (backgroundForkId !== null && forkJobs.get(backgroundForkId)?.state === 'running') {
+        console.error('[agent-session-bindings] background fork ended without an outcome; recorded as orphan-possible')
+        forkJobs.settle(backgroundForkId, refusalStatus('fork_orphan_possible'), {
+          forked: false, forkRef: null, sourceIntegrity: null, orphanPossible: true, retryable: false,
+          reason: 'fork_orphan_possible', reasonCopy: writeReasonCopy('fork_orphan_possible'),
+        }, readNow() ?? Date.now())
+      }
+    }
+  })
+
+  // ----------------------------------------------------- background fork status
+  //
+  // 6.63.0: the outcome of a fork started with a `clientForkId`. Its own path segment
+  // (`/agent-session-forks`), so it can never be read as `/agent-sessions/:provider/:threadId`.
+  // UNGATED, like the fork route it reports on.
+  router.get('/agent-session-forks/:clientForkId', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const clientForkId = String(req.params.clientForkId ?? '')
+    if (!CLIENT_FORK_ID_RE.test(clientForkId)) {
+      res.status(400).json({ state: 'invalid_request', reasonCopy: FORK_JOB_UNKNOWN_COPY })
+      return
     }
+    const row = forkJobs.get(clientForkId)
+    if (row === null) {
+      // Not "failed": an older server, a dropped row or an id never admitted all read this way,
+      // and any of them may have a copy.
+      res.status(404).json({ state: 'unknown', clientForkId, reasonCopy: FORK_JOB_UNKNOWN_COPY })
+      return
+    }
+    const projected = projectForkJob(row)
+    res.status(projected.status).json(projected.body)
   })
 
   // ----------------------------------------------------------------- turns
@@ -2656,14 +2959,16 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       // session started in the gap is exactly the residual risk option B leaves
       // open, and it is terminal here rather than a warning because COS has no
       // cross-process lock that could fence a live desktop writer.
-      const detected = detectOccupancy(binding.provider, binding.nativeThreadId)
+      const detected = routeOccupancy(binding.provider, binding.nativeThreadId)
       const verdict = projectAttachability(detected)
       stage('gate')
       if (!verdict.attachable) return refuseTurn(verdict.reason ?? 'probe_failed')
       // 6.51.0: the SAME verdict says whether a live process that is not ours holds the
-      // thread. Only the declared idle-holder exemption can carry one on an attachable
-      // verdict (`projectAttachability` refuses anything else), so this is that fact.
-      const foreignHolder = detected.idleHolder === true
+      // thread. Only the declared idle-holder exemption (or, 6.62.0, the busy Codex hop)
+      // can carry one on an attachable verdict (`projectAttachability` refuses anything
+      // else), so this is that fact.
+      const busyCodexHop = detected.busyHolder === true
+      const foreignHolder = (detected.idleHolder === true || busyCodexHop)
         && Array.isArray(detected.owners)
         && detected.owners.some(owner => owner?.selfOwned !== true)
 
@@ -2677,7 +2982,15 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       // reads as diverged, because the first turn is what moved the head.
       const baseline = guard.acknowledgedHead(bindingId) ?? binding.nativeHeadAtAttach
       if (typeof baseline !== 'string' || baseline.length === 0) return refuseTurn('native_head_unavailable')
-      if (head.digest !== baseline) {
+      if (head.digest !== baseline && busyCodexHop) {
+        // 6.62.0 (plan 3.6): a busy thread moves while it works; that is what busy means.
+        // The hop puts the turn into the app's own queue, which runs it after the current
+        // turn, the same "append to whatever the thread is when it frees" the COS queue's
+        // watermark exemption already grants a parked turn. Recorded, so the next
+        // interactive turn compares against this head.
+        console.log(`[agent-session-bindings] busy codex hop acknowledges a moving head turnId=${turnId} bindingId=${bindingId}`)
+        guard.acknowledgeHead(bindingId, head.digest)
+      } else if (head.digest !== baseline) {
         // Only a changed/not-changed signal and a new opaque revision. No diff, no
         // content, no path — the client is told THAT it moved, never to what.
         if (acknowledged !== head.digest) {
@@ -2813,7 +3126,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         if (live?.ok) {
           // 6.53.3: queued in the Codex app, which only the app can stop ("Stop it there").
           const latched = latchedHere()
-          if (latched) settleLatchedCancel(latched, binding.provider, binding.nativeThreadId, 'reached', { prompt, sentAt: handOffAt })
+          if (latched) settleLatchedCancel(latched, binding.provider, binding.nativeThreadId, 'reached', { prompt, sentAt: handOffAt, busy: busyCodexHop })
           console.log(`[agent-session-bindings] turn delivered live provider=codex turnId=${turnId} bindingId=${bindingId} verifiedBy=${live.verifiedBy ?? 'unknown'} queuedId=${live.queuedId ?? 'null'}`)
           respond(200, {
             turnId,
@@ -2832,10 +3145,18 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         // latched on the way that is the whole turn: cancelled, and no child.
         const codexLatched = latchedHere()
         if (codexLatched && live !== null && live.reason !== 'unverified') {
-          settleLatchedCancel(codexLatched, binding.provider, binding.nativeThreadId, 'none', { prompt, sentAt: handOffAt })
+          settleLatchedCancel(codexLatched, binding.provider, binding.nativeThreadId, 'none', { prompt, sentAt: handOffAt, busy: busyCodexHop })
           console.log(`[agent-session-bindings] turn cancelled during live hand-off provider=codex turnId=${turnId} bindingId=${bindingId} hop=${live.reason}`)
           return refuseTurn('turn_cancelled', { retryable: false })
         }
+        // 6.62.0 (plan 3.6): a BUSY thread never falls through to a child (the writer lock
+        // is held, so the spawn would fail after the prompt and fence). Whatever reached no
+        // queue row is the 6.61 answer instead: working, and queueable, so the COS queue
+        // takes it. A row that MAY be queued is still the ambiguous fence below.
+        if (busyCodexHop && live !== null && live.reason !== 'unverified') {
+          console.log(`[agent-session-bindings] busy codex hop declined provider=codex turnId=${turnId} bindingId=${bindingId} hop=${live.reason}`)
+          return refuseTurn('native_thread_working')
+        }
         // The operator switched this off: nothing was queued, so the abortable
         // 6.50 child path is cancellable again before it starts.
         if (live?.reason === 'disabled' && liveEntry?.turnId === turnId) liveEntry.cancellable = true
@@ -2860,7 +3181,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
             })
             console.warn(`[agent-session-bindings] fence set site=codex_live provider=codex target=${opaqueRevision(key)} turnId=${turnId} bindingId=${bindingId} headBefore=${head.digest} adapterReason=codex_queue_unverified`)
             // 6.53.3: a row MAY be in the Codex app's queue; a latched cancel says where to stop it.
-            if (codexLatched) settleLatchedCancel(codexLatched, binding.provider, binding.nativeThreadId, 'maybe', { prompt, sentAt: handOffAt })
+            if (codexLatched) settleLatchedCancel(codexLatched, binding.provider, binding.nativeThreadId, 'maybe', { prompt, sentAt: handOffAt, busy: busyCodexHop })
             return reportAmbiguous()
           }
           // Nothing was queued, and the child cannot run against a held thread. Not
@@ -2912,6 +3233,8 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
           expectedNativeHead: head.raw,
           prompt,
           abortSignal: cancelController.signal,
+          // 6.62.0 /qa (Q3): only a client that shows `continue_note` gets Cursor Run Everything.
+          continueNoteAck: continueNoteAcknowledged(req.headers[CONTINUE_NOTE_HEADER]),
           onSpawn: (pid: number): boolean => {
             // THE SELF-RECURSION ORDER. The child registers itself against the id
             // we are targeting, so unless it is in the ledger the next occupancy