@gotcos/glasses-server 6.58.2 → 6.60.0

package/server/lib/permission-broker.ts

@@ -30,7 +30,10 @@
 //     dialog chooses a permission MODE, and "allow once" is not a plan approval;
 //   - a client that can answer asked for the questions in the last 30 s: an authenticated
 //     `GET /api/session-questions?client=glasses|phone` (lib/client-liveness). An app without
-//     the question UI never calls it, so for it the broker is inert and every request is `{}`;
+//     the question UI never calls it, so for it the broker is inert and every request is `{}`.
+//     6.60.0: or the away hold applies (THE AWAY HOLD, below). Only a poll WITHOUT `hold=1`
+//     counts here as before; a `hold=1` poll counts only while its wearer's presence is
+//     recent;
 //   - the desk has been idle `COS_PERMISSION_BROKER_DESK_IDLE_S` (default 90, never below 30),
 //     read here with a bounded `ioreg`, not trusted from the script.
 // The cheap gates run first and the desk read last; the question card or the approval card
@@ -40,11 +43,64 @@
 // A parked item holds the hook's response open until EXACTLY ONE of these resolves it:
 // an answer from the lens or phone; a hand-back from either ("Leave for the Mac"): `{}`;
 // the desk becoming active (polled every 1.5 s, and two unreadable reads in a row count as
-// active): `{}`; the answering client going quiet for 30 s: `{}`; the deadline
-// (`COS_PERMISSION_BROKER_TIMEOUT_S`, default 110, clamped to 120 so it lands before the
-// hook's 125 s): `{}`; the hook hanging up: `hook_gone`; the session
+// active): `{}`; the answering client going quiet for 30 s: `{}` (never an item the away
+// hold holds, 6.60.0); the deadline (`COS_PERMISSION_BROKER_TIMEOUT_S`, default 110, clamped
+// to 120 so it lands before the hook's 125 s; 6.60.0: the away hold, up to 600 s, never past
+// `holdCeilingS`): `{}`; the hook hanging up: `hook_gone`; the session
 // moving on without us (its tool ran, was denied, or the turn ended): `{}`; a drain: `{}`.
 //
+// ---------------------------------------------------------------------------
+// THE AWAY HOLD (6.60.0, Miles 2026-09-30: "Yes, up to 10 min")
+// ---------------------------------------------------------------------------
+// A question that starts while Miles is away used to be answerable from the glasses only for
+// the 110 s above, and not at all when no client was polling at that moment (`no_client`,
+// `{}` at once). Now, while the desk is idle past the SAME threshold the gate above uses
+// (`COS_PERMISSION_BROKER_DESK_IDLE_S`), a parked request is held up to the away hold
+// (`COS_PERMISSION_BROKER_AWAY_HOLD_S`, default 600, clamped to [30, 600]; `0` turns it off,
+// which turns the away hold off; a `hold=1` client still counts as live only with recent
+// presence), but only when ALL of these hold:
+//   - the installed hook waits longer than the 6.59.0 broker could ever hold (its 120 s
+//     clamp, `AWAY_MIN_CEILING_S`). Before Install hooks it does not, and away semantics are
+//     off (QA round 1, User W6). A `hold=1` client still counts as live only with recent
+//     presence, so a lens untouched for 30 minutes gets no card (QA round 2, W-A);
+//   - a client that shows held questions reported its WEARER present recently (Miles,
+//     2026-09-30 19:54: "Hold only if the glasses or phone were connected in the last 30
+//     min. A Claude Remote Control session with no glasses gets its question right away,
+//     as before."). The contract shared with COS Glasses 6.9.563 (lib/client-liveness): a
+//     poll `?client=glasses|phone&hold=1&presenceAgeMs=<int>`, the ms since a ring or temple
+//     input, a device status with wearing true, or a phone foreground touch. Recent means
+//     within `COS_PERMISSION_BROKER_AWAY_RECENT_CLIENT_S` (default 1800; below 30 s, the 30 s
+//     live window). A connected lens nobody wears sends no presence; an older client sends
+//     no `hold=1` and keeps the 6.59.0 liveness, never the away hold. In memory: after a
+//     restart nothing is recent until such a poll.
+// Held that way, a request stays answerable while no client is polling, so a lens or phone
+// that comes back can still answer it. It is re-checked on every desk poll (QA round 1,
+// Skeptic W2): once no client is live and the wearer's latest presence is older than the
+// window, it goes to the Mac's dialog (`no_client`), so one glance never holds a question 10
+// minutes. Desk activity still hands it back within one poll (1.5 s); a request that arrives
+// while Miles is at the desk is still `{}` at once (`desk_active`); every path still ends.
+// Every request answered `{}` is logged with why, the presence age and the window.
+//
+// NEVER past the hook's own wait. The hold is clamped to `holdCeilingS`: the PermissionRequest
+// `timeout` in the Claude settings file (read, not assumed) and the wait the hook stamped on
+// THIS request (`hookWaitS`, 6.60.0 script), whichever is less, minus 10 s; settings that
+// cannot be read leave the stamp alone. A request with no stamp (the earlier script, or an
+// earlier hook block) waited 130 s and its curl 125 s, so it is never held past 120 s.
+// Canaries on Claude Code 2.1.286, 2026-09-30: a PermissionRequest hook configured for 630 s
+// that slept 610 s was waited for and its allow applied (and 300 s / 200 s before it); one
+// configured for 150 s was stopped at 150 s and the tool did not run. The script stops its
+// own curl when it is stopped, so the broker sees the hook leave (`hook_gone`) at once.
+//
+// What a client sees: `deadlineAt` is the latest the request stays answerable (sooner if the
+// wearer's presence lapses with no client live); each item says `answerable`, `awayHold` and
+// `waitingAtMac`, and the questions route lists settled items (`settled`, codes only; every one
+// the Mac still waits on, whatever the cap), with `serverStartedAt` and
+// `waitingAtMacForgottenBefore` so a client can tell "forgot" from "moved past". `waitingAtMac`
+// stays true until that request's own tool finishes or is denied, its turn ends, or its row
+// reads ended: no hook marks the moment a dialog is approved, so an approved tool that is
+// still running reads as waiting (the safe direction: never "not waiting" while a dialog may
+// be up).
+//
 // NEVER: a permission RULE. `updatedPermissions` and the request's suggestions are never
 // returned; the decision objects below are built from nothing but constants and the
 // original input. Question and command text is never logged and never goes on the display
