@phnx-labs/agents-cli 1.20.33 → 1.20.34

package/dist/index.js

@@ -51,7 +51,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, 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, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { IS_WINDOWS } from './lib/platform/index.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
@@ -764,6 +764,7 @@ async function registerAllEagerCommands() {
     await reg(loadTrash);
     await reg(loadRestore);
     await reg(loadDoctor);
+    await reg(loadStatus);
     registerExecAliasCommand(program);
     await reg(loadProfiles);
     await reg(loadSecrets);
@@ -894,7 +895,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 },
     },
@@ -375,24 +386,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
@@ -802,6 +795,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 +1073,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 +1630,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 +1666,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 +1798,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 +1838,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/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

@@ -54,3 +54,22 @@ export declare function buildLaunchCmd(remoteOs: RemoteOs, browserType: string,
  */
 export declare function buildKillCmd(remoteOs: RemoteOs, port: number): string;
 export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, remoteOs: RemoteOs, customBinary?: string): 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;

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

@@ -12,6 +12,7 @@ export { shellQuote };
 // the single ssh-tunnel helper. Calling it with no options preserves this
 // driver's original foreground, stderr-captured behavior exactly.
 import { startSSHTunnel } from '../../ssh-tunnel.js';
+import { encodePwshBase64 } from '../../pwsh.js';
 export async function connectSSH(endpoint, profile) {
     const url = new URL(endpoint);
     if (url.protocol !== 'ssh:') {
@@ -159,8 +160,7 @@ function psSingleQuote(s) {
  * `powershell -Command "…"` is fragile the moment a path or URL is involved).
  */
 export function encodePowerShell(script) {
-    const b64 = Buffer.from(script, 'utf16le').toString('base64');
-    return `powershell -NoProfile -EncodedCommand ${b64}`;
+    return `powershell -NoProfile -EncodedCommand ${encodePwshBase64(script)}`;
 }
 /**
  * The PowerShell that launches the browser on a Windows remote. Two hard
@@ -290,8 +290,23 @@ function sleep(ms) {
  *
  * 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.
  */
-function isOwnTunnel(pid, host, remotePort) {
+export function isOwnTunnel(pid, host, remotePort) {
+    if (process.platform === 'win32') {
+        const occupant = getPortOccupant(remotePort);
+        if (!occupant || occupant.pid !== pid)
+            return false;
+        return occupant.command.toLowerCase().startsWith('ssh');
+    }
     try {
         const out = execFileSync('ps', ['-p', String(pid), '-o', 'command='], {
             encoding: 'utf-8',

package/dist/lib/doctor-diff.js

@@ -29,6 +29,8 @@ import { pluginInstallDir, repairableManifestFields } from './plugin-marketplace
 import { markdownToToml } from './convert.js';
 import { resolveImports, supportsRulesImports } from './rules/compile.js';
 import { listCommandsInVersionHome, getVersionCommandsDir } from './commands.js';
+import { shouldInstallCommandAsSkill, commandSkillMatches, commandSkillName } from './command-skills.js';
+import { supports } from './capabilities.js';
 import { listSkillsInVersionHome, getVersionSkillsDir } from './skills.js';
 import { listHooksInVersionHome, listHookEntriesFromDir } from './hooks.js';
 const RULES_DOC_FILENAME = 'README.md';
@@ -87,6 +89,15 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     const isToml = agentConfig.format === 'toml';
     const ext = isToml ? '.toml' : '.md';
     const homeDir = getVersionCommandsDir(agent, version);
+    // Command-as-skill agents (kimi, codex>=0.117, grok) install every command as a
+    // SKILL wrapper at <agentDir>/skills/<cmd>/SKILL.md, not a native command file.
+    // The compare must follow that or every command false-reports as drifted.
+    const asSkill = shouldInstallCommandAsSkill(agent, version);
+    // Agents that hold commands neither natively nor as skills (e.g. goose) must not
+    // report source commands as "missing" — they structurally can't take them.
+    if (!asSkill && !supports(agent, 'commands', version).ok)
+        return [];
+    const agentDir = path.join(getVersionHomePath(agent, version), agentConfigDirName(agent));
     const installed = new Set(listCommandsInVersionHome(agent, version));
     const layerBases = buildLayerBases(cwd, 'commands', { excludeProject });
     const sourceByName = new Map();
@@ -113,11 +124,24 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     const seen = new Set();
     for (const [name, src] of sourceByName) {
         seen.add(name);
-        const homePath = path.join(homeDir, `${name}${ext}`);
         if (!installed.has(name)) {
             rows.push({ kind: 'commands', name, status: 'missing', source: src.layer, sourcePath: src.path });
             continue;
         }
+        if (asSkill) {
+            // Compare against the installed command-skill wrapper, not a native path.
+            const matches = commandSkillMatches(agentDir, name, src.path);
+            rows.push({
+                kind: 'commands',
+                name,
+                status: matches ? 'ok' : 'diff',
+                source: src.layer,
+                sourcePath: src.path,
+                homePath: path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md'),
+            });
+            continue;
+        }
+        const homePath = path.join(homeDir, `${name}${ext}`);
         const installedContent = readSafe(homePath);
         const sourceContent = readSafe(src.path);
         if (installedContent == null || sourceContent == null) {
@@ -138,7 +162,10 @@ function diffCommands(agent, version, cwd, excludeProject = false) {
     for (const name of installed) {
         if (seen.has(name))
             continue;
-        rows.push({ kind: 'commands', name, status: 'extra', homePath: path.join(homeDir, `${name}${ext}`) });
+        const extraHome = asSkill
+            ? path.join(agentDir, 'skills', commandSkillName(name), 'SKILL.md')
+            : path.join(homeDir, `${name}${ext}`);
+        rows.push({ kind: 'commands', name, status: 'extra', homePath: extraHome });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
 }

package/dist/lib/drift-sync.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Interactive drift-sync flow — the single "we detected drift, want to fix it?"
+ * action, shared by `agents status`, `agents doctor`, and the menu-bar "NEEDS
+ * SYNC" row.
+ *
+ * It composes existing pieces, re-implementing nothing:
+ *   - computeSyncStatus()          — the unified detection engine (sync-status.ts)
+ *   - pullRepo()                   — fast-forward the `.system` repo (git.ts)
+ *   - promptAgentVersionSelection() — the "which agent types / versions?" picker
+ *   - heal({ mode: 'full' })       — the reconcile engine `doctor --fix` uses
+ *
+ * Combined flow (one confirmation): if `.system` is behind AND resources drifted,
+ * a single "Sync all detected" both pulls `.system` and reconciles the chosen
+ * version homes. The security posture is preserved — the `.system` pull only ever
+ * happens on an explicit user choice here, never silently (see auto-pull-worker.ts
+ * for why system auto-pull is off by default).
+ */
+import { type VersionHealResult } from './heal.js';
+import { type UnifiedSyncStatus } from './sync-status.js';
+export interface DriftSyncOptions {
+    cwd?: string;
+    /** Reconcile everything detected with no prompts — the "kick it" path, also the
+     * non-TTY / menu-bar-launched-with-flag behavior. Pulls `.system` if behind. */
+    yes?: boolean;
+    /** Pre-computed status, to avoid a second scan when the caller already has one. */
+    status?: UnifiedSyncStatus;
+    /** Skip the drift summary — set by callers that already printed their own. */
+    quiet?: boolean;
+}
+export interface DriftSyncResult {
+    systemBehindBefore: number;
+    systemPulled: boolean;
+    healed: VersionHealResult[];
+    /** True when the user declined at the prompt (nothing was changed). */
+    cancelled: boolean;
+    /** True when there was no drift to act on in the first place. */
+    nothingToDo: boolean;
+}
+/**
+ * The unified "drift detected — sync now?" flow. Returns a structured result so
+ * callers (menu-bar, doctor) can report without re-scanning.
+ */
+export declare function promptDriftSync(opts?: DriftSyncOptions): Promise<DriftSyncResult>;