@raidiant/notifai 0.1.7 → 0.2.0

package/dist/hooks.js

@@ -1,8 +1,9 @@
 import { randomBytes } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
 import { loadConfig, projectSessionPointerPath, sanitizeSessionId, sessionConfigPath, stateDir, } from './config.js';
 import { buildDraft } from './send.js';
+import { atomicWriteFileSync } from './atomic-file.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
@@ -82,14 +83,84 @@ export function readSessionState(sessionId, env) {
 }
 export function writeSessionState(sessionId, env, state) {
     const file = sessionStatePath(sessionId, env);
-    mkdirSync(path.dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    withFileLock(`${file}.lock`, () => writeSessionStateUnlocked(file, state));
 }
 export function clearSessionState(sessionId, env) {
-    rmSync(sessionStatePath(sessionId, env), { force: true });
-    // The session override lives in a sibling file; leaving it behind meant a
-    // later session reusing the id silently inherited `ask_notifications = false`.
-    rmSync(sessionConfigPath(sessionId, env), { force: true });
+    const file = sessionStatePath(sessionId, env);
+    withFileLock(`${file}.lock`, () => {
+        rmSync(file, { force: true });
+        // The session override lives in a sibling file; leaving it behind meant a
+        // later session reusing the id silently inherited `ask_notifications = false`.
+        rmSync(sessionConfigPath(sessionId, env), { force: true });
+    });
+}
+function writeSessionStateUnlocked(file, state) {
+    atomicWriteFileSync(file, `${JSON.stringify(state, null, 2)}\n`);
+}
+function updateSessionState(sessionId, env, update) {
+    const file = sessionStatePath(sessionId, env);
+    return withFileLock(`${file}.lock`, () => {
+        const next = update(readSessionState(sessionId, env));
+        writeSessionStateUnlocked(file, next);
+        return next;
+    });
+}
+/**
+ * Serialize a short read-modify-write without ever exposing partial JSON.
+ * A crashed holder is recoverable after 30 seconds; releases compare their
+ * random token under the same cooperating lock discipline before unlinking.
+ */
+const FILE_LOCK_STALE_MS = 30_000;
+const FILE_LOCK_WAIT_MS = 1_000;
+const FILE_LOCK_POLL_MS = 5;
+const lockSleep = new Int32Array(new SharedArrayBuffer(4));
+function withFileLock(file, action) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const token = randomBytes(12).toString('base64url');
+    const deadline = Date.now() + FILE_LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            const handle = openSync(file, 'wx', 0o600);
+            try {
+                writeFileSync(handle, `${JSON.stringify({ token, at: Date.now() })}\n`);
+            }
+            finally {
+                closeSync(handle);
+            }
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            let stale = false;
+            try {
+                const held = JSON.parse(readFileSync(file, 'utf8'));
+                stale = typeof held.at !== 'number' || Date.now() - held.at >= FILE_LOCK_STALE_MS;
+            }
+            catch {
+                stale = true;
+            }
+            if (stale)
+                rmSync(file, { force: true });
+            else if (Date.now() >= deadline)
+                throw new Error(`timed out waiting for state lock ${file}`);
+            else
+                Atomics.wait(lockSleep, 0, 0, FILE_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return action();
+    }
+    finally {
+        try {
+            const held = JSON.parse(readFileSync(file, 'utf8'));
+            if (held.token === token)
+                rmSync(file, { force: true });
+        }
+        catch {
+            // A replaced or externally removed lock is no longer ours to release.
+        }
+    }
 }
 /**
  * Session state a crashed harness left behind.
@@ -149,50 +220,107 @@ export function pruneAbandonedSessions(env, now = Date.now(), maxAgeMs = SESSION
  * pending question, see no `request_id`, and both escalate: one question, two
  * notifications.
  *
- * `wx` is the whole mechanism. Exclusive create is atomic on POSIX, so exactly
- * one process gets the claim and the other steps aside. A claim older than the
- * hook budget is a crashed process rather than a live one, and is broken — the
- * alternative is a stale lock file suppressing every question for that session
- * for ever, which is worse than the duplicate this prevents.
+ * Exclusive create is atomic on POSIX, so exactly one process gets the claim
+ * and the other steps aside. A short guard serializes stale replacement with
+ * contenders and releases; random ownership tokens keep an old holder from
+ * unlinking its replacement. A claim older than the hook budget is a crashed
+ * process rather than a live one and is broken, avoiding permanent suppression.
  */
 const CLAIM_TTL_MS = STOP_BUDGET_SECONDS * 1000;
