@raidiant/notifai 3.0.1 → 5.0.0

package/dist/hooks.js

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
+import { REPLY_MAX_WINDOW_SECONDS } from '@raidiant/notifai-protocol';
 import { ApiCallError, isRetryableReplyPollError, } from './client.js';
 import { loadConfig, projectSessionPointerPath, sanitizeSessionId, sessionConfigPath, stateDir, } from './config.js';
 import { buildDraft } from './send.js';
@@ -8,12 +9,15 @@ import { atomicWriteFileSync } from './atomic-file.js';
 import { withFileLock } from './file-lock.js';
 import { HARNESS_CAPABILITIES, HARNESSES, } from './harnesses.js';
 /**
- * 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;
 function summarizeRequestIds(entries) {
@@ -30,12 +34,33 @@ function summarizeRequestIds(entries) {
  * question is only how long that host is willing to wait in total.
  */
 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) {
+    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
  * `ask_grace_seconds` from when it was sent, and only then reaches companion
@@ -168,6 +193,16 @@ export function pruneAbandonedSessions(env, now = Date.now(), maxAgeMs = SESSION
  * 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();
 export function claimQuestionPush(sessionId, env, now = Date.now(), beforeStaleReplace) {
     const file = claimPath(sessionId, env);
@@ -266,7 +301,7 @@ function acquireClaimGuard(file) {
             if (err.code !== 'EEXIST')
                 return false;
             try {
-                if (Date.now() - statSync(file).mtimeMs < CLAIM_TTL_MS)
+                if (Date.now() - statSync(file).mtimeMs < CLAIM_GUARD_TTL_MS)
                     return false;
             }
             catch {
@@ -400,6 +435,30 @@ function clearMatchingProjectSession(cwd, env, sessionId) {
         })}\n`);
     });
 }
+/**
+ * Record one gate decision.
+ *
+ * `verdict` is what happened to the question and `reason` is the closed-set
+ * name of the rule that decided it, so an agent can ask "why was it held" with
+ * a filter rather than by matching on prose. The prose still exists — it is what
+ * the user sees in the terminal — but it is free to be rewritten, and a log a
+ * filter cannot rely on is a log nobody filters.
+ */
+export 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',
+];
 function gate(ctx, verdict, reason, data = {}) {
     ctx.log?.info('hook.gate', { verdict, reason, stage: 'queued', ...data });
 }
@@ -436,14 +495,14 @@ async function prepareQuestionSubmission(ctx, options) {
         body: options.body,
         event: options.event,
         lifecycle: { tier: 'needs_you' },
-        ...(options.session !== undefined ? { session: options.session } : {}),
+        ...(options.project !== undefined ? { project: options.project } : {}),
+        ...(options.media !== undefined ? { media: options.media } : {}),
         device: answerable,
         reply: true,
-        replyWindow: Math.max(60, options.windowSeconds),
+        replyWindow: Math.max(MIN_REPLY_WINDOW_SECONDS, options.windowSeconds),
         questions: options.questions,
-        ...(options.detail !== undefined ? { detail: options.detail } : {}),
         collapseKey,
-    });
+    }, options.source === undefined ? {} : { source: options.source });
     if (!build.ok)
         return { error: build.error };
     return {
@@ -545,23 +604,6 @@ async function answerableDevices(ctx) {
         .filter((device) => configured === null || configured.includes(device.device_id))
         .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, envelope) {
-    const explicit = ctx.env['NOTIFAI_SESSION'];
-    if (explicit !== undefined && explicit !== '')
-        return explicit;
-    return envelope.session_id;
-}
 /**
  * Close is a server-side serialization fence: a successful response contains
  * every reply that committed before the window closed. `null` is deliberately
@@ -588,17 +630,17 @@ async function closeQuietly(ctx, requestId) {
  * question simply waits until next open, which beats a tombstone banner
  * announcing what the user just did.
  */
-async function retire(ctx, collapseKey, title, body, endState, retiresRequestId, devices, session) {
+async function retire(ctx, collapseKey, title, body, endState, retiresRequestId, devices, project, source) {
     const build = buildDraft(ctx.config, {
         title,
         body,
         event: 'question_retired',
         lifecycle: { tier: 'done', state: endState, retires_request_id: retiresRequestId },
-        ...(session !== undefined ? { session } : {}),
+        ...(project !== undefined ? { project } : {}),
         ...(devices !== undefined && devices.length > 0 ? { device: devices } : {}),
         collapseKey,
         level: 'passive',
-    });
+    }, source === undefined ? {} : { source });
     if (!build.ok)
         return false;
     try {
@@ -668,6 +710,8 @@ function retiringQuestion(pending, state) {
         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,
     };
 }
@@ -682,14 +726,14 @@ function retirementDeviceIds(entry) {
  * leaves the entry in place for the next hook rather than losing it, which is
  * the whole reason the queue exists.
  */
-export async function drainRetirements(ctx, sessionId, env, session) {
+export async function drainRetirements(ctx, sessionId, env) {
     const queue = readSessionState(sessionId, env).retiring ?? [];
     if (queue.length === 0)
         return [];
     const retired = [];
     for (const entry of queue) {
         await closeQuietly(ctx, entry.request_id);
-        const sent = await retire(ctx, entry.collapse_key, RETIREMENT_TITLES[entry.state], entry.question, entry.state, entry.request_id, retirementDeviceIds(entry), session);
+        const sent = await retire(ctx, entry.collapse_key, RETIREMENT_TITLES[entry.state], entry.question, entry.state, entry.request_id, retirementDeviceIds(entry), entry.project, entry.source);
         if (sent) {
             retired.push(entry.request_id);
             // Persist each success before touching the next entry. A later corrupt
@@ -730,18 +774,14 @@ function updateOrphanQueue(env, update) {
     });
 }
 /** Move retirements into the global queue; deduped so a retry costs nothing. */
-export function orphanRetirements(env, entries, session, now) {
+export function orphanRetirements(env, entries, now) {
     if (entries.length === 0)
         return;
     updateOrphanQueue(env, (queue) => {
         const known = new Set(queue.map((entry) => entry.request_id));
         const added = entries
             .filter((entry) => !known.has(entry.request_id))
-            .map((entry) => ({
-            ...entry,
-            ...(session !== undefined ? { session } : {}),
-            enqueued_at: now,
-        }));
+            .map((entry) => ({ ...entry, enqueued_at: now }));
         return [...queue, ...added].slice(-ORPHAN_QUEUE_CAP);
     });
 }
@@ -764,7 +804,7 @@ export async function drainOrphanRetirements(ctx, env, now) {
             continue;
         }
         await closeQuietly(ctx, entry.request_id);
-        const sent = await retire(ctx, entry.collapse_key, RETIREMENT_TITLES[entry.state], entry.question, entry.state, entry.request_id, retirementDeviceIds(entry), entry.session);
+        const sent = await retire(ctx, entry.collapse_key, RETIREMENT_TITLES[entry.state], entry.question, entry.state, entry.request_id, retirementDeviceIds(entry), entry.project, entry.source);
         if (sent) {
             done.push(entry.request_id);
             updateOrphanQueue(env, (current) => current.filter((candidate) => candidate.request_id !== entry.request_id));
@@ -783,6 +823,20 @@ const LATE_PROMPT_POLL_SECONDS = 3;
  * produce.
  */
 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;
 /** One bounded recovery poll for a question that outlived its original wait. */
 async function pollPendingReply(ctx, pending, timeoutSeconds) {
     if (pending.request_id === undefined) {
@@ -821,6 +875,7 @@ function finalizedAnswer(finalized) {
             reply,
             replies,
             agent_acknowledgement_required: finalized.response?.agent_acknowledgement_required,
+            agent_acknowledgement_text_required: finalized.response?.agent_acknowledgement_text_required,
         };
 }
 /** Persist and surface one answer without letting the two representations drift. */
@@ -867,6 +922,38 @@ function isSamePending(a, b) {
     }
     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) {
+    return err.status === 422 || (err.status === 400 && err.code === 'invalid_request');
+}
+function dropPendingQuestion(sessionId, env, entry) {
+    updateSessionState(sessionId, env, (current) => {
+        const pending = pendingList(current).filter((candidate) => !isSamePending(candidate, entry));
+        const next = { ...current };
+        if (pending.length > 0)
+            next.pending = pending;
+        else
+            delete next.pending;
+        return next;
+    });
+}
+function clearFrozenSubmission(sessionId, env, entry) {
+    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) {
     return pending.questions ?? [{ id: 'q1', text: pending.question }];
@@ -909,8 +996,19 @@ function answerContext(answered) {
  * tied to the question that asked it, with a truthful note about anything
  * still waiting.
  */
-function acknowledgementCommand(requestId) {
-    return `notifai acknowledge ${requestId} --text <text>`;
+function acknowledgementCommand(requestId, textRequired = true) {
+    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) {
+    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) {
     const due = answered.filter((entry) => entry.agent_acknowledgement_required === true && entry.pending.request_id !== undefined);
@@ -918,17 +1016,20 @@ function acknowledgementContext(answered) {
         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` +
+    return (` 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);
 }
 function answersContext(answered, remaining) {
@@ -976,7 +1077,11 @@ function stageAcceptedAnswers(ctx, sessionId, answered, remaining) {
             if (answer.agent_acknowledgement_required === true &&
                 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 = {
@@ -1018,10 +1123,69 @@ export function clearAcknowledgementObligation(sessionId, env, requestId) {
 }
 function acknowledgementBlockContext(due) {
     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, sessionId, due, notes) {
+    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, env) {
+    updateSessionState(sessionId, env, (current) => {
+        if (current.acknowledgement_blocks === undefined)
+            return current;
+        const next = { ...current };
+        delete next.acknowledgement_blocks;
+        return next;
+    });
 }
 async function reconcileAcknowledgementObligations(ctx, sessionId, due) {
     const unresolved = [];
@@ -1151,6 +1315,8 @@ export async function handleUserPromptSubmit(ctx, envelope) {
                 reply: replies.at(-1),
                 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) {
@@ -1184,6 +1350,16 @@ export async function handleUserPromptSubmit(ctx, envelope) {
             ...(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
@@ -1207,7 +1383,7 @@ export async function handleUserPromptSubmit(ctx, envelope) {
         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) {
@@ -1304,42 +1480,23 @@ export async function runEscalationWaiter(ctx, options) {
             state = readSessionState(sessionId, ctx.env);
             const currentAcceptedIds = new Set(accepted.answers.flatMap(({ pending }) => pending.request_id === undefined ? [] : [pending.request_id]));
             const due = await reconcileAcknowledgementObligations(ctx, sessionId, (state.acknowledgement_due ?? []).filter((entry) => 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);
         }
         if (state.accepted === undefined && (state.acknowledgement_due?.length ?? 0) > 0) {
             const due = await reconcileAcknowledgementObligations(ctx, 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) {
@@ -1386,6 +1543,18 @@ export function hookContinuationRoute() {
 async function deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes) {
     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', {
@@ -1433,6 +1602,18 @@ async function deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes) {
             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,
         stage: deliveredStage,
@@ -1461,7 +1642,11 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
         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 };
     }
@@ -1489,6 +1674,8 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
                     reply: replies.at(-1),
                     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(ctx, sessionId, authoritative, pending.length - authoritative.length - permanentlyRejected.length);
@@ -1580,31 +1767,40 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
     // its own notification — one ask never stands in for another.
     const submitted = [];
     for (const entry of unasked) {
-        // The reply window is the question's own: whatever is left of the waiter's
-        // ceiling, granted to the server so it stops accepting answers at the same
-        // moment this owner stops listening for them.
-        const replyWindowSeconds = Math.floor((ceilingAt - ctx.now()) / 1000);
-        if (replyWindowSeconds < MIN_REPLY_WINDOW_SECONDS) {
-            notes.push('too little of the waiter ceiling is left for a reply window the server would accept; leaving this question in the terminal');
+        // 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 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,
             });
@@ -1658,12 +1854,77 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             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 = 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`);
                 ctx.log?.error('hook.pushed', {
                     ok: false,
@@ -1674,11 +1935,10 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
                 });
                 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', {
@@ -1697,13 +1957,21 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             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)
+            // 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),
+                : intent.owner_deadline_at,
         };
         delete live.submission;
         submitted.push(live);
@@ -1770,10 +2038,32 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
     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 !== null);
@@ -1828,6 +2118,7 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             reply: authoritative.at(-1),
             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(`could not confirm the close fence for ${entry.request_id}; delivering the durable answer already observed`);
@@ -1875,8 +2166,7 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
         }
     }
     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`);
     }
     if (state.accepted !== undefined || (state.acknowledgement_due?.length ?? 0) > 0) {
@@ -1913,12 +2203,21 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
 // ask — register a question for the turn's end
 // ---------------------------------------------------------------------------
 /**
- * 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
@@ -1932,11 +2231,16 @@ export const MAX_PENDING_QUESTIONS = 4;
  * running in one project at once, and their questions must never interfere.
  */
 export function registerQuestion(sessionId, env, question, now = Date.now()) {
-    let full = false;
+    let full = 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 {
@@ -1952,10 +2256,14 @@ export function registerQuestion(sessionId, env, question, now = Date.now()) {
             ],
         };
     });
-    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. */
 export function parseHookInput(raw) {