@raidiant/notifai 0.5.0 → 1.0.0

package/dist/hooks.js

@@ -6,7 +6,7 @@ import { loadConfig, projectSessionPointerPath, sanitizeSessionId, sessionConfig
 import { buildDraft } from './send.js';
 import { atomicWriteFileSync } from './atomic-file.js';
 import { withFileLock } from './file-lock.js';
-import { HARNESS_CAPABILITIES, HARNESSES, HOOK_TIMING } from './harnesses.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
@@ -20,58 +20,46 @@ function summarizeRequestIds(entries) {
     const ids = entries.flatMap((entry) => entry.request_id === undefined ? [] : [entry.request_id]);
     return { ids, display: ids.join(', ') };
 }
-/** How often the grace window rechecks whether the user has come back. */
-const GRACE_POLL_MS = 5_000;
 /**
- * Total seconds the complete Stop invocation may own. Generated adapters grant
- * another minute of host headroom, because a killed hook can lose an answer
- * the user has already given. Grace and reply waiting share this budget while
- * the reply retains a small actionable window and finalization reserve.
+ * The waiter's whole wall clock: the terminal-first timer, submission, and the
+ * wait for an answer, from the moment the turn-end hook starts.
+ *
+ * One plain ceiling, deliberately not a budget carved into reserves. The
+ * reserves existed to fit every phase inside a *held* turn; on Claude Code the
+ * turn is not held any more, and on a host that still holds one the useful
+ * question is only how long that host is willing to wait in total.
+ */
+export const WAITER_CEILING_SECONDS = 480;
+/**
+ * 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 STOP_BUDGET_SECONDS = HOOK_TIMING.totalSeconds;
-const MIN_REPLY_WAIT_SECONDS = HOOK_TIMING.minimumReplySeconds;
+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
  * devices.
  *
- * Holding a blocking Stop hook open is normally hostile — while it blocks, the
- * harness cannot show its prompt either, so a user wanting to answer locally is
- * locked out. What makes it safe is that the wait is abandoned the moment the
- * user touches the keyboard or mouse. The block therefore only ever persists
- * while they are demonstrably not using the machine, which costs them nothing.
- *
- * That safety depends entirely on the idle signal, so with no idle source this
- * refuses to wait at all rather than holding a terminal it cannot monitor.
+ * A plain timer, and nothing else. It once polled an idle signal so it could
+ * abandon the wait the moment the user touched the keyboard — necessary while
+ * the wait blocked the terminal, because a user wanting to answer locally was
+ * otherwise locked out of their own prompt. Nothing is monopolised now, so
+ * there is nothing to watch for and no machine this cannot run on.
  *
- * With `require_idle` off the whole calculus changes: the user has said they
- * want the question to reach them whether or not they are at the keyboard, so
- * there is nothing to watch for and this becomes what its name always claimed —
- * a plain timer. It then works on machines with no idle source too.
+ * The window is measured from registration, not from the turn's end: a
+ * question the agent asked five minutes ago while it kept working has already
+ * served its wait. A stamp from the future would otherwise consume the whole
+ * ceiling and leave no room to answer, so it starts no later than now.
  */
-export async function awaitGrace(ctx, askedAt) {
-    const threshold = ctx.config.away_after_seconds.value;
-    // Keep a real device-answer window even when a user selects maximum grace.
-    const graceSeconds = Math.min(ctx.config.ask_grace_seconds.value, HOOK_TIMING.maxGraceSeconds);
-    // `asked_at` is wall-clock too, and the same jumps apply: a stamp from the
-    // future would wait far past the hook's budget, one from the distant past
-    // would skip the terminal-first window the user asked for entirely. Anything
-    // outside a plausible range restarts the window from now.
-    const elapsed = ctx.now() - askedAt;
-    const start = elapsed >= 0 && elapsed <= MAX_PLAUSIBLE_SILENCE_MS ? askedAt : ctx.now();
-    const deadline = start + graceSeconds * 1000;
-    for (;;) {
-        if (ctx.config.require_idle.value) {
-            const idle = ctx.idleSeconds();
-            if (idle === null)
-                return 'no-signal';
-            if (idle < threshold)
-                return 'user-returned';
-        }
-        if (ctx.now() >= deadline)
-            return 'absent';
-        await ctx.sleep(Math.min(GRACE_POLL_MS, Math.max(0, deadline - ctx.now())));
-    }
+async function awaitTerminalFirstWindow(ctx, askedAt, ceilingAt) {
+    const graceSeconds = ctx.config.ask_grace_seconds.value;
+    if (graceSeconds <= 0)
+        return;
+    const until = Math.min(Math.min(askedAt, ctx.now()) + graceSeconds * 1000, ceilingAt);
+    const remaining = until - ctx.now();
+    if (remaining > 0)
+        await ctx.sleep(remaining);
 }
 function sessionStatePath(sessionId, env) {
     return path.join(stateDir(env), 'sessions', `${sanitizeSessionId(sessionId)}.json`);
@@ -179,7 +167,7 @@ export function pruneAbandonedSessions(env, now = Date.now(), maxAgeMs = SESSION
  * known-dead PID is recoverable immediately. Only legacy/corrupt claims with
  * no trustworthy PID fall back to an age limit.
  */
-const CLAIM_TTL_MS = STOP_BUDGET_SECONDS * 1000;
+const CLAIM_TTL_MS = WAITER_CEILING_SECONDS * 1000;
 const heldClaims = new Map();
 export function claimQuestionPush(sessionId, env, now = Date.now(), beforeStaleReplace) {
     const file = claimPath(sessionId, env);
@@ -354,9 +342,16 @@ function readStoredProjectSessionPointers(file) {
 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) {
+/**
+ * Every session that has fired a hook in this directory recently, newest first.
+ *
+ * This is the only local record of which harness sessions are actually alive
+ * here, which makes it the tiebreaker when the environment alone cannot say
+ * which harness owns the current shell.
+ */
+export function readLiveProjectSessionPointers(cwd, env, now, maxAgeMs = 24 * 3600 * 1000) {
     const file = projectSessionPointerPath(cwd, env);
-    const live = readStoredProjectSessionPointers(file)
+    return readStoredProjectSessionPointers(file)
         .filter((entry) => now - entry.updatedAt <= maxAgeMs)
         .filter((entry) => {
         try {
@@ -373,32 +368,20 @@ export function readProjectSessionPointer(cwd, env, now, maxAgeMs = 24 * 3600 *
             return false;
         }
     })
-        .sort((left, right) => right.updatedAt - left.updatedAt);
-    const latest = live[0];
+        .sort((left, right) => right.updatedAt - left.updatedAt)
+        .map((entry) => ({
+        sessionId: entry.sessionId,
+        harness: entry.harness,
+        updatedAt: entry.updatedAt,
+    }));
+}
+export function readProjectSessionPointer(cwd, env, now, maxAgeMs = 24 * 3600 * 1000) {
+    const latest = readLiveProjectSessionPointers(cwd, env, now, maxAgeMs)[0];
     return latest === undefined ? null : { sessionId: latest.sessionId, harness: latest.harness };
 }
 export function readMatchingProjectSessionPointer(cwd, env, now, sessionId, harness, maxAgeMs = 24 * 3600 * 1000) {
-    const file = projectSessionPointerPath(cwd, env);
-    const match = readStoredProjectSessionPointers(file).find((entry) => entry.sessionId === sessionId &&
-        entry.harness === harness &&
-        now - entry.updatedAt <= maxAgeMs);
-    if (match === undefined)
-        return null;
-    try {
-        // 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(match.sessionId, 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: match.sessionId, harness: match.harness };
-    }
-    catch {
-        return null;
-    }
+    const match = readLiveProjectSessionPointers(cwd, env, now, maxAgeMs).find((entry) => entry.sessionId === sessionId && entry.harness === harness);
+    return match === undefined ? null : { sessionId: match.sessionId, harness: match.harness };
 }
 function clearMatchingProjectSession(cwd, env, sessionId) {
     const file = projectSessionPointerPath(cwd, env);
@@ -417,61 +400,14 @@ function clearMatchingProjectSession(cwd, env, sessionId) {
         })}\n`);
     });
 }
-/**
- * Absent means the user is not at this machine's keyboard.
- *
- * OS idle time answers that directly, so where it exists it decides alone.
- * Silence since the user's last prompt is only ever a proxy for it, and a poor
- * one — it is wrong in both directions:
- *
- *   - Too long: it counts the agent's own turn, so a user watching a build was
- *     read as absent and had the question pushed at them.
- *   - Too short: a session that has just been spawned always has a fresh
- *     prompt, so its FIRST question could never escalate however long its
- *     owner had been gone. That is the "kick off some agents and
- *     walk away" case this feature mainly exists for, and requiring both
- *     signals to agree is what broke it.
- *
- * The proxy therefore survives only as the fallback for machines with no idle
- * source. There, never having seen a prompt is not evidence of absence — it is
- * a missing `UserPromptSubmit` hook — so it resolves to "present".
- *
- * Answering from a companion device does not make the user present; only touching this
- * machine does. Answering on a device is evidence of being away from it.
- *
- * All of which only matters if presence is being consulted at all. With
- * `require_idle` off the user has said their whereabouts are not a
- * precondition, so this stops guessing and answers yes.
- */
-export function isUserAway(state, config, now, idleSeconds) {
-    if (!config.require_idle.value)
-        return true;
-    const threshold = config.away_after_seconds.value;
-    if (idleSeconds !== null)
-        return idleSeconds >= threshold;
-    if (state.last_prompt_at === undefined)
-        return false;
-    const silence = now - state.last_prompt_at;
-    // Both signs of a clock jump produce a wrong answer here, and the fallback
-    // path has no monotonic reference to check against: a forward jump (NTP
-    // correction, VM resume) hijacks a terminal whose user is sitting right
-    // there, and a backward one suppresses escalation for someone genuinely
-    // gone. Neither delta is evidence of anything, so it resolves the way every
-    // other absence of evidence does — present.
-    if (silence < 0 || silence > MAX_PLAUSIBLE_SILENCE_MS)
-        return false;
-    return silence >= threshold * 1000;
+function gate(ctx, verdict, reason, data = {}) {
+    ctx.log?.info('hook.gate', { verdict, reason, stage: 'queued', ...data });
 }
 /**
- * Beyond this, silence says more about the clock or an abandoned session file
- * than about the user. Matches the project pointer's staleness horizon.
+ * One round of the waiter's reply poll. Short enough that several questions
+ * still share one wall clock, long enough not to hammer the server.
  */
-const MAX_PLAUSIBLE_SILENCE_MS = 24 * 3600 * 1000;
-function gate(ctx, verdict, reason, data = {}) {
-    ctx.log?.info('hook.gate', { verdict, reason, ...data });
-}
-/** Re-check local presence at this cadence while a pushed question is waiting. */
-const REPLY_PRESENCE_POLL_SECONDS = 5;
+const REPLY_POLL_SECONDS = 5;
 /**
  * Push a question and block for the answer.
  *
@@ -531,29 +467,26 @@ async function submitQuestion(ctx, intent) {
     return receipt;
 }
 /**
- * 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.
+ * The waiter's wait: one bounded poll across every live question at once.
+ *
+ * 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. A question whose polling is permanently rejected drops out of
+ * the round rather than failing the whole wait.
  */
-async function waitForAnyReplyWhileAway(ctx, requestIds, timeoutSeconds, monitorPresence = true) {
+async function waitForAnyReply(ctx, requestIds, timeoutSeconds) {
     const deadline = ctx.now() + timeoutSeconds * 1000;
     let degraded = false;
     let firstPoll = true;
     const permanentFailures = new Map();
     for (;;) {
-        if (monitorPresence && ctx.config.require_idle.value) {
-            const idle = ctx.idleSeconds();
-            if (idle !== null && idle < ctx.config.away_after_seconds.value) {
-                return { byRequest: new Map(), degraded, userReturned: true, permanentFailures };
-            }
-        }
         const remainingMs = Math.max(0, deadline - ctx.now());
         if (!firstPoll && remainingMs === 0) {
-            return { byRequest: new Map(), degraded, userReturned: false, permanentFailures };
+            return { byRequest: new Map(), degraded, permanentFailures };
         }
         firstPoll = false;
-        const pollSeconds = Math.min(REPLY_PRESENCE_POLL_SECONDS, Math.max(0, Math.ceil(remainingMs / 1000)));
+        const pollSeconds = Math.min(REPLY_POLL_SECONDS, Math.max(0, Math.ceil(remainingMs / 1000)));
         const results = await Promise.all(requestIds
             .filter((requestId) => !permanentFailures.has(requestId))
             .map(async (requestId) => {
@@ -582,7 +515,7 @@ async function waitForAnyReplyWhileAway(ctx, requestIds, timeoutSeconds, monitor
                 byRequest.set(result.requestId, result.replies);
         }
         if (byRequest.size > 0 || permanentFailures.size === requestIds.length) {
-            return { byRequest, degraded, userReturned: false, permanentFailures };
+            return { byRequest, degraded, permanentFailures };
         }
     }
 }
@@ -840,7 +773,15 @@ export async function drainOrphanRetirements(ctx, env, now) {
 }
 const LATE_STOP_POLL_SECONDS = 4;
 const LATE_PROMPT_POLL_SECONDS = 3;
-const MAX_CONTINUATION_COUNT = 3;
+/**
+ * The one bound on answer deliveries, for every route.
+ *
+ * It caps two things that both used to be able to run away: how many times a
+ * single accepted answer may be handed to a route before the journal gives up
+ * on it, and how many answer-driven continuation generations one chain may
+ * produce.
+ */
+export 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) {
@@ -878,6 +819,7 @@ function finalizedAnswer(finalized) {
 function reportAnswer(ctx, notes, answered, late) {
     ctx.log?.info('hook.answer', {
         answered: true,
+        stage: 'queued',
         ...(late ? { late: true } : {}),
         request_id: answered.pending.request_id,
         device: answered.reply.device_name,
@@ -931,18 +873,27 @@ function pendingHasChoices(pending) {
  * 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.
+ *
+ * The continuation repeats only identity the agent actually registered and
+ * the answer the server accepted. It never invents trust, urgency, permission,
+ * or approval claims for the transport to assert.
  */
-function answerContext(replies, hadChoices) {
+function answerContext(answered) {
+    const { pending, replies } = answered;
     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.');
+    const answeredQuestionIds = [...new Set(latest.answers.map((answer) => answer.question_id))];
+    const identity = answeredQuestionIds.length === 0
+        ? ''
+        : `question_id${answeredQuestionIds.length === 1 ? '' : 's'} ${answeredQuestionIds.join(', ')}, `;
+    const question = `question ${JSON.stringify(pending.question)}`;
+    if (replies.length === 1 || pendingHasChoices(pending)) {
+        return `Notifai — ${identity}${question}; the user answered ${JSON.stringify(latest.text)}.`;
+    }
+    const parts = replies.map((reply) => JSON.stringify(reply.text)).join(', then ');
+    return (`Notifai — ${identity}${question}; the user answered in ${replies.length} parts, ` +
+        `in the order written: ${parts}. Later parts extend or correct earlier ones.`);
 }
 /**
  * Every answer that has arrived, as one message. Several registered questions
@@ -955,17 +906,18 @@ function answersContext(answered, remaining) {
         ? ` (${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;
+        return answerContext(answered[0]) + 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})`;
+            ? JSON.stringify(latest.text)
+            : `${replies.map((reply) => JSON.stringify(reply.text)).join(', then ')} (parts in the order written; later parts extend or correct earlier ones)`;
+        const ids = [...new Set(latest.answers.map((entry) => entry.question_id))];
+        const identity = ids.length === 0 ? '' : `question_id${ids.length === 1 ? '' : 's'} ${ids.join(', ')}: `;
+        return `- ${identity}${JSON.stringify(pending.question)} → ${answer}`;
     });
-    return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}\nContinue with these answers.${tail}`;
+    return `Notifai — the user answered ${answered.length} questions:\n${lines.join('\n')}${tail}`;
 }
 function stopAnswerOutput(context) {
     return JSON.stringify({
@@ -980,15 +932,16 @@ function stopAnswerOutput(context) {
  * UserPromptSubmit answers ride the user's new turn.
  */
 function stageAcceptedAnswers(ctx, sessionId, answered, remaining) {
+    const accepted = {
+        answers: answered,
+        remaining,
+        recorded_at: ctx.now(),
+    };
     updateSessionState(sessionId, ctx.env, (current) => {
         const pendingRemaining = pendingList(current).filter((entry) => !answered.some(({ pending }) => isSamePending(entry, pending)));
         const next = {
             ...current,
-            accepted: {
-                answers: answered,
-                remaining,
-                recorded_at: ctx.now(),
-            },
+            accepted,
         };
         if (pendingRemaining.length > 0)
             next.pending = pendingRemaining;
@@ -996,8 +949,20 @@ function stageAcceptedAnswers(ctx, sessionId, answered, remaining) {
             delete next.pending;
         return next;
     });
+    return accepted;
 }
-/** Settle only after a successor hook proves the harness received the answer. */
+/** Amend the live accepted record in place, without resurrecting a settled one. */
+function amendAcceptedAnswers(ctx, sessionId, amend) {
+    updateSessionState(sessionId, ctx.env, (current) => current.accepted === undefined ? current : { ...current, accepted: amend(current.accepted) });
+}
+/**
+ * Retire the answered questions and close the journal.
+ *
+ * Called once an answer's delivery is acknowledged — by the route's own write,
+ * or by the successor Stop of a blocking continuation. The continuation counter
+ * grows with each settled generation, so the cap that bounds chained
+ * answer-to-question loops is a real count rather than a constant 1.
+ */
 function settleAcceptedAnswers(ctx, sessionId, accepted) {
     const retirements = accepted.answers
         .map(({ pending }) => retiringQuestion(pending, 'answered'))
@@ -1015,7 +980,7 @@ function settleAcceptedAnswers(ctx, sessionId, accepted) {
         delete next.accepted;
         next.continuation = {
             answered_at: accepted.recorded_at,
-            count: accepted.continuation_count ?? 1,
+            count: (current.continuation?.count ?? 0) + 1,
         };
         return next;
     });
@@ -1068,7 +1033,9 @@ export async function handleUserPromptSubmit(ctx, envelope) {
         if (envelope.cwd !== undefined && ctx.harness !== undefined) {
             writeProjectSession(envelope.cwd, ctx.env, sessionId, ctx.now(), ctx.harness);
         }
-        notes.push('a device answer is safely journaled; the next Stop will deliver it');
+        notes.push(state.accepted.delivered_at === undefined
+            ? 'a device answer is safely journaled; the next Stop will deliver it'
+            : 'a device answer has already been delivered; the next Stop will close it out');
         return { notes };
     }
     const live = pendingList(state).filter((entry) => entry.request_id !== undefined);
@@ -1115,7 +1082,14 @@ export async function handleUserPromptSubmit(ctx, envelope) {
             ...(unasked.length > 0 ? { pending: unasked } : {}),
             ...(retiring.length > 0 ? { retiring } : {}),
             ...(current.accepted === undefined ? {} : { accepted: current.accepted }),
-            ...(current.continuation === undefined ? {} : { continuation: current.continuation }),
+            // 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
+            // first, and a wake route's injected message always arrives while its own
+            // answer is still journaled, so it can never pass for the user's presence.
+            ...(current.continuation === undefined
+                ? {}
+                : { continuation: { ...current.continuation, count: 0 } }),
         };
     });
     // The bridge that lets a plain `notifai ask` find the hook's canonical
@@ -1147,14 +1121,27 @@ export async function handleUserPromptSubmit(ctx, envelope) {
  * `notifai ask`. Guessing from the last assistant message was the alternative
  * and it is not worth it: a false positive here hijacks the terminal.
  */
-export async function handleStop(ctx, envelope, processDeadlineAt = ctx.now() + STOP_BUDGET_SECONDS * 1000) {
-    const notes = [];
-    const hardDeadlineAt = processDeadlineAt;
+export async function handleStop(ctx, envelope, processDeadlineAt = ctx.now() + WAITER_CEILING_SECONDS * 1000, route = hookContinuationRoute()) {
     const sessionId = envelope.session_id;
     if (!sessionId) {
-        gate(ctx, 'held', 'no-session');
-        return { notes };
-    }
+        gate(ctx, 'held', 'no-session', { stage: 'queued' });
+        return { notes: [] };
+    }
+    return runEscalationWaiter(ctx, {
+        sessionId,
+        envelope,
+        route,
+        processDeadlineAt,
+    });
+}
+/**
+ * Own one registered question pipeline from its terminal-first timer through
+ * its final delivery or retirement. Hosts differ only in the injected route.
+ */
+export async function runEscalationWaiter(ctx, options) {
+    const notes = [];
+    const { sessionId, envelope } = options;
+    const hardDeadlineAt = options.processDeadlineAt ?? ctx.now() + WAITER_CEILING_SECONDS * 1000;
     // This event marker is diagnostic evidence in its own right. Record it
     // before every early return so doctor can distinguish a working Stop route
     // from the prompt-only state that previously looked healthy.
@@ -1162,49 +1149,39 @@ export async function handleStop(ctx, envelope, processDeadlineAt = ctx.now() +
         ...current,
         last_stop_at: ctx.now(),
     }));
-    // Claim before any reply poll, not only before the grace window. Two racing
-    // Stops can both observe the same accepted journal or live request. An
-    // atomic state update cannot retract duplicate block output a loser already
-    // built, so one session claim owns the complete Stop decision: accepted
-    // replay/ack, late-answer collection, cleanup, and any new escalation.
-    //
-    // Real clock, deliberately, not `ctx.now` — the claim answers "is another
-    // process alive right now", which the injectable clock cannot speak to. It
-    // is also the only clock the *other* process shares.
+    // The waiter, not its host, owns this lease. It spans grace, submission,
+    // polling, close fencing, route delivery, and every retirement path.
+    // Real clock, deliberately, not `ctx.now` — the claim answers whether
+    // another process is alive right now, which an injected clock cannot know.
     if (!claimQuestionPush(sessionId, ctx.env)) {
-        gate(ctx, 'held', 'claimed-elsewhere');
+        gate(ctx, 'held', 'claimed-elsewhere', { stage: 'queued' });
         notes.push('another hook is already handling this question');
         return { notes };
     }
+    let settledAnswerThisPass = false;
     try {
         let state = readSessionState(sessionId, ctx.env);
         if (state.accepted !== undefined) {
             const accepted = state.accepted;
-            // A recursive Stop is emitted only after the previous Stop's blocking
-            // output was admitted and the continued model turn ran. That event is
-            // the acknowledgment: persisting a separate "offered" bit before stdout
-            // would recreate the crash gap this journal exists to close.
-            const deliveryProven = envelope.stop_hook_active === true;
+            // Acknowledgement is per route, because routes end in different places.
+            //
+            // A blocking continuation ends at this process's stdout, which the
+            // harness reads only after the process exits: the recursive Stop's
+            // `stop_hook_active` is the acknowledgement, and persisting a separate
+            // "offered" bit before stdout would recreate the crash gap this journal
+            // exists to close. An out-of-band route ends at a write this process made
+            // itself and recorded here. A socket write is not proof the model acted
+            // on the answer — delivery is not consumption — but nothing later can
+            // prove more, and an answer redelivered without end is strictly worse
+            // than one settled on delivery. So a recorded delivery settles.
+            const deliveryProven = accepted.delivered_at !== undefined || envelope.stop_hook_active === true;
             if (!deliveryProven) {
-                updateSessionState(sessionId, ctx.env, (current) => {
-                    if (current.accepted === undefined)
-                        return current;
-                    return {
-                        ...current,
-                        accepted: {
-                            ...current.accepted,
-                            continuation_count: (current.continuation?.count ?? 0) + 1,
-                        },
-                    };
-                });
                 for (const answer of accepted.answers)
                     reportAnswer(ctx, notes, answer, true);
-                return {
-                    stdout: stopAnswerOutput(answersContext(accepted.answers, accepted.remaining)),
-                    notes,
-                };
+                return await deliverAcceptedAnswers(ctx, sessionId, options.route, accepted, notes);
             }
             settleAcceptedAnswers(ctx, sessionId, accepted);
+            settledAnswerThisPass = true;
             state = readSessionState(sessionId, ctx.env);
         }
         const pending = pendingList(state);
@@ -1216,17 +1193,114 @@ export async function handleStop(ctx, envelope, processDeadlineAt = ctx.now() +
             if (swept.length > 0) {
                 notes.push(`retired question${swept.length > 1 ? 's' : ''} ${swept.join(', ')}`);
             }
-            gate(ctx, 'held', 'no-question');
+            gate(ctx, 'held', 'no-question', { stage: 'queued' });
             return { notes };
         }
-        return await handleClaimedStop(ctx, envelope, sessionId, state, pending, notes, hardDeadlineAt);
+        return await handleClaimedStop(ctx, envelope, sessionId, state, pending, notes, hardDeadlineAt, options.route, 
+        // Every route's successor turn-end, named the same way: the harness flag
+        // for a blocking continuation, and the settle above for a route that woke
+        // a brand-new turn out of band.
+        envelope.stop_hook_active === true || settledAnswerThisPass);
     }
     finally {
         releaseQuestionPush(sessionId, ctx.env);
     }
 }
+/**
+ * The blocking Stop hook's own last meter: the answer becomes this process's
+ * stdout, and the harness admits it as a new user turn. Exported because a
+ * host adapter that has other routes still falls back to this one.
+ */
+export function hookContinuationRoute() {
+    return {
+        kind: 'hook-continuation',
+        deliver: async (event) => ({
+            stdout: stopAnswerOutput(event.context),
+            notes: [],
+            // The harness reads this stdout after the process exits, so only the
+            // successor Stop can acknowledge it.
+            acknowledgement: 'stdout',
+        }),
+    };
+}
+/**
+ * Hand one accepted answer to a route and record what the attempt proved.
+ *
+ * Every delivery on every route passes through here, which is what makes the
+ * cap below a backstop rather than a suggestion. A guard only one route
+ * consults is not a backstop: that is how a single answer once reached a
+ * session 250 times.
+ */
+async function deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes) {
+    const { answers: answered, remaining } = accepted;
+    const requestIds = summarizeRequestIds(answered.map((entry) => entry.pending)).ids;
+    const attempt = (accepted.delivery_attempts ?? 0) + 1;
+    if (attempt > MAX_CONTINUATION_COUNT) {
+        gate(ctx, 'held', 'delivery-limit', {
+            route: route.kind,
+            attempts: accepted.delivery_attempts ?? 0,
+            limit: MAX_CONTINUATION_COUNT,
+            request_ids: requestIds,
+        });
+        // Settle rather than journal for ever. The answer has been offered as often
+        // as any working route could need, it is already in the notes of each of
+        // those turns, and the questions it answered still deserve retirement.
+        settleAcceptedAnswers(ctx, sessionId, accepted);
+        notes.push(`the user's answer reached the ${route.kind} route ${MAX_CONTINUATION_COUNT} times without being acknowledged; not delivering it again`);
+        return { notes };
+    }
+    // Count the attempt before making it: an attempt that dies mid-delivery still
+    // happened, and a counter written afterwards could be evaded by crashing.
+    amendAcceptedAnswers(ctx, sessionId, (current) => ({
+        ...current,
+        delivery_attempts: attempt,
+    }));
+    ctx.log?.info('hook.gate', {
+        verdict: 'proceeding',
+        reason: 'answered',
+        stage: 'routed',
+        route: route.kind,
+        answers: answered.length,
+        request_ids: requestIds,
+        journal_recorded_at: accepted.recorded_at,
+        delivery_attempt: attempt,
+    });
+    const delivered = await route.deliver({
+        context: answersContext(answered, remaining),
+        answers: answered.length,
+        remaining,
+        request_ids: requestIds,
+        journal_recorded_at: accepted.recorded_at,
+    });
+    const deliveredRoute = typeof delivered.log?.['route'] === 'string' ? delivered.log['route'] : route.kind;
+    const deliveredStage = typeof delivered.log?.['stage'] === 'string' ? delivered.log['stage'] : 'delivered';
+    if (delivered.acknowledgement === 'delivered') {
+        amendAcceptedAnswers(ctx, sessionId, (current) => ({
+            ...current,
+            delivered_at: ctx.now(),
+            delivered_route: deliveredRoute,
+        }));
+    }
+    ctx.log?.info('hook.answer', {
+        answered: true,
+        stage: deliveredStage,
+        route: deliveredRoute,
+        acknowledgement: delivered.acknowledgement,
+        delivery_attempt: attempt,
+        request_ids: requestIds,
+        answers: answered.length,
+        journal_recorded_at: accepted.recorded_at,
+        ...(delivered.log?.['reason'] === undefined ? {} : { reason: delivered.log['reason'] }),
+    });
+    const outcome = { notes: [...notes, ...(delivered.notes ?? [])] };
+    if (delivered.stdout !== undefined)
+        outcome.stdout = delivered.stdout;
+    if (delivered.log !== undefined)
+        outcome.log = delivered.log;
+    return outcome;
+}
 /** The complete per-session Stop decision, after this process owns the claim. */
-async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes, hardDeadlineAt) {
+async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes, hardDeadlineAt, route, continuingFromAnswer) {
     const live = pending.filter((entry) => entry.request_id !== undefined);
     const unasked = pending.filter((entry) => entry.request_id === undefined);
     let liveToEscalate = live;
@@ -1259,16 +1333,12 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
                 }
                 return { ...entry, replies, reply: replies.at(-1) };
             });
-            stageAcceptedAnswers(ctx, sessionId, authoritative, pending.length - authoritative.length - permanentlyRejected.length);
-            gate(ctx, 'proceeding', 'answered', { answers: authoritative.length });
+            const accepted = stageAcceptedAnswers(ctx, sessionId, authoritative, pending.length - authoritative.length - permanentlyRejected.length);
             for (const answer of authoritative)
                 reportAnswer(ctx, notes, answer, true);
             // 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(authoritative, pending.length - authoritative.length - permanentlyRejected.length)),
-                notes,
-            };
+            return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes);
         }
         const recoverableLive = live.filter((entry) => !permanentFailures.has(entry.request_id));
         liveToEscalate = recoverableLive;
