@phnx-labs/agents-cli 1.22.26 → 1.22.28

package/dist/commands/run-account-picker.js

@@ -1,6 +1,8 @@
 import { select } from '@inquirer/prompts';
+import chalk from 'chalk';
 import { agentLabel } from '../lib/agents.js';
-import { collectRunCandidates, readinessFromCandidate, } from '../lib/rotate.js';
+import { loginHint } from '../lib/signin-badge.js';
+import { collectRunCandidates, readinessFromCandidate, isSignInRecoverable, } from '../lib/rotate.js';
 import { compareVersions, getGlobalDefault } from '../lib/versions.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 const CANCEL_SELECTION = '__agents_cancel_account_selection__';
@@ -30,14 +32,21 @@ export function formatAccountLimits(candidate) {
     })
         .join(' · ');
 }
-function disabledReason(candidate) {
-    const readiness = readinessFromCandidate(candidate);
+/**
+ * Why a row cannot be picked. Only a THROTTLE disables a row: the account is
+ * signed in and out of capacity, so launching it just hammers an exhausted
+ * account (RUSH-2132) and nothing the user does at this prompt helps.
+ *
+ * An AUTH exclusion (`signed_out` / `revoked`) is deliberately NOT disabled —
+ * the harness's own TUI is the login surface, so picking that row and launching
+ * is the only way to sign in through agents-cli. Disabling it left a fully
+ * logged-out harness with no reachable account at all (RUSH-2334).
+ */
+function disabledReason(candidate, readiness) {
     if (readiness.ready)
         return undefined;
-    if (readiness.reason === 'signed_out')
-        return 'logged out';
-    if (readiness.reason === 'revoked')
-        return 'needs re-login';
+    if (isSignInRecoverable(readiness))
+        return undefined;
     if (readiness.reason === 'out_of_credits')
         return 'out of credits';
     const windows = candidate.usageSnapshot?.windows ?? [];
@@ -53,24 +62,44 @@ function disabledReason(candidate) {
 /** Build aligned picker rows with usable accounts first and unsafe rows disabled. */
 export function buildRunAccountChoices(candidates, globalDefault) {
     const rows = candidates.map((candidate) => {
-        const disabled = disabledReason(candidate);
+        const readiness = readinessFromCandidate(candidate);
+        const disabled = disabledReason(candidate, readiness);
+        const signInRequired = isSignInRecoverable(readiness);
         const version = candidate.version === globalDefault
             ? `${candidate.version} (default)`
             : candidate.version;
+        // `revoked` is signed-in-but-rejected, so it reads as a re-login rather
+        // than "logged out"; every throttle is still a signed-in account.
+        const authReason = readiness.ready ? null : readiness.reason;
+        const status = authReason === 'revoked'
+            ? 'needs re-login'
+            : authReason === 'signed_out'
+                ? 'logged out'
+                : 'logged in';
         return {
             candidate,
             account: candidate.accountLabel || 'account unavailable',
             version,
-            status: candidate.signedIn ? 'logged in' : 'logged out',
+            status,
             plan: candidate.usageSnapshot?.plan ?? candidate.plan ?? 'plan unavailable',
-            limits: formatAccountLimits(candidate),
+            // An auth-blocked row shows what picking it DOES; its quota is moot until
+            // there is a credential to spend it with.
+            limits: authReason === 'revoked'
+                ? 'launch to re-authenticate'
+                : authReason === 'signed_out'
+                    ? 'launch to sign in'
+                    : formatAccountLimits(candidate),
             disabled,
-            ready: disabled === undefined,
+            ready: readiness.ready,
+            signInRequired,
         };
     });
+    // Ready accounts first, then the ones a login would unlock (actionable), then
+    // the throttled rows the user can do nothing about at this prompt.
+    const rank = (row) => row.ready ? 0 : row.signInRequired ? 1 : 2;
     rows.sort((a, b) => {
-        if (a.ready !== b.ready)
-            return a.ready ? -1 : 1;
+        if (rank(a) !== rank(b))
+            return rank(a) - rank(b);
         const aDefault = a.candidate.version === globalDefault;
         const bDefault = b.candidate.version === globalDefault;
         if (aDefault !== bDefault)
@@ -92,8 +121,56 @@ export function buildRunAccountChoices(candidates, globalDefault) {
         value: row.candidate.version,
         disabled: row.disabled,
         ready: row.ready,
+        signInRequired: row.signInRequired,
     }));
 }
+/**
+ * Whether a zero-healthy run may recover by launching for a login, or must keep
+ * failing loud. Three inputs, all of which have to hold:
+ *
+ * - `recoverable` — at least one excluded account is only auth-blocked. An
+ *   all-throttled set is never launched (RUSH-2132): only a window reset clears it.
+ * - `tty` — a login needs a human present; off a TTY nobody can complete one.
+ * - `json` — `--json` marks a MACHINE consumer, which must never be handed a
+ *   picker or dropped into a login TUI. This mirrors the canonical
+ *   `Surface.interactive = tty && !json` in `commands/utils.ts`; a `--json` caller
+ *   gets the parseable fail-loud error instead.
+ */
+export function signInLaunchDecision(input) {
+    const humanPresent = input.tty && !input.json;
+    return input.recoverable > 0 && humanPresent ? 'launch' : 'fail-loud';
+}
+/**
+ * Choose which installed version to launch so the user can authenticate, when a
+ * strategy found zero healthy accounts but at least one is merely signed out
+ * (RUSH-2334). Returns the version to launch, or null if the user cancelled.
+ *
+ * A single candidate does NOT prompt — a one-item picker is pure noise, and the
+ * only thing to decide has one answer. Several candidates fall through to the
+ * normal account picker, which shows every account with its state so the choice
+ * is informed (throttled rows stay disabled there).
+ *
+ * Callers MUST have already confirmed an interactive terminal: off a TTY there
+ * is nobody to complete the login, and the run should fail loud instead.
+ */
+export async function pickSignInLaunchVersion(agent, recoverable, quiet = false) {
+    if (recoverable.length === 0)
+        return null;
+    if (recoverable.length > 1) {
+        const selected = await pickRunAccountCandidate(agent);
+        return selected?.version ?? null;
+    }
+    const [only] = recoverable;
+    if (!quiet) {
+        const readiness = readinessFromCandidate(only);
+        const why = !readiness.ready && readiness.reason === 'revoked'
+            ? 'has no valid credential (the server rejected its token)'
+            : 'has no signed-in account';
+        process.stderr.write(chalk.yellow(`${agentLabel(agent)} ${why} — launching ${agent}@${only.version} so you can sign in.\n`));
+        process.stderr.write(chalk.gray(`Sign in with: ${loginHint(agent)}\n`));
+    }
+    return only.version;
+}
 /** Prompt for one safe installed account/version. A cancelled picker launches nothing. */
 export async function pickRunAccountCandidate(agent) {
     if (!isInteractiveTerminal()) {
@@ -107,9 +184,14 @@ export async function pickRunAccountCandidate(agent) {
         throw new Error(`No installed ${agentLabel(agent)} versions are available. Run: agents add ${agent}@latest`);
     }
     const choices = buildRunAccountChoices(candidates, getGlobalDefault(agent));
-    const hasReadyAccount = choices.some((choice) => choice.ready);
-    const promptChoices = choices.map(({ ready: _ready, ...choice }) => choice);
-    if (!hasReadyAccount) {
+    // "Selectable" is broader than "ready": an auth-blocked row is pickable so the
+    // launch can carry you into the harness's login (RUSH-2334). Only offer the
+    // bail-out row when literally nothing can be chosen — i.e. every account is
+    // throttled, which no amount of signing in fixes.
+    const hasSelectableAccount = choices.some((choice) => !choice.disabled);
+    const needsSignIn = choices.some((choice) => choice.signInRequired);
+    const promptChoices = choices.map(({ ready: _ready, signInRequired: _signInRequired, ...choice }) => choice);
+    if (!hasSelectableAccount) {
         promptChoices.push({
             name: 'No usable accounts — cancel',
             value: CANCEL_SELECTION,
@@ -117,7 +199,9 @@ export async function pickRunAccountCandidate(agent) {
     }
     try {
         const version = await select({
-            message: `Select a ${agentLabel(agent)} account for this run:`,
+            message: needsSignIn
+                ? `Select a ${agentLabel(agent)} account for this run (pick a logged-out one to sign in):`
+                : `Select a ${agentLabel(agent)} account for this run:`,
             choices: promptChoices,
             loop: false,
         });

package/dist/commands/secrets.js

@@ -24,8 +24,9 @@ import { encryptForFallback, decryptForFallback } from '../lib/secrets/filestore
 import { getKeychainToken, hasKeychainToken, secretsKeychainItem, setKeychainToken, maybeAutoRekey, } from '../lib/secrets/index.js';
 import { assertOpAvailable, createPasswordItem, deleteItemByTitle, extractSecrets, itemExistsByTitle, listItems, listVaults, } from '../lib/onepassword.js';
 import { GLOBAL_HARNESS } from '../lib/secrets/scope.js';
-import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentStatus, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
-import { saveSession, deleteBundleSessions, deleteAllSessions } from '../lib/secrets/session-store.js';
+import { createSecretLease, selectLeasedEnv } from '../lib/secrets/lease.js';
+import { secretsHoldMs, secretsAgentDurable, agentLoad, agentLock, agentPing, agentSocketExists, agentStatus, agentRevoke, ensureAgentRunning, runAgentLoadFromStdin, runSecretsAgent, uninstallSecretsAgentService, } from '../lib/secrets/agent.js';
+import { activeLeaseSessions, saveSession, deleteBundleSessions, deleteAllSessions, deleteLeaseSession } from '../lib/secrets/session-store.js';
 import { getCliVersionFresh } from '../lib/version.js';
 import { readMeta } from '../lib/state.js';
 import { parseDuration } from '../lib/hooks/cache.js';
@@ -2426,6 +2427,89 @@ Examples:
             console.log(password);
         }
     });
+    cmd
+        .command('lease <bundle>')
+        .description('Hold only an explicit subset of a bundle until an independent expiry.')
+        .requiredOption('--keys <keys>', 'Comma-separated key subset')
+        .requiredOption('--for <duration>', 'Lease duration, for example 30m or 8h')
+        .option('--agent <agent>', 'Narrow the lease to one harness; default is global')
+        .option('--durable', 'Keep the lease across sleep as well as broker restart')
+        .action(async (name, opts) => {
+        if (process.platform !== 'darwin') {
+            throw new Error('Scoped lease brokering is not available on this platform yet.');
+        }
+        const seconds = parseDuration(opts.for);
+        if (seconds === null)
+            throw new Error(`Invalid lease duration '${opts.for}'.`);
+        const ttlMs = seconds * 1000;
+        const harness = opts.agent || GLOBAL_HARNESS;
+        const { bundle, env } = readAndResolveBundleEnv(name, {
+            noAgent: true,
+            interactiveUnlock: true,
+            caller: 'lease secrets',
+            agent: harness,
+            keyMode: 'storage',
+        });
+        const lease = createSecretLease({
+            bundle: name,
+            keys: opts.keys.split(','),
+            availableKeys: Object.keys(env),
+            ttlMs,
+            harness,
+            sleepPersist: opts.durable,
+        });
+        const leasedEnv = selectLeasedEnv(lease, env);
+        if (!(await ensureAgentRunning()) || !(await agentLoad(name, bundle, leasedEnv, ttlMs, harness, lease))) {
+            throw new Error('Could not load the scoped lease into the secrets broker.');
+        }
+        ensureDaemonStarted();
+        saveSession(name, {
+            bundle,
+            env: leasedEnv,
+            expiresAt: lease.expiresAt,
+            sleepPersist: lease.sleepPersist,
+            harness,
+            lease,
+        });
+        emitSecretAudit({
+            event: 'secrets.unlocked', bundle: name, operation: 'lease', source: lease.sleepPersist ? 'broker+durable' : 'broker',
+            status: 'success', keys: lease.keys, keyCount: lease.keys.length, agent: harness, ttlMs: lease.expiresAt - lease.createdAt,
+        });
+        console.log(`${chalk.green('leased')} ${chalk.cyan(lease.id)} ${chalk.gray(`(${name}: ${lease.keys.join(', ')}, ${humanRemaining(lease.expiresAt)})`)}`);
+    });
+    cmd
+        .command('leases')
+        .description('List active scoped secret leases.')
+        .action(async () => {
+        const brokerLeases = (await agentStatus()).filter((entry) => entry.leaseId);
+        const byId = new Map(brokerLeases.map((entry) => [entry.leaseId, entry]));
+        for (const { name, lease } of activeLeaseSessions()) {
+            if (!byId.has(lease.id))
+                byId.set(lease.id, { name, expiresAt: lease.expiresAt, keyCount: lease.keys.length, harness: lease.harness, leaseId: lease.id, keys: lease.keys });
+        }
+        const leases = [...byId.values()];
+        if (leases.length === 0) {
+            console.log(chalk.gray('No active secret leases.'));
+            return;
+        }
+        console.log(`${'ID'.padEnd(24)} ${'BUNDLE'.padEnd(24)} ${'KEYS'.padEnd(24)} EXPIRES IN`);
+        for (const lease of leases) {
+            console.log(`${lease.leaseId.padEnd(24)} ${lease.name.padEnd(24)} ${(lease.keys ?? []).join(',').padEnd(24)} ${humanRemaining(lease.expiresAt)}`);
+        }
+    });
+    cmd
+        .command('revoke <lease-id>')
+        .description('Revoke one scoped secret lease immediately.')
+        .action(async (leaseId) => {
+        if (agentSocketExists() && !(await agentPing()).reachable) {
+            throw new Error('Cannot revoke while the secrets broker is using an incompatible protocol. Restart the broker and retry.');
+        }
+        const persisted = deleteLeaseSession(leaseId);
+        const wiped = await agentRevoke(leaseId);
+        if (wiped + persisted === 0)
+            throw new Error(`Secret lease '${leaseId}' is not active.`);
+        console.log(chalk.green(`Revoked secret lease ${leaseId}.`));
+    });
     cmd
         .command('unlock [names...]')
         .description('Hold a bundle in the secrets-agent after one Touch ID, so concurrent runs read it without re-prompting (macOS). With --host, unlock FILE-backed bundle(s) on a remote (the passphrase prompt surfaces over the SSH TTY); keychain/biometry bundles are GUI-only and can\'t be remote-unlocked.')

package/dist/commands/sessions-picker.js

@@ -19,12 +19,17 @@ import { renderMarkdown } from '../lib/markdown.js';
 import { itemPicker } from '../lib/picker.js';
 import { classifyFileChanges, changeCounts, toolHistogram, detectTestResult } from '../lib/session/digest.js';
 import { extractArtifacts, extractHooks, extractLinks, extractRepos, extractSkills } from '../lib/session/highlights.js';
-/** A session whose transcript lives on another machine (folded in over the live
- * cross-machine fan-out): its `filePath` is on that peer's disk, so the preview
- * can't parse it locally — it shows metadata + a "resume there" note instead.
- * Keys off `_remote`, not the machine tag, so locally-readable synced mirrors
- * still parse their file normally. */
-function remoteMachineOf(session) {
+/** A session whose transcript FILE is on another machine (folded in over the
+ * live cross-machine fan-out): its `filePath` is on that peer's disk, so the
+ * preview can't parse it locally — it shows metadata + a "resume there" note
+ * instead. Keys off `_remote`, not the machine tag, so locally-readable synced
+ * mirrors still parse their file normally.
+ *
+ * This is the READ rule and only the read rule. Whether a session may be
+ * RESUMED here is a different question with a different answer — a mirror is
+ * readable but not resumable — and `sessionOwnerDevice`
+ * (lib/session/resume-owner.ts) is the single place that answers it (RUSH-2022). */
+function transcriptOnPeerOf(session) {
     return session._remote ? session.machine : undefined;
 }
 /**
@@ -98,7 +103,7 @@ function sanitizeMeta(s) {
 const previewCache = new Map();
 /** Build a cached multi-line preview string for display in the session picker. */
 export function buildPreview(session) {
-    const remote = remoteMachineOf(session);
+    const remote = transcriptOnPeerOf(session);
     const cacheKey = remote ? `${remote}:${session.id}` : session.id;
     const cached = previewCache.get(cacheKey);
     if (cached)

package/dist/commands/sessions.d.ts

@@ -11,7 +11,7 @@ interface SessionFilterOptions {
     all?: boolean;
     teams?: boolean;
     inTeam?: string;
-    routine?: boolean;
+    routine?: boolean | string;
     since?: string;
     until?: string;
 }
@@ -187,13 +187,33 @@ export declare function liveStatusWord(a: ActiveSession | undefined): string;
  */
 export declare function isAwaitingUser(s: ActiveSession): boolean;
 /**
- * Whether a row belongs in an unqualified `--active` view.
+ * Whether a row belongs in an unqualified `--active` view (RUSH-2336) — the
+ * ONE canonical selector every bare-active surface shares: the CLI's grouped
+ * table and `--json` (`renderActiveSessions`), the interactive browser's
+ * `--active` filter ({@link applyFilters} in `sessions-browser.ts`), `focus`'s
+ * attach gate (`isAttachableLiveSession`), and the menubar snapshot
+ * ({@link computeMenubarSnapshot}).
  *
- * The live registry deliberately retains terminally-dead rows long enough for
- * `--closed` / `--crashed` and recovery to find them. Presence in that registry
- * therefore is not, by itself, evidence that a session is still active.
- * Explicit lifecycle filters bypass this predicate and select those retained
- * rows through {@link matchesLiveStatus} instead.
+ * The live registry deliberately retains terminally-dead AND not-yet-started
+ * rows long enough for `--closed` / `--crashed` / `--queued` and recovery to
+ * find them. Presence in that registry therefore is not, by itself, evidence
+ * that a session is CURRENTLY active. Explicit lifecycle filters bypass this
+ * predicate and select those retained rows through {@link matchesLiveStatus}
+ * instead — this function only decides the unqualified default.
+ *
+ *   - `queued` / `closed` / `crashed` are never active here: queued hasn't
+ *     started yet, closed/crashed are unconditionally dead. All three stay
+ *     reachable through their explicit filter.
+ *   - A cloud row carries no local pid at all — it is active on the
+ *     provider's own word (`cloudProvider` + `cloudTaskId`), never a
+ *     fabricated pid.
+ *   - Every other row is a real OS process (terminal/tmux/headless/team). It
+ *     is active only when the row names the machine it runs on, carries a
+ *     positive pid, AND has POSITIVELY verified that pid is alive
+ *     (`pidAlive === true` — not merely "not known dead"). A live orphaned
+ *     row, or a live-but-stuck abandoned row, still qualifies this way since
+ *     both carry a genuinely alive pid; unknown liveness (an older peer's
+ *     row, or a pid that could never be resolved) does not.
  */
 export declare function isRunningLiveSession(s: ActiveSession): boolean;
 /**
@@ -389,6 +409,22 @@ export declare function isBareBrowserListing(options: SessionsOptions, query: st
  * `runSessionBrowser` picker cannot represent.
  */
 export declare function hasNoBrowserDisqualifyingFlags(options: SessionsOptions, query: string | undefined): boolean;
+/** Resolve a typed routine selector by exact name, substring, or one unambiguous typo. */
+export declare function resolveRoutineName(query: string, names: readonly string[]): string | null;
+export interface RoutineRunGroup {
+    runId: string;
+    timestamp: string;
+    sessions: SessionMeta[];
+}
+export interface RoutineChoice {
+    name: string;
+    lastRunAt: string;
+    runCount: number;
+    latestRunSessionCount: number;
+}
+export declare function buildRoutineRunGroups(sessions: SessionMeta[]): RoutineRunGroup[];
+export declare function buildRoutineChoices(sessions: SessionMeta[]): RoutineChoice[];
+export declare function filterSessionsByRoutine(sessions: SessionMeta[], routine: boolean | string, interactive: boolean): Promise<SessionMeta[] | null>;
 /** Resolve a session by id/query globally and print its compact preview (no pager).
  * Backs `--preview` — the fast path for the "peek before resume" hot loop. */
 export declare function renderSessionPreview(query: string, scope: {
@@ -478,6 +514,10 @@ export declare function buildOverviewGroups(pool: SessionMeta[], perProjectCap:
     groups: OverviewGroup[];
     projectCount: number;
 };
+export declare function printRoutineRunOverview(sessions: SessionMeta[], liveIndex: Map<string, ActiveSession> | undefined, opts?: {
+    hiddenCount?: number;
+    hiddenUnmanaged?: number;
+}): void;
 /**
  * Render a resolved session to stdout — the non-follow view behind
  * `agents logs <sessionId>`. Defaults to the concise `summary` digest (same as
@@ -577,6 +617,16 @@ export declare function pickSessionInteractive(sessions: SessionMeta[], message?
 export declare const LIVE_ROW_PREFIX = "live:";
 export declare function isIdlessLiveRow(s: SessionMeta): boolean;
 export declare function handlePickedSession(picked: PickedSession): Promise<void>;
+/**
+ * Resume `session` on the machine that owns it, when that is not this one.
+ * Returns true when it handled the resume (hopped, or reported an unreachable
+ * owner), false when the session is local and the caller should take over here.
+ *
+ * The one hop for a foreground, one-session-at-a-time resume — shared by the
+ * `agents sessions` picker and by `sessions resume`'s no-tab-backend path, which
+ * would otherwise reach `resumeSessionInPlace` and be refused (RUSH-2022).
+ */
+export declare function resumeOnOwnerIfRemote(session: SessionMeta): Promise<boolean>;
 /**
  * Resume a session in the current terminal — a foreground takeover of this
  * process. Used by the single-select picker and by `sessions resume` when the
@@ -647,6 +697,22 @@ export declare function resolveSessionQuery(pool: SessionMeta[], query: string,
 export declare function fleetNotFoundMessage(query: string, deviceCount: number, unreachable: string[]): string[];
 /** Filter and rank sessions by a multi-term search query across metadata and content. */
 export declare function filterSessionsByQuery(sessions: SessionMeta[], query: string | undefined): SessionMeta[];
+/**
+ * Narrow a session list by --project and --agent before search resolution.
+ * Without this, a query like "scoped search" could match sessions in BOTH
+ * the project you specified AND elsewhere, producing an ambiguity error
+ * even though the user already pointed at the correct scope.
+ */
+export declare function applyScopeFilters(sessions: SessionMeta[], scope: {
+    agent?: string;
+    project?: string;
+    routine?: boolean | string;
+}): SessionMeta[];
+export declare function artifactLookupScope(agent?: string, project?: string, routine?: boolean | string): {
+    agent?: string;
+    project?: string;
+    routine?: boolean | string;
+};
 /**
  * Whether a missed local id lookup should widen to a cross-machine sweep.
  *