@phnx-labs/agents-cli 1.14.1 → 1.14.3

package/dist/commands/teams.js

@@ -5,7 +5,8 @@ import { AgentManager, checkAllClis, getAgentsDir, VALID_TASK_TYPES, } from '../
 import { resolveProvider } from '../lib/cloud/registry.js';
 import { runSupervisor } from '../lib/teams/supervisor.js';
 import { handleSpawn, handleStatus, handleStop, handleTasks, } from '../lib/teams/api.js';
-import { createTeam, ensureTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
+import { createTeam, ensureTeam, getTeam, loadTeams, removeTeam, teamExists, } from '../lib/teams/registry.js';
+import { createWorktree, isGitRepo, hasUncommittedChanges, removeWorktree, } from '../lib/teams/worktree.js';
 import { isVersionInstalled, resolveVersionAlias, resolveVersionAliasLoose } from '../lib/versions.js';
 import { discoverSessions, parseTimeFilter, resolveSessionById } from '../lib/session/discover.js';
 import { buildPreview as buildSessionPreview } from './sessions-picker.js';
@@ -542,7 +543,8 @@ Examples:
   # Pull the live log of one teammate
   agents teams logs frontend
 
-  # A teammate is stuck — pull them out, the rest keeps going
+  # A teammate is stuck — stop them, then remove if needed
+  agents teams stop pricing-page frontend
   agents teams remove pricing-page frontend
 
   # Ship done — wind everyone down
@@ -676,10 +678,14 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .aliases(['c', 'new'])
         .description('Start a new team. No teammates yet; add them with `teams add`.')
         .option('-d, --description <text>', 'One-line summary of what this team is working on')
+        .option('--enable-worktrees', 'Each teammate works in its own git worktree (requires --worktree on add)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
         try {
-            const meta = await createTeam(team, opts.description);
+            const meta = await createTeam(team, {
+                description: opts.description,
+                enableWorktrees: opts.enableWorktrees,
+            });
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify({ team, ...meta }, null, 2));
                 return;
@@ -687,9 +693,16 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             console.log(chalk.green(`New team: ${chalk.cyan(team)}`));
             if (meta.description)
                 console.log(chalk.gray(`  ${meta.description}`));
+            if (meta.enable_worktrees)
+                console.log(chalk.gray(`  worktrees: enabled`));
             console.log();
             console.log(chalk.gray('Add your first teammate:'));
-            console.log(chalk.gray(`  agents teams add ${team} claude "your task here"`));
+            if (meta.enable_worktrees) {
+                console.log(chalk.gray(`  agents teams add ${team} claude "your task here" --name alice --worktree feature-name`));
+            }
+            else {
+                console.log(chalk.gray(`  agents teams add ${team} claude "your task here"`));
+            }
         }
         catch (err) {
             die(err.message);
@@ -706,6 +719,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .option('--model <model>', 'Override the effort tier and use this specific model (e.g. claude-opus-4-6)')
         .option('--env <key=value>', 'Set an environment variable for this teammate (repeatable for multiple vars)', (val, prev) => [...prev, val], [])
         .option('--cwd <dir>', 'Working directory for this teammate (default: current directory)')
+        .option('--worktree <name>', 'Run this teammate in a dedicated git worktree (required when team has --enable-worktrees)')
         .option('--after <names>', "DAG dependencies: comma-separated teammate names to wait for. Stages as PENDING; run 'teams start' to launch when ready.")
         .option('--task-type <type>', `Factory label: ${VALID_TASK_TYPES.join('|')}. Drives planner fan-out + test-oracle bugfix loop.`)
         .option('--cloud <provider>', `Dispatch to cloud backend instead of local CLI: ${VALID_CLOUD_PROVIDERS.join('|')}`)
@@ -762,7 +776,34 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         }
         // Auto-create the team if it doesn't exist yet (friendlier UX than erroring).
         await ensureTeam(team);
-        const cwd = opts.cwd ?? process.cwd();
+        // Check if team has worktrees enabled
+        const teamMeta = await getTeam(team);
+        const worktreesEnabled = teamMeta?.enable_worktrees ?? false;
+        let worktreeName = null;
+        let worktreePath = null;
+        if (worktreesEnabled) {
+            if (!opts.worktree) {
+                die(`Team '${team}' has worktrees enabled. Use --worktree <name> to specify a worktree name.`);
+            }
+            if (!opts.name) {
+                die(`Team '${team}' has worktrees enabled. Use --name <name> to identify this teammate.`);
+            }
+            const baseCwd = opts.cwd ?? process.cwd();
+            if (!(await isGitRepo(baseCwd))) {
+                die(`Worktrees require a git repository. ${baseCwd} is not inside a git repo.`);
+            }
+            try {
+                worktreeName = opts.worktree;
+                worktreePath = await createWorktree(baseCwd, worktreeName);
+            }
+            catch (err) {
+                die(`Failed to create worktree '${opts.worktree}': ${err.message}`);
+            }
+        }
+        else if (opts.worktree) {
+            die(`--worktree requires --enable-worktrees on the team. Recreate the team with: agents teams create ${team} --enable-worktrees`);
+        }
+        const cwd = worktreePath ?? opts.cwd ?? process.cwd();
         const mgr = mkManager();
         // Factory teammates: prepend the worker-skill preamble to every task
         // prompt so implementers/testers/reviewers know about the Ledger, the
@@ -811,7 +852,7 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             }
         }
         try {
-            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null);
+            const result = await handleSpawn(mgr, team, agent, effectiveTask, cwd, opts.mode, opts.effort, null, cwd, version, opts.name ?? null, after, opts.model ?? null, envOverrides ?? null, taskType, cloudProviderId, cloudSessionId, opts.repo ?? null, opts.branch ?? null, worktreeName, worktreePath);
             if (isJsonMode(opts)) {
                 console.log(JSON.stringify(result, null, 2));
                 return;
@@ -830,6 +871,9 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             console.log(`  ${chalk.gray('status  ')}  ${statusColor(result.status)(result.status)}`);
             console.log(`  ${chalk.gray('mode    ')}  ${opts.mode}`);
             console.log(`  ${chalk.gray('working ')}  ${cwd}`);
+            if (worktreeName) {
+                console.log(`  ${chalk.gray('worktree')}  ${chalk.cyan(worktreeName)}`);
+            }
             if (result.task_type) {
                 console.log(`  ${chalk.gray('task    ')}  ${chalk.cyan(result.task_type)}`);
             }
@@ -988,11 +1032,90 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             console.error(chalk.yellow(`Stopped by signal after ${result.waves} waves.`));
         }
     });