@@ -89,6 +145,73 @@ export function permissionBrokerTimeoutMs(env: NodeJS.ProcessEnv): number {
   return Math.round(Math.min(BROKER_TIMEOUT_MAX_S, Math.max(BROKER_TIMEOUT_MIN_S, seconds)) * 1000)
 }
 
+/** 6.60.0: the away hold. `COS_PERMISSION_BROKER_AWAY_HOLD_S`. */
+export const AWAY_HOLD_DEFAULT_S = 600
+/** Miles approved "up to 10 min" (2026-09-30). The installer's hook wait (630) is sized for it. */
+export const AWAY_HOLD_MAX_S = 600
+export const AWAY_HOLD_MIN_S = 30
+
+/**
+ * `COS_PERMISSION_BROKER_AWAY_HOLD_S`, in ms: default 600 s, clamped to [30, 600]. `0`, `off`
+ * or `false` turns the away hold off (0): the 6.59.0 broker. Junk is the default.
+ */
+export function permissionBrokerAwayHoldMs(env: NodeJS.ProcessEnv): number {
+  const raw = (env.COS_PERMISSION_BROKER_AWAY_HOLD_S ?? '').trim().toLowerCase()
+  if (raw === '0' || raw === 'off' || raw === 'false') return 0
+  const parsed = Number(raw)
+  const seconds = raw !== '' && Number.isFinite(parsed) && parsed > 0 ? parsed : AWAY_HOLD_DEFAULT_S
+  return Math.round(Math.min(AWAY_HOLD_MAX_S, Math.max(AWAY_HOLD_MIN_S, seconds)) * 1000)
+}
+
+/** 6.60.0: how recently a client must have polled for the away hold. */
+export const AWAY_RECENT_CLIENT_DEFAULT_S = 1_800
+/** A day: past that, "recently connected" no longer describes anyone. */
+export const AWAY_RECENT_CLIENT_MAX_S = 86_400
+
+/**
+ * `COS_PERMISSION_BROKER_AWAY_RECENT_CLIENT_S`, in ms: default 1800 s (30 min), clamped to
+ * [0, 86400]. `0` means a client must be live right now (polled within the 30 s window).
+ * Junk or a negative number is the default.
+ */
+export function permissionBrokerAwayRecentClientMs(env: NodeJS.ProcessEnv): number {
+  const raw = (env.COS_PERMISSION_BROKER_AWAY_RECENT_CLIENT_S ?? '').trim()
+  const parsed = Number(raw)
+  const seconds = raw !== '' && Number.isFinite(parsed) && parsed >= 0 ? parsed : AWAY_RECENT_CLIENT_DEFAULT_S
+  return Math.round(Math.min(AWAY_RECENT_CLIENT_MAX_S, Math.max(0, seconds)) * 1000)
+}
+
+/** 6.60.0: Claude Code's wait on every PermissionRequest hook before 6.60.0 (its curl: 125). */
+export const LEGACY_HOOK_WAIT_S = 130
+/**
+ * 6.60.0: the broker answers this far inside the hook's own wait: 5 s for the script's curl
+ * to give up before Claude Code stops the hook, 5 s more so `{}` lands before curl gives up.
+ * The 130 / 125 / 120 chain every release since 6.52.0 has kept.
+ */
+export const HOOK_REPLY_MARGIN_S = 10
+/** A `hookWaitS` stamp outside this range is not one the installer writes: no stamp. */
+export const HOOK_WAIT_STAMP_MAX_S = 3_600
+
+/**
+ * 6.60.0: the longest a request may be held, in seconds, from the hook's own start.
+ * `installedHookTimeoutS` is our PermissionRequest `timeout` in the Claude settings file, or
+ * null when that cannot be read (missing, unparseable, a symlink, no block of ours).
+ * `hookWaitS` is the wait this invocation stamped (the 6.60.0 script passes its block's
+ * timeout); none means an earlier hook, 130. The lesser of the two, minus the margin. With
+ * the settings unreadable, the stamp alone minus the margin (QA round 1, N4), and an
+ * unstamped request the old safe clamp, 120: an unstamped request is never held past 120.
+ * Never negative: a ceiling at or below zero is `stale_hook`.
+ */
+export function holdCeilingS(installedHookTimeoutS: number | null, hookWaitS: number | null): number {
+  const hasStamp = hookWaitS !== null && Number.isFinite(hookWaitS) && hookWaitS > 0
+  if (installedHookTimeoutS === null || !Number.isFinite(installedHookTimeoutS) || installedHookTimeoutS <= 0) {
+    // QA round 1 (N4): unreadable settings. The stamp is this invocation's own wait, so it
+    // still bounds the hold; with no stamp, the old safe clamp, never more than 120.
+    return hasStamp ? Math.max(0, hookWaitS! - HOOK_REPLY_MARGIN_S) : BROKER_TIMEOUT_MAX_S
+  }
+  const stamped = hasStamp ? hookWaitS! : LEGACY_HOOK_WAIT_S
+  return Math.max(0, Math.min(installedHookTimeoutS, stamped) - HOOK_REPLY_MARGIN_S)
+}
+
 /**
  * A client must have polled `GET /api/session-questions?client=glasses|phone` this recently,
  * at admission AND while anything is held (QA round 1: 60 s let a phone that locked hold a
@@ -111,7 +234,20 @@ export const DESK_IDLE_MIN_S = 30
 export const MAX_PENDING = 32
 /** A settled item is kept this long so a late answer gets the right code and a retry its replay. */
 export const SETTLED_RETENTION_MS = 10 * 60_000
+/**
+ * 6.60.0: a settled item still waiting at the Mac (`waitingAtMac`) is kept this long, so a
+ * client can keep saying the Mac is waiting until Miles is back. Bounded: an event the spool
+ * never delivered must not leave it waiting forever.
+ */
+export const MAC_WAIT_RETENTION_MS = 60 * 60_000
+/**
+ * 6.60.0 (QA round 1, Ghost Hunter W1): while the session's own row still waits on that very
+ * request (`stillWaitingAtMac`), it is kept up to this long instead of the hour.
+ */
+export const MAC_WAIT_MAX_RETENTION_MS = 24 * 60 * 60_000
 export const MAX_SETTLED = 256
