@phnx-labs/agents-cli 1.22.46 → 1.22.47

package/dist/lib/devices/registry.js

@@ -17,8 +17,9 @@ import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import lockfile from 'proper-lockfile';
-import { getDevicesRegistryPath, getDevicesIgnoredPath } from '../state.js';
+import { getDevicesRegistryPath, readMeta, updateMeta } from '../state.js';
 import { atomicWriteJsonSync } from '../fs-atomic.js';
+import { machineId } from '../machine-id.js';
 /**
  * Whether a fan-out should dial this device, honouring the preference stated on
  * {@link DeviceProfile.reachability}: the live SSH probe wins over the cached
@@ -62,12 +63,46 @@ function registryPath() {
 /** Valid logical device name: the ssh-alias charset, so it renders into an
  * unambiguous `Host` stanza and is safe as an ssh target. */
 const DEVICE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-/** Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.). */
+/**
+ * `--device` values that mean "resolve me", not "connect to a box with this
+ * name". A real device registered under one of these would be unreachable,
+ * and pinning `interactive.host` to one is a misconfiguration that has to fail
+ * at WRITE time — otherwise the read side can only report "none is set", which
+ * tells the user to run the command they just ran.
+ */
+export const RESERVED_DEVICE_NAMES = new Set(['auto', 'interactive', 'all']);
+/**
+ * Throw if `name` is not usable as an ssh alias (no spaces, quotes, etc.).
+ *
+ * SHAPE ONLY. Safe on read paths, which must keep working for a name that is
+ * already registered — including one this version would refuse to create.
+ */
 export function assertValidDeviceName(name) {
     if (!DEVICE_NAME_RE.test(name)) {
         throw new Error(`Invalid device name ${JSON.stringify(name)}. Use letters, digits, '.', '_', '-' (no spaces) — e.g. 'win-mini'.`);
     }
 }
+/**
+ * Throw if `name` cannot be used for a NEW device: bad shape, or a reserved
+ * routing sentinel.
+ *
+ * Deliberately separate from {@link assertValidDeviceName}, and called from
+ * exactly two kinds of place: `agents devices add <name>`, and the config keys
+ * that point AT a device (`interactive.host`, `usage.primary-host`).
+ *
+ * Not from `upsertDevice`, `addIgnored` or the discovery writers. Those all
+ * receive tailnet node names the user never typed — `devices sync` upserts every
+ * observed node in a loop with no per-node catch, so one node named `auto` would
+ * abort the entire sync and register nothing after it. A name the fleet OBSERVES
+ * is not a name anyone CHOSE; only the second kind is policy's business.
+ */
+export function assertRegistrableDeviceName(name) {
+    assertValidDeviceName(name);
+    if (RESERVED_DEVICE_NAMES.has(name.trim().toLowerCase())) {
+        throw new Error(`${JSON.stringify(name)} is a reserved --device value, not a device name. ` +
+            `Reserved: ${[...RESERVED_DEVICE_NAMES].join(', ')}.`);
+    }
+}
 /** Map a Tailscale `OS` field to our platform enum. */
 export function platformFromOs(os) {
     switch ((os ?? '').toLowerCase()) {
@@ -246,55 +281,76 @@ export async function removeDevice(name) {
         return true;
     });
 }
-function ignoredPath() {
-    return getDevicesIgnoredPath();
+/**
+ * The full ignore-list entries — who dismissed a node, when, and on which box —
+ * the typed read side for `agents devices ignored`. Absent `fleet.ignored` =>
+ * []. A malformed block is a hard error for the same reason the registry is:
+ * silently returning [] would let the next write wipe the user's dismissals.
+ */
+export function loadIgnoredEntries(meta = readMeta()) {
+    const raw = meta.fleet?.ignored;
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) ||
+        raw.some((e) => !e ||
+            typeof e.name !== 'string' ||
+            typeof e.ignoredAt !== 'string' ||
+            typeof e.ignoredOn !== 'string')) {
+        throw new Error(`Device ignore-list corrupted in agents.yaml (fleet.ignored): expected a list of { name, ignoredAt, ignoredOn } entries. Inspect and repair ~/.agents/agents.yaml.`);
+    }
+    return raw;
 }
