@phnx-labs/agents-cli 1.20.26 → 1.20.28

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+**`agents sessions --host <machine>`: query a remote machine's sessions live over SSH**
+
+- `agents sessions "<query>" --host <alias|user@host>` runs the same session query on a remote machine's own index over SSH and streams the result back — repeat `--host` (or pass several) to fan out across machines. SSH access is the only auth; there's no daemon or shared store. Targets are validated against a strict allowlist (`SSH_TARGET_RE`) to block flag-smuggling, and the forwarded invocation is double-quoted (`shellQuote`) so a query like `$(whoami)` survives as a literal string on both shell layers. Source: `src/lib/session/remote.ts`, `src/commands/sessions.ts`, `docs/05-sessions.md`.
+
+**Fix: migrations + menu-bar self-heal were silently disabled on Homebrew-node installs**
+
+- The "is this a dev build?" check walked `dirname(dirname(argv[1]))` looking for a `.git`, without resolving the bin symlink. On a Homebrew-node setup `agents` is `/opt/homebrew/bin/agents`, so it walked up to `/opt/homebrew` — **which is itself a git repo** — and false-positived as a dev build. Dev builds auto-set `AGENTS_SKIP_MIGRATION=1`, which gates **both** one-shot migrations **and** the menu-bar upgrade self-heal. Net effect: every Homebrew-node user ran with migrations and the menu-bar refresh permanently off.
+- Detection now `realpath`s the entrypoint (so a symlinked bin resolves into the real package dir) and requires the `.git`'s repo root to actually be the `@phnx-labs/agents-cli` package — an unrelated ancestor repo no longer counts. Extracted to `src/lib/startup/dev-build.ts` with tests covering the Homebrew symlink layout, a real checkout, and unrelated-ancestor cases.
+
 **Secrets default policy is now `daily` (one Touch ID per ~24h), not `always`**
 
 - The default prompt policy for bundles without an explicit one flipped from `always` (Touch ID on *every* read) to **`daily`** (one prompt, then held ~24h until screen-lock / sleep / logout). This is the fix for the prompt storm: a background reader like sessions-sync hammering a bundle now costs one Touch ID per ~24h instead of one per read.
@@ -9,10 +18,30 @@
 - **Configurable, still flexible.** Set the global default in `agents.yaml` (`secrets.policy: always` to restore prompt-every-time), or override per bundle with `agents secrets policy <bundle> always` for high-value keys (signing, SSH) you want to confirm on every read.
 - **Explicit `always` now persists** under the legacy `tier: biometry` token (older CLIs read it as their own always default). Bundles with no stored policy inherit the configured default — so an existing always-by-default bundle quietly becomes `daily` on first read by the new CLI, which is the intended migration.
 
