@raidiant/notifai 0.1.6 → 0.1.8

package/src/hooks.ts

@@ -1,5 +1,15 @@
 import { randomBytes } from 'node:crypto'
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
 import path from 'node:path'
 import type { LifecycleEndState, ReplyView } from '@raidiant/notifai-protocol'
 import type { ApiClient } from './client.js'
@@ -12,15 +22,16 @@ import {
   type CliConfig,
 } from './config.js'
 import { buildDraft } from './send.js'
+import { atomicWriteFileSync } from './atomic-file.js'
 
 /**
  * Harness hook handlers.
  *
- * Claude Code, Codex and OpenCode all expose the same three joints: a blocking
- * pre-approval hook that returns a decision, a turn-end hook, and a hook that
- * fires when the user submits a prompt. That is enough to answer a blocked
- * agent from the phone without the agent cooperating at all — no question
- * detection, no pending state in a context window that compaction will eat.
+ * 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.
  *
  * 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
@@ -61,6 +72,11 @@ export interface SessionState {
    * attempt 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. */
+  continuation?: {
+    answered_at: number
+    count: number
+  }
 }
 
 /** A delivered question awaiting its retirement push. */
@@ -217,15 +233,83 @@ export function writeSessionState(
   state: SessionState,
 ): void {
   const file = sessionStatePath(sessionId, env)
-  mkdirSync(path.dirname(file), { recursive: true })
-  writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 })
+  withFileLock(`${file}.lock`, () => writeSessionStateUnlocked(file, state))
 }
 
 export function clearSessionState(sessionId: string, env: NodeJS.ProcessEnv): void {
-  rmSync(sessionStatePath(sessionId, env), { force: true })
-  // The session override lives in a sibling file; leaving it behind meant a
-  // later session reusing the id silently inherited `ask_notifications = false`.
-  rmSync(sessionConfigPath(sessionId, env), { force: true })
+  const file = sessionStatePath(sessionId, env)
+  withFileLock(`${file}.lock`, () => {
+    rmSync(file, { force: true })
+    // The session override lives in a sibling file; leaving it behind meant a
+    // later session reusing the id silently inherited `ask_notifications = false`.
+    rmSync(sessionConfigPath(sessionId, env), { force: true })
+  })
+}
+
+function writeSessionStateUnlocked(file: string, state: SessionState): void {
+  atomicWriteFileSync(file, `${JSON.stringify(state, null, 2)}\n`)
+}
+
+function updateSessionState(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  update: (current: SessionState) => SessionState,
+): SessionState {
+  const file = sessionStatePath(sessionId, env)
+  return withFileLock(`${file}.lock`, () => {
+    const next = update(readSessionState(sessionId, env))
+    writeSessionStateUnlocked(file, next)
+    return next
+  })
+}
+
+/**
+ * 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.
+    }
+  }
 }
 
 /**
@@ -288,52 +372,101 @@ export function pruneAbandonedSessions(
  * pending question, see no `request_id`, and both escalate: one question, two
  * notifications.
  *
- * `wx` is the whole mechanism. Exclusive create is atomic on POSIX, so exactly
- * one process gets the claim and the other steps aside. A claim older than the
- * hook budget is a crashed process rather than a live one, and is broken — the
- * alternative is a stale lock file suppressing every question for that session
- * for ever, which is worse than the duplicate this prevents.
+ * 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.
  */
 const CLAIM_TTL_MS = STOP_BUDGET_SECONDS * 1000
