@phnx-labs/agents-cli 1.20.43 → 1.20.45

package/dist/lib/exec.js

@@ -515,7 +515,13 @@ export function buildExecCommand(options) {
             cmd[0] = absPath;
         }
         else {
-            cmd[0] = versionedName;
+            // No versioned shim on disk. Prefer the version's REAL launch binary
+            // (node_modules/.bin/<cli>) over the bare `<cli>@<version>` name — that
+            // literal is not on PATH and spawns as ENOENT (the `kimi@0.19.2` failure).
+            // Fall back to the literal only if the binary is absent (the run path's
+            // ensureAgentRunnable normally repairs/creates the alias before we reach here).
+            const realBinary = options.agent ? getBinaryPath(options.agent, options.version) : undefined;
+            cmd[0] = realBinary && fs.existsSync(realBinary) ? realBinary : versionedName;
         }
     }
     // Add reasoning effort flags (before mode flags for codex -c positioning)
@@ -814,6 +820,21 @@ export function buildTmuxAgentCommand(executable, args, env) {
     const agentCmd = [executable, ...args].map(shellQuote).join(' ');
     return `exec env ${envPrefix} ${agentCmd}`;
 }
+/**
+ * Trim a raw `tmux capture-pane` dump to its last `maxLines` non-empty lines
+ * (right-stripping each). Used by runInTmux to recap a fast-failed agent's
+ * output into the caller's shell so a launch crash (e.g. a gutted install that
+ * dies with ENOENT the instant it spawns) isn't swallowed by the bare
+ * `[detached]` the pane-died hook otherwise leaves behind.
+ */
+export function formatPaneTail(raw, maxLines = 30) {
+    return raw
+        .split('\n')
+        .map(l => l.replace(/\s+$/, ''))
+        .filter(l => l.length > 0)
+        .slice(-maxLines)
+        .join('\n');
+}
 /**
  * Run an interactive agent inside a detached tmux session on the shared socket,
  * attach the current TTY, and propagate the wrapped agent's exit code.
@@ -834,7 +855,7 @@ export function buildTmuxAgentCommand(executable, args, env) {
  *      (Ctrl-b d) — return 0 and LEAVE the session for `agents focus` to re-attach.
  */
 async function runInTmux(options, executable, args) {
-    const { createSession, killSession, paneExitStatus, setSessionHook, slugifyName } = await import('./tmux/session.js');
+    const { createSession, killSession, paneExitStatus, setSessionHook, slugifyName, agentPaneDiedHook, markSessionHookSchema } = await import('./tmux/session.js');
     const { getDefaultSocketPath } = await import('./tmux/paths.js');
     const { attachTmux, runTmux } = await import('./tmux/binary.js');
     const socket = getDefaultSocketPath();
@@ -855,7 +876,10 @@ async function runInTmux(options, executable, args) {
         // that split in place instead of detaching everyone (the pane-died hook runs
         // in the dead pane's context, so bare `kill-pane` targets it). Without the
         // guard, exiting any split kicked the user clean out of tmux.
-        await setSessionHook(name, 'pane-died', `if -F '#{==:#{hook_pane},${pane}}' 'detach-client -s =${name}' 'kill-pane'`, socket);
+        await setSessionHook(name, 'pane-died', agentPaneDiedHook(name, pane), socket);
+        // Stamp the schema marker so the daemon reconcile (which retrofits older
+        // sessions) recognizes this one as already current and skips it.
+        await markSessionHookSchema(name, socket);
         // Record the agent's OS pid (the pane leaf, thanks to `exec`) WITH its tmux
         // pane so the active-scan attributes it exactly and shows the %pane.
         let panePid = 0;
@@ -873,14 +897,54 @@ async function runInTmux(options, executable, args) {
             startedAtMs: Date.now(),
         });
     }