-export function claimQuestionPush(sessionId, env, now = Date.now()) {
+const heldClaims = new Map();
+export function claimQuestionPush(sessionId, env, now = Date.now(), beforeStaleReplace) {
     const file = claimPath(sessionId, env);
+    const guard = `${file}.guard`;
+    const token = randomBytes(12).toString('base64url');
     mkdirSync(path.dirname(file), { recursive: true });
+    if (!acquireClaimGuard(guard))
+        return false;
     try {
-        writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now })}\n`, {
-            mode: 0o600,
-            flag: 'wx',
-        });
-        return true;
-    }
-    catch {
-        // Held. Break it only if whoever holds it cannot still be running.
         try {
-            const held = JSON.parse(readFileSync(file, 'utf8'));
-            const age = typeof held.at === 'number' ? now - held.at : Number.POSITIVE_INFINITY;
-            if (age >= 0 && age < CLAIM_TTL_MS)
-                return false;
-        }
-        catch {
-            // Unreadable or corrupt: treat as abandoned.
-        }
-        rmSync(file, { force: true });
-        try {
-            writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now })}\n`, {
+            writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now, token })}\n`, {
                 mode: 0o600,
                 flag: 'wx',
             });
+            heldClaims.set(file, token);
             return true;
         }
         catch {
-            // Someone else broke it first and won. One of us proceeding is the point.
-            return false;
+            // Held. Break it only if whoever holds it cannot still be running.
+            try {
+                const held = JSON.parse(readFileSync(file, 'utf8'));
+                const age = typeof held.at === 'number' ? now - held.at : Number.POSITIVE_INFINITY;
+                if (age >= 0 && age < CLAIM_TTL_MS)
+                    return false;
+            }
+            catch {
+                // Unreadable or corrupt: treat as abandoned.
+            }
+            beforeStaleReplace?.();
+            rmSync(file, { force: true });
+            try {
+                writeFileSync(file, `${JSON.stringify({ pid: process.pid, at: now, token })}\n`, {
+                    mode: 0o600,
+                    flag: 'wx',
+                });
+                heldClaims.set(file, token);
+                return true;
+            }
+            catch {
+                return false;
+            }
         }
     }
+    finally {
+        rmSync(guard, { force: true });
+    }
 }
 export function releaseQuestionPush(sessionId, env) {
-    rmSync(claimPath(sessionId, env), { force: true });
+    const file = claimPath(sessionId, env);
+    const token = heldClaims.get(file);
+    if (token === undefined)
+        return;
+    const guard = `${file}.guard`;
+    if (!acquireClaimGuard(guard)) {
+        heldClaims.delete(file);
+        return;
+    }
+    try {
+        try {
+            const held = JSON.parse(readFileSync(file, 'utf8'));
+            if (held.token === token)
+                rmSync(file, { force: true });
+        }
+        catch {
+            // Missing or replaced claims are not ours to release.
+        }
+    }
+    finally {
+        heldClaims.delete(file);
+        rmSync(guard, { force: true });
+    }
+}
+/** The guard serializes stale replacement and release; recover a crashed guard. */
+function acquireClaimGuard(file) {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = openSync(file, 'wx', 0o600);
+            closeSync(handle);
+            return true;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                return false;
+            try {
+                if (Date.now() - statSync(file).mtimeMs < CLAIM_TTL_MS)
+                    return false;
+            }
+            catch {
+                // A vanished/corrupt guard is safe to retry once.
+            }
+            rmSync(file, { force: true });
+        }
+    }
+    return false;
 }
 function claimPath(sessionId, env) {
     return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.claim`);