+const heldClaims = new Map<string, string>()
 
 export function claimQuestionPush(
   sessionId: string,
   env: NodeJS.ProcessEnv,
   now: number = Date.now(),
+  beforeStaleReplace?: () => void,
 ): boolean {
   const file = claimPath(sessionId, env)
+  const guard = `${file}.guard`
+  const token = randomBytes(12).toString('base64url')
   mkdirSync(path.dirname(file), { recursive: true })
+  if (!acquireClaimGuard(guard)) return false
   try {
-    writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now })}\n`, {
-      mode: 0o600,
-      flag: 'wx',
-    })
-    return true
-  } 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 age = typeof held.at === 'number' ? now - held.at : Number.POSITIVE_INFINITY
-      if (age >= 0 && age < CLAIM_TTL_MS) return false
-    } catch {
-      // Unreadable or corrupt: treat as abandoned.
-    }
-    rmSync(file, { force: true })
     try {
-      writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now })}\n`, {
+      writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now, token })}\n`, {
         mode: 0o600,
         flag: 'wx',
       })
+      heldClaims.set(file, token)
       return true
     } catch {
-      // Someone else broke it first and won. One of us proceeding is the point.
-      return false
+      // Held. Break it only if whoever holds it cannot still be running.
+      try {
+        const held = JSON.parse(readFileSync(file, 'utf8')) as { at?: unknown }
+        const age = typeof held.at === 'number' ? now - held.at : Number.POSITIVE_INFINITY
+        if (age >= 0 && age < CLAIM_TTL_MS) return false
+      } catch {
+        // Unreadable or corrupt: treat as abandoned.
+      }
+      beforeStaleReplace?.()
+      rmSync(file, { force: true })
+      try {
+        writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now, token })}\n`, {
+          mode: 0o600,
+          flag: 'wx',
+        })
+        heldClaims.set(file, token)
+        return true
+      } catch {
+        return false
+      }
     }
