@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/dist/index.js

@@ -51,9 +51,11 @@ 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, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
+import { renderWhatsNew } from './lib/whats-new.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
+import { emit, redactArgs } from './lib/events.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
 // parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
@@ -75,6 +77,56 @@ program
     .version(VERSION)
     .helpOption('-h, --help', 'Show help')
     .addHelpCommand(false);
+// ─── Audit backbone ────────────────────────────────────────────────────────────
+// One choke point logs every `agents <module> <cmd>` invocation to the structured
+// event log — so team create/disband, agent run, secrets access, and everything
+// else is captured generically (with SSH/remote-user attribution added in emit()),
+// no per-command wiring. `agents events` reads it back. Attached to the root
+// program, so it's inherited by every subcommand regardless of lazy registration.
+/** Command path from the acting command up to (but excluding) the `agents` root. */
+function auditCommandPath(cmd) {
+    const parts = [];
+    let c = cmd;
+    while (c && c.name() && c.name() !== 'agents') {
+        parts.unshift(c.name());
+        c = c.parent;
+    }
+    return parts;
+}
+const auditStarts = new WeakMap();
+program.hook('preAction', (_thisCommand, actionCommand) => {
+    try {
+        const parts = auditCommandPath(actionCommand);
+        if (parts.length === 0)
+            return;
+        auditStarts.set(actionCommand, Date.now());
+        emit('command.start', {
+            module: parts[0],
+            command: parts.join(' '),
+            args: redactArgs(actionCommand.args),
+            cwd: process.cwd(),
+        });
+    }
+    catch {
+        // Audit logging must never break command dispatch.
+    }
+});
+program.hook('postAction', (_thisCommand, actionCommand) => {
+    try {
+        const parts = auditCommandPath(actionCommand);
+        if (parts.length === 0)
+            return;
+        const started = auditStarts.get(actionCommand);
+        emit('command.end', {
+            module: parts[0],
+            command: parts.join(' '),
+            ...(started !== undefined ? { durationMs: Date.now() - started } : {}),
+        });
+    }
+    catch {
+        // Best-effort completion record; the start line is the durable audit fact.
+    }
+});
 // Custom help for the main program only
 const originalHelpInformation = program.helpInformation.bind(program);
 program.helpInformation = function () {
@@ -121,6 +173,7 @@ Run and dispatch:
   teams                           Coordinate multiple agents on shared work
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   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
   pty                             Drive interactive terminal programs (REPLs, TUIs) via a persistent PTY session
 
@@ -175,41 +228,13 @@ async function showWhatsNew(fromVersion, toVersion) {
         const response = await fetch(`https://unpkg.com/@phnx-labs/agents-cli@${toVersion}/CHANGELOG.md`);
         if (!response.ok)
             return;
-        const changelog = await response.text();
-        const lines = changelog.split('\n');
-        const relevantChanges = [];
-        let inRelevantSection = false;
-        let currentVersion = '';
-        for (const line of lines) {
-            const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
-            if (versionMatch) {
-                currentVersion = versionMatch[1];
-                // Only the range the user actually moved through: (fromVersion, toVersion].
-                // Bounding the top end matters when upgrading to a specific older
-                // version, and guards against a changelog that lists unreleased entries.
-                const inRange = compareVersions(currentVersion, fromVersion) > 0 &&
-                    compareVersions(currentVersion, toVersion) <= 0;
-                inRelevantSection = inRange;
-                if (inRelevantSection) {
-                    relevantChanges.push('');
-                    relevantChanges.push(chalk.bold(`v${currentVersion}`));
-                }
-                continue;
-            }
-            if (inRelevantSection && line.trim()) {
-                if (line.startsWith('**') && line.endsWith('**')) {
-                    relevantChanges.push(chalk.cyan(line.replace(/\*\*/g, '')));
-                }
-                else if (line.startsWith('- ')) {
-                    relevantChanges.push(chalk.gray(`  ${line}`));
-                }
-            }
-        }
+        const relevantChanges = renderWhatsNew(await response.text(), fromVersion, toVersion);
         if (relevantChanges.length > 0) {
             console.log(chalk.bold("\nWhat's new:\n"));
             for (const line of relevantChanges) {
                 console.log(line);
             }
+            console.log(chalk.gray('\nFull notes: https://github.com/phnx-labs/agents-cli/blob/main/CHANGELOG.md'));
             console.log();
         }
     }
@@ -764,6 +789,7 @@ async function registerAllEagerCommands() {
     await reg(loadTrash);
     await reg(loadRestore);
     await reg(loadDoctor);
+    await reg(loadStatus);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
     await reg(loadSecrets);
@@ -784,6 +810,8 @@ async function registerAllEagerCommands() {
     await reg(loadBrowser);
     await reg(loadComputer);
     await reg(loadHosts);
+    await reg(loadLogs);
+    await reg(loadEvents);
     await reg(loadSsh);
     registerJobsCronAliasCommand(program, 'jobs');
     registerJobsCronAliasCommand(program, 'cron');
@@ -894,7 +922,8 @@ if (!helpOrVersionRequested) {
     // fire-and-forget the next background sync. System repo gets a real fast-forward
     // pull (read-only locally, safe). User repo and extras get fetch-only + a
     // status marker that we'll print on the *next* invocation.
-    const { spawnDetachedSync } = await import('./lib/auto-pull.js');
+    const { spawnDetachedSync, printPendingUpdateNotices } = await import('./lib/auto-pull.js');
+    printPendingUpdateNotices();
     spawnDetachedSync();
 }
 // First-run experience: no args + no config yet + TTY -> launch interactive setup.

package/dist/lib/acp/harnesses.d.ts

@@ -2,7 +2,7 @@
  * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
  *
  * Each entry describes how to launch a coding agent CLI as an ACP server
- * (stdio JSON-RPC). Unsupported harnesses (amp, roo, goose-stdio) are omitted;
+ * (stdio JSON-RPC). Unsupported harnesses (amp, goose-stdio) are omitted;
  * callers should fall back to the legacy direct-exec path for those.
  *
  * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.

package/dist/lib/acp/harnesses.js

@@ -2,7 +2,7 @@
  * Per-harness spawn configuration for Agent Client Protocol (ACP) mode.
  *
  * Each entry describes how to launch a coding agent CLI as an ACP server
- * (stdio JSON-RPC). Unsupported harnesses (amp, roo, goose-stdio) are omitted;
+ * (stdio JSON-RPC). Unsupported harnesses (amp, goose-stdio) are omitted;
  * callers should fall back to the legacy direct-exec path for those.
  *
  * Sources: https://agentclientprotocol.com/get-started/agents + vendor docs.
@@ -61,7 +61,7 @@ export const ACP_HARNESSES = {
     // goose: ACP over HTTP via `goosed`, not a clean stdio subcommand.
     // copilot, kiro: excluded for now (not installed in the reference environment,
     //                no local verification possible).
-    // amp, roo: not on the ACP agents list.
+    // amp: not on the ACP agents list.
 };
 /** Returns the ACP spawn spec for an agent, or undefined if the harness does not speak ACP. */
 export function getAcpSpec(agent) {

package/dist/lib/agents.d.ts

@@ -219,6 +219,18 @@ export declare const AGENT_NAME_ALIASES: Record<string, AgentId>;
 export declare function resolveAgentName(input: string): AgentId | null;
 /** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;
+/**
+ * Build the deprecation notice lines for an agent, or null if it isn't
+ * deprecated. Split from the printer so tests can assert the content without
+ * capturing stdout. Lines are plain (uncolored) text.
+ */
+export declare function deprecationNotice(agent: AgentId): string[] | null;
+/**
+ * Print a deprecation warning (yellow) if the agent's registry entry carries a
+ * `deprecated` marker; no-op otherwise. Call from any user entry point that
+ * acts on a chosen agent — install (`agents add`) and `agents teams add`.
+ */
+export declare function warnAgentDeprecated(agent: AgentId): void;
 /** Format an error message for an unrecognized agent name, listing valid options. */
 export declare function formatAgentError(agentName: string, validAgents?: AgentId[]): string;
 export {};

package/dist/lib/agents.js

@@ -2,7 +2,7 @@
  * Core agent configuration and detection module.
  *
  * Defines the canonical registry of all supported AI coding agents (Claude, Codex,
- * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Roo, Grok) with their
+ * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Grok) with their
  * CLI commands, config paths, capability flags, and MCP integration points.
  *
  * Provides functions for detecting installed CLIs, resolving version-managed binaries,
@@ -10,6 +10,7 @@
  */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -249,6 +250,16 @@ export const AGENTS = {
         variableSyntax: '{{args}}',
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
+        // Google retired the Gemini CLI (announced at Google I/O 2026, May 19); the `gemini`
+        // command stopped serving free/Pro/Ultra requests on June 18, 2026. Antigravity CLI
+        // (`agy`) is the official successor. See warnAgentDeprecated() for the surfaced warning.
+        deprecated: {
+            by: 'Google',
+            date: 'June 18, 2026',
+            reason: 'The Gemini CLI was retired for free, Pro, and Ultra tiers and no longer serves requests (announced at Google I/O 2026 on May 19).',
+            replacement: 'antigravity',
+            url: 'https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/',
+        },
         // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
         capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'GEMINI.md' }, workflows: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
     },
@@ -316,11 +327,16 @@ export const AGENTS = {
         commandsSubdir: 'commands',
         skillsDir: path.join(HOME, '.copilot', 'skills'),
         hooksDir: 'hooks',
+        // Copilot reads a plugin's manifest from the plugin ROOT (plugin.json),
+        // not `.claude-plugin/plugin.json`. Mirror it there. Verified against the
+        // GitHub Copilot CLI (1.0.56): `copilot plugin install` produces an
+        // installed plugin dir whose manifest sits at the root.
+        pluginManifestDir: '.',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
         supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
+        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: true, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit', 'auto', 'skip'] },
     },
     amp: {
         id: 'amp',
@@ -375,24 +391,6 @@ export const AGENTS = {
         supportsHooks: false,
         capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit'] },
     },
-    roo: {
-        id: 'roo',
-        name: 'Roo Code',
-        color: 'cyanBright',
-        cliCommand: 'roo',
-        npmPackage: '',
-        installScript: 'curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh',
-        configDir: path.join(HOME, '.roo'),
-        commandsDir: path.join(HOME, '.roo', 'commands'),
-        commandsSubdir: 'commands',
-        skillsDir: path.join(HOME, '.roo', 'skills'),
-        hooksDir: 'hooks',
-        instructionsFile: 'AGENTS.md',
-        format: 'markdown',
-        variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
-    },
     // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
     // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
     // CLI but isolates its own state in the `antigravity-cli/` subdir. Per-version HOME
@@ -498,11 +496,26 @@ export const AGENTS = {
     // Install: `curl -fsSL https://app.factory.ai/cli | sh` (no npm package).
     // Binary is NOT in node_modules/.bin — the shim resolves the fixed install
     // path ~/.local/bin/droid directly (see the droid branch in shims.ts).
-    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/).
-    // Memory: native AGENTS.md. Subagents = custom droids (top-level .md files
-    // in ~/.factory/droids/). Config isolation rides the ~/.factory symlink
-    // switch (no FACTORY_HOME env var exists). Headless: `droid exec "<prompt>"`
-    // with --auto low|medium|high, -o stream-json, -m <model>, -r <effort>.
+    // Config: `~/.factory/` (settings.json, mcp.json, droids/, commands/, hooks/,
+    // plugins/). Memory: native AGENTS.md. Subagents = custom droids (top-level
+    // .md files in ~/.factory/droids/). Config isolation rides the ~/.factory
+    // symlink switch (no FACTORY_HOME env var exists). Headless:
+    // `droid exec "<prompt>"` with --auto low|medium|high, -o stream-json,
+    // -m <model>, -r <effort>.
+    //
+    // Hooks: Claude-shaped. settings.json carries a top-level `hooks` object keyed
+    // by event (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart,
+    // SessionEnd, Stop, SubagentStop, Notification, PreCompact), each an array of
+    // `{ matcher?, hooks: [{ type: "command", command, timeout? }] }` matcher
+    // groups — verified against the droid binary's zod schema. So the Claude
+    // registrar is reused verbatim, just targeting `.factory/settings.json`.
+    //
+    // Plugins: native `droid plugin` command group + ~/.factory/plugins/ with the
+    // same marketplace layout Claude uses (known_marketplaces.json +
+    // marketplaces/<name>/plugins/<plugin>/). Droid's plugin manifest dir is
+    // `.factory-plugin/` (it also reads `.claude-plugin/` for compatibility) — set
+    // pluginManifestDir so syncPluginToVersion mirrors the manifest into it, the
+    // same pattern codex uses with `.codex-plugin`.
     droid: {
         id: 'droid',
         name: 'Droid',
@@ -516,20 +529,21 @@ export const AGENTS = {
         commandsSubdir: 'commands',
         skillsDir: '', // no skills concept
         hooksDir: 'hooks',
+        pluginManifestDir: '.factory-plugin',
         instructionsFile: 'AGENTS.md',
         format: 'markdown',
         variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
+        supportsHooks: true,
         // Factory Droid Computers (cloud VMs) reached via `droid computer ssh` +
         // remote headless `droid exec`.
         cloudProvider: 'factory',
         capabilities: {
-            hooks: false,
+            hooks: true,
             mcp: true,
             allowlist: false,
             skills: false,
             commands: true,
-            plugins: false,
+            plugins: true,
             subagents: true,
             rules: { file: 'AGENTS.md' },
             workflows: false,
@@ -802,6 +816,52 @@ function resolveAccountCredentialPath(base, ...segments) {
     }
     return 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. 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.
+ */
+function decryptDroidCredential(base) {
+    const filePath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
+    const keyPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.key');
+    if (!filePath || !keyPath)
+        return null;
+    try {
+        const blob = fs.readFileSync(filePath, 'utf-8').trim();
+        const key = Buffer.from(fs.readFileSync(keyPath, 'utf-8').trim(), 'base64');
+        if (key.length !== 32)
+            return null;
+        const [ivB64, tagB64, ctB64] = blob.split(':');
+        if (!ivB64 || !tagB64 || !ctB64)
+            return null;
+        const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(ivB64, 'base64'));
+        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+        const plaintext = Buffer.concat([
+            decipher.update(Buffer.from(ctB64, 'base64')),
+            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,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 let cachedAgyKeychainSignedIn;
 /**
  * Antigravity (`agy`, a Codeium/Windsurf-based CLI) stores its OAuth token in
@@ -1034,12 +1094,29 @@ export async function getAccountInfo(agentId, home) {
                 return { ...empty, signedIn: true, accountId: userId, accountKey, lastActive };
             }
             case 'droid': {
-                // Factory Droid stores auth at ~/.factory/auth.v2.file (+ auth.v2.key,
-                // an encrypted blob). No email/JWT is readable locally, so presence of
-                // the auth file is the only signed-in signal we can derive without a
-                // network call — same pattern as antigravity/kimi. `.factory` is the
-                // config dir on every platform (macOS/Linux ~/.factory, Windows
-                // %USERPROFILE%\.factory), so path.join keeps this cross-platform.
+                // Factory Droid stores auth at ~/.factory/auth.v2.file (AES-256-GCM,
+                // decrypted with the on-disk ~/.factory/auth.v2.key). We decrypt locally
+                // — no network — and surface the email/org/role from the WorkOS
+                // access-token JWT, same as claude/codex/grok. If the credential can't be
+                // decrypted (a keyring-v2/legacy login with no on-disk key, or a decrypt
+                // failure) we fall back to the file-presence signed-in signal so the row
+                // still reads as logged in — the conservative floor antigravity/kimi use.
+                // `.factory` is the config dir on every platform (macOS/Linux
+                // ~/.factory, Windows %USERPROFILE%\.factory).
+                const decoded = decryptDroidCredential(base);
+                if (decoded?.email) {
+                    const organizationId = decoded.orgId;
+                    const accountKey = buildIdentityKey(agentId, [['org', organizationId]]);
+                    return {
+                        ...empty,
+                        email: decoded.email,
+                        organizationId,
+                        accountId: organizationId,
+                        accountKey,
+                        signedIn: true,
+                        lastActive,
+                    };
+                }
                 const authPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
                 if (!authPath)
                     return { ...empty, lastActive };
@@ -1574,8 +1651,6 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.kiro', 'settings', 'mcp.json');
         case 'goose':
             return path.join(home, '.config', 'goose', 'config.yaml');
-        case 'roo':
-            return path.join(home, '.roo', 'mcp.json');
         case 'antigravity':
             return path.join(home, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
@@ -1612,8 +1687,6 @@ function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
             return path.join(cwd, '.kiro', 'settings', 'mcp.json');
         case 'goose':
             return path.join(cwd, '.goose', 'config.yaml');
-        case 'roo':
-            return path.join(cwd, '.roo', 'mcp.json');
         case 'antigravity':
             return path.join(cwd, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
@@ -1746,9 +1819,6 @@ export const AGENT_NAME_ALIASES = {
     'kiro-cli': 'kiro',
     goose: 'goose',
     'block-goose': 'goose',
-    roo: 'roo',
-    'roo-code': 'roo',
-    roocode: 'roo',
     antigravity: 'antigravity',
     'google-antigravity': 'antigravity',
     agy: 'antigravity',
@@ -1789,6 +1859,40 @@ export function resolveAgentName(input) {
 export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
+/**
+ * Build the deprecation notice lines for an agent, or null if it isn't
+ * deprecated. Split from the printer so tests can assert the content without
+ * capturing stdout. Lines are plain (uncolored) text.
+ */
+export function deprecationNotice(agent) {
+    const dep = AGENTS[agent].deprecated;
+    if (!dep)
+        return null;
+    const name = AGENTS[agent].name;
+    const lines = [
+        `Warning: ${name} was deprecated by ${dep.by} (${dep.date}).`,
+        `  ${dep.reason}`,
+    ];
+    if (dep.replacement) {
+        const rep = AGENTS[dep.replacement];
+        lines.push(`  Consider using ${rep.name} instead:  agents add ${rep.id}`);
+    }
+    if (dep.url)
+        lines.push(`  ${dep.url}`);
+    return lines;
+}
+/**
+ * Print a deprecation warning (yellow) if the agent's registry entry carries a
+ * `deprecated` marker; no-op otherwise. Call from any user entry point that
+ * acts on a chosen agent — install (`agents add`) and `agents teams add`.
+ */
+export function warnAgentDeprecated(agent) {
+    const lines = deprecationNotice(agent);
+    if (!lines)
+        return;
+    for (const line of lines)
+        console.log(chalk.yellow(line));
+}
 /** Format an error message for an unrecognized agent name, listing valid options. */
 export function formatAgentError(agentName, validAgents = ALL_AGENT_IDS) {
     return `Unknown agent '${agentName}'. Valid agents: ${validAgents.join(', ')}`;

package/dist/lib/browser/cdp.js

@@ -219,7 +219,11 @@ export function verifyBrowserIdentity(reported, expected, port, host = 'localhos
         // to a Comet instance doesn't trip a false "identity mismatch".
         comet: ['comet', 'chrome'],
         brave: ['brave', 'brave-browser', 'chrome'],
-        edge: ['edge', 'microsoft-edge', 'msedge', 'chrome'],
+        // Windows/Chromium Edge reports its /json/version "Browser" field as
+        // "Edg/<version>" (the `Edg` token, not `Edge`), which normalizeBrowserName
+        // reduces to "edg". Accept it so attaching to a real Edge doesn't trip a
+        // false identity mismatch (the profile enum only allows "edge").
+        edge: ['edge', 'edg', 'microsoft-edge', 'msedge', 'chrome'],
     };
     const accepted = matches[expected] || [expected];
     if (accepted.includes(reported))

package/dist/lib/browser/chrome.js

@@ -51,6 +51,7 @@ const BROWSER_PATHS = {
         edge: [
             `${WIN_PROGRAMFILES}\\Microsoft\\Edge\\Application\\msedge.exe`,
             `${WIN_PROGRAMFILES_X86}\\Microsoft\\Edge\\Application\\msedge.exe`,
+            `${WIN_LOCALAPPDATA}\\Microsoft\\Edge\\Application\\msedge.exe`,
         ],
         custom: [],
     },
@@ -282,6 +283,25 @@ export async function attachToChrome(port) {
     return wsUrl;
 }
 export function killChrome(pid) {
+    if (process.platform === 'win32') {
+        // On Windows `process.kill(pid, 'SIGINT')` maps to TerminateProcess — a
+        // hard kill that skips Chromium's on-exit profile flush (leaving a dirty
+        // "Chrome didn't shut down correctly" state). Ask taskkill for a graceful
+        // stop first (no /F → posts WM_CLOSE), and only force-kill the tree if that
+        // fails or the process is still around.
+        try {
+            execFileSync('taskkill', ['/pid', String(pid)], { stdio: 'ignore' });
+        }
+        catch {
+            try {
+                execFileSync('taskkill', ['/pid', String(pid), '/t', '/f'], { stdio: 'ignore' });
+            }
+            catch {
+                // Process already dead
+            }
+        }
+        return;
+    }
     try {
         process.kill(pid, 'SIGINT');
     }

package/dist/lib/browser/drivers/ssh.d.ts

@@ -53,4 +53,31 @@ export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string,
  * (Get-NetTCPConnection → Stop-Process).
  */
 export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
+export declare function ensureRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
 export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): Promise<void>;
+/**
+ * Kill the remote browser holding the CDP port. Invoked on stop/cleanup so the
+ * WMI-spawned (Windows) / detached (posix) browser process is not orphaned when
+ * the ssh tunnel is torn down — killing only the tunnel left it running on
+ * win-mini after every `browser stop`. Best-effort: never rejects.
+ */
+export declare function killRemoteBrowser(user: string, host: string, remoteOs: RemoteOs, port: number): Promise<void>;
+/**
+ * Identify whether a pid listening on our target local port is an SSH
+ * tunnel WE would have spawned for `host:remotePort`. Used so that two
+ * agents-browser invocations of the same SSH profile share a tunnel
+ * rather than failing the second one with "port in use".
+ *
+ * Best-effort match against the ssh -L command line via `ps`. If we
+ * can't read the cmd or the args don't look like ours, treat as not-ours.
+ *
+ * Windows has no `ps`, so the POSIX branch below always throws there and every
+ * reuse check returned false — the second invocation to the same host:port then
+ * failed "port in use". On win32 we instead reuse the netstat -ano + tasklist
+ * occupant lookup (getPortOccupant): the tunnel binds `remotePort` locally
+ * (localPort === remotePort in the caller), so the pid holding that port is our
+ * ssh.exe. tasklist only exposes the image name, not the full command line, so
+ * we can't match host/remotePort as tightly as the POSIX branch — an ssh
+ * process on our exact local port is our tunnel in practice.
+ */
+export declare function isOwnTunnel(pid: number, host: string, remotePort: number): boolean;