@gotcos/glasses-server 6.48.0 → 6.48.2

package/CHANGELOG.md

@@ -1,3 +1,25 @@
+## 6.48.2
+
+Continue and Fork work again on a session whose transcript opens with a big row. Reported from the lens on 6.9.482 (Miles, 2026-09-15): Continue on a Claude session answered "Can't continue. Fork thread instead" while the row said the session was attachable.
+
+- The attach route reads the session's working directory out of the transcript's first rows. It read a fixed 512 KiB, and a session whose first prompt carried pasted screenshots opens with one row of about 1 MB, so the window held four bookkeeping rows and a torn fifth, no `cwd`, and every Continue and Fork on that session was refused `target_unresolvable`. The read now widens (512 KiB, 2 MiB, 8 MiB, 16 MiB) while the window keeps ending inside a row with no `cwd` seen, and stops as soon as the whole file has been read or a row boundary shows the transcript records none.
+- The first `cwd` in the transcript is the workspace. Two different values used to refuse the attach as a disagreement; on the release Mac every such transcript was one session whose shell had `cd`-ed into a subfolder inside a turn, and Claude stamps each row with the process cwd of the moment. The directory the session started in keys its project folder and is the only place `--resume` finds it, so it is the answer. On the release Mac 738 of 758 transcripts resolve (before: 703); the 20 that do not are scratch sessions whose temporary directory has since been deleted, which is a refusal by design.
+- Tests: the first-cwd rule for Claude and Codex, the torn-window signal, the widening sequence against the production shape (four bookkeeping rows, a 950 KB image row, then the cwd), a short file read once, a first row past the cap refused at the cap. Mutation gate: the widening and the first-cwd rule.
+
+## 6.48.1
+
+One derivation everywhere, a Desktop turn ends when the engine says it ended, a queued follow-up drains then instead of on the 30 s idle window, and the live feed carries the same state every row does. No client change is required: the next Control and EHPK builds read the new keys, and today's consumers ignore them.
+
+- A queued follow-up is delivered when the turn ends, and "ends" means what the engine means. Claude Code does not close a turn at the `Stop` hook: it closes it when every Stop hook has RETURNED, and only then dequeues anything typed meanwhile and flips its registry record to `idle`. On the release Mac the COS repo's own Stop hooks run 12-38 s, so a delivery at Stop + 2 s would have raced a prompt typed at the desk. The drain now waits for the registry's `idle` stamped at or after the Stop (polled every second, 60 s at most), then sweeps through one in-flight guard shared with the 20 s timer, so a burst of Stops folds into exactly one follow-up pass and a sentence is never delivered twice. A kick is spent only when a queue names that session; a COS child's own end kicks at once so chained follow-ups do not wait for the timer. Measured on the release Mac against a live holder whose own Stop hook ran 25 s: the registry flipped idle 25.0 s after the Stop hook, the follow-up was delivered 185 ms after that flip (its user row landed 1.5 s later, once, answered once, in the holder's own transcript, with the holder still open). Before this release: 35 s or more from the turn's end, and a delivery during the Stop hooks was possible.
+- The attach gate reads the same end of turn. With `COS_SESSION_HOOKS` on, a foreign Desktop holder whose newest hook event is a `Stop`, with the turn closed, no sub-agent open, and the registry idle at or after that Stop, reads idle at once instead of after the 30 s window. Null, unknown, a record that says busy, Codex and a far-future clock stay strict; the clause narrows a `working` verdict and never lifts a doubt. A COS Continue child registers under the tab's session id: when two records name the session the tab's is read, the child's only when it is alone.
+- The transcript's own rule for "the turn ended", used where the hooks did not see the session: the newest assistant record's `stop_reason` is terminal (end_turn, stop_sequence, max_tokens, refusal) with no `tool_use` still awaiting its result, a `result` row, or a user interrupt; a new prompt reopens it, a `<task-notification>` and a cross-session message included; a prompt queued during the Stop hooks (Claude's `queue-operation` row) keeps it open; other meta and compact rows do not. The tail read is 512 KiB: 3 of the 10 newest Desktop transcripts on the release Mac end in a ~76 KB attachment row after the terminal record, which a 64 KiB read could not see past. Positive evidence that a turn is OPEN (the hooks, or the tail) now holds ahead of the tail's ended verdict and ahead of the idle backstop, each bounded to the last 30 minutes so a crashed session still drains.
+- Every `status` draft on the session stream carries `agent_state`, `state_source`, `state_since` and, when known, `waiting_kind`, `waiting_detail`, `failure`, and on an idle state `last_reply`, as extra fields on the existing kind; `state` keeps its vocabulary (running and waiting read `working`, idle and failed `idle`, ended `done`). Every change of a session's hook state is a live status draft, so a client's state line moves on the engine's events. The stream derives from the same inputs the rows do (the hook signal, the registry record, and whether a COS turn is attached), so an Esc-interrupted turn reads idle on the lens the moment the list says so, and a Continue's trail reads `working` for as long as the child writes, never `done` from a stale Stop or from the child's own end. A shipped lens renders the frames exactly as before (its parser keeps `seq` and strips unknown fields). `COS_SESSION_HOOK_SSE=0` omits the extra fields and the live state drafts.
+- Reconnect without a reseed: each streamed session keeps a ring of its last 500 events (the active turn kept whole up to 2,000, the ring outliving the last subscriber by five minutes), each event carries a `cursor` and the server's `epoch`, and the SSE `id:` line is `<epoch>.<cursor>`. `?after=` (or `Last-Event-ID`) replays what the ring holds after that cursor, from the same server life only; a cursor from another life, one past the ring, and one with nothing after it all seed as a fresh open, so a reconnect is never an empty screen. `?seed=turn` opens a session at its current prompt and every step since, oldest first, bounded by the same 512 KiB tail read. The default seed is unchanged.
+- `queued_turns` on every `/api/agent-sessions` row (list, search, detail) and every `/api/claude-sessions` peer: the waiting follow-ups on that thread, omitted at 0. Search hits carry the same derived state fields the list does.
+- Two 6.48.0 defects: a tab adopted mid-turn read idle from a `PostToolUse` with no prompt seen (Claude 2.1.272 reloads hooks when the settings change, so open tabs report without a restart); a main-thread tool event now opens the turn, and a sub-agent's (`agent_id`) does not, live or replayed. `GET /api/session-hooks/runs` listed an interactive tab as a run with no end; runs carry the registry `entrypoint` (`sdk-cli` for `claude -p`, `claude-desktop`, `cli`), the ledger row remembers it so a restart cannot forget which sessions were tabs, and tabs are listed only with `?all=1`.
+- Two defects the live proof found in the follow-up path, both older than 6.48.0. The drainer's loopback delivery sent a turn body without `epoch` and `targetKey`, which the turns route has required since the binding hardening, so every drained follow-up was refused `invalid_request`, refunded and held for its whole TTL: it now sends the epoch the attach minted, the server's own target key and the attach's `boundTo`. And the 30 s idle backstop delivered a follow-up INTO a turn whose tool was still running (a 45 s tool leaves the transcript untouched for 45 s): the open-turn evidence above holds it. A queued turn whose `cosSessionId` the attach route would refuse is refused at enqueue instead of sitting in the queue.
+- `/api/health` `sessionHooks.drain` reports the kick's passes, kicks, folds and open waits.
+
 ## 6.48.0
 
 Session state now comes from Claude Code itself. A hook script spools every session event (session start and end, prompt submitted, turn stopped, permission wanted) and every session row carries one derived state with its provenance. No client change is required: Control 0.5.230 and glasses 6.9.478 ignore the new keys; Control 0.5.231 and the next EHPK read them.

package/README.md

@@ -181,14 +181,25 @@ The install keeps every hook you already had, backs the file up, and copies a sm
 POSIX sh script to `~/.cos-glasses/bin/cos-session-hook`. The script writes one file per
 event into `~/.cos-glasses/data/hook-spool` and never contacts the server (a permission
 request may, only after the desk has been idle for 90 s, for the approval feature that ships
-next). Sessions started after the install report `state_source: hook` on
-`/api/agent-sessions` and `/api/claude-sessions`; tabs already open keep their startup
-hook snapshot until restarted, and may show Claude's "hooks modified externally" notice once (expected: the user-level file changed under them). The next COS Control (0.5.231) offers the same install from
-its Sessions tab. Rows change only while the server runs with `COS_CLAUDE_SESSIONS_ENABLED=1`
+next). Sessions report `state_source: hook` on `/api/agent-sessions` and
+`/api/claude-sessions` from their next event on (Claude Code 2.1.272 reloads its hooks
+when the settings file changes, so open tabs need no restart; they may show Claude's
+"hooks modified externally" notice once, which is expected: the user-level file changed
+under them). A later COS Control offers the same install from its Sessions tab. Rows
+change only while the server runs with `COS_CLAUDE_SESSIONS_ENABLED=1`
 (`--hooks status` prints `serverApplies`). Turn the ingestion off with `COS_SESSION_HOOKS=0`
 (the spool is still drained and stamped, rows are exactly as before). Removing the package
 does not remove the hooks: run `--hooks uninstall` first.
 
