@gotcos/glasses-server 6.36.8 → 6.36.10

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 ## Unreleased
 
+## 6.36.10
+- **A fenced thread had no exit and left no trace.** An ambiguous delivery fences the
+  target so a prompt cannot be double-delivered into a real conversation — that is
+  correct and stays. Everything around it was wrong: the fence lived in a process-local
+  Map, wrote no log line at either site, had no list, and had no release. It was
+  discoverable only by being refused, and the only thing that cleared it was a restart.
+- **Now listable and releasable without a restart.** `GET /api/agent-sessions/fences`
+  lists them; `POST /api/agent-sessions/fences/release` clears one. Addressed by DIGEST,
+  never by raw target key — the key embeds the private native thread id. Fails closed:
+  without `confirm: true` it returns 400 with a preview of what would be reopened. That
+  confirmation is a deliberate second call, NOT proof a human looked — the API token is
+  shared by the phone, the lens and every COS agent session, so nothing is structurally
+  prevented from asserting it. The comment says so rather than overclaiming.
+- **Durable storage ships INERT, behind `COS_THREAD_FENCE_DURABLE=1`, default off.**
+  Persisting the fence is the right direction, but durability without a reachable
+  release is a regression, not a fix: today "Restart Server" in COS Control clears a
+  fence, and making it survive restarts with no operator surface in Control would turn
+  an 8-second annoyance into a permanently dead thread needing a terminal. The flag
+  flips on when COS Control has a Fences card. The routes above already remove the
+  restart from the recovery path.
+- **A write can never erase what it could not read.** `TargetGuard` hydrates only the
+  rows it understood and saves its map wholesale, so a single unrecognised row — a
+  newer schema, a partial write, one bad field — would otherwise be erased by the next
+  fence on an unrelated thread, silently reopening every other fenced thread. Writes now
+  merge unrecognised rows back through. A corrupt file is quarantined to
+  `.corrupt-<ts>` rather than dropped, and uses `durableAtomicWriteFileSync` (fsync of
+  bytes, metadata and directory; randomized exclusive temp name) rather than the
+  lightweight cache writer.
+- **A release is persisted before it is reported.** Mutating memory first and reporting
+  success meant an operator could be told a thread was open, write to it, and find it
+  fenced again after the next restart with no record of why. A failed write now returns
+  500 `persist_failed` and the fence holds. `GET /fences` reports `degraded` when the
+  last write failed — a memory-only fence set is otherwise indistinguishable from a
+  durable one until the process restarts.
+- **Visible.** Breadcrumbs at both fence-set sites (tagged `ambiguous` vs `route_error`)
+  and both fence-hit routes (turn, attach). No raw target key in any of them. The
+  route_error line reports the hoisted pre-turn head rather than hardcoding
+  `unavailable`, which contradicted the record it had just written.
+- **Known, not fixed here:** releasing a fence does not by itself make the thread
+  attachable — the turn that fenced it left a binding holding the target for its
+  30-minute TTL, so the next attach refuses `native_target_busy`. There is no detach
+  route. `/attachability` still does not consult the fence, so the lens menu renders
+  Continue enabled on a fenced thread; the refusal is honest, the menu is not yet.
+- **Coverage.** 11 mutations against the new guards fail the suite, including all four
+  that survived the first QA pass (the release handle check, and the provider/reason/
+  fencedAt row validators). One documented survivor remains: removing the write-once
+  guard on `fence()`, which no route can reach because both fence sites sit inside the
+  `tryClaim` section. The code says so at the call site.
+
+## 6.36.9
+- **The queue gate can now see COS's own bindings, which closes a 30-minute lockout.**
+  `threadOccupancy` sees FOREIGN holders only — `OccupancyReason` has no
+  `native_target_busy`, because that refusal comes from the binding registry. So when a
+  live COS binding held a thread, Continue refused `native_target_busy`, the client
+  armed the queue, and this gate answered `409 thread_free` ("Pick Continue again"),
+  which refused identically. A closed loop for the whole binding TTL, while the refusal
+  copy said "detach that one first" — an action with no endpoint.
+- The same gap burnt the delivery ceiling: the drainer saw `attachable`, ATTEMPTED, and
+  the attach route refused. Five of those retired a turn in about two minutes. With the
+  binding visible, `drainDecision` returns `hold` and spends nothing — one change closes
+  both the loop and the burn.
+- **A gate refusal no longer spends an attempt.** Classified by REASON, never by status:
+  every refusal that is not `invalid_request` (400) or a capability gap (503) comes back
+  409, so a status rule would have retried `native_target_fenced` — "an earlier turn may
+  or may not have been delivered" — up to 1,080 times. Reuses `queueableRefusal`, and
+  fails CLOSED on an unrecognised reason.
+- The attempt is still written and fsynced BEFORE the call, then REFUNDED once the
+  outcome is known. Deferring the increment would have reopened the crash-safety hole
+  the comment there describes, and a test reads `attempts` off disk mid-delivery to
+  prove it.
+- **The refusal reason is no longer discarded.** `deliver` read `body.error`; the attach
+  route emits `reason` and has never emitted `error`, so every stored reason in the
+  field was the literal `attach_409` and the whole feature was reason-blind. Also
+  carries the turn route's own `retryable` verdict, which outranks our inference.
+
+
 ## 6.36.8
 - **The queue now covers the refusal that actually fires.** Device diagnostics, once the
   path was finally instrumented, recorded `native_target_busy` on every Continue that