-/** Load the set of ignored node names. Missing file => empty set. A malformed
- * file is a hard error for the same reason the registry is: silently returning
- * [] would let the next write wipe the user's dismissals. */
+/** Load the set of ignored node names. Same corruption contract as
+ * {@link loadIgnoredEntries}. */
 export async function loadIgnored() {
-    const p = ignoredPath();
-    let raw;
-    try {
-        raw = await fs.readFile(p, 'utf-8');
-    }
-    catch (err) {
-        if (err && err.code === 'ENOENT')
-            return new Set();
-        throw err;
-    }
-    try {
-        const parsed = JSON.parse(raw);
-        return new Set(Array.isArray(parsed.ignored) ? parsed.ignored : []);
-    }
-    catch (err) {
-        throw new Error(`Device ignore-list corrupted at ${p}: ${err?.message ?? err}. Inspect and restore from backup.`);
-    }
+    return new Set(loadIgnoredEntries().map((e) => e.name));
 }
 /** True if `name` is on the ignore-list. */
 export async function isIgnored(name) {
     return (await loadIgnored()).has(name);
 }
+/**
+ * Union `names` into the meta's ignore-list, stamping new entries with
+ * `ignoredAt` and THIS machine's id. Existing entries keep their original
+ * who/when, so re-adding a name is a true no-op. Returns the input unchanged
+ * when no name is new. Exported for the one-shot legacy-store migration in
+ * lib/devices/config-migration.ts.
+ */
+export function withIgnoredAdded(meta, names, ignoredAt) {
+    const entries = loadIgnoredEntries(meta); // throws on a corrupted block — never wipe it
+    const have = new Set(entries.map((e) => e.name));
+    const fresh = names.filter((n) => !have.has(n));
+    if (fresh.length === 0)
+        return meta;
+    const fleet = (meta.fleet ?? { devices: {} });
+    const ignored = [
+        ...entries,
+        ...fresh.map((name) => ({ name, ignoredAt, ignoredOn: machineId() })),
+    ].sort((a, b) => a.name.localeCompare(b.name));
+    const nextFleet = { ...fleet, ignored };
+    return { ...meta, fleet: nextFleet };
+}
 /** Add a node name to the ignore-list. Idempotent. Returns the resulting set. */
 export async function addIgnored(name) {
     assertValidDeviceName(name);
-    const p = ignoredPath();
-    return withRegistryLock(p, async () => {
-        const set = await loadIgnored();
-        set.add(name);
-        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
-        return set;
-    });
+    const meta = updateMeta((m) => withIgnoredAdded(m, [name], new Date().toISOString()));
+    return new Set(loadIgnoredEntries(meta).map((e) => e.name));
 }
 /** Remove a node name from the ignore-list (un-ignore). Returns false if it was
  * not ignored. */
 export async function removeIgnored(name) {
-    const p = ignoredPath();
-    return withRegistryLock(p, async () => {
-        const set = await loadIgnored();
-        if (!set.delete(name))
-            return false;
-        atomicWriteJsonSync(p, { ignored: [...set].sort(), updatedAt: new Date().toISOString() });
-        return true;
+    let removed = false;
+    updateMeta((m) => {
+        const fleet = m.fleet;
+        if (!fleet?.ignored)
+            return m;
+        const entries = loadIgnoredEntries(m);
+        const next = entries.filter((e) => e.name !== name);
+        if (next.length === entries.length)
+            return m;
+        removed = true;
+        const nextFleet = { ...fleet, ignored: next };
+        return { ...m, fleet: nextFleet };
     });
+    return removed;
 }

package/dist/lib/devices/stats-cache.d.ts

@@ -8,8 +8,12 @@ import type { DeviceProfile } from './registry.js';
  * rewrites the cache, unreachable boxes included).
  */
 export declare const STATS_STALE_MS: number;
+/** Static hardware totals are valid for seven days. */
+export declare const SPECS_STALE_MS: number;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export declare function isFreshDeviceStats(stats: DeviceStats, now?: number): boolean;
+/** True when cached core, RAM-total, and disk-total facts remain current. */
+export declare function isFreshDeviceSpecs(stats: DeviceStats, now?: number): boolean;
 /** Read the whole cache (best-effort; a missing/corrupt file yields an empty map). */
 export declare function readStatsCache(): Record<string, DeviceStats>;
 /**
@@ -30,6 +34,8 @@ export interface FleetStatsResult {
 export interface LoadFleetStatsOptions {
     /** Skip the cache and live-probe every device (the `--refresh`/`--live` path). */
     forceRefresh?: boolean;
+    /** Read only static hardware facts, whose cache lifetime is seven days. */
+    specsOnly?: boolean;
     /** Device name of THIS machine — always probed locally (no ssh), never cached-served. */
     selfName?: string;
     /** Injectable probes + cache IO for tests (default to the real ssh/local/disk ones). */

package/dist/lib/devices/stats-cache.js

@@ -37,10 +37,17 @@ const CACHE_FILE = '.fleet-stats.json';
  * rewrites the cache, unreachable boxes included).
  */
 export const STATS_STALE_MS = 3 * 60_000;
