@phnx-labs/agents-cli 1.22.75 → 1.22.77

package/dist/commands/doctor.d.ts

@@ -15,11 +15,12 @@
  *      unified diff body for each divergent file. Mirrors the resolution that
  *      the shim drives at runtime: project > user > system > extras.
  *
- * Read-only by default: doctor diagnoses, it doesn't mutate. Pass `--fix` to
- * heal the gaps it finds (install missing resources, repair Claude-invalid
- * plugin manifests, refresh stale plugins, reconcile drift). Run
- * `agents prune cleanup` to act on orphan readouts, or just launch the agent to
- * apply pending sync.
+ * Read-only always: doctor diagnoses, it never mutates. To fix the gaps it
+ * finds — install missing resources, repair Claude-invalid plugin manifests,
+ * refresh stale plugins, reconcile drift, repair hook runtime shims — run
+ * `agents sync <agent>@all` (the one fixer, a superset of the old `doctor
+ * --fix`). Run `agents prune cleanup` to act on orphan readouts. `--fix` is a
+ * deprecated no-op that now errors with a pointer to `agents sync`.
  */
 import type { Command } from 'commander';
 import { type FleetInventory } from '../lib/devices/fleet-divergence.js';

package/dist/commands/doctor.js

@@ -4,7 +4,7 @@ import { addHostOption } from '../lib/hosts/option.js';
 import { buildRemoteAgentsInvocation } from '../lib/hosts/remote-cmd.js';
 import { loadDevices } from '../lib/devices/registry.js';
 import { fanOutDevices, planFleetTargets, remoteFleetTargets } from '../lib/devices/fleet.js';
-import { enterDoctorOverviewGate, invalidateDoctorOverviewCache, writeDoctorOverviewCache } from '../lib/devices/doctor-overview-cache.js';
+import { enterDoctorOverviewGate, writeDoctorOverviewCache } from '../lib/devices/doctor-overview-cache.js';
 import { fleetDialTarget } from '../lib/devices/connect.js';
 import { compareFleetInventories, FLEET_HOOK_RUNTIME_STATES } from '../lib/devices/fleet-divergence.js';
 import { collectLocalFleetInventory } from '../lib/devices/fleet-inventory.js';
@@ -23,7 +23,7 @@ import { getVersionHomePath, listInstalledVersions, } from '../lib/installations
 import { resolveAgentTargets, AgentSpecError } from '../lib/agent-spec/index.js';
 import { loadManifest, isStale } from '../lib/staleness/index.js';
 import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
-import { checkVersionHookWiring, inspectDuplicateVersionHooks, registerHooksToSettings, repairManagedHookRuntimeArtifacts } from '../lib/hooks/install.js';
+import { inspectDuplicateVersionHooks } from '../lib/hooks/install.js';
 import { inspectReservedAuthBundle } from '../lib/secrets/bundles.js';
 import { isVersionIsolated } from '../lib/installations/versions.js';
 import { computeDrift, checkSyncStatus, countOrphans, computeSourceBehind } from '../lib/drift.js';
@@ -33,18 +33,13 @@ import { probeOwnerSink } from '../lib/channels/owner-sink.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus, listCliStatusAsync } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
-import { heal, healChangedAnything } from '../lib/heal.js';
 import { getEffectiveExecutionPolicy } from '../lib/platform/winpath.js';
 import { auditWindowsSshEnrollment, diagnoseWindowsSshFailure } from '../lib/devices/windows-ssh-enrollment.js';
 import { scanUserRcFiles, masterPassphraseInEnv } from '../lib/secrets/rc-hygiene.js';
 import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 import { readRepoBehindMarkers } from '../lib/auto-pull.js';
 import { detectAgentsBinaryShadows } from '../lib/binary-shadow.js';
-import { remediateStaleAgentsCliInstalls, resolveRunningPackageRoot, } from '../lib/self-update.js';
 import * as fs from 'fs';
