@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/feed/answer.js

@@ -1,38 +1,3 @@
-/**
- * Deliver one operator answer to one open attention item (PHNX-3999).
- *
- * The AGI Menu abandons a reply at 30s, so every path here is bounded and every
- * outcome is reported from real evidence:
- *
- *   - **Match before enrichment.** The requested key names its session, so the
- *     candidate set is that session alone and the optional `gh pr view` read
- *     runs only for a key whose generation is a PR review. Enriching every
- *     active session first spent one 15s-bounded `gh` call per session on a
- *     question that never needed one.
- *   - **Unknown stays unknown.** Three outcomes are distinct and never merged: a
- *     confirmed failure (nothing was sent, the claim is released, retry is safe),
- *     an unconfirmed delivery (something may have landed, the claim is KEPT), and
- *     a real receipt. A timeout is unconfirmed, never a failure.
- *   - **Receipts are read, never synthesized, and never over-read.** `queued`
- *     means a rail took the answer and nothing more; only the agent's own
- *     `consumed`/`continued` resolves the item; `dropped`/`expired` are failures.
- *   - **Replay is de-duplicable or refused.** A claim stranded by a kill is
- *     adopted only on the mailbox rail, where the queued message's block id makes
- *     re-delivery detectable, and only through a compare-and-swap on the claim so
- *     two retries cannot both adopt it. A keystroke or resume rail cannot be
- *     replayed safely, so it reports unknown and points at the session.
- *   - **Exact tokens across the hop.** A remote answer is quoted with the
- *     canonical `shellQuote` and run through the canonical bounded `sshExecAsync`,
- *     so newlines and shell metacharacters arrive byte-identical, and the returned
- *     receipt is verified to belong to the key that was asked about.
- *
- *   - **A claim is not a resolution.** The claim is taken `pending`
- *     (`recordAnswer`'s two-phase option): it locks the item against a second
- *     surface but leaves the block `open` and writes no tombstone, so the card
- *     stays in the operator's feed. Only a real receipt calls
- *     `confirmAnswerResolution` and lets the item leave. A delivery that never
- *     confirms can no longer make the request silently disappear.
- */
 import { spawn } from 'node:child_process';
 import { getActiveSessions } from '../session/active.js';
 import { resolveAnswerRoute, resumeArgv } from '../answer-router.js';
