@phnx-labs/agents-cli 1.20.26 → 1.20.27

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,27 @@
 - **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.
+
 **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,25 @@ 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) ────────────────────────────────────────────────
 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';
+            rows.push({ agent, version, status, isDefault: version === def });
         }
-        const stale = isStale(manifest, agent, version, cwd);
-        rows.push({ agent, version, status: stale ? 'stale' : 'fresh' });
     }
     return rows;
 }
@@ -41,15 +44,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 +58,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,28 +66,40 @@ 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 {
         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}`);
             }
@@ -103,7 +112,7 @@ function renderOverviewText(clis, syncRows, orphanRows, hostClis) {
         }
     }
     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)'));
     }
@@ -340,9 +349,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 +427,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 +446,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/sessions.js

@@ -20,6 +20,7 @@ import { getActiveSessions } from '../lib/session/active.js';
 import { discoverSessions, countSessionsInScope, resolveSessionById, searchContentIndex } from '../lib/session/discover.js';
 import { filterTeamSessions } from '../lib/session/team-filter.js';
 import { parseSession } from '../lib/session/parse.js';
+import { runRemoteSessions } from '../lib/session/remote.js';
 import { renderConversationMarkdown, renderSummary, renderSummaryHeader, computeSummaryStats, renderJson, filterEvents, parseRoleList } from '../lib/session/render.js';
 import { renderMarkdown } from '../lib/markdown.js';
 import { colorAgent, resolveAgentName } from '../lib/agents.js';
@@ -313,6 +314,16 @@ async function renderActiveSessions(asJson) {
 }
 /** Main action handler for `agents sessions`. Routes to picker, table, or single-session render. */
 async function sessionsAction(query, options) {
+    if (options.host && options.host.length > 0) {
+        try {
+            runRemoteSessions(options.host);
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        return;
+    }
     if (options.active) {
         await renderActiveSessions(options.json === true);
         return;
@@ -1116,7 +1127,8 @@ export function registerSessionsCommands(program) {
         .option('--artifacts', 'List all files written or edited during a session')
         .option('--artifact <name>', 'Read a specific artifact by filename or path (outputs to stdout)')
         .option('--active', 'Show only sessions running right now across terminals, teams, cloud, and headless agents')
-        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk');
+        .option('--cloud', 'Source sessions from Rush Cloud (captured runs) instead of local disk')
+        .option('-H, --host <target...>', 'Run this query on remote machine(s) over SSH (host alias or user@host; repeatable)');
     setHelpSections(sessionsCmd, {
         examples: `
       # Search prior sessions in this project by topic, file path, or command