+  } finally {
+    rmSync(guard, { force: true })
   }
 }
 
 export function releaseQuestionPush(sessionId: string, env: NodeJS.ProcessEnv): void {
-  rmSync(claimPath(sessionId, env), { force: true })
+  const file = claimPath(sessionId, env)
+  const token = heldClaims.get(file)
+  if (token === undefined) return
+  const guard = `${file}.guard`
+  if (!acquireClaimGuard(guard)) {
+    heldClaims.delete(file)
+    return
+  }
+  try {
+    try {
+      const held = JSON.parse(readFileSync(file, 'utf8')) as { token?: unknown }
+      if (held.token === token) rmSync(file, { force: true })
+    } catch {
+      // Missing or replaced claims are not ours to release.
+    }
+  } finally {
+    heldClaims.delete(file)
+    rmSync(guard, { force: true })
+  }
+}
+
+/** The guard serializes stale replacement and release; recover a crashed guard. */
+function acquireClaimGuard(file: string): boolean {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = openSync(file, 'wx', 0o600)
+      closeSync(handle)
+      return true
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return false
+      try {
+        if (Date.now() - statSync(file).mtimeMs < CLAIM_TTL_MS) return false
+      } catch {
+        // A vanished/corrupt guard is safe to retry once.
+      }
+      rmSync(file, { force: true })
+    }
+  }
+  return false
 }
 
 function claimPath(sessionId: string, env: NodeJS.ProcessEnv): string {
@@ -354,14 +487,22 @@ export function writeProjectSession(
   env: NodeJS.ProcessEnv,
   sessionId: string,
   now: number,
+  harness: HookHarness,
 ): void {
   const file = projectSessionPointerPath(cwd, env)
-  mkdirSync(path.dirname(file), { recursive: true })
-  writeFileSync(file, `${JSON.stringify({ session_id: sessionId, updated_at: now })}\n`, {
-    mode: 0o600,
+  withFileLock(`${file}.lock`, () => {
+    atomicWriteFileSync(
+      file,
+      `${JSON.stringify({ session_id: sessionId, updated_at: now, harness })}\n`,
+    )
   })
 }
 
+export interface ProjectSessionPointer {
+  sessionId: string
+  harness: HookHarness
+}
+
 /**
  * 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
@@ -373,21 +514,57 @@ export function readProjectSession(
   now: number,
   maxAgeMs = 24 * 3600 * 1000,
 ): string | null {
+  return readProjectSessionPointer(cwd, env, now, maxAgeMs)?.sessionId ?? null
+}
+
+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
-    return parsed.session_id
+    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 HOOK_HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'] as const
+
+function clearMatchingProjectSession(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  sessionId: string,
+): 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.
+    }
+  })
+}
+
 /**
  * Absent means the user is not at this machine's keyboard.
  *
@@ -455,8 +632,12 @@ 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. */
+  harness?: HookHarness
 }
 
+export type HookHarness = 'claude-code' | 'codex' | 'cursor' | 'opencode'
+
 interface AskResult {
   requestId: string
   collapseKey: string
@@ -465,8 +646,15 @@ interface AskResult {
   devices: string[]
   /** The wait ended amid network failures, so "no answer" is unproven. */
   degraded: boolean
+  /** False when the harness cannot consume a Stop answer and polling was skipped. */
+  waited: boolean
+  /** The user returned to this machine after the question was pushed. */
+  userReturned: boolean
 }
 
+/** Re-check local presence at this cadence while a pushed question is waiting. */
+const REPLY_PRESENCE_POLL_SECONDS = 5
+
 /**
  * Push a question and block for the answer.
  *
@@ -509,7 +697,6 @@ async function askAndWait(
     replyWindow: Math.max(60, options.windowSeconds),
     ...(options.choices !== undefined ? { replyChoice: options.choices } : {}),
     collapseKey,
-    level: 'time_sensitive',
   })
   if (!build.ok) return { error: build.error }
 
@@ -526,14 +713,62 @@ async function askAndWait(
     collapseKey,
     devices: answerable,
   })
-  const result = await ctx.waitForFirstReply(receipt.request_id, timeoutSeconds)
+  if (ctx.harness === 'opencode') {
+    return {
+      requestId: receipt.request_id,
+      collapseKey,
+      reply: null,
+      devices: answerable,
+      degraded: false,
+      waited: false,
+      userReturned: false,
+    }
+  }
+
+  const result = await waitForReplyWhileAway(ctx, receipt.request_id, timeoutSeconds)
   if (result.replies.length > 0) await closeQuietly(ctx, receipt.request_id)
   return {
     requestId: receipt.request_id,
     collapseKey,
     reply: result.replies[0] ?? null,
     devices: answerable,
-    degraded: result.degraded === true,
+    degraded: result.degraded,
+    waited: true,
+    userReturned: result.userReturned,
+  }
+}
+
+async function waitForReplyWhileAway(
+  ctx: HookContext,
+  requestId: string,
+  timeoutSeconds: number,
+): Promise<{ replies: ReplyView[]; degraded: boolean; userReturned: boolean }> {
+  const deadline = ctx.now() + timeoutSeconds * 1000
+  let degraded = false
+  let firstPoll = true
+
+  for (;;) {
+    if (ctx.config.require_idle.value) {
+      const idle = ctx.idleSeconds()
+      if (idle !== null && idle < ctx.config.away_after_seconds.value) {
+        return { replies: [], degraded, userReturned: true }
+      }
+    }
+
+    const remainingMs = Math.max(0, deadline - ctx.now())
+    if (!firstPoll && remainingMs === 0) {
+      return { replies: [], degraded, userReturned: false }
+    }
+    firstPoll = false
+    const pollSeconds = Math.min(
+      REPLY_PRESENCE_POLL_SECONDS,
+      Math.max(0, Math.ceil(remainingMs / 1000)),
+    )
+    const result = await ctx.waitForFirstReply(requestId, pollSeconds)
+    degraded ||= result.degraded === true
+    if (result.replies.length > 0) {
+      return { replies: result.replies, degraded, userReturned: false }
+    }
   }
 }
 
@@ -655,12 +890,17 @@ export function parkForRetirement(
 ): void {
   const retirement = retiringQuestion(pending, state)
   if (retirement === null) return
-  const current = readSessionState(sessionId, env)
-  const already = current.retiring ?? []
-  if (already.some((entry) => entry.request_id === retirement.request_id)) return
-  writeSessionState(sessionId, env, {
-    ...current,
-    retiring: [...already, retirement],
+  updateSessionState(sessionId, env, (current) => {
+    const already = current.retiring ?? []
+    const existing = already.findIndex((entry) => entry.request_id === retirement.request_id)
+    if (existing < 0) return { ...current, retiring: [...already, retirement] }
+    const retiring = [...already]
+    // An observed answer is final truth and upgrades an earlier supersession
+    // parked while the submission callback was racing a newer question.
+    if (retirement.state === 'answered' && retiring[existing]!.state !== 'answered') {
+      retiring[existing] = retirement
+    }
+    return { ...current, retiring }
   })
 }
 
@@ -718,7 +958,6 @@ export async function drainRetirements(
   if (queue.length === 0) return []
 
   const retired: string[] = []
-  const remaining: RetiringQuestion[] = []
   for (const entry of queue) {
     await closeQuietly(ctx, entry.request_id)
     const sent = await retire(
@@ -731,17 +970,18 @@ export async function drainRetirements(
       retirementDeviceIds(entry),
       session,
     )
-    if (sent) retired.push(entry.request_id)
-    else remaining.push(entry)
+    if (sent) {
+      retired.push(entry.request_id)
+      // Persist each success before touching the next entry. A later corrupt
+      // record or interrupted process must not resurrect work already done.
+      updateSessionState(sessionId, env, (current) => ({
+        ...current,
+        retiring: (current.retiring ?? []).filter(
+          (candidate) => candidate.request_id !== entry.request_id,
+        ),
+      }))
+    }
   }
-
-  // Re-read rather than reusing the snapshot: `notifai ask` may have parked
-  // another question while these were in flight.
-  const current = readSessionState(sessionId, env)
-  const untouched = (current.retiring ?? []).filter(
-    (entry) => !retired.includes(entry.request_id),
-  )
-  writeSessionState(sessionId, env, { ...current, retiring: untouched.length > 0 ? untouched : [] })
   return retired
 }
 
@@ -761,10 +1001,20 @@ function readOrphanQueue(env: NodeJS.ProcessEnv): OrphanRetirement[] {
   }
 }
 
-function writeOrphanQueue(env: NodeJS.ProcessEnv, queue: OrphanRetirement[]): void {
+function writeOrphanQueueUnlocked(file: string, queue: OrphanRetirement[]): void {
+  atomicWriteFileSync(file, `${JSON.stringify(queue, null, 2)}\n`)
+}
+
+function updateOrphanQueue(
+  env: NodeJS.ProcessEnv,
+  update: (current: OrphanRetirement[]) => OrphanRetirement[],
+): OrphanRetirement[] {
   const file = orphanQueuePath(env)
-  mkdirSync(path.dirname(file), { recursive: true })
-  writeFileSync(file, `${JSON.stringify(queue, null, 2)}\n`, { mode: 0o600 })
+  return withFileLock(`${file}.lock`, () => {
+    const next = update(readOrphanQueue(env))
+    writeOrphanQueueUnlocked(file, next)
+    return next
+  })
 }
 
 /** Move retirements into the global queue; deduped so a retry costs nothing. */
@@ -775,13 +1025,17 @@ export function orphanRetirements(
   now: number,
 ): void {
   if (entries.length === 0) return
-  const queue = readOrphanQueue(env)
-  const known = new Set(queue.map((entry) => entry.request_id))
-  const added = entries
-    .filter((entry) => !known.has(entry.request_id))
-    .map((entry) => ({ ...entry, ...(session !== undefined ? { session } : {}), enqueued_at: now }))
-  if (added.length === 0) return
-  writeOrphanQueue(env, [...queue, ...added].slice(-ORPHAN_QUEUE_CAP))
+  updateOrphanQueue(env, (queue) => {
+    const known = new Set(queue.map((entry) => entry.request_id))
+    const added = entries
+      .filter((entry) => !known.has(entry.request_id))
+      .map((entry) => ({
+        ...entry,
+        ...(session !== undefined ? { session } : {}),
+        enqueued_at: now,
+      }))
+    return [...queue, ...added].slice(-ORPHAN_QUEUE_CAP)
+  })
 }
 
 /**
@@ -803,6 +1057,9 @@ export async function drainOrphanRetirements(
     // and cheap, so treat it as due rather than letting it linger for ever.
     if (age > ORPHAN_TTL_MS) {
       done.push(entry.request_id)
+      updateOrphanQueue(env, (current) =>
+        current.filter((candidate) => candidate.request_id !== entry.request_id),
+      )
       continue
     }
     await closeQuietly(ctx, entry.request_id)
@@ -816,17 +1073,103 @@ export async function drainOrphanRetirements(
       retirementDeviceIds(entry),
       entry.session,
     )
-    if (sent) done.push(entry.request_id)
+    if (sent) {
+      done.push(entry.request_id)
+      updateOrphanQueue(env, (current) =>
+        current.filter((candidate) => candidate.request_id !== entry.request_id),
+      )
+    }
   }
-
-  // Re-read: another session's SessionEnd may have queued more while these were
-  // in flight, and clobbering its write would recreate the very loss this
-  // queue exists to prevent.
-  const current = readOrphanQueue(env).filter((entry) => !done.includes(entry.request_id))
-  writeOrphanQueue(env, current)
   return done
 }
 
+const LATE_STOP_POLL_SECONDS = 4
+const LATE_PROMPT_POLL_SECONDS = 3
+const MAX_CONTINUATION_COUNT = 3
+
+interface PendingPoll {
+  reply: ReplyView | null
+  degraded: boolean
+  failed: boolean
+}
+
+/** One bounded recovery poll for a question that outlived its original wait. */
+async function pollPendingReply(
+  ctx: HookContext,
+  pending: PendingQuestion,
+  timeoutSeconds: number,
+): Promise<PendingPoll> {
+  if (pending.request_id === undefined) return { reply: null, degraded: false, failed: false }
+  try {
+    const result = await ctx.waitForFirstReply(pending.request_id, timeoutSeconds)
+    return {
+      reply: result.replies[0] ?? null,
+      degraded: result.degraded === true,
+      failed: false,
+    }
+  } catch {
+    return { reply: null, degraded: true, failed: true }
+  }
+}
+
+function answerContext(reply: ReplyView): string {
+  return `Notifai — the user answered from ${reply.device_name}: "${reply.text}". Continue with that answer.`
+}
+
+function userPromptAnswerOutput(reply: ReplyView): string {
+  return JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: answerContext(reply),
+    },
+  })
+}
+
+function stopAnswerOutput(reply: ReplyView): string {
+  return JSON.stringify({ decision: 'block', reason: answerContext(reply) })
+}
+
+/**
+ * Close, truthfully retire, and forget one answered pending question without
+ * dropping any other retirement debt. Stop answers also open one bounded
+ * continuation generation; UserPromptSubmit answers ride the user's new turn.
+ */
+async function finishPendingAnswer(
+  ctx: HookContext,
+  envelope: HookEnvelope,
+  sessionId: string,
+  pending: PendingQuestion,
+  reply: ReplyView,
+  continuation: boolean,
+): Promise<void> {
+  const retirement = retiringQuestion(pending, 'answered')
+  updateSessionState(sessionId, ctx.env, (current) => {
+    const retiring = [...(current.retiring ?? [])]
+    if (retirement !== null) {
+      const existing = retiring.findIndex((entry) => entry.request_id === retirement.request_id)
+      if (existing < 0) retiring.push(retirement)
+      else retiring[existing] = retirement
+    }
+    const samePending =
+      current.pending?.question === pending.question &&
+      current.pending?.asked_at === pending.asked_at &&
+      current.pending?.request_id === pending.request_id
+    const next = { ...current, retiring }
+    if (samePending) delete next.pending
+    if (continuation) {
+      next.continuation = {
+        answered_at: ctx.now(),
+        count:
+          (envelope.stop_hook_active === true ? current.continuation?.count ?? 0 : 0) + 1,
+      }
+    } else {
+      next.last_prompt_at = ctx.now()
+    }
+    return next
+  })
+  await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))
+}
+
 // ---------------------------------------------------------------------------
 // UserPromptSubmit — the user is at the keyboard
 // ---------------------------------------------------------------------------
