@raidiant/notifai 0.2.0 → 0.3.0

package/dist/hooks.js

@@ -451,9 +451,12 @@ const REPLY_PRESENCE_POLL_SECONDS = 5;
  * because nobody has acted on the silence yet and the next turn can still
  * collect the answer with `notifai replies`.
  */
-async function askAndWait(ctx, options) {
+/**
+ * Put one registered question on the user's devices. Submission only — the
+ * wait happens once, across every live question, in the caller.
+ */
+async function submitQuestion(ctx, options) {
     const collapseKey = `notifai-hook-${randomBytes(8).toString('base64url')}`;
-    const timeoutSeconds = ctx.config.hook_reply_timeout_seconds.value;
     // A draft carrying `reply` is rejected outright if it targets a device that
     // cannot answer, so resolve the healthy companion platforms explicitly.
     const answerable = await answerableDevices(ctx);
@@ -476,45 +479,15 @@ async function askAndWait(ctx, options) {
     if (!build.ok)
         return { error: build.error };
     const receipt = await ctx.client.submit({ idempotency_key: `hook-${randomBytes(12).toString('base64url')}`, draft: build.draft }, 0);
-    // Record what is now live on the user's devices BEFORE blocking. If we only
-    // learned these ids after the wait, a question that timed out would leave no
-    // trace, and the user returning to the terminal could never retire it — the
-    // notification would stay answerable for an hour with nobody listening.
-    options.onSubmitted?.({
-        requestId: receipt.request_id,
-        collapseKey,
-        devices: answerable,
-    });
-    if (ctx.harness === 'opencode') {
-        return {
-            requestId: receipt.request_id,
-            collapseKey,
-            reply: null,
-            replies: [],
-            devices: answerable,
-            degraded: false,
-            waited: false,
-            userReturned: false,
-        };
-    }
-    const result = await waitForReplyWhileAway(ctx, receipt.request_id, timeoutSeconds);
-    if (result.replies.length > 0)
-        await closeQuietly(ctx, receipt.request_id);
-    return {
-        requestId: receipt.request_id,
-        collapseKey,
-        // The latest reply, not the first: an earlier conflicting answer was
-        // corrected by the one that followed it. The cross-device race is still
-        // first-answer-claims — that is what the close above enforces.
-        reply: result.replies.at(-1) ?? null,
-        replies: result.replies,
-        devices: answerable,
-        degraded: result.degraded,
-        waited: true,
-        userReturned: result.userReturned,
-    };
+    return { requestId: receipt.request_id, collapseKey, devices: answerable };
 }
-async function waitForReplyWhileAway(ctx, requestId, timeoutSeconds) {
+/**
+ * One blocking wait across every live question. Each round polls all of them
+ * concurrently, so several questions cost the same wall clock as one; the
+ * first round that finds any reply returns everything found in that round, and
+ * whatever was not answered stays registered.
+ */
+async function waitForAnyReplyWhileAway(ctx, requestIds, timeoutSeconds) {
     const deadline = ctx.now() + timeoutSeconds * 1000;
     let degraded = false;
     let firstPoll = true;
@@ -522,20 +495,31 @@ async function waitForReplyWhileAway(ctx, requestId, timeoutSeconds) {
         if (ctx.config.require_idle.value) {
             const idle = ctx.idleSeconds();
             if (idle !== null && idle < ctx.config.away_after_seconds.value) {
-                return { replies: [], degraded, userReturned: true };
+                return { byRequest: new Map(), degraded, userReturned: true };
             }
         }
         const remainingMs = Math.max(0, deadline - ctx.now());
         if (!firstPoll && remainingMs === 0) {
-            return { replies: [], degraded, userReturned: false };
+            return { byRequest: new Map(), degraded, userReturned: false };
         }
         firstPoll = false;
         const pollSeconds = Math.min(REPLY_PRESENCE_POLL_SECONDS, Math.max(0, Math.ceil(remainingMs / 1000)));
-        const result = await ctx.waitForFirstReply(requestId, pollSeconds);
-        degraded ||= result.degraded === true;
-        if (result.replies.length > 0) {
-            return { replies: result.replies, degraded, userReturned: false };
+        const results = await Promise.all(requestIds.map(async (requestId) => {
+            try {
+                return { requestId, ...(await ctx.waitForFirstReply(requestId, pollSeconds)) };
+            }
+            catch {
+                return { requestId, replies: [], degraded: true };
+            }
+        }));
+        const byRequest = new Map();
+        for (const result of results) {
+            degraded ||= result.degraded === true;
+            if (result.replies.length > 0)
+                byRequest.set(result.requestId, result.replies);
         }
+        if (byRequest.size > 0)
+            return { byRequest, degraded, userReturned: false };
     }
 }
 /**
@@ -790,6 +774,31 @@ async function pollPendingReply(ctx, pending, timeoutSeconds) {
         return { reply: null, replies: [], degraded: true, failed: true };
     }
 }
+/**
+ * One bounded recovery poll across every delivered question, concurrently —
+ * N questions must not multiply the hook's latency budget by N.
+ */
+async function pollPendingReplies(ctx, live, timeoutSeconds) {
+    const polls = await Promise.all(live.map((entry) => pollPendingReply(ctx, entry, timeoutSeconds)));
+    const answered = [];
+    let troubled = false;
+    for (const [index, poll] of polls.entries()) {
+        if (poll.reply !== null) {
+            answered.push({ pending: live[index], reply: poll.reply, replies: poll.replies });
+        }
+        if (poll.failed || poll.degraded)
+            troubled = true;
+    }
+    return { answered, troubled };
+}
+/** The registered-question queue. Anything but the current shape reads as empty. */
+function pendingList(state) {
+    return Array.isArray(state.pending) ? state.pending : [];
+}
+/** Registration identity — the convention every racing writer compares by. */
+function isSamePending(a, b) {
+    return a.question === b.question && a.asked_at === b.asked_at;
+}
 /** The question set this pending record pushes, however it was registered. */
 function pendingQuestions(pending) {
     return pending.questions ?? [{ id: 'q1', text: pending.question }];
@@ -817,38 +826,64 @@ function answerContext(replies, hadChoices) {
         `in the order written: ${parts}. Later parts extend or correct earlier ones. ` +
         'Continue with that answer.');
 }
-function userPromptAnswerOutput(replies, hadChoices) {
+/**
+ * Every answer that has arrived, as one message. Several registered questions
+ * may resolve in one hook pass; the agent reads them together, each answer
+ * tied to the question that asked it, with a truthful note about anything
+ * still waiting.
+ */
+function answersContext(answered, remaining) {
+    const tail = remaining > 0
+        ? ` (${remaining} more registered question${remaining === 1 ? ' is' : 's are'} still waiting for an answer.)`
+        : '';
+    if (answered.length === 1) {
+        const only = answered[0];
+        return answerContext(only.replies, pendingHasChoices(only.pending)) + tail;
+    }
+    const lines = answered.map(({ pending, replies }) => {
+        const latest = replies.at(-1);
+        const answer = replies.length === 1 || pendingHasChoices(pending)
+            ? `"${latest.text}"`
+            : `${replies.map((reply) => `"${reply.text}"`).join(', then ')} (parts in the order written; later parts extend or correct earlier ones)`;
+        return `- "${pending.question}" → ${answer} (from ${latest.device_name})`;
+    });
+    return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}\nContinue with these answers.${tail}`;
+}
+function userPromptAnswerOutput(context) {
     return JSON.stringify({
         hookSpecificOutput: {
             hookEventName: 'UserPromptSubmit',
-            additionalContext: answerContext(replies, hadChoices),
+            additionalContext: context,
         },
     });
 }
-function stopAnswerOutput(replies, hadChoices) {
-    return JSON.stringify({ decision: 'block', reason: answerContext(replies, hadChoices) });
+function stopAnswerOutput(context) {
+    return JSON.stringify({ decision: 'block', reason: context });
 }
 /**
- * Close, truthfully retire, and forget one answered pending question without
- * dropping any other retirement debt. Stop answers also open one bounded
- * continuation generation; UserPromptSubmit answers ride the user's new turn.
+ * Close, truthfully retire, and forget every answered pending question in one
+ * state write, without dropping any other retirement debt or any question
+ * still waiting. Stop answers also open one bounded continuation generation;
+ * UserPromptSubmit answers ride the user's new turn.
  */
-async function finishPendingAnswer(ctx, envelope, sessionId, pending, reply, continuation) {
-    const retirement = retiringQuestion(pending, 'answered');
+async function finishAnsweredPendings(ctx, envelope, sessionId, answered, continuation) {
+    const retirements = answered
+        .map(({ pending }) => retiringQuestion(pending, 'answered'))
+        .filter((entry) => entry !== null);
     updateSessionState(sessionId, ctx.env, (current) => {
         const retiring = [...(current.retiring ?? [])];
-        if (retirement !== null) {
+        for (const retirement of retirements) {
             const existing = retiring.findIndex((entry) => entry.request_id === retirement.request_id);
             if (existing < 0)
                 retiring.push(retirement);
             else
                 retiring[existing] = retirement;
         }
-        const samePending = current.pending?.question === pending.question &&
-            current.pending?.asked_at === pending.asked_at &&
-            current.pending?.request_id === pending.request_id;
+        const remaining = pendingList(current).filter((entry) => !answered.some(({ pending }) => isSamePending(entry, pending)));
         const next = { ...current, retiring };
-        if (samePending)
+        if (remaining.length > 0)
+            next.pending = remaining;
+        else
             delete next.pending;
         if (continuation) {
             next.continuation = {
@@ -878,20 +913,19 @@ export async function handleUserPromptSubmit(ctx, envelope) {
     if (!sessionId)
         return { notes };
     const state = readSessionState(sessionId, ctx.env);
-    const pending = state.pending;
-    if (pending?.request_id !== undefined) {
-        const late = await pollPendingReply(ctx, pending, LATE_PROMPT_POLL_SECONDS);
-        if (late.reply !== null) {
-            await finishPendingAnswer(ctx, envelope, sessionId, pending, late.reply, false);
-            if (envelope.cwd !== undefined && ctx.harness !== undefined) {
-                writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness);
+    const live = pendingList(state).filter((entry) => entry.request_id !== undefined);
+    let lateAnswers = [];
+    if (live.length > 0) {
+        const { answered, troubled } = await pollPendingReplies(ctx, live, LATE_PROMPT_POLL_SECONDS);
+        lateAnswers = answered;
+        if (answered.length > 0) {
+            await finishAnsweredPendings(ctx, envelope, sessionId, answered, false);
+            for (const { reply } of answered) {
+                notes.push(`late answer from ${reply.device_name}: ${reply.text}`);
             }
-            await drainOrphanRetirements(ctx, ctx.env, ctx.now());
-            notes.push(`late answer from ${late.reply.device_name}: ${late.reply.text}`);
-            return { stdout: userPromptAnswerOutput(late.replies, pendingHasChoices(pending)), notes };
         }
-        if (late.failed || late.degraded) {
-            notes.push('could not check the pending question for a late answer before the prompt');
+        if (troubled) {
+            notes.push('could not check every pending question for a late answer before the prompt');
         }
     }
     // Park before dropping `pending`. If the process dies between these writes,
@@ -899,10 +933,10 @@ export async function handleUserPromptSubmit(ctx, envelope) {
     // the gap after erasing the only request/collapse/device identifiers.
     updateSessionState(sessionId, ctx.env, (current) => {
         const retiring = [...(current.retiring ?? [])];
-        if (current.pending !== undefined) {
-            const retirement = retiringQuestion(current.pending, 'answered_elsewhere');
+        for (const entry of pendingList(current)) {
+            const retirement = retiringQuestion(entry, 'answered_elsewhere');
             if (retirement !== null &&
-                !retiring.some((entry) => entry.request_id === retirement.request_id)) {
+                !retiring.some((parked) => parked.request_id === retirement.request_id)) {
                 retiring.push(retirement);
             }
         }
@@ -920,6 +954,11 @@ export async function handleUserPromptSubmit(ctx, envelope) {
     if (swept.length > 0) {
         notes.push(`retired question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`);
     }
+    if (lateAnswers.length > 0) {
+        // Whatever the user did not answer was just retired above — they are at
+        // the keyboard now, so nothing is "still waiting" from their side.
+        return { stdout: userPromptAnswerOutput(answersContext(lateAnswers, 0)), notes };
+    }
     return { notes };
 }
 // ---------------------------------------------------------------------------
@@ -954,22 +993,36 @@ export async function handleStop(ctx, envelope) {
         notes.push(`retired superseded question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`);
     }
     const state = readSessionState(sessionId, ctx.env);
-    const pending = state.pending;
-    if (!pending)
+    const pending = pendingList(state);
+    if (pending.length === 0)
         return { notes };
-    if (pending.request_id !== undefined) {
-        const late = await pollPendingReply(ctx, pending, LATE_STOP_POLL_SECONDS);
-        if (late.reply !== null) {
-            await finishPendingAnswer(ctx, envelope, sessionId, pending, late.reply, true);
-            notes.push(`late answer from ${late.reply.device_name}: ${late.reply.text}`);
-            return { stdout: stopAnswerOutput(late.replies, pendingHasChoices(pending)), notes };
+    const live = pending.filter((entry) => entry.request_id !== undefined);
+    const unasked = pending.filter((entry) => entry.request_id === undefined);
+    if (live.length > 0) {
+        const { answered, troubled } = await pollPendingReplies(ctx, live, LATE_STOP_POLL_SECONDS);
+        if (answered.length > 0) {
+            await finishAnsweredPendings(ctx, envelope, sessionId, answered, true);
+            for (const { reply } of answered) {
+                notes.push(`late answer from ${reply.device_name}: ${reply.text}`);
+            }
+            // Anything still unasked rides the next Stop: the agent is being resumed
+            // with answers right now, and may not even need the rest afterwards.
+            return {
+                stdout: stopAnswerOutput(answersContext(answered, pending.length - answered.length)),
+                notes,
+            };
         }
-        // Already live on the user's devices from an earlier Stop; asking twice for
-        // one question is the nagging failure this feature exists to avoid.
-        notes.push(late.failed || late.degraded
-            ? `already asked (${pending.request_id}); could not check whether its answer arrived`
-            : `already asked (${pending.request_id}); waiting for that answer`);
-        return { notes };
+        if (unasked.length === 0) {
+            // Already live on the user's devices from an earlier Stop; asking twice
+            // for one question is the nagging failure this feature exists to avoid.
+            const ids = live.map((entry) => entry.request_id).join(', ');
+            notes.push(troubled
+                ? `already asked (${ids}); could not check whether ${live.length === 1 ? 'its answer' : 'their answers'} arrived`
+                : `already asked (${ids}); waiting for ${live.length === 1 ? 'that answer' : 'those answers'}`);
+            return { notes };
+        }
+        // Questions registered after the earlier push still owe the user their
+        // notification; fall through and escalate just those.
     }
     // A Stop answer may immediately produce a legitimate follow-up question.
     // Allow that new generation, but never re-run an old pending question and
@@ -977,8 +1030,7 @@ export async function handleStop(ctx, envelope) {
     if (envelope.stop_hook_active === true) {
         const continuation = state.continuation;
         const isNew = continuation !== undefined &&
-            pending.asked_at !== undefined &&
-            pending.asked_at > continuation.answered_at;
+            unasked.some((entry) => entry.asked_at !== undefined && entry.asked_at > continuation.answered_at);
         if (!isNew) {
             notes.push('already continuing from an answer; not asking again this turn');
             return { notes };
@@ -1004,97 +1056,125 @@ export async function handleStop(ctx, envelope) {
         return { notes };
     }
     try {
-        return await escalate(ctx, envelope, sessionId, pending, notes);
+        return await escalate(ctx, envelope, sessionId, unasked, live, notes);
     }
     finally {
         releaseQuestionPush(sessionId, ctx.env);
     }
 }
 /** The escalation itself, split out so the claim is released on every path. */
-async function escalate(ctx, envelope, sessionId, pending, notes) {
-    // Away right now, but the question still owes the user its terminal-first
-    // window before anything reaches their devices.
-    const grace = await awaitGrace(ctx, pending.asked_at ?? ctx.now());
+async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes) {
+    // Away right now, but the questions still owe the user their terminal-first
+    // window before anything reaches their devices — measured from the oldest
+    // registration, because that is the question that has waited longest.
+    const oldest = Math.min(...unasked.map((entry) => entry.asked_at ?? ctx.now()));
+    const grace = await awaitGrace(ctx, oldest);
     if (grace === 'user-returned') {
-        notes.push('you came back before the wait elapsed; leaving the question in the terminal');
+        notes.push('you came back before the wait elapsed; leaving the questions in the terminal');
         return { notes };
     }
     if (grace === 'no-signal') {
         notes.push('no idle signal on this machine; asking now rather than holding the terminal');
     }
-    const questions = pendingQuestions(pending);
-    const asked = await askAndWait(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)`
-            : pending.question,
-        questions,
-        ...(pending.detail !== undefined ? { detail: pending.detail } : {}),
-        event: 'agent_question',
-        session: sessionLabel(ctx, envelope),
-        // Outlives the block, and stays open on purpose: the answer is still
-        // useful to the next turn, which collects it with `notifai replies`.
-        windowSeconds: QUESTION_WINDOW_SECONDS,
-        onSubmitted: (live) => {
-            const livePending = {
-                ...pending,
-                request_id: live.requestId,
-                collapse_key: live.collapseKey,
-                device_ids: live.devices,
-            };
-            updateSessionState(sessionId, ctx.env, (current) => {
-                const stillCurrent = current.pending?.question === pending.question &&
-                    current.pending?.asked_at === pending.asked_at &&
-                    current.pending?.request_id === undefined;
-                if (stillCurrent)
-                    return { ...current, pending: livePending };
-                // A newer `notifai ask` won while this submit was in flight. Keep it,
-                // but now that request identifiers exist, preserve the old delivered
-                // question as collectable/retirable instead of overwriting either one.
-                const retirement = retiringQuestion(livePending, 'superseded');
-                const retiring = [...(current.retiring ?? [])];
-                if (!retiring.some((entry) => entry.request_id === retirement.request_id)) {
-                    retiring.push(retirement);
-                }
-                return { ...current, retiring };
-            });
-        },
-    });
-    if ('error' in asked) {
-        notes.push(asked.error);
+    // Phase one: every registered question reaches the user's devices, each as
+    // its own notification — one ask never stands in for another.
+    const submitted = [];
+    for (const entry of unasked) {
+        const questions = pendingQuestions(entry);
+        const sent = await submitQuestion(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,
+            questions,
+            ...(entry.detail !== undefined ? { detail: entry.detail } : {}),
+            event: 'agent_question',
+            session: sessionLabel(ctx, envelope),
+            // Outlives the block, and stays open on purpose: the answer is still
+            // useful to the next turn, which collects it with `notifai replies`.
+            windowSeconds: QUESTION_WINDOW_SECONDS,
+        });
+        if ('error' in sent) {
+            notes.push(sent.error);
+            continue;
+        }
+        const live = {
+            ...entry,
+            request_id: sent.requestId,
+            collapse_key: sent.collapseKey,
+            device_ids: sent.devices,
+        };
+        submitted.push(live);
+        // Record what is now live on the user's devices BEFORE any wait. If we
+        // only learned these ids afterwards, a question that timed out would
+        // leave no trace, and the user returning to the terminal could never
+        // retire it — the notification would stay answerable for an hour with
+        // nobody listening.
+        updateSessionState(sessionId, ctx.env, (current) => {
+            const list = pendingList(current);
+            const index = list.findIndex((candidate) => isSamePending(candidate, entry) && candidate.request_id === undefined);
+            if (index >= 0) {
+                const next = [...list];
+                next[index] = live;
+                return { ...current, pending: next };
+            }
+            // The entry vanished while the submit was in flight (the user's prompt
+            // wiped the queue). The delivered notification must still be retirable,
+            // so park it rather than lose its only identifiers.
+            const retirement = retiringQuestion(live, 'answered_elsewhere');
+            const retiring = [...(current.retiring ?? [])];
+            if (!retiring.some((parked) => parked.request_id === retirement.request_id)) {
+                retiring.push(retirement);
+            }
+            return { ...current, retiring };
+        });
+    }
+    const waitingOn = [...alreadyLive, ...submitted];
+    if (waitingOn.length === 0)
+        return { notes };
+    if (ctx.harness === 'opencode') {
+        notes.push(`question${submitted.length === 1 ? '' : 's'} sent without blocking OpenCode; retrieve answers on the next prompt or with: notifai replies --pending`);
         return { notes };
     }
-    if (!asked.reply) {
-        // Keep the pending record so a returning user's UserPromptSubmit can retire
-        // the notification that is still live on their devices. `request_id` being
-        // set is also what stops the next Stop pushing the same question again.
-        if (!asked.waited) {
-            notes.push(`question sent without blocking OpenCode; retrieve the answer on the next prompt or with: notifai replies --pending`);
-        }
-        else if (asked.userReturned) {
-            notes.push(`you came back after the question was sent; returning the terminal while it stays answerable (${asked.requestId}). ` +
-                'Retrieve it with: notifai replies --pending');
+    // Phase two: one blocking wait across everything live, old and new alike.
+    const timeoutSeconds = ctx.config.hook_reply_timeout_seconds.value;
+    const waited = await waitForAnyReplyWhileAway(ctx, waitingOn.map((entry) => entry.request_id), timeoutSeconds);
+    if (waited.byRequest.size === 0) {
+        // Keep the pending records so a returning user's UserPromptSubmit can
+        // retire the notifications still live on their devices. `request_id`
+        // being set is also what stops the next Stop pushing them again.
+        const ids = waitingOn.map((entry) => entry.request_id).join(', ');
+        if (waited.userReturned) {
+            notes.push(`you came back after the question${waitingOn.length === 1 ? ' was' : 's were'} sent; returning the terminal while ${waitingOn.length === 1 ? 'it stays' : 'they stay'} answerable (${ids}). ` +
+                'Retrieve answers with: notifai replies --pending');
         }
         else {
-            notes.push(asked.degraded
-                ? `could not reach the server to find out whether you answered; check with: notifai replies --pending`
-                : `no answer in time; retrieve it later with: notifai replies --pending`);
+            notes.push(waited.degraded
+                ? 'could not reach the server to find out whether you answered; check with: notifai replies --pending'
+                : 'no answer in time; retrieve it later with: notifai replies --pending');
         }
         return { notes };
     }
-    await finishPendingAnswer(ctx, envelope, sessionId, {
-        ...pending,
-        request_id: asked.requestId,
-        collapse_key: asked.collapseKey,
-        device_ids: asked.devices,
-    }, asked.reply, true);
-    notes.push(`answer from ${asked.reply.device_name}: ${asked.reply.text}`);
+    const answered = [];
+    for (const entry of waitingOn) {
+        const replies = waited.byRequest.get(entry.request_id);
+        if (replies === undefined)
+            continue;
+        // First answer claims the question across devices; the close is what
+        // enforces that, and the latest reply within the window is the answer.
+        await closeQuietly(ctx, entry.request_id);
+        answered.push({ pending: entry, reply: replies.at(-1), replies });
+    }
+    await finishAnsweredPendings(ctx, envelope, sessionId, answered, true);
+    for (const { reply } of answered) {
+        notes.push(`answer from ${reply.device_name}: ${reply.text}`);
+    }
     return {
-        stdout: stopAnswerOutput(asked.replies, pendingHasChoices(pending)),
+        stdout: stopAnswerOutput(answersContext(answered, waitingOn.length - answered.length)),
         notes,
     };
 }
@@ -1118,10 +1198,9 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
         clearMatchingProjectSession(envelope.cwd, env, sessionId);
     const state = readSessionState(sessionId, env);
     const orphans = [...(state.retiring ?? [])];
-    const pending = state.pending;
-    if (pending !== undefined) {
+    for (const entry of pendingList(state)) {
         try {
-            const orphan = retiringQuestion(pending, 'expired');
+            const orphan = retiringQuestion(entry, 'expired');
             if (orphan !== null)
                 orphans.push(orphan);
         }
@@ -1144,39 +1223,48 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
 // ask — register a question for the turn's end
 // ---------------------------------------------------------------------------
 /**
- * One session holds one live question, so registering a second one ends the
- * first.
- *
- * This used to replace `pending` wholesale, which silently discarded the
- * `request_id` and `collapse_key` of a question already delivered to the user's
- * devices. Nothing else knows those ids, so the notification became
- * unretirable — it sat on the lock screen for ever asking a question no answer
- * could reach. That is where the stale pile-up came from.
+ * 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.
+ */
+export const MAX_PENDING_QUESTIONS = 4;
+/**
+ * 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
+ * answerable independently. Superseding is reply semantics — a later reply
+ * corrects an earlier reply to the same question (that correction model lives
+ * server-side) — never question semantics: the old single-slot model silently
+ * discarded a question the moment a second was registered, and the user was
+ * pointed at a notification that never existed (2026-08-09).
  *
- * Supersession is keyed on the session, not the project: several agents may be
- * running in one project at once, and one agent's new question killing another
- * agent's live one would be worse than the staleness this fixes.
+ * The queue is keyed on the session, not the project: several agents may be
+ * running in one project at once, and their questions must never interfere.
  */
 export function registerQuestion(sessionId, env, question, now = Date.now()) {
+    let full = false;
     updateSessionState(sessionId, env, (state) => {
-        const retiring = [...(state.retiring ?? [])];
-        if (state.pending !== undefined) {
-            const retirement = retiringQuestion(state.pending, 'superseded');
-            if (retirement !== null &&
-                !retiring.some((entry) => entry.request_id === retirement.request_id)) {
-                retiring.push(retirement);
-            }
+        const pending = pendingList(state);
+        if (pending.length >= MAX_PENDING_QUESTIONS) {
+            full = true;
+            return state;
         }
         return {
             ...state,
-            ...(retiring.length > 0 ? { retiring } : {}),
-            pending: {
-                asked_at: now,
-                ...question,
-                question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
-            },
+            pending: [
+                ...pending,
+                {
+                    asked_at: now,
+                    ...question,
+                    question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
+                },
+            ],
         };
     });
+    if (full) {
+        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.');
+    }
 }
 /** Parses hook JSON from stdin, tolerating an empty or malformed body. */
 export function parseHookInput(raw) {