+/** 6.60.0: at most this many settled items in a questions listing, newest first. */
+export const SETTLED_LIST_MAX = 32
 /** Free text for "Other". */
 export const OTHER_TEXT_MAX = 2_000
 /** The approval card's short line: the command (or path, URL, query) as the lens shows it. */
@@ -159,6 +295,11 @@ export interface PermissionRequestFacts {
   fingerprint: string
   /** The envelope's `ts`: when the hook started, epoch ms from the same Mac clock. */
   hookStartedAtMs: number | null
+  /**
+   * 6.60.0: the envelope's `hookWaitS`, the hook block's own `timeout` as the 6.60.0 script
+   * received it (its second argument). Null for an earlier script or block: `holdCeilingS`.
+   */
+  hookWaitS: number | null
 }
 
 export type EnvelopeVerdict =
@@ -182,9 +323,11 @@ function readPermissionRequestEnvelope(body: unknown): EnvelopeRead {
   if (typeof p.tool_name !== 'string' || p.tool_name.trim().length === 0) return { ok: false, reason: 'malformed' }
   if (!isRecord(p.tool_input)) return { ok: false, reason: 'malformed' }
   const ts = typeof body.ts === 'number' && Number.isFinite(body.ts) ? body.ts : null
+  const wait = body.hookWaitS
+  const hookWaitS = typeof wait === 'number' && Number.isInteger(wait) && wait > 0 && wait <= HOOK_WAIT_STAMP_MAX_S ? wait : null
   return {
     ok: true,
-    facts: { sessionId: p.session_id.toLowerCase(), toolName: p.tool_name, toolInput: p.tool_input, hookStartedAtMs: ts },
+    facts: { sessionId: p.session_id.toLowerCase(), toolName: p.tool_name, toolInput: p.tool_input, hookStartedAtMs: ts, hookWaitS },
   }
 }
 
@@ -568,23 +711,103 @@ export interface PermissionBrokerDeps {
   now(): number
   mode(): BrokerMode
   admissionsOpen(): boolean
-  /** The newest counting `GET /api/session-questions`, or null (lib/client-liveness). */
+  /**
+   * The newest counting `GET /api/session-questions`, or null (lib/client-liveness). The
+   * 6.59.0 liveness reads it when `lastLegacyPollAt` is absent.
+   */
   lastQuestionsPollAt(): number | null
+  /**
+   * 6.60.0: the newest counting poll WITHOUT `hold=1`, the 6.59.0 liveness for every older
+   * client (`lastLegacyQuestionsPollAt`). Absent: `lastQuestionsPollAt`.
+   */
+  lastLegacyPollAt?(): number | null
+  /** 6.60.0: the newest counting poll WITH `hold=1` (`lastHoldQuestionsPollAt`). Absent: none. */
+  lastHoldPollAt?(): number | null
   readDeskIdleSeconds(): Promise<number | null>
   deskIdleSeconds(): number
   timeoutMs(): number
+  /** 6.60.0: the away hold in ms, 0 for off (`permissionBrokerAwayHoldMs`). Absent: off. */
+  awayHoldMs?(): number
+  /**
+   * 6.60.0: our PermissionRequest hook's `timeout` in the Claude settings file, or null when it
+   * cannot be read. Absent: null, the old safe clamp (`holdCeilingS`).
+   */
+  installedHookTimeoutS?(): number | null
+  /**
+   * 6.60.0: how long ago the newest QUALIFYING wearer presence was (a `hold=1` poll with a
+   * valid `presenceAgeMs`), or null when there is none since boot (`presenceAgeMs`,
+   * lib/client-liveness). Absent: null.
+   */
+  presenceAgeMs?(): number | null
+  /**
+   * 6.60.0: how recent that presence must be for the away hold, in ms
+   * (`permissionBrokerAwayRecentClientMs`), never below the 30 s live window. Absent: 30 s.
+   */
+  awayRecentClientMs?(): number
+  /**
+   * 6.60.0: the session's row still waits on exactly this request (its hook signal is
+   * waiting, on this fingerprint, and not ended). Keeps a waiting-at-the-Mac item past the
+   * hour. Absent: false.
+   */
+  stillWaitingAtMac?(sessionId: string, fingerprint: string): boolean
   signals?: BrokerSignalSink
   pollMs?: number
   newId?: () => string
   log?: (line: string) => void
 }
 
+/** 6.60.0: how a parked request's deadline was decided, logged once per request. Numbers only. */
+export interface HoldFacts {
+  /** Our PermissionRequest `timeout` in the Claude settings file, or null (unreadable). */
+  installedHookTimeoutS: number | null
+  /** The wait this hook invocation stamped, or null (an earlier script or block). */
+  hookWaitS: number | null
+  /** The away hold in seconds; 0 when it is off. */
+  awayHoldS: number
+  /** `holdCeilingS(installedHookTimeoutS, hookWaitS)`. */
+  ceilingS: number
+  /** The hold, from the hook's own start to the deadline, in seconds. */
+  effectiveDeadlineS: number
+  /** The desk's idle time at admission, in ms. */
+  deskIdleMs: number | null
+  /** A client that can answer was live at admission (6.59.0 liveness, or a `hold=1` client with recent presence). */
+  clientLive: boolean
+  /** 6.60.0: the age of the newest qualifying wearer presence; null for none since boot. */
+  presenceAgeMs: number | null
+  /** 6.60.0: how recent that presence had to be, in seconds. */
+  recentWindowS: number
+  /** 6.60.0: why this request is not away-held, or null when it is. */
+  notAwayReason: NotAwayReason | null
+}
+
+/**
+ * 6.60.0: why a request is not held by the away hold (logged once per decision):
+ * `hold_off` the switch is 0; `ceiling_at_base` the installed hook waits no longer than the
+ * 6.59.0 broker could hold (Install hooks not run); `no_hold_client` no `hold=1` client has
+ * reported wearer presence since boot; `stale_presence` its latest presence is older than the
+ * window; `desk_active` Miles is at the Mac.
+ */
+export type NotAwayReason = 'hold_off' | 'ceiling_at_base' | 'no_hold_client' | 'stale_presence' | 'desk_active'
+
+/**
+ * 6.60.0: the away hold needs a hook that waits longer than the 6.59.0 broker could ever hold
+ * (its 120 s clamp). At or below that, before Install hooks, away semantics are off entirely
+ * and the broker is 6.59.0 (QA round 1, W6).
+ */
+export const AWAY_MIN_CEILING_S = BROKER_TIMEOUT_MAX_S
+
 export interface ParkRequest {
   facts: PermissionRequestFacts
   kind: BrokerItemKind
   questions: BrokerQuestion[] | null
   approval: ApprovalCard | null
   deadlineAt: number
+  /**
+   * 6.60.0: held by the away hold: a client going quiet does not hand it back (desk activity
+   * still does). False with the away hold off, or for a request built without it.
+   */
+  awayHold?: boolean
+  hold?: HoldFacts
 }
 
 export type BrokerAdmission = { ok: true; request: ParkRequest } | { ok: false; reason: BrokerFastPath }