@@ -1279,7 +1349,7 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
             // questions remain. The next Stop is their successor owner: keep waiting
             // to the original absolute deadline instead of polling for four seconds
             // and abandoning them.
-            return await escalate(ctx, envelope, sessionId, [], recoverableLive, notes, hardDeadlineAt);
+            return await escalate(ctx, envelope, sessionId, [], recoverableLive, notes, hardDeadlineAt, route);
         }
         // Questions registered after the earlier push still owe the user their
         // notification; fall through and escalate just those.
@@ -1296,14 +1366,22 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
             notes.push('already continuing from an answer; not asking again this turn');
             return { notes };
         }
-        if (continuation.count >= MAX_CONTINUATION_COUNT) {
-            gate(ctx, 'held', 'continuation-limit', {
-                count: continuation.count,
-                limit: MAX_CONTINUATION_COUNT,
-            });
-            notes.push(`answer continuation limit (${MAX_CONTINUATION_COUNT}) reached; leaving the question in the terminal`);
-            return { notes };
-        }
+    }
+    // The cap is deliberately not keyed to `stop_hook_active`. That flag names one
+    // route's continuation; a route that wakes a brand-new turn never sets it, and
+    // a limit only one route consults bounds only that route. `continuingFromAnswer`
+    // is the same event named for every route, so the chain of answer → follow-up
+    // question → answer is bounded whatever delivered it.
+    if (continuingFromAnswer &&
+        state.continuation !== undefined &&
+        state.continuation.count >= MAX_CONTINUATION_COUNT) {
+        gate(ctx, 'held', 'continuation-limit', {
+            count: state.continuation.count,
+            limit: MAX_CONTINUATION_COUNT,
+            route: route.kind,
+        });
+        notes.push(`answer continuation limit (${MAX_CONTINUATION_COUNT}) reached; leaving the question in the terminal`);
+        return { notes };
     }
     // Silent to the user by design — they switched routing off, so saying so on
     // every turn would be nagging about their own setting. That silence is also
