@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/lib/secrets-types.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Wire-shared types for the standalone `secrets` CLI (PHNX-3989).
+ *
+ * The standalone engine (`@phnx-labs/secrets-cli`, extracted from what used to
+ * be `cli/src/lib/secrets/**`) owns every one of these shapes; this module only
+ * re-declares them so `secrets-client.ts` and its consumers keep exact static
+ * types across the process-client boundary with no runtime dependency on the
+ * (now deleted) in-repo engine. Keep byte-for-byte in sync with
+ * `secrets-cli/src/schema.ts` / `src/core/bundles.ts` — this is the one seam
+ * both sides legitimately re-declare rather than share a package for (see the
+ * `secrets-client.ts` docblock).
+ */
+/** Supported bundle storage backends. */
+export type SecretsBackend = 'keychain' | 'file' | 'vault';
+/** Supported secret resolution providers for a bundle var. */
+export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
+/** A typed reference to a secret: a provider plus a provider-specific value. */
+export interface SecretRef {
+    provider: SecretProvider;
+    value: string;
+}
+/**
+ * A bundle value: either a string (literal or provider-prefixed ref) or an
+ * object `{value: string}` used to escape a literal that would otherwise be
+ * parsed as a ref (e.g. a URL that happens to start with `env:`).
+ */
+export type BundleValue = string | {
+    value: string;
+};
+/** Remote (bundle@host) push destination backend. */
+export type RemoteBackend = 'keychain' | 'file';
+export declare const SECRET_TYPES: readonly ["api-key", "token", "password", "url", "database-url", "ssh-key", "certificate", "webhook", "note"];
+export type SecretType = (typeof SECRET_TYPES)[number];
+/** Per-secret metadata; absent fields are omitted at write time. */
+export interface VarMeta {
+    type?: SecretType;
+    /** Future-dated ISO date ('YYYY-MM-DD'). */
+    expires?: string;
+    note?: string;
+}
+/**
+ * Bundle prompt policy. `hold` (default): one Touch ID per hold window (~7d),
+ * then silent via the secrets-agent. `always`: prompt every read. `never`: no
+ * biometry ACL — least-safe, automation-only.
+ */
+export type SecretsPolicy = 'always' | 'hold' | 'never';
+/** A named set of environment variable definitions backed by secret stores. */
+export interface SecretsBundle {
+    name: string;
+    description?: string;
+    allow_exec?: boolean;
+    /** Absent ⇒ `keychain`. */
+    backend?: SecretsBackend;
+    /** Absent ⇒ configured default (`hold`). */
+    policy?: SecretsPolicy;
+    created_at?: string;
+    updated_at?: string;
+    last_used?: string;
+    vars: Record<string, BundleValue>;
+    meta?: Record<string, VarMeta>;
+}
+/** Per-key kind breakdown of an already-resolved bundle. */
+export interface BundleEntryInfo {
+    key: string;
+    kind: 'literal' | 'keychain' | 'env' | 'file' | 'exec';
+    /** Ref target, or empty for a literal. Never a resolved value. */
+    detail: string;
+}
+/** Options for `writeBundle` / `writeBundleWithItems`. */
+export interface WriteBundleOptions {
+    /** Skip evicting the broker-held copy (no-op writers such as `stampLastUsed`). */
+    skipBrokerEviction?: boolean;
+    /** Allow writing a reserved `__<harness>__` store. */
+    allowReservedStore?: boolean;
+}
+/** Options for `readAndResolveBundleEnv`. */
+export interface ResolveBundleOptions {
+    caller?: string;
+    /** Harness type whose unlock may be reused. */
+    agent?: string;
+    /** Duration shown in the Touch ID prompt. */
+    duration?: string;
+    /** Allow this call to raise an interactive biometric prompt. */
+    interactiveUnlock?: boolean;
+    /** Skip the broker fast-path and read from the keychain directly. */
+    noAgent?: boolean;
+    /** Resolve only from an already-unlocked broker snapshot; fail before prompting. */
+    agentOnly?: boolean;
+    /** Inject only these keys. Errors if any requested key is absent. */
+    keys?: string[];
+    /** Skip the per-key expiry gate. */
+    allowExpired?: boolean;
+    /** `process` projects dotted keys to shell-safe env names; `storage` preserves them. */
+    keyMode?: 'process' | 'storage';
+    /** Read a reserved `__<harness>__` store (system readers only). */
+    allowReservedStore?: boolean;
+}
+/** Options for `renameBundle`. */
+export interface RenameOptions {
+    /** Overwrite an existing destination bundle. */
+    force?: boolean;
+}
+/** Options for `rotateBundleSecret`. */
+export interface RotateOptions {
+    /** New plaintext value to write into the store (replaces the old one). */
+    newValue: string;
+    /** When true, drop existing meta for this key. Mutually exclusive with `meta`. */
+    clearMeta?: boolean;
+    /** Patch to merge into existing meta. Undefined fields preserve current values. */
+    meta?: Partial<VarMeta>;
+}
+/** Reading a keychain-backed item through the standalone. */
+export interface KeychainReadContext {
+    agent?: string;
+    bundle?: string;
+    sessionId?: string;
+    reason?: string;
+    duration?: string;
+    defaultPolicy?: 'hold' | 'always' | 'never';
+    forceDuration?: boolean;
+    /**
+     * The caller attests the item(s) carry NO biometry ACL — so the read is
+     * silent even when no one is at the screen. Never pass this for an
+     * ACL-protected item.
+     */
+    silentNoAcl?: boolean;
+}
+/** One held bundle unlock reported by `agent.agentStatus`. */
+export interface AgentStatusEntry {
+    name: string;
+    expiresAt: number;
+    keyCount: number;
+    harness: string;
+    leaseId?: string;
+    keys?: string[];
+}
+/** Options for `pushBundleToHost` / `pushBundleToHostAsync`. */
+export interface PushBundleOptions {
+    remoteBackend: RemoteBackend;
+    /** Overwrite a key that already exists on the remote. */
+    force?: boolean;
+    /**
+     * Ignored. File-backend export never forwards the passphrase (PHNX-2371);
+     * the remote auto-provisions its own machine-local key. Kept on the options
+     * type so existing callers that passed one still compile.
+     */
+    passphrase?: string;
+    /** Label for the audit trail — `export --device` vs `fleet apply`. */
+    operation: string;
+    /** Preserve an automation account's permanent prompt-free policy remotely. */
+    policyNever?: boolean;
+    /** Permit a human-invoked push to read locally without requiring the agent broker. */
+    agentOnly?: boolean;
+    /** Non-secret literals whose bundle value kind must survive the dotenv transport. */
+    literalValues?: Record<string, string>;
+    /** Per-SSH-operation deadline. Async daemon callers must set this explicitly. */
+    timeoutMs?: number;
+}
+export interface PushBundleResult {
+    ok: boolean;
+    host: string;
+    bundle: string;
+    keyCount: number;
+    /** One line for the caller to render. Never contains a secret value. */
+    message: string;
+}
+/** Lightweight listing entry returned by the managed sync transport. */
+export interface RemoteBundleSummary {
+    name: string;
+    updated_at: string;
+}
+/** Options for `pullBundle` (the `agents sync --secrets` umbrella stage). */
+export interface PullOptions {
+    passphrase: string;
+    /** When true, overwrite an existing local bundle. */
+    force?: boolean;
+}
+/** One credential-shaped shell-rc export finding. */
+export interface RcSecretFinding {
+    /** Basename of the rc file, e.g. `.zshenv`. */
+    file: string;
+    /** 1-based line number of the export. */
+    line: number;
+    /** The exported variable name. Never the value. */
+    name: string;
+    /** The file-store master passphrase gets called out separately. */
+    isMasterPassphrase: boolean;
+}

