@raidiant/notifai 4.0.0 → 6.0.0

package/src/hooks.test.ts

@@ -1,4 +1,4 @@
-import { spawn, type ChildProcess } from 'node:child_process'
+import { execFileSync, spawn, type ChildProcess } from 'node:child_process'
 import {
   existsSync,
   mkdirSync,
@@ -49,6 +49,7 @@ import {
   drainOrphanRetirements,
   runEscalationWaiter,
   MAX_CONTINUATION_COUNT,
+  MAX_HELD_DELIVERIES,
   orphanRetirements,
   pruneAbandonedSessions,
   releaseQuestionPush,
@@ -60,7 +61,15 @@ import {
   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(
@@ -126,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[]
 }
@@ -154,7 +167,8 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
           platform: 'ios' as const,
           permission_status: 'authorized',
           registration_healthy: true,
-          reply_protocol_version: 2,
+          capabilities: ['answer'],
+          derived_status: 'working',
           last_seen_at: null,
         },
         {
@@ -163,7 +177,8 @@ function fakeClient(recorder: Recorder, replies: ReplyView[]): ApiClient {
           platform: 'macos' as const,
           permission_status: 'authorized',
           registration_healthy: true,
-          reply_protocol_version: 2,
+          capabilities: ['answer'],
+          derived_status: 'working',
           last_seen_at: null,
         },
       ],
@@ -176,7 +191,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(),
         },
       }
@@ -188,6 +203,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,
@@ -207,9 +224,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: [],
@@ -223,6 +242,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,
@@ -236,6 +257,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,
@@ -316,6 +339,23 @@ function harness(replies: ReplyView[] = []): Harness {
   }
 }
 
+function runFixtureGit(cwd: string, ...args: string[]): string {
+  return execFileSync('git', ['-C', cwd, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).trim()
+}
+
+function initializeFixtureRepository(root: string, branch = 'branch-a'): void {
+  runFixtureGit(root, 'init')
+  runFixtureGit(root, 'config', 'user.email', 'notifai-tests@example.invalid')
+  runFixtureGit(root, 'config', 'user.name', 'Notifai Tests')
+  writeFileSync(path.join(root, 'tracked.txt'), 'fixture\n')
+  runFixtureGit(root, 'add', 'tracked.txt')
+  runFixtureGit(root, 'commit', '-m', 'fixture')
+  runFixtureGit(root, 'branch', '-M', branch)
+}
+
 function stdin(payload: unknown): () => Promise<string> {
   return async () => JSON.stringify(payload)
 }
@@ -451,7 +491,48 @@ 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', () => {
+  it('keeps unknown future session keys through an older read-modify-write', () => {
+    const h = harness([])
+    const sessionId = 'future-session-format'
+    const file = path.join(stateDir(h.env), 'sessions', `${sanitizeSessionId(sessionId)}.json`)
+    mkdirSync(path.dirname(file), { recursive: true })
+    writeFileSync(
+      file,
+      `${JSON.stringify({
+        last_prompt_at: NOW,
+        future_session_key: { nested: ['kept'] },
+      })}\n`,
+    )
+
+    registerQuestion(sessionId, h.env, { question: 'Still preserved?' }, NOW)
+
+    const rewritten = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+    expect(rewritten['future_session_key']).toEqual({ nested: ['kept'] })
+    expect(rewritten['pending']).toHaveLength(1)
+  })
+
   // 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
   // being present — so its FIRST question could never escalate, which is the
@@ -471,7 +552,8 @@ describe('pushing a registered question', () => {
       title: 'Ship it?',
       body: 'Ship it?',
     })
-    expect(h.recorder.submitted[0]?.draft.platform).toBeUndefined()
+    // 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('keeps sparse alt text paired with its original media item', async () => {
@@ -821,7 +903,7 @@ describe('terminal-first grace window', () => {
     ).toBeGreaterThanOrEqual(60)
   })
 