@@ -611,6 +834,14 @@ interface BrokerItem {
   handedBackBy: string | null
   channel: HookReplyChannel | null
   timer: ReturnType<typeof setTimeout> | null
+  /** 6.60.0: held by the away hold (`ParkRequest.awayHold`). */
+  awayHold: boolean
+  /**
+   * 6.60.0: settled with `{}` written to the hook (handed to the desk, expired, no client,
+   * drained), so the Mac's own dialog is showing, and the session has not moved past the
+   * request since (`sessionMovedPast`).
+   */
+  waitingAtMac: boolean
 }
 
 export interface SessionQuestionView {
@@ -620,11 +851,46 @@ export interface SessionQuestionView {
   kind: BrokerItemKind
   tool: string
   createdAt: string
+  /** When it stops being answerable from here. 6.60.0: the away hold's deadline when held by it. */
   deadlineAt: string
   questions?: BrokerQuestion[]
   approval?: ApprovalCard
+  /** 6.60.0: an answer posted now still reaches the session. Always true for a pending item. */
+  answerable: boolean
+  /** 6.60.0: held by the away hold: it stays answerable while no client polls, until `deadlineAt` or the desk. */
+  awayHold: boolean
+  /** 6.60.0: handed to the Mac's own dialog and still waiting there. Always false for a pending item. */
+  waitingAtMac: boolean
 }
 
+/**
+ * 6.60.0: a settled item as the questions route lists it (`settled`): codes and times only,
+ * never the questions, the card, or what was chosen.
+ */
+export interface SettledQuestionView {
+  id: string
+  sessionId: string
+  provider: 'claude'
+  kind: BrokerItemKind
+  tool: string
+  createdAt: string
+  deadlineAt: string
+  settledAt: string
+  resolution: BrokerResolution
+  /** Always false: a settled item takes no answer. */
+  answerable: false
+  awayHold: boolean
+  /**
+   * The broker gave the hook `{}`, so the Mac's own dialog showed, and the session has not
+   * moved past the request since: its tool has not run nor been denied, its turn has not
+   * ended. A client can say the Mac is waiting on an answer.
+   */
+  waitingAtMac: boolean
+}
+
+/** 6.60.0: the resolutions that write `{}` to a listening hook, so the Mac's dialog shows. */
+const MAC_DIALOG_RESOLUTIONS: ReadonlySet<BrokerResolution> = new Set(['handed_to_desk', 'expired', 'no_client', 'drained'])
+
 /**
  * `/api/health`'s `permissionBroker`. Counts, the mode and two timestamps: never an id,
  * a question, a command, or how many are held right now (that is on the authenticated
@@ -648,6 +914,10 @@ export interface PermissionBrokerHealth {
     invalidAnswer: number
     /** A desk read that failed while something was held. */
     deskUnreadable: number
+    /** 6.60.0: of `parked`, those held by the away hold. */
+    awayHeld: number
+    /** 6.60.0: of `parked`, those parked while no client that can answer was polling. */
+    parkedWithoutClient: number
     /** Requests answered `{}` without being parked, keyed by the camelCase of the reason. */
     fastPath: Record<string, number>
   }
@@ -682,6 +952,26 @@ export const CLIENT_ANSWER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/
 /** Events that end the turn a request was part of: every held request of the session is moot. */
 const TURN_BOUNDARIES: ReadonlySet<string> = new Set(['Stop', 'StopFailure', 'SessionEnd', 'UserPromptSubmit'])
 
