@gotcos/glasses-server 6.27.13 → 6.29.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## Unreleased
 
+## 6.28.0
+- **Continue Original Agent Thread — attach to a live desktop thread and append a turn
+  to it.** From the glasses you can now continue a Claude Code or Codex conversation that
+  already exists on your Mac: the turn is written into the REAL transcript, not a copy.
+  Verified end to end on disposable threads for both providers.
+
+  **OFF BY DEFAULT and permanently supported that way.** Set `COS_THREAD_ATTACH_ENABLED=1`
+  to turn it on. With it unset you get exactly the behaviour that existed before: read-only
+  session browsing and Fork-only everywhere. The two write routes are not registered at all
+  when it is off, so a disabled server holds no reachable write code, and the attachability
+  endpoint answers `attach_disabled` without touching the filesystem.
+
+- **A thread that someone has open on the desktop is never written to.** COS resolves, from
+  a first-party per-session registry, whether a live process owns the thread, and refuses
+  with "Open on your Mac. Fork it instead." Ownership of COS's own spawned child is
+  established from a measured kernel process start, because a bare pid can be recycled.
+
+- **A repeated POST replays instead of delivering twice.** Turns carry a required client
+  idempotency key and completed or ambiguous outcomes are remembered durably, so a retry
+  after a lost response returns what the first turn did rather than posting a second copy
+  into the conversation. A pre-delivery refusal stays re-evaluatable.
+
+- **A turn whose fate is unknown is never reported as a clean failure.** If the provider
+  fails after the prompt was delivered, the outcome is `ambiguous` with `retryable: false`
+  and copy telling you to check the thread, because a retry there would double-post.
+
+- No always-approve, bypass-permissions or sandbox-escape flag can reach a provider running
+  an attached turn; the argv is checked before any process is created.
+
 ## 6.27.13
 - **`POST /api/meeting/:sessionId/backfill-enrolment`** — train a profile from a voice
   that was named BEFORE enrolment shipped. Those meetings have a correct transcript and
@@ -2190,6 +2219,36 @@ unsaved capture, and makes batch status stop lying about finished work.
 
 # Changelog
 
+## [6.29.0] - 2026-08-16
+
+### Continue is queued instead of holding the phone
+
+- An attached turn is admitted with **202** and delivered in the background. A
+  provider turn runs up to 21 minutes and iOS suspends the WebView the moment the
+  phone is pocketed, so a synchronous turn was lost exactly when the user did the
+  natural thing.
+- Every safety gate stays synchronous: body, replay, queued-prompt, lease, target,
+  epoch, fence, claim, occupancy, head baseline, pin. A refusal still reaches the
+  user immediately and precisely. Only the spawn moved.
+- **New:** `GET /api/agent-sessions/bindings/:bindingId/turns/:clientTurnId`
+  serves the same durable ledger record the replay path serves, so a poll and a
+  retry can never disagree about what a turn did. Reports `unknown` rather than
+  `failed` for a key it has never seen.
+- Fixed: a post-202 refusal recorded nothing, so the status route would have
+  answered `pending` forever. Pre-202 refusals keep the old semantics and stay
+  re-evaluatable.
+
+### Fork, ungated
+
+- `POST /api/agent-sessions/:provider/:threadId/fork` is registered whether or not
+  `COS_THREAD_ATTACH_ENABLED` is set. Fork appends to nothing: the original is left
+  byte-identical. It is what every refusal tells the user to do instead, and a
+  refusal pointing at a route that 404s is a dead end.
+
+**Required by COS Glasses 6.8.363.** Continue still needs
+`COS_THREAD_ATTACH_ENABLED=1`; with it unset the write routes are not registered
+and behavior is unchanged.
+
 ## 6.12.7
 
 Pairs the public server with COS Glasses build 227+ meeting follow-ups while

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.27.13",
+  "version": "6.29.0",
   "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

@@ -20,6 +20,15 @@ import { transcribeRouter } from './routes/transcribe.js'
 import { sessionIndexRouter } from './routes/session-index.js'
 import { agentSessionsRouter } from './routes/agent-sessions.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
+import { createAgentSessionBindingsRouter } from './routes/agent-session-bindings.js'
+import { AgentSessionBindingRegistry } from './lib/agent-session-binding-registry.js'
+import { cosSpawnedPids } from './lib/agent-session-ownership-store.js'
+import { realOccupancyDirs, realOccupancyProbes } from './lib/occupancy-probes.js'
+import { realAttachedWorkspaceDeps, resolveAttachedWorkspace } from './lib/attached-workspace.js'
+import { deliverAttachedTurn, realAttachedTurnDeps } from './lib/attached-provider-adapter.js'
+import { forkThread, realForkDeps } from './lib/fork-thread.js'
+import { nativeHead, realNativeHeadDeps } from './lib/native-head.js'
+import { threadOccupancy } from './lib/thread-occupancy.js'
 import { displayRouter } from './routes/display.js'
 import { transcribeStreamRouter } from './routes/transcribe-stream.js'
 import { meetingRouter, resumeMeetingFinalizationJobs } from './routes/meeting.js'