package/dist/lib/secrets-types.js

@@ -0,0 +1,24 @@
+/**
+ * Wire-shared types for the standalone `secrets` CLI (PHNX-3989).
+ *
+ * The standalone engine (`@phnx-labs/secrets-cli`, extracted from what used to
+ * be `cli/src/lib/secrets/**`) owns every one of these shapes; this module only
+ * re-declares them so `secrets-client.ts` and its consumers keep exact static
+ * types across the process-client boundary with no runtime dependency on the
+ * (now deleted) in-repo engine. Keep byte-for-byte in sync with
+ * `secrets-cli/src/schema.ts` / `src/core/bundles.ts` — this is the one seam
+ * both sides legitimately re-declare rather than share a package for (see the
+ * `secrets-client.ts` docblock).
+ */
+// --- bundle document ---------------------------------------------------
+export const SECRET_TYPES = [
+    'api-key',
+    'token',
+    'password',
+    'url',
+    'database-url',
+    'ssh-key',
+    'certificate',
+    'webhook',
+    'note',
+];

package/dist/lib/self-heal/checks/shims.js

@@ -46,10 +46,12 @@ export const shimsCheck = {
             if (!ctx.dryRun && removeLegacyUserShim(agent))
                 fixed.push(`removed legacy ${cmd} shim`);
         }