+/**
+ * The session moved past a request without the broker: its turn ended (or a new session
+ * started over it), or its own tool ran or was denied, which means the Mac's dialog was
+ * answered. For a pending item that is a retraction; for one handed to the Mac (6.60.0) it
+ * means the Mac is no longer waiting on it. A question's tool is AskUserQuestion; an
+ * approval matches by fingerprint, or by tool name for a denial.
+ */
+function sessionMovedPast(item: Pick<BrokerItem, 'kind' | 'fingerprint' | 'toolName'>, env: HookEnvelope, toolName: string, fingerprint: string, strict = false): boolean {
+  if (TURN_BOUNDARIES.has(env.event) || (env.event === 'SessionStart' && env.payload.source !== 'compact')) return true
+  if (env.event === 'PostToolUse' || env.event === 'PostToolUseFailure' || env.event === 'PermissionDenied') {
+    // `strict` (QA round 1, N3), for "the Mac is no longer waiting": an approval only by its
+    // own fingerprint, never by a denial of the same tool name, which may be another dialog
+    // of the same session still on screen.
+    if (item.kind === 'question') return toolName === ASK_USER_QUESTION_TOOL
+    if (strict) return fingerprint === item.fingerprint
+    return fingerprint === item.fingerprint || (env.event === 'PermissionDenied' && toolName === item.toolName)
+  }
+  return false
+}
+
 export class PermissionBroker {
   private readonly deps: PermissionBrokerDeps
   private readonly items = new Map<string, BrokerItem>()
@@ -689,13 +979,26 @@ export class PermissionBroker {
   private pollInFlight = false
   /** Failed desk reads in a row while something is held. Two hand everything back. */
   private deskUnreadableStreak = 0
-  private readonly counters = { parked: 0, answered: 0, handedToDesk: 0, handedBack: 0, expired: 0, hookGone: 0, retracted: 0, drained: 0, noClient: 0, invalidAnswer: 0, deskUnreadable: 0 }
+  private readonly counters = { parked: 0, answered: 0, handedToDesk: 0, handedBack: 0, expired: 0, hookGone: 0, retracted: 0, drained: 0, noClient: 0, invalidAnswer: 0, deskUnreadable: 0, awayHeld: 0, parkedWithoutClient: 0 }
   private readonly fastPaths: Record<string, number> = {}
   private lastFastPath: BrokerFastPath | null = null
   private lastFastPathAt: number | null = null
 
+  /**
+   * 6.60.0 (QA round 1, Ghost Hunter W1): the server cannot know about a waiting-at-the-Mac
+   * item settled at or before this time: it started then, or it later dropped one that was
+   * still waiting. Never moves back.
+   */
+  private waitingForgottenBefore: number
+
   constructor(deps: PermissionBrokerDeps) {
     this.deps = deps
+    this.waitingForgottenBefore = deps.now()
+  }
+
+  /** 6.60.0: `waitingAtMacForgottenBefore` on the questions route, in ms. */
+  waitingAtMacForgottenBeforeMs(): number {
+    return this.waitingForgottenBefore
   }
 
   private log(line: string): void {
@@ -703,11 +1006,17 @@ export class PermissionBroker {
   }
 
   /** A request answered `{}` without being parked, counted by why. */
-  noteFastPath(reason: BrokerFastPath): { ok: false; reason: BrokerFastPath } {
+  noteFastPath(reason: BrokerFastPath, context: { notAway?: NotAwayReason; presence?: { ageMs: number | null; windowMs: number }; clientLive?: boolean } = {}): { ok: false; reason: BrokerFastPath } {
     const key = camelKey(reason)
     this.fastPaths[key] = (this.fastPaths[key] ?? 0) + 1
     this.lastFastPath = reason
     this.lastFastPathAt = this.deps.now()
+    // 6.60.0 (QA round 1, Completionist N9, Ghost Hunter W5): one line per request answered
+    // `{}`, with why, how old the wearer's presence is and the window. Numbers only.
+    let presence = context.presence
+    if (!presence) { try { presence = this.presence(this.deps.now()) } catch { presence = undefined } }
+    const age = presence?.ageMs === null || presence?.ageMs === undefined ? 'null' : String(Math.round(presence.ageMs))
+    this.log(`fast path ${reason}${context.notAway ? ` not_away=${context.notAway}` : ''} presenceAgeMs=${age} windowMs=${presence?.windowMs ?? 'null'}${context.clientLive === undefined ? '' : ` clientLive=${context.clientLive}`}`)
     return { ok: false, reason }
   }
 
@@ -717,12 +1026,89 @@ export class PermissionBroker {
    * forever.
    */
   private clientLive(now: number): boolean {
-    const polledAt = this.deps.lastQuestionsPollAt()
-    if (polledAt === null || !Number.isFinite(polledAt)) return false
+    // 6.60.0: the 6.59.0 liveness is a poll WITHOUT `hold=1` (every older client).
+    const legacy = this.deps.lastLegacyPollAt
+    return this.polledWithin(legacy ? legacy() : this.deps.lastQuestionsPollAt(), now)
+  }
+
+  /** A poll stamp within the live window, and not more than the skew ahead of the clock. */
+  private polledWithin(polledAt: number | null | undefined, now: number): boolean {
+    if (polledAt === null || polledAt === undefined || !Number.isFinite(polledAt)) return false
     if (polledAt - now > POLL_FUTURE_SKEW_MS) return false
     return now - polledAt <= CLIENT_LIVE_WINDOW_MS
   }
 
+  /** 6.60.0: the away hold in ms; 0 when off, absent, or unreadable. */
+  private awayHoldMs(): number {
+    let ms = 0
+    try { ms = Number(this.deps.awayHoldMs?.() ?? 0) } catch { ms = 0 }
+    return Number.isFinite(ms) && ms > 0 ? ms : 0
+  }
+
+  /** 6.60.0: the recent-presence window in ms, never below the 30 s live window. */
+  private recentWindowMs(): number {
+    let ms = 0
+    try { ms = Number(this.deps.awayRecentClientMs?.() ?? 0) } catch { ms = 0 }
+    return Math.max(CLIENT_LIVE_WINDOW_MS, Number.isFinite(ms) && ms > 0 ? ms : 0)
+  }
+
+  /**
+   * 6.60.0: the newest qualifying wearer presence and what it allows, read now:
+   *   - `recent`: within the window, so the away hold may apply;
+   *   - `holdLive`: a `hold=1` client polled within the live window AND its presence is
+   *     recent, so it counts as a live client the way an older client's poll does. A
+   *     connected lens nobody wears never counts (QA round 1, Skeptic W1).
+   */
+  private presence(now: number): { ageMs: number | null; recent: boolean; holdLive: boolean; windowMs: number } {
+    let ageMs: number | null = null
+    try { ageMs = this.deps.presenceAgeMs?.() ?? null } catch { ageMs = null }
+    if (typeof ageMs !== 'number' || !Number.isFinite(ageMs) || ageMs < 0) ageMs = null
+    const windowMs = this.recentWindowMs()
+    const recent = ageMs !== null && ageMs <= windowMs
+    let holdPollAt: number | null = null
+    try { holdPollAt = this.deps.lastHoldPollAt?.() ?? null } catch { holdPollAt = null }
+    return { ageMs, recent, holdLive: recent && this.polledWithin(holdPollAt, now), windowMs }
+  }
+
+  /** 6.60.0: the installed hook timeout, or null when absent or unreadable. */
+  private installedHookTimeoutS(): number | null {
+    let value: number | null = null
+    try { value = this.deps.installedHookTimeoutS?.() ?? null } catch { value = null }
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null
+  }
+
+  /**
+   * 6.60.0: how long a request arriving now, from a hook that stamped `hookWaitS`, may be held:
+   * the away hold when it applies (never shorter than the base timeout), else the base
+   * timeout, and never past `holdCeilingS`. `ceilingAllowsAway` is the hook waiting longer
+   * than the 6.59.0 broker could hold.
+   */
+  private holdMs(hookWaitS: number | null, away: boolean): { holdMs: number; awayHoldMs: number; installedHookTimeoutS: number | null; ceilingS: number; ceilingAllowsAway: boolean } {
+    const awayHoldMs = away ? this.awayHoldMs() : 0
+    const installedHookTimeoutS = this.installedHookTimeoutS()
+    const ceilingS = holdCeilingS(installedHookTimeoutS, hookWaitS)
+    const baseMs = this.deps.timeoutMs()
+    const wanted = awayHoldMs > 0 ? Math.max(baseMs, awayHoldMs) : baseMs
+    return { holdMs: Math.min(wanted, ceilingS * 1000), awayHoldMs, installedHookTimeoutS, ceilingS, ceilingAllowsAway: ceilingS > AWAY_MIN_CEILING_S }
+  }
+
+  /** 6.60.0: the recent-presence window, for the questions route and `/api/models`. */
+  awayRecentClientWindowMs(): number {
+    return this.recentWindowMs()
+  }
+
+  /**
+   * 6.60.0: the longest a question that starts now while Miles is away is held, for a hook
+   * as the settings file has it, when a `hold=1` client reported wearer presence within the
+   * window (`awayHoldMs` on the questions route and `/api/models`). 0 when the away hold is
+   * off, or when the installed hook waits no longer than the 6.59.0 broker could hold.
+   */
+  awayHoldNowMs(): number {
+    if (this.awayHoldMs() === 0) return 0
+    const hold = this.holdMs(this.installedHookTimeoutS(), true)
+    return hold.ceilingAllowsAway ? hold.holdMs : 0
+  }
+
   /** The desk-idle threshold, never below DESK_IDLE_MIN_S. */
   private deskIdleThreshold(): number {
     const configured = Number(this.deps.deskIdleSeconds())
@@ -756,17 +1142,33 @@ export class PermissionBroker {
       if (UNBROKERED_TOOLS.has(facts.toolName)) return this.noteFastPath('unsupported_tool')
     }
     const now = this.deps.now()
-    if (!this.clientLive(now)) return this.noteFastPath('no_client')
+    const presence = this.presence(now)
+    const clientLive = this.clientLive(now) || presence.holdLive
+    // 6.60.0: the away hold applies only when it is on, the installed hook waits longer than
+    // the 6.59.0 broker could hold, and a `hold=1` client reported wearer presence within the
+    // window (Miles, 19:54; QA round 1).
+    const switchOn = this.awayHoldMs() > 0
+    const ceilingAllowsAway = this.holdMs(facts.hookWaitS, false).ceilingAllowsAway
+    const away = switchOn && ceilingAllowsAway && presence.recent
+    const notAwayReason: NotAwayReason | null = away ? null
+      : !switchOn ? 'hold_off'
+      : !ceilingAllowsAway ? 'ceiling_at_base'
+      : presence.ageMs === null ? 'no_hold_client'
+      : 'stale_presence'
+    const hold = this.holdMs(facts.hookWaitS, away)
+    // With it, a request is held whether or not a client is polling right now, so a lens or
+    // phone that comes back can still answer it. Without it, no client is `{}`, as in 6.59.0.
+    if (!clientLive && !away) return this.noteFastPath('no_client', { notAway: notAwayReason!, presence, clientLive })
     // The deadline counts from when the HOOK started, when its stamp is sane: a request the
     // server read late must still be answered before the hook's curl gives up.
     const requestedAt = facts.hookStartedAtMs !== null && facts.hookStartedAtMs <= now ? facts.hookStartedAtMs : now
-    const deadlineAt = requestedAt + this.deps.timeoutMs()
+    const deadlineAt = requestedAt + hold.holdMs
     if (deadlineAt <= now) return this.noteFastPath('stale_hook')
     if (this.pendingCount() >= MAX_PENDING) return this.noteFastPath('capacity')
     let idle: number | null = null
     try { idle = await this.deps.readDeskIdleSeconds() } catch { idle = null }
     if (idle === null) return this.noteFastPath('desk_unknown')
-    if (idle < this.deskIdleThreshold()) return this.noteFastPath('desk_active')
+    if (idle < this.deskIdleThreshold()) return this.noteFastPath('desk_active', { notAway: 'desk_active', presence, clientLive })
     const mode = this.deps.mode()
     if (mode === 'off') return this.noteFastPath('broker_off')
     if (!this.deps.admissionsOpen()) return this.noteFastPath('draining')
@@ -785,7 +1187,20 @@ export class PermissionBroker {
       approval = approvalCard(facts.toolName, facts.toolInput)
     }
     const fingerprint = toolFingerprint(facts.toolName, facts.toolInput)
-    return { ok: true, request: { facts: { ...facts, fingerprint }, kind, questions, approval, deadlineAt } }
+    const awayHold = away
+    const holdFacts: HoldFacts = {
+      installedHookTimeoutS: hold.installedHookTimeoutS,
+      hookWaitS: facts.hookWaitS,
+      awayHoldS: Math.round(hold.awayHoldMs / 1000),
+      ceilingS: hold.ceilingS,
+      effectiveDeadlineS: Math.round(hold.holdMs / 1000),
+      deskIdleMs: idle * 1000,
+      clientLive,
+      presenceAgeMs: presence.ageMs === null ? null : Math.round(presence.ageMs),
+      recentWindowS: Math.round(presence.windowMs / 1000),
+      notAwayReason,
+    }
+    return { ok: true, request: { facts: { ...facts, fingerprint }, kind, questions, approval, deadlineAt, awayHold, hold: holdFacts } }
   }
 
   /** Hold the hook's response until exactly one resolution. Returns the item id. */
@@ -813,14 +1228,20 @@ export class PermissionBroker {
       handedBackBy: null,
       channel,
       timer: null,
+      awayHold: request.awayHold === true,
+      waitingAtMac: false,
     }
     this.items.set(id, item)
     this.counters.parked++
+    if (item.awayHold) this.counters.awayHeld++
+    if (request.hold && !request.hold.clientLive) this.counters.parkedWithoutClient++
     item.timer = setTimeout(() => { this.settle(item, 'expired') }, Math.max(0, request.deadlineAt - now))
     item.timer.unref?.()
     try { this.deps.signals?.attach(item.sessionId, id, item.fingerprint) } catch { /* rows are advisory */ }
     this.ensurePolling()
-    this.log(`parked ${id} kind=${item.kind} session=${item.sessionId.slice(0, 8)} deadline_s=${Math.round((request.deadlineAt - now) / 1000)} pending=${this.pendingCount()}`)
+    // 6.60.0: the numbers the deadline came from, once per request (never text).
+    const hold = request.hold ? ` hold=${JSON.stringify(request.hold)}` : ''
+    this.log(`parked ${id} kind=${item.kind} session=${item.sessionId.slice(0, 8)} deadline_s=${Math.round((request.deadlineAt - now) / 1000)} away_hold=${item.awayHold} pending=${this.pendingCount()}${hold}`)
     return id
   }
 
@@ -838,7 +1259,10 @@ export class PermissionBroker {
     if (item.timer) clearTimeout(item.timer)
     item.timer = null
     if (resolution !== 'hook_gone') {
-      try { item.channel?.reply({}) } catch { /* the hook is gone anyway */ }
+      let written = false
+      try { written = item.channel?.reply({}) === true } catch { /* the hook is gone anyway */ }
+      // 6.60.0: `{}` reached the hook, so the Mac's own dialog is up for it now.
+      item.waitingAtMac = written && MAC_DIALOG_RESOLUTIONS.has(resolution)
     }
     item.channel = null
     // A settled item is kept for its codes, not its content.
@@ -870,11 +1294,70 @@ export class PermissionBroker {
         deadlineAt: new Date(item.deadlineAt).toISOString(),
         ...(item.questions ? { questions: item.questions } : {}),
         ...(item.approval ? { approval: item.approval } : {}),
+        answerable: true,
+        awayHold: item.awayHold,
+        waitingAtMac: false,
       })
     }
     return views.sort((a, b) => a.createdAt.localeCompare(b.createdAt))
   }
 
+  /**
+   * 6.60.0: the settled items still kept, newest settled first, at most SETTLED_LIST_MAX:
+   * codes and times only. `waitingAtMac` says the Mac's own dialog is still waiting on one.
+   */
+  settledList(): SettledQuestionView[] {
+    this.prune()
+    const settled: BrokerItem[] = []
+    for (const item of this.items.values()) if (item.state !== 'pending' && item.settledAt !== null) settled.push(item)
+    settled.sort((a, b) => (b.settledAt ?? 0) - (a.settledAt ?? 0))
+    // Every item the Mac still waits on is listed whatever the cap, so a missing one is never
+    // read as "moved past" (Ghost Hunter W1); the newest others fill up to SETTLED_LIST_MAX.
+    const waiting = settled.filter(item => item.waitingAtMac)
+    const others = settled.filter(item => !item.waitingAtMac).slice(0, Math.max(0, SETTLED_LIST_MAX - waiting.length))
+    const listed = [...waiting, ...others].sort((a, b) => (b.settledAt ?? 0) - (a.settledAt ?? 0))
+    return listed.map(item => ({
+      id: item.id,
+      sessionId: item.sessionId,
+      provider: 'claude' as const,
+      kind: item.kind,
+      tool: item.toolName,
+      createdAt: new Date(item.createdAt).toISOString(),
+      deadlineAt: new Date(item.deadlineAt).toISOString(),
+      settledAt: new Date(item.settledAt!).toISOString(),
+      resolution: item.state as BrokerResolution,
+      answerable: false as const,
+      awayHold: item.awayHold,
+      waitingAtMac: item.waitingAtMac,
+    }))
+  }
+
+  /**
+   * 6.60.0 (QA round 1, N2): the session's row now reads ended (its process is gone, or it
+   * ended), so no Mac dialog of it can still be waiting. Cleared at once, not after the hour.
+   * Takes a full session id or the registry's eight-character form. Returns how many cleared.
+   */
+  sessionRowEnded(sessionId: string): number {
+    const wanted = typeof sessionId === 'string' ? sessionId.toLowerCase() : ''
+    if (wanted.length < 8) return 0
+    let cleared = 0
+    for (const item of this.items.values()) {
+      if (!item.waitingAtMac) continue
+      if (item.sessionId !== wanted && !(wanted.length < 36 && item.sessionId.startsWith(wanted))) continue
+      item.waitingAtMac = false
+      cleared++
+    }
+    if (cleared > 0) this.log(`session row ended: ${cleared} no longer waiting at the Mac session=${wanted.slice(0, 8)}`)
+    return cleared
+  }
+
+  /** 6.60.0: how many settled items are still waiting at the Mac. */
+  waitingAtMacCount(): number {
+    let n = 0
+    for (const item of this.items.values()) if (item.state !== 'pending' && item.waitingAtMac) n++
+    return n
+  }
+
   /**
    * `POST /api/session-questions/:id/answer`. Synchronous from the state check to the
    * reply, so two racing answers cannot both win: the first one settles the item and the
@@ -1040,17 +1523,13 @@ export class PermissionBroker {
         } catch { /* rows are advisory */ }
         continue
       }
