@gotcos/glasses-server 6.62.1 → 6.63.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 6.63.0 — 2026-10-05 — Background forks
+
+- Background forks. `POST /api/agent-sessions/:provider/:threadId/fork` accepts an optional `clientForkId`: once every gate passes it answers 202 and runs the fork in the background, and `GET /api/agent-session-forks/:clientForkId` returns `running` or the exact answer the synchronous route would have sent. A repeated id replays its job and never makes a second copy. Outcomes are kept in `<data>/fork-jobs.json` (7 days, 200 rows); a fork still running when the server stops reads back as orphan-possible ("look in Sessions before forking again"), never as failed. Without the id the route is unchanged. Why: on 2026-10-05 COS Control waited 5 minutes for a 6.5-minute fork that succeeded and told Miles the server had stopped. Pairs with COS Control 0.5.257; older clients keep the synchronous route.
+- A fork that recovered from a transient retry (Claude `api_retry` "overloaded"/"rate_limit", Codex "Reconnecting… 429") and then failed is reported by the provider's final error, not the retry: "too long" no longer reads as "usage limit". (6.62.1 QA)
+
 ## 6.62.1 — 2026-10-05 — Combined provider parity and handoff hardening
 
 - Includes the 6.62.0 provider parity, cancellation, hook readiness, and safe Cursor continuation updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.62.1",
+  "version": "6.63.0",
   "description": "COS Glasses: self-hosted AI heads-up-display server for Even G2 smart glasses, powered by Claude Code, Codex, Cursor Agent CLI, or local Ollama",
   "type": "module",
   "bin": {

package/server/index.ts

@@ -11,7 +11,7 @@ import { readFileSync, existsSync } from 'node:fs'
 import { networkInterfaces, homedir } from 'node:os'
 import { join } from 'node:path'
 import { execSync } from 'node:child_process'
-import { randomBytes } from 'node:crypto'
+import { randomBytes, randomUUID } from 'node:crypto'
 import { healthRouter } from './routes/health.js'
 import { diagRouter } from './routes/diag.js'
 import { createClientInstanceRouter } from './routes/client-instance.js'
@@ -67,6 +67,7 @@ import { parseAgentSession } from './lib/agent-session-store.js'
 import { makeLiveTurnDeliverer } from './lib/session-peer-inbox-deps.js'
 import { makeCodexLiveDeliverer } from './lib/codex-live-queue-deps.js'
 import { forkThread, realForkDeps } from './lib/fork-thread.js'
+import { ForkJobLedger, fileForkJobPersistence } from './lib/fork-job-ledger.js'
 import { nativeHead, realNativeHeadDeps } from './lib/native-head.js'
 import { threadOccupancy, holderActivity } from './lib/thread-occupancy.js'
 import { displayRouter } from './routes/display.js'
@@ -989,6 +990,10 @@ app.use('/api', createAgentSessionBindingsRouter({
   // 6.62.0 /qa (W9): the fixed note when the read misses its budget.
   continueNoteFallback: (provider, options) => fallbackContinueNote(provider, { noteAck: options.noteAck, codexFallbackSandbox: continueFactsDeps.codexFallbackSandbox() }),
   forkThread: forkThreadForRoute,
+  // 6.63.0: background forks record their outcome here, so a client that cannot hold a
+  // 21-minute request (COS Control, the phone) reads it from GET /api/agent-session-forks/:id.
+  // Durable: a restart turns a still-running row into the cautious orphan-possible answer.
+  forkJobs: new ForkJobLedger(randomUUID(), fileForkJobPersistence(dataPath('fork-jobs.json'))),
   // The fork's real spawn directory. Separate from `resolveTarget` above, which
   // deliberately yields only fingerprints because plan 3.3 keeps a filesystem path
   // off anything client-visible. Null refuses: never fall back to the server's own

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

@@ -232,13 +232,32 @@ export function classifyProviderErrorText(text: string): ForkProviderFailure | n
  * 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
-  const carrier = (j.type === 'result' && j.is_error === true) || j.isApiErrorMessage === true
-    || typeof j.error === 'string' || j.type === 'error' || j.type === 'turn.failed'
+  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[] = []
@@ -824,6 +843,13 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
     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
@@ -873,7 +899,7 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
           for (const id of extractNativeIdsFromLine(line)) {
             if (!observedIds.includes(id)) observedIds.push(id)
           }
-          providerFailure ??= classifyProviderOutputLine(line)
+          noteProviderLine(line)
         }
         // Deliberately nothing else: no text, no tool calls, no transcript. This
         // module cannot leak what it never held.
@@ -900,7 +926,7 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
         for (const id of extractNativeIdsFromLine(stdoutTail)) {
           if (!observedIds.includes(id)) observedIds.push(id)
         }
-        providerFailure ??= classifyProviderOutputLine(stdoutTail)
+        noteProviderLine(stdoutTail)
         stdoutTail = ''
       }
 
@@ -912,7 +938,7 @@ function driveChild(input: DriveInput): Promise<ForkResult> {
         const verdict = selectForkedId(observedIds, sourceNativeThreadId)
         return verdict.ok ? verdict.newNativeThreadId : null
       }
-      const cause = (): string | null => providerFailure ?? classifyProviderErrorText(stderrSample)
+      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', { newNativeThreadId: copyId(), detail: cause() })

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

@@ -126,6 +126,7 @@ import type { RegistryCheck, RegistryRejection, RegistryResult } from '../lib/ag
 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,
@@ -448,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. */
@@ -1522,6 +1530,22 @@ export function classifyFork(result: unknown, sourceNativeThreadId: string): For
 }
 
 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.'
 
@@ -1648,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)
@@ -2443,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,
@@ -2460,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')
@@ -2477,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 ?? '')
@@ -2486,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')
 
@@ -2514,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({
@@ -2568,7 +2657,7 @@ 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: outcome.integrity === 'verified_unchanged' ? FORKED_COPY : FORKED_COPY_UNVERIFIED,
@@ -2586,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