@gotcos/glasses-server 7.0.7 → 7.0.18

package/server/lib/drop-service.ts

@@ -97,7 +97,21 @@ const filesLine = (n: number): string => n === 1 ? 'The file stays here in the C
 const nextAsk = (drop: DropRecord): DropNextAsk =>
   ({ kind: 'ask', prompt: drop.text, ...(drop.attachments?.length ? { attachmentIds: drop.attachments.map(a => a.id) } : {}) })
 /** One item that waits on an answer: a live question, or a live item marked needsReply (6.99.10). */
-export const isWaiting = (i: FeedItem): boolean => i.state === 'live' && (i.kind === 'question' || i.needsReply === true)
+/**
+ * 7.0.9 (Miles 11/08, "Expire after 7 days"): an item that asks for a reply stops waiting on you this long after it
+ * was asked (its own createdAt, never when it was read). It is not answered or closed: it moves to the chat's older
+ * questions (GET /api/inbox/archive), where it can still be read and answered, and answering it there clears it.
+ * The one rule for every count: `asked`, the chat part of `waiting`, `archived`, and the web's split.
+ */
+export const WAITING_EXPIRY_DAYS = 7
+export const WAITING_EXPIRY_MS = WAITING_EXPIRY_DAYS * 86_400_000
+const asksForReply = (i: FeedItem): boolean => i.state === 'live' && (i.kind === 'question' || i.needsReply === true)
+/** How long ago it was asked, in ms; an unreadable time reads as just asked (it keeps waiting rather than vanish). */
+const askedAgo = (i: FeedItem, nowMs: number): number => { const t = Date.parse(i.createdAt); return Number.isFinite(t) ? nowMs - t : 0 }
+export const isWaiting = (i: FeedItem, nowMs: number = Date.now()): boolean => asksForReply(i) && askedAgo(i, nowMs) < WAITING_EXPIRY_MS
+/** Asks for a reply, but was asked WAITING_EXPIRY_DAYS or more ago: shown under older questions, never counted. */
+export const isArchivedQuestion = (i: FeedItem, nowMs: number = Date.now()): boolean => asksForReply(i) && askedAgo(i, nowMs) >= WAITING_EXPIRY_MS
+export const ARCHIVE_LIST_MAX = 200
 const A = {
   undo: { id: 'undo', label: 'Undo' }, move: { id: 'move', label: 'Move' },
   openCard: { id: 'open_card', label: 'Open card' }, openThread: { id: 'open_thread', label: 'Open thread' },
@@ -559,14 +573,24 @@ export class DropService {
    * waits on an answer from you, and clears only when it is answered, done or dismissed: every live question COS asked
    * (a router ask), every live item marked `needsReply` (a follow-up that needs a decision, a ping that asks), plus
    * `yourMove`, the Work items in Your move, when the caller could count them. Always a whole number, never negative.
+   *
+   * 7.0.9 (Miles 11/08: the web rail said 99+ and the pinned row "286 waiting" for things he had already seen): two
+   * more fields, so a client can say what each number is. `asked` is the chat's own part of `waiting`, the live
+   * questions and needsReply items, which truly wait on a reply in this chat. `yourMove` is the Work part (null when
+   * it could not be counted). `waiting` keeps its 6.99.10 meaning for COS Control, which reads it by that name.
    */
-  summary(extra: { yourMove?: number | null } = {}): { unread: number; waiting: number; lastLine: string; lastAt: string | null; version: number } {
+  summary(extra: { yourMove?: number | null } = {}): { unread: number; waiting: number; asked: number; archived: number; waitingExpiryDays: number; yourMove: number | null; lastLine: string; lastAt: string | null; version: number } {
     const items = this.deps.feed.list()
+    const nowMs = this.now().getTime()
     const unread = items.filter(i => i.readAt === null && (i.kind === 'ping' || i.kind === 'followup' || i.kind === 'question')).length
-    const asked = items.filter(i => isWaiting(i)).length
-    const work = typeof extra.yourMove === 'number' && Number.isSafeInteger(extra.yourMove) && extra.yourMove > 0 ? extra.yourMove : 0
+    // 7.0.9: a question asked WAITING_EXPIRY_DAYS ago or more is in older questions, out of `asked` and so out of the
+    // chat part of `waiting`. Work's part of `waiting` (yourMove) is untouched.
+    const asked = items.filter(i => isWaiting(i, nowMs)).length
+    const archived = items.filter(i => isArchivedQuestion(i, nowMs)).length
+    const counted = typeof extra.yourMove === 'number' && Number.isSafeInteger(extra.yourMove) && extra.yourMove >= 0
+    const work = counted && (extra.yourMove as number) > 0 ? extra.yourMove as number : 0
     const last = items[items.length - 1]
-    return { unread, waiting: asked + work, lastLine: last ? short(pinLine(last), 120) : '', lastAt: last?.createdAt ?? null, version: this.deps.feed.version() }
+    return { unread, waiting: asked + work, asked, archived, waitingExpiryDays: WAITING_EXPIRY_DAYS, yourMove: counted ? extra.yourMove as number : null, lastLine: last ? short(pinLine(last), 120) : '', lastAt: last?.createdAt ?? null, version: this.deps.feed.version() }
   }
 
   /**
@@ -574,7 +598,7 @@ export class DropService {
    * its buttons. Only an item marked `needsReply` can be dismissed; a question is answered by one of its choices
    * (Just a note among them). Idempotent: a second dismiss answers the same.
    */
-  dismiss(itemId: string): { unread: number; waiting: number; version: number } {
+  dismiss(itemId: string): { unread: number; waiting: number; asked: number; version: number } {
     const item = this.deps.feed.get(itemId)
     if (!item) throw new DropError('feed_item_not_found', 404)
     if (!item.needsReply) throw new DropError('not_dismissable', 409, 'Only something that waits on you can be dismissed.')
@@ -583,11 +607,21 @@ export class DropService {
       this.deps.feed.update(new Set([item.id]), i => ({ ...i, state: 'done', actions: [], readAt: i.readAt ?? at }))
     }
     const s = this.summary()
-    return { unread: s.unread, waiting: s.waiting, version: s.version }
+    return { unread: s.unread, waiting: s.waiting, asked: s.asked, version: s.version }
+  }
+
+  /**
+   * 7.0.9: the older questions, newest first: what still asks for a reply but was asked WAITING_EXPIRY_DAYS or more
+   * ago. Each answers exactly as in the chat (POST /api/inbox/action), and answering it takes it off this list.
+   */
+  archive(): { items: Array<FeedItem & { archived: true }>; total: number; waitingExpiryDays: number; version: number } {
+    const nowMs = this.now().getTime()
+    const all = this.deps.feed.list().filter(i => isArchivedQuestion(i, nowMs)).reverse()
+    return { items: all.slice(0, ARCHIVE_LIST_MAX).map(i => ({ ...i, archived: true as const })), total: all.length, waitingExpiryDays: WAITING_EXPIRY_DAYS, version: this.deps.feed.version() }
   }
 
-  /** The chat, oldest first. `after` is an item id: only items after it. */
-  feed(options: { after?: string; limit?: number } = {}): { items: FeedItem[]; version: number; more: boolean } {
+  /** The chat, oldest first. `after` is an item id: only items after it. 7.0.9: an older question carries `archived: true`. */
+  feed(options: { after?: string; limit?: number } = {}): { items: Array<FeedItem & { archived?: true }>; version: number; more: boolean } {
     const items = this.deps.feed.list()
     let start = 0
     if (options.after) {
@@ -599,7 +633,8 @@ export class DropService {
     const rest = items.slice(start)
     // Without `after` the newest page; with it, the next page forward.
     const page = options.after ? rest.slice(0, limit) : rest.slice(-limit)
-    return { items: page, version: this.deps.feed.version(), more: options.after ? rest.length > limit : rest.length > limit }
+    const nowMs = this.now().getTime()
+    return { items: page.map(i => isArchivedQuestion(i, nowMs) ? { ...i, archived: true as const } : i), version: this.deps.feed.version(), more: options.after ? rest.length > limit : rest.length > limit }
   }
 
   /** The drop a chat item belongs to. */
@@ -609,7 +644,7 @@ export class DropService {
     return item.threadId
   }
 
-  markRead(through: string): { unread: number; waiting: number; version: number } {
+  markRead(through: string): { unread: number; waiting: number; asked: number; version: number } {
     const items = this.deps.feed.list()
     const index = items.findIndex(i => i.id === through)
     if (index < 0) throw new DropError('feed_item_not_found', 404)
@@ -618,7 +653,7 @@ export class DropService {
     if (ids.size) this.deps.feed.update(ids, item => ({ ...item, readAt: at }))
     const s = this.summary()
     // Opening the chat clears unread only: what waits on you stays until it is answered, done or dismissed.
-    return { unread: s.unread, waiting: s.waiting, version: s.version }
+    return { unread: s.unread, waiting: s.waiting, asked: s.asked, version: s.version }
   }
 
   /** History (plan section 6), P1: words over drop text and link labels, with kind and status filters, newest first. */

package/server/lib/drop-store.ts

@@ -387,6 +387,13 @@ export class InboxFeedStore {
   private items: FeedItem[] = []
   private quarantined: unknown[] = []
   private versionNo = 0
+  /**
+   * 7.0.9 (Miles 11/08, "99 plus messages, despite the fact that I've already seen all of those"): the moment this
+   * feed started counting unread as net new. Every item still unread when the first build with it opened the file is
+   * marked read once, at that open, so the rail never counts what was already on screen. A file this build wrote
+   * carries it; a file without it (an older build wrote it last) is migrated on open.
+   */
+  private readFloorAt: string
   private readonly path: string
   private readonly lock: ServerInstanceLock
   private closed = false
@@ -400,6 +407,19 @@ export class InboxFeedStore {
       this.versionNo = Number.isSafeInteger(v) && (v as number) >= 0 ? v as number : this.items.length
     } catch (e) { this.close(); throw e }
     if (this.quarantined.length) console.warn(`[inbox] ${this.quarantined.length} unreadable feed item(s) set aside`)
+    const floor = opened.journal?.readFloorAt
+    this.readFloorAt = this.now().toISOString()
+    if (typeof floor === 'string' && Number.isFinite(Date.parse(floor))) this.readFloorAt = floor
+    else if (opened.journal) this.migrateReadFloor()
+  }
+  /** When unread started meaning net new on this feed (see readFloorAt). */
+  readFloor(): string { return this.readFloorAt }
+  /** Once per file: what was unread before this build opened it had already been shown, so it reads as read now. */
+  private migrateReadFloor(): void {
+    const at = this.readFloorAt
+    const next = this.items.map(i => i.readAt === null ? { ...i, readAt: at } : i)
+    // A file that cannot be written now still opens; the next open tries again. Unread never blocks the chat.
+    try { this.write(next, 1) } catch (e) { console.warn(`[inbox] read floor not written: ${(e as Error).message}`) }
   }
   /** Oldest first, as a chat reads. */
   list(): FeedItem[] { return structuredClone(this.items) }
@@ -455,7 +475,7 @@ export class InboxFeedStore {
     if (kept.length > DROP_LIMITS.feed) throw new DropStoreError('inbox_store_full', 503)
     const version = this.versionNo + bump
     // Never write a file the reader would refuse: the oldest COS lines (receipts, answers, pings) go first.
-    const serialize = () => JSON.stringify({ version: 1, feedVersion: version, items: kept, quarantined: this.quarantined }) + '\n'
+    const serialize = () => JSON.stringify({ version: 1, feedVersion: version, readFloorAt: this.readFloorAt, items: kept, quarantined: this.quarantined }) + '\n'
     let body = serialize()
     while (Buffer.byteLength(body) > this.maxBytes) {
       const oldest = kept.findIndex(i => i.kind !== 'drop')

package/server/lib/event-loop-stall.ts

@@ -0,0 +1,62 @@
+/**
+ * Event-loop stall detector (S1, 2026-11-09). Logs only when the server's event loop was blocked.
+ *
+ * Why: COS Control's dictation asks GET /api/transcribe/capabilities with a 5 s timeout. Six
+ * dictations (11/03 13:01 CST, 11/04 15:32, and four between 18:12 and 18:32 on 11/04) failed at
+ * 5,052 to 5,072 ms with no answer, logged by Control as "refused:unknown". That route is a
+ * constant JSON object, so a 5 s silence means the process did not get to it: a blocked event
+ * loop, a process mid-restart, or a Mac under memory pressure. Nothing in the server logs could
+ * tell those apart. This line can:
+ *
+ *   [event-loop] stalled 6230 ms (rss 1840 MB, heap 910 MB; 1 stall(s) over 2000 ms since boot)
+ *
+ * A 500 ms unref'd timer measures its own lateness. A late tick above the threshold is one stall.
+ * At most one line per 10 s; stalls in between are counted into the next line.
+ */
+export const STALL_SAMPLE_MS = 500
+export const STALL_THRESHOLD_MS = 2_000
+const LOG_EVERY_MS = 10_000
+
+export interface StallMonitor {
+  stop(): void
+  stats(): { stalls: number; worstMs: number }
+}
+
+export function startEventLoopStallMonitor(options: {
+  sampleMs?: number
+  thresholdMs?: number
+  now?: () => number
+  log?: (line: string) => void
+  memory?: () => { rss: number; heapUsed: number }
+} = {}): StallMonitor {
+  const sampleMs = options.sampleMs ?? STALL_SAMPLE_MS
+  const thresholdMs = options.thresholdMs ?? STALL_THRESHOLD_MS
+  const now = options.now ?? (() => performance.now())
+  const log = options.log ?? (line => console.warn(line))
+  const memory = options.memory ?? (() => process.memoryUsage())
+  let last = now()
+  let stalls = 0
+  let worstMs = 0
+  let lastLogAt = -Infinity
+  let unlogged = 0
+  const timer = setInterval(() => {
+    const at = now()
+    const lateMs = at - last - sampleMs
+    last = at
+    if (lateMs < thresholdMs) return
+    stalls++
+    worstMs = Math.max(worstMs, lateMs)
+    if (at - lastLogAt < LOG_EVERY_MS) { unlogged++; return }
+    lastLogAt = at
+    const m = memory()
+    const extra = unlogged ? `; ${unlogged} more since the last line` : ''
+    unlogged = 0
+    log(`[event-loop] stalled ${Math.round(lateMs)} ms (rss ${Math.round(m.rss / 1e6)} MB, heap ${Math.round(m.heapUsed / 1e6)} MB; `
+      + `${stalls} stall(s) over ${thresholdMs} ms since boot${extra})`)
+  }, sampleMs)
+  timer.unref?.()
+  return {
+    stop: () => clearInterval(timer),
+    stats: () => ({ stalls, worstMs: Math.round(worstMs) }),
+  }
+}

package/server/lib/full-hold-engine.ts

@@ -0,0 +1,114 @@
+// X1 (Q1 review O2, 2026-11-09): WHICH engine asked, read from the process that ran the hook, never
+// from the session id alone.
+//
+// The hook script posts its own `$PPID`, which is the Claude Code process that ran it (measured: a
+// CLI 2.1.322 run and the Desktop engine 2.1.317 both, `~/.claude/sessions/<ppid>.json` names the
+// same session). Reading the record for the session id instead lets a second process that shares the
+// id (an older CLI, a `claude -p --resume <id>`) inherit a tab's version (Q1 O2).
+//
+// The entrypoint is not enough either. `claude -p` takes `CLAUDE_CODE_ENTRYPOINT` from whatever
+// started it: a print run launched from a Desktop tab's shell registers as `claude-desktop`, and its
+// `kind` reads `interactive` (measured 22:05). A print run has no dialog, and it does reach the
+// PermissionRequest hook for an approval and waits on it (measured: a 20 s hold blocked it 20 s), so a
+// full hold there would stall a headless job for up to an hour. What does tell them apart is where
+// the process runs (census of 25 live sessions, 22:06):
+//   - a Desktop tab's engine is a child of Claude.app's own `Contents/Helpers/disclaimer`;
+//   - an interactive CLI has a controlling terminal (`ttys000`) and none of the print or SDK flags;
+//   - a print run started from a shell or a tool has neither.
+// Q1 C3 (Codex second opinion), measured 22:42: a terminal alone is not enough. A `claude -p` run under
+// a terminal (typed there, or started by a CLI session's own Bash tool, whose children inherit its
+// terminal) has a tty too, and `-p` in its arguments. So a terminal engine must also carry none of
+// `-p`, `--print`, `--input-format`, `--output-format` (an SDK host passes the last two). Miles's two
+// interactive CLI sessions carried none of them.
+// Anything that cannot be read is `other`, and `other` is never proven.
+
+import { execFile } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { EngineFacts, EngineHost } from './full-hold.js'
+
+export function claudeSessionsRegistryDir(): string {
+  const configDir = process.env.CLAUDE_CONFIG_DIR ? process.env.CLAUDE_CONFIG_DIR : join(homedir(), '.claude')
+  return join(configDir, 'sessions')
+}
+
+/** `~/.claude/sessions/<pid>.json` parsed, only when it names `sessionId` (and, if it says, that pid). Bounded; null on anything else. */
+function readRecord(pid: number, sessionId: string, dir: string): Record<string, unknown> | null {
+  if (!Number.isInteger(pid) || pid <= 1) return null
+  try {
+    const text = readFileSync(join(dir, `${pid}.json`), 'utf-8')
+    if (text.length > 256 * 1024) return null
+    const raw = JSON.parse(text) as Record<string, unknown>
+    if (typeof raw.sessionId !== 'string' || raw.sessionId.toLowerCase() !== sessionId.toLowerCase()) return null
+    if (typeof raw.pid === 'number' && raw.pid !== pid) return null
+    return raw
+  } catch {
+    return null
+  }
+}
+
+/** The engine's entrypoint and version from its own record. */
+export function registryRecordForPid(pid: number, sessionId: string, dir = claudeSessionsRegistryDir()): { entrypoint: string | null; version: string | null } | null {
+  const raw = readRecord(pid, sessionId, dir)
+  if (!raw) return null
+  return {
+    entrypoint: typeof raw.entrypoint === 'string' && raw.entrypoint ? raw.entrypoint : null,
+    version: typeof raw.version === 'string' && raw.version ? raw.version.slice(0, 32) : null,
+  }
+}
+
+type PsRun = (args: string[]) => Promise<string | null>
+
+/** A flag only a print run or an SDK host passes (Q1 C3). */
+const PRINT_OR_SDK_FLAG = /^(?:-p|--print|--input-format(?:=.*)?|--output-format(?:=.*)?)$/
+
+const runPs: PsRun = args => new Promise(resolve => {
+  try {
+    execFile('/bin/ps', args, { timeout: 1_000, maxBuffer: 64 * 1024 }, (error, stdout) => resolve(error ? null : String(stdout)))
+  } catch {
+    resolve(null)
+  }
+})
+
+/** Where a Claude Code process runs: Claude.app's helper, a terminal, or neither. */
+export async function processHost(pid: number, ps: PsRun = runPs): Promise<EngineHost> {
+  if (!Number.isInteger(pid) || pid <= 1) return 'other'
+  const own = await ps(['-o', 'ppid=,tty=', '-p', String(pid)])
+  if (!own) return 'other'
+  const [ppidRaw, tty] = own.trim().split(/\s+/)
+  const ppid = Number(ppidRaw)
+  if (tty && tty !== '??' && tty !== '-' && /^tty/.test(tty)) {
+    const args = await ps(['-o', 'args=', '-p', String(pid)])
+    if (args === null) return 'other'
+    return args.trim().split(/\s+/).some(token => PRINT_OR_SDK_FLAG.test(token)) ? 'other' : 'terminal'
+  }
+  if (!Number.isInteger(ppid) || ppid <= 1) return 'other'
+  const parent = await ps(['-o', 'comm=', '-p', String(ppid)])
+  const path = parent ? parent.trim() : ''
+  return /\/Claude\.app\/Contents\/Helpers\/disclaimer$/.test(path) ? 'desktop-app' : 'other'
+}
+
+/**
+ * X1 round 3: the engine's own status now (`waiting` while its dialog is up), from the same record, or
+ * null when the record is gone (the process ended) or names another session (the pid was reused).
+ * Measured 22:39 on both engines: `waiting` is written 0 to 5 ms before the PermissionRequest hook
+ * starts and leaves `waiting` within milliseconds of an answer at the desk (`busy`, or `idle` on Esc);
+ * the record is removed when the process exits.
+ */
+export function registryStatusForPid(pid: number, sessionId: string, dir = claudeSessionsRegistryDir()): { status: string | null; statusUpdatedAt: number | null } | null {
+  const raw = readRecord(pid, sessionId, dir)
+  if (!raw) return null
+  return {
+    status: typeof raw.status === 'string' ? raw.status : null,
+    statusUpdatedAt: typeof raw.statusUpdatedAt === 'number' && Number.isFinite(raw.statusUpdatedAt) ? raw.statusUpdatedAt : null,
+  }
+}
+
+/** The engine facts the full hold reads, for the process that ran the hook. Null when its record does not name the session. */
+export async function engineForHookProcess(sessionId: string, ppid: number | null, deps: { dir?: string; ps?: PsRun } = {}): Promise<EngineFacts | null> {
+  if (ppid === null) return null
+  const record = registryRecordForPid(ppid, sessionId, deps.dir)
+  if (!record) return null
+  return { ...record, host: await processHost(ppid, deps.ps) }
+}

package/server/lib/full-hold.ts

@@ -0,0 +1,124 @@
+// X1 (2026-11-09): the full hold. A session question (AskUserQuestion) or a tool approval held for
+// the WHOLE wait of the PermissionRequest hook, whether or not a COS device is live when it is asked.
+//
+// WHY THIS IS SAFE AT THE DESK (canaries, operations/personal/wk46_2026/production_hardening/
+// x1_question_fetch/CANARIES.md): on the engines below, Claude Code shows its own question or
+// approval dialog at once WHILE the PermissionRequest hook is still waiting (C1, C5). An answer at
+// the Mac wins and a later hook answer is ignored (C3, C4); a hook answer withdraws the dialog (C2;
+// the desktop engine sends `control_cancel_request` to the app, C6). A hold of 3,703 s worked (C7).
+// So holding the hook never delays the Mac's own prompt (Miles's option B, 11/05) ON THESE ENGINES.
+// An engine that is not listed, or reads older, keeps today's rule: it may not show its dialog
+// until the hook returns, and a long hold there would keep the desk waiting.
+//
+// Both switches default OFF. With both off nothing in this file is read on the permission path.
+//
+// Pure, no imports beyond the one switch reader.
+
+import { readSwitch } from './env-switch.js'
+
+/** `COS_QUESTION_FULL_HOLD`: hold a question for the whole hook wait. Default OFF. Read per request. */
+export function questionFullHoldEnabled(env: NodeJS.ProcessEnv): boolean {
+  return readSwitch(env.COS_QUESTION_FULL_HOLD, false)
+}
+
+/** `COS_APPROVAL_FULL_HOLD`: hold a tool approval for the whole hook wait while the desk stays idle. Default OFF. */
+export function approvalFullHoldEnabled(env: NodeJS.ProcessEnv): boolean {
+  return readSwitch(env.COS_APPROVAL_FULL_HOLD, false)
+}
+
+/**
+ * `COS_WAITING_QUESTION_WORDS`: a session waiting on a question carries the first 80 characters of its
+ * first question (`waiting_detail`, through `toolTarget`), so Today and the Sessions rows say what it
+ * asks. Default ON: Miles, 2026-11-09 22:10 CST, "Yes, show by default", told that the text is written
+ * to the on-disk session-hook ledger and sent to any signed-in browser, including for questions
+ * answered at the desk. `0` restores 7.0.13's empty detail exactly. Question text only: never an
+ * option, a description or an answer. The `waiting` list with full words and options is NOT this
+ * switch: it is on only while a full-hold switch is.
+ */
+export function waitingQuestionWordsEnabled(env: NodeJS.ProcessEnv): boolean {
+  return readSwitch(env.COS_WAITING_QUESTION_WORDS, true)
+}
+
+/** Control and format characters (bidi overrides, zero-width) taken out of a question before it becomes row text. */
+export function questionRowText(question: unknown): string {
+  if (typeof question !== 'string') return ''
+  return question.replace(/[\p{Cc}\p{Cf}]+/gu, ' ')
+}
+
+export interface FullHoldSwitches { questions: boolean; approvals: boolean }
+
+export function fullHoldSwitches(env: NodeJS.ProcessEnv): FullHoldSwitches {
+  return { questions: questionFullHoldEnabled(env), approvals: approvalFullHoldEnabled(env) }
+}
+
+/**
+ * The oldest engine of each kind proven to show its own dialog while the hook waits, by the
+ * registry record's `entrypoint` and `version` (`~/.claude/sessions/<pid>.json`).
+ *   - `cli` 2.1.321: canaries C1 to C4, C7, C9 (2026-11-09, tmux, real TTY).
+ *   - `claude-desktop` 2.1.317: the engine Claude Desktop runs, driven over its stream-json
+ *     protocol, C5, C6, C9 (and the 6.71.7 Desktop D1 canary of 2026-10-11 in the real app).
+ * Anything else (`sdk-cli`, an unknown entrypoint, no version) is not proven.
+ */
+export const FULL_HOLD_ENGINE_FLOORS: Readonly<Record<string, readonly number[]>> = Object.freeze({
+  cli: Object.freeze([2, 1, 321]),
+  'claude-desktop': Object.freeze([2, 1, 317]),
+})
+
+/** Where the engine runs (`lib/full-hold-engine.ts` `processHost`): Claude.app's helper, a terminal, or neither. */
+export type EngineHost = 'desktop-app' | 'terminal' | 'other'
+
+export interface EngineFacts { entrypoint: string | null; version: string | null; host?: EngineHost }
+
+/**
+ * Q1 O2: the host each entrypoint must run in. A `claude -p` print run takes its entrypoint from
+ * whatever launched it, has no dialog, and runs under neither (`lib/full-hold-engine.ts`).
+ */
+export const FULL_HOLD_ENGINE_HOSTS: Readonly<Record<string, EngineHost>> = Object.freeze({
+  cli: 'terminal',
+  'claude-desktop': 'desktop-app',
+})
+
+/** `2.1.321` as numbers; null for anything that is not one to four dot-separated whole numbers. */
+export function parseEngineVersion(version: unknown): number[] | null {
+  if (typeof version !== 'string') return null
+  const trimmed = version.trim()
+  if (!/^\d{1,6}(?:\.\d{1,6}){0,3}$/.test(trimmed)) return null
+  return trimmed.split('.').map(Number)
+}
+
+/** True when `version` is at or above `floor`, part by part (a missing part reads 0). */
+export function versionAtLeast(version: readonly number[], floor: readonly number[]): boolean {
+  const length = Math.max(version.length, floor.length)
+  for (let i = 0; i < length; i++) {
+    const v = version[i] ?? 0
+    const f = floor[i] ?? 0
+    if (v !== f) return v > f
+  }
+  return true
+}
+
+/** Whether this engine is proven to keep its dialog on screen while the hook waits, and runs where that dialog is. */
+export function engineProvenForFullHold(engine: EngineFacts | null | undefined): boolean {
+  if (!engine || typeof engine.entrypoint !== 'string') return false
+  if (!Object.prototype.hasOwnProperty.call(FULL_HOLD_ENGINE_FLOORS, engine.entrypoint)) return false
+  if (engine.host !== FULL_HOLD_ENGINE_HOSTS[engine.entrypoint]) return false
+  const floor = FULL_HOLD_ENGINE_FLOORS[engine.entrypoint]!
+  const version = parseEngineVersion(engine.version)
+  return version !== null && versionAtLeast(version, floor)
+}
+
+/** The PermissionRequest wait the installer writes for a kind under the full hold. */
+export const FULL_HOLD_HOOK_WAIT_S = 3600
+
+/**
+ * The matcher of the non-question PermissionRequest block once the hook is split (canary C9:
+ * honoured on both engines; a question runs only the `AskUserQuestion` block, everything else
+ * only this one).
+ */
+export const NON_QUESTION_MATCHER = '^(?!AskUserQuestion$).*'
+export const QUESTION_MATCHER = 'AskUserQuestion'
+
+/** How a web (browser session) answer proves a person just touched the page, while a flag is on. */
+export const WEB_ANSWER_TOUCH_MAX_MS = 60_000
+/** How long a web approval's confirm step stays usable. */
+export const WEB_CONFIRM_TTL_MS = 60_000