@@ -263,6 +272,148 @@ app.use((_req, _res, next) => {
   next()
 })
 
+// Hydrated once at boot, before any route can read it. Never throws; a corrupt
+// or unreadable store yields a degraded registry rather than a silent empty one.
+const agentSessionBindingRegistry = AgentSessionBindingRegistry.open()
+// Boot reap, and it is load-bearing rather than housekeeping. A turn pins its
+// binding and unpins in a `finally` that never runs if the process dies during the
+// provider run — a window of up to the 21-minute attached timeout, and exactly what
+// a crash, a force-quit, or a COS Control "Update Server" does. A pinned binding
+// never expires by design, and `blocksTarget` refuses any pinned target, so the
+// thread becomes permanently unattachable: measured at +1m, +31m, +2d, +40d and
+// +400d, all `native_target_busy`. The refusal copy tells the user to detach the
+// other chat, and this router registers no detach route, so the only recovery was
+// hand-editing the store. `reap()` already fixes it and simply had no caller.
+try {
+  const reaped = agentSessionBindingRegistry.reap(Date.now())
+  if (reaped.pinsDropped > 0 || reaped.removed.length > 0) {
+    console.log(`[binding-registry] boot reap: ${reaped.pinsDropped} stale pin(s) dropped, ${reaped.removed.length} binding(s) removed`)
+  }
+} catch (error) {
+  console.warn('[binding-registry] boot reap failed', error)
+}
+// And periodically, so a strand created mid-run clears without waiting for the next
+// restart. Unref'd so it never holds the process open during shutdown.
+const bindingReapTimer = setInterval(() => {
+  try { agentSessionBindingRegistry.reap(Date.now()) } catch { /* next tick retries */ }
+}, 10 * 60_000)
+bindingReapTimer.unref()
+
+// Built once. Each of these reads the disk, so sharing them keeps an attach from
+// re-deriving roots per request.
+const occupancyProbes = realOccupancyProbes(cosSpawnedPids)
+const occupancyDirs = realOccupancyDirs()
+const nativeHeadDeps = realNativeHeadDeps()
+const attachedWorkspaceDeps = realAttachedWorkspaceDeps(nativeHeadDeps)
+
+/**
+ * The shim between the route's request shape and the adapter's.
+ *
+ * The route was written against a contract that carries fingerprints and a veto
+ * hook; the adapter needs a real cwd, a permission policy, and its dependencies.
+ * Reconciling them is the composition root's job — putting it in either module
+ * would make one of them know about the other's shape.
+ *
+ * OWNERSHIP IS RECORDED EXACTLY ONCE, BY THE ROUTE.
+ *
+ * An earlier version of this comment claimed "exactly once" while the code did it
+ * twice: it called `recordCosSpawn` here and then `request.onSpawn(pid)`, and the
+ * route's `onSpawn` is not a veto — it re-probes the process start and records the
+ * claim itself (agent-session-bindings.ts:1395-1422). Measured, one turn produced
+ * `recorded +2 / released +1`. Not a leak, since both writes hit one Map key and a
+ * single release clears it, but it pinned `stats().recorded : released` at a
+ * permanent 2:1 — and that ratio is exactly what an operator reads to detect the
+ * leak this ledger exists to prevent, so the diagnostic was poisoned by the code
+ * meant to feed it.
+ *
+ * The route is the right owner: it holds the `recordedPids` list its own `finally`
+ * releases from. So this delegates rather than duplicating. Any return other than
+ * the exact string 'recorded' makes the adapter SIGKILL the child and release
+ * before a single prompt byte is written, which is the veto the route wants.
+ */
+const deliverAttachedTurnForRoute = async (request: {
+  provider: 'claude' | 'codex'
+  nativeThreadId: string
+  prompt: string
+  onSpawn: (pid: number) => boolean
+}): Promise<unknown> => {
+  // Resolved here, not stored on the binding: the cwd is read from the transcript,
+  // which records it verbatim. Decoding the project slug is lossy — this Mac's own
+  // workspace path contains both a space and hyphens.
+  const workspace = resolveAttachedWorkspace(
+    request.provider, request.nativeThreadId, attachedWorkspaceDeps,
+  )
+  // No cwd means no attach. Never fall back to the server's own working directory,
+  // which is wherever the LaunchAgent happened to start.
+  if (workspace === null) {
+    return { ok: false, delivery: 'not_attempted', reason: 'target_unresolvable' }
+  }
+
+  const base = realAttachedTurnDeps(() => {
+    // The final occupancy re-check, synchronous and immediately before spawn
+    // (plan 4.3 step 6). A newly appeared owner is terminal, not a warning.
+    const verdict = threadOccupancy(
+      request.provider, request.nativeThreadId, occupancyProbes, occupancyDirs,
+    )
+    return { attachable: verdict.attachable, reason: verdict.reason }
+  })
+
+  return deliverAttachedTurn({
+    provider: request.provider,
+    nativeThreadId: request.nativeThreadId,
+    prompt: request.prompt,
+    cwd: workspace.path,
+    // The only policy this build accepts. The adapter refuses anything else and
+    // asserts no bypass/always-approve flag reaches the argv (plan 4.7).
+    policy: 'read_only',
+    deps: {
+      ...base,
+      // `startMs` is deliberately unused: the adapter already probed it as a GATE
+      // (a null there aborts before this is reached), and the route probes again
+      // as the recorder. One record, one authority.
+      recordSpawn: (pid: number, _startMs: number) =>
+        request.onSpawn(pid) ? 'recorded' : 'route_refused_ownership',
+    },
+  })
+}
+
+/**
+ * The shim for FORK — the action seventeen refusal strings in this feature already
+ * recommend, and which until 6.29 existed nowhere in the server or the app.
+ *
+ * Deliberately much thinner than the attached shim above, and every difference is
+ * load-bearing:
+ *
+ *  - NO PREFLIGHT. `realAttachedTurnDeps` takes an occupancy re-check because it is
+ *    about to APPEND to a thread someone may have open on their desktop. A fork
+ *    appends to nothing: verified byte-for-byte on both providers on 2026-08-16,
+ *    source sha256 unchanged across the run. A live desktop owner must therefore
+ *    NOT block a fork — gating it here would refuse at exactly the moment fork is
+ *    the only path the user has left.
+ *  - NO `onSpawn` HAND-BACK. The turns route owns its own ledger record because it
+ *    holds the `recordedPids` list that its `finally` releases from. The fork route
+ *    holds no such list, so `fork-thread.ts` records and releases the child itself,
+ *    exactly once, on every exit path — which keeps the recorded:released ratio the
+ *    operator reads for leak detection at 1:1.
+ *  - A WATERMARK IS SUPPLIED, and it is the point. `nativeHead` of the SOURCE, read
+ *    once before the spawn and once after the child settles, is what turns "a fork
+ *    does not touch the original" from a promise into a checked property. It is
+ *    SYNCHRONOUS (native-head.ts:491), which is what lets the module read the
+ *    baseline at the spawn boundary without an await. Unwired, the module can only
+ *    ever report `unverified`, and it would report that honestly rather than
+ *    claiming a verification it never performed.
+ */
+const forkThreadForRoute = (request: {
+  provider: 'claude' | 'codex'
+  nativeThreadId: string
+  prompt: string
+  cwd: string
+  policy: 'read_only'
+}): Promise<unknown> => forkThread({
+  ...request,
+  deps: realForkDeps((provider, threadId) => nativeHead(provider, threadId, nativeHeadDeps)),
+})
+
 // API routes
 app.use('/api', healthRouter)
 app.use('/api', diagRouter)
