@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/sync.js

@@ -1,35 +1,3 @@
-/**
- * `agents sync` — synchronize central resources into an installed agent version.
- *
- * Forms:
- *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets opt-in)
- *   agents sync status                                  # report fleet drift (former top-level `agents status`)
- *   agents sync --repos|--secrets                       # umbrella: fetch only those, then reconcile
- *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
- *   agents sync --local                                 # umbrella: reconcile all, no fetch
- *   agents sync system                                  # one repo: git pull --rebase (pull-only mirror)
- *   agents sync user                                    # one repo: git pull --rebase + push
- *   agents sync claude                                  # one agent: uses default/sole installed version
- *   agents sync claude@2.1.142                          # one agent: explicit version
- *   agents sync claude@latest                           # one agent: newest installed
- *   agents sync claude@oldest                           # one agent: oldest installed
- *   agents sync claude@pinned   (= claude@default)      # one agent: the pinned default version
- *   agents sync --agent claude --agent-version 2.1.142  # legacy form, still supported
- *
- * The umbrella stages live in lib/sync-umbrella.ts; this file dispatches to them
- * when no agent is given.
- *
- * In a TTY the command previews available/new resources and lets the user
- * select what to sync (same prompts shown after `agents add`). Pass
- * --yes for non-interactive auto-sync, --force to re-sync when nothing
- * has changed, --quiet for total silence.
- *
- * Hot path:
- *   --launch is the shim entry point. It skips version-home reconciliation
- *   and runs only the cheap project-scoped work (rules compile, workspace
- *   resource mirror, per-scope plugin marketplaces). Filesystem-only,
- *   sub-50ms steady state. Keep changes here surgical.
- */
 import * as path from 'path';
 import { Option } from 'commander';
 import chalk from 'chalk';
@@ -49,19 +17,9 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { syncRepoGit, adoptUserRepoIfNeeded, recordUserRepoRemote, resolveUserRepoRemoteUrl } from '../lib/git.js';
 import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../lib/state.js';
 import { registerStatusCommand } from './status.js';
-/** Emit one JSON object to stdout for `--json` callers / fleet fan-out. */
 function emitJson(payload) {
     console.log(JSON.stringify(payload));
 }
-/**
- * Post-reconcile verification (PHNX-3186): after a sync writes into a set of
- * version homes, re-read each home and confirm it now matches its resolved
- * sources. The `agents sync` success line MUST NOT read "reconciled" while the
- * drift it was asked to fix stays put. Any residual drifted/missing resource
- * sets a non-zero exit code and — outside `--json` — names the exact unfixed
- * drift so the operator sees what did not converge instead of a false ✓. Orphans
- * are excluded (sync never removes them). Returns the residual for `--json`.
- */
 function verifyReconciled(pairs, cwd) {
     const residual = [];
     const seen = new Set();
@@ -74,16 +32,8 @@ function verifyReconciled(pairs, cwd) {
         if (r)
             residual.push(r);
     }
-    // Residual drift is reported loudly via `ok:false` + the printed ⚠ block, but
-    // does NOT change the exit code — matching the declined-write precedent
-    // (RUSH-2700). The fleet fan-out (`agents sync --device all`) THROWS on a
-    // non-zero peer exit (`hosts/passthrough.ts`), discarding that box's JSON, so a
-    // non-zero exit here would hide the very `residualDrift` payload it emitted.
-    // Callers that must treat an incomplete sync as failure read `ok`/`residualDrift`
-    // from `--json`, exactly as they already do for declines.
     return residual;
 }