-        // Prune orphaned legacy command shims (browser/secrets/sessions/… left by a
-        // removed install) whose baked AGENTS_BIN is dead — the current source never
+        // Prune orphaned legacy command shims (browser/sessions/… left by a removed
+        // install) whose baked AGENTS_BIN is dead — the current source never
         // regenerates them, and they either die with exit 127 or shadow the real
-        // package bin on PATH. Only removes shims whose target install is gone.
+        // package bin on PATH. Only removes shims whose target install is gone — plus
+        // the legacy `secrets` shim regardless: it re-enters `agents secrets`, which is
+        // a passthrough to the standalone binary since PHNX-3989, so it can only recurse.
         if (!ctx.dryRun) {
             for (const name of listShimFileNames()) {
                 if (pruneOrphanedCommandShim(name))

package/dist/lib/service-manifest.js

@@ -27,10 +27,9 @@
  * module is the single place both rules live, so a new manifest has one obvious
  * thing to call.
  *
- * It is not yet the only consumer of the identifier rule: `lib/secrets/agent.ts`
- * keeps a literal `SERVICE_LABEL` for its `bootout`. That path is retire-only —
- * it detects and removes a plist an older version installed and generates none
- * of its own — so it has no HOME to bake and was deliberately left alone.
+ * A third consumer that used to keep its own literal `SERVICE_LABEL` for a
+ * retire-only `bootout` — the in-repo secrets broker's launchd cleanup — moved
+ * out of this repo entirely with the standalone `secrets` engine (PHNX-3989).
  */
 import * as crypto from 'crypto';
 import * as os from 'os';

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

@@ -817,6 +817,22 @@ export declare function buildFtsQuery(input: string): {
  * so "higher = better" is consistent across all tiers.
  */
 export declare function ftsSearch(input: string, limit?: number): FtsHit[];
+/**
+ * Rewrite file_path for sessions whose path starts with any of `moves.from`,
+ * replacing that prefix with `moves.to` and clearing the matching scan_ledger
+ * entries so the next scan re-indexes from the new location.
+ *
+ * One transaction for the whole batch (PHNX-3940 T7): a migration that moves
+ * several homes into slots and several version dirs into trash must not leave
+ * the index half-rewritten. Longest `from` wins when prefixes nest, and each
+ * session row is rewritten at most once.
+ *
+ * Returns the number of session rows updated.
+ */
+export declare function reindexMovedSessionPaths(moves: ReadonlyArray<{
+    from: string;
+    to: string;
+}>): number;
 /**
  * Rewrite file_path for all sessions whose path starts with oldPrefix, replacing
  * it with newPrefix + the unchanged suffix. Also clears the matching scan_ledger
@@ -827,6 +843,8 @@ export declare function ftsSearch(input: string, limit?: number): FtsHit[];
  * Returns the number of session rows updated.
  */
 export declare function updateSessionFilePaths(oldPrefix: string, newPrefix: string): number;
+/** Count indexed sessions whose transcript path sits under `prefix`. */
+export declare function countSessionsWithFilePrefix(prefix: string): number;
 /** Per-kind capture tallies for a browser task. Counts only -- never the bytes. */
 interface BrowserCaptureCounts {
     screenshot: number;

package/dist/lib/session/db.js

@@ -4317,6 +4317,44 @@ export function ftsSearch(input, limit = 200) {
     hits.sort((a, b) => b.score - a.score);
     return hits.slice(0, limit);
 }
+/**
+ * Rewrite file_path for sessions whose path starts with any of `moves.from`,
+ * replacing that prefix with `moves.to` and clearing the matching scan_ledger
+ * entries so the next scan re-indexes from the new location.
+ *
+ * One transaction for the whole batch (PHNX-3940 T7): a migration that moves
+ * several homes into slots and several version dirs into trash must not leave
+ * the index half-rewritten. Longest `from` wins when prefixes nest, and each
+ * session row is rewritten at most once.
+ *
+ * Returns the number of session rows updated.
+ */
+export function reindexMovedSessionPaths(moves) {
+    const usable = moves.filter((m) => m.from && m.from !== m.to);
+    if (usable.length === 0)
+        return 0;
+    const db = getDB();
+    const sorted = [...usable].sort((a, b) => b.from.length - a.from.length);
+    return db.transaction(() => {
+        let n = 0;
+        const seen = new Set();
+        const update = db.prepare(`UPDATE sessions SET file_path = ? WHERE id = ?`);
+        const dropLedger = db.prepare(`DELETE FROM scan_ledger WHERE file_path = ?`);
+        const select = db.prepare(`SELECT id, file_path FROM sessions WHERE file_path LIKE ?`);
+        for (const { from, to } of sorted) {
+            const rows = select.all(from + '%');
+            for (const { id, file_path } of rows) {
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                update.run(to + file_path.slice(from.length), id);
+                dropLedger.run(canonicalLedgerKey(file_path));
+                n++;
+            }
+        }
+        return n;
+    })();
+}
 /**
  * Rewrite file_path for all sessions whose path starts with oldPrefix, replacing
  * it with newPrefix + the unchanged suffix. Also clears the matching scan_ledger
@@ -4327,21 +4365,16 @@ export function ftsSearch(input, limit = 200) {
  * Returns the number of session rows updated.
  */
 export function updateSessionFilePaths(oldPrefix, newPrefix) {
-    const db = getDB();
-    const rows = db
-        .prepare(`SELECT id, file_path FROM sessions WHERE file_path LIKE ?`)
-        .all(oldPrefix + '%');
-    if (rows.length === 0)
+    return reindexMovedSessionPaths([{ from: oldPrefix, to: newPrefix }]);
+}
+/** Count indexed sessions whose transcript path sits under `prefix`. */
+export function countSessionsWithFilePrefix(prefix) {
+    if (!prefix)
         return 0;
-    const txn = db.transaction(() => {
-        for (const { id, file_path } of rows) {
-            const newPath = newPrefix + file_path.slice(oldPrefix.length);
-            db.prepare(`UPDATE sessions SET file_path = ? WHERE id = ?`).run(newPath, id);
-            db.prepare(`DELETE FROM scan_ledger WHERE file_path = ?`).run(canonicalLedgerKey(file_path));
-        }
-    });
-    txn();
-    return rows.length;
+    const row = getDB()
+        .prepare(`SELECT COUNT(*) AS c FROM sessions WHERE file_path LIKE ?`)
+        .get(prefix + '%');
+    return row.c;
 }
 /**
  * Upsert one browser task's durable metadata.

package/dist/lib/session/sync/config.js

@@ -11,7 +11,7 @@
  * background sync. Credentials come from the `r2.backups` secrets bundle (OS
  * keychain on macOS, libsecret on Linux) — never from env or disk.
  */
-import { readAndResolveBundleEnv } from '../../secrets/bundles.js';
+import { readAndResolveBundleEnvSync } from '../../secrets-client.js';
 /** Secrets bundle holding the R2 credentials. */
 export const SYNC_BUNDLE = 'r2.backups';
 /**
@@ -30,7 +30,7 @@ function resolveR2Config() {
     // and degrades to no-transport (sync disabled) with no prompt and no crash —
     // unlock once (`agents secrets unlock r2.backups`) or set it no-ACL
     // (`agents secrets policy r2.backups never`) for silent zero-friction sync.
-    const { env } = readAndResolveBundleEnv(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: true });
+    const { env } = readAndResolveBundleEnvSync(SYNC_BUNDLE, { caller: 'session-transport', agentOnly: true });
     const accountId = env.R2_ACCOUNT_ID?.trim();
     const bucket = env.R2_BUCKET_NAME?.trim();
     const accessKeyId = env.R2_ACCESS_KEY_ID?.trim();

package/dist/lib/sha256-asset.d.ts

@@ -3,22 +3,17 @@
  *
  * These live in their own LEAF module — importing only `node:crypto` and
  * `node:fs` — on purpose. They used to sit in `computer/ssh-tunnel.ts`, whose
- * own import graph reaches `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
- * `secrets/*`. `helper-download.ts` needs nothing from that graph but these two
- * pure functions, and importing them from there closed a module-initialization
- * cycle:
- *
- *   helper-download.ts
- *     -> computer/ssh-tunnel.ts        (evaluated BEFORE `EXPECTED_TEAM_ID`)
- *       -> browser/drivers/ssh.ts -> browser/chrome.ts
- *         -> secrets/bundles.ts -> secrets/index.ts -> secrets/install-helper.ts
- *           -> secrets/download-keychain.ts
- *             -> helper-download.ts    (still evaluating; const not yet bound)
- *
- * which threw `ReferenceError: Cannot access 'EXPECTED_TEAM_ID' before
- * initialization` at `secrets/download-keychain.ts:45` for any entry point that
- * reached `helper-download.ts` first (RUSH-3113). Keep this module a leaf: adding
- * a local import here can reintroduce that cycle.
+ * own import graph reached `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
+ * the in-repo secrets engine's own keychain-helper downloader, which imported
+ * back into `helper-download.ts` while it was still evaluating — before
+ * `EXPECTED_TEAM_ID` was bound, throwing `ReferenceError: Cannot access
+ * 'EXPECTED_TEAM_ID' before initialization` for any entry point that reached
+ * `helper-download.ts` first (RUSH-3113). The secrets engine that closed that
+ * cycle is gone now (PHNX-3989 — the standalone `secrets` CLI downloads its own
+ * helper), but the discipline that fixed it still holds: keep this module a
+ * leaf, since `helper-download.ts` needs nothing beyond these two pure
+ * functions and adding a local import here can reintroduce a cycle with
+ * whatever imports it next.
  */
 /** Pull the digest out of a `<sha256>  <filename>` release asset. */
 export declare function parseSha256Asset(text: string): string;

package/dist/lib/sha256-asset.js

@@ -3,22 +3,17 @@
  *
  * These live in their own LEAF module — importing only `node:crypto` and
  * `node:fs` — on purpose. They used to sit in `computer/ssh-tunnel.ts`, whose
- * own import graph reaches `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
- * `secrets/*`. `helper-download.ts` needs nothing from that graph but these two
- * pure functions, and importing them from there closed a module-initialization
- * cycle:
- *
- *   helper-download.ts
- *     -> computer/ssh-tunnel.ts        (evaluated BEFORE `EXPECTED_TEAM_ID`)
- *       -> browser/drivers/ssh.ts -> browser/chrome.ts
- *         -> secrets/bundles.ts -> secrets/index.ts -> secrets/install-helper.ts
- *           -> secrets/download-keychain.ts
- *             -> helper-download.ts    (still evaluating; const not yet bound)
- *
- * which threw `ReferenceError: Cannot access 'EXPECTED_TEAM_ID' before
- * initialization` at `secrets/download-keychain.ts:45` for any entry point that
- * reached `helper-download.ts` first (RUSH-3113). Keep this module a leaf: adding
- * a local import here can reintroduce that cycle.
+ * own import graph reached `browser/drivers/ssh.ts` -> `browser/chrome.ts` ->
+ * the in-repo secrets engine's own keychain-helper downloader, which imported
+ * back into `helper-download.ts` while it was still evaluating — before
+ * `EXPECTED_TEAM_ID` was bound, throwing `ReferenceError: Cannot access
+ * 'EXPECTED_TEAM_ID' before initialization` for any entry point that reached
+ * `helper-download.ts` first (RUSH-3113). The secrets engine that closed that
+ * cycle is gone now (PHNX-3989 — the standalone `secrets` CLI downloads its own
+ * helper), but the discipline that fixed it still holds: keep this module a
+ * leaf, since `helper-download.ts` needs nothing beyond these two pure
+ * functions and adding a local import here can reintroduce a cycle with
+ * whatever imports it next.
  */
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';

package/dist/lib/share/config.js

@@ -9,8 +9,7 @@
 //   `cloudflare` bundle.
 import { randomBytes } from 'node:crypto';
 import { readMeta, updateMeta } from '../state.js';
-import { bundleExists, bundleItemStore, bundlePolicy, keychainRef, readAndResolveBundleEnv, readBundle, writeBundle, } from '../secrets/bundles.js';
-import { secretsKeychainItem } from '../secrets/index.js';
+import { bundleExistsSync as bundleExists, keychainRef, readAndResolveBundleEnvSync as readAndResolveBundleEnv, readBundleSync as readBundle, secretsKeychainItem, writeBundleWithItemsSync as writeBundleWithItems, } from '../secrets-client.js';
 export const SHARE_BUNDLE = 'share';
 export const SHARE_TOKEN_KEY = 'WRITE_TOKEN';
 export const SHARE_TOKEN_ENV_KEY = 'SHARE_WRITE_TOKEN';
@@ -113,10 +112,12 @@ export function storeWriteToken(token) {
             vars: {},
         };
     }
-    const store = bundleItemStore(bundle.backend, { noAcl: bundlePolicy(bundle) === 'never' });
-    store.set(secretsKeychainItem(bundle.name, SHARE_TOKEN_KEY), token);
+    // writeBundleWithItems decides the ACL (keychain backend) purely from
+    // `bundle.policy === 'never'` — the fresh-bundle case above sets it
+    // explicitly, and an existing bundle already carries its own explicit tier.
     bundle.vars[SHARE_TOKEN_KEY] = keychainRef(SHARE_TOKEN_KEY);
-    writeBundle(bundle);
+    const item = secretsKeychainItem(bundle.name, SHARE_TOKEN_KEY);
+    writeBundleWithItems(bundle, new Map([[item, token]]));
 }
 /** Read the raw write token from the `share` secrets bundle. */
 export function readWriteTokenFromBundle() {
@@ -178,6 +179,14 @@ export function readCloudflareCreds(bundle = DEFAULT_CF_BUNDLE, override) {
     if (override?.apiToken) {
         return { apiToken: override.apiToken, accountId: override.accountId ?? '' };
     }
+    // Check existence first (same guard as readShareToken above): resolving a
+    // missing bundle through the process client surfaces an opaque transport code
+    // (e.g. LOCKED), never naming the bundle the user typed — so name it here.
+    if (!bundleExists(bundle)) {
+        throw new Error(`The '${bundle}' bundle does not exist. ` +
+            `Pass credentials directly with --token <t> [--account <id>], or create it: ` +
+            `agents secrets add ${bundle} CLOUDFLARE_API_TOKEN`);
+    }
     const { env } = readAndResolveBundleEnv(bundle, {
         caller: 'share',
         // Setup is still a read; only `agents secrets unlock` may authenticate.

package/dist/lib/signin-badge.d.ts

@@ -1,5 +1,8 @@
 import type { AccountInfo } from './agents.js';
+import type { AuthVerdict } from './auth-health.js';
 import type { AgentId } from './types.js';
+export type AccountVerdict = Exclude<AuthVerdict, 'unconfigured' | 'error'> | 'missing' | 'per-device' | 'ready';
+export type AccountProvisioning = 'portable' | 'per-device';
 /**
  * The exact command that logs a given agent in — for warn banners and nudges.
  * Driven off the registry `cliCommand` with the per-agent subcommand overrides
@@ -8,6 +11,29 @@ import type { AgentId } from './types.js';
  * remaining agents (kimi, gemini, …) start their device/oauth flow on launch.
  */
 export declare function loginHint(agentId: AgentId): string;
+/**
+ * Exact action shown beside a non-live account. Every emitted command exists
+ * today — never a planned surface and never a hidden verb:
+ * - Per-device harnesses repair per box via `agents devices login`.
+ * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
+ *   A known account with no slot on a headed device is onboarded with
+ *   `agents accounts add <harness> <name>`. A worker never runs an
+ *   interactive login — the hint is `add.ts`'s worker refusal (add on the
+ *   personal device; this box is provisioned from the durable credential).
+ * - Unnamed legacy homes use the same version-targeted command shape as
+ *   doctor, so the hint never logs a different/default home in by accident.
+ * - `unverified` emits nothing: the probe could not confirm state (e.g. a
+ *   worker whose token lacks the usage scope), so there is nothing to repair.
+ */
+export declare function fixFor(input: {
+    agent: AgentId;
+    verdict: AccountVerdict;
+    name?: string | null;
+    version?: string | null;
+    provisioning?: AccountProvisioning;
+    /** When false, this named account has no slot on this device yet. */
+    hasSlot?: boolean;
+}): string | null;
 /**
  * Whether `agents run` should probe login state before launching. True only for
  * a launch that actually opens the interactive TUI — where discovering a logged-out

package/dist/lib/signin-badge.js

@@ -9,7 +9,9 @@
  * on it (the run preflight) WARN and continue; they never block.
  */
 import chalk from 'chalk';
+import { addWorkerRefusal } from './accounts/add.js';
 import { AGENTS } from './agents.js';
+import { CONFIG_ENV_ISOLATED_AGENTS } from './installations/shims.js';
 /**
  * The exact command that logs a given agent in — for warn banners and nudges.
  * Driven off the registry `cliCommand` with the per-agent subcommand overrides
@@ -34,6 +36,46 @@ export function loginHint(agentId) {
             return cli;
     }
 }
+/**
+ * Exact action shown beside a non-live account. Every emitted command exists
+ * today — never a planned surface and never a hidden verb:
+ * - Per-device harnesses repair per box via `agents devices login`.
+ * - Named accounts re-auth through `agents accounts login <harness>#<name>`.
+ *   A known account with no slot on a headed device is onboarded with
+ *   `agents accounts add <harness> <name>`. A worker never runs an
+ *   interactive login — the hint is `add.ts`'s worker refusal (add on the
+ *   personal device; this box is provisioned from the durable credential).
+ * - Unnamed legacy homes use the same version-targeted command shape as
+ *   doctor, so the hint never logs a different/default home in by accident.
+ * - `unverified` emits nothing: the probe could not confirm state (e.g. a
+ *   worker whose token lacks the usage scope), so there is nothing to repair.
+ */
+export function fixFor(input) {
+    const { agent, verdict } = input;
+    if (verdict === 'live' || verdict === 'rate_limited' || verdict === 'unverified' || verdict === 'ready')
+        return null;
+    if (input.provisioning === 'per-device' || verdict === 'per-device') {
+        return `agents devices login --agents ${agent}`;
+    }
+    if (input.name) {
+        const worker = addWorkerRefusal(agent, input.name);
+        if (worker)
+            return worker;
+        if (input.hasSlot === false)
+            return `agents accounts add ${agent} ${input.name}`;
+        return `agents accounts login ${agent}#${input.name}`;
+    }
+    const version = input.version ?? null;
+    if (!version || !CONFIG_ENV_ISOLATED_AGENTS.includes(agent))
+        return loginHint(agent);
+    if (agent === 'claude')
+        return `agents run ${agent}@${version}, then /login`;
+    if (agent === 'codex' || agent === 'grok')
+        return `agents run ${agent}@${version} -- login`;
+    if (agent === 'opencode')
+        return `agents run ${agent}@${version} -- auth login`;
+    return `agents run ${agent}@${version}`;
+}
 /**
  * Whether `agents run` should probe login state before launching. True only for
  * a launch that actually opens the interactive TUI — where discovering a logged-out