@@ -205,11 +333,10 @@ function claimPath(sessionId, env) {
  */
 const MAX_STORED_QUESTION_CHARS = 2000;
 /** Records which session is working in a directory, for `notifai ask`. */
-export function writeProjectSession(cwd, env, sessionId, now) {
+export function writeProjectSession(cwd, env, sessionId, now, harness) {
     const file = projectSessionPointerPath(cwd, env);
-    mkdirSync(path.dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify({ session_id: sessionId, updated_at: now })}\n`, {
-        mode: 0o600,
+    withFileLock(`${file}.lock`, () => {
+        atomicWriteFileSync(file, `${JSON.stringify({ session_id: sessionId, updated_at: now, harness })}\n`);
     });
 }
 /**
@@ -218,6 +345,9 @@ export function writeProjectSession(cwd, env, sessionId, now) {
  * into state nothing is watching.
  */
 export function readProjectSession(cwd, env, now, maxAgeMs = 24 * 3600 * 1000) {
+    return readProjectSessionPointer(cwd, env, now, maxAgeMs)?.sessionId ?? null;
+}
+export function readProjectSessionPointer(cwd, env, now, maxAgeMs = 24 * 3600 * 1000) {
     const file = projectSessionPointerPath(cwd, env);
     if (!existsSync(file))
         return null;
@@ -225,14 +355,39 @@ export function readProjectSession(cwd, env, now, maxAgeMs = 24 * 3600 * 1000) {
         const parsed = JSON.parse(readFileSync(file, 'utf8'));
         if (typeof parsed.session_id !== 'string' || parsed.session_id === '')
             return null;
-        if (typeof parsed.updated_at === 'number' && now - parsed.updated_at > maxAgeMs)
+        if (typeof parsed.updated_at !== 'number' || now - parsed.updated_at > maxAgeMs)
+            return null;
+        if (!HOOK_HARNESSES.includes(parsed.harness))
             return null;
-        return parsed.session_id;
+        // A pointer is routing evidence only while its session state still exists
+        // and parses. SessionEnd and explicit cleanup therefore invalidate it even
+        // when a crash prevented the pointer file itself from being removed.
+        const sessionFile = sessionStatePath(parsed.session_id, env);
+        if (!existsSync(sessionFile))
+            return null;
+        const state = JSON.parse(readFileSync(sessionFile, 'utf8'));
+        if (typeof state !== 'object' || state === null || Array.isArray(state))
+            return null;
+        return { sessionId: parsed.session_id, harness: parsed.harness };
     }
     catch {
         return null;
     }
 }
+const HOOK_HARNESSES = ['claude-code', 'codex', 'cursor', 'opencode'];
+function clearMatchingProjectSession(cwd, env, sessionId) {
+    const file = projectSessionPointerPath(cwd, env);
+    withFileLock(`${file}.lock`, () => {
+        try {
+            const parsed = JSON.parse(readFileSync(file, 'utf8'));
+            if (parsed.session_id === sessionId)
+                rmSync(file, { force: true });
+        }
+        catch {
+            // Missing/corrupt is already not a live pointer.
+        }
+    });
+}
 /**
  * Absent means the user is not at this machine's keyboard.
  *
@@ -283,11 +438,16 @@ export function isUserAway(state, config, now, idleSeconds) {
  * than about the user. Matches the project pointer's staleness horizon.
  */
 const MAX_PLAUSIBLE_SILENCE_MS = 24 * 3600 * 1000;
+/** Re-check local presence at this cadence while a pushed question is waiting. */
+const REPLY_PRESENCE_POLL_SECONDS = 5;
 /**
  * Push a question and block for the answer.
  *
- * An answered question is closed immediately: the first answer wins, and the
- * other devices must stop offering to change it. An unanswered one stays open,
+ * An answered question is closed the moment this wait sees the answer: the
+ * first device to answer claims the question and the others are told. Until
+ * that close, a later reply is a correction — so what this returns as "the"
+ * answer is always the latest reply, with the full stream alongside for
+ * free-text answers given in parts. An unanswered question stays open,
  * because nobody has acted on the silence yet and the next turn can still
  * collect the answer with `notifai replies`.
  */
@@ -309,9 +469,9 @@ async function askAndWait(ctx, options) {
         device: answerable,
         reply: true,
         replyWindow: Math.max(60, options.windowSeconds),
-        ...(options.choices !== undefined ? { replyChoice: options.choices } : {}),
+        questions: options.questions,
+        ...(options.detail !== undefined ? { detail: options.detail } : {}),
         collapseKey,
-        level: 'time_sensitive',
     });
     if (!build.ok)
         return { error: build.error };
@@ -325,17 +485,59 @@ async function askAndWait(ctx, options) {
         collapseKey,
         devices: answerable,
     });
-    const result = await ctx.waitForFirstReply(receipt.request_id, timeoutSeconds);
+    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,
-        reply: result.replies[0] ?? null,
+        // 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 === true,
+        degraded: result.degraded,
+        waited: true,
+        userReturned: result.userReturned,
     };
 }
+async function waitForReplyWhileAway(ctx, requestId, timeoutSeconds) {
+    const deadline = ctx.now() + timeoutSeconds * 1000;
+    let degraded = false;
+    let firstPoll = true;
+    for (;;) {
+        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 };
+            }
+        }
+        const remainingMs = Math.max(0, deadline - ctx.now());
+        if (!firstPoll && remainingMs === 0) {
+            return { replies: [], 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 };
+        }
+    }
+}
 /**
  * Healthy companion devices that implement replies. Both the iOS app and the
  * macOS app register reply categories and submit answers directly.
@@ -427,13 +629,18 @@ export function parkForRetirement(sessionId, env, pending, state) {
     const retirement = retiringQuestion(pending, state);
     if (retirement === null)
         return;
-    const current = readSessionState(sessionId, env);
-    const already = current.retiring ?? [];
-    if (already.some((entry) => entry.request_id === retirement.request_id))
-        return;
-    writeSessionState(sessionId, env, {
-        ...current,
-        retiring: [...already, retirement],
+    updateSessionState(sessionId, env, (current) => {
+        const already = current.retiring ?? [];
+        const existing = already.findIndex((entry) => entry.request_id === retirement.request_id);
+        if (existing < 0)
+            return { ...current, retiring: [...already, retirement] };
+        const retiring = [...already];
+        // An observed answer is final truth and upgrades an earlier supersession
+        // parked while the submission callback was racing a newer question.
+        if (retirement.state === 'answered' && retiring[existing].state !== 'answered') {
+            retiring[existing] = retirement;
+        }
+        return { ...current, retiring };
     });
 }
 /**
@@ -477,20 +684,19 @@ export async function drainRetirements(ctx, sessionId, env, session) {
     if (queue.length === 0)
         return [];
     const retired = [];
-    const remaining = [];
     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);
-        if (sent)
+        if (sent) {
             retired.push(entry.request_id);
-        else
-            remaining.push(entry);
-    }
-    // Re-read rather than reusing the snapshot: `notifai ask` may have parked
-    // another question while these were in flight.
-    const current = readSessionState(sessionId, env);
-    const untouched = (current.retiring ?? []).filter((entry) => !retired.includes(entry.request_id));
-    writeSessionState(sessionId, env, { ...current, retiring: untouched.length > 0 ? untouched : [] });
+            // Persist each success before touching the next entry. A later corrupt
+            // record or interrupted process must not resurrect work already done.
+            updateSessionState(sessionId, env, (current) => ({
+                ...current,
+                retiring: (current.retiring ?? []).filter((candidate) => candidate.request_id !== entry.request_id),
+            }));
+        }
+    }
     return retired;
 }
 function orphanQueuePath(env) {
@@ -509,23 +715,32 @@ function readOrphanQueue(env) {
         return [];
     }
 }
-function writeOrphanQueue(env, queue) {
+function writeOrphanQueueUnlocked(file, queue) {
+    atomicWriteFileSync(file, `${JSON.stringify(queue, null, 2)}\n`);
+}
+function updateOrphanQueue(env, update) {
     const file = orphanQueuePath(env);
-    mkdirSync(path.dirname(file), { recursive: true });
-    writeFileSync(file, `${JSON.stringify(queue, null, 2)}\n`, { mode: 0o600 });
+    return withFileLock(`${file}.lock`, () => {
+        const next = update(readOrphanQueue(env));
+        writeOrphanQueueUnlocked(file, next);
+        return next;
+    });
 }
 /** Move retirements into the global queue; deduped so a retry costs nothing. */
 export function orphanRetirements(env, entries, session, now) {
     if (entries.length === 0)
         return;
-    const queue = readOrphanQueue(env);
-    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 }));
-    if (added.length === 0)
-        return;
-    writeOrphanQueue(env, [...queue, ...added].slice(-ORPHAN_QUEUE_CAP));
+    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,
+        }));
+        return [...queue, ...added].slice(-ORPHAN_QUEUE_CAP);
+    });
 }
 /**
  * Retire everything a dead session left behind. Failures stay queued for the
@@ -542,20 +757,112 @@ export async function drainOrphanRetirements(ctx, env, now) {
         // and cheap, so treat it as due rather than letting it linger for ever.
         if (age > ORPHAN_TTL_MS) {
             done.push(entry.request_id);
+            updateOrphanQueue(env, (current) => current.filter((candidate) => candidate.request_id !== entry.request_id));
             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);
-        if (sent)
+        if (sent) {
             done.push(entry.request_id);
+            updateOrphanQueue(env, (current) => current.filter((candidate) => candidate.request_id !== entry.request_id));
+        }
     }
-    // Re-read: another session's SessionEnd may have queued more while these were
-    // in flight, and clobbering its write would recreate the very loss this
-    // queue exists to prevent.
-    const current = readOrphanQueue(env).filter((entry) => !done.includes(entry.request_id));
-    writeOrphanQueue(env, current);
     return done;
 }
+const LATE_STOP_POLL_SECONDS = 4;
+const LATE_PROMPT_POLL_SECONDS = 3;
+const MAX_CONTINUATION_COUNT = 3;
+/** One bounded recovery poll for a question that outlived its original wait. */
+async function pollPendingReply(ctx, pending, timeoutSeconds) {
+    if (pending.request_id === undefined) {
+        return { reply: null, replies: [], degraded: false, failed: false };
+    }
+    try {
+        const result = await ctx.waitForFirstReply(pending.request_id, timeoutSeconds);
+        return {
+            reply: result.replies.at(-1) ?? null,
+            replies: result.replies,
+            degraded: result.degraded === true,
+            failed: false,
+        };
+    }
+    catch {
+        return { reply: null, replies: [], degraded: true, failed: true };
+    }
+}
+/** The question set this pending record pushes, however it was registered. */
+function pendingQuestions(pending) {
+    return pending.questions ?? [{ id: 'q1', text: pending.question }];
+}
+/** Did any question in the set offer choices? Decides how replies combine. */
+function pendingHasChoices(pending) {
+    return pendingQuestions(pending).some((question) => question.choices !== undefined);
+}
+/**
+ * The answer as the agent should read it. For a question with choices the
+ * latest reply IS the answer — an earlier conflicting one was corrected by
+ * it. Free-text answers can arrive in parts, and every part reaches the
+ * agent in the order it was written, so it can tell expansion from
+ * correction itself.
+ */
+function answerContext(replies, hadChoices) {
+    const latest = replies.at(-1);
+    if (latest === undefined)
+        return 'Notifai — no answer was recorded.';
+    if (replies.length === 1 || hadChoices) {
+        return `Notifai — the user answered from ${latest.device_name}: "${latest.text}". Continue with that answer.`;
+    }
+    const parts = replies.map((reply) => `"${reply.text}"`).join(', then ');
+    return (`Notifai — the user answered from ${latest.device_name} in ${replies.length} parts, ` +
+        `in the order written: ${parts}. Later parts extend or correct earlier ones. ` +
+        'Continue with that answer.');
+}
+function userPromptAnswerOutput(replies, hadChoices) {
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'UserPromptSubmit',
+            additionalContext: answerContext(replies, hadChoices),
+        },
+    });
+}
+function stopAnswerOutput(replies, hadChoices) {
+    return JSON.stringify({ decision: 'block', reason: answerContext(replies, hadChoices) });
+}
+/**
+ * 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.
+ */
+async function finishPendingAnswer(ctx, envelope, sessionId, pending, reply, continuation) {
+    const retirement = retiringQuestion(pending, 'answered');
+    updateSessionState(sessionId, ctx.env, (current) => {
+        const retiring = [...(current.retiring ?? [])];
+        if (retirement !== null) {
+            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 next = { ...current, retiring };
+        if (samePending)
+            delete next.pending;
+        if (continuation) {
+            next.continuation = {
+                answered_at: ctx.now(),
+                count: (envelope.stop_hook_active === true ? current.continuation?.count ?? 0 : 0) + 1,
+            };
+        }
+        else {
+            next.last_prompt_at = ctx.now();
+        }
+        return next;
+    });
+    await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope));
+}
 // ---------------------------------------------------------------------------
 // UserPromptSubmit — the user is at the keyboard
 // ---------------------------------------------------------------------------
@@ -572,20 +879,41 @@ export async function handleUserPromptSubmit(ctx, envelope) {
         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);
+            }
+            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');
+        }
+    }
     // Park before dropping `pending`. If the process dies between these writes,
     // the next hook sees both copies and dedupes them; the old order could die in
     // the gap after erasing the only request/collapse/device identifiers.
-    if (pending !== undefined)
-        parkForRetirement(sessionId, ctx.env, pending, 'answered_elsewhere');
-    const parked = readSessionState(sessionId, ctx.env);
-    writeSessionState(sessionId, ctx.env, {
-        last_prompt_at: ctx.now(),
-        ...(parked.retiring !== undefined ? { retiring: parked.retiring } : {}),
+    updateSessionState(sessionId, ctx.env, (current) => {
+        const retiring = [...(current.retiring ?? [])];
+        if (current.pending !== undefined) {
+            const retirement = retiringQuestion(current.pending, 'answered_elsewhere');
+            if (retirement !== null &&
+                !retiring.some((entry) => entry.request_id === retirement.request_id)) {
+                retiring.push(retirement);
+            }
+        }
+        return { last_prompt_at: ctx.now(), ...(retiring.length > 0 ? { retiring } : {}) };
     });
-    // The bridge that lets a plain `notifai ask` find its own session: an agent
-    // shell command gets no hook payload and no harness exports the id.
-    if (envelope.cwd !== undefined)
-        writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now());
+    // The bridge that lets a plain `notifai ask` find the hook's canonical
+    // session: an agent shell command gets no hook payload, and not every
+    // harness exports an id in the same shape.
+    if (envelope.cwd !== undefined && ctx.harness !== undefined) {
+        writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness);
+    }
     const retired = await drainRetirements(ctx, sessionId, ctx.env, sessionLabel(ctx, envelope));
     const orphaned = await drainOrphanRetirements(ctx, ctx.env, ctx.now());
     const swept = [...retired, ...orphaned];
@@ -625,22 +953,41 @@ export async function handleStop(ctx, envelope) {
     if (swept.length > 0) {
         notes.push(`retired superseded question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`);
     }
-    // The harness sets this when it is already resuming us from a previous Stop
-    // decision. Pushing again here is how a question turns into nagging.
-    if (envelope.stop_hook_active === true) {
-        notes.push('already continuing from an answer; not asking again this turn');
-        return { notes };
-    }
     const state = readSessionState(sessionId, ctx.env);
     const pending = state.pending;
     if (!pending)
         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 };
+        }
         // 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(`already asked (${pending.request_id}); waiting for that answer`);
+        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 };
     }
+    // A Stop answer may immediately produce a legitimate follow-up question.
+    // Allow that new generation, but never re-run an old pending question and
+    // never let answer continuations become an unbounded agent loop.
+    if (envelope.stop_hook_active === true) {
+        const continuation = state.continuation;
+        const isNew = continuation !== undefined &&
+            pending.asked_at !== undefined &&
+            pending.asked_at > continuation.answered_at;
+        if (!isNew) {
+            notes.push('already continuing from an answer; not asking again this turn');
+            return { notes };
+        }
+        if (continuation.count >= MAX_CONTINUATION_COUNT) {
+            notes.push(`answer continuation limit (${MAX_CONTINUATION_COUNT}) reached; leaving the question in the terminal`);
+            return { notes };
+        }
+    }
     if (!ctx.config.ask_notifications.value)
         return { notes };
     if (!isUserAway(state, ctx.config, ctx.now(), ctx.idleSeconds())) {
@@ -657,14 +1004,14 @@ export async function handleStop(ctx, envelope) {
         return { notes };
     }
     try {
-        return await escalate(ctx, envelope, sessionId, state, pending, notes);
+        return await escalate(ctx, envelope, sessionId, pending, 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, state, pending, notes) {
+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());
@@ -675,26 +1022,45 @@ async function escalate(ctx, envelope, sessionId, state, pending, 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: 'A question from your agent',
-        body: pending.question,
-        ...(pending.choices !== undefined ? { choices: pending.choices } : {}),
+        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) => {
-            // Re-read: the drain at the top of this hook rewrote the queue, and the
-            // snapshot in `state` predates it.
-            writeSessionState(sessionId, ctx.env, {
-                ...readSessionState(sessionId, ctx.env),
-                pending: {
-                    ...pending,
-                    request_id: live.requestId,
-                    collapse_key: live.collapseKey,
-                    device_ids: live.devices,
-                },
+            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 };
             });
         },
     });
@@ -702,44 +1068,33 @@ async function escalate(ctx, envelope, sessionId, state, pending, notes) {
         notes.push(asked.error);
         return { notes };
     }
-    // What survives replacing the pending record. `retiring` has to: dropping it
-    // is exactly the class of bug this guards against — a delivered notification
-    // whose ids no longer exist anywhere.
-    const current = readSessionState(sessionId, ctx.env);
-    const carried = {
-        ...(state.last_prompt_at !== undefined ? { last_prompt_at: state.last_prompt_at } : {}),
-        ...(current.retiring !== undefined ? { retiring: current.retiring } : {}),
-    };
     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.
-        writeSessionState(sessionId, ctx.env, {
-            ...carried,
-            pending: {
-                ...pending,
-                request_id: asked.requestId,
-                collapse_key: asked.collapseKey,
-                device_ids: asked.devices,
-            },
-        });
-        notes.push(asked.degraded
-            ? `could not reach the server to find out whether you answered; check with: notifai replies ${asked.requestId}`
-            : `no answer in time; retrieve it later with: notifai replies ${asked.requestId}`);
+        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');
+        }
+        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`);
+        }
         return { notes };
     }