+    // stop
+    teams
+        .command('stop [team] [teammate]')
+        .description('Stop a running teammate. Can be restarted later. Cleans up worktree if no uncommitted changes.')
+        .option('--json', 'Output machine-readable JSON')
+        .action(async (team, ref, opts) => {
+        const mgr = mkManager();
+        if (!team) {
+            const { names } = await loadTeamRows(mgr);
+            requireDestructiveArg({
+                argName: 'team',
+                command: 'agents teams stop',
+                itemNoun: 'team',
+                available: names,
+                emptyHint: "You don't have any teams yet.",
+            });
+        }
+        if (!ref) {
+            const roster = await mgr.listByTask(team);
+            const running = roster.filter((a) => a.status === 'running');
+            requireDestructiveArg({
+                argName: 'teammate',
+                command: `agents teams stop ${team}`,
+                itemNoun: 'teammate',
+                available: running.map((a) => a.name || shortId(a.agentId)),
+                emptyHint: `Team ${team} has no running teammates.`,
+            });
+        }
+        const lookup = await mgr.resolveAgentIdInTask(team, ref);
+        if (lookup.kind === 'none') {
+            die(`No teammate matching '${ref}' in team ${team}`, 2);
+        }
+        if (lookup.kind === 'ambiguous') {
+            const shorts = lookup.matches.map(shortId).join(', ');
+            die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
+        }
+        const agentId = lookup.agentId;
+        const agent = await mgr.get(agentId);
+        const display = agent?.name || shortId(agentId);
+        const stopRes = await handleStop(mgr, team, agentId);
+        if ('error' in stopRes)
+            die(stopRes.error);
+        // Clean up worktree if this teammate had one
+        let worktreeKept = false;
+        if (agent?.worktreeName && agent?.worktreePath) {
+            try {
+                const dirty = await hasUncommittedChanges(agent.worktreePath);
+                if (dirty) {
+                    worktreeKept = true;
+                }
+                else {
+                    const baseCwd = process.cwd();
+                    await removeWorktree(baseCwd, agent.worktreeName);
+                }
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+        if (isJsonMode(opts)) {
+            console.log(JSON.stringify({
+                team,
+                agent_id: agentId,
+                name: agent?.name ?? null,
+                stopped: stopRes.stopped.length > 0,
+                worktree_kept: worktreeKept,
+            }, null, 2));
+            return;
+        }
+        if (stopRes.stopped.length) {
+            console.log(chalk.green(`Stopped ${chalk.cyan(display)} in team ${chalk.cyan(team)}.`));
+        }
+        else if (stopRes.already_stopped.length) {
+            console.log(chalk.gray(`${display} was already stopped.`));
+        }
+        if (worktreeKept && agent?.worktreeName) {
+            console.log(chalk.yellow(`Worktree '${agent.worktreeName}' has uncommitted changes. Keeping it at: ${agent.worktreePath}`));
+        }
+    });
     // remove
     teams
         .command('remove [team] [teammate]')
         .alias('rm')
-        .description("Remove a teammate from the team. Stops them cleanly if still working. Accepts name, UUID, or UUID prefix.")
+        .description("Remove a stopped teammate's logs and metadata. Use 'stop' first to end a running teammate.")
         .option('--keep-logs', 'Keep their log files on disk (default: delete them)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, ref, opts) => {
@@ -1009,12 +1132,13 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         }
         if (!ref) {
             const roster = await mgr.listByTask(team);
+            const stopped = roster.filter((a) => a.status !== 'running' && a.status !== 'pending');
             requireDestructiveArg({
                 argName: 'teammate',
                 command: `agents teams remove ${team}`,
-                itemNoun: 'teammate',
-                available: roster.map((a) => a.name || shortId(a.agentId)),
-                emptyHint: `Team ${team} has no teammates.`,
+                itemNoun: 'stopped teammate',
+                available: stopped.map((a) => a.name || shortId(a.agentId)),
+                emptyHint: `Team ${team} has no stopped teammates. Use 'agents teams stop' first.`,
             });
         }
         const lookup = await mgr.resolveAgentIdInTask(team, ref);
@@ -1026,13 +1150,13 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             die(`'${ref}' matches multiple teammates: ${shorts}. Use more characters or a name.`, 2);
         }
         const agentId = lookup.agentId;
-        // Look up the display handle (name if they had one) before we tear down.
         const agent = await mgr.get(agentId);
         const display = agent?.name || shortId(agentId);
-        const stopRes = await handleStop(mgr, team, agentId);
-        if ('error' in stopRes)
-            die(stopRes.error);
-        if (!opts.keepLogs && stopRes.not_found.length === 0) {
+        // Require agent to be stopped first
+        if (agent?.status === 'running' || agent?.status === 'pending') {
+            die(`Teammate '${display}' is still ${agent.status}. Run 'agents teams stop ${team} ${display}' first.`);
+        }
+        if (!opts.keepLogs) {
             try {
                 const dir = path.join(await getAgentsDir(), agentId);
                 await fs.rm(dir, { recursive: true, force: true });
@@ -1042,15 +1166,10 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             }
         }
         if (isJsonMode(opts)) {
-            console.log(JSON.stringify({ team, agent_id: agentId, name: agent?.name ?? null, result: stopRes }, null, 2));
+            console.log(JSON.stringify({ team, agent_id: agentId, name: agent?.name ?? null, removed: true }, null, 2));
             return;
         }
-        if (stopRes.stopped.length) {
-            console.log(chalk.green(`${display} has left team ${chalk.cyan(team)} (was working, now stopped).`));
-        }
-        else {
-            console.log(chalk.green(`${display} has left team ${chalk.cyan(team)}.`));
-        }
+        console.log(chalk.green(`Removed ${chalk.cyan(display)} from team ${chalk.cyan(team)}.`));
     });
     // disband
     teams
