@phnx-labs/agents-cli 1.22.35 → 1.22.38

package/dist/commands/sync.d.ts

@@ -30,5 +30,10 @@
  *   sub-50ms steady state. Keep changes here surgical.
  */
 import { Command } from 'commander';
+/**
+ * Attach the resource-selector flag family to the sync command.
+ * Exported for testing flag registration in sync.test.ts.
+ */
+export declare function addSelectorOptions(cmd: Command): Command;
 /** Register the `agents sync` command. */
 export declare function registerSyncCommand(program: Command): void;

package/dist/commands/sync.js

@@ -30,10 +30,11 @@
  *   sub-50ms steady state. Keep changes here surgical.
  */
 import * as path from 'path';
+import { Option } from 'commander';
 import chalk from 'chalk';
 import { resolveSyncPassphraseFromEnv } from '../lib/secrets/sync-passphrase.js';
 import { agentLabel, resolveAgentName, MANAGED_AGENT_IDS, isAgentHardDeprecated, hardDeprecationError } from '../lib/agents.js';
-import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildRepoScopedSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/versions.js';
+import { isVersionInstalled, syncResourcesToVersion, parseAgentSpec, resolveVersion, resolveVersionAlias, listInstalledVersions, getAvailableResources, getActuallySyncedResources, getProjectOnlyResources, getNewResources, hasNewResources, promptResourceSelection, promptNewResourceSelection, buildSelection, mergeRepoScopedSelections, listRepoNames, getVersionHomePath, } from '../lib/versions.js';
 import { capableAgents } from '../lib/capabilities.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
@@ -48,13 +49,94 @@ import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../l
 function emitJson(payload) {
     console.log(JSON.stringify(payload));
 }
