@gotcos/glasses-server 6.47.0 → 6.48.1

package/server/routes/claude-sessions.ts

@@ -18,8 +18,7 @@
 import { Router } from 'express'
 import { existsSync } from 'node:fs'
 import { lstat, readdir, readFile, stat } from 'node:fs/promises'
-import { homedir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { join } from 'node:path'
 import {
   REGISTRY_FILENAME,
   countPeers,
@@ -28,7 +27,15 @@ import {
   type ClaudePeer,
   type PeerProbes,
   type RawClaudeSession,
+  type ClaudePeerRecord,
+  peerRecordFacts,
+  toWirePeer,
+  claudeSessionsDir,
 } from '../lib/claude-session-registry.js'
+import { deriveForRow } from '../lib/session-hooks-runtime.js'
+import { derivedRowFields, type RegistryFacts } from '../lib/session-state-derive.js'
+import { queuedTurnsFields, queuedWaitingLookup } from '../lib/thread-turn-queue-store.js'
+import { isAttachedTurnActive, sessionStreamKey } from '../lib/session-stream-bus.js'
 
 export const claudeSessionsRouter = Router()
 
@@ -56,20 +63,8 @@ export function claudeSessionNamesVisible(): boolean {
   return process.env.COS_CLAUDE_SESSIONS_SHOW_NAMES === '1'
 }
 
-/**
- * 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.
- */
-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')
-}
+/** Where the registry lives; the definition moved to the registry lib in 6.48.1. */
+export { claudeSessionsDir }
 
 const realProbes: PeerProbes = {
   isAlive: pid => {
@@ -92,6 +87,15 @@ export async function readClaudePeers(
   probes: PeerProbes = realProbes,
   showNames = claudeSessionNamesVisible(),
 ): Promise<ClaudePeer[]> {
+  return (await readClaudePeerRecords(dir, probes, showNames)).map(toWirePeer)
+}
+
+/** The peers with the deriver's facts attached. Server-side only; see `toWirePeer`. */
+export async function readClaudePeerRecords(
+  dir: string,
+  probes: PeerProbes = realProbes,
+  showNames = claudeSessionNamesVisible(),
+): Promise<ClaudePeerRecord[]> {
   let names: string[]
   try {
     names = await readdir(dir)
@@ -101,7 +105,7 @@ export async function readClaudePeers(
     // separately so this cannot be mistaken for "the feature is off".
     return []
   }
-  const peers: ClaudePeer[] = []
+  const peers: ClaudePeerRecord[] = []
   for (const name of names.filter(n => REGISTRY_FILENAME.test(n)).slice(0, MAX_REGISTRY_FILES)) {
     const full = join(dir, name)
     try {
@@ -114,7 +118,8 @@ export async function readClaudePeers(
       let mtimeMs: number | null = null
       try { mtimeMs = (await stat(full)).mtimeMs } catch { /* raced the reaper */ }
       const peer = toPeer(raw, probes, mtimeMs, showNames)
-      if (peer) peers.push(peer)
+      const facts = peerRecordFacts(raw)
+      if (peer && facts) peers.push({ ...peer, ...facts })
     } catch {
       // ENOENT between readdir and read is NORMAL here — the reaper is actively
       // unlinking these — and a torn read is expected because writes are
@@ -122,7 +127,12 @@ export async function readClaudePeers(
       continue
     }
   }
-  return sortPeers(peers)
+  return sortPeers(peers) as ClaudePeerRecord[]
+}
+
+/** The deriver's view of a registry record. */
+export function registryFacts(record: ClaudePeerRecord): RegistryFacts {
+  return { alive: record.alive, status: record.status, waitingFor: record.waitingFor, statusUpdatedAt: record.statusUpdatedAt, lastActiveAt: record.lastActiveAt }
 }
 
 function boundedInteger(value: unknown, fallback: number, min: number, max: number): number {
@@ -148,9 +158,20 @@ claudeSessionsRouter.get('/claude-sessions', async (req, res) => {
   }
   try {
     const limit = boundedInteger(req.query.limit, 30, 1, 100)
-    const peers = await readClaudePeers(claudeSessionsDir())
+    const records = await readClaudePeerRecords(claudeSessionsDir())
+    const peers = records.map(toWirePeer)
+    const queuedOf = queuedWaitingLookup(Date.now())
+    // 6.48.0: the same derived state every surface reads, stamped ADDITIVELY on the wire
+    // peer. `toPeer` stays byte-identical (its key set is pinned); the eight extra keys
+    // come from the signal store and the registry facts an older client never sees.
+    // 6.48.1: queued_turns joins here too so a peer-only row (no agent-sessions hit)
+    // still shows a follow-up waiting.
     res.json({
-      peers: peers.slice(0, limit),
+      peers: records.slice(0, limit).map(record => ({
+        ...toWirePeer(record),
+        ...derivedRowFields(deriveForRow({ sessionId: record.sessionId, registry: registryFacts(record), attachedTurn: isAttachedTurnActive(sessionStreamKey('claude', record.sessionId)) })),
+        ...queuedTurnsFields(queuedOf('claude', record.sessionId)),
+      })),
       counts: countPeers(peers),
       enabled: true,
       generatedAt: Date.now(),

package/server/routes/health.ts

@@ -79,6 +79,7 @@ import {
   threadAttachCapability,
   threadAttachHealthFields,
 } from '../lib/thread-attach-capability.js'
+import { sessionHooksHealthFields } from '../lib/session-hooks-runtime.js'
 
 export const healthRouter = Router()
 
@@ -349,6 +350,7 @@ healthRouter.get('/health', async (_req, res) => {
     ...checks,
     server_version: managedServerVersion(),
     ...threadAttachHealthFields(threadAttach),
+    ...sessionHooksHealthFields(),
     server_instance_id: getServerInstanceId(),
     boot_id: serverMetrics.bootId,
     generation_id: getServerGenerationId(),

package/server/routes/session-hooks.ts

@@ -0,0 +1,80 @@
+// Session hooks: status, install, uninstall, and today's runs.
+//
+// `GET /api/session-hooks/status` is what Control's banner keys off. Five outcomes on
+// the client side and this route owns three of them: 200 with `installed` (no banner),
+// 200 with `drift`, `missing`, `script_outdated`, `settings_*` (banner with Install). A
+// 404 means a server older than 6.48.0 (`route_absent`), and no answer at all is
+// `unreachable`; neither is "not installed", and Control must never say so for them.
+
+import { Router } from 'express'
+import { installClaudeHooks, uninstallClaudeHooks } from '../lib/claude-hooks-installer.js'
+import { deskIdleSeconds, invalidateHookStatus, sessionHooksHealthFields, sessionSignalStore } from '../lib/session-hooks-runtime.js'
+import { workspaceFromCwd } from '../lib/claude-session-registry.js'
+
+/** The registry entrypoints a person sits at; everything else (`sdk-cli`, unknown) may be a job. */
+export function isInteractiveEntrypoint(entrypoint: string | null): boolean {
+  return entrypoint === 'claude-desktop' || entrypoint === 'cli'
+}
+
+export function createSessionHooksRouter(options: { port: number }): Router {
+  const router = Router()
+
+  router.get('/session-hooks/status', (_req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    res.json({ ok: true, ...sessionHooksHealthFields() })
+  })
+
+  router.post('/session-hooks/install', (req, res) => {
+    const dryRun = req.query.dryRun === '1' || (req.body && typeof req.body === 'object' && (req.body as { dryRun?: unknown }).dryRun === true)
+    const result = installClaudeHooks({ port: options.port, deskIdleSeconds: deskIdleSeconds(), dryRun })
+    invalidateHookStatus()
+    if (!result.ok) {
+      res.status(409).json({ ok: false, reason: result.reason ?? 'install_failed', status: result.status })
+      return
+    }
+    res.json({ ok: true, changed: result.changed, scriptCopied: result.scriptCopied, backupPath: result.backupPath, status: result.status, ...(dryRun ? { merged: result.merged } : {}) })
+  })
+
+  router.post('/session-hooks/uninstall', (req, res) => {
+    const dryRun = req.query.dryRun === '1'
+    const result = uninstallClaudeHooks({ dryRun })
+    invalidateHookStatus()
+    if (!result.ok) {
+      res.status(409).json({ ok: false, reason: result.reason ?? 'uninstall_failed', status: result.status })
+      return
+    }
+    res.json({ ok: true, changed: result.changed, backupPath: result.backupPath, status: result.status, ...(dryRun ? { merged: result.merged } : {}) })
+  })
+
+  // Sessions the hooks saw start and end, for Control's scheduled-job ledger. A run
+  // shorter than the pet's 20 s poll is recorded here where the poll never saw it.
+  router.get('/session-hooks/runs', (req, res) => {
+    res.set('Cache-Control', 'private, no-store')
+    const since = Number(req.query.since)
+    const sinceMs = Number.isFinite(since) && since > 0 ? since : Date.now() - 24 * 60 * 60_000
+    // A Desktop tab or a terminal session is not a run (6.48.1): the ledger wants the
+    // `claude -p` jobs (`sdk-cli`). `?all=1` lists every session the hooks saw.
+    const all = req.query.all === '1'
+    const runs: Array<Record<string, unknown>> = []
+    for (const signal of sessionSignalStore.snapshot()) {
+      if (signal.firstSeenAt < sinceMs && !(signal.ended && signal.ended.at >= sinceMs)) continue
+      if (!all && isInteractiveEntrypoint(signal.entrypoint)) continue
+      runs.push({
+        session_id: signal.sessionId,
+        entrypoint: signal.entrypoint,
+        started_at: new Date(signal.firstSeenAt).toISOString(),
+        ended_at: signal.ended ? new Date(signal.ended.at).toISOString() : null,
+        end_reason: signal.ended?.reason ?? null,
+        // The registry route reduces cwd to a workspace name on the wire; so does this one.
+        workspace: workspaceFromCwd(signal.cwd),
+        keep_warm: signal.keepWarm,
+        child_events: signal.childEvents,
+        last_reply: signal.lastReply || null,
+      })
+    }
+    runs.sort((a, b) => String(b.started_at).localeCompare(String(a.started_at)))
+    res.json({ ok: true, runs, since: new Date(sinceMs).toISOString() })
+  })
+
+  return router
+}

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

@@ -16,6 +16,7 @@
 // EVERY DEPENDENCY IS INJECTED so the whole path is testable without a live server.
 
 import { Router, type Request, type Response } from 'express'
+import { COS_SESSION_ID_RE } from './agent-session-bindings.js'
 import {
   admitToQueue, drainDecision, queueableRefusal, queuePosition,
   MAX_DELIVERY_ATTEMPTS, type DrainObservation, type QueuedThreadTurn,
@@ -27,6 +28,8 @@ export interface ThreadTurnQueueDeps {
   occupancy: (provider: string, threadId: string) => { attachable: boolean; reason: string | null }
   /** Did the holder's last transcript record end a turn? */
   turnEnded: (provider: string, threadId: string) => boolean
+  /** 6.48.1, optional: is the holder's turn positively OPEN right now (see DrainObservation.turnOpen)? */
+  turnOpen?: (provider: string, threadId: string) => boolean
   /** The 30s transcript clock, as a backstop. */
   activity: (provider: string, threadId: string) => 'working' | 'idle' | 'unknown'
   /**
@@ -77,6 +80,11 @@ function publicRow(turn: QueuedThreadTurn, position: number): Record<string, unk
  * return false and spend an attempt. A new refusal added upstream is therefore bounded
  * by default rather than silently retried forever.
  */
+/** A throwing turnOpen probe is not evidence either way. */
+function safeTurnOpen(deps: ThreadTurnQueueDeps, provider: string, threadId: string): boolean | undefined {
+  try { return deps.turnOpen!(provider, threadId) } catch { return undefined }
+}
+
 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
@@ -116,6 +124,7 @@ export async function drainThread(
     const seen: DrainObservation = {
       attachable: gate.attachable,
       turnEnded: deps.turnEnded(provider, threadId),
+      turnOpen: deps.turnOpen ? safeTurnOpen(deps, provider, threadId) : undefined,
       activity: deps.activity(provider, threadId),
       reason: gate.reason,
     }
@@ -212,6 +221,12 @@ export function createThreadTurnQueueRouter(deps: ThreadTurnQueueDeps): Router {
     if (!clientTurnId || !cosSessionId || !prompt.trim()) {
       return res.status(400).json({ error: 'invalid_request' })
     }
+    // 6.48.1: the attach route refuses an id outside COS_SESSION_ID_RE as invalid_request,
+    // which the drainer treats as retryable, so a bad id used to sit in the queue for the
+    // whole TTL. Refuse it here, where the client can still fix it.
+    if (!COS_SESSION_ID_RE.test(cosSessionId)) {
+      return res.status(400).json({ error: 'invalid_request', reason: 'invalid_cos_session_id' })
+    }
 
     if (provider === 'cursor') {
       return res.status(423).json({ error: 'unsupported_provider', queueable: false })

package/server/scripts/hooks-cli.ts

@@ -0,0 +1,48 @@
+#!/usr/bin/env tsx
+// Install, inspect or remove the COS session hook in ~/.claude/settings.json.
+//
+//   npx --yes @gotcos/glasses-server@latest --hooks install [--dry-run] [--port 3141]
+//   npx --yes @gotcos/glasses-server@latest --hooks status
+//   npx --yes @gotcos/glasses-server@latest --hooks uninstall [--dry-run]
+//
+// Prints one JSON document. Exit 0 on success, 2 on a refusal (unparseable or symlinked
+// settings, a missing packaged script), 64 on a bad argument. Never prints the token.
+
+import { hookStatus, installClaudeHooks, uninstallClaudeHooks } from '../lib/claude-hooks-installer.js'
+import { sessionHooksEnabled } from '../lib/session-hooks-runtime.js'
+
+const args = process.argv.slice(2)
+const action = args.find(a => !a.startsWith('--'))
+const dryRun = args.includes('--dry-run')
+const portIndex = args.indexOf('--port')
+const port = portIndex >= 0 ? Number(args[portIndex + 1]) : Number(process.env.PORT ?? 3141)
+const deskIndex = args.indexOf('--desk-idle-s')
+const deskIdleSeconds = deskIndex >= 0 ? Number(args[deskIndex + 1]) : Number(process.env.COS_PERMISSION_BROKER_DESK_IDLE_S ?? 90)
+
+function print(value: unknown): void {
+  console.log(JSON.stringify(value, null, 2))
+}
+
+// `serverApplies` says whether the running server would READ the spool into rows: the
+// hooks can be installed while the feature is off (COS_CLAUDE_SESSIONS_ENABLED unset),
+// and a status that said only "installed" would hide that.
+const serverApplies = sessionHooksEnabled()
+const flagsNote = serverApplies ? undefined : 'Rows change only when the server runs with COS_CLAUDE_SESSIONS_ENABLED=1 (or COS_SESSION_HOOKS=1).'
+
+if (action === 'status') {
+  print({ action, serverApplies, ...(flagsNote ? { note: flagsNote } : {}), ...hookStatus() })
+  process.exit(0)
+}
+if (action === 'install') {
+  if (!Number.isFinite(port) || port <= 0) { console.error('Bad --port'); process.exit(64) }
+  const result = installClaudeHooks({ port, deskIdleSeconds: Number.isFinite(deskIdleSeconds) ? deskIdleSeconds : 90, dryRun })
+  print({ action, dryRun, serverApplies, ...(flagsNote ? { note: flagsNote } : {}), ...result })
+  process.exit(result.ok ? 0 : 2)
+}
+if (action === 'uninstall') {
+  const result = uninstallClaudeHooks({ dryRun })
+  print({ action, dryRun, ...result })
+  process.exit(result.ok ? 0 : 2)
+}
+console.error('Usage: --hooks install|status|uninstall [--dry-run] [--port N] [--desk-idle-s N]')
+process.exit(64)

package/server/lib/__fixtures__/query-jobs-6.43.3/2099-01-01.jsonl

@@ -1,2 +0,0 @@
-{"schemaVersion":1,"recordId":"02b09947-ed7d-47ef-99c5-4985af3ec924","partitionDay":"2099-01-01","persistedAt":"2099-01-01T12:00:00.000Z","bootId":"boot-6-43-3-fixture","jobId":"43b397bd-dd67-4312-9a5c-4c5d4b246f1d","clientJobId":"11111111-1111-4111-8111-111111111111","generation":2,"turnId":"a456fd1d-1e82-4b2d-8a20-5d34681201fd","requestFingerprint":"024966024134bf0d46090335da03a732a7fb7eaea161b1fd07dc4c5b9d536e95","eventSeq":1,"type":"accepted","status":"accepted","request":{"clientJobId":"11111111-1111-4111-8111-111111111111","generation":2,"query":"written by 6.43.3","sessionId":"session-6-43-3","model":"opus","effort":"high","cursorExecutionMode":"ask","messageEra":"era1","globalMsgNum":78,"reference":{"query":"earlier q","response":"earlier a"},"handoffCode":"ABCD","handoffLatest":true,"clientQueueItemId":"q1","attachmentIds":[],"attachmentRefs":[],"activityToolMode":"status"},"patch":{},"eventData":{"requestFingerprint":"024966024134bf0d46090335da03a732a7fb7eaea161b1fd07dc4c5b9d536e95"}}
-{"schemaVersion":1,"recordId":"a1145a40-2ced-4da3-9cf7-76d84cffc946","partitionDay":"2099-01-01","persistedAt":"2099-01-01T12:00:00.000Z","bootId":"boot-6-43-3-fixture","jobId":"64c5b502-13f2-4871-b6c4-007b91be2414","clientJobId":"22222222-2222-4222-8222-222222222222","generation":1,"turnId":"843e633f-0f92-4fe3-b2a1-9dc683715791","requestFingerprint":"91edfdeeb088e9fb3b1ffab4202bca02d3e7a23674d8b54dd51a50ce9adbf638","eventSeq":1,"type":"accepted","status":"accepted","request":{"clientJobId":"22222222-2222-4222-8222-222222222222","generation":1,"query":"minimal by 6.43.3","sessionId":"session-6-43-3-min","attachmentIds":[],"attachmentRefs":[],"activityToolMode":"status"},"patch":{},"eventData":{"requestFingerprint":"91edfdeeb088e9fb3b1ffab4202bca02d3e7a23674d8b54dd51a50ce9adbf638"}}