+Since 6.48.1 the hooks also drive the follow-up queue (a queued Continue lands when the
+engine closes the turn: its `Stop` hook followed by its registry record flipping idle,
+which is when every Stop hook has returned), the attach gate (a Desktop holder whose
+turn just ended reads idle at once), and the live session stream (every `status` draft
+carries `agent_state` and friends; `?after=<epoch>.<cursor>` replays what the ring holds
+after a reconnect and seeds afresh when it holds nothing, `?seed=turn` opens at the
+current prompt). `COS_SESSION_HOOK_SSE=0` omits the extra status fields and the live
+state drafts; the `cursor`, `epoch` and `id:` line stay.
+
 ## Configuration
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.48.0",
+  "version": "6.48.2",
   "description": "COS Glasses \u2014 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

@@ -23,7 +23,7 @@ import { agentSessionStreamRouter } from './routes/agent-session-stream.js'
 import { createAttachedTurnStream } from './lib/session-stream-producer.js'
 import { claudeSessionsRouter } from './routes/claude-sessions.js'
 import { createSessionHooksRouter } from './routes/session-hooks.js'
-import { startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
+import { registerDrainKickStats, registryIdleAfterStop, sessionHooksEnabled, sessionSignalStore, signalFor, startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
 import {
   createAgentSessionBindingsRouter,
   TargetGuard,
@@ -33,7 +33,7 @@ import {
 import { AgentSessionBindingRegistry } from './lib/agent-session-binding-registry.js'
 import { targetKey } from './lib/agent-session-binding-store.js'
 import { cosSpawnedPids } from './lib/agent-session-ownership-store.js'
-import { buildOccupancyProbes, realOccupancyDirs } from './lib/occupancy-probes.js'
+import { buildOccupancyProbes, realOccupancyDirs, withHookTurnClock } 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'
@@ -129,7 +129,9 @@ import {
 
 const app = express()
 import { createThreadTurnQueueRouter, drainAllThreads } from './routes/thread-turn-queue.js'
-import { transcriptTurnEnded } from './lib/thread-turn-queue-store.js'
+import { queuedThreadKeys, transcriptTurnEnded, transcriptTurnVerdict } from './lib/thread-turn-queue-store.js'
+import { OPEN_TURN_CEILING_MS } from './lib/session-state-derive.js'
+import { createDrainKick, kickPlanFor } from './lib/thread-drain-kick.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'
@@ -382,7 +384,12 @@ const attachedWorkspaceDeps = realAttachedWorkspaceDeps(nativeHeadDeps)
  * Read the canary evidence in `thread-occupancy.ts` under THE IDLE-HOLDER
  * RELAXATION before changing this line.
  */
-const occupancyProbes = buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled())
+const occupancyProbes = sessionHooksEnabled()
+  // 6.48.1, the B6 clause: with the hooks on, a foreign Desktop holder whose newest hook
+  // event is a Stop reads idle at once instead of after the 30 s transcript window. The
+  // wrapper only adds a probe; the gate's precedence is unchanged. Off is 6.48.0.
+  ? withHookTurnClock(buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled()), signalFor, registryIdleAfterStop)
+  : buildOccupancyProbes(cosSpawnedPids, nativeHeadDeps, threadAttachEnabled())
 
 // 6.48.0: the hook spool ingester and the one signal store every session row reads. Starts
 // before any router is registered so the first list request already sees the replayed
@@ -622,11 +629,44 @@ if (threadAttachEnabled()) {
     turnEnded: (provider: string, threadId: string) => {
       if (provider !== 'claude' && provider !== 'codex') return false
       try {
+        // 6.48.1: the engine's own end of turn: a Stop hook newer than the turn's prompt
+        // AND the registry flipped idle after it (the Stop hooks have returned; a prompt
+        // typed during them is queued and dequeues only then). The transcript tail
+        // (`turnFromTail`) answers for everything the hooks did not see. Both refuse on doubt.
+        if (provider === 'claude') {
+          const signal = signalFor(threadId)
+          if (signal && !signal.turnOpen && signal.lastEvent === 'Stop' && typeof signal.stopAt === 'number'
+            && signal.stopAt >= (signal.turnStartedAt ?? 0) && signal.subagentsOpen === 0
+            && registryIdleAfterStop(threadId, signal.stopAt) === true) return true
+        }
         return transcriptTurnEnded(provider, transcriptPathFor(provider, threadId, nativeHeadDeps))
       } catch {
         return false
       }
     },
+    // 6.48.1: positive evidence the holder's turn is OPEN, which outranks the 30 s idle
+    // backstop (a long tool leaves the transcript untouched while it runs). Bounded: a
+    // signal or a tail older than OPEN_TURN_CEILING_MS is not evidence any more, so a
+    // crashed mid-tool session still drains by the backstop rather than holding for the TTL.
+    turnOpen: (provider: string, threadId: string): boolean => {
+      if (provider !== 'claude' && provider !== 'codex') return false
+      try {
+        const now = Date.now()
+        if (provider === 'claude') {
+          const signal = signalFor(threadId)
+          if (signal && signal.turnOpen && now - signal.lastEventAt <= OPEN_TURN_CEILING_MS) return true
+        }
+        const path = transcriptPathFor(provider, threadId, nativeHeadDeps)
+        const verdict = transcriptTurnVerdict(provider, path)
+        if (!verdict || verdict.ended) return false
+        if (verdict.reason !== 'tool_pending' && verdict.reason !== 'prompt_open') return false
+        const read = occupancyProbes.transcriptMtimeMs
+        const mtime = typeof read === 'function' ? read(provider, threadId) : null
+        return typeof mtime === 'number' && now - mtime <= OPEN_TURN_CEILING_MS
+      } catch {
+        return false
+      }
+    },
     activity: (provider: string, threadId: string): 'working' | 'idle' | 'unknown' => {
       try {
         const read = occupancyProbes.transcriptMtimeMs
@@ -645,10 +685,33 @@ if (threadAttachEnabled()) {
   // Every 20s. Fast enough that a freed thread drains while the user is still looking
   // at the pending row, slow enough to be nothing: the sweep does no work at all when
   // no queue file exists. Unref'd so it never holds the process open.
-  const queueDrainTimer = setInterval(() => {
-    void drainAllThreads(queueDeps).catch(() => { /* the next sweep retries */ })
-  }, 20_000)
+  //
+  // 6.48.1: the timer and the hooks' Stop share ONE in-flight guard (`thread-drain-kick`),
+  // so a Stop landing mid-sweep folds into exactly one follow-up pass and a sentence is
+  // never delivered twice. A Stop kicks only when a queue file names that session. A
+  // SubagentStop does NOT kick (QA, 2026-09-15): a background sub-agent finishing after
+  // the tab's 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.
+  const drainKick = createDrainKick({
+    drain: () => drainAllThreads(queueDeps),
+    queuedThreadIds: () => queuedThreadKeys().map(k => k.threadId),
+  })
+  registerDrainKickStats(() => drainKick.stats())
+  const queueDrainTimer = setInterval(() => { void drainKick.sweep() }, 20_000)
   queueDrainTimer.unref()
+  if (sessionHooksEnabled()) {
+    sessionSignalStore.subscribe((signal, env, child) => {
+      // The rule is `kickPlanFor` (pure, pinned in thread-drain-kick.test.ts). The Stop is
+      // not the engine's end of turn: that is the registry flipping idle once every Stop
+      // hook has returned (12-38 s on this Mac). Wait for it, then sweep; a session with
+      // no registry record (a print run that exited) is ready at once.
+      const plan = kickPlanFor(signal, env.event, env.ts, child)
+      if (!plan) return
+      if (plan.kind === 'kick') drainKick.kick(signal.sessionId)
+      else drainKick.kickWhen(signal.sessionId, () => registryIdleAfterStop(signal.sessionId, plan.stopAt) !== false)
+    })
+  }
 }
 
 app.use('/api', createAgentSessionBindingsRouter({

package/server/lib/attached-workspace.ts

@@ -61,9 +61,20 @@ export interface AttachedWorkspaceDeps {
   cursorSpawnWorkspace?: (threadId: string) => string | null
 }
 
-/** Enough to reach a Claude message row or the Codex session meta row. */
+/**
+ * The first window read for the cwd: enough to reach a Claude message row or the Codex
+ * session meta row in the common case. NOT enough on its own (6.48.2): a session whose
+ * first prompt carries pasted screenshots opens with a single row of ~1 MB, so 512 KiB
+ * held four bookkeeping rows and a torn fifth, no cwd, and every Continue on that
+ * session was refused `target_unresolvable` (Miles, 2026-09-15, from the lens; 55 of
+ * 758 transcripts on the release Mac). When a window ends inside a row before any cwd
+ * was seen, the read widens up to WORKSPACE_SCAN_BYTES_MAX.
+ */
 export const WORKSPACE_SCAN_BYTES = 512 * 1024
 
+/** The widest head read: a first prompt with ten screenshots fits; a 13 GB rollout does not get read. */
+export const WORKSPACE_SCAN_BYTES_MAX = 16 * 1024 * 1024
+
 /** Rows to inspect before giving up. Bounds a pathological single-line file. */
 export const WORKSPACE_SCAN_ROWS = 400
 
@@ -72,19 +83,37 @@ export function fingerprint(value: string): string {
 }
 
 /**
- * Pull the recorded cwd out of transcript text.
+ * Pull the recorded cwd out of transcript text: the FIRST row that records one.
  *
  * Claude puts it at the row's top level; Codex puts it in the session meta row's
  * `payload`. A torn trailing line is NORMAL — these files are appended to — so a
  * parse failure on any single row is skipped rather than fatal.
  *
- * Returns null when no row records one, and DISAGREEMENT is also null: a transcript
- * whose rows claim two different working directories is not something to guess at.
+ * THE FIRST cwd IS THE WORKSPACE (6.48.2). Until 6.48.1 two different values in the
+ * window refused the attach as a disagreement. On the release Mac every such
+ * transcript was one session whose shell `cd`-ed inside a turn (`operations/scripts`,
+ * a weekly folder): Claude stamps each row with the process cwd of the moment, all
+ * under the directory the session was started in. That starting directory is the
+ * workspace: it keys the transcript's project folder, it is the only place
+ * `claude --resume` finds the session, and it is what the first row records.
+ *
+ * Returns null only when no row in the window records one.
  */
 export function cwdFromTranscript(text: string): string | null {
-  const seen = new Set<string>()
+  return scanForCwd(text).cwd
+}
+
+/**
+ * The scan with its outcome: the cwd, or whether the window ended INSIDE a row before
+ * any cwd was seen (a first prompt of pasted screenshots is one row of ~1 MB), which
+ * tells the resolver that a wider read can still answer.
+ */
+export function scanForCwd(text: string): { cwd: string | null; endedMidRow: boolean; rows: number } {
   let rows = 0
-  for (const line of text.split('\n')) {
+  const lines = text.split('\n')
+  // A window that does not end with a newline ended inside whatever row came last.
+  const endedMidRow = text.length > 0 && !text.endsWith('\n')
+  for (const line of lines) {
     if (rows >= WORKSPACE_SCAN_ROWS) break
     const trimmed = line.trim()
     if (!trimmed) continue
@@ -94,18 +123,14 @@ export function cwdFromTranscript(text: string): string | null {
     if (!row || typeof row !== 'object' || Array.isArray(row)) continue
     const record = row as Record<string, unknown>
     const direct = record.cwd
-    if (typeof direct === 'string' && direct.length > 0) seen.add(direct)
+    if (typeof direct === 'string' && direct.length > 0) return { cwd: direct, endedMidRow: false, rows }
     const payload = record.payload
     if (payload && typeof payload === 'object' && !Array.isArray(payload)) {
       const nested = (payload as Record<string, unknown>).cwd
-      if (typeof nested === 'string' && nested.length > 0) seen.add(nested)
+      if (typeof nested === 'string' && nested.length > 0) return { cwd: nested, endedMidRow: false, rows }
     }
-    // One consistent answer found early is enough; keep scanning only while it is
-    // still the only one, so a disagreement is detected rather than short-circuited.
-    if (seen.size > 1) return null
   }
-  if (seen.size !== 1) return null
-  return [...seen][0]!
+  return { cwd: null, endedMidRow, rows }
 }
 
 /**
@@ -145,17 +170,27 @@ export function resolveAttachedWorkspace(
   }
   if (provider !== 'claude' && provider !== 'codex') return null
   let path: string | null
-  let text: string | null
+  let cwd: string | null = null
   try {
     path = deps.transcriptPath(provider, threadId)
     if (path === null) return null
-    text = deps.readHead(path, WORKSPACE_SCAN_BYTES)
+    // Widen the head read while the window keeps ending inside a row with no cwd seen:
+    // 512 KiB, 2 MiB, 8 MiB, then the cap. A window that ended on a row boundary with
+    // no cwd is a transcript that records none, and widening would not change that.
+    let window = WORKSPACE_SCAN_BYTES
+    for (;;) {
+      const text = deps.readHead(path, window)
+      if (text === null) return null
+      const scan = scanForCwd(text)
+      cwd = scan.cwd
+      // The whole file came back (shorter than the window): there is nothing wider to read.
+      const wholeFile = Buffer.byteLength(text, 'utf8') < window
+      if (cwd !== null || wholeFile || !scan.endedMidRow || scan.rows >= WORKSPACE_SCAN_ROWS || window >= WORKSPACE_SCAN_BYTES_MAX) break
+      window = Math.min(window * 4, WORKSPACE_SCAN_BYTES_MAX)
+    }
   } catch {
     return null
   }
-  if (text === null) return null
-
-  const cwd = cwdFromTranscript(text)
   if (cwd === null) return null
   // A relative cwd would resolve against the SERVER's working directory, which is
   // not a location we control and is never what the user meant.

package/server/lib/claude-session-registry.ts

@@ -29,6 +29,9 @@
 //     nameSource entirely. Only `derived` is a function of the folder name.
 
 /** Fields this module will read. Everything else in the file is ignored. */
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
 export interface RawClaudeSession {
   pid?: unknown
   sessionId?: unknown
@@ -98,6 +101,22 @@ export interface PeerProbes {
 /** A registry filename is exactly `<pid>.json`. Not `*.json`. */
 export const REGISTRY_FILENAME = /^\d+\.json$/
 
+/**
+ * Where the registry lives.
+ *
+ * `COS_CLAUDE_SESSIONS_DIR` first because it is both the override for a non-standard
+ * install AND the test seam: `homedir()` is not mockable, so without an env hook the
+ * only testable path would be the real one. Then CLAUDE_CONFIG_DIR, which real
+ * installs do set; hardcoding ~/.claude breaks those. (Moved here from the route in
+ * 6.48.1 so the hooks runtime can read it without importing a router.)
+ */
+export function claudeSessionsDir(): string {
+  const explicit = process.env.COS_CLAUDE_SESSIONS_DIR
+  if (explicit) return resolve(explicit)
+  const configDir = process.env.CLAUDE_CONFIG_DIR
+  return join(configDir ? resolve(configDir) : join(homedir(), '.claude'), 'sessions')
+}
+
 function str(value: unknown): string | null {
   return typeof value === 'string' && value.length > 0 ? value : null
 }

package/server/lib/occupancy-probes.ts

@@ -787,6 +787,49 @@ export function buildOccupancyProbes(
  * adapter's pre-spawn preflight REFUSES a thenable rather than awaiting one —
  * awaiting there would reopen the very race the check exists to close.
  */
+/**
+ * Add the hook turn clock (the B6 clause, 6.48.1) to a probe set.
+ *
+ * `signalFor` is the signal store's reader, taking a full session id or the registry's
+ * 8-character form; `registryIdleAfterStop` reads the registry record for the session.
+ * The probe answers a Stop time only when BOTH vouch: the session's newest hook event is
+ * that Stop, the turn is closed, no sub-agent is open, the session has not ended, and
+ * the registry says idle at or after the Stop (the hooks have returned). Codex never
+ * asks (its ids are not Claude sessions, and a Codex thread id sharing a Claude prefix
+ * must not read a Claude signal); `readHolderActivity` guards the provider too.
+ *
+ * Wired at the composition root only when `COS_SESSION_HOOKS` is on. Absent, the
+ * gate is byte-for-byte 6.48.0.
+ */
+export function withHookTurnClock(
+  probes: OccupancyProbes,
+  signalFor: (sessionId: string) => HookTurnSignal | undefined,
+  registryIdleAfterStop: (sessionId: string, stopAt: number) => boolean | null,
+): OccupancyProbes {
+  return {
+    ...probes,
+    holderTurnEndedAtMs: (provider, threadId) => {
+      if (provider !== 'claude') return null
+      if (!NATIVE_THREAD_ID_RE.test(threadId)) return null
+      const signal = signalFor(threadId)
+      if (!signal || signal.lastEvent !== 'Stop' || signal.turnOpen || signal.subagentsOpen > 0 || signal.ended !== null) return null
+      if (typeof signal.stopAt !== 'number') return null
+      // The engine's own end of turn: the registry flipped idle AFTER this Stop, which
+      // happens only once every Stop hook has returned. Anything else is strict.
+      return registryIdleAfterStop(threadId, signal.stopAt) === true ? signal.stopAt : null
+    },
+  }
+}
+
+/** The facts the hook turn clock reads off a session signal. */
+export interface HookTurnSignal {
+  lastEvent: string
+  turnOpen: boolean
+  subagentsOpen: number
+  ended: { at: number; reason: string } | null
+  stopAt: number | null
+}
+
 export function withTranscriptClock(
   probes: OccupancyProbes,
   headDeps: NativeHeadDeps,

package/server/lib/session-hook-events.ts

@@ -182,6 +182,11 @@ export function projectHookPayload(event: HookEventName, payload: Record<string,
         tool_target: toolTarget(payload.tool_input),
         tool_fingerprint: toolFingerprint(toolName, payload.tool_input ?? null),
         ...(str('tool_use_id') ? { tool_use_id: str('tool_use_id') } : {}),
+        // A sub-agent's tool events carry these (docs; unrecorded as of 2026-09-15). The
+        // store reads `agent_id` to keep them from reopening the main turn, so the ledger
+        // must keep it or a replay reopens what the live path did not.
+        ...(str('agent_id') ? { agent_id: str('agent_id') } : {}),
+        ...(str('agent_type') ? { agent_type: str('agent_type') } : {}),
         ...(event === 'PermissionRequest' && Array.isArray(payload.permission_suggestions)
           ? { permission_suggestions: payload.permission_suggestions.slice(0, 4) }
           : {}),

package/server/lib/session-hook-ledger.ts

@@ -20,6 +20,8 @@ export interface LedgerRow {
   session_id: string
   /** Classified at ingest, while the pid was alive: a COS-spawned child's event. */
   child?: boolean
+  /** The registry's `entrypoint` for the session, once read (6.48.1); a replay restores it. */
+  entrypoint?: string
   payload: Record<string, unknown>
 }
 
@@ -54,7 +56,7 @@ export class SessionHookLedger {
   }
 
   /** Append one row. Returns false (and remembers why) when the disk refused. */
-  append(key: string, env: HookEnvelope, child = false): boolean {
+  append(key: string, env: HookEnvelope, child = false, entrypoint: string | null = null): boolean {
     let row: LedgerRow
     try {
       row = {
@@ -64,6 +66,7 @@ export class SessionHookLedger {
         event: env.event,
         session_id: env.sessionId,
         ...(child ? { child: true } : {}),
+        ...(entrypoint ? { entrypoint } : {}),
         payload: projectHookPayload(env.event, env.payload),
       }
     } catch (error) {
@@ -96,7 +99,7 @@ export class SessionHookLedger {
    * hide the rows that matter most, and forget their keys). Malformed lines are skipped;
    * a boot must never fail on a torn last line.
    */
-  replay(sinceMs: number, apply: (env: HookEnvelope, key: string, child: boolean) => void): { rows: number; applied: number; keys: Set<string> } {
+  replay(sinceMs: number, apply: (env: HookEnvelope, key: string, child: boolean, entrypoint: string | null) => void): { rows: number; applied: number; keys: Set<string> } {
     const keys = new Set<string>()
     let rows = 0
     let applied = 0
@@ -115,7 +118,8 @@ export class SessionHookLedger {
       keys.add(r.key)
       if (r.ts < sinceMs) continue
       const payload = r.payload && typeof r.payload === 'object' ? r.payload as Record<string, unknown> : {}
-      apply({ ts: r.ts, ppid: typeof r.ppid === 'number' ? r.ppid : null, event: r.event, sessionId: r.session_id.toLowerCase(), payload: { session_id: r.session_id, ...payload } }, r.key, r.child === true)
+      const entrypoint = typeof r.entrypoint === 'string' && r.entrypoint ? r.entrypoint : null
+      apply({ ts: r.ts, ppid: typeof r.ppid === 'number' ? r.ppid : null, event: r.event, sessionId: r.session_id.toLowerCase(), payload: { session_id: r.session_id, ...payload } }, r.key, r.child === true, entrypoint)
       applied++
     }
     return { rows, applied, keys }

package/server/lib/session-hook-spool.ts

@@ -45,9 +45,15 @@ export interface SpoolIngesterOptions {
   dir: string
   ledger: SessionHookLedger
   /** Apply a parsed envelope to the store. Absent when the feature is off. */
-  apply?: (env: HookEnvelope, child: boolean) => void
+  apply?: (env: HookEnvelope, child: boolean, entrypoint: string | null) => void
   /** Classify the envelope's ppid at INGEST time, while the pid is still alive. */
   isChild?: (env: HookEnvelope) => boolean
+  /**
+   * The session's registry `entrypoint`, read at INGEST time while the record is alive
+   * (6.48.1). Written onto the ledger row so a replay after a restart knows a print run
+   * from a tab without a registry that has since been reaped.
+   */
+  entrypointOf?: (env: HookEnvelope, child: boolean) => string | null
   /** Keys already in the ledger at boot, so a replayed file is not applied twice. */
   seenKeys?: Set<string>
   sweepMs?: number
@@ -175,15 +181,17 @@ export function startSpoolIngester(options: SpoolIngesterOptions): SpoolIngester
     // replay after a restart (when the spawn ledger is empty) applies the same rule.
     let child = false
     try { child = options.isChild?.(env) ?? false } catch { child = false }
+    let entrypoint: string | null = null
+    try { entrypoint = options.entrypointOf?.(env, child) ?? null } catch { entrypoint = null }
     let appended = false
-    try { appended = ledger.append(name, env, child) } catch (error) { stats.lastError = errorCode(error) }
+    try { appended = ledger.append(name, env, child, entrypoint) } catch (error) { stats.lastError = errorCode(error) }
     if (!appended) {
       // Keep the file: the ledger is the durable record and it refused. Health shows why.
       stats.lastError = ledger.stats().lastError ?? stats.lastError
       return false
     }
     seen.add(name)
-    try { options.apply?.(env, child) } catch (error) {
+    try { options.apply?.(env, child, entrypoint) } catch (error) {
       stats.applyErrors++
       console.error(`[hook-spool] apply failed for ${name}: ${error instanceof Error ? error.message : error}`)
     }