@@ -1136,8 +1148,15 @@ export function registerSessionsCommands(program) {
 
       # Export for analysis
       agents sessions --since 30d --limit 200 --json > sessions.json
+
+      # Search another machine's sessions live over SSH (no sync needed)
+      agents sessions "auth bug" --last 3 --host yosemite-s1
+
+      # Fan the same query out across several machines
+      agents sessions --all "deploy script" --host box-a --host box-b
     `,
         notes: `
+      - --host runs the query on the remote's own index over SSH (host alias or user@host); repeat or pass several to fan out. SSH access is the only auth.
       - --include and --exclude are mutually exclusive.
       - --first and --last are mutually exclusive.
       - A filter flag (--include/--exclude/--first/--last) without --markdown/--json defaults to --markdown output.

package/dist/index.js

@@ -11,6 +11,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { detectDevBuild } from './lib/startup/dev-build.js';
 // `ora`, `@inquirer/prompts`, `./commands/utils.js`, and the agents/versions/shims
 // modules are imported dynamically at their use sites: they are needed only on
 // interactive / update / shim-repair paths, never for fast commands like
@@ -37,18 +38,7 @@ import { NPM_PACKAGE_NAME, deriveGlobalPrefix, detectPackageManager, installPack
 // must not scribble on the user's real ~/.agents/), and skip the update prompt
 // (the "0.0.0-dev -> 1.x.y" message is misleading). Each individual env var
 // can still be set explicitly to override (set to '0' to re-enable).
-const IS_DEV_BUILD = (() => {
-    if (VERSION.startsWith('0.0.0-dev'))
-        return true;
-    try {
-        const cliPath = process.argv[1] || '';
-        const repoRoot = path.dirname(path.dirname(cliPath));
-        return fs.existsSync(path.join(repoRoot, '.git'));
-    }
-    catch {
-        return false;
-    }
-})();
+const IS_DEV_BUILD = detectDevBuild(process.argv[1] || '', VERSION);
 if (IS_DEV_BUILD) {
     if (process.env.AGENTS_NO_AUTOPULL === undefined)
         process.env.AGENTS_NO_AUTOPULL = '1';

package/dist/lib/agent-spec.d.ts

@@ -0,0 +1,36 @@
+import type { AgentId } from './types.js';
+export interface AgentTarget {
+    agent: AgentId;
+    /** Resolved exact version, or null when the agent has no installed versions yet. */
+    version: string | null;
+}
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
+export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export declare const AGENT_SPEC_HELP: string;
+export declare class AgentSpecError extends Error {
+    constructor(message: string);
+}
+export interface ResolveAgentTargetsOptions {
+    /** Project dir for resolving a bare spec's project pin. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Restrict the agents a spec may name (e.g. only mcp-capable). Defaults to all. */
+    availableAgents?: readonly AgentId[];
+}
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
+ * (`add`/`install` use a separate available-version path). Throws AgentSpecError
+ * on bad input — never calls process.exit, so it is safe on the hot path and in
+ * library contexts.
+ */
+export declare function resolveAgentTargets(spec: string, opts?: ResolveAgentTargetsOptions): AgentTarget[];
+/**
+ * Convenience for single-target commands (`use`, `run`): resolve a spec that
+ * must name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export declare function resolveSingleAgentTarget(spec: string, opts?: ResolveAgentTargetsOptions): {
+    agent: AgentId;
+    version: string;
+};

package/dist/lib/agent-spec.js

@@ -0,0 +1,157 @@
+// Centralized agent-spec resolution — one vocabulary, one resolver, reused by
+// every subcommand that accepts `<agent>[@<qualifier>]`.
+//
+// The qualifier vocabulary used to be split across three functions in
+// versions.ts (parseAgentSpec, resolveVersionAlias, resolveInstalledAgentTargets)
+// with diverging support — `@latest`/`@oldest` in one, `@all`/`@default` in
+// another, `@pinned` nowhere. This module is the single source of truth.
+//
+// Built for the hot path (`--launch`, ~100ms budget): the common specs resolve
+// with NO directory enumeration —
+//   exact `claude@2.1.181`   → one isVersionInstalled() (existsSync)
+//   `claude@pinned|@default` → memoized getGlobalDefault() + existsSync
+//   bare `claude`            → resolveVersion() (memoized meta), no readdir
+// Only the relative qualifiers `@latest`/`@oldest`/`@all` enumerate, and even
+// then via the mtime-cached listInstalledVersions().
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from './agents.js';
+import { listInstalledVersions, getGlobalDefault, isVersionInstalled, resolveVersion, } from './versions.js';
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export const AGENT_QUALIFIERS = ['latest', 'oldest', 'pinned', 'default', 'all'];
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
+    '@latest (highest installed), @oldest (lowest installed), ' +
+    '@pinned / @default (your configured default — synonyms), ' +
+    '@all (every installed version), or an exact @x.y.z. ' +
+    'Bare <agent> uses the resolved default (project pin → global default). ' +
+    'Comma-separate to combine: claude@all,codex@latest.';
+export class AgentSpecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentSpecError';
+    }
+}
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * Domain = installed: `@latest`/`@oldest`/`@all` range over installed versions
+ * (`add`/`install` use a separate available-version path). Throws AgentSpecError
+ * on bad input — never calls process.exit, so it is safe on the hot path and in
+ * library contexts.
+ */
+export function resolveAgentTargets(spec, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const available = opts.availableAgents ?? ALL_AGENT_IDS;
+    const rawEntries = spec
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (rawEntries.length === 0) {
+        throw new AgentSpecError('Empty agent spec.');
+    }
+    // Expand the bare literal `all` (or `all@all`) into every available agent that
+    // has at least one installed version. Lenient: agents with nothing installed
+    // are skipped rather than erroring.
+    const entries = [];
+    for (const e of rawEntries) {
+        if (e === 'all' || e === 'all@all') {
+            for (const a of available) {
+                if (listInstalledVersions(a).length > 0)
+                    entries.push(`${a}@all`);
+            }
+        }
+        else {
+            entries.push(e);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const push = (agent, version) => {
+        const key = `${agent}@${version ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ agent, version });
+        }
+    };
+    for (const entry of entries) {
+        const at = entry.indexOf('@');
+        const agentToken = (at === -1 ? entry : entry.slice(0, at)).trim();
+        const qualifier = at === -1 ? null : entry.slice(at + 1).trim();
+        if (!agentToken)
+            continue;
+        if (at !== -1 && !qualifier) {
+            throw new AgentSpecError(`Missing version in '${entry}'. Use ${agentToken}@x.y.z, @latest, @oldest, @pinned, @default, or @all.`);
+        }
+        const agent = resolveAgentName(agentToken);
+        if (!agent || !available.includes(agent)) {
+            throw new AgentSpecError(formatAgentError(agentToken, [...available]));
+        }
+        const name = AGENTS[agent].name;
+        // ----- bare: resolved default, NO enumeration in the common case -----
+        if (qualifier === null) {
+            const resolved = resolveVersion(agent, cwd); // project pin → global default (meta-only)
+            if (resolved) {
+                push(agent, resolved);
+            }
+            else {
+                const installed = listInstalledVersions(agent);
+                if (installed.length === 0)
+                    push(agent, null);
+                else if (installed.length === 1)
+                    push(agent, installed[0]);
+                else
+                    throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`);
+            }
+            continue;
+        }
+        // ----- @pinned / @default: synonyms, meta-only fast path -----
+        if (qualifier === 'pinned' || qualifier === 'default') {
+            const def = getGlobalDefault(agent);
+            if (!def) {
+                throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`);
+            }
+            push(agent, def);
+            continue;
+        }
+        // ----- @all: every installed version -----
+        if (qualifier === 'all') {
+            const installed = listInstalledVersions(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
+            }
+            for (const v of installed)
+                push(agent, v);
+            continue;
+        }
+        // ----- @latest / @oldest: enumerate (mtime-cached), pick an end -----
+        if (qualifier === 'latest' || qualifier === 'oldest') {
+            const installed = listInstalledVersions(agent); // already sorted ascending
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`);
+            }
+            push(agent, qualifier === 'oldest' ? installed[0] : installed[installed.length - 1]);
+            continue;
+        }
+        // ----- exact version: one existsSync, NO enumeration -----
+        if (!isVersionInstalled(agent, qualifier)) {
+            const installed = listInstalledVersions(agent);
+            const hint = installed.length ? ` Installed: ${installed.join(', ')}.` : '';
+            throw new AgentSpecError(`${name}@${qualifier} is not installed.${hint} Install it: agents add ${agent}@${qualifier}`);
+        }
+        push(agent, qualifier);
+    }
+    return out;
+}
+/**
+ * Convenience for single-target commands (`use`, `run`): resolve a spec that
+ * must name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export function resolveSingleAgentTarget(spec, opts = {}) {
+    const targets = resolveAgentTargets(spec, opts);
+    if (targets.length !== 1) {
+        throw new AgentSpecError(`'${spec}' resolves to ${targets.length} targets; this command needs exactly one.`);
+    }
+    const t = targets[0];
+    if (t.version === null) {
+        throw new AgentSpecError(`No installed version for ${AGENTS[t.agent].name}. Run: agents add ${t.agent}@latest`);
+    }
+    return { agent: t.agent, version: t.version };
+}

package/dist/lib/agents.js

@@ -296,6 +296,7 @@ export const AGENTS = {
         commandsDir: '', // OpenClaw uses Gateway-based slash commands, not file-based
         commandsSubdir: '',
         skillsDir: path.join(HOME, '.openclaw', 'skills'),
+        nativeCommandRuntime: true, // Gateway resolves slash commands — don't convert commands to skills
         hooksDir: 'hooks',
         instructionsFile: 'workspace/AGENTS.md', // Primary memory file (also has SOUL.md, IDENTITY.md, etc.)
         format: 'markdown',

package/dist/lib/daemon.js

@@ -260,6 +260,36 @@ export async function runDaemon() {
     };
     const syncInterval = setInterval(() => { void runSessionSync(); }, 90_000);
     void runSessionSync(); // kick once at startup
+    // Resource safety check: heal gaps between what DotAgents repos define and
+    // what's actually installed in each agent home — the slow rot that nothing
+    // else catches (a non-default version left stale, a Claude-invalid plugin
+    // manifest silently rejecting a whole plugin). Conservative 'safe' mode: it
+    // fills missing resources, repairs invalid manifests, and fast-forwards
+    // provably-unmodified stale plugins, but never overwrites hand-edited content
+    // or a plugin it can't prove is pristine — those it reports for `doctor --fix`.
+    // Runs ~every 6h plus once ~30s after startup (staggered so launch isn't busy).
+    let healing = false;
+    const runHealCheck = async () => {
+        if (healing)
+            return;
+        healing = true;
+        try {
+            const { heal, summarizeHeal, notifyHeal, healChangedAnything } = await import('./heal.js');
+            const result = await heal({ mode: 'safe' });
+            if (healChangedAnything(result) || result.skippedPlugins.length > 0) {
+                log('INFO', `heal: ${summarizeHeal(result)}`);
+                notifyHeal(result);
+            }
+        }
+        catch (err) {
+            log('ERROR', `heal check failed: ${err.message}`);
+        }
+        finally {
+            healing = false;
+        }
+    };
+    const healInterval = setInterval(() => { void runHealCheck(); }, 6 * 60 * 60_000);
+    const healKickoff = setTimeout(() => { void runHealCheck(); }, 30_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -275,6 +305,8 @@ export async function runDaemon() {
         await browserIPC.stop();
         clearInterval(monitorInterval);
         clearInterval(syncInterval);
+        clearInterval(healInterval);
+        clearTimeout(healKickoff);
         removeDaemonPid();
         process.exit(0);
     };

package/dist/lib/doctor-diff.d.ts

@@ -59,6 +59,13 @@ export interface DiffOptions {
     cwd?: string;
     /** Restrict to specific kinds; undefined = all. */
     kinds?: DoctorKind[];
+    /**
+     * Drop the project (`<cwd>/.agents/`) layer from resolution. Used by the heal
+     * path: the GLOBAL version home is only ever reconciled against user/system/
+     * extra sources — project resources are layered at launch, never synced into
+     * the global home, so counting them as "missing" there is a false gap.
+     */
+    excludeProject?: boolean;
 }
 export declare function diffVersionResources(agent: AgentId, version: string, options?: DiffOptions): VersionResourceReport;
 export declare const DOCTOR_ALL_KINDS: DoctorKind[];