-import * as path from 'path';
-import { fileURLToPath } from 'url';
-const __doctorDirname = path.dirname(fileURLToPath(import.meta.url));
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
 function collapseWhitespace(s) {
@@ -521,7 +516,7 @@ function parseTargetArg(arg) {
     const agent = resolveAgentName(agentPart);
     if (!agent)
         return { error: formatAgentError(agentPart) };
-    // No qualifier → non-isolated sweep of every installed version; --fix uses the non-isolated path
+    // No qualifier → diagnose every installed version of the agent.
     if (!qualifier) {
         const versions = listInstalledVersions(agent);
         if (versions.length === 0)
@@ -659,11 +654,8 @@ function readExpectedForDiff(kind, row) {
         return null;
     return safeRead(row.sourcePath);
 }
-// Family of agents whose hooks re-wire through registerHooksToSettings into a
-// Claude-style settings.json (matches checkVersionHookWiring's supported set).
-const HOOK_WIRING_FIX_AGENTS = ['claude', 'droid'];
-/** Categories `--fix` reconciles (vs. `agents repo pull` for a behind source, or
- *  `agents prune cleanup` for an orphan). Drives the heal footer. */
+/** Categories `agents sync` reconciles (vs. `agents repo pull` for a behind
+ *  source, or `agents prune cleanup` for an orphan). Drives the heal footer. */
 const AUTO_FIXABLE_CATEGORIES = new Set([
     'hook-runtime-broken', 'unwired-hook', 'settings-missing', 'settings-unparseable', 'missing', 'divergent', 'stale', 'never-synced',
 ]);
@@ -693,8 +685,10 @@ function missingResourceSeverity(kind) {
 export function computeVerdict(report) {
     const issues = [];
     const idLabel = `${report.agent}@${report.version}`;
-    const fixCmd = `agents doctor ${idLabel} --fix`;
-    const syncCmd = `agents sync ${idLabel} --yes`;
+    // doctor diagnoses; `agents sync` fixes. Every auto-fixable finding points at
+    // the one fixer — a command sync can actually deliver (asserted in the tests).
+    const fixCmd = `agents sync ${idLabel} --yes`;
+    const syncCmd = fixCmd;
     // ── critical: settings.json / unwired hooks (silent breakage) ──
     const w = report.hookWiring;
     for (const issue of w?.runtimeBroken ?? []) {
@@ -897,7 +891,7 @@ export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, d
             issues.push({
                 severity: 'critical', category: 'hook-runtime-broken', subject: label,
                 impact: `${brokenRuntime} generated hook wrapper${brokenRuntime === 1 ? '' : 's'} unusable; affected hooks cannot run`,
-                fix: `agents doctor ${row.agent}@${row.version} --fix`,
+                fix: `agents sync ${row.agent}@${row.version} --yes`,
                 text: `${label} ${brokenRuntime} hook runtime broken`, color: 'red',
             });
         }
@@ -931,7 +925,7 @@ export function computeOverviewHealth(syncRows, orphanRows, repoBehindMarkers, d
             issues.push({
                 severity: 'warning', category: 'stale', subject: label,
                 impact: 'sources changed since last sync',
-                fix: `agents doctor ${row.agent}@${row.version} --fix`,
+                fix: `agents sync ${row.agent}@${row.version} --yes`,
                 text: `${label} stale`, color: 'yellow',
             });
         }
@@ -1040,247 +1034,16 @@ function renderTargetText(report, options) {
     }
     console.log();
     const verdict = computeVerdict(report);
-    // A source layer behind origin is healed by `agents repo pull`, not `--fix` —
+    // A source layer behind origin is healed by `agents repo pull`, not by sync —
     // the per-issue fix already names the right command, so the heal footer only
-    // shows when something is genuinely `--fix`-able (never in the source-behind or
+    // shows when something is genuinely sync-fixable (never in the source-behind or
     // orphan-only case, where it would mislead).
     const hooksWired = report.hookWiring?.supported ? ' · hooks wired' : '';
     renderHealthBlock(verdict, {
         healthySummary: `${verdict.reconciled} resource${verdict.reconciled === 1 ? '' : 's'} reconciled${hooksWired} · sources current`,
-        healFix: verdictIsAutoFixable(verdict) ? `agents doctor ${report.agent}@${report.version} --fix` : undefined,
+        healFix: verdictIsAutoFixable(verdict) ? `agents sync ${report.agent}@${report.version} --yes` : undefined,
     });
 }
-// ─── fix / heal mode ───────────────────────────────────────────────────────────
-function renderHealText(result) {
-    for (const r of result.repairedManifests) {
-        console.log(`  ${chalk.green('repair')}  plugin ${chalk.bold(r.plugin)} ${chalk.gray(`— dropped invalid ${r.droppedFields.join(', ')} field`)}`);
-    }
-    for (const r of result.refreshedPlugins) {
-        console.log(`  ${chalk.green('refresh')} plugin ${chalk.bold(r.plugin)}  ${chalk.gray(`${r.from} → ${r.to}`)}`);
-    }
-    for (const s of result.skippedPlugins) {
-        const why = s.reason === 'modified'
-            ? `locally modified — left as-is (run \`agents plugins update ${s.plugin}\` to force)`
-            : `no baseline recorded — left as-is (run \`agents plugins update ${s.plugin}\` to adopt)`;
-        console.log(`  ${chalk.yellow('hold  ')} plugin ${chalk.bold(s.plugin)}  ${chalk.gray(`${s.from} → ${s.upstream} available; ${why}`)}`);
-    }
-    for (const v of result.versions) {
-        const label = `${AGENT_NAMES[v.agent] || v.agent}@${v.version}`;
-        if (v.healed.length === 0 && v.skipped.length === 0)
-            continue;
-        const byKind = new Map();
-        for (const h of v.healed)
-            byKind.set(h.kind, (byKind.get(h.kind) ?? 0) + 1);
-        const parts = Array.from(byKind, ([k, n]) => `${n} ${k}`);
-        if (v.healed.length > 0) {
-            console.log(`  ${chalk.green('fixed ')}  ${label}  ${chalk.gray(parts.join(', '))}`);
-        }
-        const drift = v.skipped.filter((s) => s.reason === 'drift');
-        const unres = v.skipped.filter((s) => s.reason === 'unreconcilable');
-        if (drift.length > 0) {
-            console.log(`  ${chalk.yellow('drift ')}  ${label}  ${chalk.gray(`${drift.length} hand-edited — left as-is (use \`--diff\` to inspect)`)}`);
-        }
-        if (unres.length > 0) {
-            const names = unres.map((s) => `${s.kind}/${s.name}`).join(', ');
-            console.log(`  ${chalk.yellow('hold  ')}  ${label}  ${chalk.gray(`${unres.length} couldn't reconcile (${names}) — source/home mismatch the writer can't satisfy`)}`);
-        }
-    }
-    console.log();
-    const healed = result.versions.reduce((n, v) => n + v.healed.length, 0);
-    const touchedVersions = result.versions.filter((v) => v.healed.length > 0).length;
-    if (!healChangedAnything(result)) {
-        console.log(chalk.green('✓ Everything in sync — nothing to heal.'));
-    }
-    else {
-        const bits = [];
-        if (healed > 0)
-            bits.push(`${healed} resource${healed === 1 ? '' : 's'} across ${touchedVersions} version${touchedVersions === 1 ? '' : 's'}`);
-        if (result.repairedManifests.length > 0)
-            bits.push(`${result.repairedManifests.length} manifest${result.repairedManifests.length === 1 ? '' : 's'} repaired`);
-        if (result.refreshedPlugins.length > 0)
-            bits.push(`${result.refreshedPlugins.length} plugin${result.refreshedPlugins.length === 1 ? '' : 's'} refreshed`);
-        console.log(chalk.green(`✓ Healed ${bits.join(', ')}.`));
-    }
-}
-/**
- * Re-wire hooks that reconcile as files but are absent from settings.json.
- *
- * heal() only re-syncs resources the diff flags missing/diff; a hook whose file
- * is byte-identical to source but never referenced in settings.json is neither,
- * so heal walks past it. registerHooksToSettings (the same call `agents sync`
- * makes at versions.ts) regenerates the wiring, so run it for any Claude-family
- * version this fix targets that has unwired hooks. Only claude/droid — the set
- * checkVersionHookWiring can verify.
- */
-function rewireUnwiredHooks(parsed) {
-    const out = [];
-    const agents = parsed?.agent
-        ? (HOOK_WIRING_FIX_AGENTS.includes(parsed.agent) ? [parsed.agent] : [])
-        : HOOK_WIRING_FIX_AGENTS;
-    for (const agent of agents) {
-        // A named version is explicit consent; a sweep excludes isolated copies,
-        // mirroring heal().
-        const versions = parsed?.agent && parsed.versionExplicit
-            ? parsed.versions
-            : listInstalledVersions(agent).filter((v) => !isVersionIsolated(agent, v));
-        for (const version of versions) {
-            const before = checkVersionHookWiring(agent, version);
-            if (!before.supported)
-                continue;
-            const need = before.unwired.length + (before.settingsMissing ? (before.expected ?? 0) : 0);
-            if (need === 0)
-                continue;
-            try {
-                const registration = registerHooksToSettings(agent, getVersionHomePath(agent, version));
-                if (registration.errors.length > 0) {
-                    out.push({ agent, version, rewired: 0, remaining: need, failure: 'register-failed' });
-                    continue;
-                }
-                const after = checkVersionHookWiring(agent, version);
-                const remaining = after.unwired.length + (after.settingsMissing ? (after.expected ?? 0) : 0);
-                out.push({ agent, version, rewired: Math.max(0, need - remaining), remaining });
-            }
-            catch {
-                // A shim write can fail before the native config writer gets to return
-                // its own errors. Record the same stable class and keep doctor --fix
-                // moving to the one bounded runtime repair pass below.
-                out.push({ agent, version, rewired: 0, remaining: need, failure: 'register-failed' });
-            }
-        }
-    }
-    return out;
-}
-function renderHookRewireText(rewired) {
-    for (const r of rewired) {
-        const label = `${AGENT_NAMES[r.agent] || r.agent}@${r.version}`;
-        if (r.failure) {
-            console.log(`  ${chalk.red('hold  ')} ${label}  ${chalk.gray('native hook wiring could not be updated')}`);
-        }
-        else if (r.remaining === 0) {
-            console.log(`  ${chalk.green('rewired')} ${label}  ${chalk.gray(`${r.rewired} hook${r.rewired === 1 ? '' : 's'} wired into settings.json`)}`);
-        }
-        else {
-            console.log(`  ${chalk.yellow('hold  ')} ${label}  ${chalk.gray(`${r.remaining} hook${r.remaining === 1 ? '' : 's'} still unwired — run \`agents sync ${r.agent}@${r.version} --yes\``)}`);
-        }
-    }
-}
-function runtimeRepairFilter(parsed) {
-    if (!parsed)
-        return undefined;
-    // A concrete target can be narrowed to that version. Broad selectors (@all,
-    // @latest, agent-only) still make one bounded repair pass for that harness.
-    return {
-        agent: parsed.agent,
-        ...(parsed.versionExplicit && parsed.versions.length === 1 ? { version: parsed.versions[0] } : {}),
-    };
-}
-function renderHookRuntimeRepairText(repair) {
-    for (const fixed of repair.fixed) {
-        console.log(`  ${chalk.green('fixed ')}  ${chalk.gray(fixed)}`);
-    }
-    for (const unresolved of repair.needsAttention) {
-        console.log(`  ${chalk.red('hold  ')}  ${chalk.gray(unresolved)}`);
-    }
-}
-/**
- * RUSH-2415: delete npx-cache / unsafe-legacy / pre-1.22.30 agents-cli copies
- * when a fixed peer already exists. Bare `doctor --fix` is the remediation
- * surface the multi-install warning points at; a targeted
- * `doctor <agent>@<version> --fix` only heals that version home and must not
- * touch other CLI installs on the box.
- */
-function purgeStaleAgentsCliCopies(_opts) {
-    let runningRoot;
-    try {
-        // dist/commands/doctor.js (or src/commands/doctor.ts under vitest) —
-        // resolveRunningPackageRoot walks up until package.json names this package.
-        runningRoot = resolveRunningPackageRoot(__doctorDirname);
-    }
-    catch {
-        return null;
-    }
-    return remediateStaleAgentsCliInstalls({
-        runningRoot,
-        runningVersion: getCliVersion(),
-    });
-}
-function renderStaleInstallPurgeText(purge) {
-    if (purge.removed.length === 0 && purge.failed.length === 0 && purge.unresolved.length === 0)
-        return;
-    console.log(chalk.bold('\nStale agents-cli installs'));
-    for (const r of purge.removed) {
-        const why = r.reasons.join(', ');
-        console.log(`  ${chalk.green('purged')} ${chalk.gray(`${r.packageRoot}  ${r.version}  (${why})`)}`);
-    }
-    for (const f of purge.failed) {
-        console.log(`  ${chalk.red('hold  ')} ${chalk.gray(`${f.packageRoot}  ${f.version}  — ${f.error}`)}`);
-    }
-    // RUSH-2705/2713: a duplicate --fix cannot auto-purge — either a healthy
-    // >=1.22.30 peer, OR a pre-1.22.30 copy left alone only because no fixed peer
-    // exists to fall back to (that one is NOT healthy). Either way, hand back the
-    // command that removes it instead of ending on a bare "everything in sync".
-    // Don't call it "healthy" — that would understate a genuinely vulnerable copy.
-    for (const u of purge.unresolved) {
-        console.log(`  ${chalk.yellow('manual')} ${chalk.gray(`${u.packageRoot}  ${u.version}  — --fix will not delete this copy; remove it with:`)}`);
-        console.log(`         ${chalk.bold(u.manualRemoveCommand)}`);
-    }
-}
-async function runFix(parsed, opts) {
-    // Heal targets the global install — project layer is irrelevant, so cwd is
-    // left to heal's neutral default rather than process.cwd().
-    if (!opts.json)
-        console.log(chalk.bold('Healing…'));
-    // `agents doctor <agent> --fix` is a SWEEP, same as the bare form — leave the
-    // version list to heal() so it applies its isolated-copy filter. Passing the
-    // enumerated list here would smuggle isolated versions past that filter.
-    // A named version (`<agent>@<version>`) is explicit consent and is passed through.
-    const result = await heal({
-        mode: 'full',
-        agent: parsed?.agent,
-        versions: parsed?.versionExplicit ? parsed.versions : undefined,
-    });
-    // Re-wire hooks the diff-driven heal leaves behind (present file, not wired).
-    const rewired = rewireUnwiredHooks(parsed);
-    // One inspect→generate→verify pass, after normal resource and native-wiring
-    // repair have settled. This routine never calls sync/register and never
-    // retries; unresolved wrappers remain an explicit non-zero doctor outcome.
-    const hookRuntimeRepair = repairManagedHookRuntimeArtifacts({ filter: runtimeRepairFilter(parsed) });
-    // Bare doctor --fix also purges latent pre-fix / legacy agents-cli copies
-    // that only warn today (RUSH-2415). A scoped agent@version fix leaves them
-    // alone — the multi-install surface is machine-wide, not per-agent.
-    const staleInstallPurge = parsed === null ? purgeStaleAgentsCliCopies(opts) : null;
-    const rewireFailed = rewired.some((entry) => entry.failure !== undefined);
-    if (healChangedAnything(result) ||
-        rewired.some((entry) => entry.rewired > 0 || entry.remaining > 0 || entry.failure !== undefined) ||
-        hookRuntimeRepair.attempts.length > 0 ||
-        (staleInstallPurge !== null && (staleInstallPurge.removed.length > 0 || staleInstallPurge.failed.length > 0))) {
-        invalidateDoctorOverviewCache();
-    }
-    if (opts.json) {
-        console.log(JSON.stringify({
-            ...result,
-            hookRewire: rewired,
-            hookRuntimeRepair,
-            ...(staleInstallPurge ? { staleInstallPurge } : {}),
-        }, null, 2));
-        if (rewireFailed
-            || hookRuntimeRepair.needsAttention.length > 0
-            || (staleInstallPurge !== null && staleInstallPurge.failed.length > 0)) {
-            process.exitCode = 1;
-        }
-        return;
-    }
-    renderHealText(result);
-    renderHookRewireText(rewired);
-    renderHookRuntimeRepairText(hookRuntimeRepair);
-    if (staleInstallPurge)
-        renderStaleInstallPurgeText(staleInstallPurge);
-    if (rewireFailed
-        || hookRuntimeRepair.needsAttention.length > 0
-        || (staleInstallPurge !== null && staleInstallPurge.failed.length > 0)) {
-        process.exitCode = 1;
-    }
-}
 function checkLabel(row) {
     return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
 }
@@ -1360,7 +1123,7 @@ function runCheckGate(opts, cwd) {
         }
         const hints = [];
         if (drift.staleCount > 0 || drift.neverSyncedCount > 0 || drift.unwiredHookVersions > 0 || drift.brokenHookRuntimeVersions > 0) {
-            hints.push('`agents doctor --fix` (or `agents doctor <agent>@<version> --fix`)');
+            hints.push('`agents sync <agent>@all` (or `agents sync <agent>@<version>`)');
         }
         if (drift.sourceBehind.length > 0)
             hints.push('`agents repo pull <alias>` for a source layer behind origin');
@@ -1447,7 +1210,7 @@ async function runDevicesCheck(opts, cwd) {
                 : [`${d.stale} stale`, `${d.neverSynced} never-synced`].filter((p) => !p.startsWith('0 ')).join(', ');
             console.error(`  ${chalk.yellow(d.device.padEnd(18))} ${detail || 'drift'}`);
         }
-        console.error(chalk.gray('\nReconcile each device with `agents doctor --fix` or `agents repo pull user`.'));
+        console.error(chalk.gray('\nReconcile each device with `agents sync <agent>@all` or `agents repo pull user`.'));
     }
     process.exit(1);
 }
@@ -1457,7 +1220,7 @@ export function registerDoctorCommand(program) {
         .description('Diagnose CLI availability, sync status, and resource divergence (optionally for a specific agent[@version]).')
         .option('--json', 'Output machine-readable JSON')
         .option('--diff', 'In target mode, include unified diffs for divergent files')
-        .option('--fix', 'Heal gaps: install missing resources, repair invalid plugin manifests, refresh stale plugins, reconcile drift, and purge stale/legacy agents-cli installs (npx-cache, pre-1.22.30, unsafe helper installer) when a fixed peer exists')
+        .option('--fix', '(deprecated) doctor is diagnose-only — this errors with a pointer to `agents sync`, the one fixer')
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,workflows,memory)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())')
         .option('--adopt <agent>', "Take over the agent's native launcher that shadows the shim (symlink it to the version-managed shim; reversible with --release)")
@@ -1488,11 +1251,11 @@ export function registerDoctorCommand(program) {
       # Inspect only rules and hooks, with full diffs
       agents doctor claude@default --kind rules,hooks --diff
 
-      # Heal every gap across all installed versions
-      agents doctor --fix
+      # Fix every gap across all installed versions (the one fixer)
+      agents sync claude@all
 
-      # Heal just one agent (all its installed versions)
-      agents doctor claude --fix
+      # Fix just one version
+      agents sync claude@2.1.207
 
       # Fleet: agent readiness + cross-device divergence (missing plugins/skills,
       # agent-version gaps, .agents/.system repo drift) vs this machine
@@ -1503,7 +1266,7 @@ export function registerDoctorCommand(program) {
       agents doctor --check --quiet          # just the verdict line
       agents doctor --check --json           # machine-readable, for scripting
       agents doctor --check --devices        # gate every registered device
-      agents doctor --check || { echo "resources drifted — run 'agents doctor --fix'"; exit 1; }
+      agents doctor --check || { echo "resources drifted — run 'agents sync <agent>@all'"; exit 1; }
     `,
     });
     doctorCmd.action(async (target, opts) => {
@@ -1587,20 +1350,15 @@ export function registerDoctorCommand(program) {
             }
             return;
         }
-        // --fix turns the read-only diagnosis into a heal. With no target it heals
-        // every installed version; with a target it scopes to that agent.
+        // `doctor --fix` moved to `agents sync` — doctor is diagnose-only now.
+        // Keep the flag for one release as a signpost: it never heals, it points at
+        // the one fixer and exits non-zero so scripts and muscle memory get a clear
+        // redirect instead of a silent no-op.
         if (opts.fix) {
-            let scope = null;
-            if (target) {
-                const parsed = parseTargetArg(target);
-                if ('error' in parsed) {
-                    console.error(chalk.red(parsed.error));
-                    process.exit(1);
-                }
-                scope = parsed;
-            }
-            await runFix(scope, opts);
-            return;
+            const where = target ? `agents sync ${target}` : 'agents sync <agent>@all';
+            console.error(chalk.yellow('`agents doctor --fix` has moved to `agents sync`.'));
+            console.error(chalk.gray(`  doctor now only diagnoses. To fix, run: ${where}`));
+            process.exit(1);
         }
         if (!target) {
             // Singleflight + short-TTL cache for the bare `doctor --json` overview.
@@ -1666,8 +1424,8 @@ export function registerDoctorCommand(program) {
             // A MANAGED agent (installed versions) whose binary won't resolve is a
             // real critical — an unmanaged-and-absent agent is not.
             const cliMissing = ALL_AGENT_IDS.filter((a) => listInstalledVersions(a).length > 0 && clis[a] && !clis[a].installed);
-            // An isolated copy is skipped by the agent-wide `--fix` sweep, so its
-            // findings must never fold into a collapsed cross-version row.
+            // An isolated copy is skipped by the agent-wide `agents sync` sweep, so
+            // its findings must never fold into a collapsed cross-version row.
             const isolatedVersions = reports
                 .filter((r) => isVersionIsolated(r.agent, r.version))
                 .map((r) => `${r.agent}@${r.version}`);

package/dist/commands/exec.d.ts

@@ -8,6 +8,8 @@
 import { type Command } from 'commander';
 import type { ExecEffort } from '../lib/exec.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
+/** Validate a caller-supplied session id before it reaches tmux, paths, indexes, or remote dispatch. */
+export declare function parseExplicitSessionId(value: string): string;
 export interface RunAccountPickerRequest {
     requested: boolean;
     normalizedAgentSpec: string;

package/dist/commands/exec.js

@@ -5,7 +5,7 @@
  * or headlessly. Supports profile resolution, version rotation, secrets
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
-import { Option } from 'commander';
+import { InvalidArgumentError, Option } from 'commander';
 import chalk from 'chalk';
 import { isTierToken } from '../lib/model-tiers.js';
 import { RUN_AUTO_KEYWORD } from '../lib/types.js';
@@ -28,6 +28,13 @@ import { isSessionTrackedAgent } from '../lib/session/types.js';
 import { applyActiveRulesPresetAtRun } from '../lib/rules/run-sync.js';
 import { handleBroadcast } from './run-broadcast.js';
 import { bootMark } from '../lib/boot-profile.js';
+/** Validate a caller-supplied session id before it reaches tmux, paths, indexes, or remote dispatch. */
+export function parseExplicitSessionId(value) {
+    if (!/^[A-Za-z0-9._-]+$/.test(value)) {
+        throw new InvalidArgumentError('must contain only ASCII letters, digits, dots, underscores, or hyphens');
+    }
+    return value;
+}
 /** Distinguish a terminal account-picker marker from an explicit @version pin. */
 export function parseRunAccountPickerRequest(agentSpec) {
     const requested = agentSpec.endsWith('@');
@@ -514,7 +521,7 @@ export function registerRunCommand(program) {
         .option('--results [run-id]', 'With --broadcast: show one saved matrix run, or list saved runs newest first')
         .option('--concurrency <n>', 'With --broadcast: maximum cells running at once', '3')
         .option('--resume [id]', 'Recover a previous conversation on its origin device. The exact healthy origin uses native resume; otherwise a healthy version of the same harness replays via /continue. Pair with a prompt to continue headlessly.')
-        .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.')
+        .option('--session-id <id>', 'Force a NEW conversation to use this exact session UUID (Claude only). This CREATES a session — to resume an existing one, use --resume.', parseExplicitSessionId)
         .option('--name <slug>', 'Name the run — seeds the session label so it shows up as `<name>` in `agents sessions` and resolves by it (and `agents hosts logs <name>` for --device runs) instead of an opaque id. An agent-generated title later refines the label; your name shows until then. Optional.')
         .option('--notify', 'Post a desktop notification when a headless run finishes. Fired by this process on exit, so it survives whatever launched the run (the menu bar dispatching it, a terminal you closed).')
         .option('--no-trace-sync', 'Skip the run-exit trace auto-sync for this run. Auto-sync fires by default only for local runs and only once you have run `agents traces sync` at least once (also silenced by AGENTS_NO_TRACE_SYNC=1).')

package/dist/commands/harness.d.ts

@@ -22,6 +22,7 @@ import { type HarnessDraft } from './harness-wizard.js';
 export declare function renderHarnessDetail(name: string): void;
 /** Options accepted by `agents harness fork`. */
 export interface ForkOptions {
+    toHost?: string;
     model?: string;
     baseUrl?: string;
     authProvider?: string;

package/dist/commands/harness.js

@@ -62,7 +62,11 @@ export function buildFork(source, name, opts) {
     if (opts.authProvider || opts.fromSecrets)
         throw new Error("Harnesses no longer own credentials. Add one with 'agents accounts add <name> --provider <provider> --auth <type>', then pass --account <name>.");
     if (profileExists(source)) {
+        const targetHost = opts.toHost ? (resolveAgentName(opts.toHost) ?? undefined) : undefined;
+        if (opts.toHost && !targetHost)
+            throw new Error(`Unknown target host '${opts.toHost}'.`);
         const profile = forkProfile(readProfile(source), name, {
+            host: targetHost,
             model: opts.model,
             baseUrl: opts.baseUrl,
             provider: opts.authProvider,
@@ -78,14 +82,17 @@ export function buildFork(source, name, opts) {
         }
         return profile;
     }
-    const host = resolveAgentName(source);
-    if (!host) {
+    const sourceHost = resolveAgentName(source);
+    if (!sourceHost) {
         throw new Error(`No harness or agent named '${source}'.\n` +
             `Fork from a custom harness (agents harness list) or a native one: ${ALL_AGENT_IDS.join(', ')}.`);
     }
     if (!opts.model) {
-        throw new Error(`--model <id> is required when forking the native '${host}' harness (there is no model to inherit).`);
+        throw new Error(`--model <id> is required when forking the native '${sourceHost}' harness (there is no model to inherit).`);
     }
+    const host = opts.toHost ? resolveAgentName(opts.toHost) : sourceHost;
+    if (!host)
+        throw new Error(`Unknown target host '${opts.toHost}'.`);
     const profile = profileFromHostModel(name, host, opts.model, {
         version: opts.version,
         baseUrl: opts.baseUrl,
@@ -461,6 +468,7 @@ Examples:
         .command('fork [source] [name]')
         .description('Fork a native harness (claude, opencode, ...) or an existing custom one into a new named harness. Omit args in a terminal for the interactive wizard.')
         .option('--model <id>', 'Model to pin on the fork (required when forking a native harness)')
+        .option('--to-host <agent>', 'Translate the fork onto another native harness host (for example claude to codex)')
         .option('--base-url <url>', 'Custom endpoint base URL (claude/codex hosts)')
         .option('--account <name>', 'Default durable credential account')
         .option('--auth-provider <provider>', 'Removed: use agents accounts add, then --account')

package/dist/commands/hooks.js

@@ -1,3 +1,4 @@
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import ora from 'ora';
 import * as fs from 'fs';
@@ -40,8 +41,8 @@ When to use:
   - Notifications: ping Slack when agents complete long tasks
   - Team workflows: sync hooks via 'agents hooks add gh:team/hooks'
 `);
-    hooksCmd
-        .command('list [agent]')
+    withAliases(hooksCmd
+        .command('list [agent]'), 'list')
         .description('Show which hooks are installed and which events they respond to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
         .option('-s, --scope <scope>', 'user (global), project (repo), or all', 'all')
@@ -387,8 +388,8 @@ Examples:
             process.exit(1);
         }
     });
-    hooksCmd
-        .command('remove [name]')
+    withAliases(hooksCmd
+        .command('remove [name]'), 'remove')
         .description('Delete a hook from agents (interactive picker if no name given)')
         .option('-a, --agents <list>', 'Limit removal to specific agents')
         .addHelpText('after', `
@@ -527,8 +528,8 @@ Examples:
         console.error(chalk.gray('Use:  agents prune cleanup hooks   (or `agents prune cleanup` for everything)'));
         process.exit(1);
     });
-    hooksCmd
-        .command('view [name]')
+    withAliases(hooksCmd
+        .command('view [name]'), 'view')
         .description('Read the shell script content for a hook')
         .addHelpText('after', `
 Examples:

package/dist/commands/mcp.js

@@ -1,3 +1,4 @@
+import { withAliases } from '../lib/verbs.js';
 import chalk from 'chalk';
 import { truncate } from '../lib/format.js';
 import ora from 'ora';
@@ -143,8 +144,8 @@ When to use:
   - Version upgrade: 'agents mcp register' to sync servers to the new version
   - Team setup: commit mcp config to .agents and run 'agents mcp register'
 `);
-    mcpCmd
-        .command('list [agent]')
+    withAliases(mcpCmd
+        .command('list [agent]'), 'list')
         .description('Show which MCP servers are registered and which agent versions they are synced to')
         .option('-a, --agent <agent>', 'Filter to a specific agent (alternative to positional arg)')
         .option('--json', 'Emit machine-readable JSON instead of the table/picker')
@@ -337,8 +338,8 @@ Examples:
         console.log(chalk.green(`Added MCP server '${name}' to manifest`));
         console.log(chalk.gray('Run: agents mcp register to apply'));
     });
-    mcpCmd
-        .command('remove [name]')
+    withAliases(mcpCmd
+        .command('remove [name]'), 'remove')
         .description('Unregister an MCP server from agents (interactive picker if no name given)')
         .option('-a, --agents <list>', 'Limit removal to specific agents')
         .addHelpText('after', `
@@ -487,8 +488,8 @@ Examples:
             console.log(chalk.green(`\nRemoved ${removed} MCP server(s).`));
         }
     });
-    mcpCmd
-        .command('view [name]')
+    withAliases(mcpCmd
+        .command('view [name]'), 'view')
         .description('Show MCP server configuration (command, scope, registered agents)')
         .addHelpText('after', `
 Examples: