@raidiant/notifai 0.3.0 → 0.5.0

package/src/hooks.ts

@@ -11,8 +11,19 @@ import {
   writeFileSync,
 } from 'node:fs'
 import path from 'node:path'
-import type { LifecycleEndState, QuestionT, ReplyView } from '@raidiant/notifai-protocol'
-import type { ApiClient } from './client.js'
+import type {
+  LifecycleEndState,
+  ListRepliesResponse,
+  NotificationDraftT,
+  QuestionT,
+  ReplyView,
+  SubmissionReceipt,
+} from '@raidiant/notifai-protocol'
+import {
+  ApiCallError,
+  isRetryableReplyPollError,
+  type ApiClient,
+} from './client.js'
 import {
   loadConfig,
   projectSessionPointerPath,
@@ -23,20 +34,30 @@ import {
 } from './config.js'
 import { buildDraft } from './send.js'
 import { atomicWriteFileSync } from './atomic-file.js'
+import { withFileLock } from './file-lock.js'
+import type { Logger } from './logging.js'
+import {
+  HARNESS_CAPABILITIES,
+  HARNESSES,
+  type DeliveryRoute,
+  type Harness,
+} from './harnesses.js'
 
 /**
  * Harness hook handlers.
  *
  * The supported harnesses expose the same useful lifecycle joints: a turn-end
- * event and an event that fires when the user submits a prompt. Claude Code,
- * Codex, and Cursor can continue directly from a turn-end answer. OpenCode
- * preserves the pending answer at turn end and injects it on the next prompt.
- * No question detection or context-window state is needed in either path.
+ * event and an event that fires when the user submits a prompt. Claude Code
+ * and Codex can continue directly from a turn-end answer. Harnesses without a
+ * proven exact-session continuation fail closed at question admission.
  *
- * The load-bearing constraint is that these hooks are synchronous: while one
- * blocks, the harness cannot show its own prompt either. So a hook may only
- * take over when the user is demonstrably absent. Present user, or no evidence
- * either way, means exit immediately and let the terminal do its job.
+ * Where the user is standing no longer decides anything here. It used to: the
+ * turn-end hook held the terminal for as long as it waited, so waiting was
+ * only defensible while the person was demonstrably not at the keyboard. On
+ * Claude Code the handler now returns instantly and the waiter runs out of
+ * band, and nothing is monopolised in the first place — so the question is
+ * simply whether the user wants to be reached, which they answer once in
+ * configuration rather than implicitly with every keystroke.
  */
 
 /** Fields we read from harness hook JSON. Everything else is passed through. */
@@ -57,6 +78,8 @@ export interface HookEnvelope {
 export interface SessionState {
   /** Epoch ms of the user's last prompt in this session — our presence signal. */
   last_prompt_at?: number
+  /** Epoch ms of the last observed Stop hook, distinct from prompt routing. */
+  last_stop_at?: number
   /**
    * Questions registered by `notifai ask`, in registration order, each
    * awaiting escalation or its answer. A list, deliberately: registering a
@@ -79,11 +102,42 @@ export interface SessionState {
    * costs nothing and a missed one costs a stale notification for ever.
    */
   retiring?: RetiringQuestion[]
-  /** Tracks bounded Stop continuations so a follow-up ask is delivered once. */
+  /**
+   * Tracks bounded Stop continuations so a follow-up ask is delivered once.
+   * `count` is how many answer generations have run consecutively without the
+   * user taking a turn themselves; their next prompt starts it over.
+   */
   continuation?: {
     answered_at: number
     count: number
   }
+  /**
+   * A phone answer durably captured but not yet acknowledged. It stays here
+   * until a delivery is acknowledged — by the route's own write, or by the
+   * successor Stop of a blocking continuation — so a crash before the answer
+   * reaches the harness replays it instead of erasing it.
+   */
+  accepted?: AcceptedAnswerDelivery
+}
+
+interface AcceptedAnswerDelivery {
+  answers: AnsweredPending[]
+  remaining: number
+  recorded_at: number
+  /**
+   * Epoch ms when a route's own write handed this answer to the harness, with
+   * the route that performed it. Recorded so that "this answer was delivered"
+   * is a fact on the journal rather than something inferred from a harness flag
+   * that only one route ever sets.
+   */
+  delivered_at?: number
+  delivered_route?: string
+  /**
+   * How many times this answer has been handed to any route. The route-agnostic
+   * loop backstop: bounded by `MAX_CONTINUATION_COUNT` in one place every route
+   * passes through.
+   */
+  delivery_attempts?: number
 }
 
 /** A delivered question awaiting its retirement push. */
@@ -127,6 +181,8 @@ const ORPHAN_TTL_MS = 24 * 3600 * 1000
 const ORPHAN_QUEUE_CAP = 50
 
 export interface PendingQuestion {
+  /** Stable local identity across racing state writers and submit recovery. */
+  question_id?: string
   /** One-line summary: the single question's text, or the set's first. */
   question: string
   /**
@@ -147,69 +203,75 @@ export interface PendingQuestion {
   collapse_key?: string
   /** Exact fanout of the live question; routing config may change afterwards. */
   device_ids?: string[]
+  /** Absolute end of the server reply window and its local continuation owner. */
+  reply_deadline_at?: number
+  /** Frozen before the first network byte, so an ambiguous submit is replayable. */
+  submission?: PendingSubmissionIntent
 }
 
-/** How often the grace window rechecks whether the user has come back. */
-const GRACE_POLL_MS = 5_000
+interface PendingSubmissionIntent {
+  request_id: string
+  idempotency_key: string
+  collapse_key: string
+  device_ids: string[]
+  draft: NotificationDraftT
+  owner_deadline_at: number
+}
+
+function summarizeRequestIds(entries: readonly PendingQuestion[]): {
+  ids: string[]
+  display: string
+} {
+  const ids = entries.flatMap((entry) =>
+    entry.request_id === undefined ? [] : [entry.request_id],
+  )
+  return { ids, display: ids.join(', ') }
+}
 
 /**
- * Total seconds a Stop hook may spend blocking. Both harnesses kill a command
- * hook at 600s, and a killed hook loses an answer the user has already given,
- * so the grace window yields to the reply wait rather than the other way round.
+ * The waiter's whole wall clock: the terminal-first timer, submission, and the
+ * wait for an answer, from the moment the turn-end hook starts.
+ *
+ * One plain ceiling, deliberately not a budget carved into reserves. The
+ * reserves existed to fit every phase inside a *held* turn; on Claude Code the
+ * turn is not held any more, and on a host that still holds one the useful
+ * question is only how long that host is willing to wait in total.
  */
-const STOP_BUDGET_SECONDS = 480
+export const WAITER_CEILING_SECONDS = 480
 
-export type GraceOutcome =
-  /** The window elapsed with the user still gone; escalate. */
-  | 'absent'
-  /** The user touched the machine; the terminal is theirs. */
-  | 'user-returned'
-  /** No idle source, so waiting would hold a terminal we cannot monitor. */
-  | 'no-signal'
+/**
+ * The wire contract's shortest reply window. A question submitted with less
+ * than this is rejected outright, and accepting one would in any case let the
+ * server go on taking an answer after the waiter that owns it has returned.
+ */
+const MIN_REPLY_WINDOW_SECONDS = 60
 
 /**
  * The terminal-first wait: the question sits in the terminal for
  * `ask_grace_seconds` from when it was sent, and only then reaches companion
  * devices.
  *
- * Holding a blocking Stop hook open is normally hostile — while it blocks, the
- * harness cannot show its prompt either, so a user wanting to answer locally is
- * locked out. What makes it safe is that the wait is abandoned the moment the
- * user touches the keyboard or mouse. The block therefore only ever persists
- * while they are demonstrably not using the machine, which costs them nothing.
+ * A plain timer, and nothing else. It once polled an idle signal so it could
+ * abandon the wait the moment the user touched the keyboard — necessary while
+ * the wait blocked the terminal, because a user wanting to answer locally was
+ * otherwise locked out of their own prompt. Nothing is monopolised now, so
+ * there is nothing to watch for and no machine this cannot run on.
  *
- * That safety depends entirely on the idle signal, so with no idle source this
- * refuses to wait at all rather than holding a terminal it cannot monitor.
- *
- * With `require_idle` off the whole calculus changes: the user has said they
- * want the question to reach them whether or not they are at the keyboard, so
- * there is nothing to watch for and this becomes what its name always claimed —
- * a plain timer. It then works on machines with no idle source too.
+ * The window is measured from registration, not from the turn's end: a
+ * question the agent asked five minutes ago while it kept working has already
+ * served its wait. A stamp from the future would otherwise consume the whole
+ * ceiling and leave no room to answer, so it starts no later than now.
  */
-export async function awaitGrace(ctx: HookContext, askedAt: number): Promise<GraceOutcome> {
-  const threshold = ctx.config.away_after_seconds.value
-  // Never let the grace window eat the reply wait's share of the hook budget.
-  const graceSeconds = Math.min(
-    ctx.config.ask_grace_seconds.value,
-    Math.max(0, STOP_BUDGET_SECONDS - ctx.config.hook_reply_timeout_seconds.value),
-  )
-  // `asked_at` is wall-clock too, and the same jumps apply: a stamp from the
-  // future would wait far past the hook's budget, one from the distant past
-  // would skip the terminal-first window the user asked for entirely. Anything
-  // outside a plausible range restarts the window from now.
-  const elapsed = ctx.now() - askedAt
-  const start = elapsed >= 0 && elapsed <= MAX_PLAUSIBLE_SILENCE_MS ? askedAt : ctx.now()
-  const deadline = start + graceSeconds * 1000
-
-  for (;;) {
-    if (ctx.config.require_idle.value) {
-      const idle = ctx.idleSeconds()
-      if (idle === null) return 'no-signal'
-      if (idle < threshold) return 'user-returned'
-    }
-    if (ctx.now() >= deadline) return 'absent'
-    await ctx.sleep(Math.min(GRACE_POLL_MS, Math.max(0, deadline - ctx.now())))
-  }
+async function awaitTerminalFirstWindow(
+  ctx: HookContext,
+  askedAt: number,
+  ceilingAt: number,
+): Promise<void> {
+  const graceSeconds = ctx.config.ask_grace_seconds.value
+  if (graceSeconds <= 0) return
+  const until = Math.min(Math.min(askedAt, ctx.now()) + graceSeconds * 1000, ceilingAt)
+  const remaining = until - ctx.now()
+  if (remaining > 0) await ctx.sleep(remaining)
 }
 
 export interface HookOutcome {
@@ -217,6 +279,61 @@ export interface HookOutcome {
   stdout?: string
   /** Diagnostics; harnesses surface hook stderr in the transcript. */
   notes: string[]
+  /** Structured lifecycle detail that belongs on hook.end without user text. */
+  log?: Record<string, unknown>
+}
+
+/** An accepted continuation ready for whichever host owns the last meter. */
+export interface ContinuationEvent {
+  context: string
+  answers: number
+  remaining: number
+  request_ids: string[]
+  journal_recorded_at: number
+}
+
+/**
+ * How much a route's own return proves about where the answer ended up.
+ *
+ * Acknowledgement belongs to the delivery, not to the harness envelope: routes
+ * end in different places, so no single field on a hook payload can speak for
+ * all of them. `stop_hook_active` is the harness confirming that a *blocking
+ * continuation* was admitted; it stays false for ever on a route that starts a
+ * brand-new turn instead of continuing this one, so a journal keyed to it alone
+ * never settles and every later turn-end redelivers the same answer.
+ *
+ * - `delivered` — the route completed a write to the harness itself (an inbox
+ *   socket, a cold resume). Delivery is not consumption: the write proves the
+ *   harness accepted the message, never that the model acted on it. But nothing
+ *   later will ever prove more, and redelivering an answer without end is
+ *   strictly worse than settling on the write, so the journal settles here.
+ * - `stdout` — the answer is this process's stdout, which the harness reads only
+ *   after this process exits. Nothing this process can write is proof, so the
+ *   journal waits for the successor Stop's `stop_hook_active`, and a crash
+ *   before stdout replays the answer instead of losing it.
+ * - `held` — the route handed nothing over; the journal replays the answer.
+ */
+export type DeliveryAcknowledgement = 'delivered' | 'stdout' | 'held'
+
+/** What a route returns: the hook's outcome plus what the attempt proved. */
+export interface DeliveryOutcome {
+  stdout?: string
+  notes?: string[]
+  log?: Record<string, unknown>
+  acknowledgement: DeliveryAcknowledgement
+}
+
+/** Host adapter injected into the waiter; no route is implemented by the waiter. */
+export interface EscalationDeliveryRoute {
+  kind: Exclude<DeliveryRoute, 'unsupported'>
+  deliver(event: ContinuationEvent): Promise<DeliveryOutcome>
+}
+
+export interface EscalationWaiterOptions {
+  sessionId: string
+  envelope: HookEnvelope
+  route: EscalationDeliveryRoute
+  processDeadlineAt?: number
 }
 
 function sessionStatePath(sessionId: string, env: NodeJS.ProcessEnv): string {
@@ -272,55 +389,6 @@ function updateSessionState(
   })
 }
 
-/**
- * Serialize a short read-modify-write without ever exposing partial JSON.
- * A crashed holder is recoverable after 30 seconds; releases compare their
- * random token under the same cooperating lock discipline before unlinking.
- */
-const FILE_LOCK_STALE_MS = 30_000
-const FILE_LOCK_WAIT_MS = 1_000
-const FILE_LOCK_POLL_MS = 5
-const lockSleep = new Int32Array(new SharedArrayBuffer(4))
-
-function withFileLock<T>(file: string, action: () => T): T {
-  mkdirSync(path.dirname(file), { recursive: true })
-  const token = randomBytes(12).toString('base64url')
-  const deadline = Date.now() + FILE_LOCK_WAIT_MS
-  for (;;) {
-    try {
-      const handle = openSync(file, 'wx', 0o600)
-      try {
-        writeFileSync(handle, `${JSON.stringify({ token, at: Date.now() })}\n`)
-      } finally {
-        closeSync(handle)
-      }
-      break
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') throw err
-      let stale = false
-      try {
-        const held = JSON.parse(readFileSync(file, 'utf8')) as { at?: unknown }
-        stale = typeof held.at !== 'number' || Date.now() - held.at >= FILE_LOCK_STALE_MS
-      } catch {
-        stale = true
-      }
-      if (stale) rmSync(file, { force: true })
-      else if (Date.now() >= deadline) throw new Error(`timed out waiting for state lock ${file}`)
-      else Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS)
-    }
-  }
-  try {
-    return action()
-  } finally {
-    try {
-      const held = JSON.parse(readFileSync(file, 'utf8')) as { token?: unknown }
-      if (held.token === token) rmSync(file, { force: true })
-    } catch {
-      // A replaced or externally removed lock is no longer ours to release.
-    }
-  }
-}
-
 /**
  * Session state a crashed harness left behind.
  *
@@ -384,10 +452,11 @@ export function pruneAbandonedSessions(
  * Exclusive create is atomic on POSIX, so exactly one process gets the claim
  * and the other steps aside. A short guard serializes stale replacement with
  * contenders and releases; random ownership tokens keep an old holder from
- * unlinking its replacement. A claim older than the hook budget is a crashed
- * process rather than a live one and is broken, avoiding permanent suppression.
+ * unlinking its replacement. A live PID owns the claim regardless of age; a
+ * known-dead PID is recoverable immediately. Only legacy/corrupt claims with
+ * no trustworthy PID fall back to an age limit.
  */
-const CLAIM_TTL_MS = STOP_BUDGET_SECONDS * 1000
+const CLAIM_TTL_MS = WAITER_CEILING_SECONDS * 1000
 const heldClaims = new Map<string, string>()
 
 export function claimQuestionPush(
@@ -412,9 +481,13 @@ export function claimQuestionPush(
     } catch {
       // Held. Break it only if whoever holds it cannot still be running.
       try {
-        const held = JSON.parse(readFileSync(file, 'utf8')) as { at?: unknown }
+        const held = JSON.parse(readFileSync(file, 'utf8')) as { at?: unknown; pid?: unknown }
         const age = typeof held.at === 'number' ? now - held.at : Number.POSITIVE_INFINITY
-        if (age >= 0 && age < CLAIM_TTL_MS) return false
+        if (typeof held.pid === 'number') {
+          if (processIsAlive(held.pid)) return false
+        } else if (age >= 0 && age < CLAIM_TTL_MS) {
+          return false
+        }
       } catch {
         // Unreadable or corrupt: treat as abandoned.
       }
@@ -436,6 +509,15 @@ export function claimQuestionPush(
   }
 }
 
+function processIsAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
 export function releaseQuestionPush(sessionId: string, env: NodeJS.ProcessEnv): void {
   const file = claimPath(sessionId, env)
   const token = heldClaims.get(file)
@@ -490,7 +572,11 @@ function claimPath(sessionId: string, env: NodeJS.ProcessEnv): string {
  */
 const MAX_STORED_QUESTION_CHARS = 2000
 
-/** Records which session is working in a directory, for `notifai ask`. */
+interface StoredProjectSessionPointer extends ProjectSessionPointer {
+  updatedAt: number
+}
+
+/** Records every live session working in a directory, for `notifai ask`. */
 export function writeProjectSession(
   cwd: string,
   env: NodeJS.ProcessEnv,
@@ -500,9 +586,21 @@ export function writeProjectSession(
 ): void {
   const file = projectSessionPointerPath(cwd, env)
   withFileLock(`${file}.lock`, () => {
+    const existing = readStoredProjectSessionPointers(file).filter(
+      (entry) => entry.sessionId !== sessionId && now - entry.updatedAt <= 24 * 3600 * 1000,
+    )
     atomicWriteFileSync(
       file,
-      `${JSON.stringify({ session_id: sessionId, updated_at: now, harness })}\n`,
+      `${JSON.stringify({
+        sessions: [
+          ...existing.map((entry) => ({
+            session_id: entry.sessionId,
+            updated_at: entry.updatedAt,
+            harness: entry.harness,
+          })),
+          { session_id: sessionId, updated_at: now, harness },
+        ],
+      })}\n`,
     )
   })
 }
@@ -512,6 +610,34 @@ export interface ProjectSessionPointer {
   harness: HookHarness
 }
 
+function readStoredProjectSessionPointers(file: string): StoredProjectSessionPointer[] {
+  if (!existsSync(file)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as { sessions?: unknown }
+    if (!Array.isArray(parsed.sessions)) return []
+    return parsed.sessions.flatMap((candidate): StoredProjectSessionPointer[] => {
+      if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) return []
+      const entry = candidate as {
+        session_id?: unknown
+        updated_at?: unknown
+        harness?: unknown
+      }
+      if (typeof entry.session_id !== 'string' || entry.session_id === '') return []
+      if (typeof entry.updated_at !== 'number') return []
+      if (!(HARNESSES as readonly unknown[]).includes(entry.harness)) return []
+      return [
+        {
+          sessionId: entry.session_id,
+          updatedAt: entry.updated_at,
+          harness: entry.harness as HookHarness,
+        },
+      ]
+    })
+  } catch {
+    return []
+  }
+}
+
 /**
  * Resolves the session working in `cwd`. Stale pointers are ignored rather than
  * trusted: an id left by a session that ended days ago would send the question
@@ -526,37 +652,71 @@ export function readProjectSession(
   return readProjectSessionPointer(cwd, env, now, maxAgeMs)?.sessionId ?? null
 }
 
+/** A live pointer keeps when it was last written, so callers can rank by it. */
+export interface LiveProjectSessionPointer extends ProjectSessionPointer {
+  updatedAt: number
+}
+
+/**
+ * Every session that has fired a hook in this directory recently, newest first.
+ *
+ * This is the only local record of which harness sessions are actually alive
+ * here, which makes it the tiebreaker when the environment alone cannot say
+ * which harness owns the current shell.
+ */
+export function readLiveProjectSessionPointers(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  now: number,
+  maxAgeMs = 24 * 3600 * 1000,
+): LiveProjectSessionPointer[] {
+  const file = projectSessionPointerPath(cwd, env)
+  return readStoredProjectSessionPointers(file)
+    .filter((entry) => now - entry.updatedAt <= maxAgeMs)
+    .filter((entry) => {
+      try {
+        // A pointer is routing evidence only while its session state still
+        // exists and parses. SessionEnd and explicit cleanup therefore
+        // invalidate it even when a crash prevented removal from this index.
+        const sessionFile = sessionStatePath(entry.sessionId, env)
+        if (!existsSync(sessionFile)) return false
+        const state: unknown = JSON.parse(readFileSync(sessionFile, 'utf8'))
+        return typeof state === 'object' && state !== null && !Array.isArray(state)
+      } catch {
+        return false
+      }
+    })
+    .sort((left, right) => right.updatedAt - left.updatedAt)
+    .map((entry) => ({
+      sessionId: entry.sessionId,
+      harness: entry.harness,
+      updatedAt: entry.updatedAt,
+    }))
+}
+
 export function readProjectSessionPointer(
   cwd: string,
   env: NodeJS.ProcessEnv,
   now: number,
   maxAgeMs = 24 * 3600 * 1000,
 ): ProjectSessionPointer | null {
-  const file = projectSessionPointerPath(cwd, env)
-  if (!existsSync(file)) return null
-  try {
-    const parsed = JSON.parse(readFileSync(file, 'utf8')) as {
-      session_id?: unknown
-      updated_at?: unknown
-      harness?: unknown
-    }
-    if (typeof parsed.session_id !== 'string' || parsed.session_id === '') return null
-    if (typeof parsed.updated_at !== 'number' || now - parsed.updated_at > maxAgeMs) return null
-    if (!(HOOK_HARNESSES as readonly unknown[]).includes(parsed.harness)) return null
-    // A pointer is routing evidence only while its session state still exists
-    // and parses. SessionEnd and explicit cleanup therefore invalidate it even
-    // when a crash prevented the pointer file itself from being removed.
-    const sessionFile = sessionStatePath(parsed.session_id, env)
-    if (!existsSync(sessionFile)) return null
-    const state: unknown = JSON.parse(readFileSync(sessionFile, 'utf8'))
-    if (typeof state !== 'object' || state === null || Array.isArray(state)) return null
-    return { sessionId: parsed.session_id, harness: parsed.harness as HookHarness }
-  } catch {
-    return null
-  }
+  const latest = readLiveProjectSessionPointers(cwd, env, now, maxAgeMs)[0]
+  return latest === undefined ? null : { sessionId: latest.sessionId, harness: latest.harness }
 }
 
-const HOOK_HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
+export function readMatchingProjectSessionPointer(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  now: number,
+  sessionId: string,
+  harness: HookHarness,
+  maxAgeMs = 24 * 3600 * 1000,
+): ProjectSessionPointer | null {
+  const match = readLiveProjectSessionPointers(cwd, env, now, maxAgeMs).find(
+    (entry) => entry.sessionId === sessionId && entry.harness === harness,
+  )
+  return match === undefined ? null : { sessionId: match.sessionId, harness: match.harness }
+}
 
 function clearMatchingProjectSession(
   cwd: string,
@@ -565,75 +725,31 @@ function clearMatchingProjectSession(
 ): void {
   const file = projectSessionPointerPath(cwd, env)
   withFileLock(`${file}.lock`, () => {
-    try {
-      const parsed = JSON.parse(readFileSync(file, 'utf8')) as { session_id?: unknown }
-      if (parsed.session_id === sessionId) rmSync(file, { force: true })
-    } catch {
-      // Missing/corrupt is already not a live pointer.
+    const remaining = readStoredProjectSessionPointers(file).filter(
+      (entry) => entry.sessionId !== sessionId,
+    )
+    if (remaining.length === 0) {
+      rmSync(file, { force: true })
+      return
     }
+    atomicWriteFileSync(
+      file,
+      `${JSON.stringify({
+        sessions: remaining.map((entry) => ({
+          session_id: entry.sessionId,
+          updated_at: entry.updatedAt,
+          harness: entry.harness,
+        })),
+      })}\n`,
+    )
   })
 }
 
-/**
- * Absent means the user is not at this machine's keyboard.
- *
- * OS idle time answers that directly, so where it exists it decides alone.
- * Silence since the user's last prompt is only ever a proxy for it, and a poor
- * one — it is wrong in both directions:
- *
- *   - Too long: it counts the agent's own turn, so a user watching a build was
- *     read as absent and had the question pushed at them.
- *   - Too short: a session that has just been spawned always has a fresh
- *     prompt, so its FIRST question could never escalate however long its
- *     owner had been gone. That is the "kick off some agents and
- *     walk away" case this feature mainly exists for, and requiring both
- *     signals to agree is what broke it.
- *
- * The proxy therefore survives only as the fallback for machines with no idle
- * source. There, never having seen a prompt is not evidence of absence — it is
- * a missing `UserPromptSubmit` hook — so it resolves to "present".
- *
- * Answering from a companion device does not make the user present; only touching this
- * machine does. Answering on a device is evidence of being away from it.
- *
- * All of which only matters if presence is being consulted at all. With
- * `require_idle` off the user has said their whereabouts are not a
- * precondition, so this stops guessing and answers yes.
- */
-export function isUserAway(
-  state: SessionState,
-  config: CliConfig,
-  now: number,
-  idleSeconds: number | null,
-): boolean {
-  if (!config.require_idle.value) return true
-  const threshold = config.away_after_seconds.value
-  if (idleSeconds !== null) return idleSeconds >= threshold
-  if (state.last_prompt_at === undefined) return false
-  const silence = now - state.last_prompt_at
-  // Both signs of a clock jump produce a wrong answer here, and the fallback
-  // path has no monotonic reference to check against: a forward jump (NTP
-  // correction, VM resume) hijacks a terminal whose user is sitting right
-  // there, and a backward one suppresses escalation for someone genuinely
-  // gone. Neither delta is evidence of anything, so it resolves the way every
-  // other absence of evidence does — present.
-  if (silence < 0 || silence > MAX_PLAUSIBLE_SILENCE_MS) return false
-  return silence >= threshold * 1000
-}
-
-/**
- * Beyond this, silence says more about the clock or an abandoned session file
- * than about the user. Matches the project pointer's staleness horizon.
- */
-const MAX_PLAUSIBLE_SILENCE_MS = 24 * 3600 * 1000
-
 export interface HookContext {
   client: ApiClient
   config: CliConfig
   env: NodeJS.ProcessEnv
   now: () => number
-  /** Seconds since the last keyboard/mouse event, or null if unknowable. */
-  idleSeconds: () => number | null
   /** Injected so tests advance a virtual clock instead of sleeping. */
   sleep: (milliseconds: number) => Promise<void>
   /** Bounded wait for the first reply; injected so tests do not sleep. */
@@ -641,21 +757,54 @@ export interface HookContext {
     requestId: string,
     timeoutSeconds: number,
   ) => Promise<{ replies: ReplyView[]; timedOut: boolean; degraded?: boolean }>
-  /** OpenCode cannot consume Stop stdout, so its adapter must never wait there. */
+  /** The active harness selects the native continuation output adapter. */
   harness?: HookHarness
+  /**
+   * The local record. A hook's decisions are invisible from everywhere else —
+   * its stderr belongs to the harness and its usual outcome is to do nothing —
+   * so this is the only account of why a question did or did not travel.
+   */
+  log?: Logger
 }
 
-export type HookHarness = 'claude-code' | 'codex' | 'cursor' | 'opencode'
-
-interface SubmittedQuestion {
-  requestId: string
-  collapseKey: string
-  /** The devices the question went to; retirement must not reach any other. */
-  devices: string[]
+/**
+ * Record one gate decision.
+ *
+ * `verdict` is what happened to the question and `reason` is the closed-set
+ * name of the rule that decided it, so an agent can ask "why was it held" with
+ * a filter rather than by matching on prose. The prose still exists — it is what
+ * the user sees in the terminal — but it is free to be rewritten, and a log a
+ * filter cannot rely on is a log nobody filters.
+ */
+export type GateReason =
+  | 'no-session'
+  | 'no-question'
+  | 'answered'
+  | 'already-asked'
+  | 'continuation-repeat'
+  | 'continuation-limit'
+  | 'delivery-limit'
+  | 'notifications-off'
+  | 'claimed-elsewhere'
+  | 'no-devices'
+  | 'proceeding'
+
+function gate(
+  ctx: HookContext,
+  verdict: 'held' | 'proceeding',
+  reason: GateReason,
+  data: Record<string, unknown> = {},
+): void {
+  ctx.log?.info('hook.gate', { verdict, reason, stage: 'queued', ...data })
 }
 
-/** Re-check local presence at this cadence while a pushed question is waiting. */
-const REPLY_PRESENCE_POLL_SECONDS = 5
+export type HookHarness = Harness
+
+/**
+ * One round of the waiter's reply poll. Short enough that several questions
+ * still share one wall clock, long enough not to hammer the server.
+ */
+const REPLY_POLL_SECONDS = 5
 
 /**
  * Push a question and block for the answer.
@@ -672,7 +821,7 @@ const REPLY_PRESENCE_POLL_SECONDS = 5
  * Put one registered question on the user's devices. Submission only — the
  * wait happens once, across every live question, in the caller.
  */
-async function submitQuestion(
+async function prepareQuestionSubmission(
   ctx: HookContext,
   options: {
     title: string
@@ -684,8 +833,10 @@ async function submitQuestion(
     session?: string | undefined
     /** How long the server keeps accepting an answer. */
     windowSeconds: number
+    /** Absolute owner deadline persisted before submit. */
+    ownerDeadlineAt: number
   },
-): Promise<SubmittedQuestion | { error: string }> {
+): Promise<PendingSubmissionIntent | { error: string }> {
   const collapseKey = `notifai-hook-${randomBytes(8).toString('base64url')}`
   // A draft carrying `reply` is rejected outright if it targets a device that
   // cannot answer, so resolve the healthy companion platforms explicitly.
@@ -708,63 +859,112 @@ async function submitQuestion(
   })
   if (!build.ok) return { error: build.error }
 
+  return {
+    request_id: `req_${randomBytes(18).toString('base64url')}`,
+    idempotency_key: `hook-${randomBytes(12).toString('base64url')}`,
+    collapse_key: collapseKey,
+    device_ids: answerable,
+    draft: build.draft,
+    owner_deadline_at: options.ownerDeadlineAt,
+  }
+}
+
+async function submitQuestion(
+  ctx: HookContext,
+  intent: PendingSubmissionIntent,
+): Promise<SubmissionReceipt> {
   const receipt = await ctx.client.submit(
-    { idempotency_key: `hook-${randomBytes(12).toString('base64url')}`, draft: build.draft },
+    {
+      request_id: intent.request_id,
+      idempotency_key: intent.idempotency_key,
+      draft: intent.draft,
+    },
     0,
   )
-  return { requestId: receipt.request_id, collapseKey, devices: answerable }
+  if (receipt.request_id !== intent.request_id) {
+    throw new Error(
+      `server replay returned ${receipt.request_id}, expected reserved ${intent.request_id}`,
+    )
+  }
+  return receipt
 }
 
 /**
- * One blocking wait across every live question. Each round polls all of them
- * concurrently, so several questions cost the same wall clock as one; the
- * first round that finds any reply returns everything found in that round, and
- * whatever was not answered stays registered.
+ * The waiter's wait: one bounded poll across every live question at once.
+ *
+ * Each round polls all of them concurrently, so several questions cost the
+ * same wall clock as one; the first round that finds any reply returns
+ * everything found in that round, and whatever was not answered stays
+ * registered. A question whose polling is permanently rejected drops out of
+ * the round rather than failing the whole wait.
  */
-async function waitForAnyReplyWhileAway(
+async function waitForAnyReply(
   ctx: HookContext,
   requestIds: string[],
   timeoutSeconds: number,
-): Promise<{ byRequest: Map<string, ReplyView[]>; degraded: boolean; userReturned: boolean }> {
+): Promise<{
+  byRequest: Map<string, ReplyView[]>
+  degraded: boolean
+  permanentFailures: Map<string, string>
+}> {
   const deadline = ctx.now() + timeoutSeconds * 1000
   let degraded = false
   let firstPoll = true
+  const permanentFailures = new Map<string, string>()
 
   for (;;) {
-    if (ctx.config.require_idle.value) {
-      const idle = ctx.idleSeconds()
-      if (idle !== null && idle < ctx.config.away_after_seconds.value) {
-        return { byRequest: new Map(), degraded, userReturned: true }
-      }
-    }
-
     const remainingMs = Math.max(0, deadline - ctx.now())
     if (!firstPoll && remainingMs === 0) {
-      return { byRequest: new Map(), degraded, userReturned: false }
+      return { byRequest: new Map(), degraded, permanentFailures }
     }
     firstPoll = false
-    const pollSeconds = Math.min(
-      REPLY_PRESENCE_POLL_SECONDS,
-      Math.max(0, Math.ceil(remainingMs / 1000)),
-    )
+    const pollSeconds = Math.min(REPLY_POLL_SECONDS, Math.max(0, Math.ceil(remainingMs / 1000)))
     const results = await Promise.all(
-      requestIds.map(async (requestId) => {
-        try {
-          return { requestId, ...(await ctx.waitForFirstReply(requestId, pollSeconds)) }
-        } catch {
-          return { requestId, replies: [] as ReplyView[], degraded: true }
-        }
-      }),
+      requestIds
+        .filter((requestId) => !permanentFailures.has(requestId))
+        .map(async (requestId) => {
+          try {
+            return { requestId, ...(await ctx.waitForFirstReply(requestId, pollSeconds)) }
+          } catch (err) {
+            if (isRetryableReplyPollError(err)) {
+              return { requestId, replies: [] as ReplyView[], degraded: true }
+            }
+            return {
+              requestId,
+              replies: [] as ReplyView[],
+              degraded: false,
+              permanentFailure: replyPollFailure(err),
+            }
+          }
+        }),
     )
     const byRequest = new Map<string, ReplyView[]>()
     for (const result of results) {
       degraded ||= result.degraded === true
+      if (result.permanentFailure !== undefined) {
+        permanentFailures.set(result.requestId, result.permanentFailure)
+      }
       if (result.replies.length > 0) byRequest.set(result.requestId, result.replies)
     }
-    if (byRequest.size > 0) return { byRequest, degraded, userReturned: false }
+    if (byRequest.size > 0 || permanentFailures.size === requestIds.length) {
+      return { byRequest, degraded, permanentFailures }
+    }
   }
 }
 
+/** A non-retryable replies fault, with enough server identity to act on it. */
+function replyPollFailure(err: unknown): string {
+  return err instanceof ApiCallError
+    ? `${err.code} (HTTP ${err.status}): ${err.message}`
+    : String(err)
+}
+
+function permanentReplyFailureNote(failures: Map<string, string>): string | null {
+  if (failures.size === 0) return null
+  const details = [...failures].map(([requestId, failure]) => `${requestId}: ${failure}`).join('; ')
+  return `reply polling stopped after a permanent server rejection (${details}); the affected question will be retired before its continuation owner exits`
+}
+
 /**
  * Healthy companion devices that implement replies. Both the iOS app and the
  * macOS app register reply categories and submit answers directly.
@@ -806,15 +1006,28 @@ function sessionLabel(ctx: HookContext, envelope: HookEnvelope): string | undefi
  */
 export type RetireDeps = Pick<HookContext, 'client' | 'config'>
 
-/** Best effort: a question that outlives its hook is a nuisance, not a failure. */
-async function closeQuietly(ctx: RetireDeps, requestId: string): Promise<void> {
+/**
+ * Close is a server-side serialization fence: a successful response contains
+ * every reply that committed before the window closed. `null` is deliberately
+ * different from an empty reply set — it means ownership could not be proven
+ * final and the local record must stay recoverable.
+ */
+async function finalizeReplies(
+  ctx: RetireDeps,
+  requestId: string,
+): Promise<ListRepliesResponse | null> {
   try {
-    await ctx.client.closeReplies(requestId)
+    return await ctx.client.closeReplies(requestId)
   } catch {
-    // The window expires on its own; nothing here is worth failing a hook for.
+    return null
   }
 }
 
+/** Best effort only for already-journaled retirement debt. */
+async function closeQuietly(ctx: RetireDeps, requestId: string): Promise<void> {
+  await finalizeReplies(ctx, requestId)
+}
+
 /**
  * Retire the question on every device it reached. A state change is not news
  * (D-B): the retirement rides as a background state sync — no alert, no
@@ -1078,7 +1291,15 @@ export async function drainOrphanRetirements(
 
 const LATE_STOP_POLL_SECONDS = 4
 const LATE_PROMPT_POLL_SECONDS = 3
-const MAX_CONTINUATION_COUNT = 3
+/**
+ * The one bound on answer deliveries, for every route.
+ *
+ * It caps two things that both used to be able to run away: how many times a
+ * single accepted answer may be handed to a route before the journal gives up
+ * on it, and how many answer-driven continuation generations one chain may
+ * produce.
+ */
+export const MAX_CONTINUATION_COUNT = 3
 
 interface PendingPoll {
   /** The answer to act on: the latest reply, because a later one corrects. */
@@ -1086,7 +1307,7 @@ interface PendingPoll {
   /** Every reply in arrival order, for free-text answers given in parts. */
   replies: ReplyView[]
   degraded: boolean
-  failed: boolean
+  permanentFailure: string | null
 }
 
 /** One bounded recovery poll for a question that outlived its original wait. */
@@ -1096,7 +1317,7 @@ async function pollPendingReply(
   timeoutSeconds: number,
 ): Promise<PendingPoll> {
   if (pending.request_id === undefined) {
-    return { reply: null, replies: [], degraded: false, failed: false }
+    return { reply: null, replies: [], degraded: false, permanentFailure: null }
   }
   try {
     const result = await ctx.waitForFirstReply(pending.request_id, timeoutSeconds)
@@ -1104,10 +1325,12 @@ async function pollPendingReply(
       reply: result.replies.at(-1) ?? null,
       replies: result.replies,
       degraded: result.degraded === true,
-      failed: false,
+      permanentFailure: null,
     }
-  } catch {
-    return { reply: null, replies: [], degraded: true, failed: true }
+  } catch (err) {
+    return isRetryableReplyPollError(err)
+      ? { reply: null, replies: [], degraded: true, permanentFailure: null }
+      : { reply: null, replies: [], degraded: false, permanentFailure: replyPollFailure(err) }
   }
 }
 
@@ -1118,6 +1341,49 @@ interface AnsweredPending {
   replies: ReplyView[]
 }
 
+interface FinalizedPending {
+  pending: PendingQuestion
+  response: ListRepliesResponse | null
+}
+
+/** Close several windows concurrently without confusing failure with silence. */
+async function finalizePendings(
+  ctx: HookContext,
+  pending: PendingQuestion[],
+): Promise<FinalizedPending[]> {
+  return Promise.all(
+    pending.map(async (entry) => ({
+      pending: entry,
+      response: await finalizeReplies(ctx, entry.request_id!),
+    })),
+  )
+}
+
+/** Convert a fenced final reply set into the exact answer handed to the model. */
+function finalizedAnswer(finalized: FinalizedPending): AnsweredPending | null {
+  const replies = finalized.response?.replies ?? []
+  const reply = replies.at(-1)
+  return reply === undefined ? null : { pending: finalized.pending, reply, replies }
+}
+
+/** Persist and surface one answer without letting the two representations drift. */
+function reportAnswer(
+  ctx: HookContext,
+  notes: string[],
+  answered: AnsweredPending,
+  late: boolean,
+): void {
+  ctx.log?.info('hook.answer', {
+    answered: true,
+    stage: 'queued',
+    ...(late ? { late: true } : {}),
+    request_id: answered.pending.request_id,
+    device: answered.reply.device_name,
+    text: answered.reply.text,
+  })
+  notes.push(`${late ? 'late ' : ''}answer from ${answered.reply.device_name}: ${answered.reply.text}`)
+}
+
 /**
  * One bounded recovery poll across every delivered question, concurrently —
  * N questions must not multiply the hook's latency budget by N.
@@ -1126,19 +1392,27 @@ async function pollPendingReplies(
   ctx: HookContext,
   live: PendingQuestion[],
   timeoutSeconds: number,
-): Promise<{ answered: AnsweredPending[]; troubled: boolean }> {
+): Promise<{
+  answered: AnsweredPending[]
+  transientTrouble: boolean
+  permanentFailures: Map<string, string>
+}> {
   const polls = await Promise.all(
     live.map((entry) => pollPendingReply(ctx, entry, timeoutSeconds)),
   )
   const answered: AnsweredPending[] = []
-  let troubled = false
+  let transientTrouble = false
+  const permanentFailures = new Map<string, string>()
   for (const [index, poll] of polls.entries()) {
     if (poll.reply !== null) {
       answered.push({ pending: live[index]!, reply: poll.reply, replies: poll.replies })
     }
-    if (poll.failed || poll.degraded) troubled = true
+    if (poll.degraded) transientTrouble = true
+    if (poll.permanentFailure !== null) {
+      permanentFailures.set(live[index]!.request_id!, poll.permanentFailure)
+    }
   }
-  return { answered, troubled }
+  return { answered, transientTrouble, permanentFailures }
 }
 
 /** The registered-question queue. Anything but the current shape reads as empty. */
@@ -1148,6 +1422,9 @@ function pendingList(state: SessionState): PendingQuestion[] {
 
 /** Registration identity — the convention every racing writer compares by. */
 function isSamePending(a: PendingQuestion, b: PendingQuestion): boolean {
+  if (a.question_id !== undefined || b.question_id !== undefined) {
+    return a.question_id !== undefined && a.question_id === b.question_id
+  }
   return a.question === b.question && a.asked_at === b.asked_at
 }
 
@@ -1167,18 +1444,28 @@ function pendingHasChoices(pending: PendingQuestion): boolean {
  * it. Free-text answers can arrive in parts, and every part reaches the
  * agent in the order it was written, so it can tell expansion from
  * correction itself.
+ *
+ * The continuation repeats only identity the agent actually registered and
+ * the answer the server accepted. It never invents trust, urgency, permission,
+ * or approval claims for the transport to assert.
  */
-function answerContext(replies: ReplyView[], hadChoices: boolean): string {
+function answerContext(answered: AnsweredPending): string {
+  const { pending, replies } = answered
   const latest = replies.at(-1)
   if (latest === undefined) return 'Notifai — no answer was recorded.'
-  if (replies.length === 1 || hadChoices) {
-    return `Notifai — the user answered from ${latest.device_name}: "${latest.text}". Continue with that answer.`
+  const answeredQuestionIds = [...new Set(latest.answers.map((answer) => answer.question_id))]
+  const identity =
+    answeredQuestionIds.length === 0
+      ? ''
+      : `question_id${answeredQuestionIds.length === 1 ? '' : 's'} ${answeredQuestionIds.join(', ')}, `
+  const question = `question ${JSON.stringify(pending.question)}`
+  if (replies.length === 1 || pendingHasChoices(pending)) {
+    return `Notifai — ${identity}${question}; the user answered ${JSON.stringify(latest.text)}.`
   }
-  const parts = replies.map((reply) => `"${reply.text}"`).join(', then ')
+  const parts = replies.map((reply) => JSON.stringify(reply.text)).join(', then ')
   return (
-    `Notifai — the user answered from ${latest.device_name} in ${replies.length} parts, ` +
-    `in the order written: ${parts}. Later parts extend or correct earlier ones. ` +
-    'Continue with that answer.'
+    `Notifai — ${identity}${question}; the user answered in ${replies.length} parts, ` +
+    `in the order written: ${parts}. Later parts extend or correct earlier ones.`
   )
 }
 
@@ -1194,47 +1481,85 @@ function answersContext(answered: AnsweredPending[], remaining: number): string
       ? ` (${remaining} more registered question${remaining === 1 ? ' is' : 's are'} still waiting for an answer.)`
       : ''
   if (answered.length === 1) {
-    const only = answered[0]!
-    return answerContext(only.replies, pendingHasChoices(only.pending)) + tail
+    return answerContext(answered[0]!) + tail
   }
   const lines = answered.map(({ pending, replies }) => {
     const latest = replies.at(-1)!
     const answer =
       replies.length === 1 || pendingHasChoices(pending)
-        ? `"${latest.text}"`
-        : `${replies.map((reply) => `"${reply.text}"`).join(', then ')} (parts in the order written; later parts extend or correct earlier ones)`
-    return `- "${pending.question}" → ${answer} (from ${latest.device_name})`
+        ? JSON.stringify(latest.text)
+        : `${replies.map((reply) => JSON.stringify(reply.text)).join(', then ')} (parts in the order written; later parts extend or correct earlier ones)`
+    const ids = [...new Set(latest.answers.map((entry) => entry.question_id))]
+    const identity = ids.length === 0 ? '' : `question_id${ids.length === 1 ? '' : 's'} ${ids.join(', ')}: `
+    return `- ${identity}${JSON.stringify(pending.question)} → ${answer}`
   })
-  return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}\nContinue with these answers.${tail}`
+  return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}${tail}`
 }
 
-function userPromptAnswerOutput(context: string): string {
+function stopAnswerOutput(context: string): string {
   return JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: 'UserPromptSubmit',
-      additionalContext: context,
-    },
+    decision: 'block',
+    reason: context,
   })
 }
 
-function stopAnswerOutput(context: string): string {
-  return JSON.stringify({ decision: 'block', reason: context })
-}
-
 /**
  * Close, truthfully retire, and forget every answered pending question in one
  * state write, without dropping any other retirement debt or any question
  * still waiting. Stop answers also open one bounded continuation generation;
  * UserPromptSubmit answers ride the user's new turn.
  */
-async function finishAnsweredPendings(
+function stageAcceptedAnswers(
   ctx: HookContext,
-  envelope: HookEnvelope,
   sessionId: string,
   answered: AnsweredPending[],
-  continuation: boolean,
-): Promise<void> {
-  const retirements = answered
+  remaining: number,
+): AcceptedAnswerDelivery {
+  const accepted: AcceptedAnswerDelivery = {
+    answers: answered,
+    remaining,
+    recorded_at: ctx.now(),
+  }
+  updateSessionState(sessionId, ctx.env, (current) => {
+    const pendingRemaining = pendingList(current).filter(
+      (entry) => !answered.some(({ pending }) => isSamePending(entry, pending)),
+    )
+    const next: SessionState = {
+      ...current,
+      accepted,
+    }
+    if (pendingRemaining.length > 0) next.pending = pendingRemaining
+    else delete next.pending
+    return next
+  })
+  return accepted
+}
+
+/** Amend the live accepted record in place, without resurrecting a settled one. */
+function amendAcceptedAnswers(
+  ctx: HookContext,
+  sessionId: string,
+  amend: (accepted: AcceptedAnswerDelivery) => AcceptedAnswerDelivery,
+): void {
+  updateSessionState(sessionId, ctx.env, (current) =>
+    current.accepted === undefined ? current : { ...current, accepted: amend(current.accepted) },
+  )
+}
+
+/**
+ * Retire the answered questions and close the journal.
+ *
+ * Called once an answer's delivery is acknowledged — by the route's own write,
+ * or by the successor Stop of a blocking continuation. The continuation counter
+ * grows with each settled generation, so the cap that bounds chained
+ * answer-to-question loops is a real count rather than a constant 1.
+ */
+function settleAcceptedAnswers(
+  ctx: HookContext,
+  sessionId: string,
+  accepted: AcceptedAnswerDelivery,
+): void {
+  const retirements = accepted.answers
     .map(({ pending }) => retiringQuestion(pending, 'answered'))
     .filter((entry): entry is RetiringQuestion => entry !== null)
   updateSessionState(sessionId, ctx.env, (current) => {
@@ -1244,24 +1569,44 @@ async function finishAnsweredPendings(
       if (existing < 0) retiring.push(retirement)
       else retiring[existing] = retirement
     }
-    const remaining = pendingList(current).filter(
-      (entry) => !answered.some(({ pending }) => isSamePending(entry, pending)),
-    )
     const next: SessionState = { ...current, retiring }
-    if (remaining.length > 0) next.pending = remaining
-    else delete next.pending
-    if (continuation) {
-      next.continuation = {
-        answered_at: ctx.now(),
-        count:
-          (envelope.stop_hook_active === true ? current.continuation?.count ?? 0 : 0) + 1,
+    delete next.accepted
+    next.continuation = {
+      answered_at: accepted.recorded_at,
+      count: (current.continuation?.count ?? 0) + 1,
+    }
+    return next
+  })
+}
+
+async function retirePendings(
+  ctx: HookContext,
+  envelope: HookEnvelope,
+  sessionId: string,
+  entries: PendingQuestion[],
+  state: LifecycleEndState,
+): Promise<void> {
+  updateSessionState(sessionId, ctx.env, (current) => {
+    const retiring = [...(current.retiring ?? [])]
+    for (const entry of entries) {
+      const retirement = retiringQuestion(entry, state)
+      if (retirement !== null && !retiring.some((item) => item.request_id === retirement.request_id)) {
+        retiring.push(retirement)
       }
-    } else {
-      next.last_prompt_at = ctx.now()
     }
+    const pending = pendingList(current).filter(
+      (candidate) => !entries.some((entry) => isSamePending(candidate, entry)),
+    )
+    const next: SessionState = { ...current }
+    if (pending.length > 0) next.pending = pending
+    else delete next.pending
+    if (retiring.length > 0) next.retiring = retiring
+    else delete next.retiring
     return next
   })
-  await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))
+  // Network retirement is deliberately deferred to a later no-question hook.
+  // The state write above is the durable operation; blocking here creates a
+  // crash window before an answer can reach harness stdout.
 }
 
 // ---------------------------------------------------------------------------
@@ -1283,27 +1628,67 @@ export async function handleUserPromptSubmit(
   if (!sessionId) return { notes }
 
   const state = readSessionState(sessionId, ctx.env)
+  if (state.accepted !== undefined) {
+    updateSessionState(sessionId, ctx.env, (current) => ({
+      ...current,
+      last_prompt_at: ctx.now(),
+    }))
+    if (envelope.cwd !== undefined && ctx.harness !== undefined) {
+      writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness)
+    }
+    notes.push(
+      state.accepted.delivered_at === undefined
+        ? 'a device answer is safely journaled; the next Stop will deliver it'
+        : 'a device answer has already been delivered; the next Stop will close it out',
+    )
+    return { notes }
+  }
   const live = pendingList(state).filter((entry) => entry.request_id !== undefined)
   let lateAnswers: AnsweredPending[] = []
   if (live.length > 0) {
-    const { answered, troubled } = await pollPendingReplies(ctx, live, LATE_PROMPT_POLL_SECONDS)
-    lateAnswers = answered
-    if (answered.length > 0) {
-      await finishAnsweredPendings(ctx, envelope, sessionId, answered, false)
-      for (const { reply } of answered) {
-        notes.push(`late answer from ${reply.device_name}: ${reply.text}`)
+    const { answered, transientTrouble, permanentFailures } = await pollPendingReplies(
+      ctx,
+      live,
+      LATE_PROMPT_POLL_SECONDS,
+    )
+    const finalized = await finalizePendings(
+      ctx,
+      answered.map((entry) => entry.pending),
+    )
+    lateAnswers = answered.map((entry) => {
+      const response = finalized.find((candidate) =>
+        isSamePending(candidate.pending, entry.pending),
+      )?.response
+      const replies = response?.replies.length ? response.replies : entry.replies
+      if (response === null) {
+        notes.push(
+          `could not confirm the close fence for ${entry.pending.request_id}; preserving the durable answer already observed`,
+        )
       }
+      return { ...entry, replies, reply: replies.at(-1)! }
+    })
+    if (answered.length > 0) {
+      stageAcceptedAnswers(
+        ctx,
+        sessionId,
+        lateAnswers,
+        0,
+      )
+      for (const answer of lateAnswers) reportAnswer(ctx, notes, answer, true)
     }
-    if (troubled) {
+    if (transientTrouble) {
       notes.push('could not check every pending question for a late answer before the prompt')
     }
+    const permanentFailure = permanentReplyFailureNote(permanentFailures)
+    if (permanentFailure !== null) notes.push(permanentFailure)
   }
   // Park before dropping `pending`. If the process dies between these writes,
   // the next hook sees both copies and dedupes them; the old order could die in
   // the gap after erasing the only request/collapse/device identifiers.
   updateSessionState(sessionId, ctx.env, (current) => {
     const retiring = [...(current.retiring ?? [])]
-    for (const entry of pendingList(current)) {
+    const unasked = pendingList(current).filter((entry) => entry.request_id === undefined)
+    for (const entry of pendingList(current).filter((entry) => entry.request_id !== undefined)) {
       const retirement = retiringQuestion(entry, 'answered_elsewhere')
       if (
         retirement !== null &&
@@ -1312,7 +1697,21 @@ export async function handleUserPromptSubmit(
         retiring.push(retirement)
       }
     }
-    return { last_prompt_at: ctx.now(), ...(retiring.length > 0 ? { retiring } : {}) }
+    return {
+      last_prompt_at: ctx.now(),
+      ...(current.last_stop_at === undefined ? {} : { last_stop_at: current.last_stop_at }),
+      ...(unasked.length > 0 ? { pending: unasked } : {}),
+      ...(retiring.length > 0 ? { retiring } : {}),
+      ...(current.accepted === undefined ? {} : { accepted: current.accepted }),
+      // The user typed, so whatever chain of answer-driven continuations was
+      // running, a human has taken the turn and the consecutive count starts
+      // over. Only a real prompt reaches here: the journal branch above returns
+      // first, and a wake route's injected message always arrives while its own
+      // answer is still journaled, so it can never pass for the user's presence.
+      ...(current.continuation === undefined
+        ? {}
+        : { continuation: { ...current.continuation, count: 0 } }),
+    }
   })
   // The bridge that lets a plain `notifai ask` find the hook's canonical
   // session: an agent shell command gets no hook payload, and not every
@@ -1321,17 +1720,19 @@ export async function handleUserPromptSubmit(
     writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness)
   }
 
+  if (lateAnswers.length > 0) {
+    // UserPromptSubmit has no later hook field proving its stdout reached the
+    // model. Keep the journal and let the next Stop use its acknowledged
+    // continuation channel instead of recreating the crash-before-stdout gap.
+    notes.push('the late device answer will continue the agent at this turn’s Stop')
+    return { notes }
+  }
   const retired = await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))
   const orphaned = await drainOrphanRetirements(ctx, ctx.env, ctx.now())
   const swept = [...retired, ...orphaned]
   if (swept.length > 0) {
     notes.push(`retired question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`)
   }
-  if (lateAnswers.length > 0) {
-    // Whatever the user did not answer was just retired above — they are at
-    // the keyboard now, so nothing is "still waiting" from their side.
-    return { stdout: userPromptAnswerOutput(answersContext(lateAnswers, 0)), notes }
-  }
   return { notes }
 }
 
@@ -1339,66 +1740,312 @@ export async function handleUserPromptSubmit(
 // Stop — the turn ended; escalate a registered question
 // ---------------------------------------------------------------------------
 
-/**
- * How long an escalated question keeps accepting an answer after the turn
- * ended. Long enough to survive a walk away from the desk, short enough that a
- * forgotten question does not resurface days later as a live prompt.
- */
-const QUESTION_WINDOW_SECONDS = 3600
-
 /**
  * Only engages for a question the agent explicitly registered with
  * `notifai ask`. Guessing from the last assistant message was the alternative
  * and it is not worth it: a false positive here hijacks the terminal.
  */
-export async function handleStop(ctx: HookContext, envelope: HookEnvelope): Promise<HookOutcome> {
-  const notes: string[] = []
+export async function handleStop(
+  ctx: HookContext,
+  envelope: HookEnvelope,
+  processDeadlineAt = ctx.now() + WAITER_CEILING_SECONDS * 1000,
+  route: EscalationDeliveryRoute = hookContinuationRoute(),
+): Promise<HookOutcome> {
   const sessionId = envelope.session_id
-  if (!sessionId) return { notes }
+  if (!sessionId) {
+    gate(ctx, 'held', 'no-session', { stage: 'queued' })
+    return { notes: [] }
+  }
+  return runEscalationWaiter(ctx, {
+    sessionId,
+    envelope,
+    route,
+    processDeadlineAt,
+  })
+}
 
-  // Anything retired since the last hook is still live on the devices. This
-  // runs before every early return below, including the nagging guard: a queued
-  // retirement has nothing to do with whether *this* turn has a question to
-  // escalate, and the turn that supersedes a question is very often the one
-  // continuing from the previous answer.
-  const swept = [
-    ...(await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))),
-    ...(await drainOrphanRetirements(ctx, ctx.env, ctx.now())),
-  ]
-  if (swept.length > 0) {
-    notes.push(`retired superseded question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`)
+/**
+ * Own one registered question pipeline from its terminal-first timer through
+ * its final delivery or retirement. Hosts differ only in the injected route.
+ */
+export async function runEscalationWaiter(
+  ctx: HookContext,
+  options: EscalationWaiterOptions,
+): Promise<HookOutcome> {
+  const notes: string[] = []
+  const { sessionId, envelope } = options
+  const hardDeadlineAt =
+    options.processDeadlineAt ?? ctx.now() + WAITER_CEILING_SECONDS * 1000
+
+  // This event marker is diagnostic evidence in its own right. Record it
+  // before every early return so doctor can distinguish a working Stop route
+  // from the prompt-only state that previously looked healthy.
+  updateSessionState(sessionId, ctx.env, (current) => ({
+    ...current,
+    last_stop_at: ctx.now(),
+  }))
+
+  // The waiter, not its host, owns this lease. It spans grace, submission,
+  // polling, close fencing, route delivery, and every retirement path.
+  // Real clock, deliberately, not `ctx.now` — the claim answers whether
+  // another process is alive right now, which an injected clock cannot know.
+  if (!claimQuestionPush(sessionId, ctx.env)) {
+    gate(ctx, 'held', 'claimed-elsewhere', { stage: 'queued' })
+    notes.push('another hook is already handling this question')
+    return { notes }
   }
+  let settledAnswerThisPass = false
+  try {
+    let state = readSessionState(sessionId, ctx.env)
+    if (state.accepted !== undefined) {
+      const accepted = state.accepted
+      // Acknowledgement is per route, because routes end in different places.
+      //
+      // A blocking continuation ends at this process's stdout, which the
+      // harness reads only after the process exits: the recursive Stop's
+      // `stop_hook_active` is the acknowledgement, and persisting a separate
+      // "offered" bit before stdout would recreate the crash gap this journal
+      // exists to close. An out-of-band route ends at a write this process made
+      // itself and recorded here. A socket write is not proof the model acted
+      // on the answer — delivery is not consumption — but nothing later can
+      // prove more, and an answer redelivered without end is strictly worse
+      // than one settled on delivery. So a recorded delivery settles.
+      const deliveryProven =
+        accepted.delivered_at !== undefined || envelope.stop_hook_active === true
+      if (!deliveryProven) {
+        for (const answer of accepted.answers) reportAnswer(ctx, notes, answer, true)
+        return await deliverAcceptedAnswers(ctx, sessionId, options.route, accepted, notes)
+      }
+      settleAcceptedAnswers(ctx, sessionId, accepted)
+      settledAnswerThisPass = true
+      state = readSessionState(sessionId, ctx.env)
+    }
 
-  const state = readSessionState(sessionId, ctx.env)
-  const pending = pendingList(state)
-  if (pending.length === 0) return { notes }
+    const pending = pendingList(state)
+    if (pending.length === 0) {
+      const swept = [
+        ...(await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))),
+        ...(await drainOrphanRetirements(ctx, ctx.env, ctx.now())),
+      ]
+      if (swept.length > 0) {
+        notes.push(`retired question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`)
+      }
+      gate(ctx, 'held', 'no-question', { stage: 'queued' })
+      return { notes }
+    }
+
+    return await handleClaimedStop(
+      ctx,
+      envelope,
+      sessionId,
+      state,
+      pending,
+      notes,
+      hardDeadlineAt,
+      options.route,
+      // Every route's successor turn-end, named the same way: the harness flag
+      // for a blocking continuation, and the settle above for a route that woke
+      // a brand-new turn out of band.
+      envelope.stop_hook_active === true || settledAnswerThisPass,
+    )
+  } finally {
+    releaseQuestionPush(sessionId, ctx.env)
+  }
+}
+
+/**
+ * The blocking Stop hook's own last meter: the answer becomes this process's
+ * stdout, and the harness admits it as a new user turn. Exported because a
+ * host adapter that has other routes still falls back to this one.
+ */
+export function hookContinuationRoute(): EscalationDeliveryRoute {
+  return {
+    kind: 'hook-continuation',
+    deliver: async (event) => ({
+      stdout: stopAnswerOutput(event.context),
+      notes: [],
+      // The harness reads this stdout after the process exits, so only the
+      // successor Stop can acknowledge it.
+      acknowledgement: 'stdout',
+    }),
+  }
+}
+
+/**
+ * Hand one accepted answer to a route and record what the attempt proved.
+ *
+ * Every delivery on every route passes through here, which is what makes the
+ * cap below a backstop rather than a suggestion. A guard only one route
+ * consults is not a backstop: that is how a single answer once reached a
+ * session 250 times.
+ */
+async function deliverAcceptedAnswers(
+  ctx: HookContext,
+  sessionId: string,
+  route: EscalationDeliveryRoute,
+  accepted: AcceptedAnswerDelivery,
+  notes: string[],
+): Promise<HookOutcome> {
+  const { answers: answered, remaining } = accepted
+  const requestIds = summarizeRequestIds(answered.map((entry) => entry.pending)).ids
+  const attempt = (accepted.delivery_attempts ?? 0) + 1
+  if (attempt > MAX_CONTINUATION_COUNT) {
+    gate(ctx, 'held', 'delivery-limit', {
+      route: route.kind,
+      attempts: accepted.delivery_attempts ?? 0,
+      limit: MAX_CONTINUATION_COUNT,
+      request_ids: requestIds,
+    })
+    // Settle rather than journal for ever. The answer has been offered as often
+    // as any working route could need, it is already in the notes of each of
+    // those turns, and the questions it answered still deserve retirement.
+    settleAcceptedAnswers(ctx, sessionId, accepted)
+    notes.push(
+      `the user's answer reached the ${route.kind} route ${MAX_CONTINUATION_COUNT} times without being acknowledged; not delivering it again`,
+    )
+    return { notes }
+  }
+  // Count the attempt before making it: an attempt that dies mid-delivery still
+  // happened, and a counter written afterwards could be evaded by crashing.
+  amendAcceptedAnswers(ctx, sessionId, (current) => ({
+    ...current,
+    delivery_attempts: attempt,
+  }))
+  ctx.log?.info('hook.gate', {
+    verdict: 'proceeding',
+    reason: 'answered',
+    stage: 'routed',
+    route: route.kind,
+    answers: answered.length,
+    request_ids: requestIds,
+    journal_recorded_at: accepted.recorded_at,
+    delivery_attempt: attempt,
+  })
+  const delivered = await route.deliver({
+    context: answersContext(answered, remaining),
+    answers: answered.length,
+    remaining,
+    request_ids: requestIds,
+    journal_recorded_at: accepted.recorded_at,
+  })
+  const deliveredRoute =
+    typeof delivered.log?.['route'] === 'string' ? delivered.log['route'] : route.kind
+  const deliveredStage =
+    typeof delivered.log?.['stage'] === 'string' ? delivered.log['stage'] : 'delivered'
+  if (delivered.acknowledgement === 'delivered') {
+    amendAcceptedAnswers(ctx, sessionId, (current) => ({
+      ...current,
+      delivered_at: ctx.now(),
+      delivered_route: deliveredRoute,
+    }))
+  }
+  ctx.log?.info('hook.answer', {
+    answered: true,
+    stage: deliveredStage,
+    route: deliveredRoute,
+    acknowledgement: delivered.acknowledgement,
+    delivery_attempt: attempt,
+    request_ids: requestIds,
+    answers: answered.length,
+    journal_recorded_at: accepted.recorded_at,
+    ...(delivered.log?.['reason'] === undefined ? {} : { reason: delivered.log['reason'] }),
+  })
+  const outcome: HookOutcome = { notes: [...notes, ...(delivered.notes ?? [])] }
+  if (delivered.stdout !== undefined) outcome.stdout = delivered.stdout
+  if (delivered.log !== undefined) outcome.log = delivered.log
+  return outcome
+}
+
+/** The complete per-session Stop decision, after this process owns the claim. */
+async function handleClaimedStop(
+  ctx: HookContext,
+  envelope: HookEnvelope,
+  sessionId: string,
+  state: SessionState,
+  pending: PendingQuestion[],
+  notes: string[],
+  hardDeadlineAt: number,
+  route: EscalationDeliveryRoute,
+  continuingFromAnswer: boolean,
+): Promise<HookOutcome> {
   const live = pending.filter((entry) => entry.request_id !== undefined)
   const unasked = pending.filter((entry) => entry.request_id === undefined)
+  let liveToEscalate = live
+
+  if (
+    ctx.harness !== undefined &&
+    HARNESS_CAPABILITIES[ctx.harness].stopContinuation === 'unsupported'
+  ) {
+    for (const entry of live) await closeQuietly(ctx, entry.request_id!)
+    await retirePendings(ctx, envelope, sessionId, pending, 'expired')
+    gate(ctx, 'held', 'no-question')
+    notes.push(`${HARNESS_CAPABILITIES[ctx.harness].deliveryContract}; use a blocking \`notifai send --reply\` question`)
+    return { notes }
+  }
 
   if (live.length > 0) {
-    const { answered, troubled } = await pollPendingReplies(ctx, live, LATE_STOP_POLL_SECONDS)
+    const { answered, permanentFailures } = await pollPendingReplies(
+      ctx,
+      live,
+      LATE_STOP_POLL_SECONDS,
+    )
+    const permanentFailure = permanentReplyFailureNote(permanentFailures)
+    if (permanentFailure !== null) notes.push(permanentFailure)
+    const permanentlyRejected = live.filter((entry) =>
+      permanentFailures.has(entry.request_id!),
+    )
+    await Promise.all(permanentlyRejected.map((entry) => closeQuietly(ctx, entry.request_id!)))
+    if (permanentlyRejected.length > 0) {
+      await retirePendings(ctx, envelope, sessionId, permanentlyRejected, 'expired')
+    }
     if (answered.length > 0) {
-      await finishAnsweredPendings(ctx, envelope, sessionId, answered, true)
-      for (const { reply } of answered) {
-        notes.push(`late answer from ${reply.device_name}: ${reply.text}`)
-      }
+      const finalized = await finalizePendings(
+        ctx,
+        answered.map((entry) => entry.pending),
+      )
+      const authoritative = answered.map((entry) => {
+        const response = finalized.find((candidate) =>
+          isSamePending(candidate.pending, entry.pending),
+        )?.response
+        const replies = response?.replies.length ? response.replies : entry.replies
+        if (response === null) {
+          notes.push(
+            `could not confirm the close fence for ${entry.pending.request_id}; delivering the durable answer already observed`,
+          )
+        }
+        return { ...entry, replies, reply: replies.at(-1)! }
+      })
+      const accepted = stageAcceptedAnswers(
+        ctx,
+        sessionId,
+        authoritative,
+        pending.length - authoritative.length - permanentlyRejected.length,
+      )
+      for (const answer of authoritative) reportAnswer(ctx, notes, answer, true)
       // Anything still unasked rides the next Stop: the agent is being resumed
       // with answers right now, and may not even need the rest afterwards.
-      return {
-        stdout: stopAnswerOutput(answersContext(answered, pending.length - answered.length)),
-        notes,
-      }
+      return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes)
     }
+    const recoverableLive = live.filter(
+      (entry) => !permanentFailures.has(entry.request_id!),
+    )
+    liveToEscalate = recoverableLive
     if (unasked.length === 0) {
-      // Already live on the user's devices from an earlier Stop; asking twice
-      // for one question is the nagging failure this feature exists to avoid.
-      const ids = live.map((entry) => entry.request_id).join(', ')
-      notes.push(
-        troubled
-          ? `already asked (${ids}); could not check whether ${live.length === 1 ? 'its answer' : 'their answers'} arrived`
-          : `already asked (${ids}); waiting for ${live.length === 1 ? 'that answer' : 'those answers'}`,
+      if (recoverableLive.length === 0) return { notes }
+      // A previous answer may have resumed the model while independent
+      // questions remain. The next Stop is their successor owner: keep waiting
+      // to the original absolute deadline instead of polling for four seconds
+      // and abandoning them.
+      return await escalate(
+        ctx,
+        envelope,
+        sessionId,
+        [],
+        recoverableLive,
+        notes,
+        hardDeadlineAt,
+        route,
       )
-      return { notes }
     }
     // Questions registered after the earlier push still owe the user their
     // notification; fall through and escalate just those.
@@ -1415,36 +2062,54 @@ export async function handleStop(ctx: HookContext, envelope: HookEnvelope): Prom
         (entry) => entry.asked_at !== undefined && entry.asked_at > continuation.answered_at,
       )
     if (!isNew) {
+      gate(ctx, 'held', 'continuation-repeat')
       notes.push('already continuing from an answer; not asking again this turn')
       return { notes }
     }
-    if (continuation.count >= MAX_CONTINUATION_COUNT) {
-      notes.push(
-        `answer continuation limit (${MAX_CONTINUATION_COUNT}) reached; leaving the question in the terminal`,
-      )
-      return { notes }
-    }
   }
-  if (!ctx.config.ask_notifications.value) return { notes }
-  if (!isUserAway(state, ctx.config, ctx.now(), ctx.idleSeconds())) {
-    notes.push('you are at the keyboard; leaving the question in the terminal')
+  // The cap is deliberately not keyed to `stop_hook_active`. That flag names one
+  // route's continuation; a route that wakes a brand-new turn never sets it, and
+  // a limit only one route consults bounds only that route. `continuingFromAnswer`
+  // is the same event named for every route, so the chain of answer → follow-up
+  // question → answer is bounded whatever delivered it.
+  if (
+    continuingFromAnswer &&
+    state.continuation !== undefined &&
+    state.continuation.count >= MAX_CONTINUATION_COUNT
+  ) {
+    gate(ctx, 'held', 'continuation-limit', {
+      count: state.continuation.count,
+      limit: MAX_CONTINUATION_COUNT,
+      route: route.kind,
+    })
+    notes.push(
+      `answer continuation limit (${MAX_CONTINUATION_COUNT}) reached; leaving the question in the terminal`,
+    )
     return { notes }
   }
-
-  // Claim before the grace window, not after: two racing hooks would otherwise
-  // both wait, both find the user still absent, and both push.
-  // Real clock, deliberately, not `ctx.now` — the claim answers "is another
-  // process alive right now", which the injectable clock cannot speak to. It
-  // is also the only clock the *other* process shares.
-  if (!claimQuestionPush(sessionId, ctx.env)) {
-    notes.push('another hook is already handling this question')
+  // Silent to the user by design — they switched routing off, so saying so on
+  // every turn would be nagging about their own setting. That silence is also
+  // why it belongs in the log: from outside, "ask_notifications = false" and "a
+  // bug ate my question" look exactly the same.
+  if (!ctx.config.ask_notifications.value) {
+    gate(ctx, 'held', 'notifications-off', { source: ctx.config.ask_notifications.source })
     return { notes }
   }
-  try {
-    return await escalate(ctx, envelope, sessionId, unasked, live, notes)
-  } finally {
-    releaseQuestionPush(sessionId, ctx.env)
-  }
+  gate(ctx, 'proceeding', 'proceeding', {
+    unasked: unasked.length,
+    already_live: liveToEscalate.length,
+    grace_seconds: ctx.config.ask_grace_seconds.value,
+  })
+  return await escalate(
+    ctx,
+    envelope,
+    sessionId,
+    unasked,
+    liveToEscalate,
+    notes,
+    hardDeadlineAt,
+    route,
+  )
 }
 
 /** The escalation itself, split out so the claim is released on every path. */
@@ -1455,137 +2120,329 @@ async function escalate(
   unasked: PendingQuestion[],
   alreadyLive: PendingQuestion[],
   notes: string[],
+  hardDeadlineAt: number,
+  route: EscalationDeliveryRoute,
 ): Promise<HookOutcome> {
-  // Away right now, but the questions still owe the user their terminal-first
-  // window before anything reaches their devices — measured from the oldest
-  // registration, because that is the question that has waited longest.
-  const oldest = Math.min(...unasked.map((entry) => entry.asked_at ?? ctx.now()))
-  const grace = await awaitGrace(ctx, oldest)
-  if (grace === 'user-returned') {
-    notes.push('you came back before the wait elapsed; leaving the questions in the terminal')
-    return { notes }
-  }
-  if (grace === 'no-signal') {
-    notes.push('no idle signal on this machine; asking now rather than holding the terminal')
+  // The questions still owe the user their terminal-first window before
+  // anything reaches their devices — measured from the oldest registration,
+  // because that is the question that has waited longest.
+  const startedAt = ctx.now()
+  const existingDeadlines = alreadyLive.flatMap((entry) =>
+    entry.reply_deadline_at === undefined || entry.reply_deadline_at <= startedAt
+      ? []
+      : [entry.reply_deadline_at],
+  )
+  const ceilingAt = Math.min(
+    hardDeadlineAt,
+    ...(existingDeadlines.length === 0 ? [] : existingDeadlines),
+  )
+  if (unasked.length > 0 && alreadyLive.length === 0) {
+    const oldest = Math.min(...unasked.map((entry) => entry.asked_at ?? ctx.now()))
+    await awaitTerminalFirstWindow(ctx, oldest, ceilingAt)
+    ctx.log?.debug('hook.gate', {
+      verdict: 'grace',
+      reason: 'elapsed',
+      waited_from: oldest,
+      grace_seconds: ctx.config.ask_grace_seconds.value,
+    })
   }
-
   // Phase one: every registered question reaches the user's devices, each as
   // its own notification — one ask never stands in for another.
   const submitted: PendingQuestion[] = []
   for (const entry of unasked) {
+    // The reply window is the question's own: whatever is left of the waiter's
+    // ceiling, granted to the server so it stops accepting answers at the same
+    // moment this owner stops listening for them.
+    const replyWindowSeconds = Math.floor((ceilingAt - ctx.now()) / 1000)
+    if (replyWindowSeconds < MIN_REPLY_WINDOW_SECONDS) {
+      notes.push(
+        'too little of the waiter ceiling is left for a reply window the server would accept; leaving this question in the terminal',
+      )
+      continue
+    }
+    const ownerDeadlineAt = ceilingAt
     const questions = pendingQuestions(entry)
-    const sent = await submitQuestion(ctx, {
-      title:
-        ctx.config.project.value === null
-          ? 'Question'
-          : `Question · ${ctx.config.project.value}`,
-      // A set is answered on the expanded card; the banner leads with the
-      // first question and says how much more is waiting behind it.
-      body:
-        questions.length > 1
-          ? `${questions[0]!.text} (+${questions.length - 1} more)`
-          : entry.question,
-      questions,
-      ...(entry.detail !== undefined ? { detail: entry.detail } : {}),
-      event: 'agent_question',
-      session: sessionLabel(ctx, envelope),
-      // Outlives the block, and stays open on purpose: the answer is still
-      // useful to the next turn, which collects it with `notifai replies`.
-      windowSeconds: QUESTION_WINDOW_SECONDS,
-    })
-    if ('error' in sent) {
-      notes.push(sent.error)
+    let intent = entry.submission
+    if (intent === undefined) {
+      const prepared = await prepareQuestionSubmission(ctx, {
+        title:
+          ctx.config.project.value === null
+            ? 'Question'
+            : `Question · ${ctx.config.project.value}`,
+        // A set is answered on the expanded card; the banner leads with the
+        // first question and says how much more is waiting behind it.
+        body:
+          questions.length > 1
+            ? `${questions[0]!.text} (+${questions.length - 1} more)`
+            : entry.question,
+        questions,
+        ...(entry.detail !== undefined ? { detail: entry.detail } : {}),
+        event: 'agent_question',
+        session: sessionLabel(ctx, envelope),
+        windowSeconds: replyWindowSeconds,
+        ownerDeadlineAt,
+      })
+      if ('error' in prepared) {
+        ctx.log?.error('hook.pushed', { ok: false, message: prepared.error })
+        notes.push(prepared.error)
+        continue
+      }
+      intent = prepared
+      // Durable before submit. If the server commits and the response is lost,
+      // the reserved request id still lets this owner poll and finalize the
+      // exact card; a successor can also replay the frozen draft/key.
+      updateSessionState(sessionId, ctx.env, (current) => {
+        const list = pendingList(current)
+        const index = list.findIndex((candidate) => isSamePending(candidate, entry))
+        if (index < 0) return current
+        const next = [...list]
+        next[index] = { ...next[index]!, submission: prepared }
+        return { ...current, pending: next }
+      })
+    } else if (intent.owner_deadline_at <= ctx.now()) {
+      // The frozen wire identity survives a crashed owner, but its local owner
+      // lease does not. Re-arm only the local deadline; request id, key,
+      // targets, and draft remain byte-identical for idempotent replay.
+      intent = { ...intent, owner_deadline_at: ceilingAt }
+      const rearmed = intent
+      updateSessionState(sessionId, ctx.env, (current) => {
+        const list = pendingList(current)
+        const index = list.findIndex((candidate) => isSamePending(candidate, entry))
+        if (index < 0) return current
+        const next = [...list]
+        next[index] = { ...next[index]!, submission: rearmed }
+        return { ...current, pending: next }
+      })
+    }
+    if (ctx.now() >= intent.owner_deadline_at) {
+      notes.push('the waiter ceiling ended before submission; preserving the frozen intent')
+      continue
+    }
+    const beforeSubmitSeconds = Math.floor((intent.owner_deadline_at - ctx.now()) / 1000)
+    if (beforeSubmitSeconds < MIN_REPLY_WINDOW_SECONDS) {
+      notes.push(
+        'device resolution consumed the reply window; preserving the frozen intent instead of shrinking it below what the server accepts',
+      )
       continue
     }
+    let receipt: SubmissionReceipt | undefined
+    let admissionConfirmed = false
+    try {
+      receipt = await submitQuestion(ctx, intent)
+      admissionConfirmed = true
+    } catch (err) {
+      if (err instanceof ApiCallError && err.status < 500 && err.status !== 408) {
+        // A concrete client response is an admission rejection, not an
+        // ambiguous commit. Keep the frozen intent for a later retry and leave
+        // the question in the terminal; polling a request the server says it
+        // did not accept only burns the owner window and hides the real fault.
+        notes.push(
+          `question submission was rejected (${err.code}, HTTP ${err.status}); preserving it for recovery`,
+        )
+        ctx.log?.error('hook.pushed', {
+          ok: false,
+          request_id: intent.request_id,
+          status: err.status,
+          code: err.code,
+          message: err.message,
+        })
+        continue
+      }
+      // This is deliberately not a fail-open return. A transport failure is
+      // ambiguous: the server may already have dispatched the card. The
+      // client-generated request id keeps polling/finalization possible.
+      notes.push(`question submission response was ambiguous; recovering ${intent.request_id}`)
+      ctx.log?.error('hook.pushed', { ok: false, request_id: intent.request_id, message: String(err) })
+    }
+    if (admissionConfirmed) {
+      ctx.log?.info('hook.pushed', {
+        ok: true,
+        request_id: intent.request_id,
+        devices: intent.device_ids.length,
+        questions: questions.length,
+        text: questions[0]!.text,
+      })
+    }
+    const committedReplyDeadline =
+      receipt?.reply_expires_at === null || receipt?.reply_expires_at === undefined
+        ? intent.owner_deadline_at
+        : Date.parse(receipt.reply_expires_at)
     const live: PendingQuestion = {
       ...entry,
-      request_id: sent.requestId,
-      collapse_key: sent.collapseKey,
-      device_ids: sent.devices,
+      request_id: intent.request_id,
+      collapse_key: intent.collapse_key,
+      device_ids: intent.device_ids,
+      // Submission and every later poll share one wall-clock owner. The
+      // server may start its relative window a little later while the submit
+      // response is in flight; closing at this deadline is therefore the
+      // authoritative backstop against accepting an answer into a void.
+      reply_deadline_at: Math.min(
+        intent.owner_deadline_at,
+        Number.isFinite(committedReplyDeadline)
+          ? committedReplyDeadline
+          : intent.owner_deadline_at,
+      ),
     }
+    delete live.submission
     submitted.push(live)
     // Record what is now live on the user's devices BEFORE any wait. If we
     // only learned these ids afterwards, a question that timed out would
     // leave no trace, and the user returning to the terminal could never
     // retire it — the notification would stay answerable for an hour with
     // nobody listening.
-    updateSessionState(sessionId, ctx.env, (current) => {
-      const list = pendingList(current)
-      const index = list.findIndex(
-        (candidate) => isSamePending(candidate, entry) && candidate.request_id === undefined,
-      )
-      if (index >= 0) {
-        const next = [...list]
-        next[index] = live
-        return { ...current, pending: next }
-      }
-      // The entry vanished while the submit was in flight (the user's prompt
-      // wiped the queue). The delivered notification must still be retirable,
-      // so park it rather than lose its only identifiers.
-      const retirement = retiringQuestion(live, 'answered_elsewhere')!
-      const retiring = [...(current.retiring ?? [])]
-      if (!retiring.some((parked) => parked.request_id === retirement.request_id)) {
-        retiring.push(retirement)
-      }
-      return { ...current, retiring }
-    })
+    if (admissionConfirmed) {
+      updateSessionState(sessionId, ctx.env, (current) => {
+        const list = pendingList(current)
+        const index = list.findIndex(
+          (candidate) => isSamePending(candidate, entry) && candidate.request_id === undefined,
+        )
+        if (index >= 0) {
+          const next = [...list]
+          next[index] = live
+          return { ...current, pending: next }
+        }
+        // The entry vanished while the submit was in flight (the user's prompt
+        // wiped the queue). The delivered notification must still be retirable,
+        // so park it rather than lose its only identifiers.
+        const retirement = retiringQuestion(live, 'answered_elsewhere')!
+        const retiring = [...(current.retiring ?? [])]
+        if (!retiring.some((parked) => parked.request_id === retirement.request_id)) {
+          retiring.push(retirement)
+        }
+        return { ...current, retiring }
+      })
+    }
   }
 
-  const waitingOn = [...alreadyLive, ...submitted]
-  if (waitingOn.length === 0) return { notes }
-
-  if (ctx.harness === 'opencode') {
+  const staleLive = alreadyLive.filter(
+    (entry) =>
+      entry.reply_deadline_at === undefined || entry.reply_deadline_at <= ctx.now(),
+  )
+  const finalizedStale = await finalizePendings(ctx, staleLive)
+  const staleAnswers = finalizedStale
+    .map(finalizedAnswer)
+    .filter((entry): entry is AnsweredPending => entry !== null)
+  const staleSilence = finalizedStale
+    .filter((entry) => entry.response !== null && entry.response.replies.length === 0)
+    .map((entry) => entry.pending)
+  const staleUnproven = finalizedStale.filter((entry) => entry.response === null)
+  if (staleSilence.length > 0) {
+    await retirePendings(ctx, envelope, sessionId, staleSilence, 'expired')
     notes.push(
-      `question${submitted.length === 1 ? '' : 's'} sent without blocking OpenCode; retrieve answers on the next prompt or with: notifai replies --pending`,
+      `expired ${staleSilence.length} question${staleSilence.length === 1 ? '' : 's'} whose continuation owner had ended`,
     )
-    return { notes }
   }
+  if (staleUnproven.length > 0) {
+    notes.push(
+      `could not finalize ${staleUnproven.length} expired question${staleUnproven.length === 1 ? '' : 's'}; preserving ownership for recovery`,
+    )
+  }
+  if (staleAnswers.length > 0) {
+    const remaining = Math.max(
+      0,
+      pendingList(readSessionState(sessionId, ctx.env)).length - staleAnswers.length,
+    )
+    const accepted = stageAcceptedAnswers(ctx, sessionId, staleAnswers, remaining)
+    for (const answer of staleAnswers) reportAnswer(ctx, notes, answer, true)
+    return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes)
+  }
+  const waitingOn = [
+    ...alreadyLive.filter(
+      (entry) => entry.reply_deadline_at !== undefined && entry.reply_deadline_at > ctx.now(),
+    ),
+    ...submitted,
+  ]
+  if (waitingOn.length === 0) return { notes }
 
-  // Phase two: one blocking wait across everything live, old and new alike.
-  const timeoutSeconds = ctx.config.hook_reply_timeout_seconds.value
-  const waited = await waitForAnyReplyWhileAway(
+  // Phase two: one wait across everything live, old and new alike.
+  const ownerDeadline = Math.min(
+    ceilingAt,
+    Math.max(...waitingOn.map((entry) => entry.reply_deadline_at!)),
+  )
+  const timeoutSeconds = Math.max(0, Math.ceil((ownerDeadline - ctx.now()) / 1000))
+  const waited = await waitForAnyReply(
     ctx,
     waitingOn.map((entry) => entry.request_id!),
     timeoutSeconds,
   )
+  const permanentFailure = permanentReplyFailureNote(waited.permanentFailures)
+  if (permanentFailure !== null) notes.push(permanentFailure)
 
   if (waited.byRequest.size === 0) {
-    // Keep the pending records so a returning user's UserPromptSubmit can
-    // retire the notifications still live on their devices. `request_id`
-    // being set is also what stops the next Stop pushing them again.
-    const ids = waitingOn.map((entry) => entry.request_id).join(', ')
-    if (waited.userReturned) {
+    // Once this owner returns, no shipped command-hook harness can guarantee
+    // a later answer reaches the same agent turn. Close first, then retire the
+    // local records, so the Companion never accepts an answer into a void.
+    const finalized = await finalizePendings(ctx, waitingOn)
+    const finalAnswers = finalized
+      .map(finalizedAnswer)
+      .filter((entry): entry is AnsweredPending => entry !== null)
+    const confirmedSilent = finalized
+      .filter((entry) => entry.response !== null && entry.response.replies.length === 0)
+      .map((entry) => entry.pending)
+    const unproven = finalized.filter((entry) => entry.response === null)
+    if (confirmedSilent.length > 0) {
+      await retirePendings(ctx, envelope, sessionId, confirmedSilent, 'expired')
+    }
+    if (unproven.length > 0) {
       notes.push(
-        `you came back after the question${waitingOn.length === 1 ? ' was' : 's were'} sent; returning the terminal while ${waitingOn.length === 1 ? 'it stays' : 'they stay'} answerable (${ids}). ` +
-          'Retrieve answers with: notifai replies --pending',
+        `could not finalize ${unproven.length} question${unproven.length === 1 ? '' : 's'}; preserving ownership rather than risking a lost late answer`,
+      )
+    }
+    if (finalAnswers.length > 0) {
+      const remaining = Math.max(
+        0,
+        pendingList(readSessionState(sessionId, ctx.env)).length - finalAnswers.length,
       )
-    } else {
+      const accepted = stageAcceptedAnswers(ctx, sessionId, finalAnswers, remaining)
+      for (const answer of finalAnswers) reportAnswer(ctx, notes, answer, false)
+      return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes)
+    }
+    const requestIdSummary = summarizeRequestIds(waitingOn)
+    ctx.log?.info('hook.answer', {
+      answered: false,
+      stage: 'queued',
+      request_ids: requestIdSummary.ids,
+      degraded: waited.degraded,
+      permanent_failures: waited.permanentFailures.size,
+      waited_seconds: timeoutSeconds,
+    })
+    if (waited.permanentFailures.size === 0) {
       notes.push(
         waited.degraded
-          ? 'could not reach the server to find out whether you answered; check with: notifai replies --pending'
-          : 'no answer in time; retrieve it later with: notifai replies --pending',
+          ? 'could not reach the server before the owner deadline; the question was retired so no answer can be lost later'
+          : 'no answer in time; the question expired with its continuation owner',
       )
     }
     return { notes }
   }
 
+  const polledAnswered = waitingOn.filter((entry) => waited.byRequest.has(entry.request_id!))
+  const finalizedAnswered = await finalizePendings(ctx, polledAnswered)
   const answered: AnsweredPending[] = []
-  for (const entry of waitingOn) {
+  for (const finalized of finalizedAnswered) {
+    const entry = finalized.pending
     const replies = waited.byRequest.get(entry.request_id!)
     if (replies === undefined) continue
-    // First answer claims the question across devices; the close is what
-    // enforces that, and the latest reply within the window is the answer.
-    await closeQuietly(ctx, entry.request_id!)
-    answered.push({ pending: entry, reply: replies.at(-1)!, replies })
-  }
-  await finishAnsweredPendings(ctx, envelope, sessionId, answered, true)
-  for (const { reply } of answered) {
-    notes.push(`answer from ${reply.device_name}: ${reply.text}`)
-  }
-  return {
-    stdout: stopAnswerOutput(answersContext(answered, waitingOn.length - answered.length)),
-    notes,
+    // The fenced set wins because it includes corrections that committed
+    // while close was waiting for earlier writers. If finalization itself was
+    // unreachable, never discard the durable reply already observed.
+    const finalReplies = finalized.response?.replies ?? []
+    const authoritative = finalReplies.length > 0 ? finalReplies : replies
+    answered.push({ pending: entry, reply: authoritative.at(-1)!, replies: authoritative })
+    if (finalized.response === null) {
+      notes.push(
+        `could not confirm the close fence for ${entry.request_id}; delivering the durable answer already observed`,
+      )
+    }
   }
+  const accepted = stageAcceptedAnswers(
+    ctx,
+    sessionId,
+    answered,
+    waitingOn.length - answered.length,
+  )
+  for (const answer of answered) reportAnswer(ctx, notes, answer, false)
+  return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes)
 }
 
 // ---------------------------------------------------------------------------
@@ -1607,7 +2464,7 @@ export function handleSessionEnd(
 ): HookOutcome {
   const notes: string[] = []
   const sessionId = envelope.session_id
-  if (!sessionId) return { notes }
+  if (!sessionId) return { notes, log: { outcome: 'ignored', reason: 'missing-session-id' } }
   if (envelope.cwd !== undefined) clearMatchingProjectSession(envelope.cwd, env, sessionId)
 
   const state = readSessionState(sessionId, env)
@@ -1620,7 +2477,10 @@ export function handleSessionEnd(
       notes.push(err instanceof Error ? err.message : String(err))
       // Preserve the only identifiers instead of turning an explicit corrupt
       // state into an unretirable question during SessionEnd cleanup.
-      return { notes }
+      return {
+        notes,
+        log: { outcome: 'preserved', reason: 'incomplete-question-identifiers' },
+      }
     }
   }
   if (orphans.length > 0) {
@@ -1630,8 +2490,24 @@ export function handleSessionEnd(
       `queued ${orphans.length} question${orphans.length > 1 ? 's' : ''} for retirement on the next hook`,
     )
   }
+  if (state.accepted !== undefined) {
+    const preserved: SessionState = { accepted: state.accepted }
+    if (state.last_prompt_at !== undefined) preserved.last_prompt_at = state.last_prompt_at
+    if (state.last_stop_at !== undefined) preserved.last_stop_at = state.last_stop_at
+    if (state.continuation !== undefined) preserved.continuation = state.continuation
+    writeSessionState(sessionId, env, preserved)
+    notes.push('preserved an accepted device answer for this exact session to resume')
+    return {
+      notes,
+      log: {
+        outcome: 'answer-preserved',
+        queued_retirements: orphans.length,
+        accepted_answers: state.accepted.answers.length,
+      },
+    }
+  }
   clearSessionState(sessionId, env)
-  return { notes }
+  return { notes, log: { outcome: 'cleaned', queued_retirements: orphans.length } }
 }
 
 // ---------------------------------------------------------------------------
@@ -1676,6 +2552,7 @@ export function registerQuestion(
       pending: [
         ...pending,
         {
+          question_id: `q_${randomBytes(12).toString('base64url')}`,
           asked_at: now,
           ...question,
           question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),