@raidiant/notifai 3.0.1 → 5.0.0

package/src/hooks.ts

@@ -11,12 +11,15 @@ import {
   writeFileSync,
 } from 'node:fs'
 import path from 'node:path'
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol'
 import type {
   LifecycleEndState,
   ListRepliesResponse,
+  MediaItemT,
   NotificationDraftT,
   QuestionT,
   ReplyView,
+  SourceContextT,
   SubmissionReceipt,
 } from '@raidiant/notifai-protocol'
 import {
@@ -125,11 +128,19 @@ export interface SessionState {
    * the service confirms the agent-authored follow-up exists.
    */
   acknowledgement_due?: AcknowledgementDue[]
+  /** Consecutive turns this session has been held for an acknowledgement. */
+  acknowledgement_blocks?: number
 }
 
 export interface AcknowledgementDue {
   request_id: string
   recorded_at: number
+  /**
+   * Whether this request's acknowledgement must carry text. Absent on state
+   * written before the obligation started recording it; treated as true, which
+   * is the default the service ships.
+   */
+  text_required?: boolean
 }
 
 interface AcceptedAnswerDelivery {
@@ -150,6 +161,8 @@ interface AcceptedAnswerDelivery {
    * passes through.
    */
   delivery_attempts?: number
+  /** Turns this answer has been held without being handed to the agent. */
+  held_deliveries?: number
 }
 
 /** A delivered question awaiting its retirement push. */
@@ -160,6 +173,8 @@ export interface RetiringQuestion {
   device_ids: string[]
   /** Shown if the companion has no history entry to correlate against. */
   question: string
+  project?: string
+  source?: SourceContextT
   state: LifecycleEndState
 }
 
@@ -175,19 +190,20 @@ export interface RetiringQuestion {
  * next holds a client.
  */
 export interface OrphanRetirement extends RetiringQuestion {
-  /** Label of the session that asked, so the retirement sync matches its badge. */
-  session?: string
   /** Epoch ms when the entry was orphaned; entries beyond the TTL are dropped. */
   enqueued_at: number
 }
 
 /**
- * Past this, the question's reply window (3600s) has long expired server-side
- * and the companion shows it as dead on next open anyway; pushing a retirement
- * sync for it is noise. Also the backstop that keeps an unreachable server
- * from growing the queue for ever.
+ * A retirement is only worth syncing while the question it retires could still
+ * be answered, so this has to outlive the longest reply window a user can
+ * choose — it is derived from that bound rather than from a guess about how
+ * long questions stay open, which is exactly the assumption that broke when
+ * the window stopped being one hour. Past it the companion shows the question
+ * as dead on next open anyway. Also the backstop that keeps an unreachable
+ * server from growing the queue for ever.
  */
-const ORPHAN_TTL_MS = 24 * 3600 * 1000
+const ORPHAN_TTL_MS = (REPLY_MAX_WINDOW_SECONDS + 3600) * 1000
 
 /** More orphans than this means something is looping; keep the newest. */
 const ORPHAN_QUEUE_CAP = 50
@@ -208,8 +224,13 @@ export interface PendingQuestion {
    * texts, choices, multi flags. What actually rides the push.
    */
   questions?: QuestionT[]
-  /** Long-form markdown context, shown in the companion's detail view. */
-  detail?: string
+  /** Canonical Markdown body composed when the question was registered. */
+  body?: string
+  /** Final ordered media collection; uploads complete before registration. */
+  media?: MediaItemT[]
+  /** Final Project and Source Context frozen at registration. */
+  project?: string
+  source?: SourceContextT
   /** Set once the question has actually been pushed, so it can be retired. */
   request_id?: string
   collapse_key?: string
@@ -251,12 +272,35 @@ function summarizeRequestIds(entries: readonly PendingQuestion[]): {
  */
 export const WAITER_CEILING_SECONDS = 480
 
+/**
+ * The same wall clock where the waiter runs in the background instead of
+ * inside a held turn.
+ *
+ * On a host that holds its turn, 480 s is a real cost to the person sitting in
+ * front of it, and the number above is right. On Claude Code the Stop hook
+ * returns at once and the waiter is detached, so the same 480 s buys nothing
+ * and costs a direct wake: an answer arriving at minute nine had to wait for
+ * the session's next turn even though nothing was blocked.
+ *
+ * This sits under `CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS` (3600) with headroom,
+ * because that declaration's kill is silent, and under the reply window the
+ * question was pushed with. Past it the journal still delivers at the next
+ * turn — the ceiling decides how long a *direct* wake stays possible, never
+ * whether the answer survives.
+ */
+export const DETACHED_WAITER_CEILING_SECONDS = 3300
+
+/** The waiter's wall clock, which depends on whether a turn is held open for it. */
+export function waiterCeilingSeconds(detached: boolean): number {
+  return detached ? DETACHED_WAITER_CEILING_SECONDS : WAITER_CEILING_SECONDS
+}
+
 /**
  * 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
+export const MIN_REPLY_WINDOW_SECONDS = 60
 
 /**
  * The terminal-first wait: the question sits in the terminal for
@@ -469,6 +513,17 @@ export function pruneAbandonedSessions(
  * no trustworthy PID fall back to an age limit.
  */
 const CLAIM_TTL_MS = WAITER_CEILING_SECONDS * 1000
+
+/**
+ * How long a crashed claim *guard* blocks the next hook.
+ *
+ * The claim itself may legitimately be held for the whole waiter, so it takes
+ * that ceiling. The guard is a short lock around the claim's own bookkeeping —
+ * a few file operations — and borrowing the waiter's ceiling for it meant a
+ * hook killed at exactly the wrong moment wedged this session's Stop path for
+ * eight minutes, for a critical section that never runs longer than a second.
+ */
+const CLAIM_GUARD_TTL_MS = 30_000
 const heldClaims = new Map<string, string>()
 
 export function claimQuestionPush(
@@ -562,7 +617,7 @@ function acquireClaimGuard(file: string): boolean {
     } catch (err) {
       if ((err as NodeJS.ErrnoException).code !== 'EEXIST') return false
       try {
-        if (Date.now() - statSync(file).mtimeMs < CLAIM_TTL_MS) return false
+        if (Date.now() - statSync(file).mtimeMs < CLAIM_GUARD_TTL_MS) return false
       } catch {
         // A vanished/corrupt guard is safe to retry once.
       }
@@ -788,19 +843,29 @@ export interface HookContext {
  * 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'
-  | 'acknowledgement-required'
-  | 'notifications-off'
-  | 'claimed-elsewhere'
-  | 'no-devices'
-  | 'proceeding'
+export const GATE_REASONS = [
+  'no-session',
+  'no-question',
+  'answered',
+  'continuation-repeat',
+  'continuation-limit',
+  'delivery-limit',
+  'acknowledgement-required',
+  'acknowledgement-abandoned',
+  'harness-cannot-continue',
+  'notifications-off',
+  'claimed-elsewhere',
+  'elapsed',
+  'proceeding',
+] as const
+
+/**
+ * A runtime list rather than a bare type, so the guidance that tells agents to
+ * filter on these can be tested against the set the code can actually emit.
+ * `already-asked` and `no-devices` were declared here for a long time and never
+ * emitted once; documenting them taught agents to filter for silence.
+ */
+export type GateReason = (typeof GATE_REASONS)[number]
 
 function gate(
   ctx: HookContext,
@@ -840,10 +905,10 @@ async function prepareQuestionSubmission(
     title: string
     body: string
     questions: QuestionT[]
-    detail?: string | undefined
+    media?: MediaItemT[] | undefined
+    project?: string | undefined
+    source?: SourceContextT | undefined
     event: string
-    /** Which agent is asking; two of them must not look alike. */
-    session?: string | undefined
     /** How long the server keeps accepting an answer. */
     windowSeconds: number
     /** Absolute owner deadline persisted before submit. */
@@ -857,19 +922,23 @@ async function prepareQuestionSubmission(
   if (answerable.length === 0) {
     return { error: 'no device can answer a question yet; leaving this to the terminal' }
   }
-  const build = buildDraft(ctx.config, {
-    title: options.title,
-    body: options.body,
-    event: options.event,
-    lifecycle: { tier: 'needs_you' },
-    ...(options.session !== undefined ? { session: options.session } : {}),
-    device: answerable,
-    reply: true,
-    replyWindow: Math.max(60, options.windowSeconds),
-    questions: options.questions,
-    ...(options.detail !== undefined ? { detail: options.detail } : {}),
-    collapseKey,
-  })
+  const build = buildDraft(
+    ctx.config,
+    {
+      title: options.title,
+      body: options.body,
+      event: options.event,
+      lifecycle: { tier: 'needs_you' },
+      ...(options.project !== undefined ? { project: options.project } : {}),
+      ...(options.media !== undefined ? { media: options.media } : {}),
+      device: answerable,
+      reply: true,
+      replyWindow: Math.max(MIN_REPLY_WINDOW_SECONDS, options.windowSeconds),
+      questions: options.questions,
+      collapseKey,
+    },
+    options.source === undefined ? {} : { source: options.source },
+  )
   if (!build.ok) return { error: build.error }
 
   return {
@@ -996,23 +1065,6 @@ async function answerableDevices(ctx: HookContext): Promise<string[]> {
     .map((device) => device.device_id)
 }
 
-/**
- * The session id this push is attributed to — the same one `send` carries.
- *
- * The hook has always known `session_id` and never passed it on, so two agents
- * in separate worktrees produced identical notifications and the user could
- * answer the wrong one's question. An exported `NOTIFAI_SESSION`
- * still wins, for coherence rather than vanity: it is THE session id wherever
- * it is set, so a session that exported one before launching must carry
- * the same on its own sends and on the questions its hooks push. A name the
- * user chose also outlives harness restarts, which a per-launch UUID cannot.
- */
-function sessionLabel(ctx: HookContext, envelope: HookEnvelope): string | undefined {
-  const explicit = ctx.env['NOTIFAI_SESSION']
-  if (explicit !== undefined && explicit !== '') return explicit
-  return envelope.session_id
-}
-
 /**
  * Everything retirement needs. Narrower than a HookContext on purpose:
  * `notifai ask` supersedes the previous question and it is a plain command with
@@ -1058,18 +1110,23 @@ async function retire(
   endState: LifecycleEndState,
   retiresRequestId: string,
   devices?: string[],
-  session?: string | undefined,
+  project?: string | undefined,
+  source?: SourceContextT | undefined,
 ): Promise<boolean> {
-  const build = buildDraft(ctx.config, {
-    title,
-    body,
-    event: 'question_retired',
-    lifecycle: { tier: 'done', state: endState, retires_request_id: retiresRequestId },
-    ...(session !== undefined ? { session } : {}),
-    ...(devices !== undefined && devices.length > 0 ? { device: devices } : {}),
-    collapseKey,
-    level: 'passive',
-  })
+  const build = buildDraft(
+    ctx.config,
+    {
+      title,
+      body,
+      event: 'question_retired',
+      lifecycle: { tier: 'done', state: endState, retires_request_id: retiresRequestId },
+      ...(project !== undefined ? { project } : {}),
+      ...(devices !== undefined && devices.length > 0 ? { device: devices } : {}),
+      collapseKey,
+      level: 'passive',
+    },
+    source === undefined ? {} : { source },
+  )
   if (!build.ok) return false
   try {
     await ctx.client.submit(
@@ -1150,6 +1207,8 @@ function retiringQuestion(
     collapse_key: pending.collapse_key!,
     device_ids: [...pending.device_ids!],
     question: pending.question,
+    ...(pending.project !== undefined ? { project: pending.project } : {}),
+    ...(pending.source !== undefined ? { source: pending.source } : {}),
     state,
   }
 }
@@ -1172,7 +1231,6 @@ export async function drainRetirements(
   ctx: RetireDeps,
   sessionId: string,
   env: NodeJS.ProcessEnv,
-  session?: string | undefined,
 ): Promise<string[]> {
   const queue = readSessionState(sessionId, env).retiring ?? []
   if (queue.length === 0) return []
@@ -1188,7 +1246,8 @@ export async function drainRetirements(
       entry.state,
       entry.request_id,
       retirementDeviceIds(entry),
-      session,
+      entry.project,
+      entry.source,
     )
     if (sent) {
       retired.push(entry.request_id)
@@ -1241,7 +1300,6 @@ function updateOrphanQueue(
 export function orphanRetirements(
   env: NodeJS.ProcessEnv,
   entries: RetiringQuestion[],
-  session: string | undefined,
   now: number,
 ): void {
   if (entries.length === 0) return
@@ -1249,11 +1307,7 @@ export function orphanRetirements(
     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,
-      }))
+      .map((entry) => ({ ...entry, enqueued_at: now }))
     return [...queue, ...added].slice(-ORPHAN_QUEUE_CAP)
   })
 }
@@ -1291,7 +1345,8 @@ export async function drainOrphanRetirements(
       entry.state,
       entry.request_id,
       retirementDeviceIds(entry),
-      entry.session,
+      entry.project,
+      entry.source,
     )
     if (sent) {
       done.push(entry.request_id)
@@ -1315,6 +1370,21 @@ const LATE_PROMPT_POLL_SECONDS = 3
  */
 export const MAX_CONTINUATION_COUNT = 3
 
+/**
+ * How many turns an answer may be *held* before it is settled unread.
+ *
+ * A hold is not a delivery: the route reported that it handed nothing over, so
+ * the agent has not seen the answer and the wake-loop the continuation cap
+ * exists to stop has not happened. Counting holds against that cap meant three
+ * turns where a liveness probe could not reach a busy session were enough to
+ * discard an answer the user had already given.
+ *
+ * It still has to end. A route that can never deliver would otherwise retry
+ * every turn for the life of the session, so holds get their own, far looser
+ * bound — loose because each one costs nothing and the answer is still wanted.
+ */
+export const MAX_HELD_DELIVERIES = 20
+
 interface PendingPoll {
   /** The answer to act on: the latest reply, because a later one corrects. */
   reply: ReplyView | null
@@ -1355,6 +1425,8 @@ interface AnsweredPending {
   replies: ReplyView[]
   /** Immutable server snapshot for this request, known after a replies/close response. */
   agent_acknowledgement_required?: boolean | undefined
+  /** Whether that acknowledgement must carry text; the account's snapshot. */
+  agent_acknowledgement_text_required?: boolean | undefined
 }
 
 interface FinalizedPending {
@@ -1387,6 +1459,8 @@ function finalizedAnswer(finalized: FinalizedPending): AnsweredPending | null {
         replies,
         agent_acknowledgement_required:
           finalized.response?.agent_acknowledgement_required,
+        agent_acknowledgement_text_required:
+          finalized.response?.agent_acknowledgement_text_required,
       }
 }
 
@@ -1452,6 +1526,46 @@ function isSamePending(a: PendingQuestion, b: PendingQuestion): boolean {
   return a.question === b.question && a.asked_at === b.asked_at
 }
 
+/**
+ * The frozen draft itself will never be accepted. Replaying it forever hides a
+ * contract-skew (deleted fields, unexpected properties) as a recoverable wait.
+ * Auth, conflicts, and timeouts are not this class.
+ */
+function isTerminalDraftRejection(err: ApiCallError): boolean {
+  return err.status === 422 || (err.status === 400 && err.code === 'invalid_request')
+}
+
+function dropPendingQuestion(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  entry: PendingQuestion,
+): void {
+  updateSessionState(sessionId, env, (current) => {
+    const pending = pendingList(current).filter((candidate) => !isSamePending(candidate, entry))
+    const next: SessionState = { ...current }
+    if (pending.length > 0) next.pending = pending
+    else delete next.pending
+    return next
+  })
+}
+
+function clearFrozenSubmission(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  entry: PendingQuestion,
+): void {
+  updateSessionState(sessionId, env, (current) => {
+    const list = pendingList(current)
+    const index = list.findIndex((candidate) => isSamePending(candidate, entry))
+    if (index < 0) return current
+    const next = [...list]
+    const copy = { ...next[index]! }
+    delete copy.submission
+    next[index] = copy
+    return { ...current, pending: next }
+  })
+}
+
 /** The question set this pending record pushes, however it was registered. */
 function pendingQuestions(pending: PendingQuestion): QuestionT[] {
   return pending.questions ?? [{ id: 'q1', text: pending.question }]
@@ -1499,8 +1613,20 @@ function answerContext(answered: AnsweredPending): string {
  * tied to the question that asked it, with a truthful note about anything
  * still waiting.
  */
-function acknowledgementCommand(requestId: string): string {
-  return `notifai acknowledge ${requestId} --text <text>`
+function acknowledgementCommand(requestId: string, textRequired = true): string {
+  return textRequired
+    ? `notifai acknowledge ${requestId} --text <text>`
+    : `notifai acknowledge ${requestId}`
+}
+
+/**
+ * The acknowledgement is owed either way; only its text is conditional. So the
+ * instruction never says "you may skip this" — it says what to run.
+ */
+function acknowledgementDemand(textRequired: boolean): string {
+  return textRequired
+    ? ' with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient'
+    : ' exactly as shown; this account turned acknowledgement text off, so the receipt carries no words'
 }
 
 function acknowledgementContext(answered: AnsweredPending[]): string {
@@ -1512,20 +1638,23 @@ function acknowledgementContext(answered: AnsweredPending[]): string {
     return ' Agent Acknowledgement is not required for the answered request(s).'
   }
   if (due.length === 1) {
-    const requestId = due[0]!.pending.request_id!
+    const entry = due[0]!
+    const requestId = entry.pending.request_id!
+    const textRequired = entry.agent_acknowledgement_text_required !== false
     return (
       ` Agent Acknowledgement is required for request ${requestId}. Immediately, before doing the resumed work or ending this turn, run ` +
-      `\`${acknowledgementCommand(requestId)}\` with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient.`
+      `\`${acknowledgementCommand(requestId, textRequired)}\`${acknowledgementDemand(textRequired)}.`
     )
   }
+  const anyTextRequired = due.some((entry) => entry.agent_acknowledgement_text_required !== false)
   const commands = due
     .map((entry) => {
       const requestId = entry.pending.request_id!
-      return `- ${requestId}: \`${acknowledgementCommand(requestId)}\``
+      return `- ${requestId}: \`${acknowledgementCommand(requestId, entry.agent_acknowledgement_text_required !== false)}\``
     })
     .join('\n')
   return (
-    ` Agent Acknowledgement is required for ${due.length} requests. Immediately, before doing the resumed work or ending this turn, run every command below with non-empty text saying what concrete work you will do because of that reply; a bare acknowledgement is insufficient:\n` +
+    ` Agent Acknowledgement is required for ${due.length} requests. Immediately, before doing the resumed work or ending this turn, run every command below${acknowledgementDemand(anyTextRequired)}:\n` +
     commands
   )
 }
@@ -1588,7 +1717,11 @@ function stageAcceptedAnswers(
         requestId !== undefined &&
         !acknowledgementDue.some((entry) => entry.request_id === requestId)
       ) {
-        acknowledgementDue.push({ request_id: requestId, recorded_at: accepted.recorded_at })
+        acknowledgementDue.push({
+          request_id: requestId,
+          recorded_at: accepted.recorded_at,
+          text_required: answer.agent_acknowledgement_text_required !== false,
+        })
       }
     }
     const next: SessionState = {
@@ -1636,14 +1769,83 @@ export function clearAcknowledgementObligation(
 
 function acknowledgementBlockContext(due: readonly AcknowledgementDue[]): string {
   const commands = due
-    .map((entry) => `- ${entry.request_id}: \`${acknowledgementCommand(entry.request_id)}\``)
+    .map(
+      (entry) =>
+        `- ${entry.request_id}: \`${acknowledgementCommand(entry.request_id, entry.text_required !== false)}\``,
+    )
     .join('\n')
+  const anyTextRequired = due.some((entry) => entry.text_required !== false)
   return (
     `Notifai — required Agent Acknowledgement${due.length === 1 ? '' : 's'} still missing for request${due.length === 1 ? '' : 's'} ${due.map((entry) => entry.request_id).join(', ')}. ` +
-    `Before doing more resumed work or ending this turn, run ${due.length === 1 ? 'this command' : 'every command'} with non-empty text saying what concrete work you will do because of the reply; a bare acknowledgement is insufficient:\n${commands}`
+    `Before doing more resumed work or ending this turn, run ${due.length === 1 ? 'this command' : 'every command'}${acknowledgementDemand(anyTextRequired)}:\n${commands}`
   )
 }
 
+/**
+ * How many turns in a row a session may be held waiting for an acknowledgement.
+ *
+ * The gate is the one place hooks deliberately break the fail-open rule, and it
+ * had no bound at all: an agent that could not or would not acknowledge — or a
+ * server that stayed unreachable, since an error here counts as unresolved —
+ * held every turn of that session for ever. Blocking a user's agent
+ * indefinitely does not get them an acknowledgement; it costs them the agent as
+ * well as the acknowledgement.
+ */
+const MAX_ACKNOWLEDGEMENT_BLOCKS = 3
+
+/**
+ * Hold the turn for an outstanding acknowledgement, or give up and let it
+ * through once holding has stopped being worth its cost.
+ *
+ * Returns the outcome that blocks the turn, or `null` to carry on.
+ */
+function holdForAcknowledgement(
+  ctx: HookContext,
+  sessionId: string,
+  due: readonly AcknowledgementDue[],
+  notes: string[],
+): HookOutcome | null {
+  if (due.length === 0) return null
+  const requestIds = due.map((entry) => entry.request_id)
+  const blocks = (readSessionState(sessionId, ctx.env).acknowledgement_blocks ?? 0) + 1
+  if (blocks > MAX_ACKNOWLEDGEMENT_BLOCKS) {
+    // Drop the obligation with the reason recorded. The answer was already
+    // delivered; what is lost is the agent's receipt for it, and the log is
+    // where that loss stays visible.
+    for (const requestId of requestIds) clearAcknowledgementObligation(sessionId, ctx.env, requestId)
+    resetAcknowledgementBlocks(sessionId, ctx.env)
+    gate(ctx, 'proceeding', 'acknowledgement-abandoned', {
+      request_ids: requestIds,
+      blocks: blocks - 1,
+      limit: MAX_ACKNOWLEDGEMENT_BLOCKS,
+    })
+    notes.push(
+      `no acknowledgement after ${MAX_ACKNOWLEDGEMENT_BLOCKS} turns; continuing without one rather than holding this session for ever`,
+    )
+    return null
+  }
+  updateSessionState(sessionId, ctx.env, (current) => ({
+    ...current,
+    acknowledgement_blocks: blocks,
+  }))
+  gate(ctx, 'held', 'acknowledgement-required', { request_ids: requestIds, blocks })
+  return {
+    stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
+    notes,
+    log: { stage: 'acknowledgement-required', request_ids: requestIds },
+  }
+}
+
+/** A turn that was not held resets the streak; only consecutive holds count. */
+function resetAcknowledgementBlocks(sessionId: string, env: NodeJS.ProcessEnv): void {
+  updateSessionState(sessionId, env, (current) => {
+    if (current.acknowledgement_blocks === undefined) return current
+    const next = { ...current }
+    delete next.acknowledgement_blocks
+    return next
+  })
+}
+
 async function reconcileAcknowledgementObligations(
   ctx: HookContext,
   sessionId: string,
@@ -1803,6 +2005,9 @@ export async function handleUserPromptSubmit(
         agent_acknowledgement_required:
           response?.agent_acknowledgement_required ??
           entry.agent_acknowledgement_required,
+        agent_acknowledgement_text_required:
+          response?.agent_acknowledgement_text_required ??
+          entry.agent_acknowledgement_text_required,
       }
     })
     if (answered.length > 0) {
@@ -1841,6 +2046,16 @@ export async function handleUserPromptSubmit(
       ...(unasked.length > 0 ? { pending: unasked } : {}),
       ...(retiring.length > 0 ? { retiring } : {}),
       ...(current.accepted === undefined ? {} : { accepted: current.accepted }),
+      // Carried across a prompt on purpose. This rewrite rebuilds the state
+      // from named fields, so anything omitted is silently erased — and an
+      // erased obligation means the user never learns their reply was read,
+      // which is the one thing acknowledgement exists to guarantee.
+      ...(current.acknowledgement_due === undefined
+        ? {}
+        : { acknowledgement_due: current.acknowledgement_due }),
+      ...(current.acknowledgement_blocks === undefined
+        ? {}
+        : { acknowledgement_blocks: current.acknowledgement_blocks }),
       // 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
@@ -1865,7 +2080,7 @@ export async function handleUserPromptSubmit(
     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 retired = await drainRetirements(ctx, sessionId, ctx.env)
   const orphaned = await drainOrphanRetirements(ctx, ctx.env, ctx.now())
   const swept = [...retired, ...orphaned]
   if (swept.length > 0) {
@@ -1990,19 +2205,8 @@ export async function runEscalationWaiter(
           currentAcceptedIds.has(entry.request_id),
         ),
       )
-      if (due.length > 0) {
-        gate(ctx, 'held', 'acknowledgement-required', {
-          request_ids: due.map((entry) => entry.request_id),
-        })
-        return {
-          stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
-          notes,
-          log: {
-            stage: 'acknowledgement-required',
-            request_ids: due.map((entry) => entry.request_id),
-          },
-        }
-      }
+      const held = holdForAcknowledgement(ctx, sessionId, due, notes)
+      if (held !== null) return held
       state = readSessionState(sessionId, ctx.env)
     }
 
@@ -2012,26 +2216,16 @@ export async function runEscalationWaiter(
         sessionId,
         state.acknowledgement_due!,
       )
-      if (due.length > 0) {
-        gate(ctx, 'held', 'acknowledgement-required', {
-          request_ids: due.map((entry) => entry.request_id),
-        })
-        return {
-          stdout: stopAnswerOutput(acknowledgementBlockContext(due)),
-          notes,
-          log: {
-            stage: 'acknowledgement-required',
-            request_ids: due.map((entry) => entry.request_id),
-          },
-        }
-      }
+      const held = holdForAcknowledgement(ctx, sessionId, due, notes)
+      if (held !== null) return held
+      resetAcknowledgementBlocks(sessionId, ctx.env)
       state = readSessionState(sessionId, ctx.env)
     }
 
     const pending = pendingList(state)
     if (pending.length === 0) {
       const swept = [
-        ...(await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope))),
+        ...(await drainRetirements(ctx, sessionId, ctx.env)),
         ...(await drainOrphanRetirements(ctx, ctx.env, ctx.now())),
       ]
       if (swept.length > 0) {
@@ -2095,6 +2289,20 @@ async function deliverAcceptedAnswers(
 ): Promise<HookOutcome> {
   const { answers: answered, remaining } = accepted
   const requestIds = summarizeRequestIds(answered.map((entry) => entry.pending)).ids
+  const held = accepted.held_deliveries ?? 0
+  if (held >= MAX_HELD_DELIVERIES) {
+    gate(ctx, 'held', 'delivery-limit', {
+      route: route.kind,
+      held,
+      limit: MAX_HELD_DELIVERIES,
+      request_ids: requestIds,
+    })
+    settleAcceptedAnswers(ctx, sessionId, accepted)
+    notes.push(
+      `no route could hand the user's answer over in ${MAX_HELD_DELIVERIES} turns; not holding it any longer`,
+    )
+    return { notes }
+  }
   const attempt = (accepted.delivery_attempts ?? 0) + 1
   if (attempt > MAX_CONTINUATION_COUNT) {
     gate(ctx, 'held', 'delivery-limit', {
@@ -2145,6 +2353,17 @@ async function deliverAcceptedAnswers(
       delivered_at: ctx.now(),
       delivered_route: deliveredRoute,
     }))
+  } else if (delivered.acknowledgement === 'held') {
+    // Give the delivery attempt back and count the hold instead. The attempt
+    // was counted before the call because one that dies mid-delivery still
+    // happened and a counter written afterwards could be evaded by crashing —
+    // but a route that *returns* `held` proves both that this process survived
+    // and that nothing was handed over.
+    amendAcceptedAnswers(ctx, sessionId, (current) => ({
+      ...current,
+      delivery_attempts: accepted.delivery_attempts ?? 0,
+      held_deliveries: (current.held_deliveries ?? 0) + 1,
+    }))
   }
   ctx.log?.info('hook.answer', {
     answered: true,
@@ -2185,7 +2404,11 @@ async function handleClaimedStop(
   ) {
     for (const entry of live) await closeQuietly(ctx, entry.request_id!)
     await retirePendings(ctx, envelope, sessionId, pending, 'expired')
-    gate(ctx, 'held', 'no-question')
+    // Not `no-question`: there was a question, and this says so. Reading the
+    // log to find out why an ask never travelled is the whole reason these
+    // reasons exist, and the wrong one sent that reader looking for a question
+    // that was right there.
+    gate(ctx, 'held', 'harness-cannot-continue', { harness: ctx.harness })
     notes.push(`${HARNESS_CAPABILITIES[ctx.harness].deliveryContract}; use a blocking \`notifai send --reply\` question`)
     return { notes }
   }
@@ -2227,6 +2450,9 @@ async function handleClaimedStop(
         agent_acknowledgement_required:
           response?.agent_acknowledgement_required ??
           entry.agent_acknowledgement_required,
+        agent_acknowledgement_text_required:
+          response?.agent_acknowledgement_text_required ??
+          entry.agent_acknowledgement_text_required,
       }
       })
       const accepted = stageAcceptedAnswers(
@@ -2355,7 +2581,7 @@ async function escalate(
     await awaitTerminalFirstWindow(ctx, oldest, ceilingAt)
     ctx.log?.debug('hook.gate', {
       verdict: 'grace',
-      reason: 'elapsed',
+      reason: 'elapsed' satisfies GateReason,
       waited_from: oldest,
       grace_seconds: ctx.config.ask_grace_seconds.value,
     })
@@ -2364,35 +2590,42 @@ async function escalate(
   // 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) {
+    // How long the answer is accepted, and how long this owner listens for it,
+    // are two different spans. They used to be one: the window was whatever
+    // remained of the waiter's ceiling, so a question asked at a turn's end
+    // stopped being answerable about eight minutes later, whatever the user
+    // had configured.
+    //
+    // That was right when the waiter was the only way an answer came back. It
+    // is not any more: a late answer is found by the next turn's poll or
+    // replayed from the journal, so this owner giving up listening says
+    // nothing about whether the user's answer is still wanted.
+    const replyWindowSeconds = ctx.config.reply_window_seconds.value
+    if (ceilingAt - ctx.now() < MIN_REPLY_WINDOW_SECONDS * 1000) {
       notes.push(
-        'too little of the waiter ceiling is left for a reply window the server would accept; leaving this question in the terminal',
+        'too little of the waiter ceiling is left to submit and confirm this question; leaving it in the terminal',
       )
       continue
     }
+    // The owner still stops listening at its own ceiling. Only the span the
+    // server accepts answers into changed.
     const ownerDeadlineAt = ceilingAt
     const questions = pendingQuestions(entry)
     let intent = entry.submission
     if (intent === undefined) {
+      if (entry.body === undefined) {
+        notes.push('registered question has no canonical body; register it again with this CLI')
+        continue
+      }
       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,
+        // Type and Project have their own fields; the title is only substance.
+        title: questions[0]!.text,
+        body: entry.body,
         questions,
-        ...(entry.detail !== undefined ? { detail: entry.detail } : {}),
+        ...(entry.media !== undefined ? { media: entry.media } : {}),
+        ...(entry.project !== undefined ? { project: entry.project } : {}),
+        ...(entry.source !== undefined ? { source: entry.source } : {}),
         event: 'agent_question',
-        session: sessionLabel(ctx, envelope),
         windowSeconds: replyWindowSeconds,
         ownerDeadlineAt,
       })
@@ -2444,12 +2677,80 @@ async function escalate(
     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.
+    } catch (caught) {
+      let err: unknown = caught
+      if (err instanceof ApiCallError && isTerminalDraftRejection(err)) {
+        ctx.log?.error('hook.pushed', {
+          ok: false,
+          request_id: intent.request_id,
+          status: err.status,
+          code: err.code,
+          message: err.message,
+        })
+        if (entry.submission !== undefined) {
+          notes.push(
+            `question submission was rejected (${err.code}, HTTP ${err.status}); reminting the draft in the current contract instead of replaying the frozen one`,
+          )
+          clearFrozenSubmission(sessionId, ctx.env, entry)
+          if (entry.body === undefined) {
+            dropPendingQuestion(sessionId, ctx.env, entry)
+            notes.push('registered question has no canonical body; retired the frozen draft instead of retrying it')
+            continue
+          }
+          const reminted = await prepareQuestionSubmission(ctx, {
+            title: questions[0]!.text,
+            body: entry.body,
+            questions,
+            ...(entry.media !== undefined ? { media: entry.media } : {}),
+            ...(entry.project !== undefined ? { project: entry.project } : {}),
+            ...(entry.source !== undefined ? { source: entry.source } : {}),
+            event: 'agent_question',
+            windowSeconds: replyWindowSeconds,
+            ownerDeadlineAt,
+          })
+          if ('error' in reminted) {
+            dropPendingQuestion(sessionId, ctx.env, entry)
+            notes.push(reminted.error)
+            continue
+          }
+          intent = reminted
+          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: reminted }
+            return { ...current, pending: next }
+          })
+          try {
+            receipt = await submitQuestion(ctx, intent)
+            admissionConfirmed = true
+          } catch (retryErr) {
+            if (retryErr instanceof ApiCallError && isTerminalDraftRejection(retryErr)) {
+              dropPendingQuestion(sessionId, ctx.env, entry)
+              notes.push(
+                `reminted draft was also rejected (${retryErr.code}, HTTP ${retryErr.status}); retiring the question so it is not retried forever`,
+              )
+              ctx.log?.error('hook.pushed', {
+                ok: false,
+                request_id: intent.request_id,
+                status: retryErr.status,
+                code: retryErr.code,
+                message: retryErr.message,
+              })
+              continue
+            }
+            err = retryErr
+          }
+        } else {
+          dropPendingQuestion(sessionId, ctx.env, entry)
+          notes.push(
+            `question submission was rejected (${err.code}, HTTP ${err.status}); retiring it because the current draft will never be accepted`,
+          )
+          continue
+        }
+      }
+      if (!admissionConfirmed && err instanceof ApiCallError && err.status < 500 && err.status !== 408) {
         notes.push(
           `question submission was rejected (${err.code}, HTTP ${err.status}); preserving it for recovery`,
         )
@@ -2462,11 +2763,10 @@ async function escalate(
         })
         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) {
+        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', {
@@ -2486,16 +2786,21 @@ async function escalate(
       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,
-      ),
+      // When the server stops accepting an answer — not when this owner stops
+      // waiting for one. Those were the same number until the window became a
+      // setting, and taking the minimum silently capped every question at the
+      // waiter's ceiling: a question asked with a day-long window was swept as
+      // stale about eight minutes later and retired, so the answer given over
+      // lunch met a closed question.
+      //
+      // Both consumers of this field already clamp to the owner's own ceiling
+      // (`Math.min(hardDeadlineAt, …)` when deriving the ceiling, and
+      // `Math.min(ceilingAt, …)` when deriving the wait), so recording the
+      // real expiry here lengthens what the user gets without lengthening what
+      // this process waits.
+      reply_deadline_at: Number.isFinite(committedReplyDeadline)
+        ? committedReplyDeadline
+        : intent.owner_deadline_at,
     }
     delete live.submission
     submitted.push(live)
@@ -2583,10 +2888,37 @@ async function escalate(
   if (permanentFailure !== null) notes.push(permanentFailure)
 
   if (waited.byRequest.size === 0) {
-    // 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)
+    // This owner is done listening. That used to mean the question was over:
+    // it closed the window server-side and retired the record, on the reasoning
+    // that no later answer could reach the same agent turn.
+    //
+    // The reaching was never the point — the *accepting* is. A question whose
+    // window is still open is polled again by the next prompt and the next
+    // Stop, and an answer found there is journaled and replayed. Closing here
+    // capped every question at this owner's ceiling however long a window the
+    // user had configured, which is what made a day-long window mean eight
+    // minutes.
+    //
+    // So: finalize only what the server has genuinely stopped accepting, and
+    // leave the rest live for the turn that comes next. A session that truly
+    // ends still retires its questions — that is what the session-end hook is
+    // for, and it is the honest place for it.
+    const expired = waitingOn.filter(
+      (entry) =>
+        entry.reply_deadline_at === undefined ||
+        entry.reply_deadline_at <= ctx.now() ||
+        // A permanent rejection is the server saying this question can never be
+        // answered, whatever its window says. Leaving it open would strand a
+        // dead question on the user's devices.
+        waited.permanentFailures.has(entry.request_id!),
+    )
+    const stillAnswerable = waitingOn.filter((entry) => !expired.includes(entry))
+    if (stillAnswerable.length > 0) {
+      notes.push(
+        `${stillAnswerable.length} question${stillAnswerable.length === 1 ? ' is' : 's are'} still answerable; leaving ${stillAnswerable.length === 1 ? 'it' : 'them'} open for the next turn rather than closing ${stillAnswerable.length === 1 ? 'it' : 'them'} with this waiter`,
+      )
+    }
+    const finalized = await finalizePendings(ctx, expired)
     const finalAnswers = finalized
       .map(finalizedAnswer)
       .filter((entry): entry is AnsweredPending => entry !== null)
@@ -2648,6 +2980,8 @@ async function escalate(
       replies: authoritative,
       agent_acknowledgement_required:
         finalized.response?.agent_acknowledgement_required,
+      agent_acknowledgement_text_required:
+        finalized.response?.agent_acknowledgement_text_required,
     })
     if (finalized.response === null) {
       notes.push(
@@ -2704,8 +3038,7 @@ export function handleSessionEnd(
     }
   }
   if (orphans.length > 0) {
-    const label = env['NOTIFAI_SESSION']
-    orphanRetirements(env, orphans, label !== undefined && label !== '' ? label : sessionId, now)
+    orphanRetirements(env, orphans, now)
     notes.push(
       `queued ${orphans.length} question${orphans.length > 1 ? 's' : ''} for retirement on the next hook`,
     )
@@ -2744,13 +3077,23 @@ export function handleSessionEnd(
 // ---------------------------------------------------------------------------
 
 /**
- * More pending questions than this means an agent is looping, not asking.
- * Related questions belong in one `ask --form` (the wire carries up to four
- * questions per notification); four separate pushes is already a lot of lock
- * screen.
+ * Registrations still waiting for their first push. More than this in one turn
+ * means an agent is looping, not asking, and related questions belong in one
+ * `ask --form` instead.
+ *
+ * Deliberately counts only unasked entries. A question already on the user's
+ * devices is waiting on a person, not on the agent, and an answer stays
+ * accepted for a day — so counting live questions here would have turned a
+ * patient user into a reason the agent could no longer ask anything.
  */
 export const MAX_PENDING_QUESTIONS = 4
 
+/**
+ * Everything this session has open at once, asked or not. The lock screen is
+ * the shared resource being protected here, not the agent's turn.
+ */
+export const MAX_LIVE_QUESTIONS = 10
+
 /**
  * A session may hold several registered questions at once: a new `ask` never
  * ends an earlier one. Each reaches the user as its own notification and is
@@ -2769,11 +3112,16 @@ export function registerQuestion(
   question: PendingQuestion,
   now: number = Date.now(),
 ): void {
-  let full = false
+  let full: 'unasked' | 'live' | null = null
   updateSessionState(sessionId, env, (state) => {
     const pending = pendingList(state)
-    if (pending.length >= MAX_PENDING_QUESTIONS) {
-      full = true
+    const unasked = pending.filter((entry) => entry.request_id === undefined)
+    if (unasked.length >= MAX_PENDING_QUESTIONS) {
+      full = 'unasked'
+      return state
+    }
+    if (pending.length >= MAX_LIVE_QUESTIONS) {
+      full = 'live'
       return state
     }
     return {
@@ -2789,12 +3137,18 @@ export function registerQuestion(
       ],
     }
   })
-  if (full) {
+  if (full === 'unasked') {
     throw new Error(
       `${MAX_PENDING_QUESTIONS} questions are already waiting to be asked. ` +
         'Combine related questions into one `notifai ask --form` instead of registering more.',
     )
   }
+  if (full === 'live') {
+    throw new Error(
+      `${MAX_LIVE_QUESTIONS} questions from this session are already open. ` +
+        'Retire the ones you no longer need with `notifai close <request_id>` before asking another.',
+    )
+  }
 }
 
 /** Parses hook JSON from stdin, tolerating an empty or malformed body. */