-      if (item.state !== 'pending' || env.ts < item.requestedAt) continue
-      if (TURN_BOUNDARIES.has(env.event) || (env.event === 'SessionStart' && p.source !== 'compact')) {
-        this.settle(item, 'retracted')
+      // 6.60.0: one handed to the Mac's dialog stops waiting there when the session moves past it.
+      if (item.waitingAtMac && env.ts >= item.requestedAt && sessionMovedPast(item, env, toolName, fingerprint, true)) {
+        item.waitingAtMac = false
         continue
       }
-      if (env.event === 'PostToolUse' || env.event === 'PostToolUseFailure' || env.event === 'PermissionDenied') {
-        const same = item.kind === 'question'
-          ? toolName === ASK_USER_QUESTION_TOOL
-          : fingerprint === item.fingerprint || (env.event === 'PermissionDenied' && toolName === item.toolName)
-        if (same) this.settle(item, 'retracted')
-      }
+      if (item.state !== 'pending' || env.ts < item.requestedAt) continue
+      if (sessionMovedPast(item, env, toolName, fingerprint)) this.settle(item, 'retracted')
     }
   }
 
@@ -1075,7 +1554,16 @@ export class PermissionBroker {
   async tick(): Promise<void> {
     if (this.pendingCount() === 0) { this.stopPolling(); return }
     if (!this.deps.admissionsOpen()) { this.settleAll('drained'); return }
-    if (!this.clientLive(this.deps.now())) { this.settleAll('no_client'); return }
+    const now = this.deps.now()
+    const presence = this.presence(now)
+    if (!(this.clientLive(now) || presence.holdLive)) {
+      // 6.60.0: an item held by the away hold outlives the client going quiet, but only while
+      // the wearer's latest presence is still within the window (QA round 1, Skeptic W2: a
+      // single glance must not hold a question 10 more minutes). The desk below still hands
+      // it back.
+      this.settleAll('no_client', item => !item.awayHold || !presence.recent)
+      if (this.pendingCount() === 0) return
+    }
     if (this.pollInFlight) return
     this.pollInFlight = true
     let idle: number | null = null
@@ -1091,25 +1579,49 @@ export class PermissionBroker {
     this.settleAll('handed_to_desk')
   }
 
-  private settleAll(resolution: 'handed_to_desk' | 'drained' | 'no_client'): void {
-    for (const item of [...this.items.values()]) if (item.state === 'pending') this.settle(item, resolution)
+  private settleAll(resolution: 'handed_to_desk' | 'drained' | 'no_client', only: (item: BrokerItem) => boolean = () => true): void {
+    for (const item of [...this.items.values()]) if (item.state === 'pending' && only(item)) this.settle(item, resolution)
     if (this.pendingCount() === 0) this.stopPolling()
   }
 
-  /** Settled items are kept for SETTLED_RETENTION_MS (late answers, replays), at most MAX_SETTLED. */
+  /**
+   * Settled items are kept for SETTLED_RETENTION_MS (late answers, replays), at most
+   * MAX_SETTLED. 6.60.0: one still waiting at the Mac is kept for MAC_WAIT_RETENTION_MS.
+   */
   private prune(): void {
     const now = this.deps.now()
     const settled: BrokerItem[] = []
     for (const item of this.items.values()) {
       if (item.state === 'pending') continue
-      if (item.settledAt !== null && now - item.settledAt > SETTLED_RETENTION_MS) this.items.delete(item.id)
+      if (item.settledAt !== null && now - item.settledAt > this.retentionMs(item)) this.forget(item)
       else settled.push(item)
     }
+    // Over the cap, the oldest that no longer wait go first.
     const excess = settled.length - MAX_SETTLED
-    for (let i = 0; i < excess; i++) this.items.delete(settled[i]!.id)
+    if (excess > 0) {
+      settled.sort((a, b) => Number(a.waitingAtMac) - Number(b.waitingAtMac) || (a.settledAt ?? 0) - (b.settledAt ?? 0))
+      for (let i = 0; i < excess; i++) this.forget(settled[i]!)
+    }
     if (this.pendingCount() === 0) this.stopPolling()
   }
 
+  /**
+   * How long a settled item is kept: ten minutes; an hour while the Mac waits on it; a day
+   * while its session's row still waits on that very request (Ghost Hunter W1).
+   */
+  private retentionMs(item: BrokerItem): number {
+    if (!item.waitingAtMac) return SETTLED_RETENTION_MS
+    let still = false
+    try { still = this.deps.stillWaitingAtMac?.(item.sessionId, item.fingerprint) === true } catch { still = false }
+    return still ? MAC_WAIT_MAX_RETENTION_MS : MAC_WAIT_RETENTION_MS
+  }
+
+  /** Drop a settled item. One the Mac may still wait on moves the forgotten horizon. */
+  private forget(item: BrokerItem): void {
+    this.items.delete(item.id)
+    if (item.waitingAtMac && item.settledAt !== null && item.settledAt > this.waitingForgottenBefore) this.waitingForgottenBefore = item.settledAt
+  }
+
   health(): PermissionBrokerHealth {
     const mode = this.deps.mode()
     let polledAt: number | null = null
@@ -1184,6 +1696,17 @@ export interface SessionQuestionsCapability {
   protocolVersion: number
   pollIntervalMs: number
   liveWindowMs: number
+  /**
+   * 6.60.0: the longest a question that starts while you are away is held for the glasses,
+   * whether or not a client is polling (`PermissionBroker.awayHoldNowMs`); 0 when the away
+   * hold is off or the broker is.
+   */
+  awayHoldMs: number
+  /**
+   * 6.60.0: the away hold applies only when a client that can answer polled within this many
+   * ms (`COS_PERMISSION_BROKER_AWAY_RECENT_CLIENT_S`); 0 means it must be polling right now.
+   */
+  awayRecentClientMs: number
 }
 
 /**
@@ -1194,11 +1717,17 @@ export interface SessionQuestionsCapability {
 export function sessionQuestionsCapability(): SessionQuestionsCapability {
   let mode: BrokerMode = 'off'
   try { mode = registered ? registered.health().mode : 'off' } catch { mode = 'off' }
+  let awayHoldMs = 0
+  try { awayHoldMs = registered && mode !== 'off' ? registered.awayHoldNowMs() : 0 } catch { awayHoldMs = 0 }
+  let awayRecentClientMs = 0
+  try { awayRecentClientMs = registered && awayHoldMs > 0 ? registered.awayRecentClientWindowMs() : 0 } catch { awayRecentClientMs = 0 }
   return {
     enabled: mode !== 'off',
     mode,
     protocolVersion: SESSION_QUESTIONS_PROTOCOL_VERSION,
     pollIntervalMs: QUESTIONS_POLL_INTERVAL_MS,
     liveWindowMs: CLIENT_LIVE_WINDOW_MS,
+    awayHoldMs,
+    awayRecentClientMs,
   }
 }