-/** Print the residual-drift block naming exactly what did not converge. */
 function printResidual(residual, errLog) {
     if (residual.length === 0)
         return;
@@ -93,17 +43,6 @@ function printResidual(residual, errLog) {
         errLog(chalk.yellow(`  ${line}`));
     errLog(chalk.gray('  Re-run the sync; a gap that survives a re-run is a real unreconcilable drift — report it.'));
 }
-/**
- * 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;
@@ -119,7 +58,6 @@ function parseKindSelection(opts) {
     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);
@@ -146,10 +84,6 @@ function parseKindSelection(opts) {
         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);
@@ -174,7 +108,6 @@ export function addSelectorOptions(cmd) {
     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) {
     const cmd = addHostOption(program.command('sync [agentSpec] [repo]'))
         .summary('Make this machine current, or sync resources into one agent')
@@ -191,7 +124,6 @@ export function registerSyncCommand(program) {
         .option('--dry-run', 'Show what would be synced without making any changes — requires an agent scope (e.g. agents sync claude --dry-run); the umbrella verb refuses it', 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 --device 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)
         .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
         .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
@@ -200,19 +132,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);
-    // `status` is a reserved subcommand (not an agentSpec/repo positional).
     registerStatusCommand(cmd);
 }
-/**
- * Resolve a DotAgent repo name to its git working directory + whether local
- * commits should be pushed. `system` is a pull-only mirror of the npm-shipped
- * upstream; `user` and enabled extra aliases are user-owned and push. `project`
- * (and unknown names) return null — the project `.agents/` lives inside the
- * user's own project repo and is not independently git-synced here.
- */
 function resolveRepoGitTarget(repo) {
     if (repo === 'system')
         return { dir: getSystemAgentsDir(), push: false };
@@ -223,12 +145,6 @@ function resolveRepoGitTarget(repo) {
         return { dir: extra.dir, push: true };
     return null;
 }
-/**
- * `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);
     if (!target) {
@@ -249,10 +165,6 @@ async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
     }
     if (!quiet && !json)
         outLog(chalk.bold(`Syncing ${repo} repo…`) + chalk.gray(` (${target.dir})`));
-    // Self-heal a non-git / partial user checkout in place before the git sync
-    // (PHNX-3301) — otherwise syncRepoGit hard-fails with "Not a git repo" and the
-    // only fix is a destructive re-clone. Only the user repo adopts: system is
-    // cloned by setup, extras by `repo add`.
     if (repo === 'user') {
         const adopted = await adoptUserRepoIfNeeded(target.dir);
         if (adopted && !adopted.success) {
@@ -291,9 +203,6 @@ async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
         process.exitCode = 1;
         return;
     }
-    // Record the resolved remote so a future partial box (lost .git) can adopt in
-    // place without the operator re-typing the URL (PHNX-3301). Before the --json
-    // early-return so the record is refreshed on every healthy sync, JSON or not.
     if (repo === 'user') {
         const u = resolveUserRepoRemoteUrl(target.dir);
         if (u)
@@ -314,7 +223,6 @@ async function runRepoGitSync(repo, quiet, outLog, errLog, json = false) {
         outLog(chalk.green(`✓ ${repo} → ${result.commit}${note}`));
     }
 }
-/** Human label for a repo choice in the interactive picker. */
 function repoChoiceLabel(repo) {
     switch (repo) {
         case 'system': return 'system  — shared, npm-shipped defaults';
@@ -323,13 +231,6 @@ function repoChoiceLabel(repo) {
         default: return `${repo}  — extra repo`;
     }
 }
-/**
- * Interactive bare `agents sync` (TTY, no flags): two checklists — which
- * DotAgent repos to sync FROM, and which installed agents to sync INTO. Then
- * freshen the selected git-syncable repos (pull-only) and reconcile the chosen
- * repos' resources into each selected agent's default version, registering
- * hooks so synced hook scripts actually fire.
- */
 async function runInteractiveReconcile(opts, outLog, errLog) {
     const { checkbox } = await import('@inquirer/prompts');
     const cwd = opts.cwd || process.cwd();
@@ -366,13 +267,10 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         }
         throw e;
     }
-    // 1. Freshen the selected git-syncable repos (pull-only; `project` has no
-    //    independent remote). Failures are non-fatal — reconcile still runs.
     for (const repo of repos) {
         const target = resolveRepoGitTarget(repo);
         if (!target)
             continue;
-        // Adopt a non-git / partial user checkout in place before pulling (PHNX-3301).
         if (repo === 'user') {
             const adopted = await adoptUserRepoIfNeeded(target.dir);
             if (adopted?.success) {
@@ -395,18 +293,12 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         else
             outLog(chalk.yellow(`  ! ${repo}: ${(res.error ?? 'pull failed').split('\n')[0]}`));
     }
-    // Central browser-profile claiming is the standalone `browser` CLI's now
-    // (PHNX-4101): `browser profiles claim` / `browser profiles prune` own it.
-    // agents-cli no longer evicts central `browser:` tombstones on sync.
-    // 2. One selection spanning the chosen repos.
     const selection = mergeRepoScopedSelections(repos, cwd);
     const hasResources = selection.memory === 'all' || Object.entries(selection).some(([kind, v]) => kind !== 'memory' && Array.isArray(v) && v.length > 0);
     if (!hasResources) {
         outLog(chalk.gray(`Nothing from ${repos.join(', ')} to sync.`));
         return;
     }
-    // 3. Reconcile into each selected agent's default (or sole) version, then
-    //    register hooks so synced hook scripts fire.
     const hookManifest = parseHookManifest();
     const hookCapable = new Set(capableAgents('hooks'));
     const touched = [];
@@ -421,40 +313,16 @@ async function runInteractiveReconcile(opts, outLog, errLog) {
         }
         touched.push({ agent: agentId, version });
     }
-    // Post-reconcile repair (the superset of the old `doctor --fix`): heal live-home
-    // gaps, re-wire hooks the diff left behind, and repair managed hook runtime
-    // shims for exactly the versions this reconcile touched. Always interactive
-    // here, so render its detail freely.
     for (const t of touched) {
         const repair = await repairAfterSync({ agent: t.agent, versions: [t.version], cwd });
         renderRepairAfterSync(repair, outLog);
     }
-    // Bare `agents sync` at a TTY is the umbrella verb — after per-agent repair,
-    // run one no-agent pass. This purges stale/legacy agents-cli copies ONLY when
-    // the user passed `--prune-clis` (the purge is never automatic); otherwise it is
-    // a cheap re-diff no-op over the just-reconciled homes.
     const umbrellaRepair = await repairAfterSync({ cwd, pruneClis: !!opts.pruneClis });
     renderRepairAfterSync(umbrellaRepair, outLog);
     if (repairHadFailures(umbrellaRepair))
         process.exitCode = 1;
 }
-/**
- * The umbrella verb: bare `agents sync` (no agent) makes this machine current.
- * Resolves the flags + a secrets passphrase (env-only for now; tokenized auth
- * arrives with `agents secrets vault unlock`) and runs the fetch+reconcile stages, then prints
- * a one-line summary. Stage failures are non-fatal and surfaced as warnings.
- */
 async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
-    // `--dry-run` on the umbrella verb is NOT supported and must fail LOUD before
-    // touching anything (PHNX-3923). The umbrella composes stages that only exist
-    // as mutating operations — repo `git pull`, a full `refresh()` reconcile into
-    // every installed version home, central browser-profile eviction, device sync,
-    // and `repairAfterSync` — none of which carry a non-mutating preview mode. The
-    // old code ignored `opts.dryRun` entirely, ran `runUmbrellaSync` + evict +
-    // repair, and so MUTATED every native home despite `--dry-run`. Rather than
-    // ship a partial preview that silently skips the stages it cannot model (a
-    // lying "would sync" that contradicts the flag's promise), refuse here and
-    // point at the scoped path, which DOES honor `--dry-run` non-destructively.
     if (opts.dryRun) {
         const installed = MANAGED_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
         const example = installed[0] ?? 'claude';
@@ -474,11 +342,6 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         process.exitCode = 1;
         return;
     }
-    // Interactive bare `agents sync` (a TTY, no --yes, no scope flag) drops into
-    // the two-checklist picker: which repos to sync from, which agents to sync
-    // into. Any explicit flag, --yes, or --json keeps the non-interactive path.
-    // --json is a machine consumer (and the fleet fan-out injects it), so never
-    // open a picker under it.
     const kindSelection = parseKindSelection(opts);
     const anyExplicitFlag = !!(opts.repos || opts.secrets || opts.cloud || opts.local || kindSelection);
     if (!quiet && !json && !opts.yes && !anyExplicitFlag && isInteractiveTerminal()) {
@@ -490,16 +353,9 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
         repos: opts.repos,
         secrets: opts.secrets,
         cloud: opts.cloud,
-        // A resource selector is a local reconcile unless the caller explicitly
-        // asks to fetch repos/secrets first. This keeps replacements such as
-        // `sync --mcp demo` scoped like the retired resource verb.
         local: opts.local || (!!kindSelection && !opts.repos && !opts.secrets && !opts.cloud),
     };
-    // Same chokepoint as `agents secrets push/pull` — prefers AGENTS_SYNC_PASSPHRASE,
-    // falls back to the deprecated master-key name with a single warning.
     const passphrase = resolveSyncPassphraseFromEnv().value ?? undefined;
-    // Fleet fan-out only injects --json (not --yes). Treat --json as non-interactive
-    // so refresh({ skipPrompts }) never tries to prompt over SSH.
     const yes = !!opts.yes || json;
     if (!quiet && !json)
         outLog(chalk.bold('Syncing this machine…'));
@@ -508,39 +364,23 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             flags,
             yes,
             passphrase,
-            // quiet under --json so refresh() cannot pollute the JSON stdout the fleet parses.
             quiet: quiet || json,
             selection: kindSelection,
             allowExecSurfaces: !!opts.allowExecSurfaces,
             log: (msg) => { if (!quiet && !json)
                 outLog(chalk.gray(`  ${msg}`)); },
         });