@@ -847,18 +1190,43 @@ export async function handleUserPromptSubmit(
 
   const state = readSessionState(sessionId, ctx.env)
   const pending = state.pending
+  if (pending?.request_id !== undefined) {
+    const late = await pollPendingReply(ctx, pending, LATE_PROMPT_POLL_SECONDS)
+    if (late.reply !== null) {
+      await finishPendingAnswer(ctx, envelope, sessionId, pending, late.reply, false)
+      if (envelope.cwd !== undefined && ctx.harness !== undefined) {
+        writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness)
+      }
+      await drainOrphanRetirements(ctx, ctx.env, ctx.now())
+      notes.push(`late answer from ${late.reply.device_name}: ${late.reply.text}`)
+      return { stdout: userPromptAnswerOutput(late.reply), notes }
+    }
+    if (late.failed || late.degraded) {
+      notes.push('could not check the pending question for a late answer before the prompt')
+    }
+  }
   // 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.
-  if (pending !== undefined) parkForRetirement(sessionId, ctx.env, pending, 'answered_elsewhere')
-  const parked = readSessionState(sessionId, ctx.env)
-  writeSessionState(sessionId, ctx.env, {
-    last_prompt_at: ctx.now(),
-    ...(parked.retiring !== undefined ? { retiring: parked.retiring } : {}),
+  updateSessionState(sessionId, ctx.env, (current) => {
+    const retiring = [...(current.retiring ?? [])]
+    if (current.pending !== undefined) {
+      const retirement = retiringQuestion(current.pending, 'answered_elsewhere')
+      if (
+        retirement !== null &&
+        !retiring.some((entry) => entry.request_id === retirement.request_id)
+      ) {
+        retiring.push(retirement)
+      }
+    }
+    return { last_prompt_at: ctx.now(), ...(retiring.length > 0 ? { retiring } : {}) }
   })
-  // The bridge that lets a plain `notifai ask` find its own session: an agent
-  // shell command gets no hook payload and no harness exports the id.
-  if (envelope.cwd !== undefined) writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now())
+  // 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
+  // harness exports an id in the same shape.
+  if (envelope.cwd !== undefined && ctx.harness !== undefined) {
+    writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness)
+  }
 
   const retired = await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))
   const orphaned = await drainOrphanRetirements(ctx, ctx.env, ctx.now())
@@ -903,22 +1271,46 @@ export async function handleStop(ctx: HookContext, envelope: HookEnvelope): Prom
     notes.push(`retired superseded question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`)
   }
 
-  // The harness sets this when it is already resuming us from a previous Stop
-  // decision. Pushing again here is how a question turns into nagging.
-  if (envelope.stop_hook_active === true) {
-    notes.push('already continuing from an answer; not asking again this turn')
-    return { notes }
-  }
-
   const state = readSessionState(sessionId, ctx.env)
   const pending = state.pending
   if (!pending) return { notes }
   if (pending.request_id !== undefined) {
+    const late = await pollPendingReply(ctx, pending, LATE_STOP_POLL_SECONDS)
+    if (late.reply !== null) {
+      await finishPendingAnswer(ctx, envelope, sessionId, pending, late.reply, true)
+      notes.push(`late answer from ${late.reply.device_name}: ${late.reply.text}`)
+      return { stdout: stopAnswerOutput(late.reply), notes }
+    }
     // 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.
-    notes.push(`already asked (${pending.request_id}); waiting for that answer`)
+    notes.push(
+      late.failed || late.degraded
+        ? `already asked (${pending.request_id}); could not check whether its answer arrived`
+        : `already asked (${pending.request_id}); waiting for that answer`,
+    )
     return { notes }
   }