@@ -280,6 +431,41 @@ app.use('/api', agentSessionsRouter)
 // Presence view of Claude Code sessions on this Mac. Dark unless
 // COS_CLAUDE_SESSIONS_ENABLED=1 — it projects another product's 0700 state dir.
 app.use('/api', claudeSessionsRouter)
+// Phase 0 of Continue Original Agent Thread: can COS write into a desktop thread
+// without colliding with a live writer? Read-only — it answers, it never attaches.
+// Registered AFTER agentSessionsRouter deliberately: its paths are 2 and 4 segments
+// (`/agent-sessions/bindings`, `/agent-sessions/:provider/:threadId/attachability`)
+// and cannot shadow that router's `/agent-sessions/:provider/:id` transcript route.
+app.use('/api', createAgentSessionBindingsRouter({
+  probes: occupancyProbes,
+  dirs: occupancyDirs,
+  now: () => Date.now(),
+  resolveTarget: (provider, threadId) => {
+    const workspace = resolveAttachedWorkspace(provider, threadId, attachedWorkspaceDeps)
+    // Only the fingerprints cross this boundary. The route persists what it is
+    // given, and plan 3.3 keeps a filesystem path off anything client-visible.
+    return workspace === null ? null : {
+      workspaceFingerprint: workspace.workspaceFingerprint,
+      sourceFingerprint: workspace.sourceFingerprint,
+    }
+  },
+  nativeHead: (provider, threadId) => nativeHead(provider, threadId, nativeHeadDeps),
+  deliverAttachedTurn: deliverAttachedTurnForRoute as never,
+  forkThread: forkThreadForRoute,
+  // 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
+  // working directory, which is wherever the LaunchAgent happened to start.
+  resolveForkWorkspace: (provider, threadId) =>
+    resolveAttachedWorkspace(provider, threadId, attachedWorkspaceDeps)?.path ?? null,
+  // One instance per process. The epoch high-water mark is only monotonic if a
+  // single reader owns the durable store, so this must never be constructed twice.
+  // `open()` never throws: an unreadable store yields a DEGRADED registry whose
+  // `available()` is false, which the route renders as a refusal rather than as an
+  // empty list — "nothing is bound" and "the store could not be read" must not
+  // look the same.
+  bindings: agentSessionBindingRegistry,
+}))
 app.use('/api', displayRouter)
 app.use('/api', transcribeStreamRouter)
 app.use('/api', meetingRouter)