@@ -1075,6 +1194,24 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         if ('error' in stopRes)
             die(stopRes.error);
         const status = await handleStatus(mgr, team, 'all');
+        // Clean up worktrees for all teammates
+        const baseCwd = process.cwd();
+        const keptWorktrees = [];
+        for (const a of status.agents) {
+            const agent = await mgr.get(a.agent_id);
+            if (agent?.worktreeName && agent?.worktreePath) {
+                try {
+                    const dirty = await hasUncommittedChanges(agent.worktreePath);
+                    if (dirty) {
+                        keptWorktrees.push(agent.worktreeName);
+                    }
+                    else {
+                        await removeWorktree(baseCwd, agent.worktreeName);
+                    }
+                }
+                catch { /* best-effort */ }
+            }
+        }
         const removedIds = [];
         if (!opts.keepLogs) {
             const base = await getAgentsDir();
@@ -1099,6 +1236,9 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
             console.log(chalk.gray(`  Stopped ${stopRes.stopped.length} working teammate(s).`));
         if (removedIds.length)
             console.log(chalk.gray(`  Cleared ${removedIds.length} teammate log(s).`));
+        if (keptWorktrees.length) {
+            console.log(chalk.yellow(`  Kept ${keptWorktrees.length} worktree(s) with uncommitted changes: ${keptWorktrees.join(', ')}`));
+        }
     });
     // logs
     teams

