@gotcos/glasses-server 6.61.6 → 6.62.1

package/server/lib/session-transcript-watcher.ts

@@ -243,6 +243,7 @@ export function createTranscriptTailer(options: TranscriptTailerOptions): Transc
   let state: 'working' | 'idle' | 'done' | null = null
   let lastActivity = now()
   let degraded = false
+  let skippingCompaction = false
 
   const emit = (draft: SessionStreamDraft) => {
     try {
@@ -275,17 +276,40 @@ export function createTranscriptTailer(options: TranscriptTailerOptions): Transc
           // this design exists to avoid, so we rejoin at the new end and let the poll
           // fallback carry whatever the rotation took with it.
           cursor = { offset: size }
+          skippingCompaction = false
           return
         }
 
         if (size > cursor.offset) {
           const pending = size - cursor.offset
           const length = Math.min(pending, maxRead)
-          const chunk = await readRangeAt(options.path, cursor.offset, length)
+          let chunk = await readRangeAt(options.path, cursor.offset, length)
           if (chunk !== null && chunk.length > 0) {
+            if (skippingCompaction) {
+              const end = chunk.indexOf(10)
+              if (end < 0) { cursor.offset += chunk.length; lastActivity = now(); return }
+              cursor.offset += end + 1
+              chunk = chunk.subarray(end + 1)
+              skippingCompaction = false
+              lastActivity = now()
+              if (!suppressed(options.key)) emit({ kind: 'status', state: 'working' })
+              if (!chunk.length) return
+            }
             const result = consumeTranscriptChunk(cursor, chunk, chunk.length >= maxRead)
             cursor = result.cursor
             if (result.tooLarge) {
+              // A Codex context replacement is internal bookkeeping, not a reply. Its
+              // replacement_history can exceed 4 MiB. Discard just this recognized
+              // top-level record incrementally, retaining heartbeats and later output.
+              const head = chunk.subarray(0, 512).toString('utf8')
+              if (options.provider === 'codex' && /^\s*\{\s*(?:"timestamp"\s*:\s*"[^"\r\n]*"\s*,\s*)?"type"\s*:\s*"compacted"\s*[,}]/.test(head)) {
+                skippingCompaction = true
+                cursor.offset += chunk.length
+                lastActivity = now()
+                state = 'working'
+                if (!suppressed(options.key)) emit({ kind: 'status', state: 'working', reasoning: 'Updating context' } as SessionStreamDraft)
+                return
+              }
               // HAND OFF, do not skip. `done` is the same terminal status a finished turn
               // sends, so the client already knows to close the stream and resume its
               // 5s/15s/60s poll -- no new client vocabulary, no frozen screen.

package/server/lib/session-work-observation.ts

@@ -0,0 +1,46 @@
+// Display-only evidence. Never decides whether a thread can be written or dequeued.
+import type { HookEnvelope } from './session-hook-events.js'
+import type { SubagentActivity } from './codex-subagent-activity.js'
+export interface WorkObservation {
+  agents: Array<{id:string;at:number;state:'active'|'completed'}>
+  partial: boolean
+  compactingAt: number | null
+  phaseAt?: number
+}
+export function observeWork(previous: WorkObservation | undefined, env: HookEnvelope): WorkObservation {
+  const prev=previous ?? {agents:[],partial:false,compactingAt:null}
+  if (!Number.isFinite(env.ts) || env.ts <= 0 || env.ts > Date.now()+5000) return prev
+  const p=env.payload, id=typeof p.agent_id==='string' && /^[a-zA-Z0-9_-]{1,160}$/.test(p.agent_id) ? p.agent_id : null
+  if(env.event==='SubagentStart'||env.event==='SubagentStop') {
+    if(!id)return {...prev,partial:true}
+    const existing=prev.agents.find(a=>a.id===id)
+    if(existing && (existing.at>env.ts || (existing.at===env.ts && (existing.state==='completed' || env.event==='SubagentStart'))))return prev
+    if(!existing && prev.agents.length>=512)return {...prev,partial:true}
+    const row={id,at:env.ts,state:env.event==='SubagentStart'?'active' as const:'completed' as const}
+    return {...prev,agents:[...prev.agents.filter(a=>a.id!==id),row]}
+  }
+  if(id && ['PreToolUse','PostToolUse','PostToolUseFailure'].includes(env.event)) {
+    const existing=prev.agents.find(a=>a.id===id)
+    // Tool output may arrive after Stop; it must never reopen a completed child.
+    if(existing?.state==='active' && env.ts>existing.at)return {...prev,agents:prev.agents.map(a=>a.id===id?{...a,at:env.ts}:a)}
+    return prev
+  }
+  if(id)return prev // Child compaction must not label the parent as compacting.
+  if(env.ts<(prev.phaseAt??0))return prev
+  if(env.event==='PreCompact')return {...prev,compactingAt:env.ts,phaseAt:env.ts}
+  const resumes=['PostCompact','UserPromptSubmit','Stop','StopFailure','SessionEnd','PostToolUse','PostToolUseFailure'].includes(env.event)
+    || (env.event==='SessionStart' && p.source==='compact')
+  if(resumes)return {...prev,compactingAt:null,phaseAt:env.ts}
+  return prev
+}
+export function workObservationFields(observation: WorkObservation | undefined, now=Date.now()): {subagent_activity?:SubagentActivity;compaction?:{state:'compacting'|'unknown';started_at:number;checked_at:number}} {
+  if(!observation)return {}
+  const fields:ReturnType<typeof workObservationFields>={}
+  if(observation.agents.length||observation.partial){
+    const summary:SubagentActivity={active:0,completed:0,unknown:0,total:observation.agents.length,checked_at:now,partial:observation.partial}
+    for(const a of observation.agents)summary[a.state==='completed'?'completed':now-a.at<=300_000&&a.at<=now+5000?'active':'unknown']++
+    fields.subagent_activity=summary
+  }
+  if(observation.compactingAt!==null)fields.compaction={state:now-observation.compactingAt<=600_000?'compacting':'unknown',started_at:observation.compactingAt,checked_at:now}
+  return fields
+}

package/server/lib/thread-attach-capability.ts

@@ -44,7 +44,8 @@
 // registered."
 //
 // `providers` is sourced from BINDABLE_PROVIDERS for the same reason. Cursor is
-// Continue-capable once bindable; Fork stays on FORKABLE_PROVIDERS (claude/codex).
+// Continue-capable once bindable; Fork reads FORKABLE_PROVIDERS (6.62.0: Cursor too, as a new
+// read-only session with context).
 // The way to guarantee the published list matches the attach route is to read
 // the list that `isBindableProvider` is built from, rather than restating names
 // here and hoping.
@@ -64,8 +65,10 @@
 
 import {
   BINDABLE_PROVIDERS,
+  FORKABLE_PROVIDERS,
   isBindableProvider,
   type BindableProvider,
+  type ForkableProvider,
 } from './agent-session-binding-store.js'
 import { threadAttachEnabled } from '../routes/agent-session-bindings.js'
 
@@ -98,6 +101,13 @@ export interface ThreadAttachCapability {
    * incoherent default: every refusal recommends Fork while the route 404s.
    */
   forkSupported: boolean
+  /**
+   * 6.62.0 (plan 3.7, W10): WHICH providers the fork route serves. `forkSupported` stays a
+   * boolean for every reader that already checks it with `=== true`; this list is new.
+   * Sourced from FORKABLE_PROVIDERS, the list `isForkableProvider` is built from. Cursor's
+   * entry is "New session with this context" (a new read-only chat), not a native fork.
+   */
+  forkProviders?: ForkableProvider[]
 }
 
 /**
@@ -129,6 +139,7 @@ export function threadAttachCapability(
     // byte-identical, so the flag protecting an existing conversation does not
     // apply. Gating it made every refusal recommend a route that 404s.
     forkSupported: THREAD_ATTACH_SUPPORTED,
+    forkProviders: THREAD_ATTACH_SUPPORTED ? [...FORKABLE_PROVIDERS] : [],
   }
 }
 
@@ -139,6 +150,8 @@ export interface ThreadAttachHealthFields {
   /** Fork is available whenever the build supports it, gate or no gate. */
   threadForkSupported: boolean
   threadAttachProviders: BindableProvider[]
+  /** 6.62.0: the providers the fork route serves (`threadForkSupported` stays the boolean). */
+  threadForkProviders: ForkableProvider[]
 }
 
 /** Flatten the capability onto the health payload's key names. */
@@ -150,6 +163,7 @@ export function threadAttachHealthFields(
     threadAttachEnabled: capability.enabled,
     threadAttachProviders: capability.providers,
     threadForkSupported: capability.forkSupported,
+    threadForkProviders: capability.forkSupported ? [...(capability.forkProviders ?? [])] : [],
   }
 }
 

package/server/lib/thread-drain-kick.ts

@@ -70,11 +70,13 @@ export type KickPlan = { kind: 'kick' } | { kind: 'kick_when_registry_idle'; sto
  *  - a SubagentStop never kicks: a background sub-agent finishing after the Stop is
  *    answered by the model in a turn of its own, whose Stop kicks, and neither the hook
  *    short-circuit nor the B6 clause vouches for a session whose newest event is a
- *    SubagentStop, so a kick there could only fall through to the 30 s backstop.
+ *    SubagentStop, so a kick there could only fall through to the 30 s backstop;
+ *  - 6.62.0: a Codex `Interrupt` ends a turn the way a Stop does (Esc in Codex fires no
+ *    Stop), so it follows the same rule; no Claude or Cursor hook emits it.
  */
 export function kickPlanFor(signal: KickSignalFacts, event: string, eventTs: number, child: boolean): KickPlan {
   if (child) return event === 'SessionEnd' ? { kind: 'kick' } : null
-  if (event !== 'Stop') return null
+  if (event !== 'Stop' && event !== 'Interrupt') return null
   if (signal.turnOpen || signal.subagentsOpen > 0 || signal.ended) return null
   return { kind: 'kick_when_registry_idle', stopAt: typeof signal.stopAt === 'number' ? signal.stopAt : eventTs }
 }

package/server/lib/thread-occupancy.ts

@@ -93,6 +93,14 @@ export interface Occupancy {
    * Absent (not false) on every other verdict, so `=== true` is the only test.
    */
   idleHolder?: true
+  /**
+   * 6.62.0 (plan 3.6, W8): attachable DESPITE a foreign owner that is WORKING, because the
+   * owner is the Codex app and the turn goes into that app's own queue (`codex queue`),
+   * which runs it at the end of the running turn. Never set by `threadOccupancy`: only the
+   * bindings route declares it, and only when the hop is wired, on, and COS holds no turn
+   * of its own for the thread. Same `=== true` contract as `idleHolder`.
+   */
+  busyHolder?: true
 }
 
 /**
@@ -191,8 +199,25 @@ export interface OccupancyProbes {
    * absent, null, or a throw keeps the 6.50 verdict (`unsupported_provider`).
    */
   cursorComposerTurnOpen?: (threadId: string) => boolean | null
+  /**
+   * 6.62.0 (W14): the newest write to a Cursor CLI chat (`store.db`, its WAL, or the agent
+   * transcript), epoch ms, or null. A `-p` run fires no turn hooks (canary C7), so file
+   * times are the only busy signal a CLI chat has, and a Run Everything Continue must not
+   * run at the same moment as the person's own terminal run. OPTIONAL; absent or null
+   * keeps the 6.61 verdict.
+   */
+  cursorChatLastWriteMs?: (chatDir: string, threadId: string) => number | null
+  /**
+   * 6.62.0 /qa (W7): does a process that is NOT COS hold this CLI chat's `store.db` open?
+   * True is positive evidence of a run (a terminal `agent`, a desk run quiet past 30 s).
+   * Null or a throw: cannot tell, and the 30 s write window alone decides.
+   */
+  cursorChatForeignHolder?: (chatDir: string) => boolean | null
 }
 
+/** 6.62.0 (W14): a CLI chat written this recently is working; a turn for it queues. */
+export const CURSOR_CHAT_BUSY_WINDOW_MS = 30_000
+
 /**
  * How recently the transcript must have been written for a held thread to read
  * as WORKING rather than merely OPEN.
@@ -637,6 +662,25 @@ export function threadOccupancy(
       }
       return { attachable: false, owners: [], reason: open === true ? 'native_thread_working' : 'unsupported_provider' }
     }
+    // 6.62.0 (W14): a CLI chat written in the last 30 s is mid-run, at the desk or by a
+    // COS child that just finished; a turn spoken at it waits rather than running
+    // alongside. A probe that throws or cannot tell keeps the 6.61 verdict.
+    let lastWrite: number | null = null
+    try {
+      lastWrite = typeof probes.cursorChatLastWriteMs === 'function' ? probes.cursorChatLastWriteMs(session.dir, threadId) : null
+    } catch {
+      lastWrite = null
+    }
+    if (typeof lastWrite === 'number' && Number.isFinite(lastWrite) && Date.now() - lastWrite < CURSOR_CHAT_BUSY_WINDOW_MS) {
+      return { attachable: false, owners: [], reason: 'native_thread_working' }
+    }
+    let held: boolean | null = null
+    try {
+      held = typeof probes.cursorChatForeignHolder === 'function' ? probes.cursorChatForeignHolder(session.dir) : null
+    } catch {
+      held = null
+    }
+    if (held === true) return { attachable: false, owners: [], reason: 'native_thread_working' }
     return { attachable: true, owners: [], reason: null }
   }
   if (provider !== 'claude' && provider !== 'codex') {

package/server/lib/thread-turn-queue-deliver.ts

@@ -34,7 +34,7 @@ const DELIVER_TIMEOUT_MS = 15_000
 
 interface LoopbackReply { status: number; body: Record<string, unknown> }
 
-function post(port: number, token: string, path: string, payload: unknown): Promise<LoopbackReply> {
+function post(port: number, token: string, path: string, payload: unknown, extraHeaders: Record<string, string> = {}): Promise<LoopbackReply> {
   return new Promise((resolve, reject) => {
     const data = JSON.stringify(payload)
     const req = request({
@@ -47,6 +47,7 @@ function post(port: number, token: string, path: string, payload: unknown): Prom
         'content-length': Buffer.byteLength(data),
         // The header the rest of COS authenticates with. NOT `Authorization: Bearer`.
         'X-Cos-Token': token,
+        ...extraHeaders,
       },
       timeout: DELIVER_TIMEOUT_MS,
     }, res => {
@@ -77,11 +78,14 @@ export async function deliverQueuedTurnOverLoopback(
   port: number,
   token: string,
 ): Promise<{ ok: boolean; reason?: string; serverRetryable?: boolean }> {
+  // 6.62.0 /qa (Q3): repeat the parking client's acknowledgement, and only that.
+  const noteHeaders: Record<string, string> = turn.continueNoteAck === true ? { 'X-COS-Continue-Note': '1' } : {}
   try {
     const attach = await post(
       port, token,
       `/api/agent-sessions/${encodeURIComponent(turn.provider)}/${encodeURIComponent(turn.threadId)}/attach`,
       { cosSessionId: turn.cosSessionId },
+      noteHeaders,
     )
     if (attach.status !== 200 && attach.status !== 201) {
       // THE KEY IS `reason`, NOT `error`. `refuseAttach` emits
@@ -117,6 +121,7 @@ export async function deliverQueuedTurnOverLoopback(
         targetKey: targetKey(turn.provider, turn.threadId),
         ...(boundTo ? { boundTo } : {}),
       },
+      noteHeaders,
     )
     if (sent.status === 202 || sent.status === 200) return { ok: true }
     // Same defect on the turn leg: `refuseTurn` emits `reason`/`reasonCopy`/`retryable`

package/server/lib/thread-turn-queue.ts

@@ -87,6 +87,12 @@ export interface QueuedThreadTurn {
   /** The SERVER's reason for a terminal outcome. Never the client's wording. */
   reason?: string
   settledAt?: number
+  /**
+   * 6.62.0 /qa (Q3): the client that parked this turn sent `X-COS-Continue-Note: 1` (it shows
+   * `continue_note`). The drain repeats the header, so a Cursor CLI chat runs Run Everything
+   * only for a client that said it would show it. Absent: the 6.61 Ask posture.
+   */
+  continueNoteAck?: true
 }
 
 /**

package/server/lib/turn-request.ts

@@ -0,0 +1,274 @@
+// The current-request binding for provider CLI spawns (P0 from the 2026-09-27 memory audit).
+//
+// WHY THIS EXISTS. The COS UserPromptSubmit hook (a Python script in the COS repo, run by
+// the Claude Code and Codex CLIs) builds its memory query from the prompt text the CLI hands
+// it. On a glasses turn that text is not the user's question: the Codex and Cursor bridges
+// send one concatenated "SYSTEM INSTRUCTIONS ... USER REQUEST ..." prompt, and the Claude
+// bridge still wraps the question in image preambles and attachment JSON. The hook then
+// embedded display rules, the calendar and standing tasks, and injected unrelated memories.
+//
+// THE CONTRACT (04_MVP_BUILD_SPEC.md, "Current-request contract", shared with the hook).
+// Per CLI spawn with a genuine user query, write
+//
+//   <data dir>/turn-requests/<turnId or uuid>.json      directory 0700, file 0600
+//   {"schema_version":1,"turn_id":"...","current_user_text":"...",
+//    "full_prompt_sha256":"...","created_at":"ISO"}
+//
+// and pass its absolute path to the child as COS_TURN_REQUEST_FILE. The hook uses
+// `current_user_text` only when sha256(hook_prompt.strip()) equals `full_prompt_sha256` and
+// the stripped text is a substring of the hook prompt; otherwise it uses the prompt exactly
+// as before. So a file that does not bind is harmless, and nothing here may fail a turn.
+//
+// THE HASH IS PYTHON'S strip(), NOT JS trim(). The two whitespace sets differ: Python also
+// strips U+001C..U+001F and U+0085, and JS also strips U+FEFF. A prompt ending in one of
+// those would never bind if the server hashed `prompt.trim()`. `stripLikePython` uses the
+// exact `str.isspace()` set (checked against python3 over every code point, 2026-09-29).
+//
+// PRIVACY. The user's text lives only in this private file, never in argv or the child env
+// (argv is world-readable through `ps`; env is readable by every descendant). The file is
+// deleted when the child exits, and anything older than an hour is swept.
+
+import { createHash, randomUUID } from 'node:crypto'
+import {
+  closeSync,
+  constants as fsConstants,
+  fchmodSync,
+  lstatSync,
+  mkdirSync,
+  chmodSync,
+  openSync,
+  readdirSync,
+  unlinkSync,
+  writeSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import { dataPath } from './data-dir.js'
+
+/** The child env key that carries the file path. The hook reads exactly this name. */
+export const TURN_REQUEST_ENV = 'COS_TURN_REQUEST_FILE'
+export const TURN_REQUEST_SCHEMA_VERSION = 1
+/** Files older than this are swept. No provider run outlives it: the longest wall cap is 20 min. */
+export const TURN_REQUEST_STALE_MS = 60 * 60_000
+/** The hook ignores a file of 64 KB or more, so one that large is never written. */
+export const TURN_REQUEST_MAX_BYTES = 64 * 1024
+const SWEEP_INTERVAL_MS = 10 * 60_000
+const DIR_NAME = 'turn-requests'
+/** A turn id is used as a file name only when it cannot escape or collide with the directory. */
+const SAFE_TURN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/
+
+/** Exactly the code points for which Python's `str.isspace()` is true. */
+const PY_SPACE = '\\u0009-\\u000d\\u001c-\\u0020\\u0085\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000'
+const PY_STRIP = new RegExp(`^[${PY_SPACE}]+|[${PY_SPACE}]+$`, 'gu')
+
+/** Python's `str.strip()` with no arguments. */
+export function stripLikePython(text: string): string {
+  return text.replace(PY_STRIP, '')
+}
+
+/** Lowercase hex sha256 of the prompt as the hook will see it: UTF-8, Python-stripped. */
+export function turnPromptSha256(prompt: string): string {
+  return createHash('sha256').update(stripLikePython(prompt), 'utf8').digest('hex')
+}
+
+export function turnRequestDir(): string {
+  return dataPath(DIR_NAME)
+}
+
+export interface TurnRequestBinding {
+  /** Absolute path of the private file. */
+  readonly path: string
+  readonly turnId: string
+  /** Delete the file. Idempotent and never throws. */
+  release(): void
+}
+
+let lastSweepAt = 0
+
+/**
+ * Delete turn-request files older than `TURN_REQUEST_STALE_MS`. Runs at server startup and
+ * again from `createTurnRequestBinding` at most every ten minutes, so a file whose child
+ * never reported an exit (or a crash between write and spawn) cannot outlive an hour and a
+ * turn. Returns how many files it removed. Never throws.
+ */
+export function sweepStaleTurnRequests(nowMs: number = Date.now()): number {
+  lastSweepAt = nowMs
+  const dir = turnRequestDir()
+  let names: string[]
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return 0
+  }
+  let removed = 0
+  for (const name of names) {
+    if (!name.endsWith('.json')) continue
+    const file = join(dir, name)
+    try {
+      const st = lstatSync(file)
+      if (!st.isFile() && !st.isSymbolicLink()) continue
+      if (nowMs - st.mtimeMs <= TURN_REQUEST_STALE_MS) continue
+      unlinkSync(file)
+      removed += 1
+    } catch { /* raced with a release, or unreadable: leave it */ }
+  }
+  return removed
+}
+
+/** Ensure the private directory: a real directory (never a symlink), mode 0700. */
+function ensurePrivateDir(dir: string): void {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const st = lstatSync(dir)
+  if (!st.isDirectory() || st.isSymbolicLink()) throw new Error('turn-requests is not a directory')
+  if ((st.mode & 0o777) !== 0o700) chmodSync(dir, 0o700)
+}
+
+/**
+ * Create `path` exclusively with mode 0600 and write `body`. O_EXCL refuses an existing path
+ * of any kind, a planted symlink or FIFO included (POSIX: with O_CREAT|O_EXCL a symlink is
+ * never followed), so nothing is ever written through a link or over another turn's file.
+ * O_NOFOLLOW and O_NONBLOCK repeat that on the open line itself, as the server's hazard
+ * invariants require of every synchronous open (hazard-invariants.test.ts).
+ */
+function writePrivateFile(path: string, body: string): void {
+  const fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK, 0o600)
+  let ok = false
+  try {
+    // The umask can only remove bits, but set it explicitly so the contract does not rest on it.
+    fchmodSync(fd, 0o600)
+    const bytes = Buffer.from(body, 'utf8')
+    let written = 0
+    while (written < bytes.length) written += writeSync(fd, bytes, written, bytes.length - written)
+    ok = true
+  } finally {
+    closeSync(fd)
+    if (!ok) {
+      try { unlinkSync(path) } catch { /* best effort */ }
+    }
+  }
+}
+
+/**
+ * Write the turn-request file for ONE provider spawn, or return null.
+ *
+ * `userText` is the raw user query as the bridge received it, before any header, context,
+ * image preamble or attachment block. `prompt` is the exact text the CLI will receive as the
+ * user message (stdin), byte for byte.
+ *
+ * Null (and no file) when there is no genuine user query (empty or whitespace only, as for a
+ * pre-warm or an image with no words), when the text is not inside the prompt (the hook
+ * could never bind it), when the file would reach the hook's 64 KB limit, or on any
+ * filesystem failure. The binding is an optimisation for memory retrieval: it must never
+ * fail or delay the turn, so every failure is logged once and swallowed.
+ */
+export function createTurnRequestBinding(input: {
+  userText: string
+  prompt: string
+  turnId?: string
+  now?: () => Date
+}): TurnRequestBinding | null {
+  const userText = typeof input.userText === 'string' ? input.userText : ''
+  const stripped = stripLikePython(userText)
+  if (!stripped) return null
+  if (typeof input.prompt !== 'string' || !input.prompt.includes(stripped)) return null
+
+  const now = input.now?.() ?? new Date()
+  const turnId = typeof input.turnId === 'string' && SAFE_TURN_ID.test(input.turnId)
+    ? input.turnId
+    : randomUUID()
+  const record = {
+    schema_version: TURN_REQUEST_SCHEMA_VERSION,
+    turn_id: turnId,
+    current_user_text: userText,
+    full_prompt_sha256: turnPromptSha256(input.prompt),
+    created_at: now.toISOString(),
+  }
+  const body = JSON.stringify(record)
+  if (Buffer.byteLength(body, 'utf8') >= TURN_REQUEST_MAX_BYTES) return null
+
+  try {
+    const dir = turnRequestDir()
+    ensurePrivateDir(dir)
+    if (lastSweepAt === 0 || now.getTime() - lastSweepAt >= SWEEP_INTERVAL_MS) {
+      sweepStaleTurnRequests(now.getTime())
+    }
+    let path = join(dir, `${turnId}.json`)
+    try {
+      writePrivateFile(path, body)
+    } catch (error: any) {
+      // A retried turn can reuse its id while the earlier child still holds its file.
+      // Never overwrite it: that child's exit would delete this one's file.
+      if (error?.code !== 'EEXIST') throw error
+      path = join(dir, `${randomUUID()}.json`)
+      writePrivateFile(path, body)
+    }
+    let released = false
+    return {
+      path,
+      turnId,
+      release() {
+        if (released) return
+        released = true
+        try { unlinkSync(path) } catch { /* already gone */ }
+      },
+    }
+  } catch (error) {
+    console.error('[turn-request] binding unavailable:', error instanceof Error ? error.message : error)
+    return null
+  }
+}
+
+/** The minimal child surface this needs; a real ChildProcess satisfies it. */
+interface ExitObservable {
+  readonly pid?: number
+  once(event: 'exit' | 'close', listener: (...args: any[]) => void): unknown
+  once(event: 'error', listener: (error: Error) => void): unknown
+}
+
+/**
+ * Delete the binding's file when the child is gone, on every path: a normal exit, a kill
+ * (timeout, abort, lost ownership), and a spawn failure. Node reports a spawn failure as
+ * 'error' with no pid, then 'close'; an exited child always reports 'exit' and 'close'. An
+ * 'error' on a child that DID start (a failed kill) is not an exit, so it keeps the file.
+ */
+export function releaseTurnRequestOnExit(child: ExitObservable, binding: TurnRequestBinding | null): void {
+  if (!binding) return
+  child.once('exit', () => binding.release())
+  child.once('close', () => binding.release())
+  child.once('error', () => {
+    if (child.pid === undefined) binding.release()
+  })
+}
+
+/**
+ * Spawn through `start` and tie the binding's file to the child's lifetime. A synchronous
+ * spawn throw deletes the file before rethrowing, so no path can leave it behind.
+ */
+export function spawnWithTurnRequest<T extends ExitObservable>(
+  binding: TurnRequestBinding | null,
+  start: () => T,
+): T {
+  let child: T
+  try {
+    child = start()
+  } catch (error) {
+    binding?.release()
+    throw error
+  }
+  releaseTurnRequestOnExit(child, binding)
+  return child
+}
+
+/**
+ * Point the child env at this spawn's file, and never at an inherited one. A server started
+ * from inside an agent session could carry the variable, and a stale path must not reach a
+ * hook even though the hash check would reject it.
+ */
+export function applyTurnRequestEnv(env: NodeJS.ProcessEnv, binding: TurnRequestBinding | null): void {
+  delete env[TURN_REQUEST_ENV]
+  if (binding) env[TURN_REQUEST_ENV] = binding.path
+}
+
+/** Test seam: forget the sweep clock so a test can observe the first-use sweep. */
+export function resetTurnRequestSweepForTests(): void {
+  lastSweepAt = 0
+}