@phnx-labs/agents-cli 1.22.114 → 1.22.116

package/dist/lib/device-config.js

@@ -505,6 +505,67 @@ export const CONFIG_KEYS = [
         defaultValue: true,
         description: 'AGI Menu: show the open pull requests section for each project.',
     },
+    {
+        name: 'menubar.menu.sessionUpdates',
+        yamlKey: 'menubarMenuSessionUpdates',
+        scope: 'user',
+        type: 'bool',
+        defaultValue: true,
+        description: 'AGI Menu: show the session-updates section on Home. Off leaves Home to requests and progress ' +
+            'only; the full list stays on the Sessions tab either way.',
+    },
+    {
+        name: 'menubar.menu.deviceSort',
+        yamlKey: 'menubarMenuDeviceSort',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'name',
+        description: 'AGI Menu: how the device list is ordered — name, role, load, memory, or disk. The spec orders read ' +
+            'the same cached fleet stats the rows render, so a device with no observation sorts last rather than ' +
+            'as zero.',
+        validate: oneOf('menubar.menu.deviceSort', ['name', 'role', 'load', 'memory', 'disk']),
+    },
+    {
+        name: 'menubar.menu.headlessAgent',
+        yamlKey: 'menubarMenuHeadlessAgent',
+        scope: 'user',
+        type: 'string',
+        description: 'AGI Menu: the harness a Headless run dispatches to by default (an agent id, e.g. claude). Unset ' +
+            'leaves the choice to the menu\'s own default — this key never invents a primary harness.',
+        validate: (v) => isAgentId(v) ? null : `menubar.menu.headlessAgent must be an agent id (e.g. claude, codex), got ${JSON.stringify(v)}.`,
+    },
+    {
+        name: 'menubar.menu.headlessFallbackAgent',
+        yamlKey: 'menubarMenuHeadlessFallbackAgent',
+        scope: 'user',
+        type: 'string',
+        description: 'AGI Menu: the permitted alternate harness for a Headless run, dispatched as `agents run --fallback ' +
+            '<agent>`. It is reached only after every usable account of the primary harness is exhausted (the ' +
+            'run\'s own same-agent account failover runs first). Unset sends no --fallback.',
+        validate: (v) => isAgentId(v) ? null : `menubar.menu.headlessFallbackAgent must be an agent id (e.g. codex, grok), got ${JSON.stringify(v)}.`,
+    },
+    {
+        name: 'menubar.menu.headlessPlacement',
+        yamlKey: 'menubarMenuHeadlessPlacement',
+        scope: 'user',
+        type: 'string',
+        defaultValue: 'auto',
+        description: 'AGI Menu: where a Headless run executes — `auto` (the CLI picks an eligible worker; `agents run ' +
+            '--device auto` never picks a personal or desktop box), `local` (this machine, no --device), ' +
+            '`interactive` (the box pinned as interactive.host), or a device name to pin one explicitly.',
+        validate: (v) => {
+            const value = v;
+            if (value === 'auto' || value === 'local' || value === 'interactive')
+                return null;
+            try {
+                assertValidDeviceName(value);
+                return null;
+            }
+            catch {
+                return 'menubar.menu.headlessPlacement must be auto | local | interactive | a device name.';
+            }
+        },
+    },
 ];
 /** Look up a key spec by CLI dotted name, or throw listing the known keys. */
 /**

package/dist/lib/devices/connect.d.ts

@@ -30,13 +30,43 @@ export declare function sshTargetFor(device: DeviceProfile): string;
  */
 export declare function fleetDialTarget(device: DeviceProfile): string;
 /**
- * Wrap a remote command for the device's shell. Windows devices speak
- * PowerShell, so a bare command is run through `powershell -NoProfile
- * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
- * shell parses it). Returns undefined when no command was given (interactive
+ * Render `cmd` as the single command string ssh sends to the peer.
+ *
+ * Windows devices speak PowerShell, so the result is run through
+ * `powershell -NoProfile -EncodedCommand`; POSIX devices get it as the remote
+ * login shell sees it. Returns undefined when no command was given (interactive
  * login).
+ *
+ * TWO MODES, and the difference is load-bearing rather than a convenience.
+ *
+ * The default joins the tokens RAW. That is not a bug to be tidied away: every
+ * existing caller of `agents ssh` relies on the remote shell interpreting what it
+ * is handed — `agents ssh box 'bash -lc "cd x && make"'` arrives as ONE token
+ * whose pipeline, globs and redirections the peer's shell must expand. Quoting
+ * that would ship the whole line as a literal argument and break it.
+ *
+ * `{ argv: true }` is for a caller that genuinely holds an argv ARRAY and needs
+ * each element delivered as exactly one token. Joining those raw destroys any
+ * token containing a space or a metacharacter — `['--title', 'two words']`
+ * arrives as three tokens, and `'a & b'` arrives as a backgrounded command — which
+ * is what a native client hitting this path actually hit.
+ *
+ * So fidelity is opt-in at the call site that knows which shape it has, and the
+ * quoting itself reuses the canonical helpers (`shellQuote`, {@link pwshQuote})
+ * rather than introducing a third escaping scheme.
  */