+/**
+ * Translate per-kind CLI flags into a `ResourceSelection` for `buildSelection`.
+ * Returns `undefined` when no kind flag was given (caller should use full sync).
+ *
+ * Each kind has a singular primary flag and a hidden plural alias; both carry
+ * the same value. `true` = bare flag (all names for that kind), `string[]` =
+ * explicit name filter, `undefined` = flag not used.
+ *
+ * --rule / --rules / --memory all map to the `memory` key (always `'all'` —
+ * the composed file is recompiled from every layer, individual names ignored).
+ */
+function parseKindSelection(opts) {
+    function resolve(singular, plural) {
+        const val = singular ?? plural;
+        if (val === undefined)
+            return undefined;
+        return val === true ? 'all' : val;
+    }
+    const plugins = resolve(opts.plugin, opts.plugins);
+    const commands = resolve(opts.command, opts.commands);
+    const skills = resolve(opts.skill, opts.skills);
+    const hooks = resolve(opts.hook, opts.hooks);
+    const subagents = resolve(opts.subagent, opts.subagents);
+    const permissions = resolve(opts.permission, opts.permissions);
+    const mcp = resolve(opts.mcp, opts.mcps);
+    const workflows = resolve(opts.workflow, opts.workflows);
+    // --rule/--rules/--memory all enable a full memory recompile (no name filter).
+    const memory = (opts.rule || opts.rules || opts.memory) ? 'all' : undefined;
+    const anySet = [plugins, commands, skills, hooks, subagents, permissions, mcp, workflows, memory]
+        .some(v => v !== undefined);
+    if (!anySet)
+        return undefined;
+    const sel = {};
+    if (plugins)
+        sel.plugins = plugins;
+    if (commands)
+        sel.commands = commands;
+    if (skills)
+        sel.skills = skills;
+    if (hooks)
+        sel.hooks = hooks;
+    if (subagents)
+        sel.subagents = subagents;
+    if (permissions)
+        sel.permissions = permissions;
+    if (mcp)
+        sel.mcp = mcp;
+    if (workflows)
+        sel.workflows = workflows;
+    if (memory)
+        sel.memory = memory;
+    return sel;
+}
+/**
+ * Attach the resource-selector flag family to the sync command.
+ * Exported for testing flag registration in sync.test.ts.
+ */
+export function addSelectorOptions(cmd) {
+    const kindCollector = (val, prev) => {
+        const names = val.split(',').map((s) => s.trim()).filter(Boolean);
+        const base = Array.isArray(prev) ? prev : [];
+        return [...base, ...names];
+    };
+    function addKindPair(singular, plural, desc) {
+        cmd.addOption(new Option(`--${singular} [names]`, desc).argParser(kindCollector));
+        cmd.addOption(new Option(`--${plural} [names]`, `Alias of --${singular}`).argParser(kindCollector).hideHelp());
+    }
+    addKindPair('plugin', 'plugins', 'Sync only plugins (bare = all; comma-separated names to filter)');
+    addKindPair('command', 'commands', 'Sync only commands (bare = all; comma-separated names to filter)');
+    addKindPair('skill', 'skills', 'Sync only skills (bare = all; comma-separated names to filter)');
+    addKindPair('hook', 'hooks', 'Sync only hooks (bare = all; comma-separated names to filter)');
+    addKindPair('subagent', 'subagents', 'Sync only subagents (bare = all; comma-separated names to filter)');
+    addKindPair('permission', 'permissions', 'Sync only permissions (bare = all; comma-separated names to filter)');
+    addKindPair('mcp', 'mcps', 'Sync only MCP servers (bare = all; comma-separated names to filter)');
+    addKindPair('workflow', 'workflows', 'Sync only workflows (bare = all; comma-separated names to filter)');
+    cmd.addOption(new Option('--rule [names]', 'Sync only the rules/memory file (maps to the "memory" key — the whole file is always recompiled, individual names are not filtered)').argParser(kindCollector));
+    cmd.addOption(new Option('--rules [names]', 'Alias of --rule').argParser(kindCollector).hideHelp());
+    cmd.addOption(new Option('--memory', 'Sync only the rules/memory file (alias of --rule with no name filter)'));
+    cmd.addOption(new Option('--version <spec>', 'Agent version or selector: @latest, @oldest, @pinned (= @default), @all, or a concrete x.y.z. "all" targets every installed version non-interactively.'));
+    return cmd;
+}
 /** Register the `agents sync` command. */
 export function registerSyncCommand(program) {
-    addHostOption(program.command('sync [agentSpec] [repo]'))
+    const cmd = addHostOption(program.command('sync [agentSpec] [repo]'))
         .summary('Make this machine current, or sync resources into one agent')
-        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: refuse if the tree is dirty, else git pull --rebase against origin. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets are opt-in — add --secrets to pull secret bundles. Session transcripts are queryable live via "agents sessions --host <machine>", or moved with "agents sessions export/import". Also: --cloud (fetch only), --local (reconcile only).')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: git pull --rebase against origin when the tree is clean; when it is dirty, fast-forward anyway if no incoming path is uncommitted, else refuse and name what collided. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets are opt-in — add --secrets to pull secret bundles. Session transcripts are queryable live via "agents sessions --host <machine>", or moved with "agents sessions export/import". Also: --cloud (fetch only), --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
-        .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
+        .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version" or --version)')
         .option('--repo <name>', 'Scope the sync to a single DotAgent repo: system / user / project / <alias> (also accepted as a positional)')
         .option('--project-dir <path>', 'Path to project-level .agents/ directory containing project-scoped resources')
         .option('--cwd <path>', 'Working directory for discovering project manifest and resources')
@@ -62,6 +144,8 @@ export function registerSyncCommand(program) {
         .option('-y, --yes', 'Skip the interactive preview and auto-sync all detected resources', false)
         .option('--force', 'Re-sync even if no changes are detected since the last sync', false)
         .option('--quiet', 'Suppress all output (exit code indicates success)', false)
+        .option('--dry-run', 'Show what would be synced without making any changes', false)
+        .option('--allow-exec-surfaces', 'Allow syncing plugin exec surfaces (scripts, binaries) — off by default for safety', false)
         .option('--json', 'Emit machine-readable JSON (also accepted so fleet fan-out via --host all can parse each peer)', false)
         // Umbrella verb (no agent given): make this machine current.
         .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
@@ -71,6 +155,9 @@ export function registerSyncCommand(program) {
         .action(async (agentSpec, repo, opts) => {
         await runSync(agentSpec, repo, opts);
     });
+    // Per-kind resource selectors + --version. Registered after the main flags so
+    // help output groups the positional/repo/agent flags first.
+    addSelectorOptions(cmd);
 }
 /**
  * Resolve a DotAgent repo name to its git working directory + whether local
@@ -90,9 +177,10 @@ function resolveRepoGitTarget(repo) {
     return null;
 }
 /**
- * `agents sync <repo>` — git-sync a single DotAgent repo: refuse on a dirty
- * tree, else pull --rebase against origin, pushing local commits for user-owned
- * repos. Delegates the git work to `syncRepoGit`.
+ * `agents sync <repo>` — git-sync a single DotAgent repo: pull --rebase against
+ * origin on a clean tree; on a dirty one, fast-forward anyway when no incoming
+ * path is uncommitted, else refuse naming the collision. Pushes local commits
+ * for user-owned repos. Delegates the git work to `syncRepoGit`.
  */
 async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
     const target = resolveRepoGitTarget(repo);
@@ -219,7 +307,7 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         const version = resolveVersion(agentId, cwd) || listInstalledVersions(agentId).slice(-1)[0];
         if (!version)
             continue;
-        const result = syncResourcesToVersion(agentId, version, selection, { cwd });
+        const result = syncResourcesToVersion(agentId, version, selection, { cwd, prune: true });
         printSyncDetail(result, agentId, version, cwd);
         if (result.hooks && hookCapable.has(agentId) && Object.keys(hookManifest).length > 0) {
             registerHooksToSettings(agentId, getVersionHomePath(agentId, version), hookManifest);
@@ -336,7 +424,13 @@ async function runSync(agentSpec, repoArg, opts) {
     // user-owned repos. This is distinct from the [repo] resource-scoping arg
     // below, and it precedes agent-spec parsing because repo names like
     // "system"/"user" would otherwise fail parseAgentSpec.
+    //
+    // DEPRECATED: prefer `agents repo sync <name>` — this positional form will be
+    // removed in a future release.
     if (agentSpec && !opts.agent && !repoArg && listRepoNames().includes(agentSpec)) {
+        if (!quiet && !json) {
+            console.error(chalk.yellow(`Warning: 'agents sync ${agentSpec}' is deprecated. Use: agents repo sync ${agentSpec}`));
+        }
         await runRepoGitSync(agentSpec, quiet, outLog, errLog, json);
         return;
     }
@@ -359,6 +453,10 @@ async function runSync(agentSpec, repoArg, opts) {
         if (agentSpec.includes('@'))
             selector = parsed.version;
     }
+    // --version flag beats any @selector from the positional.
+    // Strip a leading @ so '--version @latest' and '--version latest' both work.
+    if (opts.version)
+        selector = opts.version.replace(/^@/, '');
     // Repo scope: --repo flag wins over the positional. Validate against the
     // known DotAgent repos so a typo fails loudly instead of syncing nothing.
     const repoScope = opts.repo || repoArg;
@@ -407,9 +505,20 @@ async function runSync(agentSpec, repoArg, opts) {
     const projectDir = opts.projectDir;
     const cwd = opts.cwd || process.cwd();
     const force = !!opts.force;
+    // Promote to @all when no version can be resolved and multiple are installed.
+    // Replaces the old "no default version pinned" error: bare `agents sync claude`
+    // with multiple installed versions and no pinned default now syncs them all.
+    if (!selector && !version && !opts.agentVersion) {
+        const pinned = resolveVersion(agentId, opts.cwd || process.cwd());
+        if (!pinned) {
+            const installed = listInstalledVersions(agentId);
+            if (installed.length > 1)
+                selector = 'all';
+        }
+    }
     // ---------- 2a. @all: reconcile every installed version of this agent ----------
     // Non-interactive by design — fanning an interactive preview across N
-    // versions is unusable. Honors an optional repo scope.
+    // versions is unusable. Honors optional repo scope and per-kind flags.
     if (selector === 'all') {
         const installed = listInstalledVersions(agentId);
         if (installed.length === 0) {
@@ -421,23 +530,45 @@ async function runSync(agentSpec, repoArg, opts) {
             process.exitCode = 1;
             return;
         }
+        const kindFilter = parseKindSelection(opts);
         let selection;
-        if (repoScope) {
-            selection = buildRepoScopedSelection(repoScope, cwd);
+        if (repoScope || kindFilter) {
+            selection = buildSelection(repoScope ? [`${repoScope}:*`] : [], kindFilter ?? undefined, cwd);
             if (Object.keys(selection).length === 0) {
                 if (json)
                     emitJson({ ok: true, mode: 'agent-all', agent: agentId, repo: repoScope, versions: [], note: 'nothing to sync' });
                 else
-                    outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync.`));
+                    outLog(chalk.gray(`Nothing to sync${repoScope ? ` from repo '${repoScope}'` : ''}.`));
                 return;
             }
         }
         const scopeLabel = repoScope ? chalk.gray(` (repo: ${repoScope})`) : '';
         if (!json)
             outLog(chalk.cyan(`Syncing ${installed.length} ${agentLabel(agentId)} version(s)${scopeLabel}.`));
+        if (opts.dryRun) {
+            if (!quiet && !json) {
+                console.log(chalk.cyan(`Dry run — would sync ${agentLabel(agentId)} (${installed.length} version(s))${scopeLabel}:`));
+                if (selection) {
+                    for (const [k, v] of Object.entries(selection)) {
+                        const names = v === 'all' ? chalk.gray('(all)') : v.join(', ');
+                        console.log(chalk.gray(`  ${k}: ${names}`));
+                    }
+                }
+                else {
+                    console.log(chalk.gray('  (all resources)'));
+                }
+            }
+            if (json)
+                emitJson({ ok: true, mode: 'dry-run', agent: agentId, repo: repoScope, versions: installed, selection: selection ?? 'all' });
+            return;
+        }
         const versions = [];
         for (const v of installed) {
-            const result = syncResourcesToVersion(agentId, v, selection, { projectDir, cwd, force });
+            // A repo scope makes @all a full reconcile of that repo → prune resources
+            // it no longer provides. Bare @all (no repo) leaves selection undefined
+            // and falls through to the full-sync orphan sweep, so prune is a no-op
+            // there (it requires a caller selection).
+            const result = syncResourcesToVersion(agentId, v, selection, { projectDir, cwd, force, prune: !!repoScope, allowExecSurfaces: !!opts.allowExecSurfaces });
             versions.push({ version: v, result });
             if (!quiet && !json)
                 printSyncDetail(result, agentId, v, cwd);
@@ -459,6 +590,7 @@ async function runSync(agentSpec, repoArg, opts) {
                     subagents: result.subagents,
                     plugins: result.plugins,
                     workflows: result.workflows,
+                    pruned: result.pruned,
                 })),
             });
         }
@@ -489,17 +621,19 @@ async function runSync(agentSpec, repoArg, opts) {
                 return;
             }
             else {
+                // Multiple installed, no default — promoted to @all before reaching here.
+                // This branch is a safety net for unexpected flow; normal callers won't hit it.
                 failJson({
                     mode: 'agent',
                     agent: agentId,
                     error: `No default ${agentLabel(agentId)} version pinned.`,
                     installed,
+                    hint: `Use agents sync ${agentId}@all to sync every installed version, or agents sync ${agentId}@latest for the newest.`,
                 });
                 if (!json) {
-                    errLog(chalk.red(`No default ${agentLabel(agentId)} version pinned. Specify one:`));
-                    for (const v of installed) {
-                        errLog(chalk.gray(`  agents sync ${agentId}@${v}`));
-                    }
+                    errLog(chalk.red(`No default ${agentLabel(agentId)} version pinned.`));
+                    errLog(chalk.gray(`  Sync all:    agents sync ${agentId}@all`));
+                    errLog(chalk.gray(`  Sync newest: agents sync ${agentId}@latest`));
                 }
                 process.exitCode = 1;
                 return;
@@ -530,11 +664,12 @@ async function runSync(agentSpec, repoArg, opts) {
         runLaunchMode(agentId, version, cwd, quiet, json);
         return;
     }
-    // ---------- 3b. Repo-scoped single-version sync ----------
-    // An explicit --repo / positional repo is a targeted request, so skip the
-    // interactive preview and reconcile just that repo's resources.
-    if (repoScope) {
-        const scoped = buildRepoScopedSelection(repoScope, cwd);
+    // ---------- 3b. Repo-scoped or kind-filtered single-version sync ----------
+    // An explicit --repo / positional repo, or any per-kind flag, is a targeted
+    // request: skip the interactive preview and reconcile only the specified scope.
+    const kindFilter = parseKindSelection(opts);
+    if (repoScope || kindFilter) {
+        const scoped = buildSelection(repoScope ? [`${repoScope}:*`] : [], kindFilter ?? undefined, cwd);
         if (Object.keys(scoped).length === 0) {
             if (json) {
                 emitJson({
@@ -542,16 +677,28 @@ async function runSync(agentSpec, repoArg, opts) {
                     mode: 'agent',
                     agent: agentId,
                     version,
-                    repo: repoScope,
+                    ...(repoScope !== undefined ? { repo: repoScope } : {}),
                     note: 'nothing to sync',
                 });
             }
             else {
-                outLog(chalk.gray(`Nothing from repo '${repoScope}' to sync into ${agentLabel(agentId)}@${version}.`));
+                outLog(chalk.gray(`Nothing to sync${repoScope ? ` from repo '${repoScope}'` : ''} into ${agentLabel(agentId)}@${version}.`));
+            }
+            return;
+        }
+        if (opts.dryRun) {
+            if (!quiet && !json) {
+                console.log(chalk.cyan(`Dry run — would sync into ${agentLabel(agentId)}@${version}${repoScope ? ` (repo: ${repoScope})` : ''}:`));
+                for (const [k, v] of Object.entries(scoped)) {
+                    const names = v === 'all' ? chalk.gray('(all)') : v.join(', ');
+                    console.log(chalk.gray(`  ${k}: ${names}`));
+                }
             }
+            if (json)
+                emitJson({ ok: true, mode: 'dry-run', agent: agentId, version, repo: repoScope, selection: scoped });
             return;
         }
-        const result = syncResourcesToVersion(agentId, version, scoped, { projectDir, cwd, force });
+        const result = syncResourcesToVersion(agentId, version, scoped, { projectDir, cwd, force, prune: !!repoScope, allowExecSurfaces: !!opts.allowExecSurfaces });
         if (json) {
             emitJson(agentSyncJson(agentId, version, result, repoScope));
         }
@@ -606,7 +753,24 @@ async function runSync(agentSpec, repoArg, opts) {
         }
     }
     // ---------- 5. Run sync ----------
-    const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force });
+    if (opts.dryRun) {
+        if (!quiet && !json) {
+            console.log(chalk.cyan(`Dry run — would sync into ${agentLabel(agentId)}@${version}${repoScope ? ` (repo: ${repoScope})` : ''}:`));
+            if (selection) {
+                for (const [k, v] of Object.entries(selection)) {
+                    const names = v === 'all' ? chalk.gray('(all)') : v.join(', ');
+                    console.log(chalk.gray(`  ${k}: ${names}`));
+                }
+            }
+            else {
+                console.log(chalk.gray('  (all resources)'));
+            }
+        }
+        if (json)
+            emitJson({ ok: true, mode: 'dry-run', agent: agentId, version, repo: repoScope, selection: selection ?? 'all' });
+        return;
+    }
+    const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force, allowExecSurfaces: !!opts.allowExecSurfaces });
     // Compile project-scope rules into the workspace itself so each agent's
     // native loader picks up cwd/<INSTRUCTIONS_FILE>. projectDir is the
     // .agents/ directory; the workspace root is its parent.
@@ -661,6 +825,7 @@ function agentSyncJson(agent, version, result, repo) {
         plugins: result.plugins,
         workflows: result.workflows,
         projectSkipped: result.projectSkipped,
+        pruned: result.pruned,
     };
 }
 function anyResources(r) {
@@ -694,22 +859,37 @@ function printSyncDetail(result, agent, version, cwd) {
     if (result.workflows.length > 0)
         lines.push({ kind: 'workflows', items: result.workflows });
     const kept = formatKeptProjectResources(result.projectSkipped);
-    if (lines.length === 0) {
+    // Removals from source-deleted resources (RUSH-2438). Rendered even when
+    // nothing was added, so a reconcile that only pruned still reports it.
+    const prunedLines = Object.entries(result.pruned)
+        .filter(([, names]) => names.length > 0)
+        .map(([kind, names]) => ({ kind, items: names }));
+    if (lines.length === 0 && prunedLines.length === 0) {
         console.log(chalk.gray(`Already in sync — ${agentLabel(agent)}@${version}`));
         if (kept)
             console.log(chalk.gray(kept));
         return;
     }
-    console.log(chalk.green(`Synced to ${agentLabel(agent)}@${version}:`));
-    const kindWidth = Math.max(...lines.map(l => l.kind.length));
     const PREVIEW = 5;
-    for (const { kind, items } of lines) {
-        const padded = kind.padEnd(kindWidth);
+    const printKindLine = (label, items, width, color) => {
+        const padded = label.padEnd(width);
         const sorted = [...items].sort((a, b) => a.localeCompare(b));
         const preview = sorted.slice(0, PREVIEW).join(', ');
         const more = sorted.length > PREVIEW ? chalk.gray(`, +${sorted.length - PREVIEW} more`) : '';
-        const count = chalk.cyan(`(${sorted.length})`.padStart(5));
+        const count = color(`(${sorted.length})`.padStart(5));
         console.log(`  ${chalk.bold(padded)}  ${count}  ${chalk.gray(preview)}${more}`);
+    };
+    if (lines.length > 0) {
+        console.log(chalk.green(`Synced to ${agentLabel(agent)}@${version}:`));
+        const kindWidth = Math.max(...lines.map(l => l.kind.length));
+        for (const { kind, items } of lines)
+            printKindLine(kind, items, kindWidth, chalk.cyan);
+    }
+    if (prunedLines.length > 0) {
+        console.log(chalk.yellow(`Pruned from ${agentLabel(agent)}@${version} (removed from source):`));
+        const kindWidth = Math.max(...prunedLines.map(l => l.kind.length));
+        for (const { kind, items } of prunedLines)
+            printKindLine(kind, items, kindWidth, chalk.yellow);
     }
     if (kept)
         console.log(chalk.gray(kept));

package/dist/commands/teams.d.ts

@@ -87,6 +87,19 @@ export declare function decideTeamMessageRoute(status: AgentStatus, hasMessage:
  * owning this worktree.
  */
 export declare function tearDownOrphanWorktree(mgr: AgentManager, baseCwd: string, name: string): Promise<void>;
+/**
+ * The blocking message when `teams add` is pointed at a stale checkout. Pure so
+ * the guidance is pinned by tests (mirrors `remoteCwdOnAddError`): it MUST name
+ * how far behind, tell the caller to sync with remote main, and mention `--confirm`
+ * as the override.
+ */
+export declare function staleRepoError(params: {
+    team: string;
+    where: string;
+    behind: number;
+    base: string;
+    sync: string;
+}): string;
 /**
  * Register the generic cloud dispatcher — staged cloud teammates get
  * dispatched when their --after deps resolve, using repo/branch stored on