@@ -1313,61 +1391,46 @@ async function handleClaimedStop(ctx, envelope, sessionId, state, pending, notes
         gate(ctx, 'held', 'notifications-off', { source: ctx.config.ask_notifications.source });
         return { notes };
     }
-    const idle = ctx.idleSeconds();
-    if (!isUserAway(state, ctx.config, ctx.now(), idle)) {
-        gate(ctx, 'held', 'user-present', {
-            idle_seconds: idle,
-            away_after_seconds: ctx.config.away_after_seconds.value,
-            require_idle: ctx.config.require_idle.value,
-            last_prompt_at: state.last_prompt_at ?? null,
-        });
-        notes.push('you are at the keyboard; leaving the question in the terminal');
-        return { notes };
-    }
     gate(ctx, 'proceeding', 'proceeding', {
         unasked: unasked.length,
         already_live: liveToEscalate.length,
-        idle_seconds: idle,
         grace_seconds: ctx.config.ask_grace_seconds.value,
     });
-    return await escalate(ctx, envelope, sessionId, unasked, liveToEscalate, notes, hardDeadlineAt);
+    return await escalate(ctx, envelope, sessionId, unasked, liveToEscalate, notes, hardDeadlineAt, route);
 }
 /** The escalation itself, split out so the claim is released on every path. */