-export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[]): string | undefined;
+export declare function wrapRemoteCommand(device: DeviceProfile, cmd: string[], opts?: {
+    argv?: boolean;
+    prelude?: string[];
+}): string | undefined;
+/**
+ * Single-quote one token for PowerShell's OWN parser. Inside a single-quoted pwsh
+ * string the only special character is `'`, escaped by doubling.
+ *
+ * This is correct for a value PowerShell itself consumes, and NOT sufficient for
+ * an argument handed on to a native program — see the Win32 note below.
+ */
+export declare function pwshQuote(token: string): string;
 /**
  * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
  * the standalone `browser` binary (`cli/package.json` `bin.browser` →
@@ -65,6 +95,19 @@ export declare function isAgentsBrowserDrive(cmd: string[]): boolean;
  * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
  * so nothing is doubled.
  */
+/**
+ * The provenance prefix as READY SHELL SYNTAX for the device's shell.
+ *
+ * These tokens are already quoted/escaped for their target shell — a POSIX
+ * `K=V` pair is `shellQuote`d here, and a PowerShell assignment is a complete
+ * statement with its own doubled quotes. That matters because argv mode quotes
+ * every token it is handed: quoting THESE again turns
+ * `'AGENTS_ACTOR=Some Name'` into `''\''AGENTS_ACTOR=Some Name'\'''` and turns a
+ * pwsh assignment into an inert string literal. So the prelude is composed
+ * SEPARATELY from the caller's argv rather than concatenated into it, and this is
+ * the single definition both paths use.
+ */
+export declare function fleetRemotePrelude(device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 export declare function markFleetRemote(cmd: string[], device: Pick<DeviceProfile, 'shell'>, provenanceEnv?: Record<string, string>): string[];
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
@@ -136,6 +179,7 @@ export declare function deviceIdentityArgs(device: DeviceProfile): string[];
 export declare function buildSshInvocation(device: DeviceProfile, cmd: string[], askpassShimPath: string, hostKey?: SshHostKeyOptions, opts?: {
     agentOnly?: boolean;
     interactiveCwd?: string;
+    argv?: boolean;
 }): {
     args: string[];
     env: Record<string, string>;

package/dist/lib/devices/connect.js

@@ -18,12 +18,14 @@ import * as path from 'path';
 import { assertValidSshTarget, shellQuote } from '../ssh-exec.js';
 import { resolveActor, actorEnv } from '../actor.js';
 import { getCliLaunch } from '../cli-entry.js';
-import { encodePwshBase64 } from '../pwsh.js';
+import { encodePwshBase64, pwshLiteral, pwshNativeExecStatements } from '../pwsh.js';
+import { quoteWin32ExecArg } from '../platform/exec.js';
 import { homeRemainder, remoteCdPrefix } from '../project-root.js';
 import { getCacheDir } from '../state.js';
 import { hostKeyCheckingOpts } from './known-hosts.js';
 import { hostNameFor } from './ssh-config.js';
 import { resolveDeviceProfile } from './resolve-profile.js';
+import { renderPowershellCommand, windowsAgentsInvocation } from '../hosts/remote-cmd.js';
 /** Env var the askpass shim reads to know which bundle holds the password. */
 export const ASKPASS_BUNDLE_ENV = 'AGENTS_SSH_BUNDLE';
 /** Env var the askpass shim reads to know which key in the bundle is the password. */
@@ -72,20 +74,139 @@ export function fleetDialTarget(device) {
     }
 }
 /**
- * Wrap a remote command for the device's shell. Windows devices speak
- * PowerShell, so a bare command is run through `powershell -NoProfile
- * -EncodedCommand`; POSIX devices get the command verbatim (the remote login
- * shell parses it). Returns undefined when no command was given (interactive
+ * Render `cmd` as the single command string ssh sends to the peer.
+ *
+ * Windows devices speak PowerShell, so the result is run through
+ * `powershell -NoProfile -EncodedCommand`; POSIX devices get it as the remote
+ * login shell sees it. Returns undefined when no command was given (interactive
  * login).
+ *
+ * TWO MODES, and the difference is load-bearing rather than a convenience.
+ *
+ * The default joins the tokens RAW. That is not a bug to be tidied away: every
+ * existing caller of `agents ssh` relies on the remote shell interpreting what it
+ * is handed — `agents ssh box 'bash -lc "cd x && make"'` arrives as ONE token
+ * whose pipeline, globs and redirections the peer's shell must expand. Quoting
+ * that would ship the whole line as a literal argument and break it.
+ *
+ * `{ argv: true }` is for a caller that genuinely holds an argv ARRAY and needs
+ * each element delivered as exactly one token. Joining those raw destroys any
+ * token containing a space or a metacharacter — `['--title', 'two words']`
+ * arrives as three tokens, and `'a & b'` arrives as a backgrounded command — which
+ * is what a native client hitting this path actually hit.
+ *
+ * So fidelity is opt-in at the call site that knows which shape it has, and the
+ * quoting itself reuses the canonical helpers (`shellQuote`, {@link pwshQuote})
+ * rather than introducing a third escaping scheme.
  */
-export function wrapRemoteCommand(device, cmd) {
+export function wrapRemoteCommand(device, cmd, opts = {}) {
     if (cmd.length === 0)
         return undefined;
-    const joined = cmd.join(' ');
+    const prelude = opts.prelude ?? [];
+    let script;
+    if (opts.argv) {
+        // Quote EACH caller token so the peer receives it byte-for-byte, then prefix
+        // the prelude VERBATIM — it is already shell syntax and re-quoting it would
+        // break it (see `fleetRemotePrelude`).
+        if (device.shell === 'powershell') {
+            script = pwshExactArgvScript(cmd, prelude);
+        }
+        else {
+            script = [...prelude, ...cmd.map(shellQuote)].join(' ');
+        }
+    }
+    else {
+        // The default joins raw, which is what lets a caller hand the remote shell
+        // something to interpret. See the docblock above for why both must exist.
+        script = [...prelude, ...cmd].join(' ');
+    }
     if (device.shell === 'powershell') {
-        return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(joined)}`;
+        // Same renderer the Windows `agents` launcher uses, so a long script gets the
+        // compressed representation here too rather than only on that path. The
+        // interactive login route (`buildInteractiveShellCommand`, -NoExit) is
+        // deliberately left alone: it must stay an interactive session.
+        return renderPowershellCommand(script);
     }
-    return joined;
+    return script;
+}
+/**
+ * Single-quote one token for PowerShell's OWN parser. Inside a single-quoted pwsh
+ * string the only special character is `'`, escaped by doubling.
+ *
+ * This is correct for a value PowerShell itself consumes, and NOT sufficient for
+ * an argument handed on to a native program — see the Win32 note below.
+ */
+export function pwshQuote(token) {
+    return `'${token.replace(/'/g, "''")}'`;
+}
+/**
+ * Emit a PowerShell script that runs `cmd` with EXACT argv, for either kind of
+ * target a Windows peer can name.
+ *
+ * Windows has no argv array: a process receives ONE string and splits it itself.
+ * PowerShell 5.1 rebuilds that string when it invokes a native program, and its
+ * serializer is lossy — measured on a real peer, an EMPTY argument is dropped and
+ * an embedded `"` is discarded, so the callee's argv silently shifts.
+ *
+ * The obvious fix, the `--%` stop-parsing token, is NOT used, because measurement
+ * killed it three ways:
+ *   - it only applies to a NATIVE command, and `agents` on Windows resolves to
+ *     `agents.ps1`, so a script target received `--%` as a literal argument and
+ *     the whole remainder as one string;
+ *   - a token containing a NEWLINE terminates the directive, producing a parser
+ *     error;
+ *   - it performs cmd-style `%VAR%` expansion, so a literal `%PATH%` became six
+ *     arguments — the exact opposite of exact argv.
+ *
+ * So the script branches on what the peer's own command discovery finds:
+ *
+ *   - **native executable** — launched through `System.Diagnostics.Process` with a
+ *     pre-built `Arguments` string escaped by {@link quoteWin32ExecArg}. .NET hands
+ *     that string to `CreateProcess` essentially verbatim, so the child's
+ *     `CommandLineToArgvW` reconstructs the tokens exactly; no shell sees it, so
+ *     no `%VAR%` expansion and no newline sensitivity. `UseShellExecute = $false`
+ *     with no redirection leaves the child on the inherited handles, which is what
+ *     lets a binary stdout stream through unchanged.
+ *   - **anything else** (a `.ps1`/`.cmd` launcher, a function, a cmdlet, an alias)
+ *     — invoked with a splatted PowerShell array. That is an in-process call, so
+ *     the native serializer is never involved and every token survives as itself.
+ *
+ * The exit code is propagated in both branches; a script launcher that sets no
+ * `$LASTEXITCODE` is left alone rather than forced to 0.
+ */
+function pwshExactArgvScript(cmd, prelude) {
+    // The Agents CLI gets the canonical launcher, not the generic dispatch. On
+    // Windows `agents` is an npm `agents.ps1` whose own body splats `$args` into
+    // native node.exe — the PowerShell 5.1 lossy path — so even a perfectly
+    // splatted call into that script loses an embedded quote one layer deeper.
+    // `windowsAgentsInvocation` resolves the package's declared entry and runs it
+    // directly, which is the only way the real Agents parser sees exact tokens.
+    const bin = cmd[0];
+    if (bin === 'agents' || bin === 'ag') {
+        // `windowsAgentsInvocation` leaves the child's code in `$zq`.
+        return [...prelude, windowsAgentsInvocation(cmd.slice(1), bin), 'exit $zq'].join('\n');
+    }
+    const program = pwshQuote(cmd[0]);
+    const rest = cmd.slice(1);
+    const splat = rest.length > 0 ? `@(${rest.map(pwshQuote).join(', ')})` : '@()';
+    return [
+        ...prelude,
+        `$ErrorActionPreference='Stop'`,
+        `$__c = Get-Command -Name ${program} -ErrorAction Stop`,
+        `if ($__c.CommandType -eq 'Application') {`,
+        // One emitter for the .NET native-exec block, shared with the Windows
+        // `agents` launcher in `hosts/remote-cmd.ts`; a second copy would drift.
+        ...pwshNativeExecStatements('$__c.Source', pwshLiteral(rest.map(quoteWin32ExecArg).join(' '))).map((line) => `  ${line}`),
+        // `pwshNativeExecStatements` names the process handle `$zp`.
+        `  exit $zp.ExitCode`,
+        `}`,
+        // `@__a` SPLATS the array into separate arguments. `& $__c @(...)` on an
+        // array LITERAL does not splat — it passes one array-valued argument, which
+        // a real peer reported back as every token collapsed into one.
+        `$__a = ${splat}`,
+        `& $__c @__a`,
+        `if ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }`,
+    ].join('\n');
 }
 /**
  * True when `cmd` is a browser drive: `agents browser …`, `ag browser …`, or
@@ -123,22 +244,43 @@ export function isAgentsBrowserDrive(cmd) {
  * fan-out stamps the marker before {@link buildSshInvocation}) is left unchanged
  * so nothing is doubled.
  */
-export function markFleetRemote(cmd, device, provenanceEnv = actorEnv(resolveActor())) {
+/**
+ * The provenance prefix as READY SHELL SYNTAX for the device's shell.
+ *
+ * These tokens are already quoted/escaped for their target shell — a POSIX
+ * `K=V` pair is `shellQuote`d here, and a PowerShell assignment is a complete
+ * statement with its own doubled quotes. That matters because argv mode quotes
+ * every token it is handed: quoting THESE again turns
+ * `'AGENTS_ACTOR=Some Name'` into `''\''AGENTS_ACTOR=Some Name'\'''` and turns a
+ * pwsh assignment into an inert string literal. So the prelude is composed
+ * SEPARATELY from the caller's argv rather than concatenated into it, and this is
+ * the single definition both paths use.
+ */
+export function fleetRemotePrelude(device, provenanceEnv = actorEnv(resolveActor())) {
     if (device.shell === 'powershell') {
-        // Exact-match guard, symmetric with the POSIX branch below: the marker token
-        // is always this literal, so `startsWith` would only loosen it for no gain.
-        if (cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`)
-            return cmd;
-        const prelude = [
+        return [
             `$env:AGENTS_FLEET_REMOTE='1';`,
             ...Object.entries(provenanceEnv).map(([k, v]) => `$env:${k}='${v.replace(/'/g, "''")}';`),
         ];
-        return [...prelude, ...cmd];
     }
-    if (cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1')
+    return [
+        'env',
+        'AGENTS_FLEET_REMOTE=1',
+        ...Object.entries(provenanceEnv).map(([k, v]) => shellQuote(`${k}=${v}`)),
+    ];
+}
+/** True when `cmd` already carries the prelude {@link fleetRemotePrelude} emits. */
+function alreadyMarked(cmd, device) {
+    if (device.shell === 'powershell')
+        return cmd[0] === `$env:AGENTS_FLEET_REMOTE='1';`;
+    return cmd[0] === 'env' && cmd[1] === 'AGENTS_FLEET_REMOTE=1';
+}
+export function markFleetRemote(cmd, device, provenanceEnv = actorEnv(resolveActor())) {
+    // Exact-match guard: the marker token is always this literal, so `startsWith`
+    // would only loosen it for no gain.
+    if (alreadyMarked(cmd, device))
         return cmd;
-    const actorTokens = Object.entries(provenanceEnv).map(([k, v]) => shellQuote(`${k}=${v}`));
-    return ['env', 'AGENTS_FLEET_REMOTE=1', ...actorTokens, ...cmd];
+    return [...fleetRemotePrelude(device, provenanceEnv), ...cmd];
 }
 /**
  * Build the remote command that starts an INTERACTIVE LOGIN shell inside a
@@ -229,10 +371,16 @@ export function buildSshInvocation(device, cmd, askpassShimPath, hostKey = {}, o
     // Stamp the consent marker on the REMOTE command, not the local ssh env:
     // SSH_ASKPASS lives on this side; AGENTS_FLEET_REMOTE must be visible to the
     // process that runs on the peer.
-    const remoteCmd = !interactive && isAgentsBrowserDrive(cmd) ? markFleetRemote(cmd, device) : cmd;
+    // Provenance is composed as a PRELUDE, not prepended to the argv array. In argv
+    // mode every token handed to `wrapRemoteCommand` is quoted, and the prelude is
+    // already shell syntax — mixing them in meant the actor pairs were quoted twice
+    // (breaking any value with a space or a quote) and the pwsh assignments became
+    // inert string literals.
+    const needsProvenance = !interactive && isAgentsBrowserDrive(cmd) && !alreadyMarked(cmd, device);
+    const prelude = needsProvenance ? fleetRemotePrelude(device) : [];
     const remote = interactive
         ? buildInteractiveShellCommand(device, opts.interactiveCwd)
-        : wrapRemoteCommand(device, remoteCmd);
+        : wrapRemoteCommand(device, cmd, { ...(opts.argv ? { argv: true } : {}), ...(prelude.length > 0 ? { prelude } : {}) });
     const env = {};
     const args = [
         ...hostKeyCheckingOpts(hostKey.pinned ?? false, hostKey.knownHostsFile),

package/dist/lib/devices/doctor-findings.js

@@ -41,7 +41,7 @@ import chalk from 'chalk';
 import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, supportsAccountInspection } from '../agents.js';
 import { blocksLocalScripts } from '../platform/winpath.js';
-import { loginHint } from '../signin-badge.js';
+import { loginHint, loginSubcommand, SUBCOMMAND_LOGIN_AGENTS } from '../signin-badge.js';
 import { CONFIG_ENV_ISOLATED_AGENTS } from '../installations/shims.js';
 import { padToWidth, stringWidth } from '../text/width.js';
 import { windowsSshEnrollmentProblem } from './windows-ssh-enrollment.js';
@@ -78,11 +78,7 @@ const NO_PER_VERSION_LOGIN = new Set(ALL_AGENT_IDS.filter((a) => !ISOLATED_LOGIN
  *    `subcommand` — `<cli> login` / `<cli> auth login`, runnable via `--`
  *    `in-tui`     — claude only: a `/login` slash command inside its own TUI
  *    `on-launch`  — the device/oauth flow starts when the agent launches */
-const LOGIN_SUBCOMMAND = {
-    codex: 'login',
-    grok: 'login',
-    opencode: 'auth login',
-};
+const LOGIN_SUBCOMMAND = Object.fromEntries(SUBCOMMAND_LOGIN_AGENTS.map((agent) => [agent, loginSubcommand(agent)]));
 /** Kinds whose fix is inherently PER VERSION, so a row collapsed across versions
  *  could not carry a correct remediation. A login is the whole set: there is no
  *  `@all` selector for it, and dropping the version falls back to the bare native

package/dist/lib/feed/answer.d.ts

@@ -1,14 +1,133 @@
 import { type ActiveSession } from '../session/active.js';
 import { type MessageReceipt } from './feed.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 declare const ANSWER_DEADLINE_MS = 20000;
+/** Slice of the budget the optional PR-review enrichment may spend. */
+export declare const PR_ENRICHMENT_BUDGET_MS = 4000;
+/** Budget for the forwarded leg — the remote repeats the local work under its own deadline. */
+export declare const REMOTE_ANSWER_TIMEOUT_MS = 25000;
+/**
+ * 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 declare const STRANDED_CLAIM_MS = 60000;
+/**
+ * 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 declare const RESUME_SETTLE_MS = 2000;
+/**
+ * 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 declare const HOLDER_RECEIPT_WAIT_MS = 400;
+/** Why an answer could not be delivered — the discriminant the operator UI branches on. */
+export type AnswerFailureCode = 'malformed_key' | 'no_session' | 'stale' | 'unverified' | 'unauthorized' | 'unknown_choice' | 'empty_answer' | 'refused' | 'rail_failed' | 'timeout' | 'remote_failed';
+/** A CONFIRMED failure: nothing reached a rail, the claim is released, retry is safe. */
+export declare class AnswerError extends Error {
+    readonly code: AnswerFailureCode;
+    constructor(message: string, code: AnswerFailureCode);
+}
+/**
+ * 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 declare class AnswerUnknownError extends Error {
+    constructor(message: string);
+}
+/**
+ *   delivered        — this call handed the answer to a rail.
+ *   already_answered — another claim owns it; the reported evidence is that claim's.
+ *   unknown          — something may have landed; do NOT resend, check delivery.
+ *   failed           — confirmed: nothing was delivered.
+ */
+export type AnswerStatus = 'delivered' | 'already_answered' | 'unknown' | 'failed';
+/**
+ *   receipt     — a real {@link MessageReceipt} exists on the block.
+ *   unconfirmed — no receipt evidence either way. The card must NOT be cleared.
+ *   failed      — confirmed failure, including a `dropped`/`expired` receipt.
+ */
+export type AnswerDelivery = 'receipt' | 'unconfirmed' | 'failed';
+export interface FeedAnswerResult {
+    status: AnswerStatus;
+    /** How much the CLI can actually vouch for. */
+    delivery: AnswerDelivery;
+    /** The block's real receipt. Absent means no rail ever reported one. */
+    receipt?: MessageReceipt;
+    /**
+     * The AGENT's own evidence that it received the answer — a `consumed` or
+     * `continued` receipt. A `queued` receipt is delivery, never resolution, so it
+     * leaves this false. Removal of the item from the feed resolves the card on
+     * its own; this flag only ever adds evidence, it never withholds it.
+     */
+    resolved: boolean;
+    /** Human explanation for a failure, an unknown, or an unconfirmed delivery. */
+    reason?: string;
+    /** Set when `status` is `failed`. */
+    code?: AnswerFailureCode;
+    attentionKey: string;
+    blockId?: string;
+    /** The device that owns the item — the exact target a delivery check re-queries. */
+    host?: string;
+    /**
+     * Stable identity of the delivery attempt (the claim timestamp). A delivery
+     * check correlates its read-only answer with the attempt it is checking, so
+     * "still unconfirmed" is distinguishable from "a newer attempt replaced it".
+     */
+    attempt?: string;
+}
 interface VerifiedOperator {
     id?: string;
     verified: boolean;
     label?: string;
 }
-interface FeedAnswerResult {
-    status: 'delivered' | 'already_answered';
-    receipt: MessageReceipt;
+export interface ParsedAttentionKey {
+    host: string;
+    sessionId: string;
+    generation: string;
 }
+/**
+ * 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 declare function parseAttentionKey(key: string): ParsedAttentionKey;
+/**
+ * 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 declare function answerOwnerIsLocal(host: string, self?: string): boolean;
+/**
+ * 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 declare function classifyReceipt(receipt: MessageReceipt): {
+    delivery: AnswerDelivery;
+    resolved: boolean;
+};
+/**
+ * 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 declare function checkAnswerDelivery(attentionKey: string, feedRoot?: string, expectedAttempt?: string): FeedAnswerResult;
 /** Atomically claim the first answer, then route it over the session's recorded reply rail. */
 export declare function claimAndRouteAttentionAnswer(input: {
     attentionKey: string;
@@ -18,13 +137,43 @@ export declare function claimAndRouteAttentionAnswer(input: {
     feedRoot?: string;
     mailboxRoot?: string;
     sessions?: ActiveSession[];
+    deadlineMs?: number;
 }): Promise<FeedAnswerResult>;
-/** Forward a fleet attention answer to the device that owns its scope. */
+/**
+ * The remote `agents feed answer` argv for a forwarded answer. Exported so the
+ * exact tokens that cross the hop are asserted directly.
+ */
+export declare function remoteAnswerArgv(input: {
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operatorId?: string;
+    check?: boolean;
+    attempt?: string;
+}): string[];
+/**
+ * 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 declare function forwardFeedAnswer(input: {
     host: string;
     attentionKey: string;
     choiceId?: string;
     text?: string;
     operatorId?: string;
+    check?: boolean;
+    attempt?: string;
+    timeoutMs?: number;
 }): Promise<FeedAnswerResult>;
 export {};