@phnx-labs/agents-cli 1.20.62 → 1.20.64

package/dist/commands/sync-provision.js

@@ -0,0 +1,107 @@
+/**
+ * Interactive provisioning flow for cross-machine session sync. Collects R2
+ * credentials, writes the `r2.backups` bundle (via the pure lib helper), probes
+ * connectivity, and opts the machine into the `session-sync` beta. Shared by
+ * `agents setup` (offered, opt-in) and `agents sessions sync --setup` (explicit).
+ *
+ * The prompt/UI lives here in the command layer; the credential-writing and
+ * connectivity logic is the pure, unit-tested `lib/session/sync/provision.ts`.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { isSyncConfigured } from '../lib/session/sync/config.js';
+import { writeSyncBundle, probeR2Connectivity, readStoredEncKey } from '../lib/session/sync/provision.js';
+import { setBetaEnabled } from '../lib/beta.js';
+const SYNC_BETA = 'session-sync';
+const nonEmpty = (v) => (v.trim().length > 0 ? true : 'required');
+/**
+ * Run the guided session-sync setup. Never throws for expected outcomes
+ * (non-interactive shell, user declines, cancels, or a failed probe) — returns
+ * quietly so a first-run `agents setup` is never blocked by the optional step.
+ */
+export async function promptAndProvisionSessionSync(opts = {}) {
+    if (!isInteractiveTerminal()) {
+        if (opts.explicit)
+            console.error(chalk.red('Session-sync setup needs an interactive terminal.'));
+        return;
+    }
+    const alreadyConfigured = isSyncConfigured();
+    const { confirm, input, password } = await import('@inquirer/prompts');
+    try {
+        if (!opts.explicit) {
+            if (alreadyConfigured)
+                return; // first-run setup: nothing to do
+            const want = await confirm({
+                message: 'Set up cross-machine session sync (encrypted transcripts via Cloudflare R2)?',
+                default: false,
+            });
+            if (!want)
+                return;
+        }
+        else if (alreadyConfigured) {
+            const reconfigure = await confirm({
+                message: 'Session sync is already configured. Re-enter R2 credentials?',
+                default: false,
+            });
+            if (!reconfigure) {
+                const key = readStoredEncKey();
+                if (key) {
+                    console.log(chalk.dim('\nShared encryption key (paste on every other machine you sync):'));
+                    console.log('  ' + chalk.cyan(key));
+                }
+                return;
+            }
+        }
+        console.log(chalk.dim('\nR2 credentials — Cloudflare dashboard > R2 > Manage API Tokens (needs read+write):'));
+        const accountId = (await input({ message: 'R2 account ID:', validate: nonEmpty })).trim();
+        const bucketName = (await input({ message: 'R2 bucket name:', validate: nonEmpty })).trim();
+        const accessKeyId = (await password({ message: 'R2 access key ID:', mask: true })).trim();
+        const secretAccessKey = (await password({ message: 'R2 secret access key:', mask: true })).trim();
+        const endpoint = (await input({
+            message: 'S3 endpoint override (blank = Cloudflare R2):',
+            default: '',
+        })).trim();
+        // Encryption key: the first machine mints one; every other machine pastes it
+        // so the whole fabric shares a single key (and can decrypt each other).
+        const firstMachine = await confirm({ message: 'Is this the FIRST machine in your sync fabric?', default: true });
+        let encKey;
+        if (!firstMachine) {
+            encKey = (await password({
+                message: 'Paste the shared R2_SYNC_ENC_KEY from your first machine:',
+                mask: true,
+                validate: nonEmpty,
+            })).trim();
+        }
+        const { encKeyAction } = writeSyncBundle({
+            accountId, bucketName, accessKeyId, secretAccessKey,
+            endpoint: endpoint || undefined,
+            encKey: encKey || undefined,
+        });
+        const spinner = ora('Validating R2 read+write...').start();
+        const probe = await probeR2Connectivity();
+        if (!probe.ok) {
+            spinner.fail(`R2 probe failed: ${probe.error}`);
+            console.log(chalk.yellow('Credentials were saved to the r2.backups bundle but not verified. Fix them and re-run ' +
+                '`agents sessions sync --setup`, or rotate one key with `agents secrets rotate r2.backups <KEY>`.'));
+            return; // do not auto-enable sync against credentials that don't work
+        }
+        spinner.succeed('R2 read+write verified.');
+        setBetaEnabled([SYNC_BETA], true);
+        console.log(chalk.green('\nSession sync configured and enabled') + chalk.dim(' (the daemon syncs every ~90s).'));
+        if (encKeyAction === 'generated') {
+            const key = readStoredEncKey();
+            console.log(chalk.bold('\nShared encryption key — paste this on every OTHER machine you sync:'));
+            console.log('  ' + chalk.cyan(key ?? '(unavailable)'));
+            console.log(chalk.dim('Anyone with this key can decrypt your transcripts. Keep it secret.'));
+        }
+        console.log(chalk.dim('\nSync now with: agents sessions sync'));
+    }
+    catch (err) {
+        if (isPromptCancelled(err)) {
+            console.log(chalk.yellow('\nSession-sync setup cancelled.'));
+            return;
+        }
+        throw err;
+    }
+}

