@phnx-labs/agents-cli 1.22.47 → 1.22.50

package/dist/commands/exec.js

@@ -508,7 +508,7 @@ export function registerRunCommand(program) {
         .option('--no-auth-check', 'Skip the pre-launch "looks logged out" warning on an interactive run (advisory; never blocks anyway). Also silenced by AGENTS_NO_AUTH_CHECK=1.')
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
         .option('--broadcast', 'Run the same prompt or --task across multiple agents (comma-separated [agent]) × --model cells. Replaces the former `agents bench` group.')
-        .option('--task <id>', 'With --broadcast: house benchmark task id under apps/cli/bench/tasks/')
+        .option('--task <id>', 'With --broadcast: house benchmark task id under cli/bench/tasks/')
         .option('--list-tasks', 'With --broadcast: list available broadcast task ids')
         .option('--results [run-id]', 'With --broadcast: show one saved matrix run, or list saved runs newest first')
         .option('--concurrency <n>', 'With --broadcast: maximum cells running at once', '3')
@@ -1501,6 +1501,19 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     if (process.env.AGENTS_DISPATCH_DEBUG || options.verbose) {
                         process.stderr.write(chalk.gray(`[hosts] dispatch interactive ${runAgent}${runVersion ? `@${runVersion}` : ''} -> ${host.name}\n`));
                     }
+                    {
+                        const { connectionStartedNotice, startConnectionTarget } = await import('../lib/hosts/reconnect.js');
+                        const startTarget = startConnectionTarget({
+                            agent: runAgent,
+                            hostSessionId,
+                            resumeId,
+                        });
+                        if (startTarget) {
+                            const started = connectionStartedNotice(startTarget, host.name);
+                            if (started)
+                                process.stderr.write(chalk.gray(started));
+                        }
+                    }
                     const exitCode = await runInteractiveOnHost(host, {
                         agent: runAgent,
                         version: resumeId ? undefined : runVersion,
@@ -1565,19 +1578,32 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     // `raw` runs aren't tmux wrapped, so there is nothing to reconnect to.
                     // For `run auto` prefer the join-resolved id (the harness the remote
                     // ACTUALLY picked) over the explicit --session-id only claude adopts.
-                    const reconnectId = (runAgent === RUN_AUTO_KEYWORD
-                        ? resolvedRemoteId ?? hostSessionId
-                        : hostSessionId ?? resolvedRemoteId) ?? resumeId;
-                    if (reconnectId && !isRaw) {
-                        const { reconnectInteractiveSession, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
-                        if (exitCode === SSH_CONN_FAILURE) {
-                            process.exit(await reconnectInteractiveSession({
-                                host,
-                                sessionId: reconnectId,
-                                initialExit: exitCode,
-                            }));
-                        }
+                    const { pickReconnectTarget, reconnectInteractiveSession, afterInteractiveRemoteExit, SSH_CONN_FAILURE } = await import('../lib/hosts/reconnect.js');
+                    const reconnectTarget = pickReconnectTarget({
+                        agent: runAgent,
+                        sessionId: hostSessionId,
+                        resolvedId: resolvedRemoteId,
+                        resumeId,
+                        launchId: correlationLaunchId,
+                    });
+                    // Raw is not tmux-wrapped, so it never auto-reconnects — but it
+                    // still prints the session id (EXEC-55). Bundling the notice
+                    // behind `!isRaw` left a dropped `--raw` tab as a bare shell.
+                    const next = afterInteractiveRemoteExit({
+                        target: reconnectTarget,
+                        host: host.name,
+                        exitCode,
+                        willReconnect: exitCode === SSH_CONN_FAILURE && !isRaw,
+                    });
+                    if (next.reconnect && reconnectTarget) {
+                        process.exit(await reconnectInteractiveSession({
+                            host,
+                            target: reconnectTarget,
+                            initialExit: exitCode,
+                        }));
                     }
+                    if (next.notice)
+                        process.stderr.write(next.notice);
                     process.exit(exitCode);
                 }
                 // Headless host run: launch detached, tail the remote log, and follow
@@ -2268,7 +2294,7 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 const peer = sessionRecoveryPeer(session);
                 if (peer) {
                     const { runOnPeer } = await import('../lib/session/remote-list.js');
-                    const routed = await runOnPeer(sessionRecoveryRunArgs(session), peer, { tty: true });
+                    const routed = await runOnPeer(sessionRecoveryRunArgs(session), peer, { tty: true, sessionId: session.id });
                     if (routed === 'no-target') {
                         console.error(chalk.red(`Cannot recover session ${session.shortId}: origin device ${peer} is not a registered reachable peer.`));
                         process.exitCode = 1;
@@ -2351,7 +2377,13 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
             }
             else {
                 try {
-                    const resolved = await resolveRunVersion(agent, strategy, cwd);
+                    // Account-centric candidate list: native version-home logins PLUS
+                    // provider accounts (setup-token / API-key) that can auth this agent,
+                    // so `--strategy balanced` spreads across ALL accounts, not just the
+                    // ones sitting in a version home (RUSH-3182). Run-path only — the
+                    // picker's other callers keep the native-only collector.
+                    const { collectRunCandidatesForRun } = await import('../lib/accounting/account-pool-collect.js');
+                    const resolved = await resolveRunVersion(agent, strategy, cwd, collectRunCandidatesForRun);
                     if (resolved.exhausted) {
                         // Zero healthy accounts splits two ways, and conflating them is what
                         // stranded a logged-out harness with no way in at all (RUSH-2334):
@@ -2402,6 +2434,23 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                     else if (resolved.version) {
                         version = resolved.version;
                         rotationResult = resolved.rotation;
+                        // A balanced/available pick of a PROVIDER account (setup-token /
+                        // API-key) carries `providerAccount`. Resolve its env through the
+                        // same `resolveSpawnAccount` path an explicit `--account` uses, so
+                        // exec injects the credential; a native pick has no providerAccount
+                        // and runs from its own version home unchanged (RUSH-3182).
+                        const pickedProviderAccount = resolved.rotation?.picked.providerAccount;
+                        if (pickedProviderAccount) {
+                            try {
+                                const picked = resolveSpawnAccount(pickedProviderAccount, agent, resolved.version, readMeta(), { useDefault: false });
+                                if (picked?.kind === 'provider')
+                                    accountEnv = picked.env;
+                            }
+                            catch (err) {
+                                console.error(chalk.red(err.message));
+                                process.exit(1);
+                            }
+                        }
                         if (resolved.rotation && !options.quiet) {
                             const banner = formatRotationBanner(resolved.rotation, strategy);
                             process.stderr.write(chalk.gray(banner + '\n'));
@@ -2523,7 +2572,18 @@ agents run auto --device yosemite-s0 "fix the flaky test"   # pin the device
                 try {
                     const { getAccountInfo } = await import('../lib/agents.js');
                     const info = await getAccountInfo(agent);
-                    if (!info.signedIn) {
+                    // Claude authenticates interactively from a per-version setup-token on a
+                    // keychain-less worker (the shim's .oauth_token fallback), which the
+                    // native-credential probe above can't see — so don't warn "logged out" when
+                    // a setup-token resolves for this version. No-op on macOS, where the
+                    // credential lives in the keychain and resolveClaudeSetupToken returns null.
+                    let authedViaSetupToken = false;
+                    if (!info.signedIn && agent === 'claude' && version) {
+                        const { resolveClaudeSetupToken } = await import('../lib/claude-account-token.js');
+                        const { getVersionHomePath } = await import('../lib/installations/versions.js');
+                        authedViaSetupToken = resolveClaudeSetupToken(getVersionHomePath('claude', version)) !== null;
+                    }
+                    if (!info.signedIn && !authedViaSetupToken) {
                         process.stderr.write(chalk.yellow(`⚠  ${agent} looks logged out — log in with: ${loginHint(agent)}. Launching anyway...\n`));
                     }
                 }

package/dist/commands/focus.d.ts

@@ -20,6 +20,19 @@ import { type LiveStatusFilter } from './sessions.js';
 import { openSurfaces, type Backend } from '../lib/terminal/index.js';
 /** Options for `sessions focus` — device scope + the `--active` live-state filters. */
 export interface FocusOptions {
+    /**
+     * Resolve the target from the launcher's AGENT_LAUNCH_ID instead of a session
+     * id (RUSH-3125).
+     *
+     * A `--device` launcher mints this id BEFORE it opens the connection and
+     * forwards it, so it is the one handle that is still known after the link
+     * dies. A session id is not: only Claude is handed one up front, and every
+     * other harness's real id had to be read back off the peer — over the very
+     * link that just dropped — which is why a blink left a Grok or Codex tab with
+     * nothing to reconnect to. The lookup runs HERE, on the box that owns the hook
+     * records, so it needs no network at the moment it is needed most.
+     */
+    launchId?: string;
     local?: boolean;
     attachOnly?: boolean;
     device?: string[];
@@ -54,6 +67,7 @@ export interface FocusOptions {
     abandoned?: boolean;
     queued?: boolean;
     unknown?: boolean;
+    reconnectReattach?: boolean;
 }
 /** Commander gives overlapping `sessions` flags to the parent command, even
  * when they appear after `focus`. Fold only values explicitly provided there

package/dist/commands/focus.js

@@ -80,8 +80,10 @@ export function registerFocusCommand(program) {
         // console.warn here without first removing that delegation.
         .command('focus', { hidden: true })
         .argument('[selector]', 'Session id/prefix, agent@version, or topic/path search')
+        .option('--launch-id <id>', 'Target the run by its launcher AGENT_LAUNCH_ID instead of a session id (resolved from this machine\'s hook records)')
         .option('--local', 'Only this machine (skip the cross-host sweep)')
         .option('--attach-only', 'Attach only — never open a new tab / resume a copy (the old `go` behavior)')
+        .option('--reconnect-reattach', '(internal) Set by the reconnect loop — warns when the expected pane is dead and a fresh copy starts instead', false)
         .option('-D, --device <target...>', 'Scope the picker to live sessions on these devices (device alias from `agents devices`, user@host; repeatable)')
         .option('--active', 'Only sessions present in the live roster')
         .option('-a, --agent <agent>', 'Filter by harness and recorded version (for example claude@latest)')
@@ -162,6 +164,38 @@ export function selectFallback(attachOnly) {
     return attachOnly ? refuseFallback : resumeInNewTab;
 }
 export async function focusAction(id, opts) {
+    // RUSH-3125: `--launch-id` names the run by the handle its launcher minted,
+    // and this box holds the hook record that maps it to the real session id — a
+    // local read, so it still works when the network that started the run is gone.
+    // Resolved up front into the ordinary id path: everything below, including the
+    // attach-else-resume recovery, is identical once we know which session it is.
+    if (opts.launchId) {
+        if (id) {
+            console.error(chalk.red('Pass a session id or --launch-id, not both — they name the same thing two ways.'));
+            process.exitCode = 1;
+            return;
+        }
+        // Read the launch-id index directly rather than through
+        // `resolveHookSessionRecord`: that helper kind-guards every hit, which exists
+        // to stop a REUSED PID crossing harnesses. A launch id is a per-launch uuid
+        // and cannot collide, and the caller here is a reattach that deliberately
+        // does not assume which harness the peer picked (`run auto` chooses it
+        // remotely), so demanding a kind would reject the exact case this serves.
+        const { loadHookSessionIndex } = await import('../lib/session/hook-sessions.js');
+        const resolved = loadHookSessionIndex().byLaunchId.get(opts.launchId)?.session_id;
+        if (!resolved) {
+            // Fail loud: a launch id with no record means the harness never got far
+            // enough to write one (it died at startup, or it has no SessionStart
+            // hook). Silently opening the picker here would strand an automated
+            // reattach in an interactive prompt nobody is watching.
+            console.error(chalk.red(`No session recorded for launch id ${opts.launchId} on ${machineId()}.`));
+            console.error(chalk.gray('  The run may have failed before its SessionStart hook fired.'));
+            console.error(chalk.gray('  Look for it:  agents sessions --active'));
+            process.exitCode = 1;
+            return;
+        }
+        id = resolved;
+    }
     const hosts = mergeFocusHosts(opts);
     const statuses = requestedLiveStatuses(opts);
     // A device scope needs the cross-host sweep; --local only wins when no host is named.
@@ -204,7 +238,7 @@ export async function focusAction(id, opts) {
                 // still joined instead of resumed as a copy; a crashed session has no live
                 // row and recovers in place.
                 const { activeById } = await gatherLiveTargets(true, { statuses: [] });
-                await focusResolvedSession(localMatch[0], activeById, self, fallback, opts.attachOnly === true);
+                await focusResolvedSession(localMatch[0], activeById, self, fallback, opts.attachOnly === true, opts.reconnectReattach === true);
                 return;
             }
         }
@@ -290,7 +324,7 @@ export async function focusAction(id, opts) {
             exact = [focusTargetForResolved(filteredMatch, outcome.session)];
         }
         if (exact.length === 1) {
-            await focusResolvedSession(exact[0], liveById, self, fallback, opts.attachOnly === true);
+            await focusResolvedSession(exact[0], liveById, self, fallback, opts.attachOnly === true, opts.reconnectReattach === true);
             return;
         }
         if (exact.length > 1) {
@@ -524,7 +558,7 @@ async function pickFocusCandidates(sessions, liveById, initialSearch) {
 export function focusTargetForResolved(poolMatch, resolved) {
     return poolMatch ?? resolved;
 }
-async function focusResolvedSession(meta, liveById, self, fallback, attachOnly) {
+async function focusResolvedSession(meta, liveById, self, fallback, attachOnly, reconnectReattach = false) {
     const active = liveById.get(meta.id);
     if (active && isAttachableLiveSession(active)) {
         await jumpTo(active, self, fallback);
@@ -535,10 +569,19 @@ async function focusResolvedSession(meta, liveById, self, fallback, attachOnly)
         process.exitCode = 1;
         return;
     }
+    if (reconnectReattach) {
+        // The reconnect loop expected this pane to be alive. It isn't — the peer
+        // rebooted, tmux crashed, or the agent exited while the link was down.
+        // Warn before any recovery attempt (local resume OR remote hop) so the
+        // user always knows their original context was not directly recovered.
+        console.error(chalk.yellow(`\nWarning: ${meta.shortId}'s pane is gone (reboot, tmux crash, or agent exited).`));
+        console.error(chalk.gray(`  Prior context is in the transcript — starting recovery.\n` +
+            `  To see what happened: agents sessions preview ${meta.shortId}`));
+    }
     const remote = sessionProcessHost(meta, self);
     if (remote) {
         console.log(chalk.gray(`Recovering ${meta.shortId} on ${remote}…`));
-        const rc = await runOnPeer(sessionRecoveryRunArgs(meta), remote, { tty: true });
+        const rc = await runOnPeer(sessionRecoveryRunArgs(meta), remote, { tty: true, sessionId: meta.id });
         if (rc === 'no-target') {
             console.error(chalk.red(`Cannot recover ${meta.shortId}: ${remote} is unreachable.`));
             process.exitCode = 1;
@@ -765,7 +808,7 @@ const resumeInNewTab = async (s, remote) => {
     // it actually delivers you to the session (the peer picks the right version + HOME).
     if (remote) {
         console.log(chalk.gray(`${shortId(s)} has no live terminal on ${remote} — resuming it there over SSH…`));
-        const rc = await runOnPeer(sessionRecoveryRunArgs({ id }), remote, { tty: true });
+        const rc = await runOnPeer(sessionRecoveryRunArgs({ id }), remote, { tty: true, sessionId: id });
         if (rc === 'no-target') {
             console.log(chalk.red(`${remote} isn't reachable as a device. Try: agents devices sync`));
             console.log(chalk.gray(`  recovery must run on ${remote}, where the indexed session originated`));

package/dist/commands/go.d.ts

@@ -66,6 +66,9 @@ export interface Where {
     label: string;
     action: string;
 }
+/** What `jumpTo` writes after a remote tmux attach's SSH stream returns. Pure so
+ *  the ControlMaster close path is unit-tested without SSH (RUSH-3227). */
+export declare function remoteAttachEndedNotice(sessionId: string | undefined, host: string, code: number): string | undefined;
 /**
  * Pure, testable mirror of `jumpTo`'s path selection (jumpTo itself has side
  * effects — process.exit / ssh / osascript). Keep the branch ORDER in sync with

package/dist/commands/go.js

@@ -30,7 +30,8 @@ import { machineId } from '../lib/session/sync/config.js';
 import { attachTmux, runTmux } from '../lib/tmux/binary.js';
 import { ensureSessionHookRepaired, paneExitStatus } from '../lib/tmux/session.js';
 import { getDefaultSocketPath } from '../lib/tmux/paths.js';
-import { sshExec, sshStream, assertValidSshTarget, shellQuote } from '../lib/ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget, shellQuote, SSH_CONN_FAILURE_CODE } from '../lib/ssh-exec.js';
+import { connectionEndedNotice } from '../lib/hosts/reconnect.js';
 import { enumerateGhosttyTabs, assignGhosttyTabs } from '../lib/session/ghostty-tabs.js';
 const execFileAsync = promisify(execFile);
 export function registerGoCommand(program) {
@@ -191,6 +192,13 @@ function synthMeta(s, self) {
 function shortId(s) {
     return (s.sessionId ?? '').slice(0, 8) || '-';
 }
+/** What `jumpTo` writes after a remote tmux attach's SSH stream returns. Pure so
+ *  the ControlMaster close path is unit-tested without SSH (RUSH-3227). */
+export function remoteAttachEndedNotice(sessionId, host, code) {
+    if (!sessionId)
+        return undefined;
+    return connectionEndedNotice({ kind: 'session', id: sessionId }, host, { dropped: code === SSH_CONN_FAILURE_CODE });
+}
 /**
  * Pure, testable mirror of `jumpTo`'s path selection (jumpTo itself has side
  * effects — process.exit / ssh / osascript). Keep the branch ORDER in sync with
@@ -276,8 +284,13 @@ export async function jumpTo(s, self, fallback = refuseFallback) {
                 `sess=$(tmux ${sock}display-message -pt ${p} '#{session_name}' 2>/dev/null); ` +
                 `[ -n "$w" ] && tmux ${sock}select-window -t "$w" 2>/dev/null; ` +
                 `exec tmux ${sock}attach-session -t "\${sess:-${p}}"`;
-            console.log(chalk.gray(`Attaching ${shortId(s)} on ${remote} over SSH — Ctrl-b d to detach.`));
-            process.exit(sshStream(remote, remoteCmd, { tty: true }));
+            const attachId = s.sessionId || shortId(s);
+            console.log(chalk.gray(`Attaching ${attachId} on ${remote} over SSH — Ctrl-b d to detach.`));
+            const code = sshStream(remote, remoteCmd, { tty: true });
+            const notice = remoteAttachEndedNotice(s.sessionId, remote, code);
+            if (notice)
+                process.stderr.write(notice);
+            process.exit(code);
         }
         // Remote, not in tmux → hand off to the fallback (go: shell; focus: resume in a tab).
         await fallback(s, remote);

package/dist/commands/inspect.js

@@ -274,8 +274,8 @@ function isDotAgentsRoot(dir) {
     for (const kind of DRILLABLE_KINDS) {
         // `routines/` alone is NOT a marker. Shipping example routine YAML for
         // `agents routines add` is a documented pattern (this repo's own
-        // apps/cli/routines/), and that directory is the ONLY kind dir there — so
-        // counting it would make `agents inspect apps/cli` resolve a source tree as
+        // cli/routines/), and that directory is the ONLY kind dir there — so
+        // counting it would make `agents inspect cli` resolve a source tree as
         // a DotAgents repo. Same reasoning as the nested-`.agents/` case above.
         if (kind === 'routines')
             continue;

package/dist/commands/lease.d.ts

@@ -1,7 +1,7 @@
 /**
  * `agents devices lease` — manage the disposable cloud boxes used by `agents run --lease`.
  *
- * Today: `agents devices lease gc`, which stops expired + idle "orphan" boxes that are
+ * Today: `agents devices lease prune`, which stops expired + idle "orphan" boxes that are
  * holding a provider's server quota (the cause of the `server_limit` 403 a new
  * lease hits). Reaping is conservative: only boxes whose lease has expired AND
  * that have been untouched for a safety window are eligible (see `isReapSafe`),

package/dist/commands/lease.js

@@ -1,7 +1,7 @@
 /**
  * `agents devices lease` — manage the disposable cloud boxes used by `agents run --lease`.
  *
- * Today: `agents devices lease gc`, which stops expired + idle "orphan" boxes that are
+ * Today: `agents devices lease prune`, which stops expired + idle "orphan" boxes that are
  * holding a provider's server quota (the cause of the `server_limit` 403 a new
  * lease hits). Reaping is conservative: only boxes whose lease has expired AND
  * that have been untouched for a safety window are eligible (see `isReapSafe`),
@@ -256,7 +256,8 @@ export function registerLeaseCommand(devicesCommand) {
         process.exit(ok ? 0 : 1);
     });
     lease
-        .command('gc')
+        .command('prune')
+        .alias('gc')
         .description('Stop expired, idle lease boxes that are holding your provider quota. Safe: never stops a box in active use.')
         .option('--dry-run', 'List reap-safe orphan boxes without stopping any', false)
         .option('--yes', 'Stop them without the interactive confirm', false)
@@ -269,7 +270,7 @@ export function registerLeaseCommand(devicesCommand) {
             candidates = reapSafeOrphans(crabboxList(boxOpts), nowSecs);
         }
         catch (e) {
-            console.error(chalk.red(`lease gc: ${e.message}`));
+            console.error(chalk.red(`lease prune: ${e.message}`));
             process.exit(1);
             return;
         }

package/dist/commands/mailboxes.js

@@ -405,17 +405,18 @@ export function registerMailboxesCommand(program) {
         renderOverview(boxes, limit, filters);
     });
     const gcCmd = cmd
-        .command('gc')
+        .command('prune')
+        .alias('gc')
         .description('Run a liveness sweep: archive pending messages in dead boxes and prune stale consumed mail.')
         .option('--json', 'Emit the GC result as JSON')
         .action(async (_opts, command) => runGcCommand({ json: command.optsWithGlobals().json === true }));
     setHelpSections(gcCmd, {
         examples: `
       # One-shot sweep using the live session set as the liveness source
-      agents mailboxes gc
+      agents mailboxes prune
 
       # Machine-readable summary (for scripts / monitors)
-      agents mailboxes gc --json
+      agents mailboxes prune --json
     `,
         notes: `
       A box is considered dead when no live session (the same source

package/dist/commands/menubar.js

@@ -115,7 +115,7 @@ export function registerMenubarCommands(program) {
         .description('Configure AGI Menu end-to-end: one instance, started at login')
         .option('--check', 'Report the current state, change nothing')
         .option('--json', 'Emit machine-readable JSON')
-        .action((options) => {
+        .action(async (options) => {
         if (options.check) {
             const s = getMenubarStatus();
             if (options.json) {
@@ -129,7 +129,7 @@ export function registerMenubarCommands(program) {
         }
         if (!options.json && notMac())
             return;
-        const r = runMenubarSetup();
+        const r = await runMenubarSetup();
         if (options.json) {
             process.stdout.write(JSON.stringify(r) + '\n');
         }
@@ -174,10 +174,17 @@ export function registerMenubarCommands(program) {
     menubar
         .command('enable')
         .description('Install and start AGI Menu (launches at login)')
-        .action(() => {
+        .action(async () => {
         if (notMac())
             return;
-        const ok = enableMenubarService({ clearOptOut: true });
+        let ok = false;
+        try {
+            ok = await enableMenubarService({ clearOptOut: true });
+        }
+        catch (e) {
+            console.log(chalk.red(`Could not enable AGI Menu: ${e.message}`));
+            return;
+        }
         if (!ok) {
             console.log(chalk.red('Could not enable: no AGI Menu bundle ships with this install.'));
             console.log(chalk.gray('  This build may predate the helper, or be a non-macOS package.'));

package/dist/commands/projects.d.ts

@@ -8,7 +8,7 @@
  * lifecycle state, plan completion, open PRs, and tickets in flight.
  */
 import type { Command } from 'commander';
-import { type ProjectRepo } from '../lib/projects.js';
+import { type ProjectDef, type ProjectRepo } from '../lib/projects.js';
 import { type LinearMilestone } from '../lib/linear-project-counts.js';
 /** Recursion guard: a peer answering a probe fan-out never re-fans-out itself. */
 export declare const PROJECTS_NO_FANOUT_ENV = "AGENTS_PROJECTS_LOCAL";
@@ -101,4 +101,19 @@ export declare function formatMilestoneDue(targetDate: string, nowMs: number): s
 export declare function formatMilestoneLines(milestones: LinearMilestone[], next: LinearMilestone | undefined, nowMs: number, limit: number): string[];
 /** The `next` card line: what this project is due to hit, and how far along it is. */
 export declare function formatNextMilestone(ms: LinearMilestone, nowMs: number): string;
+/** Options shared by `status` and `view`. */
+export type ProjectCardOpts = {
+    json?: boolean;
+    window?: string;
+    remote?: boolean;
+    /** Scope the fleet fan-out to specific devices; undefined = the whole fleet. */
+    deviceFilter?: string[];
+};
+/**
+ * Merge `--device a b` (variadic) and `--devices a,b,c` (comma list) into one
+ * deduped device filter; undefined when neither was given (= whole fleet).
+ */
+export declare function resolveDeviceFilter(device?: string[], devices?: string): string[] | undefined;
+/** Print the YAML-side fields that sit under the shared card in `view` mode. */
+export declare function printProjectDefinition(def: ProjectDef, name: string): void;
 export declare function registerProjectsCommands(program: Command): void;