-async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, hardDeadlineAt) {
-    // 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 budgetStartedAt = ctx.now();
-    const existingDeadlines = alreadyLive.flatMap((entry) => entry.reply_deadline_at === undefined || entry.reply_deadline_at <= budgetStartedAt
+async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, hardDeadlineAt, route) {
+    // 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 startedAt = ctx.now();
+    const existingDeadlines = alreadyLive.flatMap((entry) => entry.reply_deadline_at === undefined || entry.reply_deadline_at <= startedAt
         ? []
         : [entry.reply_deadline_at]);
-    const budgetDeadlineAt = Math.min(hardDeadlineAt - HOOK_TIMING.finalizationReserveSeconds * 1000, ...(existingDeadlines.length === 0 ? [] : existingDeadlines));
+    const ceilingAt = Math.min(hardDeadlineAt, ...(existingDeadlines.length === 0 ? [] : existingDeadlines));
     if (unasked.length > 0 && alreadyLive.length === 0) {
         const oldest = Math.min(...unasked.map((entry) => entry.asked_at ?? ctx.now()));
-        const grace = await awaitGrace(ctx, oldest);
-        ctx.log?.debug('hook.gate', { verdict: 'grace', reason: grace, waited_from: oldest });
-        if (grace === 'user-returned') {
-            gate(ctx, 'held', 'user-returned', { grace_seconds: ctx.config.ask_grace_seconds.value });
-            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');
-        }
+        await awaitTerminalFirstWindow(ctx, oldest, ceilingAt);
+        ctx.log?.debug('hook.gate', {
+            verdict: 'grace',
+            reason: 'elapsed',
+            waited_from: oldest,
+            grace_seconds: ctx.config.ask_grace_seconds.value,
+        });
     }
     // 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 remainingSeconds = Math.floor((budgetDeadlineAt - ctx.now()) / 1000);
-        if (remainingSeconds <
-            MIN_REPLY_WAIT_SECONDS + HOOK_TIMING.submissionReserveSeconds) {
-            notes.push('the Stop budget cannot fit device resolution, submission, and a full reply window; leaving this question in the terminal');
+        // 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');
             continue;
         }
-        const replyWindowSeconds = Math.min(ctx.config.hook_reply_timeout_seconds.value, remainingSeconds - HOOK_TIMING.submissionReserveSeconds);
-        const ownerDeadlineAt = Math.min(budgetDeadlineAt, ctx.now() +
-            (replyWindowSeconds + HOOK_TIMING.submissionReserveSeconds) * 1000);
+        const ownerDeadlineAt = ceilingAt;
         const questions = pendingQuestions(entry);
         let intent = entry.submission;
         if (intent === undefined) {
@@ -1410,12 +1473,7 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             // The frozen wire identity survives a crashed owner, but its local owner
             // lease does not. Re-arm only the local deadline; request id, key,
             // targets, and draft remain byte-identical for idempotent replay.
-            const frozenReplyWindow = intent.draft.reply?.expires_in_seconds ?? replyWindowSeconds;
-            intent = {
-                ...intent,
-                owner_deadline_at: Math.min(budgetDeadlineAt, ctx.now() +
-                    (frozenReplyWindow + HOOK_TIMING.submissionReserveSeconds) * 1000),
-            };
+            intent = { ...intent, owner_deadline_at: ceilingAt };
             const rearmed = intent;
             updateSessionState(sessionId, ctx.env, (current) => {
                 const list = pendingList(current);
@@ -1428,13 +1486,12 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             });
         }
         if (ctx.now() >= intent.owner_deadline_at) {
-            notes.push('the Stop budget ended before submission; preserving the frozen intent');
+            notes.push('the waiter ceiling ended before submission; preserving the frozen intent');
             continue;
         }
         const beforeSubmitSeconds = Math.floor((intent.owner_deadline_at - ctx.now()) / 1000);
-        if (beforeSubmitSeconds <
-            MIN_REPLY_WAIT_SECONDS + HOOK_TIMING.submissionReserveSeconds / 2) {
-            notes.push('device resolution consumed the submission reserve; preserving the frozen intent instead of shrinking its reply window');
+        if (beforeSubmitSeconds < MIN_REPLY_WINDOW_SECONDS) {
+            notes.push('device resolution consumed the reply window; preserving the frozen intent instead of shrinking it below what the server accepts');
             continue;
         }
         let receipt;
@@ -1536,13 +1593,10 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
     }
     if (staleAnswers.length > 0) {
         const remaining = Math.max(0, pendingList(readSessionState(sessionId, ctx.env)).length - staleAnswers.length);
-        stageAcceptedAnswers(ctx, sessionId, staleAnswers, remaining);
+        const accepted = stageAcceptedAnswers(ctx, sessionId, staleAnswers, remaining);
         for (const answer of staleAnswers)
             reportAnswer(ctx, notes, answer, true);
-        return {
-            stdout: stopAnswerOutput(answersContext(staleAnswers, remaining)),
-            notes,
-        };
+        return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes);
     }
     const waitingOn = [
         ...alreadyLive.filter((entry) => entry.reply_deadline_at !== undefined && entry.reply_deadline_at > ctx.now()),
@@ -1550,10 +1604,10 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
     ];
     if (waitingOn.length === 0)
         return { notes };
-    // Phase two: one blocking wait across everything live, old and new alike.
-    const ownerDeadline = Math.min(budgetDeadlineAt, Math.max(...waitingOn.map((entry) => entry.reply_deadline_at)));
+    // Phase two: one wait across everything live, old and new alike.
+    const ownerDeadline = Math.min(ceilingAt, Math.max(...waitingOn.map((entry) => entry.reply_deadline_at)));
     const timeoutSeconds = Math.max(0, Math.ceil((ownerDeadline - ctx.now()) / 1000));
-    const waited = await waitForAnyReplyWhileAway(ctx, waitingOn.map((entry) => entry.request_id), timeoutSeconds, ctx.harness !== 'opencode');
+    const waited = await waitForAnyReply(ctx, waitingOn.map((entry) => entry.request_id), timeoutSeconds);
     const permanentFailure = permanentReplyFailureNote(waited.permanentFailures);
     if (permanentFailure !== null)
         notes.push(permanentFailure);
@@ -1570,34 +1624,28 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             .map((entry) => entry.pending);
         const unproven = finalized.filter((entry) => entry.response === null);
         if (confirmedSilent.length > 0) {
-            await retirePendings(ctx, envelope, sessionId, confirmedSilent, waited.userReturned ? 'answered_elsewhere' : 'expired');
+            await retirePendings(ctx, envelope, sessionId, confirmedSilent, 'expired');
         }
         if (unproven.length > 0) {
             notes.push(`could not finalize ${unproven.length} question${unproven.length === 1 ? '' : 's'}; preserving ownership rather than risking a lost late answer`);
         }
         if (finalAnswers.length > 0) {
             const remaining = Math.max(0, pendingList(readSessionState(sessionId, ctx.env)).length - finalAnswers.length);
-            stageAcceptedAnswers(ctx, sessionId, finalAnswers, remaining);
+            const accepted = stageAcceptedAnswers(ctx, sessionId, finalAnswers, remaining);
             for (const answer of finalAnswers)
                 reportAnswer(ctx, notes, answer, false);
-            return {
-                stdout: stopAnswerOutput(answersContext(finalAnswers, remaining)),
-                notes,
-            };
+            return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes);
         }
         const requestIdSummary = summarizeRequestIds(waitingOn);
         ctx.log?.info('hook.answer', {
             answered: false,
+            stage: 'queued',
             request_ids: requestIdSummary.ids,
-            user_returned: waited.userReturned,
             degraded: waited.degraded,
             permanent_failures: waited.permanentFailures.size,
             waited_seconds: timeoutSeconds,
         });