package/dist/commands/usage.d.ts

@@ -4,6 +4,8 @@
  * Lists every installed agent with the best available usage snapshot:
  *   - claude: live OAuth API call (cached for 2 minutes)
  *   - codex:  parsed from latest session log's rate_limits event
+ *   - kimi:   live Kimi Code /usages API call (cached for 2 minutes)
+ *   - droid:  live Factory billing/limits API call (cached for 2 minutes)
  *   - others: marked as "not exposed by CLI" (Gemini, OpenCode, Cursor, etc.
  *     don't publish per-account usage today)
  */

package/dist/commands/usage.js

@@ -3,8 +3,13 @@ import chalk from 'chalk';
 import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
 import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/versions.js';
 import { formatUsageSection, getUsageInfoForIdentity } from '../lib/usage.js';
-/** Agents whose CLI surfaces usage data we can read today. */
-const USAGE_SUPPORTED = new Set(['claude', 'codex']);
+/**
+ * Agents whose CLI surfaces usage data we can read today. Kept in sync with the
+ * live/last-seen sources `getUsageInfo` dispatches on in `../lib/usage.js`
+ * (claude, codex, kimi, droid) — an agent with a usage source but missing here
+ * would wrongly print "does not publish usage data" for a signed-in account.
+ */
+const USAGE_SUPPORTED = new Set(['claude', 'codex', 'kimi', 'droid']);
 export function registerUsageCommand(program) {
     addHostOption(program.command('usage [agent]'))
         .description('Show rate-limit / quota usage per agent')

package/dist/commands/view.d.ts

@@ -39,7 +39,7 @@ export interface ViewJsonVersion {
         currency: string;
     } | null;
     windows: Array<{
-        key: 'session' | 'week' | 'sonnet_week';
+        key: 'session' | 'week' | 'sonnet_week' | 'month';
         usedPercent: number;
         resetsAt: string | null;
     }>;

package/dist/commands/webhook.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `agents webhook` — localhost receiver for signed public webhook ingress.
+ *
+ * The receiver intentionally binds localhost by default. Public exposure is a
+ * separate `agents funnel up <host>` step so the HTTP process can be tested and
+ * rotated without changing the Tailscale Funnel config.
+ */
+import type { Command } from 'commander';
+export declare function registerWebhookCommand(program: Command): void;

package/dist/commands/webhook.js

@@ -0,0 +1,93 @@
+import chalk from 'chalk';
+import { readAndResolveBundleEnv } from '../lib/secrets/bundles.js';
+import { startWebhookServer } from '../lib/triggers/webhook.js';
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8787;
+function positiveInt(value, fallback) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function readWebhookSecrets(bundleName) {
+    const { env } = readAndResolveBundleEnv(bundleName, {
+        caller: 'webhook serve',
+    });
+    const secrets = {};
+    if (env.GITHUB_WEBHOOK_SECRET)
+        secrets.github = env.GITHUB_WEBHOOK_SECRET;
+    if (env.LINEAR_WEBHOOK_SECRET)
+        secrets.linear = env.LINEAR_WEBHOOK_SECRET;
+    if (!secrets.github && !secrets.linear) {
+        throw new Error(`Bundle '${bundleName}' must contain GITHUB_WEBHOOK_SECRET or LINEAR_WEBHOOK_SECRET.`);
+    }
+    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 registerWebhookCommand(program) {
+    const webhook = program
+        .command('webhook')
+        .description('Run a localhost signed webhook receiver for routine triggers.');
+    webhook
+        .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('-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) => {
+        let secrets;
+        try {
+            secrets = readWebhookSecrets(opts.secretsBundle);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        const port = positiveInt(opts.port, DEFAULT_PORT);
+        const rateLimit = positiveInt(opts.rateLimit, 60);
+        try {
+            const server = startWebhookServer({
+                host: opts.host ?? DEFAULT_HOST,
+                port,
+                secrets,
+                rateLimitPerMinute: rateLimit,
+                onDelivery: (webhook, fired) => {
+                    console.log(`${new Date().toISOString()} ${webhook.source}:${webhook.event} ` +
+                        `${fired.length ? `fired ${fired.map((f) => f.jobName).join(', ')}` : 'no match'}`);
+                },
+            });
+            await waitForListening(server);
+            const address = server.address();
+            const bound = typeof address === 'object' && address ? address.port : port;
+            console.log(`${chalk.green('agents webhook')} ${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'));
+            const shutdown = () => {
+                server.close(() => process.exit(0));
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+        }
+        catch (err) {
+            console.error(chalk.red(`Could not start webhook receiver: ${err.message}`));
+            process.exit(1);
+        }
+    });
+}

package/dist/index.js

@@ -50,7 +50,7 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadOutput, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadFeed, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { emit, redactArgs } from './lib/events.js';
@@ -174,6 +174,8 @@ Run and dispatch:
   defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
+  webhook                         Receive signed GitHub/Linear webhooks for trigger routines
+  funnel                          Expose a webhook receiver through Tailscale Funnel
   sessions                        Browse, search, and replay past runs (live-search in TTY; grouped by workspace)
   logs [id]                       Show a run's log — host-dispatch task or session; -f to follow
   browser                         Automate a browser — navigate, click, screenshot, console, network
@@ -702,7 +704,10 @@ async function registerAllEagerCommands() {
     await reg(loadLogs);
     await reg(loadEvents);
     await reg(loadAudit);
+    await reg(loadWebhook);
+    await reg(loadFunnel);
     await reg(loadFeed);
+    await reg(loadMailboxes);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
@@ -875,7 +880,7 @@ if (process.env.AGENTS_SKIP_MIGRATION !== '1') {
         // Bumping the suffix re-runs migrations for every user; binary releases that
         // don't change the schema must NOT re-run (they would destroy user content
         // when migration steps overlap with user-authored paths). See issue #20.
-        const sentinelValue = 'v12';
+        const sentinelValue = 'v13';
         let needRun = true;
         try {
             if (fs.existsSync(sentinel) && fs.readFileSync(sentinel, 'utf-8').trim() === sentinelValue) {

package/dist/lib/agents.d.ts

@@ -130,6 +130,48 @@ export interface AccountInfo {
 }
 /** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
+/** Decrypted contents of Droid's auth.v2.file (subset we consume). */
+export interface DroidAuthPayload {
+    access_token?: string;
+    active_organization_id?: string | null;
+}
+/**
+ * Factory Droid stores its OAuth credential encrypted at ~/.factory/auth.v2.file
+ * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
+ * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
+ * device binding — the key is on disk — so we can decrypt locally with no
+ * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
+ * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
+ * Never throws. Shared by account identity below and the Droid usage fetcher
+ * in usage.ts.
+ */
+export declare function decryptDroidAuthPayload(base: string): DroidAuthPayload | null;
+/**
+ * Antigravity (`agy`) stores its OAuth token via the Go keyring library
+ * (zalando/go-keyring), which is platform-split:
+ *
+ *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
+ *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
+ *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
+ *     mapping of service+user). Prefer this over the file when a keyring
+ *     daemon is running.
+ *   - Linux without Secret Service: file fallback at
+ *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
+ *
+ * Probe the OS keyring for existence after the file check. On macOS,
+ * `security find-generic-password` without `-w` is metadata-only (never
+ * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
+ * (stdout is the secret — discarded, never logged). Cached per process —
+ * the keyring is account-global, so one probe covers every installed version.
+ * Returns false when the platform has no probe (Windows) or the tool is
+ * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
+ */
+export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+} | null;
+/** @internal test hook — clear the per-process keyring probe cache. */
+export declare function __resetAntigravityKeychainCacheForTest(): void;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,
@@ -147,6 +189,8 @@ export declare function resolveLastActive(agentId: AgentId, base: string, config
  * Used during init to show approximate session count to user.
  */
 export declare function countSessionFiles(agentId: AgentId): number;
+/** Decode the payload section of a JWT token without verifying its signature. */
+export declare function decodeJwtPayload(token: string): Record<string, any> | null;
 /** Register an MCP server with an agent's CLI via `mcp add`. */
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;

package/dist/lib/agents.js

@@ -984,15 +984,12 @@ function resolveAccountCredentialPath(base, ...segments) {
  * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
  * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
  * device binding — the key is on disk — so we can decrypt locally with no
- * network call. The decrypted JSON credential's `access_token` is a WorkOS JWT
- * carrying an `email` claim (plus org_id / role). We decode the claim WITHOUT
- * verifying `exp`: the email is stable identity for display, not an
- * authorization decision, so an expired token still yields the right address.
- * Every failure (missing key file — e.g. a keyring-v2/legacy login with no
- * on-disk key, a bad GCM tag, malformed JSON, or no email claim) returns null so
- * the caller falls back to the file-presence signed-in signal. Never throws.
+ * network call. Every failure (missing key file — e.g. a keyring-v2/legacy
+ * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
+ * Never throws. Shared by account identity below and the Droid usage fetcher
+ * in usage.ts.
  */
-function decryptDroidCredential(base) {
+export function decryptDroidAuthPayload(base) {
     const filePath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
     const keyPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.key');
     if (!filePath || !keyPath)
@@ -1012,46 +1009,97 @@ function decryptDroidCredential(base) {
             decipher.final(),
         ]).toString('utf-8');
         const cred = JSON.parse(plaintext);
-        const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
-        if (!claims)
-            return null;
-        return {
-            email: typeof claims.email === 'string' ? claims.email : null,
-            orgId: normalizeIdentityPart(claims.org_id ?? cred.active_organization_id),
-            role: typeof claims.role === 'string' ? claims.role : null,
-        };
+        return cred && typeof cred === 'object' ? cred : null;
     }
     catch {
         return null;
     }
 }
+/**
+ * Derive Droid account identity from the decrypted credential. The
+ * `access_token` is a WorkOS JWT carrying an `email` claim (plus org_id /
+ * role). We decode the claim WITHOUT verifying `exp`: the email is stable
+ * identity for display, not an authorization decision, so an expired token
+ * still yields the right address. Returns null when the credential can't be
+ * decrypted or has no decodable claims, so the caller falls back to the
+ * file-presence signed-in signal.
+ */
+function decryptDroidCredential(base) {
+    const cred = decryptDroidAuthPayload(base);
+    const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
+    if (!claims)
+        return null;
+    return {
+        email: typeof claims.email === 'string' ? claims.email : null,
+        orgId: normalizeIdentityPart(claims.org_id ?? cred?.active_organization_id),
+        role: typeof claims.role === 'string' ? claims.role : null,
+    };
+}
 let cachedAgyKeychainSignedIn;
 /**
- * Antigravity (`agy`, a Codeium/Windsurf-based CLI) stores its OAuth token in
- * the macOS keychain — service `gemini`, account `antigravity` — NOT a file.
- * The file path (`antigravity-oauth-token`) only exists on Linux, where the Go
- * keyring falls back to disk. Probe the keychain for existence (metadata only;
- * `-w` omitted so it never prompts). Cached per process — the keychain is
- * account-global, so one probe covers every installed version. Returns false on
- * non-macOS (the file path handles those).
+ * Antigravity (`agy`) stores its OAuth token via the Go keyring library
+ * (zalando/go-keyring), which is platform-split:
+ *
+ *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
+ *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
+ *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
+ *     mapping of service+user). Prefer this over the file when a keyring
+ *     daemon is running.
+ *   - Linux without Secret Service: file fallback at
+ *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
+ *
+ * Probe the OS keyring for existence after the file check. On macOS,
+ * `security find-generic-password` without `-w` is metadata-only (never
+ * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
+ * (stdout is the secret — discarded, never logged). Cached per process —
+ * the keyring is account-global, so one probe covers every installed version.
+ * Returns false when the platform has no probe (Windows) or the tool is
+ * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
  */
+export function antigravityOsKeyringProbe(platform = process.platform) {
+    if (platform === 'darwin') {
+        return {
+            cmd: 'security',
+            args: ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'],
+        };
+    }
+    if (platform === 'linux') {
+        // go-keyring secret_service attributes: "service" + "username" (not
+        // "account" — that flag is the macOS security(1) spelling of the same user).
+        return {
+            cmd: 'secret-tool',
+            args: ['lookup', 'service', 'gemini', 'username', 'antigravity'],
+        };
+    }
+    return null;
+}
+/** @internal test hook — clear the per-process keyring probe cache. */
+export function __resetAntigravityKeychainCacheForTest() {
+    cachedAgyKeychainSignedIn = undefined;
+}
 async function antigravityKeychainSignedIn() {
-    if (cachedAgyKeychainSignedIn !== undefined)
-        return cachedAgyKeychainSignedIn;
-    // Test isolation: the real macOS keychain can't be sandboxed per-test, so
-    // allow suites asserting "signed out" to opt out of the probe (same spirit as
-    // AGENTS_REAL_HOME). Not cached, so tests can toggle it.
+    // Test isolation first (before cache): real OS keyrings can't be sandboxed
+    // per-test. Same spirit as AGENTS_REAL_HOME. Not cached, so tests can toggle.
     if (process.env.AGENTS_NO_KEYCHAIN_PROBE === '1')
         return false;
-    if (process.platform !== 'darwin') {
+    if (cachedAgyKeychainSignedIn !== undefined)
+        return cachedAgyKeychainSignedIn;
+    const probe = antigravityOsKeyringProbe();
+    if (!probe) {
         cachedAgyKeychainSignedIn = false;
         return false;
     }
     try {
-        await execFileAsync('security', ['find-generic-password', '-s', 'gemini', '-a', 'antigravity'], { timeout: 3000 });
+        // Discard stdout: Linux secret-tool lookup prints the secret value.
+        await execFileAsync(probe.cmd, probe.args, {
+            timeout: 3000,
+            // encoding so stdout is a string we can drop without ever logging it
+            encoding: 'utf8',
+        });
         cachedAgyKeychainSignedIn = true;
     }
     catch {
+        // Missing tool (ENOENT), missing item, locked collection, timeout → signed out.
         cachedAgyKeychainSignedIn = false;
     }
     return cachedAgyKeychainSignedIn;
@@ -1282,10 +1330,12 @@ export async function getAccountInfo(agentId, home) {
                 // Antigravity (`agy`) stores a consumer Google OAuth grant (access +
                 // refresh token, no id_token) — presence of a refresh token is the only
                 // signed-in signal we can derive without a network call. Storage is
-                // platform-split: on Linux it's a file at
-                // ~/.gemini/antigravity-cli/antigravity-oauth-token; on macOS the Go
-                // keyring puts it in the keychain (service 'gemini', account
-                // 'antigravity'), so no file exists — check both.
+                // platform-split via go-keyring:
+                //   - file ~/.gemini/antigravity-cli/antigravity-oauth-token (Linux
+                //     fallback when no Secret Service is available)
+                //   - macOS keychain / Linux libsecret (service gemini + user
+                //     antigravity) when a keyring daemon is present
+                // Check the file first, then the OS keyring probe.
                 const tokenPath = resolveAccountCredentialPath(base, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
                 if (tokenPath) {
                     const data = JSON.parse(await fs.promises.readFile(tokenPath, 'utf-8'));
@@ -1524,7 +1574,7 @@ export function countSessionFiles(agentId) {
     return count;
 }
 /** Decode the payload section of a JWT token without verifying its signature. */
-function decodeJwtPayload(token) {
+export function decodeJwtPayload(token) {
     const payload = token.split('.')[1];
     if (!payload)
         return null;

package/dist/lib/browser/drivers/ssh.js

@@ -9,7 +9,7 @@ import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // is the shared hardened baseline (BatchMode + ConnectTimeout + keepalive) —
 // reuse it so the raw-ssh spawns below fail fast on an unreachable host instead
 // of hanging on the default ~127s TCP timeout, rather than re-listing options.
-import { shellQuote, SSH_OPTS } from '../../ssh-exec.js';
+import { shellQuote, SSH_OPTS, assertValidSshTarget } from '../../ssh-exec.js';
 export { shellQuote };
 // The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
@@ -292,6 +292,12 @@ export function buildKillCmd(remoteOs, port) {
     return `pids=$(lsof -ti ${shellQuote(`:${port}`)} 2>/dev/null); [ -z "$pids" ] || kill -9 $pids 2>/dev/null || true`;
 }
 export async function ensureRemoteBrowser(user, host, browserType, port, remoteOs, customBinary) {
+    // `user`/`host` derive from an ssh:// profile endpoint (git-tracked user
+    // config). Validate the composed target before it reaches the raw `ssh` spawn:
+    // an endpoint like `ssh://-Fattack@victim` would otherwise place `-Fattack` at
+    // the target position, where OpenSSH parses it as `-F <file>` and an
+    // attacker-supplied ssh config's ProxyCommand yields local code execution.
+    assertValidSshTarget(`${user}@${host}`);
     const remoteCmd = buildLaunchCmd(remoteOs, browserType, port, customBinary);
     return new Promise((resolve, reject) => {
         // Capture stderr so a real launch failure (missing exe, auth denied, bad
@@ -362,7 +368,18 @@ export function killRemoteBrowser(user, host, remoteOs, port) {
     return runSSHCommand(user, host, buildKillCmd(remoteOs, port));
 }
 function runSSHCommand(user, host, cmd) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
+        // Reject an option-injecting target (e.g. a `-`-leading user from a crafted
+        // ssh:// profile) before it reaches the raw `ssh` spawn. Reject rather than
+        // throw synchronously so `killRemoteBrowser(...).catch()` stays best-effort.
+        // See ensureRemoteBrowser.
+        try {
+            assertValidSshTarget(`${user}@${host}`);
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
         // Reuse the shared hardened baseline so a hung TCP SYN to an unreachable
         // host is bounded by ConnectTimeout (the local 3s kill below only bounds a
         // connected-but-slow command, not the connect itself). Options precede the

package/dist/lib/browser/ipc.js

@@ -432,11 +432,12 @@ export class BrowserIPCServer {
                 return { ok: true };
             }
             case 'set-download-path': {
-                if (!request.task || !request.downloadPath) {
-                    return { ok: false, error: 'Task and download path required' };
+                if (!request.task) {
+                    return { ok: false, error: 'Task required' };
                 }
-                await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
-                return { ok: true };
+                // downloadPath optional: omitted → service defaults to the profile's downloads dir.
+                const resolved = await this.service.setDownloadPath(request.task, request.downloadPath, request.tabId);
+                return { ok: true, downloadPath: resolved };
             }
             case 'wait-download': {
                 if (!request.task) {

package/dist/lib/browser/profiles.d.ts

@@ -11,6 +11,19 @@ export declare const DEFAULT_BROWSER_PROFILE_NAME = "default";
 export declare function getConfiguredDefaultProfileName(): string | undefined;
 export declare function getBrowserRuntimeDir(): string;
 export declare function getProfileRuntimeDir(name: string): string;
+/**
+ * Default destination for browser downloads for a profile. Set browser-global at
+ * connect time (see BrowserService), so downloads land here even when the agent
+ * never calls `browser download --path`. Keyed by the same composite name as the
+ * runtime dir, so every profile is one self-contained tree.
+ */
+export declare function getProfileDownloadsDir(name: string): string;
+/**
+ * Per-profile directory for a task's captured artifacts (screenshots, PDFs,
+ * recordings). Replaces the legacy global `browser/sessions/<task>/` root — the
+ * one-shot migration in migrate.ts folds old captures into here.
+ */
+export declare function getProfileSessionsDir(name: string, task: string): string;
 export declare function listProfiles(): Promise<BrowserProfile[]>;
 export declare function getProfile(name: string): Promise<BrowserProfile | null>;
 /**

package/dist/lib/browser/profiles.js

@@ -19,6 +19,23 @@ export function getBrowserRuntimeDir() {
 export function getProfileRuntimeDir(name) {
     return path.join(getBrowserRuntimeDir(), name);
 }
+/**
+ * Default destination for browser downloads for a profile. Set browser-global at
+ * connect time (see BrowserService), so downloads land here even when the agent
+ * never calls `browser download --path`. Keyed by the same composite name as the
+ * runtime dir, so every profile is one self-contained tree.
+ */
+export function getProfileDownloadsDir(name) {
+    return path.join(getProfileRuntimeDir(name), 'downloads');
+}
+/**
+ * Per-profile directory for a task's captured artifacts (screenshots, PDFs,
+ * recordings). Replaces the legacy global `browser/sessions/<task>/` root — the
+ * one-shot migration in migrate.ts folds old captures into here.
+ */
+export function getProfileSessionsDir(name, task) {
+    return path.join(getProfileRuntimeDir(name), 'sessions', task);
+}
 function configToProfile(name, config) {
     validateRemoteBrowserBinaries(config);
     return {

package/dist/lib/browser/service.d.ts

@@ -226,7 +226,18 @@ export declare class BrowserService {
         timeout?: number;
         tabHint?: string;
     }): Promise<void>;
-    setDownloadPath(taskId: string, downloadPath: string, tabHint?: string): Promise<void>;
+    /**
+     * Point the browser's default download destination at the profile's downloads
+     * dir, browser-global, at connect time. Without this a download the agent never
+     * explicitly routed (`browser download --path`) falls to Chromium's own default
+     * — for an attached user browser, wherever that browser was last configured,
+     * which is how downloads used to escape into random locations. Sent on the root
+     * session (no sessionId) so every current and future tab inherits it. Best
+     * effort: a remote CDP endpoint that doesn't expose the Browser domain must not
+     * fail the whole connect.
+     */
+    private applyDefaultDownloadBehavior;
+    setDownloadPath(taskId: string, downloadPath?: string, tabHint?: string): Promise<string>;
     waitForDownload(taskId: string, timeout?: number): Promise<string>;
     private findTaskBySession;
     shutdown(): Promise<void>;