@@ -45,38 +10,13 @@ import { blockGeneration, blockIdForSession, confirmAnswerResolution, getAnswerR
 import { reconcileAttention } from './attention.js';
 import { readPullRequestStatus } from './pr-status.js';
 import { getAgentsInvocation } from '../daemon/daemon.js';
-/**
- * Total budget for one answer. Sits below the AGI Menu's 30s abandon so the
- * operator always gets a typed verdict instead of a timeout.
- */
 export const ANSWER_DEADLINE_MS = 20_000;
-/** Slice of the budget the optional PR-review enrichment may spend. */
 export const PR_ENRICHMENT_BUDGET_MS = 4_000;
-/** Budget for the forwarded leg — the remote repeats the local work under its own deadline. */
 export const REMOTE_ANSWER_TIMEOUT_MS = 25_000;
-/**
- * A claim older than this with no receipt was stranded by a kill, not left in
- * flight: it exceeds a full local deadline plus the remote leg, so no live
- * delivery can still be running behind it.
- */
 export const STRANDED_CLAIM_MS = 60_000;
-/**
- * How long to watch a `resume` child before giving up on a verdict. A resume
- * runs the agent's whole next turn — minutes — so waiting for exit would blow the
- * operator deadline on every headless answer. Only a clean early exit is booked;
- * a non-zero exit or a still-running child is unknown, because neither proves
- * the agent did or did not accept the prompt.
- */
 export const RESUME_SETTLE_MS = 2_000;
-/**
- * How long a caller that LOST the claim waits for the holder's receipt before
- * reporting unknown. The holder is mid-delivery — a double-clicked answer is the
- * common case — so a short wait turns "I can't tell" into the real receipt,
- * without ever delivering a second copy.
- */
 export const HOLDER_RECEIPT_WAIT_MS = 400;
 const HOLDER_RECEIPT_POLL_MS = 20;
-/** A CONFIRMED failure: nothing reached a rail, the claim is released, retry is safe. */
 export class AnswerError extends Error {
     code;
     constructor(message, code) {
@@ -85,22 +25,12 @@ export class AnswerError extends Error {
         this.name = 'AnswerError';
     }
 }
-/**
- * An UNCONFIRMED outcome: something may have been delivered. The claim is kept
- * so a retry cannot double-send, and the operator is offered a delivery check
- * rather than a resend.
- */
 export class AnswerUnknownError extends Error {
     constructor(message) {
         super(message);
         this.name = 'AnswerUnknownError';
     }
 }
-/**
- * Split `<host>/<session>/<generation>` (attention.ts `attentionKey`). Fails
- * loud on a malformed key: the old `slice(0, indexOf('/'))` returned a truncated
- * host for a key with no separator, which then routed the answer at random.
- */
 export function parseAttentionKey(key) {
     const first = key.indexOf('/');
     const last = key.lastIndexOf('/');
@@ -109,28 +39,12 @@ export function parseAttentionKey(key) {
     }
     return { host: key.slice(0, first), sessionId: key.slice(first + 1, last), generation: key.slice(last + 1) };
 }
-/**
- * Whether THIS machine owns the item. The exact local/remote choice: the key's
- * host is compared through the same {@link normalizeHost} the machine id is
- * minted with, so `Yosemite-M4.local` and `yosemite-m4` are one machine.
- */
 export function answerOwnerIsLocal(host, self = machineId()) {
     return normalizeHost(host) === normalizeHost(self);
 }
-/** A PR-review generation (`pr<number>:<decision>`) — the only kind a `gh` read can produce. */
 function isPullRequestGeneration(generation) {
     return /^pr\d+:/.test(generation);
 }
-// --- receipt semantics ------------------------------------------------------
-/**
- * What a stored receipt proves. The lifecycle vocabulary is fixed by
- * `MessageReceipt`, and each member means exactly one thing here:
- *   queued            — a rail took the answer. Delivery, never resolution.
- *   consumed/continued— the agent itself acknowledged it. This resolves the item.
- *   dropped/expired   — terminal failure; it is the newest truth for its message
- *                       (the write rank puts it top precisely so it cannot be
- *                       regressed), which is exactly why it must not read as success.
- */
 export function classifyReceipt(receipt) {
     if (receipt.status === 'consumed' || receipt.status === 'continued')
         return { delivery: 'receipt', resolved: true };
@@ -140,11 +54,6 @@ export function classifyReceipt(receipt) {
 }
 function startDeadline(totalMs) { return { endMs: Date.now() + totalMs }; }
 function remainingMs(deadline) { return deadline.endMs - Date.now(); }
-/**
- * Bound one delivery await. Expiry is UNKNOWN, not failure: the rail's own child
- * may still land the answer, so the claim stays and the operator is sent to a
- * delivery check.
- */
 async function withinDeadline(work, deadline, what) {
     const budget = remainingMs(deadline);
     if (budget <= 0)
@@ -164,7 +73,6 @@ async function withinDeadline(work, deadline, what) {
             clearTimeout(timer);
     }
 }
-// --- resolution -------------------------------------------------------------
 function blockFromAttention(attention, session) {
     return {
         blockId: blockIdForSession(attention.sessionId), sessionId: attention.sessionId,
@@ -173,18 +81,10 @@ function blockFromAttention(attention, session) {
         state: 'open', sourceCursor: attention.sourceCursor, project: attention.project,
         ts: attention.openedAt, questions: [attention.question ?? { text: 'Continue from this attention item.' }],
         kind: attention.kind === 'permission' ? 'notification' : attention.kind === 'declared' ? 'declared' : attention.source === 'system' ? 'control' : 'question',
-        // A notification block is a permission only by its recorded subtype
-        // (attention.ts kindFromNotification), so the reconstructed block must carry
-        // it or a re-read classifies the same item as unverified.
         ...(attention.kind === 'permission' ? { notificationType: 'permission_prompt' } : {}),
         safeDefault: attention.safeDefault,
     };
 }
-/**
- * Reconcile one session against the requested key. `pullRequest` is passed only
- * on the enrichment pass — `reconcileAttention` consults it last
- * (`attentionFromPullRequest`), so a block- or session-derived match never needed it.
- */
 function matchSession(session, key, attentionKey, root, pullRequest) {
     const projected = { ...session, host: key.host };
     const blockId = blockIdForSession(session.sessionId);
@@ -195,8 +95,6 @@ function matchSession(session, key, attentionKey, root, pullRequest) {
     });
     if (attention?.key === attentionKey) {
         if (attention.kind === 'unverified') {
-            // No confirmed prompt to land a reply in: an answer typed into the session
-            // could hit an empty prompt line or a different dialog (PHNX-3999).
             throw new AnswerError(`'${attentionKey}' could not be verified as a pending request — open the session and answer it there.`, 'unverified');
         }
         if (block)
@@ -205,9 +103,6 @@ function matchSession(session, key, attentionKey, root, pullRequest) {
         publishBlock(reconstructed, root);
         return { hit: { block: reconstructed, attention, session } };
     }
-    // The winning caller advances the block to answered before a concurrent loser
-    // resolves it. Reconstruct only this block's original generation so the loser
-    // reaches the claim check and reports the real outcome, without routing again.
     if (block && getAnswerRecord(blockId, root)) {
         const original = reconcileAttention({
             block: { ...block, state: 'open', answer: undefined }, session: projected, nowMs: Date.now(),
@@ -218,8 +113,6 @@ function matchSession(session, key, attentionKey, root, pullRequest) {
     return { observed: attention };
 }
 async function resolveTarget(key, attentionKey, sessions, deadline, root) {
-    // The key names its session, so only that session can produce it. Narrowing
-    // here is also what keeps an answer off an unrelated operator's pending item.
     const candidates = sessions.filter((session) => session.sessionId && session.sessionId === key.sessionId);
     if (candidates.length === 0) {
         throw new AnswerError(`No live session '${key.sessionId}' here to answer '${attentionKey}'.`, 'no_session');
@@ -231,8 +124,6 @@ async function resolveTarget(key, attentionKey, sessions, deadline, root) {
             return outcome.hit;
         observed ??= outcome.observed;
     }
-    // Enrichment pass — only a review key can come from a PR read, and only the
-    // named session is fetched, under whatever budget is left.
     if (isPullRequestGeneration(key.generation)) {
         for (const session of candidates) {
             const budget = Math.min(PR_ENRICHMENT_BUDGET_MS, remainingMs(deadline));
@@ -247,30 +138,16 @@ async function resolveTarget(key, attentionKey, sessions, deadline, root) {
             observed ??= outcome.observed;
         }
     }
-    // The session is live but has moved on — a different generation, or none. That
-    // is a STALE request, not a missing one: the operator answered yesterday's card.
     throw new AnswerError(observed
         ? `'${attentionKey}' is no longer the open request for '${key.sessionId}' — it is now '${observed.key}'.`
         : `'${attentionKey}' is no longer open — session '${key.sessionId}' has no pending request.`, 'stale');
 }
-/**
- * Take over a claim a kill stranded, atomically.
- *
- * `rollbackAnswerClaim` compares `answeredAt` before releasing, so it IS the
- * compare-and-swap: exactly one racer can release this exact claim, and it
- * re-takes it immediately under `recordAnswer`'s `O_EXCL`. A racer that loses
- * either the release or the re-take finds a live marker and reports
- * `already_answered` instead of delivering a second copy.
- */
 function adoptStrandedClaim(block, stranded, operator, verified, root) {
     let released;
     try {
         released = rollbackAnswerClaim(block.blockId, stranded.answeredAt, { ...block, state: 'open', answer: undefined }, undefined, root);
     }
     catch {
-        // The release is a read-compare-then-unlink, so a racing adopter that got
-        // there first leaves this one unlinking a marker that is already gone. That
-        // is losing the race, not an error — fall through and let the loser report.
         return undefined;
     }
     if (!released)
@@ -282,10 +159,6 @@ function adoptStrandedClaim(block, stranded, operator, verified, root) {
         return undefined;
     return getAnswerRecord(block.blockId, root);
 }
-/**
- * Wait briefly for the claim holder to record its receipt. Read-only — it polls
- * the block's own receipt list and never claims, routes or resends.
- */
 async function awaitHolderReceipt(blockId, waitMs, origin, root) {
     const until = Date.now() + waitMs;
     for (;;) {
@@ -313,17 +186,7 @@ function heldClaimResult(block, attentionKey, host, existing, receipt) {
         ...base,
     };
 }
-/**
- * Take the claim, or reconcile the one already on disk against the block's real
- * receipts. A stranded claim is adopted only when `replayable` — the mailbox rail,
- * where the queued message's block id makes a second enqueue detectable. A
- * keystroke or resume rail may already have landed before the kill and cannot be
- * de-duplicated, so it stays unknown.
- */
 async function claimOrReconcile(block, attentionKey, host, operator, verified, replayable, generation, nowMs, deadline, root) {
-    // PENDING: claimed, not resolved. The card stays in the operator's feed until
-    // a rail reports a receipt, so a claim whose delivery never lands cannot make
-    // the request silently disappear.
     const claim = recordAnswer(block.blockId, {
         answeredBy: operator.label, answeredFrom: 'feed', operatorId: operator.id, verified,
     }, root, { pending: true });
@@ -336,21 +199,14 @@ async function claimOrReconcile(block, attentionKey, host, operator, verified, r
     if ('unauthorized' in claim)
         throw new AnswerError(claim.reason, 'unauthorized');
     const existing = getAnswerRecord(block.blockId, root) ?? claim.existing;
-    // Scope every receipt read to THIS ask and THIS attempt, so a leftover receipt
-    // from an earlier question on the same session cannot answer for this one.
     const origin = { generation, attempt: existing.answeredAt };
     const claimedAtMs = Date.parse(existing.answeredAt);
     const stranded = Number.isFinite(claimedAtMs) && nowMs - claimedAtMs >= STRANDED_CLAIM_MS;
-    // A fresh claim with no receipt is a delivery IN FLIGHT (the double-clicked
-    // answer), so give the holder a moment to record it rather than reporting a
-    // scary unknown for what is about to be a receipt.
     const receipt = stranded
         ? latestMessageReceipt(block.blockId, root, origin)
         : await awaitHolderReceipt(block.blockId, Math.max(0, Math.min(HOLDER_RECEIPT_WAIT_MS, remainingMs(deadline))), origin, root);
     if (receipt)
         return { adopted: false, lost: heldClaimResult(block, attentionKey, host, existing, receipt) };
-    // No receipt and the claim predates any possible live delivery: a kill cut it
-    // between the claim and the receipt.
     if (stranded && replayable) {
         const adopted = adoptStrandedClaim(block, existing, operator, verified, root);
         if (adopted)
@@ -358,23 +214,11 @@ async function claimOrReconcile(block, attentionKey, host, operator, verified, r
     }
     return { adopted: false, lost: heldClaimResult(block, attentionKey, host, existing, undefined) };
 }
-/** A multiline free-text answer needs a rail that inserts rather than submits per line. */
 function isMultilineFreeText(route, answer) {
     return (route.payload ?? '') === answer && answer.includes('\n');
 }
 async function deliverMailbox(block, answer, operator, adopted, origin, mailboxRoot) {
     const dir = mailboxDir(block.mailboxId, mailboxRoot);
-    // An adopted claim may already have enqueued before it was killed. The whole
-    // spool is scanned — inbox, processing AND consumed (`readBox`, not `peek`) —
-    // because a kill AFTER the agent drained the message would otherwise look
-    // like nothing was ever sent and enqueue the answer a second time.
-    //
-    // The match is on the ASK (block id + generation), not just the block id: a
-    // block id is per SESSION, so an already-consumed message answering question N
-    // would otherwise suppress a genuine delivery for question N+1. It is NOT keyed
-    // on the attempt: adopting a stranded claim necessarily mints a NEW attempt, so
-    // requiring an attempt match would never find the message the killed run queued
-    // and would duplicate the answer.
     const existing = adopted
         ? readBox(dir).find((msg) => msg.blockId === block.blockId && msg.generation === origin.generation)
         : undefined;
@@ -387,17 +231,6 @@ async function deliverMailbox(block, answer, operator, adopted, origin, mailboxR
         ...(existing ? { reason: 'Re-used the message a stranded claim had already enqueued.' } : {}),
     };
 }
-/**
- * Re-enter a headless agent with the answer as its next user turn.
- *
- * Nothing here can prove non-delivery. A non-zero exit does NOT mean the prompt
- * never ran — the agent may have acted on it and then crashed — and a process
- * still running is not evidence the prompt was accepted either. Both are
- * therefore UNKNOWN, which keeps the claim and sends the operator to a delivery
- * check instead of a resend. Only a clean exit is booked, as `queued`: the
- * resume command completed, which is the rail taking the answer — not the agent
- * acknowledging it, which is what `consumed`/`continued` mean.
- */
 async function deliverResume(route, block, claimedAt, operator, attentionKey, deadline, origin) {
     const invocation = getAgentsInvocation(resumeArgv(route));
     const settleMs = Math.max(0, Math.min(RESUME_SETTLE_MS, remainingMs(deadline)));
@@ -413,7 +246,6 @@ async function deliverResume(route, block, claimedAt, operator, attentionKey, de
         child.once('error', () => { clearTimeout(timer); resolve(1); });
         child.once('close', (code) => { clearTimeout(timer); resolve(code ?? 1); });
     });
-    // Detach either way — the agent's turn outlives the operator's deadline.
     child.stderr?.destroy();
     child.unref();
     if (exit !== undefined && exit !== 0) {
@@ -424,29 +256,12 @@ async function deliverResume(route, block, claimedAt, operator, attentionKey, de
     }
     return { receipt: { msgId: `resume-${block.blockId}-${claimedAt}`, status: 'queued', at: new Date().toISOString(), from: operator.label, ...origin } };
 }
-/**
- * Drive a keystroke rail.
- *
- * A failure here is UNKNOWN, not a confirmed failure: the tmux/iTerm path writes
- * the text and its Enter as two separate sends (terminal/inject.ts, the Ink-safe
- * split), so a reported error can mean the text already landed in the composer
- * and only the submit failed. Every check that can prove nothing was sent —
- * rail completeness, paste capability — runs BEFORE the claim instead.
- */
 async function deliverInject(route, block, answer, claimedAt, operator, origin, deadline) {
-    // The rail gets the remaining budget, so it cancels its own process group and
-    // never starts a write the deadline can no longer cover.
     const delivered = await injectIntoTerminal(route.inject, route.payload, {
         enter: route.enter ?? true, combined: false, deadlineMs: Math.max(0, remainingMs(deadline)),
         ...(isMultilineFreeText(route, answer) ? { paste: true } : {}),
     });
     if (!delivered.ok) {
-        // `writes === 0` means no write was even issued, so nothing landed and the
-        // item is cleanly retryable. Anything past the first write is ambiguous: the
-        // text may sit in the composer with only its submit missing.
-        // `started === 0` is the ONLY proof nothing reached the terminal. A spec that
-        // was started and then failed or timed out may have written bytes first, so
-        // `writes` (which counts COMPLETED specs) cannot license a retry.
         if (delivered.started === 0) {
             throw new AnswerError(`${delivered.error ?? `Failed to deliver over ${route.kind}`} — no keystroke was sent.`, 'rail_failed');
         }
@@ -457,11 +272,6 @@ async function deliverInject(route, block, answer, claimedAt, operator, origin,
     }
     return { receipt: { msgId: `inject-${block.blockId}-${claimedAt}`, status: 'queued', at: new Date().toISOString(), from: operator.label, ...origin } };
 }
-/**
- * Everything provable BEFORE a claim is taken. Each of these means nothing was
- * sent, so raising here keeps the item cleanly retryable instead of parking it
- * in an unknown state.
- */
 function preflightRoute(route, answer, attentionKey) {
     if (route.kind === 'refuse')
         throw new AnswerError(route.reason, 'refused');
@@ -473,29 +283,16 @@ function preflightRoute(route, answer, attentionKey) {
         throw new AnswerError(`A multiline answer cannot be typed into the ${route.inject.backend} rail for '${attentionKey}' — only tmux carries bracketed paste. Open the session and paste it there.`, 'refused');
     }
 }
-// --- entry points -----------------------------------------------------------
-/**
- * Read-only reconciliation of an attention item's delivery state — what powers
- * "Check delivery" on an unconfirmed answer. It NEVER claims, routes, adopts or
- * resends; it reports the stored claim and the block's real receipt so an
- * operator can tell "still unconfirmed" from "the agent has it".
- */
 export function checkAnswerDelivery(attentionKey, feedRoot, expectedAttempt) {
     const key = parseAttentionKey(attentionKey);
     const blockId = blockIdForSession(key.sessionId);
     const base = { attentionKey, blockId, host: key.host };
     const claim = getAnswerRecord(blockId, feedRoot);
-    // Scoped to the requested ask AND the attempt being checked, so a receipt left
-    // by a different question or a superseded attempt is never read as this one's.
     const receipt = claim
         ? latestMessageReceipt(blockId, feedRoot, {
             generation: key.generation, attempt: expectedAttempt ?? claim.answeredAt,
         })
         : undefined;
-    // A block id is per SESSION, so its claim and receipts belong to whatever
-    // generation the session is on NOW. Checking an older card against them would
-    // report the NEXT question's receipt as this question's answer, which is the
-    // one way a read-only check can still lie.
     const block = readBlock(blockId, feedRoot);
     const resolution = readResolution(blockId, feedRoot);
     const liveGeneration = block ? blockGeneration(block) : resolution?.generation;
@@ -506,8 +303,6 @@ export function checkAnswerDelivery(attentionKey, feedRoot, expectedAttempt) {
             ...base,
         };
     }
-    // An attempt the caller did not ask about is a DIFFERENT delivery — say so
-    // rather than answering about someone else's.
     if (expectedAttempt !== undefined && claim && claim.answeredAt !== expectedAttempt) {
         return {
             status: 'unknown', delivery: 'unconfirmed', resolved: false,
@@ -532,15 +327,12 @@ export function checkAnswerDelivery(attentionKey, feedRoot, expectedAttempt) {
             ...base, attempt: claim.answeredAt,
         };
     }
-    // No claim at all is the one state that IS a confirmed non-delivery: nothing
-    // ever took the item, so the operator can safely answer it again.
     return {
         status: 'failed', delivery: 'failed', resolved: false, code: 'rail_failed',
         reason: `No answer has been claimed for '${attentionKey}'.`,
         ...base,
     };
 }
-/** Atomically claim the first answer, then route it over the session's recorded reply rail. */
 export async function claimAndRouteAttentionAnswer(input) {
     if ((input.choiceId == null) === (input.text == null)) {
         throw new AnswerError('Exactly one of choiceId or text is required.', 'empty_answer');
@@ -556,8 +348,6 @@ export async function claimAndRouteAttentionAnswer(input) {
     const answer = input.text ?? choice?.deliveryKey ?? choice?.label;
     if (!answer)
         throw new AnswerError('Answer is empty.', 'empty_answer');
-    // The route is pure, so it is resolved BEFORE the claim: a refusal or an
-    // incapable rail then fails with nothing claimed and nothing delivered.
     const route = resolveAnswerRoute({ mailboxId: block.mailboxId, answer, block, session });
     preflightRoute(route, answer, input.attentionKey);
     const verified = input.operator.verified && verifyOperatorIdentity(input.operator.id);
@@ -566,12 +356,8 @@ export async function claimAndRouteAttentionAnswer(input) {
     if (outcome.lost)
         return outcome.lost;
     const claim = outcome.claim;
-    // Every receipt this delivery writes names the ask and the attempt it belongs
-    // to, so a late acknowledgement can never be read against a different question.
     const origin = { generation: key.generation, attempt: claim.answeredAt };
     const base = { attentionKey: input.attentionKey, blockId: block.blockId, host: key.host, attempt: claim.answeredAt };
-    // An adopted claim was created by the killed run, so releasing it means
-    // restoring the pre-claim OPEN state, not the tombstone that claim wrote.
     const restoreBlock = outcome.adopted ? { ...block, state: 'open', answer: undefined } : block;
     const restoreResolution = outcome.adopted ? undefined : previousResolution;
     let delivered;
@@ -583,10 +369,6 @@ export async function claimAndRouteAttentionAnswer(input) {
                 : deliverInject(route, block, answer, claim.answeredAt, input.operator, origin, deadline), deadline, `Delivering '${input.attentionKey}' over ${route.kind}`);
     }
     catch (error) {
-        // Only a CONFIRMED failure releases the claim. Past this point the code is
-        // inside a rail that may already have written bytes, so anything unexpected
-        // is UNKNOWN too — keeping the claim is what stops a retry double-sending
-        // behind a delivery that may have landed.
         if (error instanceof AnswerError) {
             rollbackAnswerClaim(block.blockId, claim.answeredAt, restoreBlock, restoreResolution, input.feedRoot);
             throw error;
@@ -597,12 +379,6 @@ export async function claimAndRouteAttentionAnswer(input) {
     const { delivery, resolved } = classifyReceipt(delivered.receipt);
     try {
         recordMessageReceipt(block.blockId, delivered.receipt, input.feedRoot);
-        // Only the AGENT's own acknowledgement resolves the item. A `queued` receipt
-        // says a rail took the answer and nothing more, so the card stays up until
-        // the mailbox drain records `consumed` (which promotes it through
-        // `recordMessageReceipt`) or the transcript moves past the block. The
-        // generation + attempt binding stops a slow delivery from resolving the ask
-        // the agent has since moved on to.
         if (resolved) {
             confirmAnswerResolution(block.blockId, input.feedRoot, {
                 generation: key.generation, answeredAt: claim.answeredAt,
@@ -610,8 +386,6 @@ export async function claimAndRouteAttentionAnswer(input) {
         }
     }
     catch (error) {
-        // The answer IS on the rail; only the bookkeeping failed. Reporting a
-        // failure here would invite a resend of something already delivered.
         return {
             status: 'unknown', delivery: 'unconfirmed', resolved: false,
             reason: `Delivered over ${route.kind}, but the receipt could not be recorded: ${error instanceof Error ? error.message : String(error)}.`,
@@ -624,10 +398,6 @@ export async function claimAndRouteAttentionAnswer(input) {
         ...base,
     };
 }
-/**
- * The remote `agents feed answer` argv for a forwarded answer. Exported so the
- * exact tokens that cross the hop are asserted directly.
- */
 export function remoteAnswerArgv(input) {
     const argv = ['agents', 'feed', 'answer', input.attentionKey, '--json'];
     if (input.check)
@@ -642,21 +412,6 @@ export function remoteAnswerArgv(input) {
         argv.push('--as', input.operatorId);
     return argv;
 }
-/**
- * Forward a fleet attention answer to the device that owns its scope.
- *
- * Every token is POSIX-quoted with the canonical {@link shellQuote} before the
- * remote login shell parses it, so a multiline answer or one carrying `$`, `"`,
- * `` ` ``, `;` or a newline arrives byte-identical. The transport is the
- * canonical bounded {@link sshExecAsync} — it disables ControlMaster whenever a
- * timeout is set, so the bound actually tears the remote command down instead of
- * orphaning it behind a control socket.
- *
- * A timeout is reported UNKNOWN: the remote may well have delivered before the
- * link was cut, so the operator is offered a delivery check, never an implicit
- * resend. The returned receipt is verified to be about the key that was asked
- * for, so a mismatched or truncated remote reply cannot be trusted as one.
- */
 export async function forwardFeedAnswer(input) {
     const timeoutMs = input.timeoutMs ?? REMOTE_ANSWER_TIMEOUT_MS;
     const remoteCmd = remoteAnswerArgv(input).map(shellQuote).join(' ');
@@ -665,10 +420,6 @@ export async function forwardFeedAnswer(input) {
         reason: `${reason} Check delivery rather than resending.`,
         attentionKey: input.attentionKey, host: input.host,
     });
-    // The caller enforces the bound, not the transport. `sshExecAsync` resolves on
-    // the child's `close`, which a remote peer still holding the pipe can delay
-    // past the kill it already issued — so the operator's verdict is raced against
-    // the deadline directly and returns on time regardless.
     const settled = await Promise.race([
         sshExecAsync(input.host, remoteCmd, { timeoutMs }).then((value) => ({ value })),
         new Promise((resolve) => {
@@ -680,13 +431,6 @@ export async function forwardFeedAnswer(input) {
     if (!result || result.timedOut) {
         return unknown(`Answering on '${input.host}' did not finish in ${timeoutMs}ms — it may already have been delivered.`);
     }
-    // Once ssh has been handed the command there is NO way to prove the remote did
-    // not run it. Exit 255 covers both "could not connect" and "connection dropped
-    // after the answer was delivered", and a dropped link can lose stdout, so even
-    // an echoed start marker is not proof of its own absence. Every post-dispatch
-    // remote outcome is therefore UNKNOWN — the operator gets "check delivery",
-    // never a retry that could double-send. (A locally-detectable fault, such as an
-    // invalid ssh target, throws from `sshExecAsync` before anything is dispatched.)
     if (result.code === SSH_CONN_FAILURE_CODE) {
         return unknown(`ssh to '${input.host}' failed (exit 255)${result.stderr.trim() ? `: ${result.stderr.trim()}` : ''}; whether the answer ran there is unknown.`);
     }
@@ -709,11 +453,6 @@ export async function forwardFeedAnswer(input) {
 const ANSWER_STATUSES = ['delivered', 'already_answered', 'unknown', 'failed'];
 const ANSWER_DELIVERIES = ['receipt', 'unconfirmed', 'failed'];
 const RECEIPT_STATUSES = ['queued', 'consumed', 'continued', 'dropped', 'expired'];
-/**
- * Validate a forwarded result as a whole, not just its key: an off-key, truncated
- * or shape-invalid reply is not evidence about THIS request, and a caller that
- * trusted one would report another item's outcome as this one's.
- */
 function remoteResultProblem(parsed, attentionKey, requestedAttempt) {
     if (parsed?.attentionKey !== attentionKey) {
         return `reported '${parsed?.attentionKey ?? 'no key'}', not '${attentionKey}'`;
@@ -727,8 +466,6 @@ function remoteResultProblem(parsed, attentionKey, requestedAttempt) {
     if (parsed.blockId !== undefined && parsed.blockId !== blockIdForSession(parseAttentionKey(attentionKey).sessionId)) {
         return `reported block '${parsed.blockId}', which is not this key's block`;
     }
-    // An answer about a DIFFERENT attempt than the one asked about is not evidence
-    // for this one, even though the key matches.
     if (requestedAttempt !== undefined && parsed.attempt !== undefined && parsed.attempt !== requestedAttempt) {
         return `reported attempt '${parsed.attempt}', not the requested '${requestedAttempt}'`;
     }
@@ -738,11 +475,9 @@ function remoteResultProblem(parsed, attentionKey, requestedAttempt) {
         if (!RECEIPT_STATUSES.includes(parsed.receipt.status)) {
             return `reported an unknown receipt status '${parsed.receipt.status}'`;
         }
-        // A dead message is a failure, not a delivery.
         if (parsed.receipt.status === 'dropped' || parsed.receipt.status === 'expired') {
             return `reported delivery 'receipt' for a '${parsed.receipt.status}' message`;
         }
-        // The receipt must be about the ASK that was requested.
         const generation = parseAttentionKey(attentionKey).generation;
         if (parsed.receipt.generation !== undefined && parsed.receipt.generation !== generation) {
             return `returned a receipt for ask '${parsed.receipt.generation}', not '${generation}'`;
@@ -751,8 +486,6 @@ function remoteResultProblem(parsed, attentionKey, requestedAttempt) {
             && parsed.receipt.attempt !== parsed.attempt) {
             return `returned a receipt for attempt '${parsed.receipt.attempt}', not its own '${parsed.attempt}'`;
         }
-        // `resolved` means the agent itself acknowledged — only consumed/continued
-        // can support it. A `queued` receipt claiming resolution is inconsistent.
         const acknowledged = parsed.receipt.status === 'consumed' || parsed.receipt.status === 'continued';
         if (parsed.resolved !== acknowledged) {
             return `reported resolved=${parsed.resolved} for a '${parsed.receipt.status}' receipt`;