@phnx-labs/agents-cli 1.22.39 → 1.22.40

package/dist/commands/webhook.js

@@ -1,7 +1,7 @@
 import * as path from 'path';
 import chalk from 'chalk';
 import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
-import { createFileDeliveryStore, startWebhookServer } from '../lib/triggers/webhook.js';
+import { createFileDeliveryStore, startWebhookServer, waitForListening } from '../lib/triggers/webhook.js';
 import { getRuntimeStateDir } from '../lib/state.js';
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8787;
@@ -30,26 +30,6 @@ function readWebhookSecrets(bundleName) {
     }
     return secrets;
 }
-function waitForListening(server) {
-    if (server.listening)
-        return Promise.resolve();
-    return new Promise((resolve, reject) => {
-        const cleanup = () => {
-            server.off('listening', onListening);
-            server.off('error', onError);
-        };
-        const onListening = () => {
-            cleanup();
-            resolve();
-        };
-        const onError = (err) => {
-            cleanup();
-            reject(err);
-        };
-        server.once('listening', onListening);
-        server.once('error', onError);
-    });
-}
 export function registerWebhooksCommand(program) {
     const webhooks = program
         .command('webhooks')
@@ -58,7 +38,7 @@ export function registerWebhooksCommand(program) {
         .command('serve')
         .description('Receive signed GitHub/Linear webhooks on /hooks/<source> and fire matching routines.')
         .requiredOption('--secrets-bundle <name>', 'agents secrets bundle containing GITHUB_WEBHOOK_SECRET and/or LINEAR_WEBHOOK_SECRET')
-        .option('--host <addr>', `Bind address (default ${DEFAULT_HOST})`, DEFAULT_HOST)
+        .option('--bind <addr>', `Bind address (default ${DEFAULT_HOST})`, DEFAULT_HOST)
         .option('-p, --port <n>', `Local port (default ${DEFAULT_PORT})`, String(DEFAULT_PORT))
         .option('--rate-limit <n>', 'Accepted deliveries per source per minute', '60')
         .action(async (opts) => {
@@ -74,7 +54,7 @@ export function registerWebhooksCommand(program) {
         const rateLimit = positiveInt(opts.rateLimit, 60);
         try {
             const server = startWebhookServer({
-                host: opts.host ?? DEFAULT_HOST,
+                host: opts.bind ?? DEFAULT_HOST,
                 port,
                 secrets,
                 rateLimitPerMinute: rateLimit,
@@ -90,12 +70,18 @@ export function registerWebhooksCommand(program) {
                     console.log(`${new Date().toISOString()} ${webhook.source}:${webhook.event} ` +
                         (parts.length ? `fired ${parts.join('; ')}` : 'no match'));
                 },
+                // The delivery is acked 202 before dispatch (RUSH-2548), so a dispatch
+                // failure has no HTTP status left to ride — print it instead.
+                onDeliveryError: (webhook, err) => {
+                    console.error(chalk.red(`${new Date().toISOString()} ${webhook.source}:${webhook.event} dispatch failed after ack: ${err.message}`));
+                },
             });
             await waitForListening(server);
             const address = server.address();
             const bound = typeof address === 'object' && address ? address.port : port;
-            console.log(`${chalk.green('agents webhooks')} ${chalk.dim('→')} ${chalk.cyan(`http://${opts.host ?? DEFAULT_HOST}:${bound}`)}`);
-            console.log(chalk.dim('signed · localhost by default · endpoints: /hooks/github, /hooks/linear · Ctrl-C to stop'));
+            console.log(`${chalk.green('agents webhooks')} ${chalk.dim('→')} ${chalk.cyan(`http://${opts.bind ?? DEFAULT_HOST}:${bound}`)}`);
+            console.log(chalk.dim('signed · localhost by default · endpoints: /hooks/github, /hooks/linear · acks 202 then dispatches · Ctrl-C to stop'));
+            console.log(chalk.dim('for a supervised receiver that survives reboot: agents daemon webhooks add --secrets-bundle <name>'));
             const shutdown = () => {
                 server.close(() => process.exit(0));
             };

package/dist/commands/workflows.js

@@ -8,7 +8,7 @@ import { resolveAgentName, agentLabel } from '../lib/agents.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { cloneRepo } from '../lib/git.js';
 import { discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
-import { getVersionHomePath, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
+import { getVersionHomePath, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/installations/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';

package/dist/index.js

@@ -71,7 +71,7 @@ if (process.argv[2] === '__shim') {
     process.exit(code);
 }
 if (process.argv[2] === '__daemon-run') {
-    const { runDaemon, log: daemonLog } = await import('./lib/daemon.js');
+    const { runDaemon, log: daemonLog } = await import('./lib/daemon/daemon.js');
     // RUSH-2418: the daemon is the one always-on process here, and it ran with no
     // top-level handler of any kind — an uncaught throw or a rejected promise from
     // any of its background ticks died on Node's default handler, printing a raw

package/dist/lib/account-capabilities.d.ts

@@ -0,0 +1,39 @@
+import type { AgentId } from './types.js';
+/**
+ * How safely agents-cli can read a harness's native login identity, and at what
+ * granularity that identity is scoped.
+ *
+ * - `inspection`: `strong` = a stable account key (Claude/Codex/Grok);
+ *   `email` = only an email claim, so the name binds to an address not a token
+ *   (Muse); `opaque` = a stable but non-human identifier from an OAuth/JWT blob
+ *   with no email (the device-scoped harnesses); `none` = no inspectable identity.
+ * - `scope`: `version` = auth lives per installed version home; `device` = one
+ *   login per device shared by every install; `unsupported` = agents-cli must not
+ *   name/attach this harness's native login.
+ * - `status`: `supported` = name + attach safely; `conditional` = supported only
+ *   when the weaker (email) identity is present; `discovery-only` = shown in the
+ *   list but not nameable; `unsupported` = neither.
+ */
+export interface NativeAccountCapability {
+    inspection: 'strong' | 'email' | 'opaque' | 'none';
+    scope: 'version' | 'device' | 'unsupported';
+    status: 'supported' | 'conditional' | 'discovery-only' | 'unsupported';
+}
+/** Canonical truth for native-account naming and attachment semantics. */
+export declare const NATIVE_ACCOUNT_CAPABILITIES: Record<AgentId, NativeAccountCapability>;
+export declare function nativeAccountCapability(agent: AgentId): NativeAccountCapability;
+/** Whether a harness's native login can be named/attached (supported or conditional). */
+export declare function nativeAccountNameable(agent: AgentId): boolean;
+/**
+ * The single identity key used at `accounts name`, attach, exec validation,
+ * view, and inventory. Prefer the harness's stable `accountKey`. For an
+ * email-only (`conditional`) harness, email is a presence gate — the stored
+ * key is still `accountKey` (e.g. `muse:email=user@x.com`), never the bare
+ * address, so `run`/`view` compare against the same value `getAccountInfo`
+ * returns.
+ */
+export declare function nativeIdentityKey(info: {
+    signedIn?: boolean;
+    email?: string | null;
+    accountKey?: string | null;
+}, capability: NativeAccountCapability): string | null;

package/dist/lib/account-capabilities.js

@@ -0,0 +1,59 @@
+/** Canonical truth for native-account naming and attachment semantics. */
+export const NATIVE_ACCOUNT_CAPABILITIES = {
+    // Version-scoped with a strong account key — the only harnesses whose native
+    // identity is safe to pin per installed version.
+    claude: { inspection: 'strong', scope: 'version', status: 'supported' },
+    codex: { inspection: 'strong', scope: 'version', status: 'supported' },
+    grok: { inspection: 'strong', scope: 'version', status: 'supported' },
+    // Version-scoped but only an email identity — nameable only when that email is
+    // present (the resolver rejects an emailless Muse login).
+    muse: { inspection: 'email', scope: 'version', status: 'conditional' },
+    // Device-scoped, opaque identity (an OAuth/JWT blob). These are recorded as
+    // device-scoped opaque, but marked UNSUPPORTED for naming: a NativeAccount has
+    // no device-id discriminator, so an opaque/singleton identity cannot be proven
+    // to distinguish accounts across synced metadata — Droid exposes no account key
+    // at all, and Antigravity (singleton) / OpenCode (provider-set) can read two
+    // different credentials as the same identity on another device. A truthful
+    // "unsupported" is correct until a device-scoped identity key (with a stable
+    // device id) exists to validate against.
+    antigravity: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
+    kimi: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
+    droid: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
+    opencode: { inspection: 'opaque', scope: 'device', status: 'unsupported' },
+    // Cursor multi-account isolation is unresolved (RUSH-2400) — blocked from
+    // native naming/attachment; its API-key path is a provider account instead.
+    cursor: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    // Discoverable in the list, but not nameable.
+    gemini: { inspection: 'email', scope: 'unsupported', status: 'discovery-only' },
+    copilot: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    openclaw: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    amp: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    kiro: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    goose: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    hermes: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    pi: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+    warp: { inspection: 'none', scope: 'unsupported', status: 'unsupported' },
+};
+export function nativeAccountCapability(agent) {
+    return NATIVE_ACCOUNT_CAPABILITIES[agent];
+}
+/** Whether a harness's native login can be named/attached (supported or conditional). */
+export function nativeAccountNameable(agent) {
+    const cap = NATIVE_ACCOUNT_CAPABILITIES[agent];
+    return (cap.status === 'supported' || cap.status === 'conditional') && cap.scope !== 'unsupported';
+}
+/**
+ * The single identity key used at `accounts name`, attach, exec validation,
+ * view, and inventory. Prefer the harness's stable `accountKey`. For an
+ * email-only (`conditional`) harness, email is a presence gate — the stored
+ * key is still `accountKey` (e.g. `muse:email=user@x.com`), never the bare
+ * address, so `run`/`view` compare against the same value `getAccountInfo`
+ * returns.
+ */
+export function nativeIdentityKey(info, capability) {
+    if (!info.signedIn)
+        return null;
+    if (capability.inspection === 'email' && !info.email)
+        return null;
+    return info.accountKey ?? info.email?.toLowerCase() ?? null;
+}

package/dist/lib/account-catalog.js

@@ -1,5 +1,5 @@
 import { ALL_AGENT_IDS, getAccountInfo, supportsAccountInspection } from './agents.js';
-import { getVersionHomePath, listInstalledVersions } from './versions.js';
+import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 export function groupNativeAccountRows(rows) {
     const grouped = new Map();
     for (const row of rows) {

package/dist/lib/account-registry.d.ts

@@ -19,12 +19,42 @@ export interface ResolvedCredentialAccount {
     auth: AccountAuthKind;
     env: Record<string, string>;
 }
+export interface NativeAccount {
+    id: string;
+    name: string;
+    kind: 'native';
+    agent: AgentId;
+    identityKey: string;
+    identityLabel?: string;
+    scope: 'version' | 'device';
+}
+export type UnifiedAccount = (CredentialAccount & {
+    kind: 'provider';
+}) | NativeAccount;
 export declare function accountRegistryPath(base?: string): string;
 export declare function readAccountRegistry(base?: string): AccountRegistryDocument;
 export declare function findAccount(name: string, doc?: AccountRegistryDocument): CredentialAccount | null;
+export declare function listNativeAccounts(meta: Pick<Meta, 'accounts'>): NativeAccount[];
+/**
+ * Resolve one account by name or id across both stores, native first.
+ *
+ * `doc` is optional and read LAZILY: a native match returns without ever reading
+ * the provider bundle registry — so a native view/attach/run never triggers a
+ * bundle read, legacy-`accounts.yaml` migration, or a keychain decrypt (which
+ * would surface a Touch ID prompt or crash on an undecryptable legacy item). A
+ * default-evaluated `doc = readAccountRegistry()` argument would defeat this by
+ * running before the body, so callers that only need a native lookup must be
+ * able to omit it.
+ */
+export declare function findUnifiedAccount(nameOrId: string, meta: Pick<Meta, 'accounts'>, doc?: AccountRegistryDocument): UnifiedAccount | null;
+export declare function addNativeAccount(name: string, agent: AgentId, identityKey: string, identityLabel: string | undefined, scope: 'version' | 'device'): NativeAccount;
+export declare function bindAccount(nameOrId: string, target: string): UnifiedAccount;
+export declare function unbindAccount(nameOrId: string, target: string): void;
+export declare function accountBindings(accountId: string, meta: Pick<Meta, 'accounts'>): string[];
 /** Explicit selection wins over a configured per-harness default. */
 export declare function resolveAccountSelection(explicit: string | undefined, agent: AgentId, meta: Pick<Meta, 'accounts'>, opts?: {
     useDefault?: boolean;
+    target?: string;
 }): string | undefined;
 export interface AddAccountOptions {
     baseUrl?: string;
@@ -38,3 +68,39 @@ export declare function inspectAccount(name: string, base?: string): CredentialA
     policy: 'never';
 };
 export declare function resolveCredentialAccount(name: string, host: AgentId, expectedProvider?: string, base?: string): ResolvedCredentialAccount;
+/** The account a spawn should launch under, classified for the exec path. */
+export type SpawnAccount = {
+    kind: 'provider';
+    id: string;
+    name: string;
+    agent: AgentId;
+    env: Record<string, string>;
+} | {
+    kind: 'native';
+    id: string;
+    name: string;
+    agent: AgentId;
+    identityKey: string;
+    scope: 'version' | 'device';
+};
+/**
+ * Resolve the account a run should launch under, following the binding order
+ * (explicit → exact `agent@version` → device-scoped `agent` → per-harness
+ * default) and classifying the result:
+ *
+ * - **provider** → the injected env is resolved here (fails closed when the
+ *   credential is absent or the provider cannot authenticate the host).
+ * - **native** → returns the identity the caller must confirm is live on the
+ *   execution device; **no secret or env is produced**, because a native login
+ *   is owned by the harness and read from its own home. The caller validates the
+ *   live fingerprint against the installed version before spawn.
+ *
+ * A native account bound to a different harness than the one being launched
+ * fails loudly (EXEC-ACCOUNT-4). Returns null when nothing is selected.
+ */
+export declare function resolveSpawnAccount(explicit: string | undefined, agent: AgentId, version: string | undefined, meta: Pick<Meta, 'accounts'>, opts?: {
+    useDefault?: boolean;
+    provider?: string;
+    base?: string;
+    target?: string;
+}): SpawnAccount | null;

package/dist/lib/account-registry.js

@@ -19,7 +19,7 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import * as yaml from 'yaml';
 import { atomicWriteFileSync } from './fs-atomic.js';
-import { getUserAgentsDir } from './state.js';
+import { getUserAgentsDir, readMeta, updateMeta } from './state.js';
 import { deleteKeychainToken, getKeychainToken, hasKeychainToken } from './secrets/index.js';
 import { bundleExists, deleteBundle, listBundles, readBundle, renameBundle, writeBundleWithItems } from './secrets/bundles.js';
 import { getAccountProvider } from './account-provider-registry.js';
@@ -128,10 +128,85 @@ export function readAccountRegistry(base = getUserAgentsDir()) {
 export function findAccount(name, doc = readAccountRegistry()) {
     return doc.accounts[name] ?? Object.values(doc.accounts).find(account => account.name === name) ?? null;
 }
+export function listNativeAccounts(meta) {
+    return Object.values(meta.accounts?.native ?? {}).map(account => ({ ...account, kind: 'native' }));
+}
+/**
+ * Resolve one account by name or id across both stores, native first.
+ *
+ * `doc` is optional and read LAZILY: a native match returns without ever reading
+ * the provider bundle registry — so a native view/attach/run never triggers a
+ * bundle read, legacy-`accounts.yaml` migration, or a keychain decrypt (which
+ * would surface a Touch ID prompt or crash on an undecryptable legacy item). A
+ * default-evaluated `doc = readAccountRegistry()` argument would defeat this by
+ * running before the body, so callers that only need a native lookup must be
+ * able to omit it.
+ */
+export function findUnifiedAccount(nameOrId, meta, doc) {
+    const native = listNativeAccounts(meta).find(account => account.id === nameOrId || account.name === nameOrId);
+    if (native)
+        return native;
+    const provider = findAccount(nameOrId, doc ?? readAccountRegistry());
+    return provider ? { ...provider, kind: 'provider' } : null;
+}
+function assertUniqueUnifiedName(name, meta, doc) {
+    if (findUnifiedAccount(name, meta, doc))
+        throw new Error(`Account '${name}' already exists.`);
+}
+export function addNativeAccount(name, agent, identityKey, identityLabel, scope) {
+    assertName(name);
+    const meta = readMeta();
+    assertUniqueUnifiedName(name, meta);
+    const duplicate = listNativeAccounts(meta).find(account => account.agent === agent && account.identityKey === identityKey);
+    if (duplicate)
+        throw new Error(`This ${agent} login is already named '${duplicate.name}'.`);
+    const account = { id: crypto.randomUUID(), name, kind: 'native', agent, identityKey, identityLabel, scope };
+    updateMeta(current => ({
+        ...current,
+        accounts: {
+            ...current.accounts,
+            native: { ...current.accounts?.native, [account.id]: { id: account.id, name, agent, identityKey, identityLabel, scope } },
+        },
+    }));
+    return account;
+}
+export function bindAccount(nameOrId, target) {
+    const meta = readMeta();
+    const account = findUnifiedAccount(nameOrId, meta);
+    if (!account)
+        throw new Error(`Unknown account '${nameOrId}'.`);
+    updateMeta(current => ({
+        ...current,
+        accounts: { ...current.accounts, bindings: { ...current.accounts?.bindings, [target]: account.id } },
+    }));
+    return account;
+}
+export function unbindAccount(nameOrId, target) {
+    const meta = readMeta();
+    const account = findUnifiedAccount(nameOrId, meta);
+    if (!account)
+        throw new Error(`Unknown account '${nameOrId}'.`);
+    if (meta.accounts?.bindings?.[target] !== account.id)
+        throw new Error(`Account '${account.name}' is not attached to '${target}'.`);
+    updateMeta(current => {
+        const bindings = { ...current.accounts?.bindings };
+        delete bindings[target];
+        return { ...current, accounts: { ...current.accounts, bindings } };
+    });
+}
+export function accountBindings(accountId, meta) {
+    return Object.entries(meta.accounts?.bindings ?? {}).filter(([, id]) => id === accountId).map(([target]) => target).sort();
+}
 /** Explicit selection wins over a configured per-harness default. */
 export function resolveAccountSelection(explicit, agent, meta, opts = {}) {
     if (explicit)
         return explicit;
+    const bound = opts.target ? meta.accounts?.bindings?.[opts.target] : undefined;
+    if (bound)
+        return bound;
+    const deviceScoped = meta.accounts?.bindings?.[agent];
+    if (deviceScoped)
+        return deviceScoped;
     return opts.useDefault === false ? undefined : meta.accounts?.defaults?.[agent];
 }
 function profileConsumers(name, base) {
@@ -158,12 +233,11 @@ function renameProfileConsumers(oldName, newName, base) {
 }
 export function addAccount(name, provider, auth, secret, base = getUserAgentsDir(), opts = {}) {
     assertName(name);
+    assertUniqueUnifiedName(name, readMeta(), readAccountRegistry(base));
     const adapter = getAccountProvider(provider);
     adapter.validate(auth, secret);
     if (bundleExists(name))
         throw new Error(`Secrets bundle '${name}' already exists. Choose a different account name.`);
-    if (findAccount(name, readAccountRegistry(base)))
-        throw new Error(`Account '${name}' already exists.`);
     const record = { id: crypto.randomUUID(), name, provider: adapter.provider, auth, baseUrl: opts.baseUrl };
     const { bundle, items } = buildAccountBundle(record, secret);
     writeBundleWithItems(bundle, items);
@@ -182,18 +256,49 @@ export function setAccountSecret(name, secret, base = getUserAgentsDir()) {
 export function renameAccount(oldName, newName, base = getUserAgentsDir()) {
     assertName(newName);
     const doc = readAccountRegistry(base);
+    const meta = readMeta();
+    const native = listNativeAccounts(meta).find(account => account.id === oldName || account.name === oldName);
+    if (native) {
+        assertUniqueUnifiedName(newName, meta, doc);
+        updateMeta(current => ({
+            ...current,
+            accounts: {
+                ...current.accounts,
+                native: { ...current.accounts?.native, [native.id]: { ...current.accounts?.native?.[native.id], name: newName } },
+            },
+        }));
+        return;
+    }
     const account = findAccount(oldName, doc);
     if (!account)
         throw new Error(`Unknown account '${oldName}'.`);
-    if (findAccount(newName, doc))
-        throw new Error(`Account '${newName}' already exists.`);
+    assertUniqueUnifiedName(newName, meta, doc);
     renameBundle(account.name, newName); // moves metadata + secret, preserves ACCOUNT_ID
     renameProfileConsumers(account.name, newName, base);
 }
 export function removeAccount(name, base = getUserAgentsDir()) {
+    const meta = readMeta();
+    const native = listNativeAccounts(meta).find(account => account.id === name || account.name === name);
+    if (native) {
+        const bindings = accountBindings(native.id, meta);
+        if (bindings.length)
+            throw new Error(`Account '${native.name}' is attached to: ${bindings.join(', ')}. Detach it before removing it.`);
+        updateMeta(current => {
+            const accounts = { ...current.accounts?.native };
+            delete accounts[native.id];
+            return { ...current, accounts: { ...current.accounts, native: accounts } };
+        });
+        return;
+    }
     const account = findAccount(name, readAccountRegistry(base));
     if (!account)
         throw new Error(`Unknown account '${name}'.`);
+    const bindings = accountBindings(account.id, meta);
+    const defaults = Object.entries(meta.accounts?.defaults ?? {}).filter(([, id]) => id === account.id).map(([agent]) => agent);
+    if (bindings.length || defaults.length) {
+        const refs = [...bindings.map(target => `binding ${target}`), ...defaults.map(agent => `default ${agent}`)];
+        throw new Error(`Account '${account.name}' is still referenced by: ${refs.join(', ')}. Detach or clear those references before removing it.`);
+    }
     const consumers = [...new Set([...profileConsumers(account.name, base), ...profileConsumers(account.id, base)])].sort();
     if (consumers.length)
         throw new Error(`Account '${account.name}' is used by harness${consumers.length === 1 ? '' : 'es'}: ${consumers.join(', ')}. Reassign them before removing it.`);
@@ -237,3 +342,44 @@ export function resolveCredentialAccount(name, host, expectedProvider, base = ge
         env: { ...connectionEnv, [envVar]: getKeychainToken(account.secretRef) },
     };
 }
+/**
+ * Resolve the account a run should launch under, following the binding order
+ * (explicit → exact `agent@version` → device-scoped `agent` → per-harness
+ * default) and classifying the result:
+ *
+ * - **provider** → the injected env is resolved here (fails closed when the
+ *   credential is absent or the provider cannot authenticate the host).
+ * - **native** → returns the identity the caller must confirm is live on the
+ *   execution device; **no secret or env is produced**, because a native login
+ *   is owned by the harness and read from its own home. The caller validates the
+ *   live fingerprint against the installed version before spawn.
+ *
+ * A native account bound to a different harness than the one being launched
+ * fails loudly (EXEC-ACCOUNT-4). Returns null when nothing is selected.
+ */
+export function resolveSpawnAccount(explicit, agent, version, meta, opts = {}) {
+    // The binding lookup key. A custom harness passes its own profile/harness name
+    // (a run of `deepseek` must find a binding on `deepseek`, not `claude@x`); a
+    // native/global run keys on the exact `agent@version` installation.
+    const target = opts.target ?? (version ? `${agent}@${version}` : agent);
+    const selection = resolveAccountSelection(explicit, agent, meta, { useDefault: opts.useDefault, target });
+    if (!selection)
+        return null;
+    const unified = findUnifiedAccount(selection, meta);
+    if (!unified)
+        throw new Error(`Unknown account '${selection}'.`);
+    if (unified.kind === 'native') {
+        if (unified.agent !== agent) {
+            throw new Error(`Account '${unified.name}' is a ${unified.agent} login and cannot authenticate the ${agent} harness.`);
+        }
+        // A provider-backed custom harness still injects its provider auth env, so a
+        // native identity claim over it is incoherent — reject before spawn even when
+        // the account is chosen explicitly with --account (which bypasses `attach`).
+        if (opts.provider) {
+            throw new Error(`Account '${unified.name}' is a native ${unified.agent} login and cannot run under a provider-backed harness (${opts.provider}); the harness's ${opts.provider} credentials would still be injected. Use a matching provider account.`);
+        }
+        return { kind: 'native', id: unified.id, name: unified.name, agent, identityKey: unified.identityKey, scope: unified.scope };
+    }
+    const resolved = resolveCredentialAccount(unified.name, agent, opts.provider, opts.base ?? getUserAgentsDir());
+    return { kind: 'provider', id: resolved.id, name: resolved.name, agent, env: resolved.env };
+}

package/dist/lib/{rotate.d.ts → accounting/rotate.d.ts}

@@ -4,11 +4,11 @@
  * Detects which installed versions have expired credentials and rotates
  * authentication tokens so users maintain active sessions across version switches.
  */
-import type { AgentId, RunStrategy } from './types.js';
-import type { FallbackEntry } from './exec.js';
-import { type AccountInfo, type CredentialPresence } from './agents.js';
+import type { AgentId, RunStrategy } from '../types.js';
+import type { FallbackEntry } from '../exec.js';
+import { type AccountInfo, type CredentialPresence } from '../agents.js';
 import { type UsageSnapshot } from './usage.js';
-import { type AuthVerdict } from './auth-health.js';
+import { type AuthVerdict } from '../auth-health.js';
 export interface RotateCandidate {
     agent: AgentId;
     version: string;

package/dist/lib/{rotate.js → accounting/rotate.js}

@@ -6,15 +6,15 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { accountDisplayLabel, getAccountInfo, credentialPresence, ALL_AGENT_IDS, } from './agents.js';
-import { readMeta, writeMeta, getHelpersDir } from './state.js';
-import { listInstalledVersions, getVersionHomePath, resolveVersion } from './versions.js';
-import { getProjectRunConfigs } from './run-config.js';
-import { emit } from './events.js';
+import { accountDisplayLabel, getAccountInfo, credentialPresence, ALL_AGENT_IDS, } from '../agents.js';
+import { readMeta, writeMeta, getHelpersDir } from '../state.js';
+import { listInstalledVersions, getVersionHomePath, resolveVersion } from '../installations/versions.js';
+import { getProjectRunConfigs } from '../run-config.js';
+import { emit } from '../feed/events.js';
 import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
-import { readAccountHeadroom } from './fleet-cache.js';
-import { machineId } from './machine-id.js';
-import { readAuthHealthCache, authCacheKey, isDeadVerdict } from './auth-health.js';
+import { readAccountHeadroom } from '../fleet-cache.js';
+import { machineId } from '../machine-id.js';
+import { readAuthHealthCache, authCacheKey, isDeadVerdict } from '../auth-health.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });

package/dist/lib/{usage.d.ts → accounting/usage.d.ts}

@@ -1,5 +1,5 @@
-import { type AccountInfo } from './agents.js';
-import type { AgentId } from './types.js';
+import { type AccountInfo } from '../agents.js';
+import type { AgentId } from '../types.js';
 /**
  * Why a usage read produced no snapshot, when the cause is the credential or the
  * server rather than the payload. Every provider used to return `error: null`
@@ -460,14 +460,14 @@ export declare function normalizeDroidWindows(data: DroidBillingLimitsResponse):
  *  1. The OS keychain (`getKeychainToken`). Canonical on macOS — Claude Code
  *     writes the token to the login keychain and we read it via `/usr/bin/security`.
  *  2. `<home>/.claude/.credentials.json`. On a headless Linux box (the
- *     `agents view --host <linux>` case) there is no reachable Secret Service, so
+ *     `agents view --device <linux>` case) there is no reachable Secret Service, so
  *     the Claude CLI stores its OAuth token in this plaintext file instead. The
  *     keychain read above finds nothing on that platform, so we fall back to the
  *     file. Same wrapped `{ claudeAiOauth }` shape, so one parser handles both.
  *     Mirrors `readClaudeCredentialsBlob` (cloud/rush.ts), the proven pattern.
  *
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
- * (run remotely over SSH by `--host`) rendered no usage bars even though the
+ * (run remotely over SSH by `--device`) rendered no usage bars even though the
  * account + plan — read from the plaintext `.claude.json` — showed fine.
  *
  * `opts.accessTokenCache` marks a read-only, access-token-only consumer (the

package/dist/lib/{usage.js → accounting/usage.js}

@@ -17,15 +17,15 @@ import * as path from 'path';
 import * as readline from 'readline';
 import { promisify } from 'util';
 import chalk from 'chalk';
-import { decodeJwtPayload, decryptDroidAuthPayload } from './agents.js';
-import { walkForFiles } from './fs-walk.js';
-import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden, } from './secrets/index.js';
-import { resolveClaudeSetupToken } from './claude-account-token.js';
-import { formatBackoffRemaining, noteUsageRateLimited, usageRateLimitedUntil, } from './usage-backoff.js';
-import { getCacheDir } from './state.js';
-import { mapBounded } from './concurrency.js';
-import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
-import { withRefreshLease } from './refresh-coordinator.js';
+import { decodeJwtPayload, decryptDroidAuthPayload } from '../agents.js';
+import { walkForFiles } from '../fs-walk.js';
+import { getKeychainToken, setKeychainToken, deleteKeychainToken, isKeychainBackendOverridden, } from '../secrets/index.js';
+import { resolveClaudeSetupToken } from '../claude-account-token.js';
+import { formatBackoffRemaining, noteUsageRateLimited, usageRateLimitedUntil, } from '../usage-backoff.js';
+import { getCacheDir } from '../state.js';
+import { mapBounded } from '../concurrency.js';
+import { atomicWriteFileSync, ensureLockTarget, withFileLock } from '../fs-atomic.js';
+import { withRefreshLease } from '../refresh-coordinator.js';
 const execFileAsync = promisify(execFile);
 const CLAUDE_USAGE_URL = 'https://api.anthropic.com/api/oauth/usage';
 const CLAUDE_TOKEN_URL = 'https://platform.claude.com/v1/oauth/token';
@@ -1282,14 +1282,14 @@ function deleteCachedClaudeOauth(service) {
  *  1. The OS keychain (`getKeychainToken`). Canonical on macOS — Claude Code
  *     writes the token to the login keychain and we read it via `/usr/bin/security`.
  *  2. `<home>/.claude/.credentials.json`. On a headless Linux box (the
- *     `agents view --host <linux>` case) there is no reachable Secret Service, so
+ *     `agents view --device <linux>` case) there is no reachable Secret Service, so
  *     the Claude CLI stores its OAuth token in this plaintext file instead. The
  *     keychain read above finds nothing on that platform, so we fall back to the
  *     file. Same wrapped `{ claudeAiOauth }` shape, so one parser handles both.
  *     Mirrors `readClaudeCredentialsBlob` (cloud/rush.ts), the proven pattern.
  *
  * Without step 2 the live usage fetch got no token on Linux, so `agents view`
- * (run remotely over SSH by `--host`) rendered no usage bars even though the
+ * (run remotely over SSH by `--device`) rendered no usage bars even though the
  * account + plan — read from the plaintext `.claude.json` — showed fine.
  *
  * `opts.accessTokenCache` marks a read-only, access-token-only consumer (the

package/dist/lib/agent-spec/provider.js

@@ -1,6 +1,6 @@
 // The production VersionProvider: the only fs/meta-coupled file in the engine.
 // Everything else in this module is pure and testable without it.
-import { listInstalledVersions, getGlobalDefault, getIsolatedDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
+import { listInstalledVersions, getGlobalDefault, getIsolatedDefault, getProjectVersion, isVersionInstalled, } from '../installations/versions.js';
 export const defaultVersionProvider = {
     listInstalled: (agent) => listInstalledVersions(agent),
     getProjectVersion: (agent, cwd) => getProjectVersion(agent, cwd),