@phnx-labs/agents-cli 1.20.45 → 1.20.46

package/CHANGELOG.md

@@ -2,10 +2,13 @@
 
 ## Unreleased
 
-## 1.20.45
+## 1.20.46
 
-- **NEW: `agents run <agent> --host <name>` without a prompt forwards your TTY over SSH and runs the agent interactively on the remote host.** Previously `--host` runs required a prompt and were always headless (`agents run <agent> "<task>" --host <name>`). Now, omitting the prompt takes the interactive path: when local stdin is a TTY, the local CLI SSHes with `-tt`, runs `agents run <agent>` on the host, and lets the remote machine's `agents` start its normal tmux wrapper. The tmux session lives on the remote box, so detaching (`Ctrl-b d`) ends the SSH connection but keeps the agent running; you can reattach from the host or resume by session id. Session ids for Claude are still minted up front so `agents sessions` can surface and resolve the remote run. `--no-follow` is rejected for interactive host runs (it is meaningless for an attached TTY), and `--mode`, `--model`, `--name`, passthrough args after `--`, and `--raw`/`--no-tmux` are forwarded to the remote invocation. Source: `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/hosts/dispatch.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/docs/hosts.md`.
+- **NEW: `Cmd-Shift-O` opens a Spotlight-style quick-issue bar in the menu-bar helper — type a sentence, attach recent screenshots, and an agent files the Linear ticket for you.** The menu-bar helper already turned a screenshot into a `<host>:<path>` token with `Cmd-Shift-V` (clip capture), but there was no path from "I see a bug" to "a triaged ticket exists." The new chord summons a borderless panel (a thin capture surface, not another form): you type a one-line note, optionally toggle one or more recent screenshots (from the system screencapture folder, CleanShot's export path, or the clip history) as a thumbnail strip (the newest is pre-selected when it's fresh), and hit Return. It then **dispatches a headless agent** (`agents run claude --mode auto`, isolated behind one `AgentsCLI.dispatchTicketAgent` call so a cloud pod is a later swap) that reads the screenshots, runs `agents sessions` to identify which repo/project this concerns, does a brief investigation for real context, and files the ticket via `~/.agents/skills/linear/scripts/linear create` with an honest priority + a `repo:<name>` label — no preview step, the panel closes immediately and a notification reports the created `RUSH-####`. Focus is handled for a no-Dock `.accessory` app (`NSApp.activate` → `makeKeyAndOrderFront` → `makeFirstResponder`, with a borderless `NSPanel` overriding `canBecomeKey`; click-outside dismissal is armed only after the summon settles so the activation race can't self-dismiss the panel). The `Cmd-Shift-V` clip hotkey is unchanged — the Carbon hotkey manager now demultiplexes both chords by `EventHotKeyID.id` through one installed handler. Self-test: `MENUBAR_ISSUE_TEST=1 MenubarHelper` exercises screenshot selection, ticket-id parsing, and the meta-prompt contract; `MENUBAR_PROMPT_PREVIEW=1` renders the panel without the global hotkey for QA. Source: `apps/cli/menubar/Sources/MenubarHelper/{PromptPanel,Hotkey,AgentsCLI,main,IssueSelfTest,Clip}.swift`.
 
+- **NEW: a unified self-heal subsystem — the shim/PATH "repair" notice no longer nags on every terminal, and the daemon now heals shim drift in the background.** agents-cli had accumulated ~37 separate repair routines scattered across the daemon, every CLI startup, and a handful of commands, each hand-rolling its own detect+fix on its own trigger. The most visible symptom: the interactive shim bootstrap (`maybeBootstrapShimIntegration`) regenerated shims, adopted shadowing launchers, and offered to add the shims dir to PATH **in the foreground on every invocation**, suppressed only by a `process.ppid`-keyed temp sentinel — so a new terminal re-ran the whole detect-and-nag, and the underlying condition was never permanently fixed. This lands a single `HealCheck` registry (`lib/self-heal/`) with one runner (`runSelfHeal`) driven by two front doors — the daemon (on its existing ~30s-after-start + ~6h `safe`-mode cycle) and the interactive startup — sharing the same checks: `shims` (regenerate stale shims/aliases), `shadowing` (adopt symlink launchers; report real-binary shadows), `path` (add the shims dir to PATH once), and `resources` (the existing `heal()` engine, wrapped unchanged). The daemon's heal cycle now runs all four in `safe` mode (low-risk fixes silently; risky ones reported), replacing the resource-only `heal()` call — and drops the desktop toast for background heals (the log is the record). The interactive startup now heals **silently** and prints at most a **persistent, once-per-condition** notice (`lib/shim-heal.ts`, keyed to a signature of the actionable state under `~/.agents/.cache/state/shim-notice.json`) for what a machine genuinely can't fix for you — a real native binary shadowing the shim — instead of re-nagging every shell. What changes is *where* the repairs run (background/silent) and *how often* you hear about them (once, not every terminal). Source: `apps/cli/src/lib/self-heal/` (new), `apps/cli/src/lib/shim-heal.ts` (new), `apps/cli/src/lib/daemon.ts`, `apps/cli/src/index.ts`, `apps/cli/src/lib/shims.ts` (`isShimCurrent` exported).
+## 1.20.45
+- **NEW: `agents run <agent> --host <name>` without a prompt forwards your TTY over SSH and runs the agent interactively on the remote host.** Previously `--host` runs required a prompt and were always headless (`agents run <agent> "<task>" --host <name>`). Now, omitting the prompt takes the interactive path: when local stdin is a TTY, the local CLI SSHes with `-tt`, runs `agents run <agent>` on the host, and lets the remote machine's `agents` start its normal tmux wrapper. The tmux session lives on the remote box, so detaching (`Ctrl-b d`) ends the SSH connection but keeps the agent running; you can reattach from the host or resume by session id. Session ids for Claude are still minted up front so `agents sessions` can surface and resolve the remote run. `--no-follow` is rejected for interactive host runs (it is meaningless for an attached TTY), and `--mode`, `--model`, `--name`, passthrough args after `--`, and `--raw`/`--no-tmux` are forwarded to the remote invocation. Source: `apps/cli/src/commands/exec.ts`, `apps/cli/src/lib/hosts/dispatch.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/docs/hosts.md`.
 - **`agents secrets export --host` now works against Windows targets, and a new `agents secrets unlock --host` unlocks a bundle on a remote machine.** The export push was POSIX-only (`bash -lc`, `--from /dev/stdin`, `create … || true`, `IFS= read`), so a Windows remote died with `'true' is not recognized … cannot find the path specified`. Two changes fix it: `agents secrets import` now accepts **`--from -`** (read the `.env` from stdin, replacing the POSIX-only `/dev/stdin`), and the push is **platform-aware** — `bash -lc` on POSIX, `powershell -EncodedCommand` on Windows, with the target's OS taken from the device registry. Because the npm `agents.ps1` shim does **not** forward ssh-piped stdin to the underlying node process (a raw `--from -` read hangs), the Windows keychain push bridges the piped `.env` through PowerShell into a temp file and imports `--from <file>` (deleted afterwards). File-backend export to a Windows target is refused cleanly rather than emitting broken PowerShell. Verified end-to-end: `agents secrets export linear.app --host win-mini` imported all 13 keys. Separately, **`agents secrets unlock --host <machine> <bundle>`** runs the unlock ON the remote over `ssh -tt`, so a **file-backed** bundle's passphrase prompt surfaces on your terminal — the "unlock the Mac from the road with its password" path; keychain/biometry bundles are GUI-only (a local Touch-ID/passcode sheet can't cross SSH) and can't be remote-unlocked. `unlock`'s `--host` is single-valued so it never swallows the positional bundle name. Source: `apps/cli/src/commands/secrets.ts`, `apps/cli/src/lib/hosts/remote-cmd.ts`.
 - **A session now has ONE name, not two. `--name` seeds the session label instead of a parallel column.** Shipping `agents run --name` (1.20.43) as a separate immutable `name` column created two look-alike fields — an unshown, frozen `name` and the shown, searchable `label` — that both resolved `agents sessions <ref>` and forced tie-break bookkeeping nobody could keep straight. They unify into one field. `--name` is now the universal way to *seed* the `label` at launch — the same field an agent-generated title (Claude's `/rename`) later refines and `agents sessions` displays and searches — and it works consistently across interactive, headless, `--host`, and teams teammate runs (a teammate's friendly name now seeds its session label; before, teammate sessions had no name at all). Priority is a plain fallback chain resolved at scan time, no stored winner: an agent-generated title wins, else the `--name` seed, else the listing falls back to `topic`. So a Claude run's `--name` shows until Claude titles it (your seed, then refined); a non-Claude run keeps its `--name` as the label (it has no auto-title). The seeded name is now fuzzy-searchable in FTS (the old `name` column was not). `agents hosts logs <name>` is unchanged — it resolves against the host-task sidecar, not the session column. Schema v10 folds any existing `name` into `label` (where the label was empty), mirrors it into the FTS row, then drops the `name` column; the run-name sidecars re-seed every scan (`seedLabelsFromNames`), so no rescan is needed. Reworks the 1.20.43 `--name` design (partly reverts its separate-column approach). Source: `apps/cli/src/lib/session/{db,discover,run-names,types}.ts`, `apps/cli/src/lib/hosts/session-index.ts`, `apps/cli/src/lib/teams/agents.ts`, `apps/cli/src/commands/exec.ts`, `apps/cli/docs/{05-sessions,hosts}.md`.
 - **NEW: `agents teams add`/`start` warns when a *version-pinned* teammate is on a throttled or signed-out account.** The 1.20.43 `balanced`-default fix keeps *bare* teammates off rate-limited accounts (they route through bare `agents run`, which rotates), but a **version-pinned** (`claude@2.1.112`) or **profile** teammate spawns `agents run <agent>@<version>` / `agents run <profile>`, and a pin/profile deliberately *bypasses* rotation — so it would launch straight onto a maxed account and 429 on the first request, with no mid-run failover either (that only arms when a non-pinned strategy actually rotated). `agents teams add` (at add time) and `agents teams start` (per staged teammate, deduped by `agent@version`) now pre-check a **version-pinned** teammate's account and print an advisory when it's rate-limited, out of credits, or not signed in — reusing the router's *exact* eligibility gate (`checkRunAccountReadiness` → `hasUsageAvailable`, the same session-inclusive signal the `agents view` badge uses), so the warning can never disagree with what the spawn would actually do. It **warns, never blocks** (mirroring the existing "may not be signed in" advisory); `--force` silences it. Scoped to version-pinned teammates on purpose: bare teammates are already handled by rotation, and a profile injects its own auth (a different account than the version home carries) that isn't locally checkable — so no unreliable profile warning is emitted. Source: `apps/cli/src/lib/rotate.ts` (`readinessFromCandidate`, `checkRunAccountReadiness`, `rotate.test.ts`), `apps/cli/src/commands/teams.ts`.

package/dist/index.js

@@ -8,7 +8,6 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 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';
@@ -54,7 +53,6 @@ if (IS_DEV_BUILD) {
 import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadPackages, loadDaemon, loadRoutines, loadRun, loadDefaults, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadCheck, loadStatus, loadProfiles, loadSecrets, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadBudget, loadAlias, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadSsh, loadPull, loadPush, loadRepo, loadSetup, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
-import { IS_WINDOWS } from './lib/platform/index.js';
 import { emit, redactArgs } from './lib/events.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
@@ -477,124 +475,21 @@ async function maybeBootstrapShimIntegration(requestedCommand, helpOrVersionRequ
     if (requestedCommand === 'sync' || requestedCommand === 'refresh-rules') {
         return;
     }
-    // Past the documentation/non-TTY guards: only now load the shim + agent
-    // tables this interactive repair flow needs, so fast commands never pay for
-    // them at module-eval time.
-    const { confirm } = await import('@inquirer/prompts');
-    const { AGENTS } = await import('./lib/agents.js');
-    const { getGlobalDefault, listInstalledVersions } = await import('./lib/versions.js');
-    const { addShimsToPath, adoptShadowingLauncher, ensureShimCurrent, ensureVersionedAliasCurrent, getPathShadowingExecutable, getPathSetupInstructions, getShimsDir, isShimsInPath, listAgentsWithInstalledVersions, removeLegacyUserShim, } = await import('./lib/shims.js');
-    const installedAgents = listAgentsWithInstalledVersions();
-    if (installedAgents.length === 0) {
-        return;
-    }
-    const createdOrUpdated = [];
-    for (const agent of installedAgents) {
-        const status = ensureShimCurrent(agent);
-        if (status !== 'current') {
-            createdOrUpdated.push(`${status === 'created' ? 'Created' : 'Updated'} ${AGENTS[agent].cliCommand} shim`);
-        }
-        for (const version of listInstalledVersions(agent)) {
-            const aliasStatus = ensureVersionedAliasCurrent(agent, version);
-            if (aliasStatus !== 'current') {
-                createdOrUpdated.push(`${aliasStatus === 'created' ? 'Created' : 'Updated'} ${AGENTS[agent].cliCommand}@${version} alias`);
-            }
-        }
-    }
-    for (const notice of createdOrUpdated) {
-        console.log(chalk.green(notice));
-    }
-    // Best-effort: remove leftover ~/.agents/shims/<cli> files from the pre-split
-    // layout BEFORE running detection. These cause false-positive "shadowing"
-    // results that make the repair prompt loop forever (the prompt user said
-    // "yes" to never deletes the file; next invocation finds it again).
-    for (const agent of installedAgents) {
-        removeLegacyUserShim(agent);
-    }
-    // The remaining flow is rc-file PATH repair, which is POSIX-only. On Windows
-    // the shims were just regenerated (incl. `.cmd` companions) above; PATH setup
-    // is covered by the install-time guidance, so stop here rather than printing
-    // shell-rc instructions that don't apply.
-    if (IS_WINDOWS) {
-        return;
-    }
-    const defaultAgents = installedAgents.filter((agent) => getGlobalDefault(agent));
-    // Auto-adopt any harness launcher that shadows our shim. PATH-order repair
-    // (below) cannot win against `~/.local/bin` — it's prepended in .zshenv for
-    // every shell while our prepend only lands in .zshrc — so for symlink
-    // launchers we *become* the launcher instead. Detection keys on the launcher
-    // symlink EXISTING (via adoptShadowingLauncher's own fallback), not on this
-    // shell's PATH order, so it also heals the GUI/non-interactive shadow an
-    // interactive run can't see. Reversible; only ever rewrites a symlink.
-    for (const agent of defaultAgents) {
-        const result = adoptShadowingLauncher(agent);
-        if (result.adopted) {
-            console.log(chalk.green(`Adopted ${AGENTS[agent].cliCommand} launcher (${result.launcher}) — version management now wins regardless of PATH order.`));
-        }
-    }
-    // Recompute AFTER adoption so anything we just took over drops out. What
-    // remains is a real binary we deliberately don't touch (adoption is
-    // symlink-only) — those get an honest one-time note, never a looping prompt.
-    const shadowed = defaultAgents
-        .map((agent) => ({ agent, shadowedBy: getPathShadowingExecutable(agent) }))
-        .filter((item) => Boolean(item.shadowedBy));
-    // After adoption, the only things left are (a) real-binary shadows we won't
-    // touch, and (b) a genuinely missing PATH entry. Nothing else needs the user.
-    const pathMissing = !isShimsInPath();
-    if (shadowed.length === 0 && !pathMissing) {
-        return;
-    }
-    // Suppress repeated notices within the same shell. A successful rc-file edit
-    // doesn't reload the parent shell, so the next invocation re-fires detection.
-    // The sentinel survives only as long as the parent shell process — a new
-    // terminal (new PPID) is allowed to surface it again.
-    const sentinelPath = path.join(os.tmpdir(), `agents-shim-prompted-${process.ppid}`);
-    if (fs.existsSync(sentinelPath)) {
-        return;
-    }
-    // Real-binary shadows: adoption is symlink-only (we never rename a real native
-    // binary), and `addShimsToPath` provably can't outrank an early-PATH dir like
-    // ~/.local/bin across zsh's whole sourcing chain. So DON'T offer a "Repair?"
-    // prompt here — that was the infinite-loop bug (Yes was always a no-op).
-    // Inform once and point at the real levers.
-    if (shadowed.length > 0) {
-        const targets = shadowed
-            .map(({ agent, shadowedBy }) => `  ${AGENTS[agent].cliCommand}: ${shadowedBy}`)
-            .join('\n');
-        console.log(chalk.yellow('These agent commands run a native binary instead of the version-managed shim:'));
-        console.log(chalk.gray(targets));
-        console.log(chalk.gray(`It's a real binary (not a symlink), so agents-cli won't move it. To hand it to agents-cli, remove/reorder it, or put ${getShimsDir()} earlier in PATH.`));
-    }
-    // Genuinely-missing PATH entry is the one thing addShimsToPath actually fixes,
-    // so it's the only case that still earns an interactive prompt.
-    if (pathMissing) {
-        const shouldRepair = await confirm({
-            message: 'Add the agents-cli shims directory to your PATH now?',
-            default: true,
-        });
-        if (!shouldRepair) {
-            console.log(chalk.gray(getPathSetupInstructions()));
-        }
-        else {
-            const pathResult = addShimsToPath();
-            if (!pathResult.success) {
-                console.log(chalk.yellow('Could not update PATH automatically.'));
-                console.log(chalk.gray(pathResult.error || getPathSetupInstructions()));
-            }
-            else if (pathResult.alreadyPresent) {
-                console.log(chalk.yellow(`Shim PATH entry is already in ~/${pathResult.rcFile} — this shell just needs to reload it.`));
-                console.log(chalk.gray(`Run: source ~/${pathResult.rcFile}   (or open a new terminal)`));
-            }
-            else {
-                console.log(chalk.green(`Added shims to PATH in ~/${pathResult.rcFile}`));
-                console.log(chalk.gray(getPathSetupInstructions()));
-            }
-        }
-    }
-    try {
-        fs.writeFileSync(sentinelPath, '1');
+    // Past the documentation/non-TTY guards: heal the shim/shadow/PATH conditions
+    // through the unified self-heal registry — the SAME checks the daemon runs, but
+    // driven silently on this interactive invocation so a user who never starts the
+    // daemon still gets healed. Regenerating stale shims, adopting symlink launchers,
+    // and adding the shims dir to PATH now happen without any output. The only thing
+    // that ever prints is a ONE-TIME notice for what a machine can't silently fix
+    // (a real native binary shadowing the shim) or is worth saying once (a PATH entry
+    // just added). Suppression is persistent and keyed to the condition — a new
+    // terminal no longer re-nags (the old per-PPID sentinel did, every shell).
+    const { healShimsInteractive } = await import('./lib/shim-heal.js');
+    const noticeLines = await healShimsInteractive();
+    if (noticeLines) {
+        for (const line of noticeLines)
+            console.log(chalk.gray(line));
     }
-    catch { /* best-effort */ }
 }
 // --- Inline command registrars ----------------------------------------------
 // These commands are defined here rather than in a command module because they

package/dist/lib/daemon.js

@@ -374,15 +374,18 @@ export async function runDaemon() {
             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);
+            const { runSelfHeal, selfHealChangedAnything, selfHealNeedsAttention, summarizeSelfHeal } = await import('./self-heal/registry.js');
+            // Background heal is conservative (mode: 'safe'): fixes low-risk drift (shims,
+            // symlink adoption, PATH, missing resources) and only reports risky ones. The
+            // 30s kickoff means shims/PATH settle shortly after the daemon starts. No
+            // desktop toast here — background heal is silent by design; the log is the record.
+            const report = await runSelfHeal({ mode: 'safe' });
+            if (selfHealChangedAnything(report) || selfHealNeedsAttention(report)) {
+                log('INFO', `self-heal: ${summarizeSelfHeal(report)}`);
             }
         }
         catch (err) {
-            log('ERROR', `heal check failed: ${err.message}`);
+            log('ERROR', `self-heal check failed: ${err.message}`);
         }
         finally {
             healing = false;

package/dist/lib/self-heal/checks/path.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const pathCheck: HealCheck;

package/dist/lib/self-heal/checks/path.js

@@ -0,0 +1,30 @@
+// path check — ensures the shims dir is on PATH. On POSIX it appends to the shell
+// rc file; on Windows it registers on the user PATH (registry). addShimsToPath is a
+// no-op when already present, so this is idempotent. Formerly an interactive prompt
+// in index.ts fired on every new shell; here the daemon does it once, silently.
+//
+// Caveat: an already-open shell won't pick up the new rc/PATH entry until it reloads
+// — but new shells will, so the recurring prompt stops.
+import { resultOf } from '../types.js';
+import { isShimsInPath, addShimsToPath } from '../../shims.js';
+export const pathCheck = {
+    id: 'path',
+    title: 'Shims directory on PATH',
+    cadence: 'startup',
+    async run(ctx) {
+        if (isShimsInPath())
+            return resultOf([], []);
+        if (ctx.dryRun)
+            return resultOf(['add shims dir to PATH'], []);
+        const r = addShimsToPath();
+        if (r.success && !r.alreadyPresent) {
+            return resultOf([`added shims to PATH (${r.location ?? r.rcFile ?? 'PATH'})`], []);
+        }
+        if (r.success && r.alreadyPresent) {
+            // Present in the rc file but not in THIS process's PATH — a reload issue,
+            // not something to fix again. Report quietly.
+            return resultOf([], [`shims dir in ${r.rcFile ?? 'rc file'} but not loaded — open a new terminal`]);
+        }
+        return resultOf([], [`could not add shims to PATH: ${r.error ?? 'unknown'}`]);
+    },
+};

package/dist/lib/self-heal/checks/resources.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const resourcesCheck: HealCheck;

package/dist/lib/self-heal/checks/resources.js

@@ -0,0 +1,36 @@
+// resources check — reconciles each installed version's home against the DotAgents
+// definitions (commands, skills, hooks, rules, mcp, plugins). This is a thin adapter
+// over the existing, battle-tested heal() engine (lib/heal.ts) — no behavior change;
+// it just re-expresses heal()'s result in the unified CheckResult shape.
+import { resultOf } from '../types.js';
+export const resourcesCheck = {
+    id: 'resources',
+    title: 'Resource sync (commands, skills, hooks, rules, plugins)',
+    cadence: 'periodic',
+    async run(ctx) {
+        // Lazy import so the (heavy) heal graph only loads when this check actually runs.
+        const { heal } = await import('../../heal.js');
+        const result = await heal({ mode: ctx.mode, dryRun: ctx.dryRun });
+        const fixed = [];
+        const needsAttention = [];
+        let healed = 0;
+        for (const v of result.versions) {
+            healed += v.healed.length;
+            for (const s of v.skipped) {
+                needsAttention.push(`${v.agent}@${v.version}: ${s.kind}/${s.name} (${s.reason})`);
+            }
+        }
+        if (healed > 0)
+            fixed.push(`${healed} resource(s) reconciled`);
+        for (const m of result.repairedManifests) {
+            fixed.push(`plugin ${m.plugin}: dropped ${m.droppedFields.join(', ')}`);
+        }
+        for (const p of result.refreshedPlugins) {
+            fixed.push(`plugin ${p.plugin}: ${p.from} -> ${p.to}`);
+        }
+        for (const s of result.skippedPlugins) {
+            needsAttention.push(`plugin ${s.plugin}: ${s.reason} (${s.from} vs ${s.upstream})`);
+        }
+        return resultOf(fixed, needsAttention);
+    },
+};

package/dist/lib/self-heal/checks/shadowing.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const shadowingCheck: HealCheck;

package/dist/lib/self-heal/checks/shadowing.js

@@ -0,0 +1,48 @@
+// shadowing check — when a harness's own launcher shadows our shim on PATH, adopt
+// it (symlink-only, reversible) so version management wins regardless of PATH order.
+// A REAL native binary is never moved — it's surfaced as needsAttention so the
+// interactive layer can inform the user once. POSIX-only (the launcher convention
+// and PATH-order problem are POSIX; Windows resolves via the registry PATH).
+import { resultOf } from '../types.js';
+import { AGENTS } from '../../agents.js';
+import { getPathShadowingExecutable, adoptShadowingLauncher, listAgentsWithInstalledVersions, } from '../../shims.js';
+import { getGlobalDefault } from '../../versions.js';
+export const shadowingCheck = {
+    id: 'shadowing',
+    title: 'Launcher shadowing the version-managed shim',
+    platforms: ['darwin', 'linux'],
+    cadence: 'frequent',
+    async run(ctx) {
+        const fixed = [];
+        const needsAttention = [];
+        for (const agent of listAgentsWithInstalledVersions()) {
+            if (!getGlobalDefault(agent))
+                continue; // only default agents, like the interactive flow
+            const cmd = AGENTS[agent].cliCommand;
+            const shadowedBy = getPathShadowingExecutable(agent);
+            if (!shadowedBy)
+                continue;
+            if (ctx.dryRun) {
+                // Classify without mutating: adoption only ever touches a symlink.
+                let isSymlink = false;
+                try {
+                    const fs = await import('node:fs');
+                    isSymlink = fs.lstatSync(shadowedBy).isSymbolicLink();
+                }
+                catch { /* treat as real binary */ }
+                if (isSymlink)
+                    fixed.push(`${cmd} launcher (${shadowedBy})`);
+                else
+                    needsAttention.push(`${cmd}: real binary shadows the shim (${shadowedBy})`);
+                continue;
+            }
+            const res = adoptShadowingLauncher(agent);
+            if (res.adopted)
+                fixed.push(`adopted ${cmd} launcher (${res.launcher})`);
+            else if (res.reason === 'not-a-symlink') {
+                needsAttention.push(`${cmd}: real binary shadows the shim (${shadowedBy})`);
+            }
+        }
+        return resultOf(fixed, needsAttention);
+    },
+};

package/dist/lib/self-heal/checks/shims.d.ts

@@ -0,0 +1,2 @@
+import type { HealCheck } from '../types.js';
+export declare const shimsCheck: HealCheck;

package/dist/lib/self-heal/checks/shims.js

@@ -0,0 +1,35 @@
+// shims check — keeps the dispatch shims and versioned aliases current, and clears
+// pre-split legacy shim files. Formerly done in the interactive index.ts startup
+// (which PRINTED "Updated <cli> shim" on every run); here it runs silently in the
+// background so the shim schema settles without user-facing churn.
+import { resultOf } from '../types.js';
+import { AGENTS } from '../../agents.js';
+import { ensureShimCurrent, ensureVersionedAliasCurrent, isShimCurrent, isVersionedAliasCurrent, removeLegacyUserShim, listAgentsWithInstalledVersions, } from '../../shims.js';
+import { listInstalledVersions } from '../../versions.js';
+export const shimsCheck = {
+    id: 'shims',
+    title: 'Dispatch shims + versioned aliases',
+    cadence: 'frequent',
+    async run(ctx) {
+        const fixed = [];
+        for (const agent of listAgentsWithInstalledVersions()) {
+            const cmd = AGENTS[agent].cliCommand;
+            if (!isShimCurrent(agent)) {
+                if (!ctx.dryRun)
+                    ensureShimCurrent(agent);
+                fixed.push(`${cmd} shim`);
+            }
+            for (const version of listInstalledVersions(agent)) {
+                if (!isVersionedAliasCurrent(agent, version)) {
+                    if (!ctx.dryRun)
+                        ensureVersionedAliasCurrent(agent, version);
+                    fixed.push(`${cmd}@${version} alias`);
+                }
+            }
+            // Pre-split ~/.agents/shims/<cli> files cause false-positive shadow hits.
+            if (!ctx.dryRun && removeLegacyUserShim(agent))
+                fixed.push(`removed legacy ${cmd} shim`);
+        }
+        return resultOf(fixed, []);
+    },
+};

package/dist/lib/self-heal/registry.d.ts

@@ -0,0 +1,22 @@
+import type { HealCheck, HealCheckId, HealCadence, SelfHealReport } from './types.js';
+export declare const HEAL_CHECKS: HealCheck[];
+export interface SelfHealOptions {
+    /** Restrict to these check ids; omit to run every registered check. */
+    checks?: HealCheckId[];
+    /** Only run checks whose cadence is in this set (daemon scheduling). */
+    cadences?: HealCadence[];
+    /** 'safe' (daemon default) or 'full' (doctor --fix). Default 'safe'. */
+    mode?: 'safe' | 'full';
+    /** Detect only — never write. Default false. */
+    dryRun?: boolean;
+    /** Override the platform gate (tests). Default process.platform. */
+    platform?: NodeJS.Platform;
+}
+/** Run the selected checks, isolating per-check failures. */
+export declare function runSelfHeal(opts?: SelfHealOptions): Promise<SelfHealReport>;
+/** True if any check repaired something (for daemon logging / notification). */
+export declare function selfHealChangedAnything(report: SelfHealReport): boolean;
+/** True if any check surfaced something a human should look at. */
+export declare function selfHealNeedsAttention(report: SelfHealReport): boolean;
+/** One-line human summary, e.g. "shims: 2 fixed; path: 1 fixed". */
+export declare function summarizeSelfHeal(report: SelfHealReport): string;

package/dist/lib/self-heal/registry.js

@@ -0,0 +1,66 @@
+// The self-heal registry + runner.
+//
+// One ordered list of HealChecks; one runner that executes the requested subset,
+// isolating failures (one check throwing never aborts the rest) and aggregating a
+// SelfHealReport. Both front doors — the daemon (by cadence) and `agents doctor`
+// (all, or by id) — call runSelfHeal.
+import { resourcesCheck } from './checks/resources.js';
+import { shimsCheck } from './checks/shims.js';
+import { shadowingCheck } from './checks/shadowing.js';
+import { pathCheck } from './checks/path.js';
+// Order matters: cheap structural fixes (shims, shadow adoption, PATH) before the
+// heavier resource reconciliation, so a freshly-repaired shim is in place first.
+export const HEAL_CHECKS = [
+    shimsCheck,
+    shadowingCheck,
+    pathCheck,
+    resourcesCheck,
+];
+/** Run the selected checks, isolating per-check failures. */
+export async function runSelfHeal(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const ctx = { mode: opts.mode ?? 'safe', dryRun: opts.dryRun ?? false };
+    const selected = HEAL_CHECKS.filter((c) => {
+        if (opts.checks && !opts.checks.includes(c.id))
+            return false;
+        if (opts.cadences && !opts.cadences.includes(c.cadence))
+            return false;
+        if (c.platforms && !c.platforms.includes(platform))
+            return false;
+        return true;
+    });
+    const reports = [];
+    for (const check of selected) {
+        try {
+            const result = await check.run(ctx);
+            reports.push({ id: check.id, title: check.title, result });
+        }
+        catch (err) {
+            reports.push({ id: check.id, title: check.title, result: null, error: err.message });
+        }
+    }
+    return { checks: reports };
+}
+/** True if any check repaired something (for daemon logging / notification). */
+export function selfHealChangedAnything(report) {
+    return report.checks.some((c) => (c.result?.fixed.length ?? 0) > 0);
+}
+/** True if any check surfaced something a human should look at. */
+export function selfHealNeedsAttention(report) {
+    return report.checks.some((c) => (c.result?.needsAttention.length ?? 0) > 0 || Boolean(c.error));
+}
+/** One-line human summary, e.g. "shims: 2 fixed; path: 1 fixed". */
+export function summarizeSelfHeal(report) {
+    const parts = [];
+    for (const c of report.checks) {
+        if (c.error) {
+            parts.push(`${c.id}: error (${c.error})`);
+            continue;
+        }
+        const n = c.result?.fixed.length ?? 0;
+        const a = c.result?.needsAttention.length ?? 0;
+        if (n > 0 || a > 0)
+            parts.push(`${c.id}: ${n} fixed${a > 0 ? `, ${a} to review` : ''}`);
+    }
+    return parts.join('; ') || 'nothing to heal';
+}

package/dist/lib/self-heal/types.d.ts

@@ -0,0 +1,41 @@
+export type HealCheckId = 'resources' | 'shims' | 'shadowing' | 'path';
+/** When the daemon schedules a check. */
+export type HealCadence = 'startup' | 'frequent' | 'periodic';
+export interface HealCtx {
+    /** 'safe' = daemon (low-risk only); 'full' = doctor --fix (everything). */
+    mode: 'safe' | 'full';
+    /** Detect only — never write. Powers `agents doctor` (read-only) and previews. */
+    dryRun: boolean;
+}
+/** Outcome of one check. `ok` means nothing was wrong. */
+export interface CheckResult {
+    /** Things repaired (or, under dryRun, that WOULD be repaired). Human-readable. */
+    fixed: string[];
+    /** Detected but not auto-fixed: unfixable, or risky-in-safe-mode. Human-readable. */
+    needsAttention: string[];
+    /** True iff detect found nothing wrong (fixed and needsAttention both empty). */
+    ok: boolean;
+}
+export interface HealCheck {
+    id: HealCheckId;
+    title: string;
+    /** Restrict to these platforms; omit to run on all. */
+    platforms?: NodeJS.Platform[];
+    cadence: HealCadence;
+    /** Detect + (repair unless dryRun). Must be headless (no TTY/prompt) and idempotent. */
+    run(ctx: HealCtx): Promise<CheckResult>;
+}
+export interface CheckReport {
+    id: HealCheckId;
+    title: string;
+    result: CheckResult | null;
+    /** Set when the check itself threw (isolated — one check failing never aborts the run). */
+    error?: string;
+}
+export interface SelfHealReport {
+    checks: CheckReport[];
+}
+/** Convenience: an all-clear result. */
+export declare function okResult(): CheckResult;
+/** Build a CheckResult from collected fixes/attention items (ok iff both empty). */
+export declare function resultOf(fixed: string[], needsAttention: string[]): CheckResult;

package/dist/lib/self-heal/types.js

@@ -0,0 +1,21 @@
+// Unified self-heal subsystem — shared shapes.
+//
+// agents-cli had ~37 separate repair routines scattered across the daemon, every
+// CLI startup, and a handful of commands, each hand-rolling detect+fix on its own
+// trigger. This subsystem gives every repairable class of problem ONE shape — a
+// HealCheck — driven by ONE runner, hosted behind TWO front doors (the daemon,
+// on tiered schedules, and `agents doctor`, on demand).
+//
+// A check's `run()` both detects and repairs in a single pass (repair is skipped
+// when `ctx.dryRun`), mirroring the existing resource heal (heal.ts) which computes
+// and applies together. `mode` gates how aggressive a repair may be: 'safe' (the
+// daemon default) fixes only low-risk drift and merely reports risky conditions;
+// 'full' (`agents doctor --fix`) applies everything.
+/** Convenience: an all-clear result. */
+export function okResult() {
+    return { fixed: [], needsAttention: [], ok: true };
+}
+/** Build a CheckResult from collected fixes/attention items (ok iff both empty). */
+export function resultOf(fixed, needsAttention) {
+    return { fixed, needsAttention, ok: fixed.length === 0 && needsAttention.length === 0 };
+}

package/dist/lib/shim-heal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Heal the shim/shadow/PATH conditions silently, then return the notice lines to
+ * print ONCE for whatever is left (a real-binary shadow we won't move; a PATH entry
+ * that was just added / needs a reload), or null when there's nothing new to say.
+ */
+export declare function healShimsInteractive(): Promise<string[] | null>;
+type PathNoticeState = 'ok' | 'added' | 'reload';
+/**
+ * A stable signature of the conditions worth surfacing: the sorted set of
+ * real-binary shadows plus the PATH notice state. Empty string = nothing to say.
+ */
+export declare function computeShimNoticeSignature(input: {
+    shadowNotes: string[];
+    pathState: PathNoticeState;
+}): string;
+/**
+ * Whether to surface the notice for the current condition. Returns false (stay
+ * quiet) when the exact same signature was already surfaced, or when there's
+ * nothing to say. On true it records the signature so the next shell with the same
+ * state is suppressed. An empty signature clears the marker.
+ */
+export declare function shouldSurfaceShimNotice(signature: string): boolean;
+export {};

package/dist/lib/shim-heal.js

@@ -0,0 +1,109 @@
+// Interactive shim-heal for the CLI startup path + the persistent notice-state that
+// replaces the old per-PPID sentinel.
+//
+// The actual repair (regenerating shims, adopting symlink launchers, adding the
+// shims dir to PATH) lives in the unified self-heal registry — this module just
+// drives the shim-relevant checks SILENTLY on a normal `agents` invocation and then
+// decides whether to print a one-time notice about anything left. The old flow
+// re-ran its whole detect-and-nag on every new terminal (its sentinel was keyed to
+// process.ppid); the persistent signature here means an unresolved condition is
+// surfaced once, not on every shell.
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRuntimeStateDir } from './state.js';
+/**
+ * Heal the shim/shadow/PATH conditions silently, then return the notice lines to
+ * print ONCE for whatever is left (a real-binary shadow we won't move; a PATH entry
+ * that was just added / needs a reload), or null when there's nothing new to say.
+ */
+export async function healShimsInteractive() {
+    const { runSelfHeal } = await import('./self-heal/registry.js');
+    const report = await runSelfHeal({ checks: ['shims', 'shadowing', 'path'], mode: 'safe' });
+    const shadowNotes = [];
+    let pathAdded = null;
+    let pathReload = null;
+    for (const c of report.checks) {
+        if (!c.result)
+            continue;
+        if (c.id === 'shadowing')
+            shadowNotes.push(...c.result.needsAttention);
+        if (c.id === 'path') {
+            for (const f of c.result.fixed)
+                pathAdded = f; // "added shims to PATH (~/.zshrc)"
+            for (const a of c.result.needsAttention)
+                pathReload = a; // "...not loaded — open a new terminal"
+        }
+    }
+    const pathState = pathAdded ? 'added' : pathReload ? 'reload' : 'ok';
+    const signature = computeShimNoticeSignature({ shadowNotes, pathState });
+    if (!shouldSurfaceShimNotice(signature))
+        return null;
+    const lines = [];
+    if (pathAdded) {
+        lines.push(pathAdded);
+        lines.push('Open a new terminal (or source your shell rc) to pick it up.');
+    }
+    else if (pathReload) {
+        lines.push(pathReload);
+    }
+    if (shadowNotes.length > 0) {
+        lines.push('These agent commands run a native binary instead of the version-managed shim:');
+        for (const note of shadowNotes)
+            lines.push(`  ${note}`);
+        lines.push("It's a real binary (not a symlink), so agents-cli won't move it — reorder PATH or remove it to hand it over.");
+    }
+    return lines.length > 0 ? lines : null;
+}
+function noticeStatePath() {
+    return path.join(getRuntimeStateDir(), 'shim-notice.json');
+}
+/**
+ * A stable signature of the conditions worth surfacing: the sorted set of
+ * real-binary shadows plus the PATH notice state. Empty string = nothing to say.
+ */
+export function computeShimNoticeSignature(input) {
+    const shadows = [...input.shadowNotes].sort().join(',');
+    const parts = [];
+    if (shadows)
+        parts.push(`shadow:${shadows}`);
+    if (input.pathState !== 'ok')
+        parts.push(`path:${input.pathState}`);
+    return parts.join('|');
+}
+function readLastNoticeSignature() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(noticeStatePath(), 'utf-8'));
+        return typeof parsed.signature === 'string' ? parsed.signature : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLastNoticeSignature(signature) {
+    try {
+        fs.mkdirSync(getRuntimeStateDir(), { recursive: true });
+        fs.writeFileSync(noticeStatePath(), JSON.stringify({ signature }));
+    }
+    catch {
+        /* best-effort: never block a command on the marker */
+    }
+}
+/**
+ * Whether to surface the notice for the current condition. Returns false (stay
+ * quiet) when the exact same signature was already surfaced, or when there's
+ * nothing to say. On true it records the signature so the next shell with the same
+ * state is suppressed. An empty signature clears the marker.
+ */
+export function shouldSurfaceShimNotice(signature) {
+    if (!signature) {
+        try {
+            fs.rmSync(noticeStatePath(), { force: true });
+        }
+        catch { /* best-effort */ }
+        return false;
+    }
+    if (readLastNoticeSignature() === signature)
+        return false;
+    writeLastNoticeSignature(signature);
+    return true;
+}

package/dist/lib/shims.d.ts

@@ -278,6 +278,12 @@ export declare function getConfigSymlinkVersion(agent: AgentId): string | null;
  */
 export declare function onDiskShimFile(cliCommand: string, platform: NodeJS.Platform): string;
 export declare function shimExists(agent: AgentId): boolean;
+/**
+ * True if the on-disk shim's schema version matches `SHIM_SCHEMA_VERSION`.
+ * False means either the shim is missing, is pre-v2 (no marker), or is an
+ * older version that needs regeneration.
+ */
+export declare function isShimCurrent(agent: AgentId): boolean;
 /**
  * Regenerate the shim if it's missing or outdated. Returns a status describing
  * what happened — callers can surface a one-line notice to the user ("Updated

package/dist/lib/shims.js

@@ -1606,7 +1606,7 @@ function readShimSchemaVersion(agent) {
  * False means either the shim is missing, is pre-v2 (no marker), or is an
  * older version that needs regeneration.
  */
-function isShimCurrent(agent) {
+export function isShimCurrent(agent) {
     const version = readShimSchemaVersion(agent);
     return version === SHIM_SCHEMA_VERSION;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.45",
+  "version": "1.20.46",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",