+**Menu bar: a macOS status item for agent activity (`agents menubar`)**
+
+- New no-Dock menu bar app showing live agent activity on the machine: a **NEEDS YOU** section (sessions awaiting input + failed/overdue routines), a per-agent **roster** (running / idle counts across installed agents), a **+ New session** launcher, and a one-line routines summary. The icon badges red `!` when something needs you, green with a count when sessions are running.
+- Reads state **directly from disk** — `live-terminals.json`, teams `meta.json`, and the cloud `tasks.db` — so opening the menu never triggers the costly sessions transcript re-index. The CLI is shelled only for actions (start a session, run a routine).
+- **Auto-enabled on macOS** for every user as a launchd login service (`com.phnx-labs.agents-menubar`); a fresh install brings the icon up with no manual step. Manage with `agents menubar enable | disable | status`. Opt out with `agents menubar disable` — sticky across upgrades.
+- **Upgrade self-heal:** the installed bundle is version-stamped, and the startup self-heal now re-installs the helper when a newer release ships a newer build (or the installed copy goes missing), instead of skipping whenever a service already existed. So `npm update` actually moves users onto the new helper binary + plist rather than leaving the old one running (#442). `agents menubar status` shows installed vs current version and staleness.
+- Docs: [Menu bar](docs/menubar.md). macOS only.
+
 **`agents repos view [name]`: inspect one repo's contents without opening it**
 
 - New `agents repo view <name>` (also reachable as `agents repos view`, now a first-class alias of the `repo` command) prints a single repo's git state and per-kind resource counts — `system`, `user`, `project`, or an extra-repo alias. Omit the name for an interactive picker over the registered repos. It reuses the `inspect` repo renderer, so output matches `agents inspect <repo>`; supports `--brief` and `--json`. Source: `src/commands/repo.ts`, `src/commands/inspect.ts`.
 
+**`agents doctor --fix` + a daemon safety check: heal the gap between defined and installed**
+
+- Root cause behind "a plugin/command silently vanished": a DotAgents repo can DEFINE a resource that never makes it into an agent home, and nothing closes the gap. Two concrete failure modes — (1) `agents plugins update`/`sync` only reconcile each agent's **default** version, so a non-default installed version keeps serving stale/invalid resources; (2) a plugin.json with a bare-name `skills`/`commands` field makes Claude Code **silently reject the entire plugin**, and the sync path only *warned*. The detection (`agents doctor`'s live-home diff) and the healing (`syncResourcesToVersion`) existed but were never wired together — and the sync fast-guard keyed off the staleness manifest, which is blind to home-side rot.
+- **`agents doctor --fix`** turns the read-only diagnosis into a heal: installs missing resources, repairs Claude-invalid plugin manifests (strips the bare `skills`/`commands` field — Claude auto-discovers from the dirs), fast-forwards stale plugins from their `.source`, and reconciles drift — across **every installed version**, not just defaults. With no target it heals the whole install; `agents doctor <agent> --fix` scopes to one.
+- **Daemon safety check:** the routines daemon now runs the same heal in conservative `safe` mode (~every 6h + ~30s after start) — it fixes only unambiguous gaps (missing resources, invalid manifests, *provably-unmodified* stale plugins) and **notifies rather than clobbers** on hand-edited content or a plugin it can't prove is pristine.
+- Built on the **live-home diff**, not the staleness manifest, so it catches drift the sync fast-guard can't. Heal **fills and fixes, never deletes** (orphans stay `agents prune cleanup`'s job), excludes the project layer (the global home isn't reconciled against per-cwd project resources), and **verifies after writing** — it only claims resources that actually reconciled, so repeated runs converge instead of "fixing" the same item forever.
+- `.source` now records the plugin version at pull time, a baseline that lets the safe path tell an untouched mirror (fast-forward) from a user edit (leave alone).
+- **`agents doctor` overview now covers every installed version, not just defaults.** Sync status and orphans previously reported only each agent's default version — so a stale NON-default version (the exact rot `--fix` heals) was invisible in the readout. Each version is now listed with its default marked. The **Agent CLIs** list also stops nagging: it shows the agents you actually run (ready, or managed-but-broken) and collapses the rest of the supported catalog to a single `+N more supported …` hint instead of a column of red "not installed" lines for tools you never adopted.
+- **Says exactly WHAT is out of sync — plugins first.** A stale version in the overview now lists the specifics under it, prioritizing plugins and their bundled content: `plugin code — 0.6.1→0.7.0, missing skills: ship, learn`. The plugin diff went from presence-only ("installed: yes") to **content-aware** — it compares the version's marketplace mirror against the central source and surfaces a stale mirror version, a Claude-invalid manifest, and the plugin's own skills/commands that never reached the mirror (the system-repo content that matters most). `agents doctor <agent>@<version>` shows the same detail per plugin row.
+- **Fixed a false "drift" that could never be reconciled:** a hook's `.md`/`.rst` doc sibling (e.g. `git-guard.md` next to `git-guard.sh`) was wrongly treated as the hook's runtime *data file*, so the installer's correct omission of docs showed as perpetual drift in `doctor` (and as an un-healable item under `--fix`). Docs are no longer counted as hook data; structured siblings (`.yaml`/`.json`/...) still are.
+- **Corrected a false promise in the sync-status readout.** Stale/cold versions used to say "will sync on next launch" / "first launch will populate" — but version homes are NOT reconciled on launch (the shim hot path only resolves a version and compiles project-scoped resources; v15/v16 moved version-home reconciliation to management commands). The readout now states the fact ("sources changed since last sync" / "never synced") and points at the real fix: `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>`.
+
 **Secrets prompt policy: human-readable `always` / `daily`, and `secrets list` now shows it**
 
 - Renamed the secrets-agent `tier` to a **prompt policy** with plain-language names: `biometry` → **`always`** (ask every time), `session` → **`daily`** (ask once, then held ~24h until screen-lock / sleep / logout). The old name `session` was misleading — it never meant "once per login session" — and collided with the half-dozen other "session" concepts in the CLI (`agents sessions`, sessions-sync, pty/browser sessions). Set it with `agents secrets policy <bundle> [always|daily]`.

package/dist/commands/doctor.d.ts

@@ -15,8 +15,11 @@
  *      unified diff body for each divergent file. Mirrors the resolution that
  *      the shim drives at runtime: project > user > system > extras.
  *
- * Read-only: doctor never mutates state. Run `agents prune cleanup` to act on orphan
- * readouts, or just launch the agent to apply pending sync.
+ * 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.
  */
 import type { Command } from 'commander';
 export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -10,22 +10,64 @@ import { diffVersionResources, DOCTOR_ALL_KINDS, } from '../lib/doctor-diff.js';
 import { unifiedDiff, colorizeUnifiedDiff } from '../lib/diff-text.js';
 import { listCliStatus } from '../lib/cli-resources.js';
 import { setHelpSections } from '../lib/help.js';
+import { heal, healChangedAnything } from '../lib/heal.js';
 import * as fs from 'fs';
 const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
 // ─── overview mode (no target) ────────────────────────────────────────────────
+// Lines naming exactly what's out of sync for a version, plugins prioritized:
+// each divergent plugin gets its own line with specifics (stale mirror version,
+// invalid manifest, or the bundled skills/commands missing from the mirror —
+// the system-repo plugin content that matters most). Other kinds collapse to
+// compact counts so the readout stays scannable.
+function divergenceLines(report) {
+    const lines = [];
+    for (const p of report.kinds.plugins) {
+        if (p.status === 'missing')
+            lines.push(`plugin ${p.name} — not installed`);
+        else if (p.status === 'diff')
+            lines.push(`plugin ${p.name} — ${p.detail ?? 'mirror drifted'}`);
+    }
+    const counts = [];
+    for (const kind of ['commands', 'skills', 'hooks', 'rules', 'mcp', 'permissions', 'subagents']) {
+        const rows = report.kinds[kind];
+        const miss = rows.filter((r) => r.status === 'missing').length;
+        const dif = rows.filter((r) => r.status === 'diff').length;
+        const bits = [];
+        if (miss)
+            bits.push(`${miss} missing`);
+        if (dif)
+            bits.push(`${dif} drifted`);
+        if (bits.length)
+            counts.push(`${kind} ${bits.join('/')}`);
+    }
+    if (counts.length)
+        lines.push(counts.join(' · '));
+    return lines;
+}
 function checkSyncStatus(cwd) {
     const rows = [];
+    // Every installed version, not just the default — a stale NON-default version
+    // (e.g. one you launched from yesterday) is exactly the rot that silently
+    // serves outdated/invalid resources and that `--fix` now heals. Hiding it here
+    // is why that class of bug went unnoticed.
     for (const agent of ALL_AGENT_IDS) {
-        const version = getGlobalDefault(agent);
-        if (!version)
-            continue;
-        const manifest = loadManifest(agent, version);
-        if (!manifest) {
-            rows.push({ agent, version, status: 'never-synced' });
-            continue;
+        const def = getGlobalDefault(agent);
+        for (const version of listInstalledVersions(agent)) {
+            const manifest = loadManifest(agent, version);
+            const status = !manifest
+                ? 'never-synced'
+                : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
+            const row = { agent, version, status, isDefault: version === def };
+            if (status === 'stale') {
+                // Resolve the specifics against non-project layers (the global home is
+                // never reconciled against per-cwd project resources).
+                const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
+                const lines = divergenceLines(report);
+                if (lines.length)
+                    row.divergence = lines;
+            }
+            rows.push(row);
         }
-        const stale = isStale(manifest, agent, version, cwd);
-        rows.push({ agent, version, status: stale ? 'stale' : 'fresh' });
     }
     return rows;
 }
@@ -41,15 +83,11 @@ function countOrphans() {
         return row;
     };
     for (const { agent, version } of iterCommandsCapableVersions()) {
-        if (version !== getGlobalDefault(agent))
-            continue;
         const diff = diffVersionCommands(agent, version);
         if (diff.orphans.length > 0)
             ensure(agent, version).commands = diff.orphans.length;
     }
     for (const { agent, version } of iterSkillsCapableVersions()) {
-        if (version !== getGlobalDefault(agent))
-            continue;
         const diff = diffVersionSkills(agent, version);
         if (diff.orphans.length > 0)
             ensure(agent, version).skills = diff.orphans.length;
@@ -59,8 +97,6 @@ function countOrphans() {
     // never fire. (Distinct from the source-diff `diffVersionHooks().orphans`,
     // which false-flags valid system-sourced registered hooks.)
     for (const { agent, version } of iterHooksCapableVersions()) {
-        if (version !== getGlobalDefault(agent))
-            continue;
         const dead = listUnmanagedHooksInVersionHome(agent, version);
         if (dead.length > 0)
             ensure(agent, version).hooks = dead.length;
@@ -69,41 +105,66 @@ function countOrphans() {
 }
 function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
     console.log(chalk.bold('Agent CLIs'));
-    if (Object.keys(clis).length === 0) {
-        console.log(chalk.gray('  (no agents reported)'));
+    // Show the fleet you actually run — agents that are ready in PATH, plus any
+    // you MANAGE (have installed versions) whose binary isn't resolving (a real
+    // problem). The other supported-but-unadopted agents collapse to one hint line
+    // instead of a column of red "not installed" nags for tools you never wanted.
+    const managed = new Set(ALL_AGENT_IDS.filter((a) => listInstalledVersions(a).length > 0));
+    const entries = Object.entries(clis);
+    const shown = entries.filter(([name, e]) => e.installed || managed.has(name));
+    const hidden = entries.filter(([name, e]) => !e.installed && !managed.has(name)).map(([name]) => name);
+    if (shown.length === 0) {
+        console.log(chalk.gray('  (none installed — `agents add <name>` to start)'));
     }
     else {
-        for (const [name, entry] of Object.entries(clis)) {
-            const pretty = AGENT_NAMES[name] || name;
+        for (const [name, entry] of shown) {
+            const pretty = (AGENT_NAMES[name] || name).padEnd(11);
             if (entry.installed) {
-                console.log(`  ${chalk.green('ready')}  ${pretty.padEnd(10)} ${chalk.gray(entry.path || '')}`);
+                console.log(`  ${chalk.green('ready')}  ${pretty} ${chalk.gray(entry.path || '')}`);
             }
             else {
-                console.log(`  ${chalk.red('no   ')}  ${pretty.padEnd(10)} ${chalk.gray(entry.error || 'not installed')}`);
+                console.log(`  ${chalk.red('no   ')}  ${pretty} ${chalk.gray(entry.error || 'not installed')}`);
             }
         }
     }
+    if (hidden.length > 0) {
+        console.log(chalk.gray(`  +${hidden.length} more supported (${hidden.join(', ')}) — \`agents add <name>\` to manage`));
+    }
     console.log();
-    console.log(chalk.bold('Sync status (default versions)'));
+    console.log(chalk.bold('Sync status (installed versions)'));
     if (syncRows.length === 0) {
-        console.log(chalk.gray('  (no default versions set; pin one with `agents use <agent>@<version>`)'));
+        console.log(chalk.gray('  (no versions installed; add one with `agents add <agent>@<version>`)'));
     }
     else {
+        let anyOutOfSync = false;
         for (const row of syncRows) {
-            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+            const tag = row.isDefault ? chalk.gray(' (default)') : '';
+            const label = `${AGENT_NAMES[row.agent] || row.agent}@${row.version}${tag}`;
             if (row.status === 'fresh') {
                 console.log(`  ${chalk.green('fresh')}  ${label}`);
             }
             else if (row.status === 'stale') {
-                console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— will sync on next launch')}`);
+                anyOutOfSync = true;
+                console.log(`  ${chalk.yellow('stale')}  ${label}  ${chalk.gray('— sources changed since last sync')}`);
+                for (const line of row.divergence ?? []) {
+                    console.log(chalk.gray(`           ${line}`));
+                }
             }
             else {
-                console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced; first launch will populate')}`);
+                anyOutOfSync = true;
+                console.log(`  ${chalk.gray('cold ')}  ${label}  ${chalk.gray('— never synced')}`);
             }
         }
+        // Launching does NOT reconcile a version home — the shim hot path only
+        // resolves a version and compiles project-scoped resources (shims.ts v15/v16).
+        // Version homes are reconciled only by management commands, so point at one
+        // rather than promising an auto-sync that never happens.
+        if (anyOutOfSync) {
+            console.log(chalk.gray('  Reconcile with `agents doctor <agent>@<version> --fix` or `agents sync <agent>@<version>` (not applied on launch).'));
+        }
     }
     console.log();
-    console.log(chalk.bold('Orphans (default versions)'));
+    console.log(chalk.bold('Orphans (installed versions)'));
     if (orphanRows.length === 0) {
         console.log(chalk.gray('  (none — version homes match central sources)'));
     }
@@ -252,7 +313,8 @@ function renderKindSection(kind, rows, layers, options) {
     }
     for (const r of visible) {
         const src = sourceLabel(r, layers);
-        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}`);
+        const detail = r.detail ? chalk.gray(`  ${r.detail}`) : '';
+        console.log(`    ${statusLabel(r.status)}  ${r.name.padEnd(28)} ${src}${detail}`);
         if (options.showDiff && r.status === 'diff' && r.sourcePath && r.homePath) {
             const expected = readExpectedForDiff(kind, r);
             const actual = safeRead(r.homePath);
@@ -340,9 +402,77 @@ function renderTargetText(report, options) {
     }
     else {
         console.log(`  Verdict: ${verdictParts.join(', ')}.`);
-        console.log(chalk.gray(`  Run \`agents sync ${report.agent}@${report.version}\` to reconcile, or \`agents prune cleanup\` to drop extras.`));
+        console.log(chalk.gray(`  Run \`agents doctor ${report.agent}@${report.version} --fix\` to heal, or \`agents prune cleanup\` to drop extras.`));
+    }
+}
+// ─── 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(', ')}.`));
     }
 }
+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…'));
+    const result = await heal({
+        mode: 'full',
+        agent: parsed?.agent,
+        versions: parsed?.versions,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    renderHealText(result);
+}
 // ─── command registration ────────────────────────────────────────────────────
 export function registerDoctorCommand(program) {
     const doctorCmd = program
@@ -350,6 +480,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, and reconcile drift (all installed versions, or just the target)')
         .option('--kind <kinds>', 'Restrict to comma-separated resource kinds (commands,skills,hooks,rules,mcp,permissions,subagents,plugins,promptcuts)')
         .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
     setHelpSections(doctorCmd, {
@@ -368,10 +499,31 @@ 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
+
+      # Heal just one agent (all its installed versions)
+      agents doctor claude --fix
     `,
     });
-    doctorCmd.action((target, opts) => {
+    doctorCmd.action(async (target, opts) => {
         const cwd = opts.cwd ? opts.cwd : process.cwd();
+        // --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.
+        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;
+        }
         if (!target) {
             const clis = checkAllClis();
             const syncRows = checkSyncStatus(cwd);

package/dist/commands/exec.d.ts

@@ -5,7 +5,7 @@
  * or headlessly. Supports profile resolution, version rotation, secrets
  * injection, and multi-agent fallback chains for rate-limit resilience.
  */
-import type { Command } from 'commander';
+import { type Command } from 'commander';
 /**
  * Build the LoopConfig the driver consumes from CLI flags and/or a workflow's
  * `loop:` frontmatter block (issue #332). Returns undefined when neither source

package/dist/commands/exec.js

@@ -5,6 +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 chalk from 'chalk';
 import { setHelpSections } from '../lib/help.js';
 import { parseLoopInterval } from '../lib/loop.js';
@@ -117,7 +118,8 @@ export function registerRunCommand(program) {
         .option('--quiet', 'Suppress preamble (rotation banner, "Running:" line). Useful when piping JSON events to a parser.', false)
         .option('--headless', 'Force headless mode. Auto-enabled when a prompt is provided; pass explicitly to stay headless with no prompt (reads the prompt from stdin).', false)
         .option('-i, --interactive', 'Force interactive mode even when a prompt is provided. Mutually exclusive with --headless.')
-        .option('--session-id <id>', 'Resume a previous conversation (Claude only)')
+        .option('--resume [id]', 'Resume a previous conversation. Accepts a full or partial session id (prefix-matched against the index); omit the id to pick from recent sessions interactively. Resumes under the version that started the session. claude/codex resume natively; other agents replay via a /continue first message. 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('--verbose', 'Show detailed execution logs')
         .option('--timeout <duration>', 'Kill the agent after this duration (e.g., 30m, 1h, 2h30m)')
         .option('--fallback <agents>', 'Comma-separated agents to try on rate-limit failure. Each entry accepts an optional @version pin (e.g., codex@0.116.0,gemini). The primary runs first; if it exits with a rate-limit error, the next agent picks up via /continue handoff.')
@@ -130,7 +132,14 @@ export function registerRunCommand(program) {
         .option('--max-iterations <n>', 'Loop hard cap: stop after N iterations (stoppedBy: max). Loop only.')
         .option('--budget <tokens>', 'Loop token hard-cap: stop once cumulative tokens reach this (stoppedBy: budget), enforced outside the agent. Loop only.')
         .option('--until <signal>', 'Loop stop condition. `signal` reads <runDir>/loop-signal.json {continue,reason} each iteration; absent or continue:false stops (fail-closed). Loop only.')
-        .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.');
+        .option('--interval <dur>', 'Loop delay between iterations ("0" back-to-back, "30m" paces). Loop only.')
+        .option('--host <name>', 'Offload this run onto a registered agent host over SSH instead of running locally. See `agents hosts`.')
+        .option('--remote-cwd <dir>', 'Working directory on the host for --host runs.')
+        .option('--no-follow', 'With --host, dispatch detached and return immediately (track via `agents hosts ps/logs`).')
+        .option('--any', 'With --host <cap> (a capability tag), pick any matching host instead of erroring when several match.');
+    // `--on` and `--computer` are hidden aliases of `--host` — same behavior.
+    runCmd.addOption(new Option('--on <name>', 'Alias of --host.').hideHelp());
+    runCmd.addOption(new Option('--computer <name>', 'Alias of --host.').hideHelp());
     setHelpSections(runCmd, {
         examples: `
       # Headless, read-only: investigate or summarize without writing files
@@ -171,7 +180,7 @@ export function registerRunCommand(program) {
 
       Fallback: --fallback codex,gemini retries on rate-limit failure via /continue handoff. Each entry accepts @version.
 
-      Resume: --session-id <id> continues a prior Claude conversation.
+      Resume: --resume <id> continues a prior conversation (full or partial id; omit to pick interactively). claude/codex resume natively; others replay via a /continue first message. Add a prompt to continue headlessly.
 
       Passthrough: everything after -- is forwarded verbatim to the underlying agent CLI.
         agents run kimi -- --plan --some-native-flag value
@@ -182,6 +191,61 @@ export function registerRunCommand(program) {
         // Use command.args (all positional strings) and strip the declared positional args from the front.
         const declaredArgCount = prompt !== undefined ? 2 : 1;
         const passthroughArgs = command.args.slice(declaredArgCount);
+        // --host/--on/--computer: offload this run onto a registered agent host
+        // over SSH instead of running locally. The three flags are aliases.
+        const hostGiven = [options.host, options.on, options.computer].filter((v) => !!v);
+        if (hostGiven.length > 0) {
+            if (new Set(hostGiven).size > 1) {
+                console.error(chalk.red('Conflicting --host/--on/--computer values — pass just one.'));
+                process.exit(1);
+            }
+            const hostName = hostGiven[0];
+            if (prompt === undefined) {
+                console.error(chalk.red('A prompt is required for host runs: agents run <agent> "<task>" --host <name>'));
+                process.exit(1);
+            }
+            const { resolveHost, resolveHostByCap } = await import('../lib/hosts/registry.js');
+            const { dispatchToHost } = await import('../lib/hosts/dispatch.js');
+            let host = await resolveHost(hostName);
+            if (!host) {
+                // Not a host name — try capability routing (e.g. --host gpu). A
+                // "Multiple hosts tagged…" error is actionable and must surface;
+                // only "no host tagged" falls through to the generic unknown-host msg.
+                try {
+                    host = await resolveHostByCap(hostName, options.any);
+                }
+                catch (e) {
+                    const msg = e.message ?? '';
+                    if (msg.startsWith('Multiple hosts')) {
+                        console.error(chalk.red(msg));
+                        process.exit(1);
+                    }
+                }
+            }
+            if (!host) {
+                console.error(chalk.red(`Unknown host "${hostName}". List hosts: agents hosts list`));
+                process.exit(1);
+            }
+            try {
+                const { exitCode } = await dispatchToHost(host, {
+                    agent: agentSpec.split('@')[0],
+                    prompt,
+                    mode: options.mode,
+                    model: options.model,
+                    remoteCwd: options.remoteCwd,
+                    follow: options.follow !== false,
+                });
+                if (options.follow === false) {
+                    console.log(chalk.green(`Dispatched to ${host.name}.`) + chalk.gray(' Track: agents hosts ps · Follow: agents hosts logs <id> -f'));
+                    process.exit(0);
+                }
+                process.exit(exitCode === undefined || exitCode === -1 ? 1 : exitCode);
+            }
+            catch (err) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        }
         // --resume-checkpoint short-circuits normal dispatch entirely: the
         // checkpoint already carries the agent, version, prompt, session id,
         // iteration, and loop config of the killed run. Reconstruct ExecOptions
@@ -260,7 +324,7 @@ export function registerRunCommand(program) {
             process.stderr.write(chalk.gray(`[loop] stopped: ${result.stoppedBy} after ${result.iterations} iteration(s), ${result.tokens} tokens\n`));
             process.exit(loopExitCode(result.stoppedBy));
         }
-        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
+        const [{ buildExecCommand, parseExecEnv, execAgent, runWithFallback, normalizeMode, resolveMode, defaultModeFor, headlessPlanStallCommand, nativeResume, resolveInteractive }, { ALL_AGENT_IDS }, { profileExists, resolveProfileForRun }, { readAndResolveBundleEnv, describeBundle }, { getConfiguredRunStrategy, normalizeRunStrategy, resolveRunVersion, RUN_STRATEGIES }, { getGlobalDefault, getVersionHomePath, resolveVersion, resolveVersionAlias }, { buildDiscoveredPlugin, loadPluginManifest, syncPluginToVersion }, { parseWorkflowFrontmatter, resolveWorkflowRef, resolveAllowedSubagents }, { resolveRunDefaults }, { getMcpServersByName, buildWorkflowMcpConfig }, { supports },] = await Promise.all([
             import('../lib/exec.js'),
             import('../lib/agents.js'),
             import('../lib/profiles.js'),
@@ -489,6 +553,112 @@ export function registerRunCommand(program) {
             }
         }
         version = resolveVersionAlias(agent, version);
+        // --resume: resolve a prior conversation and rewrite the run target to
+        // continue it. `version` here is already the alias-resolved candidate-version
+        // FILTER (undefined for default/any, concrete for @latest/@oldest/@x.y.z);
+        // it is replaced below by the chosen session's OWN version (isolation).
+        let resumeNative = false;
+        let resumeSessionId;
+        let forceInteractive = false;
+        if (options.resume !== undefined) {
+            if (options.sessionId) {
+                console.error(chalk.red('--resume and --session-id are mutually exclusive. --session-id CREATES a session with a fixed id; --resume continues an existing one.'));
+                process.exit(1);
+            }
+            if (options.loop || options.fallback || options.resumeCheckpoint) {
+                console.error(chalk.red('--resume cannot be combined with --loop, --fallback, or --resume-checkpoint (those are separate continuation mechanisms).'));
+                process.exit(1);
+            }
+            const { findSessionsById } = await import('../lib/session/db.js');
+            const { discoverSessions } = await import('../lib/session/discover.js');
+            const { pickSessionInteractive } = await import('./sessions.js');
+            const { buildContinuePrompt } = await import('../lib/loop.js');
+            // Freshen the index for this agent before any lookup (incremental, cached).
+            // AgentId is wider than SessionAgentId (cursor/amp/… keep no transcripts);
+            // those simply yield no matches and fall through to the not-found error.
+            const sessionAgent = agent;
+            await discoverSessions({ agent: sessionAgent, version });
+            // Resume is interactive unless a follow-on prompt makes it headless.
+            const wantsInteractive = resolveInteractive({ interactive: options.interactive, headless: options.headless, prompt });
+            const idArg = typeof options.resume === 'string' ? options.resume.trim() : '';
+            let scopeCwd;
+            try {
+                scopeCwd = fs.realpathSync(cwd);
+            }
+            catch {
+                scopeCwd = cwd;
+            }
+            let session;
+            if (idArg) {
+                let matches = findSessionsById(idArg, { agent: sessionAgent, version, cwd: scopeCwd });
+                if (matches.length === 0) {
+                    const wide = findSessionsById(idArg, { agent: sessionAgent, version });
+                    if (wide.length > 0) {
+                        if (!options.quiet)
+                            process.stderr.write(chalk.gray(`No match for "${idArg}" in this project; widened to all projects.\n`));
+                        matches = wide;
+                    }
+                }
+                if (matches.length === 0) {
+                    console.error(chalk.red(`No ${agent} session matching "${idArg}".`));
+                    console.error(chalk.gray(`Browse sessions: agents sessions ${idArg}`));
+                    process.exit(1);
+                }
+                else if (matches.length === 1) {
+                    session = matches[0];
+                }
+                else if (wantsInteractive) {
+                    const picked = await pickSessionInteractive(matches, `Multiple sessions match "${idArg}":`);
+                    if (!picked)
+                        process.exit(0);
+                    session = picked.session;
+                }
+                else {
+                    console.error(chalk.red(`"${idArg}" is ambiguous — ${matches.length} sessions match:`));
+                    for (const m of matches.slice(0, 10)) {
+                        console.error(chalk.gray(`  ${m.shortId}  ${m.timestamp.slice(0, 16).replace('T', ' ')}  ${m.topic ?? m.label ?? ''}`));
+                    }
+                    console.error(chalk.gray('Pass more of the id, or resume interactively (drop the prompt).'));
+                    process.exit(1);
+                }
+            }
+            else {
+                // Bare --resume: pick from recent sessions in scope. Needs a TTY.
+                if (!wantsInteractive) {
+                    console.error(chalk.red('--resume with no id needs an interactive terminal. Pass a session id (full or prefix), or run without --headless.'));
+                    process.exit(1);
+                }
+                const recent = await discoverSessions({ agent: sessionAgent, version, limit: 200 });
+                if (recent.length === 0) {
+                    console.error(chalk.red(`No ${agent} sessions found to resume in this project.`));
+                    console.error(chalk.gray('Browse all: agents sessions'));
+                    process.exit(1);
+                }
+                const picked = await pickSessionInteractive(recent, `Resume which ${agent} session?`);
+                if (!picked)
+                    process.exit(0);
+                session = picked.session;
+                forceInteractive = true; // bare resume always lands in the agent's TUI
+            }
+            // Pin to the chosen session's own version (the isolated HOME the transcript
+            // lives in) and route by tier.
+            version = session.version;
+            if (nativeResume(agent)) {
+                resumeNative = true;
+                resumeSessionId = session.id;
+                if (!options.quiet)
+                    process.stderr.write(chalk.gray(`Resuming ${agent} ${session.shortId} (native)${version ? ` @${version}` : ''}\n`));
+            }
+            else {
+                // Tier-2: launch fresh with a /continue <id> first message; the agent
+                // loads the transcript via `agents sessions <id>` and picks up.
+                prompt = buildContinuePrompt(session.id, prompt);
+                if (prompt.trim() === `/continue ${session.id}`)
+                    forceInteractive = true;
+                if (!options.quiet)
+                    process.stderr.write(chalk.gray(`Resuming ${agent} ${session.shortId} (/continue replay)${version ? ` @${version}` : ''}\n`));
+            }
+        }
         const configuredStrategy = getConfiguredRunStrategy(agent, cwd);
         const explicitStrategy = options.strategy ? normalizeRunStrategy(options.strategy) : null;
         if (options.strategy && !explicitStrategy) {
@@ -639,7 +809,7 @@ export function registerRunCommand(program) {
             agent,
             version,
             prompt,
-            interactive: options.interactive,
+            interactive: options.interactive || forceInteractive,
             mode,
             effort,
             cwd: options.cwd,
@@ -647,7 +817,8 @@ export function registerRunCommand(program) {
             addDirs: options.addDir,
             json: options.json,
             headless: options.headless,
-            sessionId: options.sessionId,
+            sessionId: resumeSessionId ?? options.sessionId,
+            resume: resumeNative,
             verbose: options.verbose,
             timeout: options.timeout,
             env,