@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/commands/accounts.d.ts

@@ -1,13 +1,6 @@
 import type { Command } from 'commander';
-import type { AgentId } from '../lib/types.js';
-import { listInstalledVersions } from '../lib/versions.js';
-import { discoverAccounts } from '../lib/account-labels.js';
-export declare function fingerprintFromSource(raw: string, deps?: {
-    installedVersions?: typeof listInstalledVersions;
-    discover?: typeof discoverAccounts;
-}): Promise<{
-    agent: AgentId;
-    fingerprint: string;
-    versions: string[];
-}>;
+export declare function parseBundleKey(raw: string): {
+    bundle: string;
+    key: string;
+};
 export declare function registerAccountsCommand(program: Command): void;

package/dist/commands/accounts.js

@@ -1,32 +1,164 @@
 import chalk from 'chalk';
-import { select } from '@inquirer/prompts';
-import { resolveAgentName, formatAgentError } from '../lib/agents.js';
-import { listInstalledVersions } from '../lib/versions.js';
-import { discoverAccounts, nameAccount, removeAccountLabel, renameAccountLabel } from '../lib/account-labels.js';
+import { password } from '@inquirer/prompts';
 import { setHelpSections } from '../lib/help.js';
-function parseSource(raw) { const at = raw.lastIndexOf('@'); if (at < 1 || at === raw.length - 1)
-    throw new Error(`Expected <agent>@<version>, got '${raw}'.`); const name = raw.slice(0, at); const agent = resolveAgentName(name); if (!agent)
-    throw new Error(formatAgentError(name)); return { agent, version: raw.slice(at + 1) }; }
-export async function fingerprintFromSource(raw, deps = {}) {
-    const { agent, version } = parseSource(raw);
-    if (!(deps.installedVersions ?? listInstalledVersions)(agent).includes(version))
-        throw new Error(`${raw} is not installed.`);
-    const account = (await (deps.discover ?? discoverAccounts)([agent])).find(candidate => candidate.versions.includes(version));
-    if (!account)
-        throw new Error(`${raw} has no stable signed-in account. Run it and complete its normal login first.`);
-    return { agent, fingerprint: account.fingerprint, versions: account.versions };
+import { updateMeta } from '../lib/state.js';
+import { ALL_AGENT_IDS } from '../lib/agents.js';
+import { pushBundleToHost } from '../lib/secrets/push.js';
+import { resolveRemoteOsSync } from '../lib/hosts/remote-os.js';
+import { runDevicesAccounts } from './ssh.js';
+import { discoverNativeAccounts } from '../lib/account-catalog.js';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { getAccountProvider, listAccountProviders } from '../lib/account-provider-registry.js';
+import { addAccount, findAccount, inspectAccount, readAccountRegistry, removeAccount, renameAccount, setAccountSecret } from '../lib/account-registry.js';
+export function parseBundleKey(raw) {
+    const colon = raw.indexOf(':');
+    if (colon < 1 || colon === raw.length - 1)
+        throw new Error(`Expected bundle:key, got '${raw}'.`);
+    return { bundle: raw.slice(0, colon), key: raw.slice(colon + 1) };
+}
+function secretFromBundle(raw) {
+    const { bundle, key } = parseBundleKey(raw);
+    return readAndResolveBundleEnv(bundle, { keys: [key], keyMode: 'storage', agentOnly: true, caller: 'accounts import' }).env[key];
+}
+function publicAccount(account) {
+    return { kind: 'provider', id: account.id, name: account.name, provider: account.provider, auth: account.auth, baseUrl: account.baseUrl, policy: account.policy, secretPresent: account.secretPresent };
+}
+async function printAccounts(json, fleet = false) {
+    if (fleet)
+        return runDevicesAccounts({ json });
+    const records = Object.values(readAccountRegistry().accounts).sort((a, b) => a.name.localeCompare(b.name));
+    const native = await discoverNativeAccounts();
+    if (json) {
+        console.log(JSON.stringify([...records.map(account => publicAccount(inspectAccount(account.name))), ...native], null, 2));
+        return;
+    }
+    console.log(chalk.bold('Provider account bundles\n'));
+    if (!records.length)
+        console.log(chalk.gray("  None. Add one with 'agents accounts add <name> --provider <provider> --auth <type>'."));
+    for (const account of records) {
+        const present = inspectAccount(account.name).secretPresent ? chalk.green('ready') : chalk.red('missing on this device');
+        console.log(`  ${chalk.cyan(account.name)}  ${account.provider}  ${account.auth}  ${present}`);
+    }
+    console.log(chalk.bold('\nNative harness logins\n'));
+    if (!native.length)
+        console.log(chalk.gray('  No signed-in native accounts found.'));
+    for (const account of native)
+        console.log(`  ${chalk.cyan(account.display)}  ${account.agent}  ${account.versions.join(', ')}`);
+}
+function parseAuth(raw) {
+    if (raw === 'api-key' || raw === 'setup-token' || raw === 'bearer-token')
+        return raw;
+    throw new Error(`Unsupported auth type '${raw}'. Use api-key, setup-token, or bearer-token.`);
 }
-async function printAccounts(json) { const accounts = await discoverAccounts(); if (json)
-    return console.log(JSON.stringify(accounts, null, 2)); if (!accounts.length)
-    return console.log(chalk.gray('No signed-in accounts found. Run an installed agent and complete its normal login first.')); console.log(chalk.bold('Signed-in accounts\n')); for (const account of accounts)
-    console.log(`  ${account.label ? chalk.cyan(account.label) : chalk.gray('(unnamed)')}  ${account.agent}  ${account.display}\n    ${account.versions.length} installed version${account.versions.length === 1 ? '' : 's'}: ${account.versions.join(', ')}`); }
-async function chooseAccount() { const accounts = await discoverAccounts(); if (!accounts.length)
-    throw new Error('No signed-in accounts found. Run an installed agent and complete its normal login first.'); return select({ message: 'Which signed-in account do you want to name?', choices: accounts.map(account => ({ name: `${account.agent}  ${account.display}  (${account.versions.length} version${account.versions.length === 1 ? '' : 's'})${account.label ? `  currently “${account.label}”` : ''}`, value: account })) }); }
 export function registerAccountsCommand(program) {
-    const accounts = program.command('accounts').description('Browse and name signed-in harness accounts').option('--json', 'Machine-readable discovered accounts').action(async (o) => printAccounts(!!o.json));
-    accounts.command('list').description('Alias for accounts').option('--json', 'Machine-readable discovered accounts').action((o) => printAccounts(!!o.json));
-    accounts.command('name <label>').description('Name one signed-in account; matching installed versions are found automatically').option('--from <agent@version>', 'Non-interactive identity source').action(async (label, o) => { const picked = o.from ? await fingerprintFromSource(o.from) : await chooseAccount(); nameAccount(label, picked.agent, picked.fingerprint); console.log(chalk.green(`Named the ${picked.agent} account '${label}'.`)); console.log(chalk.gray(`Found it in ${picked.versions.length} installed version${picked.versions.length === 1 ? '' : 's'}: ${picked.versions.join(', ')}`)); });
-    accounts.command('rename <old> <new>').description('Rename a saved account label').action((oldLabel, newLabel) => renameAccountLabel(oldLabel, newLabel));
-    accounts.command('remove <label>').description('Remove a saved account label').action((label) => removeAccountLabel(label));
-    setHelpSections(accounts, { examples: `agents accounts\nagents accounts name work\nagents accounts name work --from claude@2.1.220\nagents run claude --account work`, notes: 'First run the harness and complete its normal login. A label names one provider account; every matching installed version is discovered automatically. OAuth credentials are never copied or shared.' });
+    const accounts = program.command('accounts').description('Browse native logins and manage provider account bundles')
+        .option('--json', 'Machine-readable account metadata')
+        .option('--fleet', 'Show harness-native signed-in identities across reachable devices')
+        .action((o) => printAccounts(!!o.json, !!o.fleet));
+    accounts.command('list').description('List credential accounts').option('--json', 'Machine-readable account metadata').action((o, command) => printAccounts(!!(o.json || command.optsWithGlobals().json)));
+    accounts.command('add <name>')
+        .description('Add a durable API key, setup token, or bearer token')
+        .requiredOption('--provider <provider>', `Credential provider (${listAccountProviders().join(', ')})`)
+        .requiredOption('--auth <type>', 'Credential type: api-key | setup-token | bearer-token')
+        .option('--base-url <url>', 'Optional endpoint override stored with the account')
+        .option('--from-secrets <bundle:key>', 'Import from an existing agents secrets entry')
+        .action(async (name, o) => {
+        const auth = parseAuth(o.auth);
+        const provider = getAccountProvider(o.provider);
+        if (!provider.authKinds.includes(auth))
+            throw new Error(`Provider '${provider.provider}' does not support ${auth}. Supported: ${provider.authKinds.join(', ')}.`);
+        const secret = o.fromSecrets ? secretFromBundle(o.fromSecrets) : await password({ message: `Enter ${provider.provider} ${auth} for '${name}':` });
+        const account = addAccount(name, provider.provider, auth, secret, undefined, { baseUrl: o.baseUrl });
+        console.log(chalk.green(`Added ${account.provider} ${account.auth} account '${account.name}'.`));
+        console.log(chalk.gray(`Secret bundle '${account.name}' is the account and uses policy never, so agent launches never request Touch ID.`));
+    });
+    accounts.command('set-key <name>')
+        .description('Rotate an account credential without changing its identity')
+        .option('--from-secrets <bundle:key>', 'Import from an existing agents secrets entry')
+        .action(async (name, o) => {
+        const account = findAccount(name);
+        if (!account)
+            throw new Error(`Unknown account '${name}'.`);
+        const secret = o.fromSecrets ? secretFromBundle(o.fromSecrets) : await password({ message: `Enter new ${account.provider} ${account.auth} for '${name}':` });
+        setAccountSecret(name, secret);
+        console.log(chalk.green(`Updated credential for account '${name}'.`));
+    });
+    accounts.command('inspect <name>').description('Show safe account metadata').option('--json', 'Machine-readable output').action((name, o, command) => {
+        const account = publicAccount(inspectAccount(name));
+        if (o.json || command.optsWithGlobals().json)
+            return console.log(JSON.stringify(account, null, 2));
+        console.log(`${chalk.bold(account.name)}  ${account.provider}`);
+        console.log(`  auth: ${account.auth}`);
+        console.log(`  id: ${account.id}`);
+        console.log(`  policy: ${account.policy}`);
+        if (account.baseUrl)
+            console.log(`  base url: ${account.baseUrl}`);
+        console.log(`  credential: ${account.secretPresent ? 'present on this device' : 'missing on this device'}`);
+    });
+    accounts.command('rename <old> <new>').description('Rename an account without changing its stable id').action((oldName, newName) => renameAccount(oldName, newName));
+    accounts.command('remove <name>').description('Remove an account and its device-local credential').action((name) => removeAccount(name));
+    accounts.command('set-default <agent> <name>')
+        .description('Use a provider account for a harness when --account is omitted')
+        .action((agentRaw, name) => {
+        if (!ALL_AGENT_IDS.includes(agentRaw))
+            throw new Error(`Unknown agent '${agentRaw}'.`);
+        const agent = agentRaw;
+        const account = findAccount(name);
+        if (!account)
+            throw new Error(`Unknown provider account '${name}'.`);
+        getAccountProvider(account.provider).envFor(agent, account.auth);
+        // Defaults follow the stable account id, so renaming the bundle cannot
+        // strand bare runs on a deleted label. findAccount accepts ids and names.
+        updateMeta(meta => ({ ...meta, accounts: { ...meta.accounts, defaults: { ...meta.accounts?.defaults, [agent]: account.id } } }));
+        console.log(chalk.green(`${agent} now uses account '${account.name}' unless --account overrides it.`));
+    });
+    accounts.command('clear-default <agent>')
+        .description('Return a harness to native login or balanced account selection')
+        .action((agentRaw) => {
+        if (!ALL_AGENT_IDS.includes(agentRaw))
+            throw new Error(`Unknown agent '${agentRaw}'.`);
+        updateMeta(meta => {
+            const defaults = { ...meta.accounts?.defaults };
+            delete defaults[agentRaw];
+            return { ...meta, accounts: { ...meta.accounts, defaults } };
+        });
+        console.log(chalk.green(`Cleared the default account for ${agentRaw}.`));
+    });
+    accounts.command('sync <name>')
+        .description('Copy one provider account bundle to a worker device')
+        .requiredOption('--device <device>', 'Destination device or SSH host')
+        .option('--force', 'Replace matching keys on the destination')
+        .action((name, o) => {
+        const account = findAccount(name);
+        if (!account)
+            throw new Error(`Unknown provider account '${name}'.`);
+        const remoteBackend = resolveRemoteOsSync(o.device) === 'win32' ? 'keychain' : 'file';
+        const literalValues = {
+            ACCOUNT_ID: account.id,
+            PROVIDER: account.provider,
+            AUTH_TYPE: account.auth,
+            ...(account.baseUrl ? { BASE_URL: account.baseUrl } : {}),
+        };
+        const result = pushBundleToHost(account.name, o.device, {
+            remoteBackend,
+            force: o.force,
+            operation: 'accounts sync',
+            policyNever: true,
+            agentOnly: false,
+            literalValues,
+        });
+        if (!result.ok)
+            throw new Error(`${result.message}\nRetry: agents accounts sync ${account.name} --device ${o.device}${o.force ? ' --force' : ''}`);
+        console.log(chalk.green(`${account.name} synced to ${o.device} (${result.keyCount} keys, ${remoteBackend} backend, policy never).`));
+    });
+    setHelpSections(accounts, {
+        examples: `agents accounts add work --provider anthropic --auth setup-token
+agents accounts add openrouter-work --provider openrouter --auth api-key --from-secrets openrouter.ai:OPENROUTER_API_KEY
+agents accounts set-key work
+agents accounts inspect work --json
+agents accounts set-default claude work
+agents accounts sync work --device yosemite-s0
+agents run claude --account work`,
+        notes: 'Provider accounts are durable credentials independent of agent versions. Harness-native auth remains managed by each harness and is not copied or renamed by agents-cli.',
+    });
 }

package/dist/commands/artifacts-setup.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `agents artifacts setup` — configure the artifact share endpoint (Cloudflare
+ * R2 + Worker) that backs `agents artifacts share`.
+ *
+ * One door, two modes, because it replaces two commands that used to be
+ * separate (RUSH-2580): the interactive wizard formerly at `agents setup share`
+ * and the flag-driven provisioner formerly at `agents share setup`. On a TTY
+ * with no provisioning flags TYPED it runs the wizard (provision or join, and
+ * offers a Worker update when an endpoint already exists); with any provisioning
+ * flag typed, or on a non-TTY, it provisions directly. Both modes call the same
+ * `runShareProvision` / `runShareJoin` in commands/share.ts, so there is a
+ * single source of truth for provisioning.
+ *
+ * "Typed", not "present", is load-bearing — see {@link isDirectProvisionRequest}.
+ *
+ * Idempotent: re-running shows the current endpoint and offers to reconfigure.
+ */
+import type { Command } from 'commander';
+/**
+ * Interactive share setup. Returns true if the user configured (or already had)
+ * an endpoint, false if they skipped. Never throws on user cancel — callers
+ * (the `agents setup` hub) rely on that to keep the fresh-machine flow going.
+ */
+export declare function runShareWizard(): Promise<boolean>;
+/** Parsed `agents artifacts setup` options — the retired `agents share setup` flag set. */
+interface ArtifactsSetupOpts {
+    bundle: string;
+    worker: string;
+    bucket: string;
+    account?: string;
+    token?: string;
+    domain?: string;
+    analyticsToken?: string;
+}
+/** The provisioning flags, by their commander option-value keys. */
+declare const PROVISION_FLAGS: readonly ["bundle", "worker", "bucket", "account", "token", "domain", "analyticsToken"];
+/**
+ * True when the invocation named a Cloudflare endpoint detail, i.e. the caller
+ * is driving the old `agents share setup` provisioning path rather than asking
+ * for the wizard.
+ *
+ * `--bundle`/`--worker`/`--bucket` carry commander defaults, so their mere
+ * PRESENCE proves nothing — the question is whether the user typed them, which
+ * only `wasTyped` (backed by commander's `getOptionValueSource`) can answer.
+ * Reading presence alone would classify `agents artifacts setup --bundle
+ * cloudflare-work` as a wizard run and then silently provision against the
+ * DEFAULT bundle, i.e. someone else's Cloudflare account. The other four flags
+ * have no default, so presence is proof for them.
+ */
+export declare function isDirectProvisionRequest(opts: ArtifactsSetupOpts, wasTyped?: (flag: (typeof PROVISION_FLAGS)[number]) => boolean): boolean;
+/** Register `agents artifacts setup` under the parent `artifacts` command. */
+export declare function registerArtifactsSetupCommand(artifactsCmd: Command): void;
+export {};

package/dist/commands/artifacts-setup.js

@@ -0,0 +1,161 @@
+/**
+ * `agents artifacts setup` — configure the artifact share endpoint (Cloudflare
+ * R2 + Worker) that backs `agents artifacts share`.
+ *
+ * One door, two modes, because it replaces two commands that used to be
+ * separate (RUSH-2580): the interactive wizard formerly at `agents setup share`
+ * and the flag-driven provisioner formerly at `agents share setup`. On a TTY
+ * with no provisioning flags TYPED it runs the wizard (provision or join, and
+ * offers a Worker update when an endpoint already exists); with any provisioning
+ * flag typed, or on a non-TTY, it provisions directly. Both modes call the same
+ * `runShareProvision` / `runShareJoin` in commands/share.ts, so there is a
+ * single source of truth for provisioning.
+ *
+ * "Typed", not "present", is load-bearing — see {@link isDirectProvisionRequest}.
+ *
+ * Idempotent: re-running shows the current endpoint and offers to reconfigure.
+ */
+import chalk from 'chalk';
+import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, readShareConfig, } from '../lib/share/config.js';
+import { runShareProvision, runShareJoin, runShareUpdate, shareTemplateStatus } from './share.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/**
+ * Interactive share setup. Returns true if the user configured (or already had)
+ * an endpoint, false if they skipped. Never throws on user cancel — callers
+ * (the `agents setup` hub) rely on that to keep the fresh-machine flow going.
+ */
+export async function runShareWizard() {
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('The artifact share wizard needs an interactive terminal. ' +
+            'Non-interactively, use `agents artifacts setup --account <id> --token <t>` (provision) ' +
+            'or `agents artifacts share join <baseUrl> --token <t>`.'));
+        return false;
+    }
+    const existing = readShareConfig();
+    if (existing) {
+        console.log(chalk.dim(`Share is already configured → ${chalk.green(existing.baseUrl)}`));
+        console.log(chalk.dim(`  worker ${existing.workerName} · bucket ${existing.bucketName} · account ${existing.accountId}`));
+        const templateStatus = shareTemplateStatus(existing);
+        console.log(chalk.dim(`  template ${templateStatus}`));
+        const { select } = await import('@inquirer/prompts');
+        const action = await select({
+            message: 'Share is already configured. What do you want to do?',
+            choices: [
+                { name: 'Keep as is', value: 'keep' },
+                {
+                    name: 'Update the deployed Worker to the latest template',
+                    value: 'update',
+                    description: templateStatus === 'current'
+                        ? 'Already current — this re-deploys anyway and refreshes the token in place.'
+                        : 'Re-deploys the Worker script on your existing endpoint (same account/worker/bucket, same write token).',
+                },
+                {
+                    name: 'Reconfigure from scratch (provision or join again)',
+                    value: 'reconfigure',
+                },
+            ],
+            default: templateStatus === 'outdated' || templateStatus === 'unknown' ? 'update' : 'keep',
+        });
+        if (action === 'keep') {
+            console.log(chalk.dim('Keeping the current endpoint.'));
+            return true;
+        }
+        if (action === 'update') {
+            // When the template is already current, the description below promises a
+            // re-deploy anyway — force it, or runShareUpdate's own no-op would silently
+            // contradict what was just said.
+            const result = await runShareUpdate({ force: templateStatus === 'current' });
+            console.log(result.updated
+                ? chalk.green(`Worker '${result.workerName}' updated → template ${result.templateHash.slice(0, 12)}…`)
+                : chalk.dim(`Worker '${result.workerName}' already matches the current template — no-op.`));
+            return true;
+        }
+        // action === 'reconfigure' — fall through to the provision/join flow below.
+    }
+    const { select } = await import('@inquirer/prompts');
+    const mode = await select({
+        message: 'How do you want to publish shared links?',
+        choices: [
+            {
+                name: 'Provision my own (Cloudflare R2 + Worker)',
+                value: 'provision',
+                description: 'One-time: creates a bucket + Worker on your Cloudflare account (~$0). Needs a Cloudflare API token.',
+            },
+            {
+                name: 'Join an existing endpoint (a teammate already provisioned one)',
+                value: 'join',
+                description: 'Use synced config when present, or paste the base URL + write token from the endpoint owner.',
+            },
+        ],
+    });
+    if (mode === 'provision') {
+        await runShareProvision({
+            bundle: DEFAULT_CF_BUNDLE,
+            worker: DEFAULT_WORKER_NAME,
+            bucket: DEFAULT_BUCKET_NAME,
+        });
+        return true;
+    }
+    const { input } = await import('@inquirer/prompts');
+    const baseUrl = await input({
+        message: 'Endpoint base URL (e.g. https://share.agents-cli.sh)',
+        validate: (v) => (v.trim().startsWith('http') ? true : 'Enter the full https:// URL of the endpoint.'),
+    });
+    await runShareJoin(baseUrl.trim());
+    return true;
+}
+/** The provisioning flags, by their commander option-value keys. */
+const PROVISION_FLAGS = ['bundle', 'worker', 'bucket', 'account', 'token', 'domain', 'analyticsToken'];
+/**
+ * True when the invocation named a Cloudflare endpoint detail, i.e. the caller
+ * is driving the old `agents share setup` provisioning path rather than asking
+ * for the wizard.
+ *
+ * `--bundle`/`--worker`/`--bucket` carry commander defaults, so their mere
+ * PRESENCE proves nothing — the question is whether the user typed them, which
+ * only `wasTyped` (backed by commander's `getOptionValueSource`) can answer.
+ * Reading presence alone would classify `agents artifacts setup --bundle
+ * cloudflare-work` as a wizard run and then silently provision against the
+ * DEFAULT bundle, i.e. someone else's Cloudflare account. The other four flags
+ * have no default, so presence is proof for them.
+ */
+export function isDirectProvisionRequest(opts, wasTyped = () => false) {
+    if (opts.account || opts.token || opts.domain || opts.analyticsToken)
+        return true;
+    return PROVISION_FLAGS.some((flag) => wasTyped(flag));
+}
+/** Register `agents artifacts setup` under the parent `artifacts` command. */
+export function registerArtifactsSetupCommand(artifactsCmd) {
+    artifactsCmd
+        .command('setup')
+        .description('Provision (or join) the Cloudflare R2 + Worker endpoint that backs `agents artifacts share`.')
+        .option('--bundle <name>', 'secrets bundle holding the Cloudflare API token', DEFAULT_CF_BUNDLE)
+        .option('--worker <name>', 'Worker name', DEFAULT_WORKER_NAME)
+        .option('--bucket <name>', 'R2 bucket name', DEFAULT_BUCKET_NAME)
+        .option('--account <id>', 'Cloudflare account id (else read from the bundle / prompt)')
+        .option('--token <t>', 'Cloudflare API token (else read from the --bundle)')
+        .option('--domain <host>', `custom domain to map (default: ${DEFAULT_SHARE_DOMAIN}; workers.dev if zone is not visible)`)
+        .option('--analytics-token <token>', 'Cloudflare Web Analytics token to inject into published HTML pages')
+        .action(async (opts, cmd) => {
+        try {
+            // Named endpoint details, or no terminal to prompt on, means provision
+            // directly — the wizard has nothing to ask that was not already given,
+            // and it would provision against its own hardcoded defaults, dropping
+            // whatever the caller named.
+            const wasTyped = (flag) => cmd.getOptionValueSource(flag) === 'cli';
+            if (isDirectProvisionRequest(opts, wasTyped) || !isInteractiveTerminal()) {
+                await runShareProvision(opts);
+                return;
+            }
+            await runShareWizard();
+        }
+        catch (err) {
+            if (isPromptCancelled(err)) {
+                console.log(chalk.yellow('\nCancelled'));
+                return;
+            }
+            console.error(chalk.red(err.message));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/artifacts.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `agents artifacts` — the group that owns everything an agent publishes for a
+ * human to open: HTML plans, reports, rendered visuals, screenshots.
+ *
+ * RUSH-2580 nested the former top-level `agents share` here. `artifacts` is the
+ * noun, `share` is the action on it, so the surface reads noun-then-action like
+ * the rest of the CLI:
+ *
+ *   agents artifacts share <file>          publish
+ *   agents artifacts share list|delete|analytics|join|status|update
+ *   agents artifacts setup                 provision (or join) the endpoint
+ *
+ * The subtree itself lives in commands/share.ts (publish + its subcommands) and
+ * commands/artifacts-setup.ts (the provisioning door); this module only assembles
+ * the group, so there is one place that says what `agents artifacts` contains.
+ */
+import type { Command } from 'commander';
+export declare function registerArtifactsCommands(program: Command): void;

package/dist/commands/artifacts.js

@@ -0,0 +1,58 @@
+/**
+ * `agents artifacts` — the group that owns everything an agent publishes for a
+ * human to open: HTML plans, reports, rendered visuals, screenshots.
+ *
+ * RUSH-2580 nested the former top-level `agents share` here. `artifacts` is the
+ * noun, `share` is the action on it, so the surface reads noun-then-action like
+ * the rest of the CLI:
+ *
+ *   agents artifacts share <file>          publish
+ *   agents artifacts share list|delete|analytics|join|status|update
+ *   agents artifacts setup                 provision (or join) the endpoint
+ *
+ * The subtree itself lives in commands/share.ts (publish + its subcommands) and
+ * commands/artifacts-setup.ts (the provisioning door); this module only assembles
+ * the group, so there is one place that says what `agents artifacts` contains.
+ */
+import { setHelpSections } from '../lib/help.js';
+import { registerShareCommands, registerUnshareCommand } from './share.js';
+import { registerArtifactsSetupCommand } from './artifacts-setup.js';
+export function registerArtifactsCommands(program) {
+    const artifactsCmd = program
+        .command('artifacts')
+        .description('Publish agent-made artifacts (plans, reports, visuals) to your own Cloudflare R2 and get a shareable link (~$0).');
+    registerArtifactsSetupCommand(artifactsCmd);
+    registerShareCommands(artifactsCmd);
+    setHelpSections(artifactsCmd, {
+        examples: `
+      # One-time: provision your own endpoint (or join a teammate's)
+      agents artifacts setup
+      agents artifacts share join https://share.agents-cli.sh
+
+      # Publish — auto OG cover, default 30d expiry, shareable link
+      agents artifacts share ./out/plan.html
+
+      # What's live in your namespace, and taking one down
+      agents artifacts share list
+      agents unshare my-plan-a1b2
+
+      # Endpoint health, and pushing a new Worker template to it
+      agents artifacts share status
+      agents artifacts share update
+    `,
+        notes: `
+  agents artifacts share is the publish action; agents artifacts setup is the
+  one-time endpoint provisioning. It runs the interactive wizard only when you
+  type NO endpoint flag on a TTY; type any of --bundle/--worker/--bucket/
+  --account/--token/--domain/--analytics-token, or run non-interactively, and it
+  provisions directly with what you named.
+
+  agents unshare <targets...> stays a top-level alias of
+  agents artifacts share delete.
+
+  Full reference: apps/cli/docs/share.md.
+    `,
+    });
+    // Top-level, deliberately: see registerUnshareCommand in commands/share.ts.
+    registerUnshareCommand(program);
+}

package/dist/commands/attach.js

@@ -4,19 +4,32 @@ import { sessionRecoveryPeer } from '../lib/session/recovery.js';
 import { resolveSessionMetadataValue, resumeSessionInPlace } from './sessions.js';
 import { readDetachRecord, clearDetachRecord, isHeadlessAlive } from '../lib/session/detached.js';
 export function registerAttachCommand(program) {
+    // Deprecated: superseded by `agents sessions resume`, which detects the state
+    // (live pane / headless / ended) instead of making the caller pick a verb.
+    // Hidden from help; kept as a warned, functional alias for one release so old
+    // muscle-memory and scripts don't break.
     program
-        .command('attach')
+        .command('attach', { hidden: true })
         .argument('<id>', 'Short or full id of the backgrounded/parked session to resume interactively')
-        .description('Bring a backgrounded agent to the foreground — resume it interactively here')
+        .description('Deprecated — use `agents sessions resume <id>` instead.')
         .action(async (id) => {
+        console.warn(chalk.yellow('`agents sessions attach` is deprecated — use `agents sessions resume` instead:'));
+        console.warn(chalk.gray(`  agents sessions resume ${id}`));
         await attachAction(id);
     });
 }
 export async function attachAction(id) {
     const outcome = await resolveSessionMetadataValue(id);
     if (outcome.kind === 'partial') {
-        console.error(chalk.red(`Could not resolve session while these devices were unavailable: ${outcome.failedPeers.join(', ')}`));
-        process.exitCode = 2;
+        // RUSH-2492: an unreachable peer is a warning, not a hard failure. The
+        // resolver already resolves an id found on the reachable fleet (SES-9a), so
+        // reaching here means the session was not found on any device we COULD reach
+        // — it may live on one of the unreachable peers, which we could not check.
+        const offline = outcome.failedPeers;
+        console.error(chalk.yellow(`Warning: ${offline.length} device(s) unreachable, not checked: ${offline.join(', ')}`));
+        console.error(chalk.red(`No session matching "${id}" on any reachable device (${offline.length} unreachable, not checked).`));
+        console.error(chalk.gray('  If it lives on an offline box, wake it (agents devices) or run there: agents ssh <device>'));
+        process.exitCode = 1;
         return;
     }
     if (outcome.kind === 'not-found') {

package/dist/commands/audit.d.ts

@@ -1,14 +1,14 @@
 /**
- * `agents audit` — inspect the tamper-evident audit log of dispatched runs.
+ * `agents audit` — thin alias of `agents events --include runs`.
  *
- * Every run that reaches the exec dispatch chokepoint appends one hash-chained
- * record (see src/lib/audit/log.ts). This command walks that chain:
+ * New run-dispatch outcomes land in the unified event stream as `run.dispatched`
+ * (see lib/audit/log.ts::recordDispatchedRun). This command does not own a
+ * separate store or query path — it only sets the default family filter.
  *
- *   agents audit verify   Confirm the chain is intact; report the first break.
- *   agents audit list     Print recent records (newest last).
- *
- * `verify` exits non-zero when the chain is broken so it can gate CI / governance
- * checks.
+ *   agents audit              ≡ agents events --include runs
+ *   agents audit list         ≡ same
+ *   agents audit verify       walks the legacy hash-chain file if present
+ *                             (pre-unification history only)
  */
 import type { Command } from 'commander';
 export declare function registerAuditCommands(program: Command): void;