+    // 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
+    // otherwise leave only a bare `[detached]` with no clue why. Must run BEFORE
+    // killSession — capture-pane needs the session still alive (remain-on-exit
+    // keeps the dead pane readable until we tear it down). Best-effort throughout.
+    const surfacePaneFailure = async (status, headline) => {
+        if (!pane)
+            return;
+        let tail = '';
+        try {
+            const r = await runTmux({ socket, args: ['capture-pane', '-p', '-t', pane, '-S', '-200'], throwOnError: false });
+            if (r.code === 0)
+                tail = formatPaneTail(r.stdout);
+        }
+        catch { /* best-effort — a missing pane just means no recap */ }
+        const RED = '\x1b[31m', GRAY = '\x1b[90m', OFF = '\x1b[0m';
+        process.stderr.write(`\n${RED}agents: ${headline} (exit ${status ?? 1}).${OFF}\n`);
+        if (tail) {
+            process.stderr.write(`${GRAY}  ── last output from ${options.agent} ──${OFF}\n`);
+            process.stderr.write(tail.replace(/^/gm, '  ') + '\n');
+            process.stderr.write(`${GRAY}  ${'─'.repeat(30)}${OFF}\n`);
+        }
+        process.stderr.write(`${GRAY}  Tip: re-run with --no-tmux to launch the agent directly and see its full output.${OFF}\n\n`);
+    };
     // The agent could exit before we attach (fast failure). Don't attach to an
-    // already-dead pane — read its status directly and tear down.
+    // already-dead pane — surface its output + status directly and tear down.
     const before = pane ? await paneExitStatus(pane, socket) : { dead: false };
