@raidiant/notifai 3.0.1 → 5.0.0

package/src/hooks.test.ts

@@ -14,11 +14,12 @@ import {
 import os from 'node:os'
 import path from 'node:path'
 import { PassThrough } from 'node:stream'
-import type {
-  ListRepliesResponse,
-  ReplyView,
-  SubmissionReceipt,
-  SubmitNotificationRequestT,
+import {
+  sessionLabelFromId,
+  type ListRepliesResponse,
+  type ReplyView,
+  type SubmissionReceipt,
+  type SubmitNotificationRequestT,
 } from '@raidiant/notifai-protocol'
 import { describe, expect, it, vi } from 'vitest'
 import { ApiCallError, type ApiClient } from './client.js'
@@ -48,16 +49,60 @@ import {
   drainOrphanRetirements,
   runEscalationWaiter,
   MAX_CONTINUATION_COUNT,
+  MAX_HELD_DELIVERIES,
   orphanRetirements,
   pruneAbandonedSessions,
   releaseQuestionPush,
   readMatchingProjectSessionPointer,
   readProjectSession,
   readSessionState,
-  registerQuestion,
+  registerQuestion as persistQuestion,
   writeProjectSession,
-  writeSessionState,
+  writeSessionState as persistSessionState,
+  type PendingQuestion,
+  type SessionState,
+  waiterCeilingSeconds,
+  WAITER_CEILING_SECONDS,
+  DETACHED_WAITER_CEILING_SECONDS,
 } from './hooks.js'
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol'
+import {
+  BLOCKING_STOP_TIMEOUT_SECONDS,
+  CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS,
+} from './install-hooks.js'
+
+/** New-format test fixtures always carry the canonical body explicitly. */
+function registerQuestion(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  question: PendingQuestion,
+  now?: number,
+): void {
+  persistQuestion(
+    sessionId,
+    env,
+    { ...question, body: question.body ?? question.question },
+    now,
+  )
+}
+
+function writeSessionState(
+  sessionId: string,
+  env: NodeJS.ProcessEnv,
+  state: SessionState,
+): void {
+  persistSessionState(sessionId, env, {
+    ...state,
+    ...(state.pending === undefined
+      ? {}
+      : {
+          pending: state.pending.map((entry) => ({
+            ...entry,
+            body: entry.body ?? entry.question,
+          })),
+        }),
+  })
+}
 
 class CapturedIo implements CommandIo {
   outLines: string[] = []
@@ -90,6 +135,10 @@ interface Recorder {
   /** Per-request answer stream for multi-question ownership tests. */
   repliesFor?: (requestId: string) => ReplyView[]
   acknowledgementRequiredFor?: (requestId: string) => boolean
+  /** The window the server commits to, when a test needs one unlike the waiter's. */
+  replyExpiresAt?: string
+  /** Whether that request's acknowledgement must carry text; default true. */
+  acknowledgementTextRequiredFor?: (requestId: string) => boolean
   acknowledged?: Set<string>
   acknowledgementChecks?: string[]
 }
@@ -140,7 +189,7 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
       return {
         status: 'recorded',
         agent_acknowledgement: {
-          text: body.text,
+          text: body.text ?? '',
           created_at: new Date(NOW).toISOString(),
         },
       }
@@ -152,6 +201,8 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
       return {
         request_id: requestId,
         agent_acknowledgement_required: required,
+        agent_acknowledgement_text_required:
+          recorder.acknowledgementTextRequiredFor?.(requestId) ?? true,
         agent_acknowledgement: recorder.acknowledged?.has(requestId)
           ? { text: 'I will continue.', created_at: new Date(NOW).toISOString() }
           : null,
@@ -171,9 +222,11 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
       recorder.receipts.push(requestId)
       return {
         request_id: requestId,
-        reply_expires_at: new Date(NOW + 480_000).toISOString(),
+        reply_expires_at: recorder.replyExpiresAt ?? new Date(NOW + 480_000).toISOString(),
         agent_acknowledgement_required:
           recorder.acknowledgementRequiredFor?.(requestId) ?? true,
+        agent_acknowledgement_text_required:
+          recorder.acknowledgementTextRequiredFor?.(requestId) ?? true,
         replayed: false,
         overall: 'provider_accepted_all',
         deliveries: [],
@@ -187,6 +240,8 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
         reply_expires_at: null,
         agent_acknowledgement_required:
           recorder.acknowledgementRequiredFor?.(requestId) ?? true,
+        agent_acknowledgement_text_required:
+          recorder.acknowledgementTextRequiredFor?.(requestId) ?? true,
         agent_acknowledgement: recorder.acknowledged?.has(requestId)
           ? { text: 'I will continue.', created_at: new Date(NOW).toISOString() }
           : null,
@@ -200,6 +255,8 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
         reply_expires_at: new Date(NOW).toISOString(),
         agent_acknowledgement_required:
           recorder.acknowledgementRequiredFor?.(requestId) ?? true,
+        agent_acknowledgement_text_required:
+          recorder.acknowledgementTextRequiredFor?.(requestId) ?? true,
         agent_acknowledgement: recorder.acknowledged?.has(requestId)
           ? { text: 'I will continue.', created_at: new Date(NOW).toISOString() }
           : null,
@@ -415,6 +472,27 @@ function writeGlobalConfig(h: Harness, toml: string): void {
 /** Long enough ago that no test is accidentally sensitive to the stamp. */
 const AWAY = NOW - 600_000
 
+describe('the waiter wall clock', () => {
+  it('spends a held turn sparingly and a detached one generously', () => {
+    // A held turn is somebody's terminal, so the short ceiling is the cost of
+    // waiting. Detached, nothing is held, and the same number only shortens how
+    // long a direct wake stays possible.
+    expect(waiterCeilingSeconds(false)).toBe(WAITER_CEILING_SECONDS)
+    expect(waiterCeilingSeconds(true)).toBe(DETACHED_WAITER_CEILING_SECONDS)
+    expect(DETACHED_WAITER_CEILING_SECONDS).toBeGreaterThan(WAITER_CEILING_SECONDS)
+  })
+
+  it('stays under the timeout the async Stop handler declares', () => {
+    // That declaration's kill is silent: past it the waiter vanishes and the
+    // answer the user already gave is never delivered.
+    expect(DETACHED_WAITER_CEILING_SECONDS).toBeLessThan(CLAUDE_ASYNC_STOP_TIMEOUT_SECONDS)
+  })
+
+  it('leaves the blocking host headroom above the waiter it declares for', () => {
+    expect(BLOCKING_STOP_TIMEOUT_SECONDS).toBeGreaterThan(WAITER_CEILING_SECONDS)
+  })
+})
+
 describe('pushing a registered question', () => {
   // Found by a live Claude Code session: a spawned agent always has a
   // just-set last_prompt_at, and the routing gate once read that as the user
@@ -432,16 +510,39 @@ describe('pushing a registered question', () => {
       device_ids: ['dev_iphone', 'dev_mac'],
     })
     expect(h.recorder.submitted[0]?.draft.presentation).toMatchObject({
-      title: 'Question',
+      title: 'Ship it?',
       body: 'Ship it?',
     })
-    expect(h.recorder.submitted[0]?.draft.platform).toEqual({
-      ios: { sound: 'attention', interruption_level: 'active' },
-      macos: { sound: 'attention', interruption_level: 'active' },
-    })
+    // A pushed question is a question, and a question has an attention tone.
+    expect(h.recorder.submitted[0]?.draft.platform?.ios?.sound).toBe('attention')
   })
 
-  it('names the resolved project in the pushed question title', async () => {
+  it('keeps sparse alt text paired with its original media item', async () => {
+    const h = harness([reply({ text: 'Yes' })])
+    writeSessionState('media-order', h.env, { last_prompt_at: AWAY })
+    registerQuestion(
+      'media-order',
+      h.env,
+      {
+        question: 'Which image should ship?',
+        body: 'Compare ![the second image](media:med_second).',
+        media: [
+          { media_id: 'med_first' },
+          { media_id: 'med_second', alt: 'Second image' },
+        ],
+      },
+      NOW,
+    )
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'media-order' }))
+
+    expect(h.recorder.submitted[0]?.draft.presentation.media).toEqual([
+      { media_id: 'med_first' },
+      { media_id: 'med_second', alt: 'Second image' },
+    ])
+  })
+
+  it('keeps Project identity out of the substantive question title', async () => {
     const h = harness([reply({ text: 'Yes' })])
     const projectDir = path.join(h.deps.cwd, '.notifai')
     mkdirSync(projectDir, { recursive: true })
@@ -450,11 +551,17 @@ describe('pushing a registered question', () => {
       'project = "notifai-cli"\nask_grace_seconds = 0\n',
     )
     writeSessionState('project-title', h.env, { last_prompt_at: AWAY })
-    registerQuestion('project-title', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'project-title',
+      h.env,
+      { question: 'Ship it?', project: 'notifai-cli' },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'project-title', cwd: h.deps.cwd }))
 
-    expect(h.recorder.submitted[0]?.draft.presentation.title).toBe('Question · notifai-cli')
+    expect(h.recorder.submitted[0]?.draft.presentation.title).toBe('Ship it?')
+    expect(h.recorder.submitted[0]?.draft.project).toBe('notifai-cli')
   })
 })
 
@@ -981,6 +1088,12 @@ describe('late answer collection', () => {
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'late-prompt' }))
     expect(JSON.parse(h.io.outLines.at(-1) ?? '{}').reason).toContain('Hold')
+    // The obligation survives the user typing — that is the whole point of
+    // recording it — so the turn after the answer is held for it. Satisfy it
+    // the way the agent would, then the retirement proceeds.
+    expect(readSessionState('late-prompt', h.env).acknowledgement_due).toHaveLength(1)
+    h.recorder.acknowledged = new Set(['req_live'])
+
     await hookRunCommand(
       h.deps,
       'stop',
@@ -1152,10 +1265,66 @@ describe('the waiter owning one question to the end', () => {
     expect(h.recorder.submitted[0]).toEqual(firstAttempt)
   })
 
-  it('preserves and exactly replays an intent after a definitive submit rejection', async () => {
+  it('remints a frozen draft after a terminal 422 instead of replaying it', async () => {
+    const h = harness([])
+    const factory = h.deps.clientFactory
+    h.deps.clientFactory = () => {
+      const client = factory!()
+      return {
+        ...client,
+        submit: async () => {
+          throw new ApiCallError(401, 'unauthorized', 'Sign in again.')
+        },
+      } as ApiClient
+    }
+    writeSessionState('rejected-submit', h.env, { last_prompt_at: AWAY })
+    registerQuestion('rejected-submit', h.env, { question: 'Deploy?' }, NOW)
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-submit' }))
+    const frozen = readSessionState('rejected-submit', h.env).pending?.[0]?.submission
+    if (frozen === undefined) throw new Error('expected a persisted submission intent')
+
+    let submits = 0
+    h.deps.clientFactory = () => {
+      const client = factory!()
+      return {
+        ...client,
+        submit: async (body: SubmitNotificationRequestT, waitSeconds: number) => {
+          submits += 1
+          if (body.request_id === frozen.request_id) {
+            throw new ApiCallError(422, 'invalid_request', 'The draft was rejected.', null, [
+              { path: 'presentation.detail', message: 'Unexpected property' },
+            ])
+          }
+          return client.submit(body, waitSeconds)
+        },
+      } as ApiClient
+    }
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-submit' }))
+
+    expect(submits).toBe(2)
+    expect(h.recorder.submitted[0]?.request_id).toBeDefined()
+    expect(h.recorder.submitted[0]?.request_id).not.toBe(frozen.request_id)
+    expect(h.io.errLines.join('\n')).toContain('reminting the draft')
+    expect(readSessionState('rejected-submit', h.env).pending).toBeUndefined()
+  })
+
+  it('retires a reminted draft that the server still rejects', async () => {
     const h = harness([])
     const factory = h.deps.clientFactory
-    let polls = 0
+    h.deps.clientFactory = () => {
+      const client = factory!()
+      return {
+        ...client,
+        submit: async () => {
+          throw new ApiCallError(401, 'unauthorized', 'Sign in again.')
+        },
+      } as ApiClient
+    }
+    writeSessionState('rejected-forever', h.env, { last_prompt_at: AWAY })
+    registerQuestion('rejected-forever', h.env, { question: 'Deploy?' }, NOW)
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-forever' }))
+    expect(readSessionState('rejected-forever', h.env).pending?.[0]?.submission).toBeDefined()
+
     h.deps.clientFactory = () => {
       const client = factory!()
       return {
@@ -1163,29 +1332,72 @@ describe('the waiter owning one question to the end', () => {
         submit: async () => {
           throw new ApiCallError(422, 'invalid_request', 'The draft was rejected.')
         },
+      } as ApiClient
+    }
+    h.advanceClock(600_000)
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-forever' }))
+    expect(readSessionState('rejected-forever', h.env).pending).toBeUndefined()
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-forever' }))
+    expect(h.recorder.submitted).toEqual([])
+    expect(h.io.errLines.join('\n')).toContain('retiring the question so it is not retried forever')
+  })
+
+  it('retires a freshly minted draft the current contract rejects', async () => {
+    const h = harness([])
+    const factory = h.deps.clientFactory
+    h.deps.clientFactory = () => {
+      const client = factory!()
+      return {
+        ...client,
+        submit: async () => {
+          throw new ApiCallError(422, 'invalid_request', 'The draft was rejected.')
+        },
+      } as ApiClient
+    }
+    writeSessionState('fresh-422', h.env, { last_prompt_at: AWAY })
+    registerQuestion('fresh-422', h.env, { question: 'Deploy?' }, NOW)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'fresh-422' }))
+
+    expect(readSessionState('fresh-422', h.env).pending).toBeUndefined()
+    expect(h.io.errLines.join('\n')).toContain('retiring it because the current draft will never be accepted')
+  })
+
+  it('preserves a frozen intent after a retryable client rejection', async () => {
+    const h = harness([])
+    const factory = h.deps.clientFactory
+    let polls = 0
+    h.deps.clientFactory = () => {
+      const client = factory!()
+      return {
+        ...client,
+        submit: async () => {
+          throw new ApiCallError(401, 'unauthorized', 'Sign in again.')
+        },
         replies: async () => {
           polls += 1
           throw new Error('must not poll an unaccepted request')
         },
       } as ApiClient
     }
-    writeSessionState('rejected-submit', h.env, { last_prompt_at: AWAY })
-    registerQuestion('rejected-submit', h.env, { question: 'Deploy?' }, NOW)
+    writeSessionState('auth-submit', h.env, { last_prompt_at: AWAY })
+    registerQuestion('auth-submit', h.env, { question: 'Deploy?' }, NOW)
 
-    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-submit' }))
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'auth-submit' }))
 
-    const pending = readSessionState('rejected-submit', h.env).pending?.[0]
+    const pending = readSessionState('auth-submit', h.env).pending?.[0]
     expect(pending?.request_id).toBeUndefined()
     expect(pending?.submission?.request_id).toMatch(/^req_[A-Za-z0-9_-]{22,24}$/)
     expect(polls).toBe(0)
-    expect(h.io.errLines.join('\n')).toContain('submission was rejected')
+    expect(h.io.errLines.join('\n')).toContain('preserving it for recovery')
 
     const frozen = pending?.submission
     if (frozen === undefined) throw new Error('expected a persisted submission intent')
     writeGlobalConfig(h, 'project = "changed-after-crash"\n')
     h.advanceClock(600_000)
     h.deps.clientFactory = factory
-    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'rejected-submit' }))
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'auth-submit' }))
 
     expect(h.recorder.submitted[0]).toEqual({
       request_id: frozen.request_id,
@@ -1220,7 +1432,7 @@ describe('the waiter owning one question to the end', () => {
     expect(h.io.errLines.join('\n')).toContain('expired with its continuation owner')
   })
 
-  it('charges sequential submission latency to one deadline', async () => {
+  it('charges sequential submission latency to one owner deadline, not to the answer window', async () => {
     const h = harness([reply({ text: 'Done' })])
     writeSessionState('latency', h.env, { last_prompt_at: AWAY })
     registerQuestion('latency', h.env, { question: 'First?' }, NOW)
@@ -1232,9 +1444,12 @@ describe('the waiter owning one question to the end', () => {
     const windows = h.recorder.submitted
       .filter((entry) => entry.draft.event === 'agent_question')
       .map((entry) => entry.draft.reply?.expires_in_seconds)
-    // Both windows end at the same absolute moment: the second question's is
-    // shorter by exactly the 40s the first submission spent.
-    expect(windows).toEqual([480, 440])
+    // How long the user may answer does not shrink because this owner spent
+    // part of its own budget getting the question out. Both questions stay
+    // answerable for the configured window.
+    expect(windows).toEqual([86_400, 86_400])
+    // The owner's own budget is still one shared deadline, and it is still
+    // charged for the latency: the whole pass fits inside the waiter ceiling.
     expect(h.deps.now?.()).toBeLessThanOrEqual(NOW + 480_000)
   })
 
@@ -1699,7 +1914,7 @@ describe('several questions in flight', () => {
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-required' }))
     expect(readSessionState('ack-required', h.env).acknowledgement_due).toEqual([
-      { request_id: 'req_ack_required', recorded_at: NOW },
+      { request_id: 'req_ack_required', recorded_at: NOW, text_required: true },
     ])
 
     h.io.outLines = []
@@ -1719,6 +1934,66 @@ describe('several questions in flight', () => {
     expect(readSessionState('ack-required', h.env).accepted).toBeUndefined()
   })
 
+  it('still blocks Stop, without asking for text, when the account turned text off', async () => {
+    const h = harness([reply({ text: 'Ship it' })])
+    h.recorder.acknowledgementTextRequiredFor = () => false
+    writeSessionState('ack-textless', h.env, {
+      pending: [
+        {
+          question: 'Ship it?',
+          request_id: 'req_ack_textless',
+          collapse_key: 'collapse-ack-textless',
+          device_ids: ['dev_iphone'],
+          reply_deadline_at: NOW + 60_000,
+        },
+      ],
+    })
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-textless' }))
+    // The obligation is unchanged by the preference: the acknowledgement still
+    // has to happen, because the user's read-state depends on it.
+    expect(readSessionState('ack-textless', h.env).acknowledgement_due).toEqual([
+      { request_id: 'req_ack_textless', recorded_at: NOW, text_required: false },
+    ])
+
+    h.io.outLines = []
+    await hookRunCommand(
+      h.deps,
+      'stop',
+      stdin({ session_id: 'ack-textless', stop_hook_active: true }),
+    )
+
+    const blocked = JSON.parse(h.io.outLines[0] ?? '{}') as { decision?: string; reason?: string }
+    expect(blocked.decision).toBe('block')
+    expect(blocked.reason).toContain('notifai acknowledge req_ack_textless`')
+    expect(blocked.reason).not.toContain('--text')
+  })
+
+  it('gives up holding the turn rather than wedging the session for ever', async () => {
+    // The acknowledgement gate is the one place hooks break the fail-open rule.
+    // Unbounded, an agent that never acknowledges — or a server that stays
+    // unreachable, since an error counts as unresolved — held every turn of
+    // this session for good.
+    const h = harness([])
+    writeSessionState('ack-wedge', h.env, {
+      acknowledgement_due: [{ request_id: 'req_wedge', recorded_at: NOW }],
+    })
+
+    const blocked: unknown[] = []
+    for (let turn = 0; turn < 3; turn += 1) {
+      h.io.outLines.length = 0
+      await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-wedge' }))
+      blocked.push(h.io.outLines.length > 0)
+    }
+    expect(blocked).toEqual([true, true, true])
+
+    // The fourth turn is let through, and the obligation stops being owed.
+    h.io.outLines.length = 0
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'ack-wedge' }))
+    expect(h.io.outLines).toEqual([])
+    expect(readSessionState('ack-wedge', h.env).acknowledgement_due).toBeUndefined()
+  })
+
   it('reconciles a server-recorded Agent Acknowledgement after a local clearing crash', async () => {
     const h = harness([])
     writeSessionState('ack-heal', h.env, {
@@ -1889,7 +2164,7 @@ describe('a question that outlives its session', () => {
     expect(retirements(h).filter((r) => r.retires === first)).toHaveLength(count)
   })
 
-  it('gives up on an orphan older than a day instead of queueing it for ever', async () => {
+  it('gives up on an orphan that outlived the longest answerable window', async () => {
     const h = harness([])
     orphanRetirements(
       h.env,
@@ -1900,8 +2175,7 @@ describe('a question that outlives its session', () => {
         question: 'Old?',
         state: 'expired',
       }],
-      undefined,
-      NOW - 25 * 3600 * 1000,
+      NOW - (REPLY_MAX_WINDOW_SECONDS + 2 * 3600) * 1000,
     )
     const drained = await drainOrphanRetirements(
       { client: h.deps.clientFactory('https://test.notifai.invalid', 'Bearer x'), config: loadConfig({ cwd: h.deps.cwd, env: h.env }) },
@@ -1962,7 +2236,7 @@ describe('ask registration', () => {
     const h = harness()
     // Inside a hook, a rejection is only a stderr note the agent never reads —
     // so it would look registered and then silently never ask.
-    expect(askCommand(h.deps, 'Ship it?', { choice: ['Only one'], session: 'a1' })).toBe(EXIT.usage)
+    expect(askCommand(h.deps, 'Ship it?', { choice: ['Only one'], sessionId: 'a1' })).toBe(EXIT.usage)
     expect(readSessionState('a1', h.env).pending).toBeUndefined()
   })
 
@@ -1993,7 +2267,7 @@ describe('ask registration', () => {
             { text: 'Deploy where?', choices: ['Staging', 'Production'], multi: true },
             { text: 'Anything to watch?' },
           ],
-          detail: '## Context\nThe long story.',
+          body: '## Context\nThe long story.',
         }) },
       undefined,
     )
@@ -2002,18 +2276,18 @@ describe('ask registration', () => {
     registerQuestion('form1', h.env, {
       question: built.questions[0]!.text,
       questions: built.questions,
-      ...(built.detail === undefined ? {} : { detail: built.detail }),
+      body: built.body,
     })
     const pending = readSessionState('form1', h.env).pending?.[0]
     expect(pending?.questions).toHaveLength(2)
-    expect(pending?.detail).toContain('long story')
+    expect(pending?.body).toContain('long story')
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'form1' }))
     const draft = h.recorder.submitted[0]?.draft
-    // The banner leads with the first question and admits the rest exists;
-    // the full set rides the payload for the answering card.
-    expect(draft?.presentation.body).toBe('Deploy where? (+1 more)')
-    expect(draft?.presentation.detail).toContain('long story')
+    expect(draft?.presentation.title).toBe('Deploy where?')
+    expect(draft?.presentation.body).toBe(
+      '1. Deploy where?\n2. Anything to watch?\n\n## Context\nThe long story.',
+    )
     expect(draft?.reply?.questions).toEqual([
       {
         id: 'deploy-where',
@@ -2108,7 +2382,7 @@ describe('ask registration', () => {
 
   it('does not let an explicit session bypass exact active-harness proof', () => {
     const h = harness()
-    expect(askCommand(h.deps, 'Ship it?', { session: 'guessed' })).toBe(EXIT.usage)
+    expect(askCommand(h.deps, 'Ship it?', { sessionId: 'guessed' })).toBe(EXIT.usage)
     expect(readSessionState('guessed', h.env).pending).toBeUndefined()
   })
 
@@ -2529,21 +2803,46 @@ describe('malformed input', () => {
 })
 
 describe('telling concurrent agents apart', () => {
-  it('stamps the harness session on the question it pushes', async () => {
-    // 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.
+  it('stamps structured Source Context on the question it pushes', async () => {
     const h = harness([])
-    registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'sess-abc',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'sess-abc',
+          session_label: sessionLabelFromId('sess-abc'),
+          harness: 'claude-code',
+        },
+      },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
 
-    expect(h.recorder.submitted[0]?.draft.session).toBe('sess-abc')
+    expect(h.recorder.submitted[0]?.draft.source).toEqual({
+      session_id: 'sess-abc',
+      session_label: sessionLabelFromId('sess-abc'),
+      harness: 'claude-code',
+    })
   })
 
   it('stamps the retirement too, so it lands on the right agent’s notification', async () => {
     const h = harness([reply({ text: 'Yes' })])
-    registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'sess-abc',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'sess-abc',
+          session_label: sessionLabelFromId('sess-abc'),
+          harness: 'claude-code',
+        },
+      },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
     h.recorder.acknowledged ??= new Set()
@@ -2555,17 +2854,35 @@ describe('telling concurrent agents apart', () => {
     )
 
     const retirement = h.recorder.submitted.find((s) => s.draft.event === 'question_retired')
-    expect(retirement?.draft.session).toBe('sess-abc')
+    expect(retirement?.draft.source).toEqual({
+      session_id: 'sess-abc',
+      session_label: sessionLabelFromId('sess-abc'),
+      harness: 'claude-code',
+    })
   })
 
-  it('prefers a name the user chose over the harness UUID', async () => {
+  it('preserves a human session label without displaying the opaque id', async () => {
     const h = harness([])
-    h.env['NOTIFAI_SESSION'] = 'migration-worktree'
-    registerQuestion('sess-abc', h.env, { question: 'Ship it?' }, NOW)
+    registerQuestion(
+      'sess-abc',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'sess-abc',
+          session_label: 'Migration Worktree',
+          harness: 'claude-code',
+        },
+      },
+      NOW,
+    )
 
     await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'sess-abc' }))
 
-    expect(h.recorder.submitted[0]?.draft.session).toBe('migration-worktree')
+    const draft = h.recorder.submitted[0]?.draft
+    expect(draft?.source?.session_label).toBe('Migration Worktree')
+    expect(draft?.presentation.title).not.toContain('sess-abc')
+    expect(draft?.presentation.body).not.toContain('sess-abc')
   })
 })
 
@@ -2713,7 +3030,6 @@ describe('durable state writes', () => {
             state: 'expired',
           },
         ],
-        'linked-pointer',
         NOW,
       ),
     ).toThrow(/symlink/)
@@ -3456,6 +3772,47 @@ describe('escalation waiter delivery seam', () => {
     expect(readSessionState('waiter-once', h.env).accepted).toBeUndefined()
   })
 
+  it('does not spend the delivery cap on turns where nothing was handed over', async () => {
+    // The bug: holds counted against MAX_CONTINUATION_COUNT, so three turns
+    // where a liveness probe could not reach a busy session were enough to
+    // settle an answer the user had already given, unread.
+    const h = harness([])
+    const sessionId = 'waiter-transient-holds'
+    journaled(h, sessionId)
+    const context = waiterContext(h)
+    let handedOver = 0
+    let pass = 0
+
+    for (; pass < MAX_CONTINUATION_COUNT + 2; pass += 1) {
+      await runEscalationWaiter(context, {
+        sessionId,
+        envelope: { session_id: sessionId, stop_hook_active: false },
+        route: {
+          kind: 'inbox-socket',
+          deliver: async () => ({ notes: [], acknowledgement: 'held' as const }),
+        },
+        processDeadlineAt: NOW + 480_000,
+      })
+    }
+    // Still journaled after more holds than the delivery cap allows.
+    expect(readSessionState(sessionId, h.env).accepted).toBeDefined()
+
+    // And when a route can finally take it, it is delivered rather than lost.
+    await runEscalationWaiter(context, {
+      sessionId,
+      envelope: { session_id: sessionId, stop_hook_active: false },
+      route: {
+        kind: 'inbox-socket',
+        deliver: async () => {
+          handedOver += 1
+          return { notes: [], acknowledgement: 'delivered' as const }
+        },
+      },
+      processDeadlineAt: NOW + 480_000,
+    })
+    expect(handedOver).toBe(1)
+  })
+
   it('bounds deliveries by the continuation cap on every route', async () => {
     // A route that never acknowledges must still stop. The cap lives where all
     // routes pass, so no future route can be the one it does not cover.
@@ -3467,7 +3824,7 @@ describe('escalation waiter delivery seam', () => {
       let deliveries = 0
       const notes: string[] = []
 
-      for (let pass = 0; pass < MAX_CONTINUATION_COUNT + 3; pass += 1) {
+      for (let pass = 0; pass < MAX_HELD_DELIVERIES + 3; pass += 1) {
         const outcome = await runEscalationWaiter(context, {
           sessionId,
           envelope: { session_id: sessionId, stop_hook_active: false },
@@ -3483,9 +3840,11 @@ describe('escalation waiter delivery seam', () => {
         notes.push(...outcome.notes)
       }
 
-      expect(deliveries).toBe(MAX_CONTINUATION_COUNT)
+      // A hold is not a delivery — nothing was handed over — so it does not
+      // spend the wake-loop cap. It still has to end, on its own looser bound.
+      expect(deliveries).toBe(MAX_HELD_DELIVERIES)
       expect(notes.join('\n')).toContain(
-        `${MAX_CONTINUATION_COUNT} times without being acknowledged`,
+        `could hand the user's answer over in ${MAX_HELD_DELIVERIES} turns`,
       )
       expect(readSessionState(sessionId, h.env).accepted).toBeUndefined()
     }
@@ -3519,3 +3878,86 @@ describe('escalation waiter delivery seam', () => {
     releaseQuestionPush('waiter-failed-route', h.env)
   })
 })
+
+
+describe('session state across a prompt', () => {
+  it('carries every kind of session state across a typed prompt', async () => {
+    // The prompt handler rebuilds state from named fields, so a field nobody
+    // remembered to name is erased by the user typing. That is how an
+    // acknowledgement obligation once vanished. This fails if a future field is
+    // added to SessionState and not carried across.
+    const h = harness([])
+    const before = {
+      last_prompt_at: AWAY,
+      last_stop_at: NOW - 1_000,
+      retiring: [
+        {
+          request_id: 'req_carry',
+          collapse_key: 'collapse-carry',
+          device_ids: ['dev_iphone'],
+          question: 'Carried?',
+          state: 'expired' as const,
+        },
+      ],
+      continuation: { answered_at: NOW - 2_000, count: 2 },
+      acknowledgement_due: [{ request_id: 'req_carry_ack', recorded_at: NOW }],
+      acknowledgement_blocks: 2,
+    }
+    writeSessionState('carry-all', h.env, before)
+
+    await hookRunCommand(
+      h.deps,
+      'user-prompt-submit',
+      stdin({ session_id: 'carry-all', cwd: h.deps.cwd }),
+    )
+
+    const after = readSessionState('carry-all', h.env)
+    for (const key of Object.keys(before) as (keyof typeof before)[]) {
+      expect(after[key], `${key} did not survive the prompt`).toBeDefined()
+    }
+    // The one field a prompt resets rather than carries.
+    expect(after.continuation?.count).toBe(0)
+    expect(after.acknowledgement_blocks).toBe(2)
+  })
+})
+
+describe('a question outliving the waiter that pushed it', () => {
+  it('records when the server stops accepting, not when this owner stops waiting', async () => {
+    // These were the same number until the window became a setting, and taking
+    // the minimum capped every question at the waiter's ceiling: a day-long
+    // window was swept as stale about eight minutes later and retired, so the
+    // answer given over lunch met a closed question.
+    const h = harness([])
+    const aDayOut = NOW + 86_400_000
+    h.recorder.replyExpiresAt = new Date(aDayOut).toISOString()
+    writeSessionState('outlive', h.env, { last_prompt_at: AWAY })
+    registerQuestion('outlive', h.env, { question: 'Ship it?' }, NOW)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'outlive' }))
+
+    const state = readSessionState('outlive', h.env)
+    const live = state.pending?.[0]
+    // Still live, still carrying the server's window — not the waiter's.
+    expect(live?.request_id).toBeDefined()
+    expect(live?.reply_deadline_at).toBe(aDayOut)
+    // Not closed and not retired: those are what capped it at eight minutes.
+    expect(state.retiring).toBeUndefined()
+    expect(h.recorder.closed).toEqual([])
+    // And the waiter still stopped at its own ceiling rather than waiting a day.
+    expect(h.deps.now?.()).toBeLessThanOrEqual(NOW + 480_000)
+  })
+
+  it('still closes a question the server has genuinely stopped accepting', async () => {
+    const h = harness([])
+    h.recorder.replyExpiresAt = new Date(NOW + 90_000).toISOString()
+    writeSessionState('short-window', h.env, { last_prompt_at: AWAY })
+    registerQuestion('short-window', h.env, { question: 'Ship it?' }, NOW)
+
+    await hookRunCommand(h.deps, 'stop', stdin({ session_id: 'short-window' }))
+
+    // Its window closed inside the waiter's ceiling, so it is retired here
+    // rather than left for a turn that could never collect it.
+    expect(readSessionState('short-window', h.env).pending).toBeUndefined()
+    expect(h.recorder.closed.length).toBe(1)
+  })
+})