+/** Static hardware totals are valid for seven days. */
+export const SPECS_STALE_MS = 7 * 24 * 60 * 60_000;
 /** True when a cached row is still within {@link STATS_STALE_MS}. */
 export function isFreshDeviceStats(stats, now = Date.now()) {
     return now - stats.fetchedAt <= STATS_STALE_MS;
 }
+/** True when cached core, RAM-total, and disk-total facts remain current. */
+export function isFreshDeviceSpecs(stats, now = Date.now()) {
+    const fetchedAt = stats.specsFetchedAt ?? stats.fetchedAt;
+    return now - fetchedAt <= SPECS_STALE_MS;
+}
 function cacheFilePath() {
     return path.join(getCacheDir(), CACHE_FILE);
 }
@@ -93,13 +100,14 @@ export async function loadFleetStats(devices, opts = {}) {
     const toProbe = [];
     let servedFromCache = false;
     for (const d of devices) {
-        if (d.name === self) {
+        if (d.name === self && !opts.specsOnly) {
             // This machine is always probed locally — cheap, no ssh, always live.
             toProbe.push(d);
             continue;
         }
         const cached = cache[d.name];
-        if (cached && isFreshDeviceStats(cached, now)) {
+        const cacheFresh = cached && (opts.specsOnly ? isFreshDeviceSpecs(cached, now) : isFreshDeviceStats(cached, now));
+        if (cached && cacheFresh) {
             stats.set(d.name, cached);
             servedFromCache = true;
         }

package/dist/lib/exec.d.ts

@@ -94,6 +94,8 @@ export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 export interface ExecOptions {
     agent: AgentId;
     version?: string;
+    /** Version home whose native auth/config is overlaid onto this run's binary. */
+    configVersion?: string;
     /** Omit to launch the CLI interactively -- no prompt, no --print, stdio fully inherited. */
     prompt?: string;
     /** Force interactive mode even when a prompt is provided. Wins over `headless`. */
@@ -398,7 +400,7 @@ export interface TmuxWrapContext {
     raw: boolean;
     /** The AGENTS_NO_TMUX=1 escape hatch. */
     noTmuxEnv: boolean;
-    /** This device's `tmux.enabled` config — false turns the wrap off for every launch on this box. */
+    /** This device's `tmux.enabled` config — true opts every eligible launch on this box into the wrap. */
     configEnabled: boolean;
     /** Whether a tmux binary is on PATH. */
     tmuxAvailable: boolean;
@@ -407,7 +409,7 @@ export interface TmuxWrapContext {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * Opting into tmux wrapping gives every interactive agent an exact, unique `%pane` handle so
  * `agents sessions --active` can tell co-located agents apart, and lets `agents
  * focus` re-attach a live session without forking it. Pure so the gate is unit-
  * tested independently of the (side-effecting) spawn.
@@ -418,7 +420,7 @@ export interface TmuxWrapContext {
  *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
  *   - not --raw       — explicit opt-out.
  *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
+ *   - tmux.enabled    — this device explicitly opted into addressable tmux panes.
  *   - tmux installed  — otherwise there is nothing to wrap with.
  */
 export declare function shouldWrapInTmux(ctx: TmuxWrapContext): boolean;

package/dist/lib/exec.js

@@ -28,7 +28,7 @@ import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { isTmuxInstalled } from './tmux/binary.js';
-import { isTmuxEnabled } from './device-config.js';
+import { isTmuxEnabled, selfConfiguredDeviceRole } from './device-config.js';
 import { machineId } from './machine-id.js';
 import { shellQuote } from './ssh-exec.js';
 import { codexEditWritableRoots, codexPolicyArgs } from './codex-policy.js';
@@ -293,17 +293,28 @@ export function buildExecEnv(options) {
         // Resolve version/versionHome here (this module already imports
         // installations/versions); the adapters must not import it themselves or they
         // close a versions -> shims -> harness -> adapter import cycle.
-        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.version);
+        const { version, versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion ?? options.version);
         configAdapter.applyExecConfigEnv(result, {
             agent: options.agent,
             version,
             versionHome,
             interactive: resolveInteractive(options),
+            deviceRole: selfConfiguredDeviceRole(),
             resolveClaudeSetupToken,
         });
     }
     else {
         stripForeignConfigDir(result);
+        // Grok's adapter owns the same GROK_HOME export in generated shims, but a
+        // labeled account deliberately runs one version's binary with another
+        // version's config. Apply that overlay here because the shim's binary-slot
+        // export cannot express a distinct account slot.
+        if (options.agent === 'grok' && options.configVersion) {
+            const { versionHome } = resolveConfigVersion(options.agent, options.cwd || process.cwd(), options.configVersion);
+            if (!versionHome)
+                throw new Error(`Cannot resolve Grok account config home for ${options.configVersion}.`);
+            result.GROK_HOME = path.join(versionHome, '.grok');
+        }
     }
     // Point the agent at its own mailbox so the PreToolUse `mailbox-inject` hook
     // knows which box to drain and inject mid-run. Keyed by the session id — the
@@ -322,6 +333,7 @@ export function buildExecEnv(options) {
     // every event the child emits. `options.sessionId` is the CHILD's id, so read the
     // spawner from the live env; guard a same-session resume from naming itself parent.
     // Local-spawn scope here; forwarding it across the `--device` SSH hop is Phase 4.
+    delete result.AGENTS_PARENT_SESSION_ID;
     const spawnerSessionId = process.env.AGENTS_SESSION_ID || process.env.AGENT_SESSION_ID;
     if (spawnerSessionId && spawnerSessionId !== options.sessionId) {
         result.AGENTS_PARENT_SESSION_ID = spawnerSessionId;
@@ -388,6 +400,7 @@ export const AGENT_COMMANDS = {
             // independent; legacy --sandbox flags cannot express that combination.
             plan: [],
             edit: [],
+            auto: [],
             // skip = codex --yolo: drops the sandbox entirely and approves anything.
             skip: ['--dangerously-bypass-approvals-and-sandbox'],
         },
@@ -1163,7 +1176,7 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  * Decide whether to run an interactive agent INSIDE a detached tmux session on
  * the shared socket (then attach the current TTY) instead of a bare spawn.
  *
- * tmux-wrapping gives every interactive agent an exact, unique `%pane` handle so
+ * Opting into tmux wrapping gives every interactive agent an exact, unique `%pane` handle so
  * `agents sessions --active` can tell co-located agents apart, and lets `agents
  * focus` re-attach a live session without forking it. Pure so the gate is unit-
  * tested independently of the (side-effecting) spawn.
@@ -1174,7 +1187,7 @@ export function isPaneKnownAliveFromQueryResult(code, stdout) {
  *   - not already in tmux — nesting tmux-in-tmux is pointless and confusing.
  *   - not --raw       — explicit opt-out.
  *   - not AGENTS_NO_TMUX=1 — env opt-out (CI, scripts, the shim passthrough path).
- *   - tmux.enabled    — this device's durable opt-out, for a box whose tmux is broken.
+ *   - tmux.enabled    — this device explicitly opted into addressable tmux panes.
  *   - tmux installed  — otherwise there is nothing to wrap with.
  */
 export function shouldWrapInTmux(ctx) {
@@ -1282,11 +1295,14 @@ export function formatPaneTail(raw, maxLines = 30) {
  * Lifecycle:
  *   1. createSession() launches `sh -c 'exec env … agent'` detached, remain-on-exit
  *      on (global), and returns the pane id.
- *   2. A per-session `pane-died` hook detaches the attach client the instant the
- *      AGENT pane exits, so attach returns instead of parking on a dead pane. The
- *      hook is guarded on `#{hook_pane}` so it fires ONLY for the agent pane —
- *      user-created splits (Ctrl-b " / %) that the user exits are closed in place
- *      (`kill-pane`) instead of tearing down the whole client, so exiting one
+ *   2. A per-session `pane-died` hook tears the session down the instant the AGENT
+ *      pane exits: with a client attached it `detach-client`s so attach returns
+ *      instead of parking on a dead pane (then resolveAfterAttach reads the status
+ *      and kills); with no client attached it `kill-session`s outright, so a
+ *      wrapped agent that exits unattended can't leave a dead husk lingering on the
+ *      socket. The hook is guarded on `#{hook_pane}` so it fires ONLY for the agent
+ *      pane — user-created splits (Ctrl-b " / %) that the user exits are closed in
+ *      place (`kill-pane`) instead of tearing down the whole client, so exiting one
  *      split leaves the agent running full-window rather than kicking you out.
  *   3. We record the agent pane's pid → session mapping (WITH the tmux pane) so the
  *      headless active-scan attributes it, then attach the TTY (blocking).
@@ -1303,7 +1319,7 @@ async function runInTmux(options, executable, args) {
     const idSeed = (options.sessionId ?? randomUUID()).slice(0, 8);
     const name = slugifyName(`ag-${options.agent}-${idSeed}`);
     const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
-    const NO_TMUX_TIP = `${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.\n  If tmux is broken on this machine, turn the wrap off for good: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
+    const NO_TMUX_TIP = `${GRAY}  This run used the opt-in tmux wrap. Re-run with --no-tmux for a direct launch, or turn the wrap off: agents config set devices.${machineId()}.tmux off${OFF}\n\n`;
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
     // gutted install that dies with ENOENT, a bad flag, a crash on startup) would
@@ -1600,11 +1616,10 @@ async function spawnAgent(options) {
         command: executable,
         args: redactArgs(args.slice(0, 10)),
     });
-    // Interactive spawn-wrap: on macOS/Linux, run the agent INSIDE a shared-socket
-    // tmux session (then attach this TTY) so it gets a unique, addressable %pane.
-    // Headless runs, Windows, already-in-tmux, --raw, and AGENTS_NO_TMUX=1 keep the
-    // bare spawn below. See shouldWrapInTmux / runInTmux.
-    if (shouldWrapInTmux({
+    // Interactive spawn-wrap: when this device opts in on macOS/Linux, run the
+    // agent INSIDE a shared-socket tmux session (then attach this TTY) so it gets
+    // a unique, addressable %pane. Every failed guard keeps the bare spawn below.
+    const wrapInTmux = shouldWrapInTmux({
         interactive,
         platform: process.platform,
         inTmux: !!process.env.TMUX,
@@ -1612,7 +1627,8 @@ async function spawnAgent(options) {
         noTmuxEnv: process.env.AGENTS_NO_TMUX === '1',
         configEnabled: isTmuxEnabled(),
         tmuxAvailable: isTmuxInstalled(),
-    })) {
+    });
+    if (wrapInTmux) {
         timer.mark('startup');
         try {
             const result = await runInTmux(options, executable, args);

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

@@ -0,0 +1,29 @@
+import { type ActiveSession } from '../session/active.js';
+import { type MessageReceipt } from './feed.js';
+export interface VerifiedOperator {
+    id?: string;
+    verified: boolean;
+    label?: string;
+}
+export interface FeedAnswerResult {
+    status: 'delivered' | 'already_answered';
+    receipt: MessageReceipt;
+}
+/** Atomically claim the first answer, then route it over the session's recorded reply rail. */
+export declare function claimAndRouteAttentionAnswer(input: {
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operator: VerifiedOperator;
+    feedRoot?: string;
+    mailboxRoot?: string;
+    sessions?: ActiveSession[];
+}): Promise<FeedAnswerResult>;
+/** Forward a fleet attention answer to the device that owns its scope. */
+export declare function forwardFeedAnswer(input: {
+    host: string;
+    attentionKey: string;
+    choiceId?: string;
+    text?: string;
+    operatorId?: string;
+}): Promise<FeedAnswerResult>;

package/dist/lib/feed/answer.js

@@ -0,0 +1,145 @@
+import { spawn } from 'node:child_process';
+import { getActiveSessions } from '../session/active.js';
+import { resolveAnswerRoute, resumeArgv } from '../answer-router.js';
+import { enqueue, mailboxDir } from '../mailbox.js';
+import { injectIntoTerminal } from '../terminal/index.js';
+import { verifyOperatorIdentity } from '../operator.js';
+import { blockIdForSession, getAnswerRecord, publishBlock, readBlock, readResolution, recordAnswer, recordMessageReceipt, rollbackAnswerClaim, } from './feed.js';
+import { reconcileAttention } from './attention.js';
+import { readPullRequestStatus } from './pr-status.js';
+import { getAgentsInvocation } from '../daemon/daemon.js';
+function sessionForBlock(block, sessions) {
+    return sessions.find((session) => session.sessionId === block.sessionId || session.agentId === block.mailboxId);
+}
+function blockFromAttention(attention, session) {
+    return {
+        blockId: blockIdForSession(attention.sessionId), sessionId: attention.sessionId,
+        mailboxId: attention.mailboxId, host: attention.host, runtime: session.kind,
+        generation: attention.key.slice(attention.key.lastIndexOf('/') + 1), source: attention.source,
+        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',
+        safeDefault: attention.safeDefault,
+    };
+}
+async function resolveBlock(attentionKey, sessions, root) {
+    const ownerHost = attentionKey.slice(0, attentionKey.indexOf('/'));
+    for (const session of sessions) {
+        if (!session.sessionId)
+            continue;
+        let block = readBlock(blockIdForSession(session.sessionId), root);
+        const projectedSession = { ...session, host: ownerHost };
+        const attention = reconcileAttention({ block, session: projectedSession, pullRequest: await readPullRequestStatus(session), resolution: readResolution(blockIdForSession(session.sessionId), root), nowMs: Date.now() });
+        if (attention?.key === attentionKey && block)
+            return { block, attention };
+        // The winning caller advances the block to answered before a concurrent
+        // loser resolves it. Reconstruct only this block's original generation so
+        // the loser can return already_answered without routing a second reply.
+        if (block) {
+            const original = reconcileAttention({ block: { ...block, state: 'open', answer: undefined }, session: projectedSession, nowMs: Date.now() });
+            if (original?.key === attentionKey && getAnswerRecord(block.blockId, root))
+                return { block, attention: original };
+        }
+        if (attention?.key === attentionKey) {
+            block = blockFromAttention(attention, session);
+            publishBlock(block, root);
+            return { block, attention };
+        }
+    }
+    throw new Error(`No open attention item matches '${attentionKey}'.`);
+}
+/** 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 Error('Exactly one of choiceId or text is required.');
+    const sessions = input.sessions ?? await getActiveSessions();
+    const { block, attention } = await resolveBlock(input.attentionKey, sessions, input.feedRoot);
+    const choice = input.choiceId == null ? undefined : attention.choices?.find((item) => item.id === input.choiceId);
+    if (input.choiceId != null && !choice)
+        throw new Error(`Unknown choice '${input.choiceId}' for '${input.attentionKey}'.`);
+    const answer = input.text ?? choice?.deliveryKey ?? choice?.label;
+    if (!answer)
+        throw new Error('Answer is empty.');
+    const verified = input.operator.verified && verifyOperatorIdentity(input.operator.id);
+    const previousResolution = readResolution(block.blockId, input.feedRoot);
+    const claim = recordAnswer(block.blockId, {
+        answeredBy: input.operator.label,
+        answeredFrom: 'feed',
+        operatorId: input.operator.id,
+        verified,
+    }, input.feedRoot);
+    if (!claim.ok) {
+        if ('unauthorized' in claim)
+            throw new Error(claim.reason);
+        const existing = getAnswerRecord(block.blockId, input.feedRoot) ?? claim.existing;
+        return { status: 'already_answered', receipt: {
+                msgId: `answer-${block.blockId}`,
+                status: 'queued',
+                at: existing.answeredAt,
+                from: existing.answeredBy ?? existing.answeredFrom,
+            } };
+    }
+    const claimed = getAnswerRecord(block.blockId, input.feedRoot);
+    if (!claimed)
+        throw new Error(`Answer claim for '${input.attentionKey}' was not persisted.`);
+    const session = sessionForBlock(block, sessions);
+    const route = resolveAnswerRoute({ mailboxId: block.mailboxId, answer, block, session });
+    if (route.kind === 'refuse') {
+        rollbackAnswerClaim(block.blockId, claimed.answeredAt, block, previousResolution, input.feedRoot);
+        throw new Error(route.reason);
+    }
+    let msgId;
+    try {
+        if (route.kind === 'mailbox') {
+            msgId = enqueue(mailboxDir(block.mailboxId, input.mailboxRoot), {
+                to: block.mailboxId, text: answer, from: input.operator.label, blockId: block.blockId,
+            });
+        }
+        else if (route.kind === 'resume') {
+            const invocation = getAgentsInvocation(resumeArgv(route));
+            const child = spawn(invocation.command, invocation.args, { stdio: 'inherit', env: process.env });
+            const code = await new Promise((resolve) => { child.once('error', () => resolve(1)); child.once('close', (value) => resolve(value ?? 1)); });
+            if (code !== 0)
+                throw new Error(`Resume delivery for '${input.attentionKey}' exited ${code}.`);
+            msgId = `resume-${Date.now()}`;
+        }
+        else {
+            if (!route.inject || route.payload == null)
+                throw new Error(`Incomplete ${route.kind} reply rail.`);
+            const delivered = await injectIntoTerminal(route.inject, route.payload, { enter: true, combined: false });
+            if (!delivered.ok)
+                throw new Error(delivered.error ?? `Failed to deliver over ${route.kind}.`);
+            msgId = `inject-${Date.now()}`;
+        }
+    }
+    catch (error) {
+        rollbackAnswerClaim(block.blockId, claimed.answeredAt, block, previousResolution, input.feedRoot);
+        throw error;
+    }
+    const receipt = { msgId, status: 'queued', at: new Date().toISOString(), from: input.operator.label };
+    recordMessageReceipt(block.blockId, receipt, input.feedRoot);
+    return { status: 'delivered', receipt };
+}
+/** Forward a fleet attention answer to the device that owns its scope. */
+export async function forwardFeedAnswer(input) {
+    const remoteArgs = ['feed', 'answer', input.attentionKey, '--json'];
+    if (input.choiceId != null)
+        remoteArgs.push('--choice', input.choiceId);
+    if (input.text != null)
+        remoteArgs.push('--text', input.text);
+    if (input.operatorId)
+        remoteArgs.push('--as', input.operatorId);
+    const invocation = getAgentsInvocation(['ssh', input.host, 'agents', ...remoteArgs]);
+    const child = spawn(invocation.command, invocation.args, { stdio: ['ignore', 'pipe', 'pipe'], env: process.env });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    const code = await new Promise((resolve) => { child.once('error', () => resolve(1)); child.once('close', (value) => resolve(value ?? 1)); });
+    if (code !== 0)
+        throw new Error(stderr.trim() || `Remote feed answer on '${input.host}' exited ${code}.`);
+    const line = stdout.trim().split('\n').reverse().find((value) => value.startsWith('{'));
+    if (!line)
+        throw new Error(`Remote feed answer on '${input.host}' returned no JSON receipt.`);
+    return JSON.parse(line);
+}

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

@@ -0,0 +1,83 @@
+import type { ActiveSession } from '../session/active.js';
+import { type AttentionResolution, type AttentionSource, type AttentionState, type BlockOption, type BlockQuestion, type OpenBlock, type SourceCursor } from './feed.js';
+/** What an attention item is asking of the operator. */
+export type AttentionKind = 'question' | 'permission' | 'plan_review' | 'declared' | 'failure' | 'stall' | 'review';
+/** How an answer can be routed back to the waiting agent. */
+export type ReplyCapability = 'terminal' | 'tmux' | 'cloud' | 'team' | 'none';
+/**
+ * One answerable choice on an attention item. Extends {@link BlockOption} with a
+ * stable `id` the UI echoes back when the operator picks it, and an optional
+ * `deliveryKey` (the harness-native keystroke / selection token) that Track B's
+ * answer router resolves the reply rail with.
+ */
+export interface AttentionChoice extends BlockOption {
+    id: string;
+    deliveryKey?: string;
+}
+/**
+ * The canonical operator-facing attention record. One reconciled thing that needs
+ * a human, whatever produced it. This is the public envelope Tracks B and C
+ * consume — a stability contract, not an internal shape.
+ */
+export interface AttentionItem {
+    /** Stable identity: `host/session/generation`. A new generation is a new item. */
+    key: string;
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    project?: string;
+    kind: AttentionKind;
+    source: AttentionSource;
+    state: AttentionState;
+    /** ISO-8601 timestamp the ask opened. */
+    openedAt: string;
+    question?: BlockQuestion;
+    choices?: AttentionChoice[];
+    replyCapability: ReplyCapability;
+    safeDefault?: string;
+    /**
+     * Clusters IDENTICAL asks across different agents for batch triage. It is a hash
+     * of the RAW question intent (kind + verbatim question text + option labels) —
+     * deliberately NOT the UI-normalized display text, so two agents asking the same
+     * thing collapse even when the floor renders them differently.
+     */
+    fingerprint: string;
+    /** Where in the source this generation sits — the fence a resolution compares against. */
+    sourceCursor?: SourceCursor;
+}
+/**
+ * A pull-request attention signal, supplied BY the CLI (Track B refreshes it on a
+ * bounded TTL and hands it in). Track A only consumes the computed `needsHuman`
+ * flag — it never reaches into the extension's PR board or recomputes review
+ * state. Fields mirror the `gh pr view` projection so Track B can populate it.
+ */
+export interface PullRequestAttentionSignal {
+    number: number;
+    title?: string;
+    url?: string;
+    /** True when the PR is in a state that needs a human decision (review / merge). */
+    needsHuman: boolean;
+    reviewDecision?: string;
+    mergeable?: string;
+    state?: string;
+    isDraft?: boolean;
+}
+/**
+ * Fingerprint of an ask's raw intent. Uses the verbatim question text and option
+ * labels (NOT display-normalized text) so identical asks from different agents
+ * share a fingerprint for batch triage.
+ */
+export declare function attentionFingerprint(kind: AttentionKind, question?: BlockQuestion): string;
+/**
+ * Reconcile the feed block ledger, the session lifecycle, a CLI-supplied PR
+ * signal, and the latest resolution tombstone into one attention item — or
+ * `undefined` when nothing needs a human. Pure; the extension never chooses
+ * authority.
+ */
+export declare function reconcileAttention(input: {
+    block?: OpenBlock;
+    session: ActiveSession;
+    pullRequest?: PullRequestAttentionSignal;
+    resolution?: AttentionResolution;
+    nowMs: number;
+}): AttentionItem | undefined;