@gotcos/glasses-server 6.58.2 → 6.60.0

package/server/index.ts

@@ -24,13 +24,15 @@ 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 { cachedHookStatus, claudeDeskRunning, deskIdleSeconds, deskTurnEndedAt, haltHandedOffTurn, registerDrainKickStats, registryIdleAfterStop, sessionHooksEnabled, sessionSignalStore, signalFor, startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
+import { cachedHookStatus, claudeDeskRunning, onSessionRowEnded, deskIdleSeconds, deskTurnEndedAt, haltHandedOffTurn, registerDrainKickStats, registryIdleAfterStop, sessionHooksEnabled, sessionSignalStore, signalFor, startSessionHooksRuntime } from './lib/session-hooks-runtime.js'
 import { writeHaltMarker } from './lib/session-halt.js'
 import { appendSessionCancelLedger, cancelHoldUntil as cancelHoldUntilFor, noteThreadCancelled, threadCancel } from './lib/session-cancel.js'
 import { makeQueueTurnEvidence } from './lib/queue-turn-evidence.js'
 import {
   PermissionBroker,
   brokerSignalSink,
+  permissionBrokerAwayHoldMs,
+  permissionBrokerAwayRecentClientMs,
   permissionBrokerMode,
   permissionBrokerTimeoutMs,
   readHidIdleSeconds,
@@ -38,7 +40,7 @@ import {
   wirePermissionBrokerToSignals,
 } from './lib/permission-broker.js'
 import { createPermissionBrokerHookRouter, createSessionQuestionsRouter } from './routes/permission-broker.js'
-import { lastQuestionsPollAt } from './lib/client-liveness.js'
+import { lastHoldQuestionsPollAt, lastLegacyQuestionsPollAt, lastQuestionsPollAt, presenceAgeMs } from './lib/client-liveness.js'
 import {
   createAgentSessionBindingsRouter,
   TargetGuard,
@@ -125,9 +127,13 @@ import { createQueryJobsRouter } from './routes/query-jobs.js'
 import { createWorkReviewsRouter } from './routes/work-reviews.js'
 import { createWorkBoardRouter } from './routes/work-board.js'
 import { createWorkIntakeRouter } from './routes/work-intake.js'
+import { createWorkHandoffRequestsRouter } from './routes/work-handoff-requests.js'
 import { createJevRouter } from './routes/jev.js'
 import { dataPath } from './lib/data-dir.js'
 import { WorkIntakeStore, createOptionalWorkIntakeStore } from './lib/work-intake-store.js'
+import { WorkHandoffRequestStore, createOptionalWorkHandoffRequestStore, handoffRequestCapabilities } from './lib/work-handoff-requests.js'
+import { createWorkBoardReader } from './lib/work-board-reader.js'
+import { listBoard } from './lib/task-store.js'
 import { createDefaultWorkReviewRuntime } from './lib/work-review-backend.js'
 import { createMorningBriefRouter } from './routes/morning-brief.js'
 import { getMorningBriefScheduler, startMorningBriefScheduler, stopMorningBriefScheduler } from './lib/morning-brief-runtime.js'
@@ -237,6 +243,13 @@ app.use(cors({
 // (lib/permission-broker.ts). An app without the question UI never polls, so for it every
 // request is `{}`. `COS_PERMISSION_BROKER=0` is the switch, read per request, and every
 // request outside the gate is answered `{}` at once.
+// 6.60.0: the away hold. While the desk is idle, and only when glasses or a phone that send
+// `hold=1` reported wearer presence within `COS_PERMISSION_BROKER_AWAY_RECENT_CLIENT_S`
+// (default 1800; in memory, the larger of the monotonic and wall-clock age), a request is held
+// up to `COS_PERMISSION_BROKER_AWAY_HOLD_S` (default 600, `0` is the 6.59.0 broker) whether or
+// not a client is polling right now, never past the PermissionRequest timeout the Claude
+// settings file carries (read through the 5 s hook-status cache) and the hook's own stamp.
+// Older clients (no `hold=1`) keep the 6.59.0 liveness and never enable it.
 const permissionBroker = new PermissionBroker({
   now: () => Date.now(),
   mode: () => permissionBrokerMode(process.env, sessionHooksEnabled()),
@@ -245,10 +258,22 @@ const permissionBroker = new PermissionBroker({
   readDeskIdleSeconds: readHidIdleSeconds,
   deskIdleSeconds,
   timeoutMs: () => permissionBrokerTimeoutMs(process.env),
+  awayHoldMs: () => permissionBrokerAwayHoldMs(process.env),
+  installedHookTimeoutS: () => cachedHookStatus().permissionHookTimeoutS,
+  lastLegacyPollAt: lastLegacyQuestionsPollAt,
+  lastHoldPollAt: lastHoldQuestionsPollAt,
+  presenceAgeMs: () => presenceAgeMs(),
+  awayRecentClientMs: () => permissionBrokerAwayRecentClientMs(process.env),
+  stillWaitingAtMac: (sessionId, fingerprint) => {
+    const signal = sessionSignalStore.get(sessionId)
+    return !!signal && !signal.ended && signal.waiting?.fingerprint === fingerprint
+  },
   signals: brokerSignalSink(sessionSignalStore),
 })
 registerPermissionBroker(permissionBroker)
 wirePermissionBrokerToSignals(permissionBroker, sessionSignalStore)
+// 6.60.0 (QA round 1, N2): a row that reads ended clears "waiting at the Mac" at once.
+onSessionRowEnded(sessionId => { permissionBroker.sessionRowEnded(sessionId) })
 
 // THE TWO HOOK-TOKEN DOORS, deliberately BEFORE the /api gate and the global body parser.
 // Each checks the per-install hook token (never the pairing token) in constant time before
@@ -625,7 +650,13 @@ app.use('/api', createQueryJobsRouter(queryJobCoordinator, {
 }))
 const workReviewRuntime = createDefaultWorkReviewRuntime()
 app.use('/api', createWorkReviewsRouter(workReviewRuntime))
-app.use('/api', createWorkBoardRouter())
+// Work handoff requests (6.59.0): the glasses ask for Work to start and COS Control claims them. Optional: a bad
+// journal answers 503 and `capabilities.requests: 0`, never blocks boot. The server runs no provider for a request.
+const workHandoffRequestStore = createOptionalWorkHandoffRequestStore(() => new WorkHandoffRequestStore(dataPath('work-handoff-requests')))
+// One bounded board read (5 s) shared by the glasses' Work glances and the request inbox; GET /api/work-board primes it.
+const workBoardReader = createWorkBoardReader(() => listBoard())
+app.use('/api', createWorkBoardRouter({ readBoard: workBoardReader, requests: () => handoffRequestCapabilities(workHandoffRequestStore, Date.now()) }))
+app.use('/api', createWorkHandoffRequestsRouter({ store: workHandoffRequestStore, readBoard: workBoardReader }))
 // Work intake (6.57.0): meeting-derived suggestions, asks and review items. Optional: a bad journal never blocks boot.
 const workIntakeStore = createOptionalWorkIntakeStore(() => new WorkIntakeStore(dataPath('work-intake')))
 app.use('/api', createWorkIntakeRouter({ store: workIntakeStore }))
@@ -948,6 +979,7 @@ async function gracefulShutdown(): Promise<void> {
   stopMorningBriefScheduler()
   await workReviewRuntime?.close()
   workIntakeStore?.close()
+  workHandoffRequestStore?.close()
   stopMeetingImportScheduler()
   stopMeetingMergeScheduler()
   sessionHooksRuntime.stop()

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

@@ -36,8 +36,24 @@ export interface HookSubscription {
   matcher?: string
   async: boolean
   timeout: number
+  /**
+   * 6.60.0: the command passes the block's own `timeout` to the script as its second
+   * argument. The script stops waiting 5 s before it and stamps it on the request it posts
+   * (`hookWaitS`), so the broker knows the wait of THIS invocation. The command and the
+   * timeout sit in one block, so whether or not a running Claude session re-reads its hook
+   * settings, the stamp it sends and the timeout it enforces come from the same block.
+   */
+  passTimeout?: boolean
 }
 
+/**
+ * 6.60.0: Claude Code's wait on the PermissionRequest hook: the away hold (default 600 s)
+ * plus slack. The script's curl stops at 625 and the broker answers by 620 at the latest.
+ */
+export const PERMISSION_HOOK_TIMEOUT_S = 630
+/** What every install before 6.60.0 carries for PermissionRequest, with no wait argument. */
+export const LEGACY_PERMISSION_HOOK_TIMEOUT_S = 130
+
 /**
  * Every event the reducer understands, with the timing each one needs. SessionStart,
  * UserPromptSubmit, Stop and SessionEnd are synchronous: measured 2026-09-15, an async
@@ -55,6 +71,10 @@ export interface HookSubscription {
  * because the merge keeps exactly one of ours per event and status requires it: the script
  * spools only AskUserQuestion and ExitPlanMode, which is what the old async matcher block
  * did. Changing this row makes every existing install read `drift` until Install hooks.
+ *
+ * 6.60.0: PermissionRequest waits 630 s (was 130) and passes that number to the script, for
+ * the away hold. An install that differs ONLY by still carrying the earlier block (130 s, no
+ * argument) reads `drift` with `priorWaitOnly`, and stays halt-ready (`hookHaltReady`).
  */
 export const HOOK_SUBSCRIPTIONS: readonly HookSubscription[] = [
   { event: 'SessionStart', async: false, timeout: 5 },
@@ -62,7 +82,7 @@ export const HOOK_SUBSCRIPTIONS: readonly HookSubscription[] = [
   { 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: 'PermissionRequest', async: false, timeout: PERMISSION_HOOK_TIMEOUT_S, passTimeout: true },
   { event: 'PermissionDenied', async: true, timeout: 10 },
   { event: 'PreToolUse', async: false, timeout: 5 },
   { event: 'PostToolUse', async: true, timeout: 10 },
@@ -117,9 +137,13 @@ export function shellQuote(value: string): string {
 /**
  * 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.
+ * 6.60.0: `waitS`, for a subscription with `passTimeout`, follows the event name as the
+ * script's second argument (an argument, never an environment variable: a variable could
+ * be inherited from the shell that started Claude, an argument only comes from this block).
  */
-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 function hookCommand(scriptPath: string, event: string, paths: HookPaths = currentHookPaths(), waitS?: number): string {
+  const base = `COS_GLASSES_HOME=${shellQuote(paths.home)} COS_HOOK_SPOOL=${shellQuote(paths.spoolDir)} ${shellQuote(scriptPath)} ${event}`
+  return waitS === undefined ? base : `${base} ${Math.trunc(waitS)}`
 }
 
 export interface HookPaths {
@@ -133,20 +157,57 @@ export function currentHookPaths(): HookPaths {
 
 type HookBlock = { matcher?: unknown; hooks?: unknown }
 
+function hookIsOurs(h: unknown): boolean {
+  return !!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 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 + ' ')))
+  return hooks.some(hookIsOurs)
 }
 
 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 }
+  const command = hookCommand(scriptPath, sub.event, paths, sub.passTimeout ? sub.timeout : undefined)
+  const hook: Record<string, unknown> = { type: 'command', command, timeout: sub.timeout }
   if (sub.async) hook.async = true
   return sub.matcher ? { matcher: sub.matcher, hooks: [hook] } : { hooks: [hook] }
 }
 
+/**
+ * 6.60.0: the block an install before 6.60.0 wrote for this event, when this release changed
+ * it only by the wait: PermissionRequest at 130 s with no wait argument. Null for any other.
+ */
+function priorWaitBlock(scriptPath: string, sub: HookSubscription, paths: HookPaths): Record<string, unknown> | null {
+  if (sub.event !== 'PermissionRequest') return null
+  return canonicalBlock(scriptPath, { event: sub.event, async: sub.async, timeout: LEGACY_PERMISSION_HOOK_TIMEOUT_S }, paths)
+}
+
+/**
+ * 6.60.0: how long Claude Code waits on OUR PermissionRequest hook, read from a settings
+ * object: the smallest `timeout` among our entries (Claude runs each, so the first to give up
+ * bounds the wait). Null when none of ours is there, or one of ours has no usable number:
+ * the broker then keeps the old safe clamp (`lib/permission-broker.ts` `holdCeilingS`).
+ */
+export function permissionHookTimeoutS(settings: unknown): number | null {
+  const hooks = settings && typeof settings === 'object' ? (settings as Record<string, unknown>).hooks : null
+  const blocks = hooks && typeof hooks === 'object' ? (hooks as Record<string, unknown>).PermissionRequest : null
+  if (!Array.isArray(blocks)) return null
+  let least: number | null = null
+  for (const block of blocks) {
+    if (!blockIsOurs(block)) continue
+    for (const h of (block as HookBlock).hooks as unknown[]) {
+      if (!hookIsOurs(h)) continue
+      const timeout = (h as { timeout?: unknown }).timeout
+      if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0) return null
+      least = least === null ? timeout : Math.min(least, timeout)
+    }
+  }
+  return least
+}
+
 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. */
@@ -190,22 +251,29 @@ export function stripHookSettings(current: unknown): MergeResult {
   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[] } {
+/**
+ * Which of our events a settings object carries, by exact canonical command. `priorWait`
+ * (6.60.0) names the drifted events whose one block of ours is exactly the block an earlier
+ * release wrote, differing only by the wait (`priorWaitBlock`).
+ */
+export function subscribedEvents(current: unknown, scriptPath: string, paths: HookPaths = currentHookPaths()): { subscribed: string[]; missing: string[]; drifted: string[]; priorWait: 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[] = []
+  const priorWait: 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)
+    if (ours.length === 1 && JSON.stringify(ours[0]) === canonical) { subscribed.push(sub.event); continue }
+    drifted.push(sub.event)
+    const prior = priorWaitBlock(scriptPath, sub, paths)
+    if (prior && ours.length === 1 && JSON.stringify(ours[0]) === JSON.stringify(prior)) priorWait.push(sub.event)
   }
-  return { subscribed, missing, drifted }
+  return { subscribed, missing, drifted, priorWait }
 }
 
 export type HookInstallState =
@@ -231,6 +299,16 @@ export interface HookStatus {
   subscribed: string[]
   missing: string[]
   drifted: string[]
+  /** 6.60.0: drifted events whose block is exactly an earlier release's, but for the wait. */
+  priorWait: string[]
+  /**
+   * 6.60.0: `drift`, and the ONLY difference is that the settings still carry the earlier
+   * PermissionRequest block (130 s, no wait argument): an install from before 6.60.0 that
+   * has not run Install hooks since. Questions are then held at most 120 s, as before.
+   */
+  priorWaitOnly: boolean
+  /** 6.60.0: our PermissionRequest hook's `timeout` in the settings file, or null (`permissionHookTimeoutS`). */
+  permissionHookTimeoutS: number | null
   tokenPresent: boolean
 }
 
@@ -272,16 +350,19 @@ export function hookStatus(paths: { settingsPath?: string; scriptPath?: string;
   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 }
+    return { state: read.reason, installed: false, settingsPath, scriptPath, scriptSha, packageScriptSha, subscribed: [], missing: HOOK_SUBSCRIPTIONS.map(s => s.event), drifted: [], priorWait: [], priorWaitOnly: false, permissionHookTimeoutS: null, tokenPresent }
   }
   const events = subscribedEvents(read.settings, scriptPath, hookPaths)
+  const permissionWaitS = permissionHookTimeoutS(read.settings)
   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 }
+  const priorWaitOnly = state === 'drift' && events.missing.length === 0 && events.drifted.length > 0
+    && events.drifted.every(event => events.priorWait.includes(event))
+  return { state, installed: state === 'installed', settingsPath, scriptPath, scriptSha, packageScriptSha, ...events, priorWaitOnly, permissionHookTimeoutS: permissionWaitS, tokenPresent }
 }
 
 /**
@@ -295,22 +376,35 @@ export function hookStatus(paths: { settingsPath?: string; scriptPath?: string;
  *   - c0b41bf8...: the 6.53.3 script as first built, before its /qa round made every event
  *     drain stdin. Never published, but installable from a local build of that commit
  *     (7433b7f), and it carries the same halt check.
+ *   - df54677f...: the script 6.53.3 through 6.59.0 shipped. 6.60.0 changed it only for the
+ *     away hold (the PermissionRequest wait); its halt check is the same.
  * Each is pinned against its bytes in `server/lib/__fixtures__/`.
  */
 export const HALT_CAPABLE_PRIOR_SCRIPT_SHAS: readonly string[] = [
   '1158bb06297550128f01fc47caa68806a5287d6da2d05b0d1c812e8ae20764e7',
   'c0b41bf8581cfea498e1e1ac5220fe4e148bd97448d13b60a88879ee5992cc51',
+  'df54677f79908893509ee87608cfe3f4a53ced03f88f337f16a63741d6b3d547',
 ]
 
 /**
  * 6.53.3: can the hooks on this Mac stop a desk Claude run now? `installed`, or the only
  * difference is a halt-capable earlier script (above). What the cancel route's
  * `hooksReady` and `/api/health` `features.sessionCancel.deskClaude` read.
+ *
+ * 6.60.0: or `drift` with `priorWaitOnly` (the settings still carry the earlier
+ * PermissionRequest wait, every other block is current) on this package's script or a
+ * halt-capable earlier one. The wait changes how long a question is held, not the halt
+ * check, so updating the server never turns cancel from the lens off. Any other drift
+ * still is not halt-ready.
  */
-export function hookHaltReady(status: Pick<HookStatus, 'installed' | 'state' | 'scriptSha'>): boolean {
+export function hookHaltReady(status: Pick<HookStatus, 'installed' | 'state' | 'scriptSha'> & Partial<Pick<HookStatus, 'priorWaitOnly' | 'packageScriptSha'>>): boolean {
   if (status.installed === true) return true
-  return status.state === 'script_outdated' && typeof status.scriptSha === 'string'
-    && HALT_CAPABLE_PRIOR_SCRIPT_SHAS.includes(status.scriptSha)
+  const priorScript = typeof status.scriptSha === 'string' && HALT_CAPABLE_PRIOR_SCRIPT_SHAS.includes(status.scriptSha)
+  if (status.state === 'script_outdated') return priorScript
+  if (status.state === 'drift' && status.priorWaitOnly === true) {
+    return priorScript || (typeof status.scriptSha === 'string' && status.scriptSha === status.packageScriptSha)
+  }
+  return false
 }
 
 const INSTALL_COMMAND = 'npx --yes @gotcos/glasses-server@latest --hooks install'
@@ -319,8 +413,17 @@ const INSTALL_COMMAND = 'npx --yes @gotcos/glasses-server@latest --hooks install
  * 6.53.3: one plain sentence for `--hooks status` saying what the state means and what fixes
  * it. Null when installed. Carries no path: the status JSON beside it already names them.
  */
-export function hookStatusAdvice(status: Pick<HookStatus, 'installed' | 'state' | 'scriptSha' | 'packageScriptSha'>): string | null {
+export function hookStatusAdvice(status: Pick<HookStatus, 'installed' | 'state' | 'scriptSha' | 'packageScriptSha'> & Partial<Pick<HookStatus, 'priorWaitOnly'>>): string | null {
   const short = (sha: string | null): string => (sha ? sha.slice(0, 12) : 'none')
+  // 6.60.0: the one drift an update itself causes. Say what it costs and that nothing broke.
+  if (status.state === 'drift' && status.priorWaitOnly === true) {
+    return 'The Claude settings file still carries the earlier permission hook wait (130 s), so a question that starts while you are away '
+      + 'is held for the glasses for at most 2 minutes instead of 10. '
+      + `Run \`${INSTALL_COMMAND}\`, or press Install hooks in COS Control. `
+      + (hookHaltReady(status)
+        ? 'Cancel from the lens still stops desk runs meanwhile.'
+        : 'Until then a desk run cannot be cancelled from the lens.')
+  }
   switch (status.state) {
     case 'installed':
       return null

package/server/lib/client-liveness.ts

@@ -23,28 +23,116 @@
 //
 // In memory: a restart forgets it, and the next poll restores it. Until then nothing is
 // held, which is the native dialog, the safe side.
+//
+// 6.60.0 (QA round 1, the contract shared with COS Glasses 6.9.563): the away hold needs
+// more than a poll. A poll QUALIFIES only with `hold=1` (this client shows held questions;
+// 6.9.563 and later send it) AND a finite `presenceAgeMs` within [0, 24 h]: the ms since
+// the latest real wearer evidence (glasses: a ring or temple input, or a device status with
+// wearing true; phone: a foreground touch). A connected lens nobody wears sends no
+// `presenceAgeMs`, and an older client sends no `hold=1`, so neither can make the Mac hold a
+// question for 10 minutes.
+//
+// Kept apart, all in memory (a restart forgets them, which fails toward 6.59.0):
+//   - the newest counting poll of any kind (`lastQuestionsPollAt`, for /api/health);
+//   - the newest poll WITHOUT `hold=1` (`lastLegacyQuestionsPollAt`): the 6.59.0 liveness,
+//     unchanged for every older client;
+//   - the newest poll WITH `hold=1` (`lastHoldQuestionsPollAt`);
+//   - the newest qualifying presence, on BOTH clocks, each forward-only: monotonic
+//     (`performance.now()`, immune to the wall clock stepping) and wall. Its age is the
+//     larger of the two (`presenceAgeMs`): on macOS the monotonic clock does not advance
+//     while the Mac sleeps, so on its own it would read a pre-sleep presence as younger
+//     than it is; the wall clock does advance. A wall clock stepped forward reads older
+//     (no hold), never younger.
+
+/** 6.60.0: the most a client may report as `presenceAgeMs`. Anything else is no presence. */
+export const PRESENCE_AGE_MAX_MS = 86_400_000
 
 let lastPollAt: number | null = null
+let lastLegacyPollAt: number | null = null
+let lastHoldPollAt: number | null = null
+let lastPresenceMono: number | null = null
+let lastPresenceWall: number | null = null
+
+/** 6.60.0: the monotonic clock. Milliseconds since this process started; paused while the Mac sleeps. */
+export function monotonicNowMs(): number {
+  return performance.now()
+}
 
 /** A stored stamp this far ahead of a new poll means the clock stepped back. */
 const CLOCK_STEP_BACK_MS = 5_000
 
+/** Newest-wins for a poll stamp, following a clock that stepped back (see below). */
+function newerStamp(stored: number | null, at: number): number {
+  return stored === null || at > stored || stored - at > CLOCK_STEP_BACK_MS ? at : stored
+}
+
+/** 6.60.0: what a counting poll said about the client, read from its query. */
+export interface QuestionsPollFacts {
+  /** `hold=1`: this client can show held questions. */
+  hold?: boolean
+  /** ms since the latest real wearer evidence; null or absent when there is none since boot. */
+  presenceAgeMs?: number | null
+}
+
+/** 6.60.0: a `presenceAgeMs` the contract accepts: a finite whole number within [0, 24 h]. */
+export function validPresenceAgeMs(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= PRESENCE_AGE_MAX_MS
+}
+
 /**
  * A counting questions poll answered at `at` (server clock). Never moves backwards for a
  * slower request answered later, but a clock that stepped back is followed: a stamp left in
  * the future would read stale to the broker, and ignoring every poll until the clock caught
- * up would leave no live client for that long.
+ * up would leave no live client for that long. 6.60.0: `poll` says whether it was a `hold=1`
+ * poll and carried qualifying presence; `mono` is the monotonic time it was answered.
  */
-export function noteQuestionsPoll(at: number): void {
+export function noteQuestionsPoll(at: number, poll: QuestionsPollFacts = {}, mono: number = monotonicNowMs()): void {
   if (!Number.isFinite(at)) return
-  if (lastPollAt === null || at > lastPollAt || lastPollAt - at > CLOCK_STEP_BACK_MS) lastPollAt = at
+  lastPollAt = newerStamp(lastPollAt, at)
+  if (poll.hold !== true) {
+    lastLegacyPollAt = newerStamp(lastLegacyPollAt, at)
+    return
+  }
+  lastHoldPollAt = newerStamp(lastHoldPollAt, at)
+  if (!validPresenceAgeMs(poll.presenceAgeMs) || !Number.isFinite(mono)) return
+  // Forward-only on each clock: a slower poll carrying older evidence never moves it back.
+  const presenceMono = mono - poll.presenceAgeMs
+  const presenceWall = at - poll.presenceAgeMs
+  if (lastPresenceMono === null || presenceMono > lastPresenceMono) lastPresenceMono = presenceMono
+  if (lastPresenceWall === null || presenceWall > lastPresenceWall) lastPresenceWall = presenceWall
+}
+
+/**
+ * 6.60.0: how long ago the newest qualifying wearer presence was, or null when no
+ * qualifying poll has arrived since this process started. The larger of the monotonic age
+ * and the wall-clock age, so a Mac that slept never makes it read younger.
+ */
+export function presenceAgeMs(mono: number = monotonicNowMs(), wall: number = Date.now()): number | null {
+  if (lastPresenceMono === null || !Number.isFinite(mono)) return null
+  const monoAge = Math.max(0, mono - lastPresenceMono)
+  const wallAge = lastPresenceWall !== null && Number.isFinite(wall) ? wall - lastPresenceWall : 0
+  return Math.max(monoAge, wallAge)
 }
 
-/** When the newest authenticated questions poll arrived, or null when none has since boot. */
+/** When the newest authenticated questions poll of any kind arrived, or null since boot (/api/health). */
 export function lastQuestionsPollAt(): number | null {
   return lastPollAt
 }
 
+/** 6.60.0: the newest poll WITHOUT `hold=1`: the 6.59.0 liveness, for every older client. */
+export function lastLegacyQuestionsPollAt(): number | null {
+  return lastLegacyPollAt
+}
+
+/** 6.60.0: the newest poll WITH `hold=1`. */
+export function lastHoldQuestionsPollAt(): number | null {
+  return lastHoldPollAt
+}
+
 export function __resetClientLivenessForTests(): void {
   lastPollAt = null
+  lastLegacyPollAt = null
+  lastHoldPollAt = null
+  lastPresenceMono = null
+  lastPresenceWall = null
 }