-    // Answered and closed — nothing left to retire.
-    writeSessionState(sessionId, ctx.env, carried);
-    await retire(ctx, asked.collapseKey, 'Answered', asked.reply.text, 'answered', asked.requestId, asked.devices, sessionLabel(ctx, envelope));
+    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}`);
     return {
-        stdout: JSON.stringify({
-            decision: 'block',
-            // Harnesses render a Stop decision under an error-ish label, so this
-            // text must read as an answer on its own rather than as a failure.
-            reason: `NotifAI — the user answered from ${asked.reply.device_name}: ` +
-                `"${asked.reply.text}". Continue with that answer.`,
-        }),
+        stdout: stopAnswerOutput(asked.replies, pendingHasChoices(pending)),
         notes,
     };
 }
@@ -759,6 +1114,8 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
     const sessionId = envelope.session_id;
     if (!sessionId)
         return { notes };
+    if (envelope.cwd !== undefined)
+        clearMatchingProjectSession(envelope.cwd, env, sessionId);
     const state = readSessionState(sessionId, env);
     const orphans = [...(state.retiring ?? [])];
     const pending = state.pending;
@@ -801,17 +1158,24 @@ export function handleSessionEnd(env, envelope, now = Date.now()) {
  * agent's live one would be worse than the staleness this fixes.
  */
 export function registerQuestion(sessionId, env, question, now = Date.now()) {
-    const state = readSessionState(sessionId, env);
-    if (state.pending !== undefined)
-        parkForRetirement(sessionId, env, state.pending, 'superseded');
-    // Re-read: parkForRetirement wrote the queue we must not clobber.
-    writeSessionState(sessionId, env, {
-        ...readSessionState(sessionId, env),
-        pending: {
-            asked_at: now,
-            ...question,
-            question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
-        },
+    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);
+            }
+        }
+        return {
+            ...state,
+            ...(retiring.length > 0 ? { retiring } : {}),
+            pending: {
+                asked_at: now,
+                ...question,
+                question: question.question.slice(0, MAX_STORED_QUESTION_CHARS),
+            },
+        };
     });
 }
 /** Parses hook JSON from stdin, tolerating an empty or malformed body. */