@gotcos/glasses-server 6.47.0 → 6.48.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 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.
+
+- `--hooks install|status|uninstall [--dry-run] [--port N]` writes fifteen hook subscriptions into `~/.claude/settings.json` (user level, so Desktop tabs, the CLI and `claude -p` jobs all report), preserving every existing hook block and every other key, with a backup of the file and an atomic 0600 write. The script is copied to the stable path `~/.cos-glasses/bin/cos-session-hook` so a server update never breaks it; `status` reports `script_outdated` when the package copy moved on and `install` re-copies. The same actions are on `POST /api/session-hooks/install` and `/uninstall` for COS Control. `status` also reports `disabled_by_settings` (the file carries `disableAllHooks`) and `settings_unreadable`, and `serverApplies` says whether the running server would read the spool into rows at all. A hooks install changes sessions started after it; tabs already open keep their startup snapshot until restarted. Removing the package does not remove the hooks: run `--hooks uninstall` first.
+- The hook is a POSIX sh script that writes one file per event into `~/.cos-glasses/data/hook-spool` and exits 0 on every path; it never talks to the server, so a session is never delayed by a server restart. It stops spooling when the spool holds 2,000 files or the server has not drained for a day, except permission requests. Only `PermissionRequest` may contact the server, and only after the desk has been idle (`ioreg` HIDIdleTime, default 90 s), for the broker that ships in 6.48.2; on 6.48.0 that call is refused (401) and the hook prints nothing, so the native dialog shows as before. An unreadable idle time never contacts the server.
+- The server ingests the spool (2 s sweep, `fs.watch` as a wake-up, bounded batches), keeps a projected ledger at `~/.cos-glasses/data/session-hook-events.jsonl` (10 MB rotation, replayed for the last 6 hours at boot), and reduces the events into one record per session. A pending permission clears only on evidence for that request (its own PostToolUse by fingerprint, a PermissionDenied naming the tool, Stop, a new prompt, SessionEnd; a parallel auto-allowed tool of the same name ending does not clear it); a Continue child that shares the tab's session id never changes the tab's state; a dead registry pid on two consecutive scans ends the row.
+- Rows on `/api/agent-sessions` (list and detail) and peers on `/api/claude-sessions` gain `agent_state` (running, waiting, idle, failed, ended), `state_source` (hook, registry, transcript), `state_since`, and when known `waiting_kind` (permission, question, plan, mcp_input), `waiting_detail` (the tool and its target), `failure`, and `last_reply` (the turn's last assistant message, 400 chars; the ledger keeps the same 400 chars of each prompt). `pending_permission_id` is reserved for the 6.48.2 broker and never set here. `state` keeps its old meaning and values. Older clients ignore the new keys.
+- `/api/health` gains `sessionHooks` (enabled, state, installed, scriptSha, tokenPresent, lastEventAt, spoolBacklog, spoolStuck, applyErrors, ledgerBytes, ledgerError and spoolError as codes, signals). A pending wait is also cleared by evidence the hooks cannot see: the registry moving on after it, the transcript moving on well after it, or nothing alive standing behind it for 30 minutes; an interrupted turn (no Stop fires) follows the registry to idle at once. `GET /api/session-hooks/runs?since=<ms>` lists the sessions the hooks saw start and end, for Control's scheduled-job ledger.
+- Flags: `COS_SESSION_HOOKS` (default on whenever `COS_CLAUDE_SESSIONS_ENABLED=1`; off still drains and stamps the spool and every row is exactly as 6.47.0), `COS_SESSION_HOOKS_SPOOL_DIR` (baked into the installed hook command together with the token directory, so the script and the server always agree; reinstall after changing it, `status` reports `drift` until then), `managed-runtime-contract.json` lists all six, and the reserved `COS_SESSION_HOOK_SSE`, `COS_PERMISSION_BROKER`, `COS_PERMISSION_BROKER_DESK_IDLE_S`, `COS_PERMISSION_BROKER_TIMEOUT_S` for the next releases. The next Control (0.5.231) adds all six to its runtime environment allowlist; until then a hand-set flag is dropped by Control's next Update Server, which is the fail-safe direction.
+- Fixtures under `server/lib/__fixtures__/session-hooks-6.48.0/` are real 2.1.272 recordings (paths redacted) and are excluded from the npm tarball. Recorded there: `SessionStart.source`, `SessionEnd.reason`, a `Stop` with no stop reason, a `PermissionRequest` with no `tool_use_id`, two permission hooks in one turn running one after the other, and a hook deny whose message reaches Claude with no `PermissionDenied` afterwards. Measured limit: an asynchronous hook that fires right before a print-mode process exits can be dropped by Claude (a `PostToolUse` in one recording, a `Stop` in another), so SessionStart, UserPromptSubmit, Stop and SessionEnd (the four events a row's state turns on) are installed synchronously with a 5 s timeout and were never dropped that way. The script itself is behaviour-tested under its own restricted PATH: spool naming, the 1 MiB cap, both B8 guards, the empty-token and closed-port paths, and a PermissionRequest round trip against a local listener.
+
 ## 6.47.0
 
 Meetings from Fireflies join the library, and recordings of the same meeting merge into one richer record. Paired Control build: 0.5.230. Glasses 6.9.474 adds Ref on the lens and needs no server change.

package/README.md

@@ -165,6 +165,30 @@ range is the exact Tailscale/CGNAT allocation (`100.64.0.0/10`), not all of
   `COS_WEATHER_DEFAULT_*`, otherwise omits weather. Optional `nextEvent`
   appears when `COS_SCRIPTS_DIR` calendar data is available.
 
+## Session hooks (6.48.0)
+
+Claude Code can tell the server what each session is doing (started, prompt submitted,
+waiting on a permission, turn stopped, ended) through its own hooks. Install them once:
+
+```bash
+npx --yes @gotcos/glasses-server@latest --hooks install --dry-run   # shows the merge, writes nothing
+npx --yes @gotcos/glasses-server@latest --hooks install             # merges into ~/.claude/settings.json
+npx --yes @gotcos/glasses-server@latest --hooks status
+npx --yes @gotcos/glasses-server@latest --hooks uninstall
+```
+
+The install keeps every hook you already had, backs the file up, and copies a small
+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`
+(`--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.
+
 ## Configuration
 
 Config lives at `~/.cos-glasses/.env` (created on first run). Every key is

package/bin/cli.cjs

@@ -27,6 +27,7 @@ const CONFIG_DIR = join(homedir(), '.cos-glasses')
 const PREPARE_ONLY = process.argv.includes('--prepare-only')
 const SETUP_TRANSCRIPTION = process.argv.includes('--setup-transcription')
 const SETUP_SPEAKER_MODEL = process.argv.includes('--setup-speaker-model')
+const HOOKS_ACTION = process.argv.includes('--hooks') ? process.argv[process.argv.indexOf('--hooks') + 1] : undefined
 function optionValue(name) {
   const index = process.argv.indexOf(name)
   return index >= 0 ? process.argv[index + 1] : undefined
@@ -145,6 +146,26 @@ function setupSpeakerModel() {
   return 0
 }
 
+// --hooks install|status|uninstall: the Claude Code session hook (6.48.0). Runs before the
+// banner and the runtime checks, resolving tsx itself; the managed runtime never comes
+// through here (Control uses POST /api/session-hooks/install on the running server).
+if (process.argv.includes('--hooks')) {
+  if (!['install', 'status', 'uninstall'].includes(HOOKS_ACTION)) {
+    console.error('Usage: --hooks install|status|uninstall [--dry-run] [--port N]')
+    process.exit(64)
+  }
+  let hooksTsx
+  try {
+    hooksTsx = require.resolve('tsx/esm', { paths: [PKG_ROOT] })
+  } catch {
+    console.error('COS package dependencies are incomplete; run npm install in the package first.')
+    process.exit(2)
+  }
+  const rest = process.argv.slice(process.argv.indexOf('--hooks') + 1)
+  const child = require('child_process').spawnSync(process.execPath, ['--import', hooksTsx, join(PKG_ROOT, 'server', 'scripts', 'hooks-cli.ts'), ...rest], { cwd: PKG_ROOT, stdio: 'inherit' })
+  process.exit(child.status ?? 1)
+}
+
 if (SETUP_SPEAKER_MODEL) {
   console.log('')
   console.log(bold('  COS Glasses - voiceprint model'))
@@ -162,6 +183,7 @@ if (process.argv.includes('--help') || process.argv.includes('-h')) {
   console.log('    npx --yes @gotcos/glasses-server@latest --setup-transcription --transcription-tier balanced|max')
   console.log('    npx --yes @gotcos/glasses-server@latest --setup-speaker-model')
   console.log('    npx --yes @gotcos/glasses-server@latest --prepare-only')
+  console.log('    npx --yes @gotcos/glasses-server@latest --hooks install|status|uninstall [--dry-run] [--port N]')
   console.log('')
   console.log('  Requirements:')
   console.log('    - Node.js 20.11+')

package/bin/hooks/cos-session-hook

@@ -0,0 +1,43 @@
+#!/bin/sh
+# COS session hook (glasses-server 6.48.0). Installed into ~/.claude/settings.json by
+# `--hooks install`; Claude Code runs it with the hook event name as $1 and the event
+# payload on stdin. It spools one JSON file per event into the hook spool and exits 0
+# on every path. Only PermissionRequest ever talks to the server, and only when the
+# desk has been idle. Everything else is a file write, so the server being down or
+# restarting never delays a Claude session.
+#
+# The installer bakes COS_GLASSES_HOME and COS_HOOK_SPOOL into the command, so this
+# script and the server can never disagree about where the token or the spool is.
+PATH=/usr/bin:/bin:/usr/sbin; umask 077; trap '' PIPE
+HOME=${HOME:-$(cd ~ 2>/dev/null && pwd)}; [ -n "$HOME" ] || exit 0
+GH=${COS_GLASSES_HOME:-$HOME/.cos-glasses}
+SPOOL=${COS_HOOK_SPOOL:-$GH/data/hook-spool}; EVENT="$1"
+mkdir -p "$SPOOL/rejected" 2>/dev/null || exit 0
+TS=$(perl -MTime::HiRes -e 'printf "%.0f", Time::HiRes::time()*1000' 2>/dev/null || date +%s000)
+# B8 guard: a full spool or a stale drain stamp means nobody is reading; keep only permissions.
+if [ "$EVENT" != PermissionRequest ]; then
+  N=$(ls "$SPOOL" 2>/dev/null | wc -l | tr -d ' '); [ "${N:-0}" -lt 2000 ] || exit 0
+  STAMP="$SPOOL/.last-drain"; [ ! -f "$STAMP" ] || [ -z "$(find "$STAMP" -mmin +1440 2>/dev/null)" ] || exit 0   # -mtime +1 would mean two days
+fi
+T="$SPOOL/.tmp.$$.$TS"; head -c 1048576 > "$T.in"                    # stdin to disk, 1 MiB cap
+case "$(head -c 1 "$T.in")" in '{') ;; *) EVENT=rejected ;; esac
+{ printf '{"ts":%s,"ppid":%s,"event":"%s","payload":' "$TS" "$PPID" "$EVENT"; cat "$T.in"; printf '}\n'; } > "$T"
+rm -f "$T.in"
+if [ "$EVENT" != PermissionRequest ]; then mv "$T" "$SPOOL/$TS-$$-$EVENT.json"; exit 0; fi   # rename = publish
+# A permission request keeps its own copy: the server unlinks the published file within
+# milliseconds of the rename, and the request body below must outlive that.
+cp "$T" "$T.req" 2>/dev/null; mv "$T" "$SPOOL/$TS-$$-$EVENT.json"
+cleanup() { rm -f "$T.req"; }
+# Desk-active fast path decided HERE (about 30 ms): no HTTP at all when someone is at the
+# keyboard. An unreadable idle time fails the same way: nothing is contacted, the native
+# dialog shows.
+IDLE_NS=$(ioreg -c IOHIDSystem 2>/dev/null | awk -F'= ' '/HIDIdleTime/{print $2; exit}')
+DESK_S=$(cat "$GH/hook-desk-idle-s" 2>/dev/null || echo 90)
+{ [ -n "$IDLE_NS" ] && [ "$(( ${IDLE_NS%.*} / 1000000000 ))" -ge "$DESK_S" ]; } || { cleanup; exit 0; }
+TOK=$(cat "$GH/hook-token" 2>/dev/null); [ -n "$TOK" ] || { cleanup; exit 0; }   # no token, no request
+PORT=$(cat "$GH/hook-port" 2>/dev/null || echo 3141)
+OUT=$(curl -s --connect-timeout 2 --max-time 125 -H "X-Cos-Hook-Token: $TOK" -H 'content-type: application/json' \
+  --data-binary @"$T.req" "http://127.0.0.1:$PORT/api/permission-requests/ask") || { cleanup; exit 0; }
+cleanup
+case "$OUT" in '{"hookSpecificOutput"'*) printf '%s' "$OUT" ;; esac
+exit 0

package/managed-runtime-contract.json

@@ -26,7 +26,13 @@
     "COS_UNSAVED_AUDIO_RETENTION_HOURS",
     "COS_CLAUDE_TRUST_MODE",
     "COS_CODEX_SANDBOX",
-    "COS_SCRIPTS_DIR"
+    "COS_SCRIPTS_DIR",
+    "COS_SESSION_HOOKS",
+    "COS_SESSION_HOOKS_SPOOL_DIR",
+    "COS_SESSION_HOOK_SSE",
+    "COS_PERMISSION_BROKER",
+    "COS_PERMISSION_BROKER_DESK_IDLE_S",
+    "COS_PERMISSION_BROKER_TIMEOUT_S"
   ],
   "maintenance": {
     "scope": "cross_boot",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotcos/glasses-server",
-  "version": "6.47.0",
+  "version": "6.48.0",
   "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": {
@@ -29,6 +29,7 @@
   "files": [
     "bin/cli.cjs",
     "bin/managed-server.cjs",
+    "bin/hooks/cos-session-hook",
     "managed-runtime-contract.json",
     "server",
     "!server/data/**",
@@ -40,6 +41,7 @@
     "!server/scripts/engine-canary.ts",
     "!server/scripts/mutation-gate.mjs",
     "!server/lib/meeting-engine/__fixtures__/**",
+    "!server/lib/__fixtures__/**",
     "!shared/**/*.test.ts",
     ".env.example",
     ".cos-profile.example.json",

package/server/index.ts

@@ -22,6 +22,8 @@ import { agentSessionsRouter } from './routes/agent-sessions.js'
 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 {
   createAgentSessionBindingsRouter,
   TargetGuard,
@@ -382,6 +384,11 @@ const attachedWorkspaceDeps = realAttachedWorkspaceDeps(nativeHeadDeps)
  */
 const occupancyProbes = 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
+// ledger. With COS_SESSION_HOOKS off it still drains and stamps the spool (see the module).
+const sessionHooksRuntime = startSessionHooksRuntime({ port: PORT })
+
 /**
  * The shim between the route's request shape and the adapter's.
  *
@@ -537,6 +544,7 @@ app.use('/api', agentSessionStreamRouter)
 // 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)
+app.use('/api', createSessionHooksRouter({ port: PORT }))
 // 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
@@ -760,6 +768,7 @@ async function gracefulShutdown(): Promise<void> {
   stopMorningBriefScheduler()
   stopMeetingImportScheduler()
   stopMeetingMergeScheduler()
+  sessionHooksRuntime.stop()
   try {
     await shutdownQueryJobRuntime('server_shutdown')
   } catch (error) {

package/server/lib/claude-hooks-installer.ts

@@ -0,0 +1,403 @@
+// Installing the COS session hook into `~/.claude/settings.json`, and knowing whether it
+// is installed.
+//
+// USER LEVEL ONLY. Hooks in `~/.claude/settings.json` fire for every Claude Code session
+// on this Mac (Desktop tabs, the CLI, `claude -p` jobs). The project-level file the COS
+// repo owns (seven memory and canvas hooks) is never touched; Claude merges levels, so
+// both sets run.
+//
+// THE MERGE IS A PURE FUNCTION over the settings object (`mergeHookSettings`), tested
+// against the real file's shape: keep every block whose commands do not name our script,
+// drop every block that does, append one canonical block per subscribed event. Other
+// events and every other top-level key pass through untouched. Nothing is written when
+// the merged object equals the current one.
+//
+// STABLE PATH. The script is copied from the package (`bin/hooks/cos-session-hook`) to
+// `~/.cos-glasses/bin/cos-session-hook`, because the managed runtime's generation
+// directory changes on every server update and a settings file pointing into it would
+// break at the first Update Server. `status` reports `script_outdated` when the package
+// copy differs from the installed one, and `install` re-copies.
+
+import { copyFileSync, chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { createHash, randomBytes } from 'node:crypto'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { atomicWriteFileSync } from './atomic-fs.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+/** Substring that marks a hook block as ours, whatever the home directory is. */
+export const HOOK_SCRIPT_MARKER = '/.cos-glasses/bin/cos-session-hook'
+export const HOOK_SCRIPT_NAME = 'cos-session-hook'
+
+export interface HookSubscription {
+  event: string
+  matcher?: string
+  async: boolean
+  timeout: number
+}
+
+/**
+ * Every event the reducer understands, with the timing each one needs. SessionStart,
+ * UserPromptSubmit, Stop and SessionEnd are synchronous: measured 2026-09-15, an async
+ * Stop was dropped when a print-mode process exited right after it (PostToolUse landed,
+ * Stop did not), and those four carry the transitions a row is derived from (a dropped
+ * UserPromptSubmit would leave a running turn reading idle). The write is a few
+ * milliseconds. PermissionRequest must be synchronous to return a decision; the rest
+ * are fire-and-forget.
+ */
+export const HOOK_SUBSCRIPTIONS: readonly HookSubscription[] = [
+  { event: 'SessionStart', async: false, timeout: 5 },
+  { event: 'SessionEnd', async: false, timeout: 5 },
+  { event: 'UserPromptSubmit', async: false, timeout: 5 },
+  { event: 'Stop', async: false, timeout: 5 },
+  { event: 'StopFailure', async: true, timeout: 10 },
+  { event: 'PermissionRequest', async: false, timeout: 130 },
+  { event: 'PermissionDenied', async: true, timeout: 10 },
+  { event: 'PreToolUse', matcher: 'AskUserQuestion|ExitPlanMode', async: true, timeout: 10 },
+  { event: 'PostToolUse', async: true, timeout: 10 },
+  { event: 'PostToolUseFailure', async: true, timeout: 10 },
+  { event: 'Notification', matcher: 'permission_prompt|idle_prompt|elicitation_dialog|agent_needs_input', async: true, timeout: 10 },
+  { event: 'SubagentStart', async: true, timeout: 10 },
+  { event: 'SubagentStop', async: true, timeout: 10 },
+  { event: 'PostCompact', async: true, timeout: 10 },
+  { event: 'PostModelSwitch', async: true, timeout: 10 },
+]
+
+/**
+ * Where the token, port and spool live. Derived from `COS_DATA_DIR` when that is set, so
+ * a scratch server booted with a temp data dir never touches the production files under
+ * `~/.cos-glasses` (it did once, in review). `COS_GLASSES_HOME` overrides for tests.
+ */
+export function cosGlassesHome(): string {
+  if (process.env.COS_GLASSES_HOME) return resolve(process.env.COS_GLASSES_HOME)
+  if (process.env.COS_DATA_DIR) return dirname(resolve(process.env.COS_DATA_DIR))
+  return join(homedir(), '.cos-glasses')
+}
+
+/** The spool the server drains; baked into the installed command so the script agrees. */
+export function hookSpoolDir(): string {
+  if (process.env.COS_SESSION_HOOKS_SPOOL_DIR) return resolve(process.env.COS_SESSION_HOOKS_SPOOL_DIR)
+  return join(process.env.COS_DATA_DIR ? resolve(process.env.COS_DATA_DIR) : join(cosGlassesHome(), 'data'), 'hook-spool')
+}
+
+export function claudeSettingsPath(): string {
+  const configDir = process.env.CLAUDE_CONFIG_DIR ? resolve(process.env.CLAUDE_CONFIG_DIR) : join(homedir(), '.claude')
+  return join(configDir, 'settings.json')
+}
+
+export function stableHookScriptPath(): string {
+  return join(cosGlassesHome(), 'bin', HOOK_SCRIPT_NAME)
+}
+
+/** The copy shipped in this package. */
+export function packagedHookScriptPath(): string {
+  return resolve(__dirname, '..', '..', 'bin', 'hooks', HOOK_SCRIPT_NAME)
+}
+
+export function hookTokenPath(): string { return join(cosGlassesHome(), 'hook-token') }
+export function hookPortPath(): string { return join(cosGlassesHome(), 'hook-port') }
+export function hookDeskIdlePath(): string { return join(cosGlassesHome(), 'hook-desk-idle-s') }
+
+/** sh-safe quoting for the settings command string. Paths with spaces get single quotes. */
+export function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_\-./]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/**
+ * The installed command carries the two paths the script needs as environment, so the
+ * server and the script can never disagree about where the spool or the token is.
+ */
+export function hookCommand(scriptPath: string, event: string, paths: HookPaths = currentHookPaths()): string {
+  return `COS_GLASSES_HOME=${shellQuote(paths.home)} COS_HOOK_SPOOL=${shellQuote(paths.spoolDir)} ${shellQuote(scriptPath)} ${event}`
+}
+
+export interface HookPaths {
+  home: string
+  spoolDir: string
+}
+
+export function currentHookPaths(): HookPaths {
+  return { home: cosGlassesHome(), spoolDir: hookSpoolDir() }
+}
+
+type HookBlock = { matcher?: unknown; hooks?: unknown }
+
+function blockIsOurs(block: unknown): boolean {
+  if (!block || typeof block !== 'object') return false
+  const hooks = (block as HookBlock).hooks
+  if (!Array.isArray(hooks)) return false
+  return hooks.some(h => h && typeof h === 'object' && typeof (h as { command?: unknown }).command === 'string'
+    && ((h as { command: string }).command.includes(HOOK_SCRIPT_MARKER) || (h as { command: string }).command.includes(HOOK_SCRIPT_NAME + ' ')))
+}
+
+function canonicalBlock(scriptPath: string, sub: HookSubscription, paths: HookPaths): Record<string, unknown> {
+  const hook: Record<string, unknown> = { type: 'command', command: hookCommand(scriptPath, sub.event, paths), timeout: sub.timeout }
+  if (sub.async) hook.async = true
+  return sub.matcher ? { matcher: sub.matcher, hooks: [hook] } : { hooks: [hook] }
+}
+
+export type MergeResult =
+  | { ok: true; settings: Record<string, unknown>; changed: boolean }
+  /** The file holds a `hooks` shape this merge would have to destroy to proceed. */
+  | { ok: false; reason: 'settings_hooks_invalid' }
+
+/**
+ * Pure. Adds or refreshes our blocks; every foreign block and key survives in order. A
+ * `hooks` key that is not an object, or an event whose value is not an array, is refused
+ * rather than replaced: "preserving every existing hook block" is the contract.
+ */
+export function mergeHookSettings(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths()): MergeResult {
+  const settings: Record<string, unknown> = current && typeof current === 'object' && !Array.isArray(current) ? { ...(current as Record<string, unknown>) } : {}
+  const before = JSON.stringify(settings)
+  if (settings.hooks !== undefined && (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks))) return { ok: false, reason: 'settings_hooks_invalid' }
+  const hooksIn = (settings.hooks ?? {}) as Record<string, unknown>
+  const hooks: Record<string, unknown> = { ...hooksIn }
+  for (const sub of HOOK_SUBSCRIPTIONS) {
+    const value = hooks[sub.event]
+    if (value !== undefined && !Array.isArray(value)) return { ok: false, reason: 'settings_hooks_invalid' }
+    const existing = Array.isArray(value) ? value : []
+    const foreign = existing.filter(b => !blockIsOurs(b))
+    hooks[sub.event] = [...foreign, canonicalBlock(scriptPath, sub, paths)]
+  }
+  settings.hooks = hooks
+  return { ok: true, settings, changed: JSON.stringify(settings) !== before }
+}
+
+/** Pure. Removes our blocks; emptied event arrays are deleted, everything else survives. */
+export function stripHookSettings(current: unknown): MergeResult {
+  const settings: Record<string, unknown> = current && typeof current === 'object' && !Array.isArray(current) ? { ...(current as Record<string, unknown>) } : {}
+  const before = JSON.stringify(settings)
+  const hooksIn = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks) ? settings.hooks as Record<string, unknown> : null
+  if (!hooksIn) return { ok: true, settings, changed: false }
+  const hooks: Record<string, unknown> = {}
+  for (const [event, blocks] of Object.entries(hooksIn)) {
+    if (!Array.isArray(blocks)) { hooks[event] = blocks; continue }
+    const foreign = blocks.filter(b => !blockIsOurs(b))
+    if (foreign.length > 0) hooks[event] = foreign
+  }
+  settings.hooks = hooks
+  return { ok: true, settings, changed: JSON.stringify(settings) !== before }
+}
+
+/** Which of our events a settings object carries, by exact canonical command. */
+export function subscribedEvents(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths()): { subscribed: string[]; missing: string[]; drifted: string[] } {
+  const hooks = current && typeof current === 'object' && (current as Record<string, unknown>).hooks
+  const table = hooks && typeof hooks === 'object' ? hooks as Record<string, unknown> : {}
+  const subscribed: string[] = []
+  const missing: string[] = []
+  const drifted: string[] = []
+  for (const sub of HOOK_SUBSCRIPTIONS) {
+    const blocks = Array.isArray(table[sub.event]) ? table[sub.event] as unknown[] : []
+    const ours = blocks.filter(blockIsOurs)
+    if (ours.length === 0) { missing.push(sub.event); continue }
+    const canonical = JSON.stringify(canonicalBlock(scriptPath, sub, paths))
+    if (ours.length === 1 && JSON.stringify(ours[0]) === canonical) subscribed.push(sub.event)
+    else drifted.push(sub.event)
+  }
+  return { subscribed, missing, drifted }
+}
+
+export type HookInstallState =
+  | 'installed'
+  | 'drift'
+  | 'missing'
+  | 'script_outdated'
+  /** The user-level file carries `disableAllHooks: true`: installed or not, nothing fires. */
+  | 'disabled_by_settings'
+  | 'settings_unparseable'
+  | 'settings_symlink'
+  /** The file exists but could not be read (EACCES, ELOOP, ENOTDIR): not "missing". */
+  | 'settings_unreadable'
+
+export interface HookStatus {
+  state: HookInstallState
+  /** True only for `installed`: the boolean Control's banner keys off. */
+  installed: boolean
+  settingsPath: string
+  scriptPath: string
+  scriptSha: string | null
+  packageScriptSha: string | null
+  subscribed: string[]
+  missing: string[]
+  drifted: string[]
+  tokenPresent: boolean
+}
+
+function sha256File(path: string): string | null {
+  try { return createHash('sha256').update(readFileSync(path)).digest('hex') } catch { return null }
+}
+
+type SettingsRead = { ok: true; settings: unknown; existed: boolean } | { ok: false; reason: 'settings_unparseable' | 'settings_symlink' | 'settings_unreadable' }
+
+function readSettings(path: string): SettingsRead {
+  try {
+    if (lstatSync(path).isSymbolicLink()) return { ok: false, reason: 'settings_symlink' }
+  } catch (error) {
+    // Only "no such file" is missing. Anything else is a file that could not be looked at,
+    // and "I could not look" must never render as "it is not there".
+    if ((error as { code?: string }).code === 'ENOENT') return { ok: true, settings: {}, existed: false }
+    return { ok: false, reason: 'settings_unreadable' }
+  }
+  let text: string
+  try { text = readFileSync(path, 'utf-8') } catch { return { ok: false, reason: 'settings_unreadable' } }
+  try {
+    return { ok: true, settings: JSON.parse(text), existed: true }
+  } catch {
+    return { ok: false, reason: 'settings_unparseable' }
+  }
+}
+
+function hooksDisabled(settings: unknown): boolean {
+  return !!settings && typeof settings === 'object' && (settings as { disableAllHooks?: unknown }).disableAllHooks === true
+}
+
+export function hookStatus(paths: { settingsPath?: string; scriptPath?: string; packageScriptPath?: string; hookPaths?: HookPaths } = {}): HookStatus {
+  const settingsPath = paths.settingsPath ?? claudeSettingsPath()
+  const scriptPath = paths.scriptPath ?? stableHookScriptPath()
+  const packageScriptPath = paths.packageScriptPath ?? packagedHookScriptPath()
+  const hookPaths = paths.hookPaths ?? currentHookPaths()
+  const scriptSha = sha256File(scriptPath)
+  const packageScriptSha = sha256File(packageScriptPath)
+  const tokenPresent = existsSync(hookTokenPath())
+  const read = readSettings(settingsPath)
+  if (!read.ok) {
+    return { state: read.reason, installed: false, settingsPath, scriptPath, scriptSha, packageScriptSha, subscribed: [], missing: HOOK_SUBSCRIPTIONS.map(s => s.event), drifted: [], tokenPresent }
+  }
+  const events = subscribedEvents(read.settings, scriptPath, hookPaths)
+  let state: HookInstallState
+  if (hooksDisabled(read.settings)) state = 'disabled_by_settings'
+  else if (events.subscribed.length === 0 && events.drifted.length === 0) state = 'missing'
+  else if (events.missing.length > 0 || events.drifted.length > 0) state = 'drift'
+  else if (!scriptSha || (packageScriptSha && scriptSha !== packageScriptSha)) state = 'script_outdated'
+  else state = 'installed'
+  return { state, installed: state === 'installed', settingsPath, scriptPath, scriptSha, packageScriptSha, ...events, tokenPresent }
+}
+
+export interface InstallOptions {
+  settingsPath?: string
+  scriptPath?: string
+  packageScriptPath?: string
+  hookPaths?: HookPaths
+  port?: number
+  deskIdleSeconds?: number
+  dryRun?: boolean
+}
+
+export interface InstallResult {
+  ok: boolean
+  reason?: string
+  changed: boolean
+  scriptCopied: boolean
+  backupPath: string | null
+  status: HookStatus
+  /** The merged settings, for `--dry-run` to print. */
+  merged?: Record<string, unknown>
+}
+
+const BACKUPS_KEPT = 3
+
+function backupSettings(settingsPath: string): string | null {
+  if (!existsSync(settingsPath)) return null
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-')
+  const backup = `${settingsPath}.cos-backup-${stamp}`
+  try {
+    copyFileSync(settingsPath, backup)
+    chmodSync(backup, 0o600)
+  } catch { return null }
+  try {
+    const dir = dirname(settingsPath)
+    const prefix = `${settingsPath.slice(dir.length + 1)}.cos-backup-`
+    const olds = readdirSync(dir).filter(n => n.startsWith(prefix)).sort()
+    for (const old of olds.slice(0, Math.max(0, olds.length - BACKUPS_KEPT))) {
+      try { unlinkSync(join(dir, old)) } catch { /* fine */ }
+    }
+  } catch { /* the backup itself succeeded */ }
+  return backup
+}
+
+/** Mint the per-install token once (0600, atomically); write port and desk-idle files every time. */
+export function ensureHookRuntimeFiles(port: number, deskIdleSeconds: number): void {
+  const home = cosGlassesHome()
+  mkdirSync(home, { recursive: true, mode: 0o700 })
+  if (!existsSync(hookTokenPath())) atomicWriteFileSync(hookTokenPath(), randomBytes(32).toString('hex'), { mode: 0o600 })
+  atomicWriteFileSync(hookPortPath(), String(port), { mode: 0o600 })
+  atomicWriteFileSync(hookDeskIdlePath(), String(Math.max(0, Math.trunc(deskIdleSeconds))), { mode: 0o600 })
+}
+
+export function readHookToken(): string | null {
+  try { return readFileSync(hookTokenPath(), 'utf-8').trim() || null } catch { return null }
+}
+
+/**
+ * Copy the packaged script to the stable path when it differs (`install`), or only when it
+ * is missing (`onlyIfMissing`, used at boot: an older server booting must never downgrade
+ * the script a newer `install` put there, since every Claude session on the Mac runs it).
+ * Returns true when copied.
+ */
+export function ensureStableHookScript(scriptPath = stableHookScriptPath(), packageScriptPath = packagedHookScriptPath(), onlyIfMissing = false): boolean {
+  const want = sha256File(packageScriptPath)
+  if (!want) throw new Error(`hook script missing from the package at ${packageScriptPath}`)
+  const have = sha256File(scriptPath)
+  if (have === want) return false
+  if (have && onlyIfMissing) return false
+  mkdirSync(dirname(scriptPath), { recursive: true, mode: 0o755 })
+  atomicWriteFileSync(scriptPath, readFileSync(packageScriptPath), { mode: 0o755 })
+  chmodSync(scriptPath, 0o755)
+  return true
+}
+
+export function installClaudeHooks(options: InstallOptions = {}): InstallResult {
+  const settingsPath = options.settingsPath ?? claudeSettingsPath()
+  const scriptPath = options.scriptPath ?? stableHookScriptPath()
+  const packageScriptPath = options.packageScriptPath ?? packagedHookScriptPath()
+  const hookPaths = options.hookPaths ?? currentHookPaths()
+  const read = readSettings(settingsPath)
+  const statusNow = () => hookStatus({ settingsPath, scriptPath, packageScriptPath, hookPaths })
+  const refuse = (reason: string, scriptCopied = false): InstallResult => ({ ok: false, reason, changed: false, scriptCopied, backupPath: null, status: statusNow() })
+  if (!read.ok) return refuse(read.reason)
+  const merged = mergeHookSettings(read.settings, scriptPath, hookPaths)
+  if (!merged.ok) return refuse(merged.reason)
+  if (options.dryRun) {
+    return { ok: true, changed: merged.changed, scriptCopied: false, backupPath: null, status: statusNow(), merged: merged.settings }
+  }
+  let scriptCopied = false
+  try {
+    scriptCopied = ensureStableHookScript(scriptPath, packageScriptPath)
+    ensureHookRuntimeFiles(options.port ?? 3141, options.deskIdleSeconds ?? 90)
+  } catch (error) {
+    return refuse(error instanceof Error ? error.message : String(error), scriptCopied)
+  }
+  let backupPath: string | null = null
+  if (merged.changed) {
+    if (read.existed) {
+      backupPath = backupSettings(settingsPath)
+      // No backup, no overwrite: "with a backup of the file" is the contract.
+      if (!backupPath) return refuse('backup_failed', scriptCopied)
+    }
+    mkdirSync(dirname(settingsPath), { recursive: true, mode: 0o700 })
+    atomicWriteFileSync(settingsPath, JSON.stringify(merged.settings, null, 2) + '\n', { mode: 0o600 })
+  }
+  return { ok: true, changed: merged.changed, scriptCopied, backupPath, status: statusNow() }
+}
+
+export function uninstallClaudeHooks(options: Pick<InstallOptions, 'settingsPath' | 'scriptPath' | 'packageScriptPath' | 'hookPaths' | 'dryRun'> = {}): InstallResult {
+  const settingsPath = options.settingsPath ?? claudeSettingsPath()
+  const scriptPath = options.scriptPath ?? stableHookScriptPath()
+  const packageScriptPath = options.packageScriptPath ?? packagedHookScriptPath()
+  const hookPaths = options.hookPaths ?? currentHookPaths()
+  const read = readSettings(settingsPath)
+  const statusNow = () => hookStatus({ settingsPath, scriptPath, packageScriptPath, hookPaths })
+  if (!read.ok) return { ok: false, reason: read.reason, changed: false, scriptCopied: false, backupPath: null, status: statusNow() }
+  const stripped = stripHookSettings(read.settings)
+  if (!stripped.ok) return { ok: false, reason: stripped.reason, changed: false, scriptCopied: false, backupPath: null, status: statusNow() }
+  if (options.dryRun) return { ok: true, changed: stripped.changed, scriptCopied: false, backupPath: null, status: statusNow(), merged: stripped.settings }
+  let backupPath: string | null = null
+  if (stripped.changed) {
+    backupPath = backupSettings(settingsPath)
+    if (!backupPath) return { ok: false, reason: 'backup_failed', changed: false, scriptCopied: false, backupPath: null, status: statusNow() }
+    atomicWriteFileSync(settingsPath, JSON.stringify(stripped.settings, null, 2) + '\n', { mode: 0o600 })
+  }
+  return { ok: true, changed: stripped.changed, scriptCopied: false, backupPath, status: statusNow() }
+}