package/package.json

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

package/server/index.ts

@@ -109,6 +109,7 @@ import { createThreadTurnQueueRouter, drainAllThreads } from './routes/thread-tu
 import { transcriptTurnEnded } from './lib/thread-turn-queue-store.js'
 import { transcriptPathFor } from './lib/native-head.js'
 import { deliverQueuedTurnOverLoopback } from './lib/thread-turn-queue-deliver.js'
+import { readFences, writeFences } from './lib/thread-fence-store.js'
 import type { QueuedThreadTurn } from './lib/thread-turn-queue.js'
 
 const PORT = parseInt(process.env.PORT ?? '3141', 10)
@@ -517,10 +518,33 @@ app.use('/api', claudeSessionsRouter)
 // buys the guarantee that the queue CANNOT weaken the gate even by accident.
 if (threadAttachEnabled()) {
   const queueDeps = {
+    // TWO GATES, ONE ANSWER. `threadOccupancy` sees FOREIGN holders -- another app on
+    // the Mac writing the transcript. It does not, and cannot, see COS's OWN bindings:
+    // `OccupancyReason` has no `native_target_busy` member, because that refusal is
+    // produced only by the binding registry inside `bindings.create`.
+    //
+    // That gap is what trapped Miles on 2026-08-18. Continue refused
+    // `native_target_busy` (a live COS binding held the thread), the client armed the
+    // queue, he dictated -- and this gate, asking occupancy alone, answered
+    // `attachable: true`, so the route replied `409 thread_free` ("Pick Continue again
+    // to send it"). Continue refused identically. A closed loop for the 30-minute
+    // binding TTL, with the refusal copy telling him to "detach that one first" -- an
+    // action with no endpoint.
+    //
+    // It also burnt the delivery ceiling: the drainer saw `attachable` and ATTEMPTED,
+    // the attach route refused, and five of those retired the turn in ~2 minutes. With
+    // the binding visible here, `drainDecision` returns 'hold' instead and no attempt
+    // is spent -- so this single change closes the loop AND the attempt burn.
     occupancy: (provider: string, threadId: string) => {
       try {
         const v = threadOccupancy(provider, threadId, occupancyProbes, occupancyDirs)
-        return { attachable: v.attachable === true, reason: v.reason ?? null }
+        if (v.attachable !== true) return { attachable: false, reason: v.reason ?? null }
+        // Occupancy is happy; ask the registry the question it cannot answer.
+        // `getByThread` returns the binding ONLY when it actually blocks the target
+        // (`blocksTarget`), so an expired or terminal one correctly reads as free.
+        const holder = agentSessionBindingRegistry.getByThread(provider, threadId, Date.now())
+        if (holder !== null) return { attachable: false, reason: 'native_target_busy' }
+        return { attachable: true, reason: null }
       } catch {
         // A throwing probe is not an open door.
         return { attachable: false, reason: 'probe_failed' }
@@ -559,6 +583,23 @@ if (threadAttachEnabled()) {
 }
 
 app.use('/api', createAgentSessionBindingsRouter({
+  // Durable fences (6.36.10), OFF BY DEFAULT.
+  //
+  // The fence is the one piece of state whose loss writes twice into a real
+  // conversation, so persisting it is the right direction. But durability
+  // without a reachable release is a REGRESSION, not a fix: today "Restart
+  // Server" in COS Control clears a fence, and making it survive restarts with
+  // no operator surface in Control turns an 8-second annoyance into a
+  // permanently dead thread that needs a terminal to clear. Miles, 2026-08-12:
+  // "we couldn't do anything without bash, that shouldn't be the case."
+  //
+  // So the storage ships inert. GET /agent-sessions/fences and
+  // POST /agent-sessions/fences/release work either way — which already removes
+  // the restart from the recovery path — and this flag flips on once COS Control
+  // has a Fences card.
+  fencePersistence: process.env.COS_THREAD_FENCE_DURABLE === '1'
+    ? { load: readFences, save: writeFences }
+    : undefined,
   probes: occupancyProbes,
   dirs: occupancyDirs,
   now: () => Date.now(),

package/server/lib/thread-fence-store.ts

@@ -0,0 +1,102 @@
+// Durable storage for target fences.
+//
+// A fence shuts a native thread that may already hold an undelivered COS turn. It
+// is the one piece of state whose LOSS writes twice into a real human conversation
+// — agent-session-binding-registry.ts records the incident verbatim: "the
+// process-local fence re-opened on restart and delivered a second copy."
+//
+// SEPARATE FROM THE DECISIONS, matching thread-turn-queue-store.ts: TargetGuard
+// holds the rules and takes load/save as injected callbacks, so its behaviour stays
+// testable in memory and only production touches the disk.
+//
+// UNDER THE DATA HOME, never the generation directory, which Update Server replaces
+// wholesale. Same lesson as the stranded voice profiles.
+//
+// NEVER TTL'd AND NEVER EVICTED. `heads` and fork refs both bound their maps, and
+// both evict in the SAFE direction — losing a head asks the user to acknowledge,
+// losing a fork ref makes them find the thread by hand. Losing a fence silently
+// reopens a thread that may hold an undelivered turn, so the only way an entry
+// leaves this file is an explicit operator release.
+
+import { durableAtomicWriteFileSync, loadJsonOrQuarantine } from './atomic-fs.js'
+import { dataPath } from './data-dir.js'
+
+export interface FenceRecord {
+  /** The raw target key. On disk only — it embeds the private native thread id and
+   *  is never emitted by any route. Callers outside this module use the digest. */
+  targetKey: string
+  provider: string
+  reason: string
+  /** The head digest as it stood BEFORE the ambiguous turn. Null ONLY when the
+   *  failure happened before the head was read — `head` is scoped to the try, so
+   *  the route-error site reads a hoisted copy rather than nothing. */
+  headBefore: string | null
+  turnId: string
+  bindingId: string | null
+  fencedAt: number
+}
+
+export function fencePath(): string {
+  return dataPath('thread-fences.json')
+}
+
+function isFenceRecord(r: unknown): r is FenceRecord {
+  return !!r && typeof r === 'object'
+    && typeof (r as FenceRecord).targetKey === 'string' && (r as FenceRecord).targetKey.length > 0
+    && typeof (r as FenceRecord).provider === 'string'
+    && typeof (r as FenceRecord).reason === 'string'
+    && typeof (r as FenceRecord).fencedAt === 'number'
+}
+
+/** The raw array on disk, or [] when the file is missing or was quarantined. */
+function rawRows(): unknown[] {
+  const loaded = loadJsonOrQuarantine<unknown>(fencePath())
+  if (loaded.status === 'corrupt') {
+    // Quarantined to `<path>.corrupt-<ts>` rather than discarded: the bytes are
+    // the only record of which threads were fenced, and this is the one state
+    // whose silent loss double-writes a real conversation.
+    console.warn(`[thread-fence-store] fence file was corrupt, quarantined as ${loaded.quarantinedAs}`)
+    return []
+  }
+  if (loaded.status !== 'ok') return []
+  if (!Array.isArray(loaded.data)) {
+    console.warn('[thread-fence-store] fence file is not an array — treating as empty')
+    return []
+  }
+  return loaded.data
+}
+
+/**
+ * Every stored fence this build can understand.
+ *
+ * A missing or corrupt file reads as empty. That fails OPEN, deliberately:
+ * failing closed would refuse every thread on the machine with no way back,
+ * while failing open is exactly the pre-6.36.10 behaviour (the fence was
+ * process-local and died on restart), so it cannot be a regression. A corrupt
+ * file is quarantined rather than dropped, so the evidence survives.
+ */
+export function readFences(): FenceRecord[] {
+  return rawRows().filter(isFenceRecord)
+}
+
+/**
+ * Replace the stored set, PRESERVING rows this build could not validate.
+ *
+ * THE MERGE IS THE WHOLE POINT. `TargetGuard` holds only the rows `readFences`
+ * understood and saves its map wholesale, so without this a single unrecognised
+ * row — a newer schema, a partial write, one bad field — would be erased by the
+ * next fence on an unrelated thread, silently reopening every other fenced
+ * thread. Preserved rows are inert (nothing enforces a fence that is not in the
+ * map) but they are never destroyed by a write that did not understand them.
+ *
+ * Uses the DURABLE writer, not the lightweight one: fsync of bytes, metadata and
+ * directory, plus a randomized exclusive temp name so two independent writers
+ * cannot share `<path>.tmp`.
+ */
+export function writeFences(rows: FenceRecord[]): void {
+  const preserved = rawRows().filter(r => !isFenceRecord(r))
+  if (preserved.length > 0) {
+    console.warn(`[thread-fence-store] preserving ${preserved.length} unrecognised fence row(s) through this write`)
+  }
+  durableAtomicWriteFileSync(fencePath(), `${JSON.stringify([...rows, ...preserved], null, 2)}\n`)
+}

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

@@ -75,7 +75,7 @@ export async function deliverQueuedTurnOverLoopback(
   turn: QueuedThreadTurn,
   port: number,
   token: string,
-): Promise<{ ok: boolean; reason?: string }> {
+): Promise<{ ok: boolean; reason?: string; serverRetryable?: boolean }> {
   try {
     const attach = await post(
       port, token,
@@ -83,8 +83,17 @@ export async function deliverQueuedTurnOverLoopback(
       { cosSessionId: turn.cosSessionId },
     )
     if (attach.status !== 200 && attach.status !== 201) {
-      // The gate said no at drain time. Not an error -- the queue holds and tries again.
-      return { ok: false, reason: String(attach.body.error ?? `attach_${attach.status}`) }
+      // THE KEY IS `reason`, NOT `error`. `refuseAttach` emits
+      // `{ attached: false, reason, reasonCopy }` and has never emitted an `error`
+      // key, so reading `body.error` always fell through to the status fallback and
+      // every stored reason in the field was the literal string `attach_409`.
+      //
+      // That made the whole feature reason-blind: 409 is the DEFAULT status for every
+      // refusal that is not `invalid_request` (400) or a capability gap (503), so
+      // `attach_409` covered transient `native_target_busy` and permanent
+      // `native_target_fenced` alike. Any retry policy keyed on the status would have
+      // treated "an earlier turn may or may not have been delivered" as retryable.
+      return { ok: false, reason: String(attach.body.reason ?? attach.body.error ?? `attach_${attach.status}`) }
     }
     const bindingId = typeof attach.body.bindingId === 'string' ? attach.body.bindingId : ''
     if (!bindingId) return { ok: false, reason: 'attach_no_binding' }
@@ -99,7 +108,14 @@ export async function deliverQueuedTurnOverLoopback(
     )
     // 202 is the success shape: admitted, delivered in the background, poll the ledger.
     if (sent.status === 202 || sent.status === 200) return { ok: true }
-    return { ok: false, reason: String(sent.body.error ?? `turn_${sent.status}`) }
+    // Same defect on the turn leg: `refuseTurn` emits `reason`/`reasonCopy`/`retryable`
+    // and no `error`. `retryable` is the server's OWN judgement about this refusal --
+    // carried through rather than re-derived, so the two layers cannot disagree.
+    return {
+      ok: false,
+      reason: String(sent.body.reason ?? sent.body.error ?? `turn_${sent.status}`),
+      serverRetryable: typeof sent.body.retryable === 'boolean' ? sent.body.retryable : undefined,
+    }
   } catch (error) {
     return { ok: false, reason: error instanceof Error ? error.message : 'deliver_failed' }
   }

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

@@ -94,6 +94,7 @@
 // does not — a future remount above the parser — the POST routes see a non-object
 // and answer 400. They never treat an unparsed body as an empty one.
 
+import type { FenceRecord } from '../lib/thread-fence-store.js'
 import { Router, type Request, type Response } from 'express'
 import { createHash, randomUUID } from 'node:crypto'
 import {
@@ -268,6 +269,12 @@ export type AttachedTurnResult =
   | { ok: boolean; delivery: 'not_attempted' | 'aborted' | 'ambiguous' | 'delivered' }
 
 export interface AgentSessionBindingsDeps {
+  /**
+   * Durable fence storage. OPTIONAL, and omitting it is what keeps the existing
+   * suite in memory: a test that silently began writing the real data home would
+   * leak fences between cases and into the running server. Production wires it.
+   */
+  fencePersistence?: FencePersistence
   probes: OccupancyProbes
   dirs: OccupancyDirs
   /** Epoch ms. Injected so lease expiry is decidable in a test without waiting. */
@@ -829,24 +836,86 @@ export const MAX_TRACKED_HEADS = 512
 /** A COS session id may contain ':' and '/', which is exactly why it is never projected. */
 export const COS_SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/
 
+/** What a fence records about the turn that set it. */
+export interface FenceEvidence {
+  provider: string
+  /** The head BEFORE the ambiguous turn. Null ONLY when the failure happened
+   *  before the head was read. */
+  headBefore: string | null
+  turnId: string
+  bindingId: string | null
+  now: number
+}
+
+export type ReleaseOutcome =
+  | { ok: true; row: FenceRecord }
+  | { ok: false; reason: 'unknown_fence' | 'persist_failed' }
+
+/** Injected so TargetGuard stays testable in memory; production wires the store. */
+export interface FencePersistence {
+  load: () => FenceRecord[]
+  save: (rows: FenceRecord[]) => void
+}
+
 /**
- * The in-process half of plan 4.5 and 4.6: one COS turn per native target, and a
- * target that may already hold an undelivered turn stays shut.
+ * One COS turn per native target, and a target that may already hold an
+ * undelivered turn stays shut.
  *
- * NOT DURABLE, AND THAT IS A STATED GAP. Plan 4.5 wants the reservation
- * persisted in the job journal and rehydrated on boot, and 4.6 item 3 wants the
- * fence to have its own lifecycle and an operator release path. Both belong to
- * Phase 2, which owns that journal. What lives here is the process-lifetime
- * version, which is enough to make the two properties true for a running server
- * and fails in the safe direction on restart: a claim is released (no turn is
- * running after a restart anyway) and a FENCE is lost, which is the one that
- * matters and is why it is called out rather than implied.
+ * CLAIMS ARE PROCESS-LOCAL; FENCES ARE DURABLE (6.36.10). The two states fail in
+ * opposite directions, which is why only one of them is persisted. Losing a claim
+ * on restart is safe — no turn is running after a restart anyway. Losing a FENCE
+ * reopens a thread that may already hold an undelivered turn, and the binding
+ * registry records what that cost: "the process-local fence re-opened on restart
+ * and delivered a second copy." So fences are written through to disk and
+ * rehydrated in the constructor, and the ONLY way one leaves the map is an
+ * explicit operator release (`releaseFence`).
+ *
+ * Persistence is INJECTED rather than imported. A test that silently began writing
+ * the real data home would leak fences between cases and into the running server,
+ * so the suite runs with `null` and stays in memory.
  */
 class TargetGuard {
   /** targetKey -> turnId of the single COS turn allowed to be in flight. */
   private readonly claims = new Map<string, string>()
-  /** targetKey -> why no further turn may be delivered. */
-  private readonly fences = new Map<string, WriteRefusal>()
+  /** targetKey -> the fence record. DURABLE as of 6.36.10: persistence is injected
+   *  so tests stay in memory and only production touches the data home. */
+  private readonly fences = new Map<string, FenceRecord>()
+  private readonly persistence: FencePersistence | null
+  private persistDegraded = false
+
+  constructor(persistence: FencePersistence | null = null) {
+    this.persistence = persistence
+    if (persistence === null) return
+    // Rehydrate BEFORE the router serves. A fence that died on restart is exactly
+    // how a second copy of a turn reached a real transcript.
+    try {
+      for (const row of persistence.load()) this.fences.set(row.targetKey, row)
+    } catch (error) {
+      console.error(`[agent-session-bindings] fence rehydrate failed: ${error instanceof Error ? error.message : error}`)
+    }
+  }
+
+  /** True when the durable write succeeded (or there is nothing to persist to). */
+  private persistFences(rows: FenceRecord[]): boolean {
+    if (this.persistence === null) return true
+    try {
+      this.persistence.save(rows)
+      this.persistDegraded = false
+      return true
+    } catch (error) {
+      // The in-memory fence still holds for this process, so the thread stays shut
+      // NOW; what is lost is survival across a restart. Loud, and surfaced on
+      // GET /fences — a silent fallback is indistinguishable from working.
+      this.persistDegraded = true
+      console.error(`[agent-session-bindings] fence persist FAILED (fences hold in memory only): ${error instanceof Error ? error.message : error}`)
+      return false
+    }
+  }
+
+  /** Whether the last durable write failed. Reported, never inferred. */
+  degraded(): boolean {
+    return this.persistDegraded
+  }
   /** bindingId -> the head digest this binding is currently reconciled to. */
   private readonly heads = new Map<string, string>()
 
@@ -869,12 +938,72 @@ class TargetGuard {
     if (this.claims.get(targetKey) === turnId) this.claims.delete(targetKey)
   }
 
-  fence(targetKey: string, reason: WriteRefusal): void {
-    if (!this.fences.has(targetKey)) this.fences.set(targetKey, reason)
+  /**
+   * Write-once: the FIRST reason wins, so a later ambiguity cannot overwrite the
+   * evidence chain of an unresolved one.
+   *
+   * DEFENSIVE, AND UNVERIFIED BY EXECUTION. Both fence sites sit inside the
+   * `tryClaim` section, which serialises them per target, and a fenced target is
+   * refused at the check before it can reach either site again — so no route can
+   * currently fence the same key twice, and a mutation removing this guard passes
+   * the whole suite. It is kept because the one path that could reach it (the
+   * ambiguous site fences, then the response throws into the catch, which fences
+   * `claimedKey` again) would otherwise replace a record carrying `bindingId` with
+   * one carrying null. Do not read the passing suite as coverage of this line.
+   */
+  fence(targetKey: string, reason: WriteRefusal, evidence: FenceEvidence): void {
+    if (this.fences.has(targetKey)) return
+    this.fences.set(targetKey, {
+      targetKey,
+      provider: evidence.provider,
+      reason,
+      headBefore: evidence.headBefore,
+      turnId: evidence.turnId,
+      bindingId: evidence.bindingId,
+      fencedAt: evidence.now,
+    })
+    this.persistFences([...this.fences.values()])
   }
 
   fencedReason(targetKey: string): WriteRefusal | null {
-    return this.fences.get(targetKey) ?? null
+    const row = this.fences.get(targetKey)
+    return row === undefined ? null : (row.reason as WriteRefusal)
+  }
+
+  /** Every fence, REDACTED for the wire: the raw targetKey embeds the private
+   *  native thread id, so callers address a fence by its deterministic digest. */
+  listFences(): Array<{ target: string; provider: string; reason: string; headBefore: string | null; turnId: string; fencedAt: number }> {
+    return [...this.fences.values()].map(row => ({
+      target: opaqueRevision(row.targetKey),
+      provider: row.provider,
+      reason: row.reason,
+      headBefore: row.headBefore,
+      turnId: row.turnId,
+      fencedAt: row.fencedAt,
+    }))
+  }
+
+  /**
+   * The operator release. THE ONLY WAY A FENCE LEAVES THIS MAP.
+   *
+   * Addressed by digest, never by raw target key. Returns false when no fence
+   * matches, so a stale handle reports honestly instead of silently succeeding.
+   */
+  releaseFence(targetDigest: string): ReleaseOutcome {
+    for (const [key, row] of this.fences) {
+      // THE authority on which fence a handle names. The route also looks the row
+      // up for its preview, but the release decision is made here — a duplicate
+      // lookup upstream would leave this comparison enforced by nothing.
+      if (opaqueRevision(row.targetKey) !== targetDigest) continue
+      // PERSIST FIRST. Reporting a release that was not durably recorded is how an
+      // operator is told a thread is open, writes to it, and finds it fenced again
+      // after the next restart with no record of why.
+      const remaining = [...this.fences.values()].filter(r => r.targetKey !== key)
+      if (!this.persistFences(remaining)) return { ok: false, reason: 'persist_failed' }
+      this.fences.delete(key)
+      return { ok: true, row }
+    }
+    return { ok: false, reason: 'unknown_fence' }
   }
 
   /**
@@ -1135,7 +1264,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
   const canListBindings = bindingDepsUsable(deps)
   const canWriteBindings = bindingWriteDepsUsable(deps)
   const detect = deps?.occupancy ?? threadOccupancy
-  const guard = new TargetGuard()
+  const guard = new TargetGuard(deps.fencePersistence ?? null)
   const ownership = deps?.ownership ?? { record: recordCosSpawn, release: releaseCosSpawn }
   // One per router. Injectable so the follow-on (attach accepting a `forkRef`)
   // shares this instance rather than standing up a second, disconnected one.
@@ -1216,6 +1345,54 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     }
   }
 
+  // ------------------------------------------------------------------ fences
+  //
+  // Mounted BEFORE the parameterised routes so `fences` can never be read as a
+  // provider. Both are operator surfaces: a fenced thread was previously
+  // discoverable only by trying to use it and being refused.
+  //
+  // A fence is addressed by DIGEST. The raw target key embeds the private native
+  // thread id, and the redaction contract at the top of this file is absolute.
+
+  router.get('/agent-sessions/fences', (_req, res) => {
+    // A fence list is a liveness answer; a cached one is worse than none.
+    res.set('Cache-Control', 'private, no-store')
+    // `degraded` is reported, never inferred: a memory-only fence set behaves
+    // identically to a durable one until the process restarts, so a silent
+    // fallback would be indistinguishable from working.
+    res.json({ fences: guard.listFences(), degraded: guard.degraded() })
+  })
+
+  router.post('/agent-sessions/fences/release', (req, res) => {
+    const body = (req.body ?? {}) as { target?: unknown; confirm?: unknown }
+    const target = body.target
+    if (typeof target !== 'string' || target.length === 0 || target.length > 256) {
+      res.status(400).json({ released: false, reason: 'invalid_request' })
+      return
+    }
+    res.set('Cache-Control', 'private, no-store')
+    if (body.confirm !== true) {
+      // FAILS CLOSED, like every other destructive COS call. NOTE WHAT THIS IS
+      // AND IS NOT: it is a deliberate second call, not proof a human looked.
+      // The API token is shared by the phone, the lens and every COS agent
+      // session, so nothing is structurally prevented from asserting `confirm`.
+      // It stops an accidental release, not an automated one.
+      const preview = guard.listFences().find(f => f.target === target) ?? null
+      res.status(400).json({ released: false, reason: 'confirmation_required', preview })
+      return
+    }
+    // The guard decides. It re-matches the handle itself rather than trusting a
+    // lookup performed up here, and it persists BEFORE it mutates.
+    const outcome = guard.releaseFence(target)
+    if (!outcome.ok) {
+      const status = outcome.reason === 'unknown_fence' ? 404 : 500
+      res.status(status).json({ released: false, reason: outcome.reason })
+      return
+    }
+    console.warn(`[agent-session-bindings] fence RELEASED by operator target=${target} provider=${outcome.row.provider} fencedAt=${outcome.row.fencedAt}`)
+    res.json({ released: true, target, provider: outcome.row.provider })
+  })
+
   router.get('/agent-sessions/:provider/:threadId/attachability', (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
@@ -1375,7 +1552,10 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       // again just because the binding that delivered it is gone. Checked here as
       // well as in the turn route, because a fresh attach is the obvious way around
       // a per-binding fence.
-      if (fenced !== null) return refuseAttach(res, fenced)
+      if (fenced !== null) {
+        console.warn(`[agent-session-bindings] fence hit route=attach provider=${providerParam} target=${opaqueRevision(key)}`)
+        return refuseAttach(res, fenced)
+      }
 
       const resolve = deps.resolveTarget
       if (typeof resolve !== 'function') return refuseAttach(res, 'target_unresolvable')
@@ -1623,6 +1803,11 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
     const turnId = mintId()
     /** The target we hold a claim on, released in the finally. */
     let claimedKey: string | null = null
+    // Hoisted so the CATCH site can fence with evidence. `binding` and `head` are
+    // both declared inside the try, so neither is in scope where the route-error
+    // fence is set — without these it would store a fence it can say nothing about.
+    let fenceProvider = ''
+    let preTurnHeadDigest: string | null = null
     /** Children the adapter reported, released in the finally. */
     const recordedPids: number[] = []
     let pinnedBindingId: string | null = null
@@ -1789,6 +1974,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (gate?.ok !== true) return refuseTurn(registryRefusal(gate?.reason))
 
       const binding = deps.bindings.get!(bindingId)
+      if (binding) fenceProvider = binding.provider
       // Only `active` runs work. `staging` is the pre-commit state of the journaled
       // Chat handoff and must never execute against a Chat that can still roll back.
       const usable = assertUsable(binding ?? null, now)
@@ -1805,6 +1991,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       const key = binding.targetKey
       const fenced = guard.fencedReason(key)
       if (fenced !== null) {
+        console.warn(`[agent-session-bindings] fence hit route=turn provider=${binding.provider} target=${opaqueRevision(key)} turnId=${turnId}`)
         return refuseTurn(fenced, { retryable: false, deliveryState: 'unknown' })
       }
 
@@ -1823,6 +2010,7 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
 
       const head = await readHead(binding.provider, binding.nativeThreadId)
       if (head === null) return refuseTurn('native_head_unavailable')
+      preTurnHeadDigest = head.digest
 
       // The attach baseline, advanced by each completed turn and by each explicit
       // Continue Anyway. Without the advance the SECOND turn on a binding always
@@ -1928,7 +2116,18 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
         // Fenced under its own reason, not this turn's: `delivery_ambiguous`
         // describes what happened to THIS request, while a later caller needs to
         // be told the thread is shut and why it must be inspected first.
-        guard.fence(key, 'native_target_fenced')
+        guard.fence(key, 'native_target_fenced', {
+          provider: binding.provider,
+          headBefore: head.digest,
+          turnId,
+          bindingId,
+          now: Date.now(),
+        })
+        // A fence shuts a thread until a human acts, and until now it wrote NO log
+        // line at either site — so a fenced thread was discoverable only by trying
+        // to use it (Miles, 2026-08-18). Never log `key`: it embeds the private
+        // native thread id, which this router does not emit anywhere.
+        console.warn(`[agent-session-bindings] fence set site=ambiguous provider=${binding.provider} target=${opaqueRevision(key)} turnId=${turnId} bindingId=${bindingId} headBefore=${head.digest}`)
         return reportAmbiguous()
       }
 
@@ -1958,7 +2157,21 @@ export function createAgentSessionBindingsRouter(deps: AgentSessionBindingsDeps)
       if (deliveryAttempted) {
         // A bug in this route that happened AROUND a delivery is indistinguishable
         // from a delivery.
-        if (claimedKey !== null) guard.fence(claimedKey, 'native_target_fenced')
+        if (claimedKey !== null) {
+          guard.fence(claimedKey, 'native_target_fenced', {
+            provider: fenceProvider,
+            headBefore: preTurnHeadDigest,
+            turnId,
+            bindingId: null,
+            now: Date.now(),
+          })
+          // `head` is scoped to the try, so `preTurnHeadDigest` is hoisted to the
+          // handler specifically to reach this site. It is null ONLY when the throw
+          // happened before the head was read. An earlier version of this line
+          // hardcoded `unavailable` and so contradicted the record it had just
+          // written — an operator would read "no baseline" off a fence that has one.
+          console.warn(`[agent-session-bindings] fence set site=route_error target=${opaqueRevision(claimedKey)} turnId=${turnId} headBefore=${preTurnHeadDigest ?? 'unavailable'}`)
+        }
         reportAmbiguous()
       } else {
         refuseTurn('turn_failed')

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

@@ -36,7 +36,12 @@ export interface ThreadTurnQueueDeps {
    * ambiguous must resolve `ok: false` with a reason: an unknown delivery that is
    * retried puts the same sentence into a real conversation twice.
    */
-  deliver: (turn: QueuedThreadTurn) => Promise<{ ok: boolean; reason?: string }>
+  deliver: (turn: QueuedThreadTurn) => Promise<{
+    ok: boolean
+    reason?: string
+    /** The turn route's OWN `retryable` judgement, when it sent one. Authoritative. */
+    serverRetryable?: boolean
+  }>
   now: () => number
 }
 
@@ -54,6 +59,31 @@ function publicRow(turn: QueuedThreadTurn, position: number): Record<string, unk
   }
 }
 
+/**
+ * Is this failed delivery a "not yet" rather than a "no"?
+ *
+ * CLASSIFIED BY REASON, NEVER BY STATUS. Every attach refusal that is not
+ * `invalid_request` (400) or a capability gap (503) comes back 409 -- transient
+ * `native_target_busy` and permanent `native_target_fenced` alike -- so a status-based
+ * rule would retry a turn whose copy reads "an earlier turn on this thread may or may
+ * not have been delivered" up to 1,080 times inside the TTL. That is the one refusal
+ * that needs a human.
+ *
+ * `queueableRefusal` is reused rather than a second list being written: it already
+ * encodes "can this condition ever pass", it is tested, and a turn should be retried
+ * for exactly the reasons it was allowed to queue for.
+ *
+ * FAILS CLOSED. An unrecognised reason, an absent reason, or a thrown deliver all
+ * return false and spend an attempt. A new refusal added upstream is therefore bounded
+ * by default rather than silently retried forever.
+ */
+function isRetryableDelivery(outcome: { reason?: string; serverRetryable?: boolean }): boolean {
+  // The turn route publishes its own verdict; it outranks our inference either way.
+  if (outcome.serverRetryable === false) return false
+  if (outcome.serverRetryable === true) return true
+  return queueableRefusal(outcome.reason)
+}
+
 /**
  * One drain pass over one thread.
  *
@@ -103,7 +133,7 @@ export async function drainThread(
     writeQueue(provider, threadId, queue)
     dirty = true
 
-    let outcome: { ok: boolean; reason?: string }
+    let outcome: { ok: boolean; reason?: string; serverRetryable?: boolean }
     try {
       outcome = await deps.deliver(turn)
     } catch (error) {
@@ -114,6 +144,20 @@ export async function drainThread(
       turn.status = 'delivered'
       turn.settledAt = deps.now()
       delivered += 1
+    } else if (isRetryableDelivery(outcome)) {
+      // A GATE REFUSAL IS NOT A FAILED DELIVERY, so it must not spend the ceiling --
+      // measured cost of getting this wrong: three of Miles's turns retired in about
+      // two minutes each, never delivered, while the 6h TTL never got to matter.
+      //
+      // REFUNDED, not deferred. The increment and its fsync stay BEFORE the call
+      // (routes:101-103) because that is what survives a crash mid-delivery -- the
+      // ceiling only bounds anything if it outlives the crash it is bounding, and a
+      // test reads `attempts` off disk from inside the deliver callback to prove it.
+      // So the attempt is spent first and given back here, where the outcome is known.
+      turn.attempts = Math.max(0, turn.attempts - 1)
+      turn.status = 'waiting'
+      turn.reason = outcome.reason
+      held += 1
     } else if (turn.attempts >= MAX_DELIVERY_ATTEMPTS) {
       turn.status = 'refused'
       turn.reason = outcome.reason ?? 'delivery_failed'