@phnx-labs/agents-cli 1.20.44 → 1.20.46

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/hosts/dispatch.d.ts

@@ -45,6 +45,35 @@ export interface DispatchOptions {
  * resume wins when — defensively — both are set.
  */
 export declare function buildRunForwardedArgs(opts: DispatchOptions): string[];
+export interface InteractiveDispatchOptions {
+    agent: string;
+    /** Optional prompt — forwarded only when the caller explicitly forced interactive mode. */
+    prompt?: string;
+    mode?: string;
+    model?: string;
+    remoteCwd?: string;
+    sessionId?: string;
+    name?: string;
+    resume?: string;
+    passthroughArgs?: string[];
+    raw?: boolean;
+    /** Forward `--interactive` to the remote so a prompt-bearing run still starts the TUI. */
+    forceInteractive?: boolean;
+}
+/**
+ * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The
+ * remote agent sees a TTY, so we omit `--quiet`; the remote CLI will launch its
+ * normal interactive TUI / tmux wrapper. A prompt is only included when the
+ * caller explicitly forced interactive mode (otherwise the remote CLI would
+ * infer headless from the prompt).
+ */
+export declare function buildInteractiveRunForwardedArgs(opts: InteractiveDispatchOptions): string[];
+/**
+ * Run an agent interactively on a host, forwarding the local TTY over SSH.
+ * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
+ * tmux wrapping; the local machine is just the transport.
+ */
+export declare function runInteractiveOnHost(host: Host, opts: InteractiveDispatchOptions): Promise<number>;
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export declare function dispatchToHost(host: Host, opts: DispatchOptions): Promise<DispatchResult>;
 export interface CommandDispatchOptions {

package/dist/lib/hosts/dispatch.js

@@ -9,7 +9,7 @@
  * same core so a remote team supervisor keeps running after you disconnect.
  */
 import { randomUUID } from 'crypto';
-import { sshExec, shellQuote } from '../ssh-exec.js';
+import { sshExec, sshStream, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 import { ensureHostReady } from './ready.js';
 import { remoteShellFor } from './remote-cmd.js';
@@ -105,6 +105,51 @@ export function buildRunForwardedArgs(opts) {
         args.push('--session-id', opts.sessionId);
     return args;
 }
+/**
+ * Build the remote `agents run …` argv for an INTERACTIVE host dispatch. The
+ * remote agent sees a TTY, so we omit `--quiet`; the remote CLI will launch its
+ * normal interactive TUI / tmux wrapper. A prompt is only included when the
+ * caller explicitly forced interactive mode (otherwise the remote CLI would
+ * infer headless from the prompt).
+ */
+export function buildInteractiveRunForwardedArgs(opts) {
+    const args = ['run', opts.agent];
+    if (opts.prompt && opts.forceInteractive)
+        args.push(opts.prompt);
+    if (opts.forceInteractive)
+        args.push('--interactive');
+    if (opts.mode)
+        args.push('--mode', opts.mode);
+    if (opts.model)
+        args.push('--model', opts.model);
+    if (opts.name)
+        args.push('--name', opts.name);
+    if (opts.resume)
+        args.push('--resume', opts.resume);
+    else if (opts.sessionId)
+        args.push('--session-id', opts.sessionId);
+    if (opts.raw)
+        args.push('--raw');
+    if (opts.passthroughArgs && opts.passthroughArgs.length > 0) {
+        args.push('--', ...opts.passthroughArgs);
+    }
+    return args;
+}
+/**
+ * Run an agent interactively on a host, forwarding the local TTY over SSH.
+ * Returns the SSH exit code. The remote `agents` CLI is responsible for its own
+ * tmux wrapping; the local machine is just the transport.
+ */
+export async function runInteractiveOnHost(host, opts) {
+    const target = sshTargetFor(host);
+    const { warnings } = ensureHostReady(host, { agent: opts.agent });
+    for (const w of warnings)
+        process.stderr.write(`[hosts] warning: ${w}\n`);
+    const invocation = ['agents', ...buildInteractiveRunForwardedArgs(opts)].map(shellQuote).join(' ');
+    const cwd = opts.remoteCwd ? `cd ${shellQuote(opts.remoteCwd)} && ` : '';
+    const remoteCmd = `${cwd}${invocation}`;
+    return sshStream(target, remoteCmd, { tty: process.stdin.isTTY, multiplex: true });
+}
 /** Dispatch an `agents run <agent> "<prompt>"` onto a host (the `run --host` path). */
 export async function dispatchToHost(host, opts) {
     const target = sshTargetFor(host);

package/dist/lib/hosts/remote-cmd.d.ts

@@ -101,3 +101,20 @@ export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
  * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
  */
 export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): string;
+/**
+ * Build the `ssh <target> <cmd>` string for `agents secrets import` on a Windows
+ * remote where the `.env` is piped over ssh stdin.
+ *
+ * We can't just run `agents secrets import <bundle> --from -`: the npm
+ * `agents.ps1` shim does NOT forward the ssh-piped stdin down to the underlying
+ * node process, so a raw fd-0 read (`--from -`) hangs forever (observed: the
+ * push to a Windows host times out). PowerShell ITSELF can read the pipe, so we
+ * read stdin into a temp file in PowerShell, import `--from <file>` (a plain
+ * file read, which the shim handles fine), and delete the temp file afterwards
+ * — success or failure. Backend defaults to the platform native store
+ * (Credential Manager, or the headless file store when there's no logon
+ * session), matching a local `agents secrets import`.
+ */
+export declare function buildWindowsStdinImportCommand(bundle: string, opts?: {
+    force?: boolean;
+}): string;

package/dist/lib/hosts/remote-cmd.js

@@ -130,3 +130,30 @@ export function windowsAgentsScript(cmd) {
 export function buildWindowsAgentsCommand(cmd) {
     return `powershell -NoProfile -EncodedCommand ${encodePowershell(windowsAgentsScript(cmd))}`;
 }
+/**
+ * Build the `ssh <target> <cmd>` string for `agents secrets import` on a Windows
+ * remote where the `.env` is piped over ssh stdin.
+ *
+ * We can't just run `agents secrets import <bundle> --from -`: the npm
+ * `agents.ps1` shim does NOT forward the ssh-piped stdin down to the underlying
+ * node process, so a raw fd-0 read (`--from -`) hangs forever (observed: the
+ * push to a Windows host times out). PowerShell ITSELF can read the pipe, so we
+ * read stdin into a temp file in PowerShell, import `--from <file>` (a plain
+ * file read, which the shim handles fine), and delete the temp file afterwards
+ * — success or failure. Backend defaults to the platform native store
+ * (Credential Manager, or the headless file store when there's no logon
+ * session), matching a local `agents secrets import`.
+ */
+export function buildWindowsStdinImportCommand(bundle, opts = {}) {
+    const force = opts.force ? ' --force' : '';
+    const script = [
+        '$in = [Console]::In.ReadToEnd()',
+        '$tmp = [System.IO.Path]::GetTempFileName()',
+        '[System.IO.File]::WriteAllText($tmp, $in)',
+        `try { & agents secrets import ${powershellQuote(bundle)} --from $tmp${force}; $code = $LASTEXITCODE } ` +
+            `finally { Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue }`,
+        'if ($null -eq $code) { $code = 1 }',
+        'exit $code',
+    ].join('; ');
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(script)}`;
+}

package/dist/lib/hosts/session-index.d.ts

@@ -32,3 +32,18 @@ export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext)
  * break the dispatch itself, which has already been launched on the host.
  */
 export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;
+export interface InteractiveHostSessionContext {
+    cwd: string;
+    host: string;
+    agent: string;
+    sessionId: string;
+    name?: string;
+    createdAt?: string;
+}
+/**
+ * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
+ * local session index. Unlike detached host runs, there is no remote log/exit
+ * file and no HostTask; we only need the session id so `agents sessions` can
+ * surface and resume it by id.
+ */
+export declare function registerInteractiveHostSession(ctx: InteractiveHostSessionContext): void;

package/dist/lib/hosts/session-index.js

@@ -35,8 +35,10 @@ export function hostSessionMeta(task, ctx) {
         // stale-filter treats as "always live" (see module doc).
         filePath: '',
         topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
-        label: `[host/${task.host}]`,
-        name: task.name,
+        // The run's `--name` seeds the label (resolves `agents sessions <name>` and
+        // `agents hosts logs <name>`); an unnamed host run falls back to the
+        // `[host/<name>]` indicator, mirroring the cloud path's `[cloud/<status>]`.
+        label: task.name || `[host/${task.host}]`,
     };
 }
 /**
@@ -55,3 +57,27 @@ export function registerHostSession(task, ctx) {
         /* index write is best-effort; the run is already live on the host */
     }
 }
+/**
+ * Register an interactive host run (no prompt, TTY forwarded over SSH) in the
+ * local session index. Unlike detached host runs, there is no remote log/exit
+ * file and no HostTask; we only need the session id so `agents sessions` can
+ * surface and resume it by id.
+ */
+export function registerInteractiveHostSession(ctx) {
+    if (!SESSION_AGENTS.includes(ctx.agent))
+        return;
+    try {
+        upsertSession({
+            id: ctx.sessionId,
+            shortId: ctx.sessionId.slice(0, 8),
+            agent: ctx.agent,
+            timestamp: ctx.createdAt ?? new Date().toISOString(),
+            cwd: ctx.cwd,
+            filePath: '',
+            label: ctx.name || `[host/${ctx.host}]`,
+        }, '');
+    }
+    catch {
+        /* index write is best-effort; the run is already live on the host */
+    }
+}

package/dist/lib/rotate.d.ts

@@ -56,6 +56,39 @@ export declare function getProjectRunStrategy(agent: AgentId, startPath: string)
 export declare function getConfiguredRunStrategy(agent: AgentId, startPath?: string): RunStrategy;
 /** Persist the global run strategy used by bare `agents run <agent>`. */
 export declare function setGlobalRunStrategy(agent: AgentId, strategy: RunStrategy): void;
+/**
+ * Whether a specific account can serve a run right now, and — when it can't —
+ * why. `signed_out` covers no-email / invalid-auth; `rate_limited` and
+ * `out_of_credits` name the throttle. Used to pre-warn on a version-pinned
+ * teammate whose account rotation won't route around (a pin IS the target).
+ */
+export type AccountReadiness = {
+    ready: true;
+} | {
+    ready: false;
+    reason: 'rate_limited' | 'out_of_credits' | 'signed_out';
+    email: string | null;
+};
+/**
+ * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
+ * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * disagree with what rotation would actually do. The `reason` combines the two
+ * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
+ * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
+ * snapshot never carries). When a live snapshot exists it wins over the cached
+ * status — matching the gate — so a stale `out_of_credits` cache is not
+ * reported while the account is actually serving requests.
+ */
+export declare function readinessFromCandidate(candidate: RotateCandidate): AccountReadiness;
+/**
+ * Readiness for a specific installed (agent, version). Returns `{ ready: true }`
+ * when the version isn't among the collected candidates — absence is the
+ * caller's `isVersionInstalled` concern, not ours; don't cry wolf. Only
+ * meaningful for a version-pinned target: a bare target rotates to a healthy
+ * account on its own, and a profile injects its own auth (a different account
+ * than the version home carries), so neither is checkable here.
+ */
+export declare function checkRunAccountReadiness(agent: AgentId, version: string): Promise<AccountReadiness>;
 /**
  * Pick a healthy candidate using weighted random by remaining capacity.
  *

package/dist/lib/rotate.js

@@ -92,6 +92,43 @@ function hasUsageAvailable(candidate) {
     }
     return true;
 }
+/**
+ * Pure decision reusing the router's own eligibility gate (`hasUsageAvailable`
+ * + email/auth, i.e. `isRotationEligible`), so a pre-flight warning can NEVER
+ * disagree with what rotation would actually do. The `reason` combines the two
+ * signals `hasUsageAvailable` reads: the live snapshot (session-inclusive
+ * rate-limit) and the coarse cached `usageStatus` (out-of-credits, which a
+ * snapshot never carries). When a live snapshot exists it wins over the cached
+ * status — matching the gate — so a stale `out_of_credits` cache is not
+ * reported while the account is actually serving requests.
+ */
+export function readinessFromCandidate(candidate) {
+    if (!candidate.email || !candidate.authValid) {
+        return { ready: false, reason: 'signed_out', email: candidate.email };
+    }
+    if (hasUsageAvailable(candidate)) {
+        return { ready: true };
+    }
+    const snap = candidate.usageSnapshot;
+    const snapRateLimited = !!snap && snap.windows.length > 0 && deriveUsageStatusFromSnapshot(snap) === 'rate_limited';
+    const reason = !snapRateLimited && candidate.usageStatus === 'out_of_credits' ? 'out_of_credits' : 'rate_limited';
+    return { ready: false, reason, email: candidate.email };
+}
+/**
+ * Readiness for a specific installed (agent, version). Returns `{ ready: true }`
+ * when the version isn't among the collected candidates — absence is the
+ * caller's `isVersionInstalled` concern, not ours; don't cry wolf. Only
+ * meaningful for a version-pinned target: a bare target rotates to a healthy
+ * account on its own, and a profile injects its own auth (a different account
+ * than the version home carries), so neither is checkable here.
+ */
+export async function checkRunAccountReadiness(agent, version) {
+    const candidates = await collectRunCandidates(agent);
+    const candidate = candidates.find((c) => c.version === version);
+    if (!candidate)
+        return { ready: true };
+    return readinessFromCandidate(candidate);
+}
 function getRoutingUsedPercent(snapshot) {
     if (!snapshot || snapshot.windows.length === 0)
         return null;

package/dist/lib/secrets/remote.d.ts

@@ -51,6 +51,20 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
     tty?: boolean;
     input?: string;
 }): SshExecResult;
+/**
+ * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
+ * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
+ *
+ * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
+ * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
+ * appear (the macOS file-store guard then hard-errors "needs
+ * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
+ * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
+ * the keystrokes. This is the transport for `unlock --host`: you type the remote
+ * bundle's passphrase at your own terminal. Output is NOT captured (it streams
+ * to the terminal); only the exit code is returned.
+ */
+export declare function remoteSecretsStream(target: string, args: string[]): number;
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over

package/dist/lib/secrets/remote.js

@@ -15,7 +15,7 @@
  * file-backend passphrase travels over ssh stdin (first line) so it never lands
  * in argv / `ps` / remote shell history. Nothing is persisted locally.
  */
-import { sshExec, assertValidSshTarget } from '../ssh-exec.js';
+import { sshExec, sshStream, assertValidSshTarget } from '../ssh-exec.js';
 import { resolveHost } from '../hosts/registry.js';
 import { emit } from '../events.js';
 import { sshTargetFor } from '../hosts/types.js';
@@ -93,6 +93,23 @@ export function remoteSecretsRaw(target, args, opts = {}) {
         extraSshArgs: opts.tty ? ['-tt'] : undefined,
     });
 }
+/**
+ * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
+ * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
+ *
+ * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
+ * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
+ * appear (the macOS file-store guard then hard-errors "needs
+ * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
+ * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
+ * the keystrokes. This is the transport for `unlock --host`: you type the remote
+ * bundle's passphrase at your own terminal. Output is NOT captured (it streams
+ * to the terminal); only the exit code is returned.
+ */
+export function remoteSecretsStream(target, args) {
+    const remoteCmd = buildRemoteAgentsInvocation(['secrets', ...args], undefined, osForTarget(target));
+    return sshStream(target, remoteCmd, { tty: true });
+}
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over

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;