+
+  // A Stop answer may immediately produce a legitimate follow-up question.
+  // Allow that new generation, but never re-run an old pending question and
+  // never let answer continuations become an unbounded agent loop.
+  if (envelope.stop_hook_active === true) {
+    const continuation = state.continuation
+    const isNew =
+      continuation !== undefined &&
+      pending.asked_at !== undefined &&
+      pending.asked_at > continuation.answered_at
+    if (!isNew) {
+      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')
@@ -935,7 +1327,7 @@ export async function handleStop(ctx: HookContext, envelope: HookEnvelope): Prom
     return { notes }
   }
   try {
-    return await escalate(ctx, envelope, sessionId, state, pending, notes)
+    return await escalate(ctx, envelope, sessionId, pending, notes)
   } finally {
     releaseQuestionPush(sessionId, ctx.env)
   }
@@ -946,7 +1338,6 @@ async function escalate(
   ctx: HookContext,
   envelope: HookEnvelope,
   sessionId: string,
-  state: SessionState,
   pending: PendingQuestion,
   notes: string[],
 ): Promise<HookOutcome> {
@@ -962,7 +1353,10 @@ async function escalate(
   }
 
   const asked = await askAndWait(ctx, {
-    title: 'A question from your agent',
+    title:
+      ctx.config.project.value === null
+        ? 'Question'
+        : `Question · ${ctx.config.project.value}`,
     body: pending.question,
     ...(pending.choices !== undefined ? { choices: pending.choices } : {}),
     event: 'agent_question',
@@ -971,16 +1365,28 @@ async function escalate(
     // useful to the next turn, which collects it with `notifai replies`.
     windowSeconds: QUESTION_WINDOW_SECONDS,
     onSubmitted: (live) => {
-      // Re-read: the drain at the top of this hook rewrote the queue, and the
-      // snapshot in `state` predates it.
-      writeSessionState(sessionId, ctx.env, {
-        ...readSessionState(sessionId, ctx.env),
-        pending: {
-          ...pending,
-          request_id: live.requestId,
-          collapse_key: live.collapseKey,
-          device_ids: live.devices,
-        },
+      const livePending: PendingQuestion = {
+        ...pending,
+        request_id: live.requestId,
+        collapse_key: live.collapseKey,
+        device_ids: live.devices,
+      }
+      updateSessionState(sessionId, ctx.env, (current) => {
+        const stillCurrent =
+          current.pending?.question === pending.question &&
+          current.pending?.asked_at === pending.asked_at &&
+          current.pending?.request_id === undefined
+        if (stillCurrent) return { ...current, pending: livePending }
+
+        // A newer `notifai ask` won while this submit was in flight. Keep it,
+        // but now that request identifiers exist, preserve the old delivered
+        // question as collectable/retirable instead of overwriting either one.
+        const retirement = retiringQuestion(livePending, 'superseded')!
+        const retiring = [...(current.retiring ?? [])]
+        if (!retiring.some((entry) => entry.request_id === retirement.request_id)) {
+          retiring.push(retirement)
+        }
+        return { ...current, retiring }
       })
     },
   })
@@ -989,59 +1395,38 @@ async function escalate(
     return { notes }
   }
 
-  // What survives replacing the pending record. `retiring` has to: dropping it
-  // is exactly the class of bug this guards against — a delivered notification
-  // whose ids no longer exist anywhere.
-  const current = readSessionState(sessionId, ctx.env)
-  const carried = {
-    ...(state.last_prompt_at !== undefined ? { last_prompt_at: state.last_prompt_at } : {}),
-    ...(current.retiring !== undefined ? { retiring: current.retiring } : {}),
-  }
-
   if (!asked.reply) {
     // Keep the pending record so a returning user's UserPromptSubmit can retire
     // the notification that is still live on their devices. `request_id` being
     // set is also what stops the next Stop pushing the same question again.
-    writeSessionState(sessionId, ctx.env, {
-      ...carried,
-      pending: {
-        ...pending,
-        request_id: asked.requestId,
-        collapse_key: asked.collapseKey,
-        device_ids: asked.devices,
-      },
-    })
-    notes.push(
-      asked.degraded
-        ? `could not reach the server to find out whether you answered; check with: notifai replies ${asked.requestId}`
-        : `no answer in time; retrieve it later with: notifai replies ${asked.requestId}`,
-    )
+    if (!asked.waited) {
+      notes.push(
+        `question sent without blocking OpenCode; retrieve the answer on the next prompt or with: notifai replies --pending`,
+      )
+    } else if (asked.userReturned) {
+      notes.push(
+        `you came back after the question was sent; returning the terminal while it stays answerable (${asked.requestId}). ` +
+          'Retrieve it with: notifai replies --pending',
+      )
+    } else {
+      notes.push(
+        asked.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`,
+      )
+    }
     return { notes }
   }
 
-  // Answered and closed — nothing left to retire.
-  writeSessionState(sessionId, ctx.env, carried)
-
-  await retire(
-    ctx,
-    asked.collapseKey,
-    'Answered',
-    asked.reply.text,
-    'answered',
-    asked.requestId,
-    asked.devices,
-    sessionLabel(ctx, envelope),
-  )
+  await finishPendingAnswer(ctx, envelope, sessionId, {
+    ...pending,
+    request_id: asked.requestId,
+    collapse_key: asked.collapseKey,
+    device_ids: asked.devices,
+  }, asked.reply, true)
   notes.push(`answer from ${asked.reply.device_name}: ${asked.reply.text}`)
   return {
-    stdout: JSON.stringify({
-      decision: 'block',
-      // Harnesses render a Stop decision under an error-ish label, so this
-      // text must read as an answer on its own rather than as a failure.
-      reason:
-        `NotifAI — the user answered from ${asked.reply.device_name}: ` +
-        `"${asked.reply.text}". Continue with that answer.`,
-    }),
+    stdout: stopAnswerOutput(asked.reply),
     notes,
   }
 }
@@ -1066,6 +1451,7 @@ export function handleSessionEnd(
   const notes: string[] = []
   const sessionId = envelope.session_id
   if (!sessionId) return { notes }
+  if (envelope.cwd !== undefined) clearMatchingProjectSession(envelope.cwd, env, sessionId)
 
   const state = readSessionState(sessionId, env)
   const orphans: RetiringQuestion[] = [...(state.retiring ?? [])]
@@ -1116,16 +1502,26 @@ export function registerQuestion(
   question: PendingQuestion,
   now: number = Date.now(),
 ): void {
-  const state = readSessionState(sessionId, env)
-  if (state.pending !== undefined) parkForRetirement(sessionId, env, state.pending, 'superseded')
-  // Re-read: parkForRetirement wrote the queue we must not clobber.
-  writeSessionState(sessionId, env, {
-    ...readSessionState(sessionId, env),
-    pending: {
-      asked_at: now,
-      ...question,
-      question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
-    },
+  updateSessionState(sessionId, env, (state) => {
+    const retiring = [...(state.retiring ?? [])]
+    if (state.pending !== undefined) {
+      const retirement = retiringQuestion(state.pending, 'superseded')
+      if (
+        retirement !== null &&
+        !retiring.some((entry) => entry.request_id === retirement.request_id)
+      ) {
+        retiring.push(retirement)
+      }
+    }
+    return {
+      ...state,
+      ...(retiring.length > 0 ? { retiring } : {}),
+      pending: {
+        asked_at: now,
+        ...question,
+        question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
+      },
+    }
   })
 }