-        if (waited.userReturned) {
-            notes.push(`you came back after the question${waitingOn.length === 1 ? ' was' : 's were'} sent; ${waitingOn.length === 1 ? 'it was' : 'they were'} retired before returning the terminal (${requestIdSummary.display})`);
-        }
-        else if (waited.permanentFailures.size === 0) {
+        if (waited.permanentFailures.size === 0) {
             notes.push(waited.degraded
                 ? 'could not reach the server before the owner deadline; the question was retired so no answer can be lost later'
                 : 'no answer in time; the question expired with its continuation owner');
@@ -1622,13 +1670,10 @@ async function escalate(ctx, envelope, sessionId, unasked, alreadyLive, notes, h
             notes.push(`could not confirm the close fence for ${entry.request_id}; delivering the durable answer already observed`);
         }
     }
-    stageAcceptedAnswers(ctx, sessionId, answered, waitingOn.length - answered.length);
+    const accepted = stageAcceptedAnswers(ctx, sessionId, answered, waitingOn.length - answered.length);
     for (const answer of answered)
         reportAnswer(ctx, notes, answer, false);
-    return {
-        stdout: stopAnswerOutput(answersContext(answered, waitingOn.length - answered.length)),
-        notes,
-    };
+    return deliverAcceptedAnswers(ctx, sessionId, route, accepted, notes);
 }
 // ---------------------------------------------------------------------------
 // SessionEnd — local cleanup only