-    if (!before.dead) {
-        await attachTmux({ socket, args: ['attach-session', '-t', name] });
+    if (before.dead) {
+        // Only recap a FAILURE. A clean (0) exit before we attached is a successful
+        // quick run, not a crash — a red banner there would be spurious (mirrors the
+        // post-attach guard below).
+        if ((before.status ?? 0) !== 0) {
+            await surfacePaneFailure(before.status, `${options.agent} exited before it could start`);
+        }
+        await killSession(name, socket).catch(() => { });
+        return { exitCode: before.status ?? 0, stderr: '' };
     }
+    await attachTmux({ socket, args: ['attach-session', '-t', name] });
     const after = pane ? await paneExitStatus(pane, socket) : { dead: false };
     if (after.dead) {
+        // Nonzero exit after attach → the agent crashed rather than the user
+        // detaching cleanly (a clean detach leaves the pane ALIVE, handled below).
+        // The pane-died hook may have yanked the view before the error was readable,
+        // so recap it into the shell. A clean (0) exit stays quiet — nothing to say.
+        if ((after.status ?? 0) !== 0) {
+            await surfacePaneFailure(after.status, `${options.agent} exited`);
+        }
         await killSession(name, socket).catch(() => { });
         return { exitCode: after.status ?? 0, stderr: '' };
     }

package/dist/lib/hosts/dispatch.d.ts

@@ -45,6 +45,35 @@ export interface DispatchOptions {
  * resume wins when — defensively — both are set.
  */
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
+export interface InteractiveDispatchOptions {
+    agent: string;
+    /** Optional prompt — forwarded only when the caller explicitly forced interactive mode. */
+    prompt?: string;
+    mode?: string;
+    model?: string;
+    remoteCwd?: string;
+    sessionId?: string;
+    name?: string;
+    resume?: string;
+    passthroughArgs?: string[];
+    raw?: boolean;
+    /** Forward `--interactive` to the remote so a prompt-bearing run still starts the TUI. */
+    forceInteractive?: boolean;
+}
+/**
+ * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The
+ * remote agent sees a TTY, so we omit `--quiet`; the remote CLI will launch its
+ * normal interactive TUI / tmux wrapper. A prompt is only included when the
+ * caller explicitly forced interactive mode (otherwise the remote CLI would
+ * infer headless from the prompt).
+ */
+export declare function buildInteractiveRunForwardedArgs(opts: InteractiveDispatchOptions): string[];
+/**
+ * Run an agent interactively on a host, forwarding the local TTY over SSH.
+ * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
+ * tmux wrapping; the local machine is just the transport.
+ */
+export declare function runInteractiveOnHost(host: Host, opts: InteractiveDispatchOptions): Promise<number>;
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
 export interface CommandDispatchOptions {

package/dist/lib/hosts/dispatch.js

@@ -9,7 +9,7 @@
  * same core so a remote team supervisor keeps running after you disconnect.
  */
 import { randomUUID } from 'crypto';
-import { sshExec, shellQuote } from '../ssh-exec.js';
+import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
 import { remoteShellFor } from './remote-cmd.js';
@@ -105,6 +105,51 @@ export function buildRunForwardedArgs(opts) {
         args.push('--session-id', opts.sessionId);
     return args;
 }
+/**
+ * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The
+ * remote agent sees a TTY, so we omit `--quiet`; the remote CLI will launch its
+ * normal interactive TUI / tmux wrapper. A prompt is only included when the
+ * caller explicitly forced interactive mode (otherwise the remote CLI would
+ * infer headless from the prompt).
+ */
+export function buildInteractiveRunForwardedArgs(opts) {
+    const args = ['run', opts.agent];
+    if (opts.prompt && opts.forceInteractive)
+        args.push(opts.prompt);
+    if (opts.forceInteractive)
+        args.push('--interactive');
+    if (opts.mode)
+        args.push('--mode', opts.mode);
+    if (opts.model)
+        args.push('--model', opts.model);
+    if (opts.name)
+        args.push('--name', opts.name);
+    if (opts.resume)
+        args.push('--resume', opts.resume);
+    else if (opts.sessionId)
+        args.push('--session-id', opts.sessionId);
+    if (opts.raw)
+        args.push('--raw');
+    if (opts.passthroughArgs && opts.passthroughArgs.length > 0) {
+        args.push('--', ...opts.passthroughArgs);
+    }
+    return args;
+}
+/**
+ * Run an agent interactively on a host, forwarding the local TTY over SSH.
+ * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
+ * tmux wrapping; the local machine is just the transport.
+ */
+export async function runInteractiveOnHost(host, opts) {
+    const target = sshTargetFor(host);
+    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    for (const w of warnings)
+        process.stderr.write(`[hosts] warning: ${w}\n`);
+    const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
+    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const remoteCmd = `${cwd}${invocation}`;
+    return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
+}
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export async function dispatchToHost(host, opts) {
     const target = sshTargetFor(host);

package/dist/lib/hosts/logs.d.ts

@@ -2,9 +2,13 @@
  * Shared host-task log viewer — the show-or-follow core behind both
  * `agents hosts logs <id>` and the top-level `agents logs <id>`.
  *
- * A running task with follow re-enters the offset-tail (`followHostTask`);
- * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
- * place so the two commands can never drift.
+ * A running task with follow re-enters the offset-tail (`followHostTask`).
+ * Otherwise the view is **concise by default**: a bounded tail of the captured
+ * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
+ * log. `full` opts into the entire raw log. (A host run's real transcript lives
+ * on the remote, not the local index — surfacing its rich summary needs remote
+ * runs to be discoverable there first; until then the bounded tail is the safe
+ * concise default.) Kept in one place so the two commands can never drift.
  */
 export interface HostLogResult {
     /** False when no host task with this id exists (caller may fall through to sessions). */
@@ -12,5 +16,10 @@ export interface HostLogResult {
     /** Process exit code to adopt when the task was shown/followed. */
     exitCode?: number;
 }
-/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
-export declare function showHostTaskLog(id: string, follow: boolean): Promise<HostLogResult>;
+/**
+ * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
+ * default; `full` dumps the entire raw combined-stdout log.
+ */
+export declare function showHostTaskLog(id: string, follow: boolean, full?: boolean): Promise<HostLogResult>;
+/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
+export declare function tailLines(text: string, n: number): string;

package/dist/lib/hosts/logs.js

@@ -2,9 +2,13 @@
  * Shared host-task log viewer — the show-or-follow core behind both
  * `agents hosts logs <id>` and the top-level `agents logs <id>`.
  *
- * A running task with follow re-enters the offset-tail (`followHostTask`);
- * otherwise the captured local mirror (`localLogPath`) is printed. Kept in one
- * place so the two commands can never drift.
+ * A running task with follow re-enters the offset-tail (`followHostTask`).
+ * Otherwise the view is **concise by default**: a bounded tail of the captured
+ * combined-stdout, so an agent glancing at a dispatched run never pulls the whole
+ * log. `full` opts into the entire raw log. (A host run's real transcript lives
+ * on the remote, not the local index — surfacing its rich summary needs remote
+ * runs to be discoverable there first; until then the bounded tail is the safe
+ * concise default.) Kept in one place so the two commands can never drift.
  */
 import * as fs from 'fs';
 import chalk from 'chalk';
@@ -12,8 +16,13 @@ import { loadTask, localLogPath, updateTask, terminalPatch } from './tasks.js';
 import { followHostTask } from './progress.js';
 import { reconcileTask } from './reconcile.js';
 import { sshExecRaw } from '../ssh-exec.js';
-/** Show (or follow, when running) a dispatched host task's combined-stdout log. */
-export async function showHostTaskLog(id, follow) {
+/** Lines of raw combined-stdout to show in the concise (non-`full`) view. */
+const HOST_LOG_TAIL_LINES = 40;
+/**
+ * Show (or follow, when running) a dispatched host task. Bounded-tail summary by
+ * default; `full` dumps the entire raw combined-stdout log.
+ */
+export async function showHostTaskLog(id, follow, full = false) {
     const task = loadTask(id);
     if (!task)
         return { found: false };
@@ -36,21 +45,38 @@ export async function showHostTaskLog(id, follow) {
     // plain `logs <id>` also unsticks a task whose follower was killed. No-op (no
     // ssh) once the record is already terminal.
     reconcileTask(task);
+    // Raw combined-stdout: the whole log with `full`, else a bounded tail.
+    const raw = readTaskLog(task);
+    if (raw === null) {
+        process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
+        return { found: true, exitCode: 0 };
+    }
+    process.stdout.write(full ? raw : tailLines(raw, HOST_LOG_TAIL_LINES));
+    return { found: true, exitCode: 0 };
+}
+/** Read the task's combined-stdout — local mirror first, else fetch+cache remote. */
+function readTaskLog(task) {
     try {
-        process.stdout.write(fs.readFileSync(localLogPath(id), 'utf-8'));
+        return fs.readFileSync(localLogPath(task.id), 'utf-8');
     }
     catch {
         // No local log — task was dispatched with --no-follow. Fetch from the remote
         // on demand and cache locally so subsequent calls are instant.
         const remote = fetchAndCacheRemoteLog(task);
-        if (remote !== null) {
-            process.stdout.write(remote);
-        }
-        else {
-            process.stdout.write(chalk.gray('(no local log captured for this task)\n'));
-        }
+        return remote !== null ? remote.toString('utf-8') : null;
     }
-    return { found: true, exitCode: 0 };
+}
+/** Last `n` lines of `text`, prefixed with an elision note when truncated. */
+export function tailLines(text, n) {
+    const lines = text.split('\n');
+    // A trailing newline yields a final empty element — drop it from the count.
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    if (lines.length <= n)
+        return lines.join('\n') + '\n';
+    const hidden = lines.length - n;
+    const note = chalk.gray(`… ${hidden} earlier line${hidden === 1 ? '' : 's'} hidden — pass --full for the whole log\n`);
+    return note + lines.slice(-n).join('\n') + '\n';
 }
 /**
  * Fetch a task's remote log over SSH, write it to the local mirror path (for

package/dist/lib/hosts/remote-cmd.d.ts

@@ -101,3 +101,20 @@ export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
  * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
  */
 export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): string;
+/**
+ * Build the `ssh <target> <cmd>` string for `agents secrets import` on a Windows
+ * remote where the `.env` is piped over ssh stdin.
+ *
+ * We can't just run `agents secrets import <bundle> --from -`: the npm
+ * `agents.ps1` shim does NOT forward the ssh-piped stdin down to the underlying
+ * node process, so a raw fd-0 read (`--from -`) hangs forever (observed: the
+ * push to a Windows host times out). PowerShell ITSELF can read the pipe, so we
+ * read stdin into a temp file in PowerShell, import `--from <file>` (a plain
+ * file read, which the shim handles fine), and delete the temp file afterwards
+ * — success or failure. Backend defaults to the platform native store
+ * (Credential Manager, or the headless file store when there's no logon
+ * session), matching a local `agents secrets import`.
+ */
+export declare function buildWindowsStdinImportCommand(bundle: string, opts?: {
+    force?: boolean;
+}): string;

package/dist/lib/hosts/remote-cmd.js

@@ -130,3 +130,30 @@ export function windowsAgentsScript(cmd) {
 export function buildWindowsAgentsCommand(cmd) {
     return `powershell -NoProfile -EncodedCommand ${encodePowershell(windowsAgentsScript(cmd))}`;
 }
+/**
+ * Build the `ssh <target> <cmd>` string for `agents secrets import` on a Windows
+ * remote where the `.env` is piped over ssh stdin.
+ *
+ * We can't just run `agents secrets import <bundle> --from -`: the npm
+ * `agents.ps1` shim does NOT forward the ssh-piped stdin down to the underlying
+ * node process, so a raw fd-0 read (`--from -`) hangs forever (observed: the
+ * push to a Windows host times out). PowerShell ITSELF can read the pipe, so we
+ * read stdin into a temp file in PowerShell, import `--from <file>` (a plain
+ * file read, which the shim handles fine), and delete the temp file afterwards
+ * — success or failure. Backend defaults to the platform native store
+ * (Credential Manager, or the headless file store when there's no logon
+ * session), matching a local `agents secrets import`.
+ */
+export function buildWindowsStdinImportCommand(bundle, opts = {}) {
+    const force = opts.force ? ' --force' : '';
+    const script = [
+        '$in = [Console]::In.ReadToEnd()',
+        '$tmp = [System.IO.Path]::GetTempFileName()',
+        '[System.IO.File]::WriteAllText($tmp, $in)',
+        `try { & agents secrets import ${powershellQuote(bundle)} --from $tmp${force}; $code = $LASTEXITCODE } ` +
+            `finally { Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue }`,
+        'if ($null -eq $code) { $code = 1 }',
+        'exit $code',
+    ].join('; ');
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+}

package/dist/lib/hosts/session-index.d.ts

@@ -32,3 +32,18 @@ export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext)
  * break the dispatch itself, which has already been launched on the host.
  */
 export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;
+export interface InteractiveHostSessionContext {
+    cwd: string;
+    host: string;
+    agent: string;
+    sessionId: string;
+    name?: string;
+    createdAt?: string;
+}
+/**
+ * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
+ * local session index. Unlike detached host runs, there is no remote log/exit
+ * file and no HostTask; we only need the session id so `agents sessions` can
+ * surface and resume it by id.
+ */
+export declare function registerInteractiveHostSession(ctx: InteractiveHostSessionContext): void;

package/dist/lib/hosts/session-index.js

@@ -35,8 +35,10 @@ export function hostSessionMeta(task, ctx) {
         // stale-filter treats as "always live" (see module doc).
         filePath: '',
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
-        label: `[host/${task.host}]`,
-        name: task.name,
+        // The run's `--name` seeds the label (resolves `agents sessions <name>` and
+        // `agents hosts logs <name>`); an unnamed host run falls back to the
+        // `[host/<name>]` indicator, mirroring the cloud path's `[cloud/<status>]`.
+        label: task.name || `[host/${task.host}]`,
     };
 }
 /**
@@ -55,3 +57,27 @@ export function registerHostSession(task, ctx) {
         /* index write is best-effort; the run is already live on the host */
     }
 }
+/**
+ * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
+ * local session index. Unlike detached host runs, there is no remote log/exit
+ * file and no HostTask; we only need the session id so `agents sessions` can
+ * surface and resume it by id.
+ */
+export function registerInteractiveHostSession(ctx) {
+    if (!SESSION_AGENTS.includes(ctx.agent))
+        return;
+    try {
+        upsertSession({
+            id: ctx.sessionId,
+            shortId: ctx.sessionId.slice(0, 8),
+            agent: ctx.agent,
+            timestamp: ctx.createdAt ?? new Date().toISOString(),
+            cwd: ctx.cwd,
+            filePath: '',
+            label: ctx.name || `[host/${ctx.host}]`,
+        }, '');
+    }
+    catch {
+        /* index write is best-effort; the run is already live on the host */
+    }
+}

package/dist/lib/redact.js

@@ -7,6 +7,7 @@ const SECRET_PATTERNS = [
     [/\bsk-[A-Za-z0-9]{20,}\b/g, '[REDACTED_API_KEY]'],
     [/\bnpm_[A-Za-z0-9]{36}\b/g, '[REDACTED_NPM_TOKEN]'],
     [/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g, '[REDACTED_JWT]'],
+    [/Bearer\s+\S+/gi, 'Bearer [REDACTED]'],
     [/\b([A-Z0-9_]*(?:TOKEN|KEY|SECRET|PASSWORD)[A-Z0-9_]*)=("[^"]*"|'[^']*'|\S+)/gi, '$1=[REDACTED]'],
 ];
 export function redactSecrets(text) {

package/dist/lib/rotate.d.ts

@@ -56,6 +56,39 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
+/**
+ * Whether a specific account can serve a run right now, and — when it can't —
+ * why. `signed_out` covers no-email / invalid-auth; `rate_limited` and
+ * `out_of_credits` name the throttle. Used to pre-warn on a version-pinned
+ * teammate whose account rotation won't route around (a pin IS the target).
+ */
+export type AccountReadiness = {
+    ready: true;
+} | {
+    ready: false;
+    reason: 'rate_limited' | 'out_of_credits' | 'signed_out';
+    email: string | null;
+};
+/**
+ * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
+ * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * disagree with what rotation would actually do. The `reason` combines the two
+ * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
+ * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
+ * snapshot never carries). When a live snapshot exists it wins over the cached
+ * status — matching the gate — so a stale `out_of_credits` cache is not
+ * reported while the account is actually serving requests.
+ */
+export declare function readinessFromCandidate(candidate: RotateCandidate): AccountReadiness;
+/**
+ * Readiness for a specific installed (agent, version). Returns `{ ready: true }`
+ * when the version isn't among the collected candidates — absence is the
+ * caller's `isVersionInstalled` concern, not ours; don't cry wolf. Only
+ * meaningful for a version-pinned target: a bare target rotates to a healthy
+ * account on its own, and a profile injects its own auth (a different account
+ * than the version home carries), so neither is checkable here.
+ */
+export declare function checkRunAccountReadiness(agent: AgentId, version: string): Promise<AccountReadiness>;
 /**
  * Pick a healthy candidate using weighted random by remaining capacity.
  *

package/dist/lib/rotate.js

@@ -92,6 +92,43 @@ function hasUsageAvailable(candidate) {
     }
     return true;
 }
+/**
+ * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
+ * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * disagree with what rotation would actually do. The `reason` combines the two
+ * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
+ * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
+ * snapshot never carries). When a live snapshot exists it wins over the cached
+ * status — matching the gate — so a stale `out_of_credits` cache is not
+ * reported while the account is actually serving requests.
+ */
+export function readinessFromCandidate(candidate) {
+    if (!candidate.email || !candidate.authValid) {
+        return { ready: false, reason: 'signed_out', email: candidate.email };
+    }
+    if (hasUsageAvailable(candidate)) {
+        return { ready: true };
+    }
+    const snap = candidate.usageSnapshot;
+    const snapRateLimited = !!snap && snap.windows.length > 0 && deriveUsageStatusFromSnapshot(snap) === 'rate_limited';
+    const reason = !snapRateLimited && candidate.usageStatus === 'out_of_credits' ? 'out_of_credits' : 'rate_limited';
+    return { ready: false, reason, email: candidate.email };
+}
+/**
+ * Readiness for a specific installed (agent, version). Returns `{ ready: true }`
+ * when the version isn't among the collected candidates — absence is the
+ * caller's `isVersionInstalled` concern, not ours; don't cry wolf. Only
+ * meaningful for a version-pinned target: a bare target rotates to a healthy
+ * account on its own, and a profile injects its own auth (a different account
+ * than the version home carries), so neither is checkable here.
+ */
+export async function checkRunAccountReadiness(agent, version) {
+    const candidates = await collectRunCandidates(agent);
+    const candidate = candidates.find((c) => c.version === version);
+    if (!candidate)
+        return { ready: true };
+    return readinessFromCandidate(candidate);
+}
 function getRoutingUsedPercent(snapshot) {
     if (!snapshot || snapshot.windows.length === 0)
         return null;

package/dist/lib/secrets/remote.d.ts

@@ -51,6 +51,20 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
     tty?: boolean;
     input?: string;
 }): SshExecResult;
+/**
+ * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
+ * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
+ *
+ * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
+ * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
+ * appear (the macOS file-store guard then hard-errors "needs
+ * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
+ * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
+ * the keystrokes. This is the transport for `unlock --host`: you type the remote
+ * bundle's passphrase at your own terminal. Output is NOT captured (it streams
+ * to the terminal); only the exit code is returned.
+ */
+export declare function remoteSecretsStream(target: string, args: string[]): number;
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over

package/dist/lib/secrets/remote.js

@@ -15,7 +15,7 @@
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
  */
-import { sshExec, assertValidSshTarget } from '../ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { emit } from '../events.js';
 import { sshTargetFor } from '../hosts/types.js';
@@ -93,6 +93,23 @@ export function remoteSecretsRaw(target, args, opts = {}) {
         extraSshArgs: opts.tty ? ['-tt'] : undefined,
     });
 }
+/**
+ * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
+ * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
+ *
+ * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
+ * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
+ * appear (the macOS file-store guard then hard-errors "needs
+ * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
+ * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
+ * the keystrokes. This is the transport for `unlock --host`: you type the remote
+ * bundle's passphrase at your own terminal. Output is NOT captured (it streams
+ * to the terminal); only the exit code is returned.
+ */
+export function remoteSecretsStream(target, args) {
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target));
+    return sshStream(target, remoteCmd, { tty: true });
+}
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over