package/dist/commands/trash.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `agents trash` — list and restore soft-deleted version directories.
+ *
+ * `removeVersion` moves a version dir to ~/.agents-system/trash/versions/<agent>/<version>/<timestamp>/
+ * instead of hard-deleting. These commands let the user inspect what's there
+ * and put a soft-deleted version back. The trash never auto-expires; only
+ * `rm -rf ~/.agents-system/trash/` removes bytes from disk.
+ */
+import type { Command } from 'commander';
+export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -0,0 +1,187 @@
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+import { resolveAgentName, agentLabel } from '../lib/agents.js';
+import { getTrashVersionsDir } from '../lib/state.js';
+import { getVersionDir } from '../lib/versions.js';
+function listTrashEntries(filterAgent) {
+    const root = getTrashVersionsDir();
+    if (!fs.existsSync(root))
+        return [];
+    const out = [];
+    let agentDirs;
+    try {
+        agentDirs = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    for (const agentEntry of agentDirs) {
+        if (!agentEntry.isDirectory())
+            continue;
+        const agent = resolveAgentName(agentEntry.name);
+        if (!agent)
+            continue;
+        if (filterAgent && agent !== filterAgent)
+            continue;
+        const agentDir = path.join(root, agentEntry.name);
+        let versionDirs;
+        try {
+            versionDirs = fs.readdirSync(agentDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const ver of versionDirs) {
+            if (!ver.isDirectory())
+                continue;
+            const versionDir = path.join(agentDir, ver.name);
+            let stampDirs;
+            try {
+                stampDirs = fs.readdirSync(versionDir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const stamp of stampDirs) {
+                if (!stamp.isDirectory())
+                    continue;
+                out.push({
+                    agent,
+                    version: ver.name,
+                    stamp: stamp.name,
+                    trashPath: path.join(versionDir, stamp.name),
+                });
+            }
+        }
+    }
+    return out.sort((a, b) => a.stamp.localeCompare(b.stamp)).reverse();
+}
+function pickLatest(entries, agent, version) {
+    const matches = entries.filter((e) => e.agent === agent && e.version === version);
+    if (matches.length === 0)
+        return null;
+    return matches[0];
+}
+function parseAgentVersion(target) {
+    const at = target.indexOf('@');
+    if (at < 1 || at === target.length - 1)
+        return null;
+    const agent = resolveAgentName(target.slice(0, at));
+    if (!agent)
+        return null;
+    return { agent, version: target.slice(at + 1) };
+}
+function dirSizeBytes(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop();
+        let stat;
+        try {
+            stat = fs.lstatSync(cur);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            let entries;
+            try {
+                entries = fs.readdirSync(cur);
+            }
+            catch {
+                continue;
+            }
+            for (const e of entries)
+                stack.push(path.join(cur, e));
+        }
+        else {
+            total += stat.size;
+        }
+    }
+    return total;
+}
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+    return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+export function registerTrashCommands(program) {
+    const trash = program
+        .command('trash')
+        .description('Inspect and restore soft-deleted agent version directories');
+    trash
+        .command('list [agent]')
+        .description('List soft-deleted version directories (optionally filtered to one agent)')
+        .action((agentArg) => {
+        let filter;
+        if (agentArg) {
+            const a = resolveAgentName(agentArg);
+            if (!a) {
+                console.error(chalk.red(`Unknown agent: ${agentArg}`));
+                process.exit(1);
+            }
+            filter = a;
+        }
+        const entries = listTrashEntries(filter);
+        if (entries.length === 0) {
+            console.log(chalk.gray('Trash is empty.'));
+            return;
+        }
+        console.log(chalk.bold(`Soft-deleted versions (${entries.length})`));
+        for (const e of entries) {
+            const size = humanSize(dirSizeBytes(e.trashPath));
+            console.log(`  ${agentLabel(e.agent)}@${e.version}  ` +
+                chalk.gray(`${e.stamp}  ${size}  ${e.trashPath}`));
+        }
+        console.log();
+        console.log(chalk.gray('Restore with: agents trash restore <agent>@<version>'));
+    });
+    trash
+        .command('restore <target>')
+        .description('Restore a soft-deleted version (e.g. "claude@2.1.110") back to ~/.agents-system/versions/')
+        .action((target) => {
+        const parsed = parseAgentVersion(target);
+        if (!parsed) {
+            console.error(chalk.red(`Expected <agent>@<version>, got: ${target}`));
+            process.exit(1);
+        }
+        const { agent, version } = parsed;
+        const entries = listTrashEntries(agent);
+        const entry = pickLatest(entries, agent, version);
+        if (!entry) {
+            console.error(chalk.red(`No trashed copy found for ${agent}@${version}`));
+            console.error(chalk.gray('Run `agents trash list` to see what exists.'));
+            process.exit(1);
+        }
+        const dest = getVersionDir(agent, version);
+        if (fs.existsSync(dest)) {
+            console.error(chalk.red(`Cannot restore: ${dest} already exists.`));
+            console.error(chalk.gray('Move or remove the existing dir first, then re-run restore.'));
+            process.exit(1);
+        }
+        try {
+            fs.mkdirSync(path.dirname(dest), { recursive: true, mode: 0o700 });
+            fs.renameSync(entry.trashPath, dest);
+        }
+        catch (err) {
+            console.error(chalk.red(`Restore failed: ${err.message}`));
+            process.exit(1);
+        }
+        // Best-effort cleanup of empty stamp/version parents in trash.
+        try {
+            const verDir = path.dirname(entry.trashPath);
+            if (fs.readdirSync(verDir).length === 0)
+                fs.rmdirSync(verDir);
+            const agentDir = path.dirname(verDir);
+            if (fs.readdirSync(agentDir).length === 0)
+                fs.rmdirSync(agentDir);
+        }
+        catch { /* best-effort */ }
+        console.log(chalk.green(`Restored ${agentLabel(agent)}@${version} to ${dest}`));
+    });
+}

package/dist/commands/view.js

@@ -6,12 +6,12 @@ import * as yaml from 'yaml';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { formatUsageSection, formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { getAgentsDir, getUserAgentsDir, getPromptcutsPath } from '../lib/state.js';
 import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
-import { getCentralMemoryFileName } from '../lib/memory.js';
+import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
@@ -426,7 +426,7 @@ async function showAgentResources(agentId, requestedVersion) {
         }
         else {
             // Rules files: map agent-specific name (CLAUDE.md) back to canonical (AGENTS.md)
-            const centralName = getCentralMemoryFileName(agentId);
+            const centralName = getCentralRulesFileName(agentId);
             relativePath = `rules/${centralName}`;
         }
         const matchesPath = (f) => f === relativePath || f.startsWith(relativePath + '/');
@@ -653,14 +653,21 @@ async function collectAgentsJson(filterAgentId) {
     return out;
 }
 async function buildAgentPrunePlan(agentId) {
-    const entries = await Promise.all(listInstalledVersions(agentId).map(async (version) => {
+    const dirInfos = listInstalledVersionDirs(agentId);
+    const entries = await Promise.all(dirInfos.map(async ({ version, hasBinary }) => {
         const home = getVersionHomePath(agentId, version);
         const info = await getAccountInfo(agentId, home);
-        return { version, info };
+        return { version, info, hasBinary };
     }));
     const globalDefault = getGlobalDefault(agentId);
+    const toPrune = [];
+    const skippedDefaults = [];
+    // Duplicate-account detection runs only over installs that actually have a
+    // working binary — those are the things that compete for "the live install
+    // for this account."
+    const installed = entries.filter((e) => e.hasBinary);
     const byEmail = new Map();
-    for (const e of entries) {
+    for (const e of installed) {
         if (!e.info.email)
             continue;
         const key = e.info.email.toLowerCase();
@@ -668,8 +675,6 @@ async function buildAgentPrunePlan(agentId) {
         list.push(e);
         byEmail.set(key, list);
     }
-    const toPrune = [];
-    const skippedDefaults = [];
     for (const [, group] of byEmail) {
         if (group.length < 2)
             continue;
@@ -682,6 +687,7 @@ async function buildAgentPrunePlan(agentId) {
                 email: older.info.email,
                 keeper,
                 isDefault: older.version === globalDefault,
+                reason: 'duplicate',
             };
             if (plan.isDefault)
                 skippedDefaults.push(plan);
@@ -689,6 +695,23 @@ async function buildAgentPrunePlan(agentId) {
                 toPrune.push(plan);
         }
     }
+    // Home-only leftovers: dirs without a binary. These are residue from a
+    // prior removeVersion before the soft-delete migration, plus any hand-edited
+    // installs. Surface them so the user can move them to trash.
+    for (const e of entries) {
+        if (e.hasBinary)
+            continue;
+        if (e.version === globalDefault)
+            continue; // never auto-suggest the default
+        toPrune.push({
+            agentId,
+            version: e.version,
+            email: e.info.email || '',
+            keeper: '',
+            isDefault: false,
+            reason: 'home-leftover',
+        });
+    }
     return { agentId, toPrune, skippedDefaults };
 }
 async function executePrunePlan(plan) {
@@ -720,11 +743,17 @@ function printPrunePlan(plan, isFirst) {
     }
     if (plan.toPrune.length === 0)
         return;
-    const heading = isFirst ? `Will prune ${agentLabel(plan.agentId)}:` : `Also found duplicates for ${agentLabel(plan.agentId)}:`;
+    const heading = isFirst ? `Will move to trash for ${agentLabel(plan.agentId)}:` : `Also found candidates for ${agentLabel(plan.agentId)}:`;
     console.log(chalk.bold(heading));
     for (const p of plan.toPrune) {
-        console.log(`  ${agentLabel(p.agentId)}@${p.version}  ${chalk.cyan(p.email)}  ` +
-            chalk.gray(`— keeping ${p.agentId}@${p.keeper}`));
+        if (p.reason === 'duplicate') {
+            console.log(`  ${agentLabel(p.agentId)}@${p.version}  ${chalk.cyan(p.email)}  ` +
+                chalk.gray(`— duplicate, keeping ${p.agentId}@${p.keeper}`));
+        }
+        else {
+            console.log(`  ${agentLabel(p.agentId)}@${p.version}  ` +
+                chalk.gray(`— home-only leftover (no binary; transcripts preserved in trash)`));
+        }
     }
     console.log();
 }
@@ -746,7 +775,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
     spinner.stop();
     const actionable = plans.filter((p) => p.toPrune.length > 0 || p.skippedDefaults.length > 0);
     if (actionable.length === 0) {
-        console.log(chalk.gray('Nothing to prune — no older versions share an account with a newer version.'));
+        console.log(chalk.gray('Nothing to prune — no duplicate-account installs and no home-only leftovers.'));
         return;
     }
     const totalCandidates = actionable.reduce((n, plan) => n + plan.toPrune.length, 0);
@@ -844,7 +873,11 @@ export async function viewAction(agentArg, options) {
         console.log(chalk.red(formatAgentError(agentName)));
         process.exit(1);
     }
-    const requestedVersion = resolveVersionAlias(agentId, parts[1]) ?? null;
+    // Keep 'default' as-is since showAgentResources handles it; resolveVersionAlias
+    // returns undefined for 'default' which would skip the detailed view.
+    const requestedVersion = parts[1] === 'default'
+        ? 'default'
+        : (resolveVersionAlias(agentId, parts[1]) ?? null);
     if (prune) {
         if (requestedVersion) {
             console.log(chalk.red('--prune does not take a @version suffix.'));