-  it('never pushes a question to a Companion without the current reply protocol', async () => {
+  it('never pushes a question to a Companion that did not advertise answer', async () => {
     const h = harness([])
     const factory = h.deps.clientFactory
     h.deps.clientFactory = () => {
@@ -831,7 +913,7 @@ describe('terminal-first grace window', () => {
         listDevices: async () => ({
           devices: (await client.listDevices()).devices.map((device) => ({
             ...device,
-            reply_protocol_version: null,
+            capabilities: [],
           })),
         }),
       } as ApiClient
@@ -1045,6 +1127,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',
@@ -1216,10 +1304,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 {
@@ -1227,29 +1371,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,
@@ -1284,7 +1471,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)
@@ -1296,9 +1483,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)
   })
 
@@ -1763,7 +1953,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 = []
@@ -1783,6 +1973,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, {
@@ -1953,7 +2203,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,
@@ -1964,7 +2214,7 @@ describe('a question that outlives its session', () => {
         question: 'Old?',
         state: 'expired',
       }],
-      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 }) },
@@ -2427,6 +2677,58 @@ describe('user-prompt-submit hook', () => {
     clearSessionState('s14', h.env)
     expect(readProjectSession(project, h.env, NOW)).toBeNull()
   })
+
+  it('round-trips future project-pointer fields while publishing a session', () => {
+    const h = harness()
+    const pointer = projectSessionPointerPath(h.deps.cwd, h.env)
+    const futureEntry = {
+      format: 2,
+      session: { id: 'future-session', runtime: 'future-harness' },
+    }
+    mkdirSync(path.dirname(pointer), { recursive: true })
+    writeFileSync(
+      pointer,
+      `${JSON.stringify({
+        future_root: { retained: true },
+        sessions: [
+          {
+            session_id: 'still-running',
+            updated_at: NOW - 1,
+            harness: 'codex',
+            future_entry: { retained: true },
+          },
+          {
+            session_id: 'new-session',
+            updated_at: NOW - 2,
+            harness: 'claude-code',
+            future_current_entry: { retained: true },
+          },
+          futureEntry,
+        ],
+      })}\n`,
+    )
+
+    writeProjectSession(h.deps.cwd, h.env, 'new-session', NOW, 'claude-code')
+
+    expect(JSON.parse(readFileSync(pointer, 'utf8'))).toEqual({
+      future_root: { retained: true },
+      sessions: [
+        {
+          session_id: 'still-running',
+          updated_at: NOW - 1,
+          harness: 'codex',
+          future_entry: { retained: true },
+        },
+        futureEntry,
+        {
+          session_id: 'new-session',
+          updated_at: NOW,
+          harness: 'claude-code',
+          future_current_entry: { retained: true },
+        },
+      ],
+    })
+  })
 })
 
 describe('session-end hook', () => {
@@ -2445,6 +2747,36 @@ describe('session-end hook', () => {
     expect(records.at(-1)?.data).toMatchObject({ outcome: 'cleaned', queued_retirements: 0 })
   })
 
+  it('round-trips future session-state fields when SessionEnd preserves an obligation', async () => {
+    const h = harness()
+    const sessionId = 'session-end-future-state'
+    const stateFile = path.join(
+      stateDir(h.env),
+      'sessions',
+      `${sanitizeSessionId(sessionId)}.json`,
+    )
+    const acknowledgement = {
+      request_id: 'req_future_ack',
+      recorded_at: NOW,
+      future_entry: { retained: true },
+    }
+    mkdirSync(path.dirname(stateFile), { recursive: true })
+    writeFileSync(
+      stateFile,
+      `${JSON.stringify({
+        future_root: { retained: true },
+        acknowledgement_due: [acknowledgement],
+      })}\n`,
+    )
+
+    await hookRunCommand(h.deps, 'session-end', stdin({ session_id: sessionId }))
+
+    expect(JSON.parse(readFileSync(stateFile, 'utf8'))).toEqual({
+      future_root: { retained: true },
+      acknowledgement_due: [acknowledgement],
+    })
+  })
+
   it('runs the real Codex SessionEnd cleanup before contended diagnostics and exits fail-open', async () => {
     const h = harness()
     const sessionId = 'session-end-budget'
@@ -2561,6 +2893,54 @@ describe('session-end hook', () => {
     ).toEqual({ sessionId: 'still-running', harness: 'codex' })
   })
 
+  it('keeps future project-pointer data when clearing the ending session', async () => {
+    const h = harness()
+    const pointer = projectSessionPointerPath(h.deps.cwd, h.env)
+    const futureEntry = {
+      format: 2,
+      session: { id: 'future-session', runtime: 'future-harness' },
+    }
+    writeSessionState('still-running', h.env, { last_prompt_at: NOW })
+    writeSessionState('ending', h.env, { last_prompt_at: NOW })
+    mkdirSync(path.dirname(pointer), { recursive: true })
+    writeFileSync(
+      pointer,
+      `${JSON.stringify({
+        future_root: { retained: true },
+        sessions: [
+          {
+            session_id: 'still-running',
+            updated_at: NOW - 1,
+            harness: 'codex',
+            future_entry: { retained: true },
+          },
+          futureEntry,
+          { session_id: 'ending', updated_at: NOW, harness: 'claude-code' },
+        ],
+      })}\n`,
+    )
+
+    await hookRunCommand(
+      h.deps,
+      'session-end',
+      stdin({ session_id: 'ending', cwd: h.deps.cwd }),
+      'claude-code',
+    )
+
+    expect(JSON.parse(readFileSync(pointer, 'utf8'))).toEqual({
+      future_root: { retained: true },
+      sessions: [
+        {
+          session_id: 'still-running',
+          updated_at: NOW - 1,
+          harness: 'codex',
+          future_entry: { retained: true },
+        },
+        futureEntry,
+      ],
+    })
+  })
+
   it('preserves incomplete live state and reports why it cannot retire it', async () => {
     const h = harness()
     writeSessionState('s-incomplete', h.env, {
@@ -2592,6 +2972,164 @@ describe('malformed input', () => {
 })
 
 describe('telling concurrent agents apart', () => {
+  it('uses each hook event branch while keeping one immutable session identity', async () => {
+    const h = harness([reply({ text: 'Yes' })])
+    initializeFixtureRepository(h.deps.cwd)
+    registerQuestion(
+      'session-branch-transition',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'session-branch-transition',
+          session_label: 'Branch transition',
+          harness: 'claude-code',
+          branch: 'branch-a',
+        },
+      },
+      NOW,
+    )
+
+    runFixtureGit(h.deps.cwd, 'checkout', '-b', 'branch-b')
+    await hookRunCommand(
+      h.deps,
+      'stop',
+      stdin({ session_id: 'session-branch-transition', cwd: h.deps.cwd }),
+      'claude-code',
+    )
+
+    const question = h.recorder.submitted.find((entry) => entry.draft.event === 'agent_question')
+    expect(question?.draft.source).toEqual({
+      session_id: 'session-branch-transition',
+      session_label: 'Branch transition',
+      harness: 'claude-code',
+      branch: 'branch-b',
+    })
+
+    runFixtureGit(h.deps.cwd, 'checkout', 'branch-a')
+    h.recorder.acknowledged ??= new Set()
+    h.recorder.acknowledged.add(h.recorder.receipts[0]!)
+    await hookRunCommand(
+      h.deps,
+      'stop',
+      stdin({
+        session_id: 'session-branch-transition',
+        cwd: h.deps.cwd,
+        stop_hook_active: true,
+      }),
+      'claude-code',
+    )
+
+    const retirement = h.recorder.submitted.find(
+      (entry) => entry.draft.event === 'question_retired',
+    )
+    expect(retirement?.draft.source).toEqual({
+      session_id: 'session-branch-transition',
+      session_label: 'Branch transition',
+      harness: 'claude-code',
+      branch: 'branch-a',
+    })
+  })
+
+  it('clears registration-time branch and worktree on a detached-HEAD hook event', async () => {
+    const h = harness([])
+    initializeFixtureRepository(h.deps.cwd)
+    registerQuestion(
+      'session-detached',
+      h.env,
+      {
+        question: 'Ship it?',
+        source: {
+          session_id: 'session-detached',
+          session_label: 'Detached review',
+          harness: 'claude-code',
+          branch: 'branch-a',
+          worktree: 'stale-worktree',
+        },
+      },
+      NOW,
+    )
+    runFixtureGit(h.deps.cwd, 'checkout', '--detach', 'HEAD')
+
+    await hookRunCommand(
+      h.deps,
+      'stop',
+      stdin({ session_id: 'session-detached', cwd: h.deps.cwd }),
+      'claude-code',
+    )
+
+    const question = h.recorder.submitted.find((entry) => entry.draft.event === 'agent_question')
+    expect(question?.draft.source).toEqual({
+      session_id: 'session-detached',
+      session_label: 'Detached review',
+      harness: 'claude-code',
+    })
+  })
+
+  it('captures entry into and exit from a linked worktree on the same session', async () => {
+    const h = harness([reply({ text: 'Yes' })])
+    initializeFixtureRepository(h.deps.cwd, 'main')
+    const linked = `${h.deps.cwd}-linked`
+    runFixtureGit(h.deps.cwd, 'worktree', 'add', '-b', 'worktree-branch', linked)
+    try {
+      registerQuestion(
+        'session-worktree-transition',
+        h.env,
+        {
+          question: 'Ship it?',
+          source: {
+            session_id: 'session-worktree-transition',
+            session_label: 'Worktree transition',
+            harness: 'claude-code',
+            branch: 'main',
+          },
+        },
+        NOW,
+      )
+
+      await hookRunCommand(
+        h.deps,
+        'stop',
+        stdin({ session_id: 'session-worktree-transition', cwd: linked }),
+        'claude-code',
+      )
+      const question = h.recorder.submitted.find(
+        (entry) => entry.draft.event === 'agent_question',
+      )
+      expect(question?.draft.source).toEqual({
+        session_id: 'session-worktree-transition',
+        session_label: 'Worktree transition',
+        harness: 'claude-code',
+        branch: 'worktree-branch',
+        worktree: path.basename(linked),
+      })
+
+      h.recorder.acknowledged ??= new Set()
+      h.recorder.acknowledged.add(h.recorder.receipts[0]!)
+      await hookRunCommand(
+        h.deps,
+        'stop',
+        stdin({
+          session_id: 'session-worktree-transition',
+          cwd: h.deps.cwd,
+          stop_hook_active: true,
+        }),
+        'claude-code',
+      )
+      const retirement = h.recorder.submitted.find(
+        (entry) => entry.draft.event === 'question_retired',
+      )
+      expect(retirement?.draft.source).toEqual({
+        session_id: 'session-worktree-transition',
+        session_label: 'Worktree transition',
+        harness: 'claude-code',
+        branch: 'main',
+      })
+    } finally {
+      runFixtureGit(h.deps.cwd, 'worktree', 'remove', '--force', linked)
+    }
+  })
+
   it('stamps structured Source Context on the question it pushes', async () => {
     const h = harness([])
     registerQuestion(
@@ -3561,6 +4099,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.
@@ -3572,7 +4151,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 },
@@ -3588,9 +4167,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()
     }
@@ -3624,3 +4205,99 @@ describe('escalation waiter delivery seam', () => {
     releaseQuestionPush('waiter-failed-route', h.env)
   })
 })
+
+
+describe('session state across a prompt', () => {
+  it('carries known and future session state across a typed prompt', async () => {
+    // The prompt transition deliberately changes pending/retiring state and the
+    // continuation count, but fields introduced by a newer CLI remain opaque.
+    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,
+    }
+    const futureSessionValue = { nested: ['kept'], revision: 2 }
+    writeSessionState('carry-all', h.env, {
+      ...before,
+      future_session_key: futureSessionValue,
+    } as SessionState & { future_session_key: typeof futureSessionValue })
+
+    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()
+    }
+    const persisted = JSON.parse(
+      readFileSync(
+        path.join(
+          stateDir(h.env),
+          'sessions',
+          `${sanitizeSessionId('carry-all')}.json`,
+        ),
+        'utf8',
+      ),
+    ) as Record<string, unknown>
+    expect(persisted['future_session_key']).toEqual(futureSessionValue)
+    // 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)
+  })
+})