package/dist/lib/session/active.d.ts

@@ -36,6 +36,10 @@ export interface ActiveSession {
     worktree?: DetectedWorktree;
     /** Tracker ticket the session is tied to. */
     ticket?: DetectedTicket;
+    /** Tracker refs the session CREATED (Linear create_issue / gh issue create). */
+    createdTickets?: string[];
+    /** Team name the session SPAWNED via `agents teams create/add`. */
+    spawnedTeam?: string;
     sessionFile?: string;
     startedAtMs?: number;
     status: ActiveStatus;
@@ -102,6 +106,12 @@ export interface ActiveQueryOptions {
     /** Skip the `ps` scan for ad-hoc headless agents. */
     skipHeadless?: boolean;
 }
+/**
+ * Resolve an agent kind from a process's reported executable. `comm` may be an
+ * absolute path (shim-launched agents), and Windows image names carry an
+ * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
+ */
+export declare function agentKindFromComm(commRaw: string): string | undefined;
 /**
  * Pick a Claude transcript file within a project dir.
  *

package/dist/lib/session/active.js

@@ -64,7 +64,16 @@ const AGENT_CLI_NAMES = {
  * absolute path (shim-launched agents), and Windows image names carry an
  * `.exe` suffix (`claude.exe`), so basename + suffix-strip before the lookup.
  */
-function agentKindFromComm(commRaw) {
+export function agentKindFromComm(commRaw) {
+    // A GUI desktop app can bundle a binary with the SAME name as an agent CLI: the
+    // Codex desktop app ships `/Applications/Codex.app/Contents/Resources/codex` (its
+    // `app-server`), whose basename `codex` would otherwise match the codex CLI and
+    // surface the app's background server as a phantom agent session — running at cwd
+    // '/', so it shows up unattributed in the feed. A real agent CLI is never inside a
+    // `.app` bundle, so exclude those. (The Claude desktop app is a separate case,
+    // already excluded by name below: its process is 'Claude', not the CLI's 'claude'.)
+    if (commRaw.includes('.app/Contents/'))
+        return undefined;
     const base = path.basename(commRaw);
     const stripped = base.replace(/\.exe$/i, '');
     // Windows image names compare case-insensitively; POSIX comms stay exact —
@@ -232,6 +241,8 @@ function applyState(base, state, fallbackFile) {
         pr: state.pr,
         worktree: state.worktree,
         ticket: state.ticket,
+        createdTickets: state.createdTickets,
+        spawnedTeam: state.spawnedTeam,
     };
 }
 /**