-        // Central browser-profile claiming moved to the standalone `browser` CLI
-        // (PHNX-4101: `browser profiles claim` / `prune`), so `agents sync` no longer
-        // drains the central `browser:` tombstone.
-        // Post-reconcile verification (PHNX-3186): re-read every version the reconcile
-        // wrote into and confirm it now matches source. Without this the umbrella
-        // printed `✓ sync: reconciled` unconditionally, the exact false-success the
-        // ticket reports. Residual drift downgrades the line and sets a non-zero exit.
         const residual = result.reconciled && !kindSelection
             ? verifyReconciled(result.reconciledVersions.map((r) => ({ agent: r.agent, version: r.version })), cwd)
             : [];
-        // Post-reconcile repair, machine-wide: no agent scope → heal every installed
-        // agent, re-wire hooks the diff left behind, and repair managed hook runtime
-        // shims. The stale-CLI purge runs ONLY with `--prune-clis` (never automatic).
-        // Skipped under --cloud (fetch-only: nothing was reconciled to repair).
         const repair = opts.cloud || kindSelection
             ? null
             : await repairAfterSync({ cwd, pruneClis: !!opts.pruneClis });
-        // A repair that left something for a human (an unresolvable shim, a failed
-        // rewire/purge) is a non-zero outcome, same as the deleted `doctor --fix`.
         const repairFailed = repair !== null && repairHadFailures(repair);
         if (repairFailed)
             process.exitCode = 1;
         if (json) {
             emitJson({
-                // A refused resource, residual drift, OR a repair failure is not a clean
-                // sync (RUSH-2700 + PHNX-3186).
                 ok: result.declined.length === 0 && residual.length === 0 && !repairFailed,
                 mode: 'umbrella',
                 plan: result.plan,
@@ -564,9 +404,6 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
             if (result.secrets) {
                 parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
             }
-            // Only claim "reconciled" when the reconcile actually converged. Residual
-            // drift is already printed loudly by verifyReconciled above; reflect it in
-            // the one-line summary rather than a bare ✓.
             if (result.reconciled)
                 parts.push(residual.length === 0 ? 'reconciled' : 'reconcile INCOMPLETE');
             const symbol = residual.length === 0 ? chalk.green('✓') : chalk.yellow('⚠');
@@ -592,37 +429,18 @@ async function runUmbrella(opts, quiet, outLog, errLog, json = false) {
 }
 async function runSync(agentSpec, repoArg, opts) {
     const json = !!opts.json;
-    // --json is a machine consumer: suppress human stdout/stderr chatter so the
-    // single JSON object on stdout stays parseable for fleet fan-out.
     const quiet = !!opts.quiet || json;
     const errLog = (msg) => { if (!quiet)
         console.error(msg); };
     const outLog = (msg) => { if (!quiet)
         console.log(msg); };
-    // Failures under --json still need a structured line on stdout so fleet
-    // fan-out's safeJsonParse gets a real object (not "unknown option").
     const failJson = (payload) => {
         if (json)
             emitJson({ ok: false, ...payload });
     };
-    // ---------- 1. Resolve agent + version ----------
     let agentId;
     let version;
-    // A positional @selector typed by the user (latest/oldest/pinned/default/
-    // all/explicit). parseAgentSpec defaults a missing version to 'latest', so a
-    // bare `agents sync claude` and `agents sync claude@latest` are
-    // indistinguishable after parsing — we only treat the version as a selector
-    // when an '@' was actually typed, keeping bare `claude` on the
-    // default-version path.
     let selector;
-    // Repo-level git sync: a DotAgent repo name given ALONE (no agent, no second
-    // positional) means "git-sync that repo" — pull --rebase, and push for
-    // 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}`));
@@ -649,12 +467,8 @@ 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;
     if (repoScope !== undefined) {
         const known = listRepoNames();
@@ -687,23 +501,15 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     }
     if (opts.agentVersion) {
-        // Legacy flag and the launch-shim hot path (`--agent-version <concrete>`):
-        // pass through verbatim. Selector aliases are a positional-spec feature.
         version = opts.agentVersion;
     }
     if (!agentId) {
-        // No agent specified → the umbrella verb: make this machine current
-        // (fetch repos + secrets + sessions, then reconcile all installed agents).
-        // This is the path fleet fan-out (`--device all`) hits with injected --json.
         await runUmbrella(opts, quiet, outLog, errLog, json);
         return;
     }
     const projectDir = opts.projectDir;
     const cwd = opts.cwd || process.cwd();
     const force = !!opts.force;
-    // RUSH-2471: self-heal any version pointer (global/isolated default, ~/.<agent>
-    // symlink) left aimed at a version that is no longer installed BEFORE resolving
-    // the version to sync. Skipped on --dry-run since it mutates on-disk pointers.
     let healed = {};
     if (!opts.dryRun) {
         healed = await healDanglingVersionPointers(agentId, cwd);
@@ -722,9 +528,6 @@ async function runSync(agentSpec, repoArg, opts) {
         }
     }
     const healedPointers = Object.keys(healed).length > 0 ? { healedPointers: healed } : {};
-    // 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) {
@@ -733,9 +536,6 @@ async function runSync(agentSpec, repoArg, opts) {
                 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 optional repo scope and per-kind flags.
     if (selector === 'all') {
         const installed = listInstalledVersions(agentId);
         if (installed.length === 0) {
@@ -781,26 +581,16 @@ async function runSync(agentSpec, repoArg, opts) {
         }
         const versions = [];
         for (const v of installed) {
-            // 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);
         }
-        // Verify each version actually converged; a repo-scoped sync only touched
-        // that repo's kinds, so skip verification there (the other layers legitimately
-        // still differ and are not this run's responsibility).
         const residual = repoScope
             ? []
             : verifyReconciled(versions.map(({ version: v }) => ({ agent: agentId, version: v })), cwd);
         if (!quiet && !json)
             printResidual(residual, errLog);
-        // Post-reconcile repair over exactly the versions just reconciled (the
-        // superset of the old `doctor --fix`). Runs under --json too (fleet fan-out);
-        // only its human detail is gated on !quiet && !json.
         const allRepair = await repairAfterSync({ agent: agentId, versions: installed, cwd });
         if (!quiet && !json)
             renderRepairAfterSync(allRepair, outLog);
@@ -809,8 +599,6 @@ async function runSync(agentSpec, repoArg, opts) {
             process.exitCode = 1;
         if (json) {
             emitJson({
-                // Any version that refused a write, any residual drift, or a repair
-                // failure makes the whole run not-ok (RUSH-2700 + PHNX-3186).
                 ok: versions.every(({ result }) => result.declined.length === 0) && residual.length === 0 && !allRepairFailed,
                 mode: 'agent-all',
                 agent: agentId,
@@ -836,11 +624,6 @@ async function runSync(agentSpec, repoArg, opts) {
         }
         return;
     }
-    // ---------- 2. Resolve version (project pin → global default → sole installed) ----------
-    // A positional @selector wins over the default-resolution below.
-    //   @latest / @oldest        → newest / oldest installed (process.exit if none)
-    //   @pinned / @default       → undefined → fall through to the default path
-    //   @x.y.z                   → that version (process.exit if not installed)
     if (selector !== undefined && !version) {
         version = resolveVersionAlias(agentId, selector);
     }
@@ -861,8 +644,6 @@ 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,
@@ -899,14 +680,10 @@ async function runSync(agentSpec, repoArg, opts) {
         process.exitCode = 1;
         return;
     }
-    // ---------- 3. --launch mode bypasses everything below ----------
     if (opts.launch) {
         runLaunchMode(agentId, version, cwd, quiet, json);
         return;
     }
-    // ---------- 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);
@@ -953,8 +730,6 @@ async function runSync(agentSpec, repoArg, opts) {
         }
         return;
     }
-    // ---------- 4. Decide selection (interactive preview vs auto) ----------
-    // --json forces non-interactive (machine consumer / fleet fan-out).
     const yes = !!opts.yes || json;
     const interactive = !quiet && !yes && isInteractiveTerminal();
     let selection;
@@ -983,11 +758,6 @@ async function runSync(agentSpec, repoArg, opts) {
                 selection = userSelection;
             }
             else if (!force) {
-                // Tracked resources match source — but a generated hook shim can still be
-                // broken on an otherwise in-sync version (the yosemite-s1 class), and
-                // syncResourcesToVersion never generates it. Run the repair pass BEFORE
-                // the early return so a broken shim is still fixed on bare
-                // `agents sync <agent>`, then report what (if anything) it touched.
                 const repair = await repairAfterSync({ agent: agentId, versions: [version], cwd });
                 if (repairChangedAnything(repair)) {
                     renderRepairAfterSync(repair, outLog);
@@ -1000,8 +770,6 @@ async function runSync(agentSpec, repoArg, opts) {
                     process.exitCode = 1;
                 return;
             }
-            // else: --force on a fully-synced version → selection stays undefined,
-            // syncResourcesToVersion falls through to its pattern-based full sync.
         }
         catch (e) {
             if (isPromptCancelled(e)) {
@@ -1011,7 +779,6 @@ async function runSync(agentSpec, repoArg, opts) {
             throw e;
         }
     }
-    // ---------- 5. Run sync ----------
     if (opts.dryRun) {
         if (!quiet && !json) {
             console.log(chalk.cyan(`Dry run — would sync into ${agentLabel(agentId)}@${version}${repoScope ? ` (repo: ${repoScope})` : ''}:`));
@@ -1030,21 +797,11 @@ async function runSync(agentSpec, repoArg, opts) {
         return;
     }
     const result = syncResourcesToVersion(agentId, version, selection, { projectDir, cwd, force, allowExecSurfaces: !!opts.allowExecSurfaces });
-    // Post-reconcile verification (PHNX-3186). Only for a FULL reconcile
-    // (`!selection`): an interactive subset-selection deliberately touched only the
-    // picked kinds, so the rest legitimately still differs and is not this run's
-    // failure. This is the exact path `agents sync <agent>[@version]` takes.
     const residual = selection ? [] : verifyReconciled([{ agent: agentId, version }], cwd);
-    // Post-reconcile repair over the single version just reconciled (the superset
-    // of the old `doctor --fix`). Runs under --json too; only its human detail is
-    // gated on the non-quiet path below.
     const singleRepair = await repairAfterSync({ agent: agentId, versions: [version], cwd });
     const singleRepairFailed = repairHadFailures(singleRepair);
     if (singleRepairFailed)
         process.exitCode = 1;
-    // 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.
     let projectCompile = null;
     if (projectDir) {
         const projectRoot = path.dirname(projectDir);
@@ -1071,7 +828,6 @@ async function runSync(agentSpec, repoArg, opts) {
     }
     if (quiet)
         return;
-    // ---------- 6. Detailed output ----------
     printSyncDetail(result, agentId, version, cwd);
     printResidual(residual, errLog);
     renderRepairAfterSync(singleRepair, outLog);
@@ -1085,12 +841,8 @@ async function runSync(agentSpec, repoArg, opts) {
         console.log(chalk.yellow(`Skipped (user-authored, not overwritten): ${projectCompile.skippedClobber.join(', ')}`));
     }
 }
-/** Stable `--json` payload for a single agent@version resource sync. */
 function agentSyncJson(agent, version, result, repo) {
     return {
-        // A refused resource is not a clean sync. `ok` was hardcoded true, so the
-        // machine surface (`--host all` fan-out) reported success for exactly the
-        // silent no-op this changed (RUSH-2677).
         ok: result.declined.length === 0,
         mode: 'agent',
         agent,
@@ -1115,11 +867,7 @@ function anyResources(r) {
         r.mcp.length + r.permissions.length + r.subagents.length +
         r.plugins.length + r.workflows.length > 0;
 }
-/** Format the post-sync detail output: per-kind count + a name preview. */
 function printSyncDetail(result, agent, version, cwd) {
-    // Booleans in SyncResult (commands, skills, hooks, permissions) carry no
-    // name list. Re-derive ground truth from the version home so the user
-    // sees what's actually present after the sync.
     const synced = getActuallySyncedResources(agent, version, { cwd });
     const lines = [];
     if (result.commands)
@@ -1141,8 +889,6 @@ function printSyncDetail(result, agent, version, cwd) {
     if (result.workflows.length > 0)
         lines.push({ kind: 'workflows', items: result.workflows });
     const kept = formatKeptProjectResources(result.projectSkipped);
-    // 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 }));
@@ -1173,8 +919,6 @@ function printSyncDetail(result, agent, version, cwd) {
         for (const { kind, items } of prunedLines)
             printKindLine(kind, items, kindWidth, chalk.yellow);
     }
-    // A resource agents-cli refused to write is reported, never swallowed — an
-    // empty synced list on its own reads as "nothing to do" (RUSH-2677).
     if (result.declined.length > 0) {
         console.log(chalk.yellow(`Not written to ${agentLabel(agent)}@${version}:`));
         for (const reason of result.declined)

package/dist/commands/teams-picker.d.ts

@@ -3,14 +3,11 @@ export interface TeamRow {
     team: TaskInfo;
     agents: AgentStatusDetail[];
     description?: string;
-    /** Short id of the session that spawned this team, when the index knows it. */
     spawnedBy?: string;
 }
 interface PickedTeam {
     team: string;
 }
-/** Print a non-interactive team table to stdout (used when output is piped). */
 export declare function printTeamTable(rows: TeamRow[]): void;
-/** Show an interactive team picker with fuzzy search and return the selected team name. */
 export declare function teamPicker(rows: TeamRow[], initialSearch?: string): Promise<PickedTeam | null>;
 export {};