@phnx-labs/agents-cli 1.20.45 → 1.20.47

package/CHANGELOG.md

@@ -2,8 +2,20 @@
 
 ## Unreleased
 
+## 1.20.47
+
+- **Quick-issue bar (`Cmd-Shift-O`): `Cmd-V` now pastes into the note field, and double-clicking a screenshot thumbnail opens it in Preview.** Two fixes from dogfooding the new bar. (1) The panel is a borderless `.accessory` window with **no main menu**, so the standard clipboard key-equivalents (`Cmd-V`/`C`/`X`/`A`) were never dispatched to the field editor — paste silently did nothing. `PromptPanel.performKeyEquivalent` now routes them through the responder chain so the text field handles them. (2) Thumbnails are small, so there was no way to confirm which screenshot you were attaching: **single click still toggles selection, double click opens the full image in the default viewer (Preview)**. The single-click toggle is deferred by the double-click interval so a double-click previews without also flipping the selection, and the bar suppresses its own click-outside dismissal while Preview takes focus (so summoning Preview never closes the bar or drops your typed note; it re-arms when the bar regains focus). Source: `apps/cli/menubar/Sources/MenubarHelper/PromptPanel.swift`.
+- **Fix: the headless file-store fallback no longer silently shadows the OS keyring; NEW `agents secrets import-keyring` migrates stranded secrets into it.** On headless Linux/Windows the encrypted-file store is *sticky* — once any item is on disk, `preflight()` routed **every** op to the file store and never consulted GNOME Keyring / Windows Credential Manager again, so a secret written earlier into the native store (e.g. while a desktop keyring was unlocked) read back **empty** with no hint. This stranded real Linear CLI credentials in a locked keyring while other bundles lived in the file store, silently breaking the SessionStart hook. Two fixes: (1) `get`/`has` now **read through** to the native store on a file-store *miss* (the fast path and the non-fallback keychain-first path are untouched — the file store is still checked first), emitting a one-time stderr notice pointing at `import-keyring`; once a locked/`1312` error is seen the store is marked unreachable so it stops re-probing a known-dead store. (2) NEW **`agents secrets import-keyring`** — the Linux/Windows analogue of the macOS `migrate-acl`/orphan sweep — enumerates `agents-cli` items in the native store and copies them into the encrypted file store (the durable, passwordless headless backend). Dry-run by default; `--commit` writes; existing file-store items are never overwritten; Windows enumeration is floored to the `agents-cli.` namespace since Credential Manager targets have no service scoping. macOS is unaffected (it has no file fallback and keeps `migrate-acl`). Source: `apps/cli/src/lib/secrets/{fallback,linux,windows,index}.ts`, `apps/cli/src/commands/{secrets-import,secrets}.ts`, `apps/cli/docs/secrets.md`.
+- **Launch-health self-heal now covers Windows, and the daemon repairs a gutted install proactively — before your next `agents run`.** #764 gave `agents run` an install/run-time self-heal (probe `<binary> --version`; clean-reinstall in place, else fall back to another installed version that launches), but it **skipped the probe on Windows** — `verifyInstalledBinaryLaunches` returned healthy on `win32` unconditionally, because probing the extensionless `.bin/<cli>` wrapper would ENOENT even on a *healthy* install. So the exact Windows failure the self-heal was built for went unhealed: a vendor auto-update renames the native `claude.exe` to `claude.exe.old.<epochMs>` and never lands the replacement, leaving the shim chain intact but pointing at a missing file, and every launch dies with `'…claude.exe' is not recognized`. The probe now runs on Windows against the **real launch target** — the npm `.cmd` wrapper `agents run` actually execs (`getBinaryPath + '.cmd'`, resolved via `cmd.exe`), which chains to the native `.exe` — so a gutted install trips the existing missing-binary signature (`is not recognized`) and is repaired by the same `ensureAgentRunnable` machinery; a missing `.cmd` (a non-npm/global agent like `droid.exe`) is still treated as healthy so a good install is never destroyed. Separately, the **daemon** now runs a proactive launch-health pass (`healBrokenDefaultLaunches`) ~90s after startup and every ~6h: it probes each agent's default version and, if it won't launch, repairs it in the background — so a gutted install is fixed *before* the next `agents run` hits the ENOENT, not at spawn time (the run-time `ensureAgentRunnable` only fires once a run is already starting). Verified end-to-end on a real Windows host: renaming `claude.exe` to `.old` makes the `.cmd` probe emit `is not recognized`; restoring it returns `2.1.191 (Claude Code)`. Source: `apps/cli/src/lib/versions.ts` (`verifyInstalledBinaryLaunches`, `healBrokenDefaultLaunches`), `apps/cli/src/lib/daemon.ts`.
+
 ## 1.20.45
 
+## 1.20.46
+
+- **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`.

package/dist/commands/secrets-import.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `agents secrets import-keyring` — migrate agents-cli secrets out of the native
+ * credential store (GNOME Keyring / Windows Credential Manager) and into the
+ * encrypted file store.
+ *
+ * Why: on headless Linux/Windows the file store is the durable, passwordless
+ * backend, but secrets written earlier (e.g. while a desktop keyring was
+ * unlocked) can linger in the native store where a headless session can't reach
+ * them. This is the Linux/Windows analogue of the macOS `migrate-acl` /
+ * orphan sweep. Dry-run by default; `--commit` performs the copy.
+ *
+ * Requires the native store to be reachable/unlocked — a locked keyring can't be
+ * read, so unlock it first (or the values are already only in the file store and
+ * there is nothing to do).
+ */
+import type { Command } from 'commander';
+/** Register `agents secrets import-keyring` on the parent secrets Command. */
+export declare function registerSecretsImportKeyringCommand(secrets: Command): void;

package/dist/commands/secrets-import.js

@@ -0,0 +1,74 @@
+/**
+ * `agents secrets import-keyring` — migrate agents-cli secrets out of the native
+ * credential store (GNOME Keyring / Windows Credential Manager) and into the
+ * encrypted file store.
+ *
+ * Why: on headless Linux/Windows the file store is the durable, passwordless
+ * backend, but secrets written earlier (e.g. while a desktop keyring was
+ * unlocked) can linger in the native store where a headless session can't reach
+ * them. This is the Linux/Windows analogue of the macOS `migrate-acl` /
+ * orphan sweep. Dry-run by default; `--commit` performs the copy.
+ *
+ * Requires the native store to be reachable/unlocked — a locked keyring can't be
+ * read, so unlock it first (or the values are already only in the file store and
+ * there is nothing to do).
+ */
+import chalk from 'chalk';
+import { importNativeItems } from '../lib/secrets/index.js';
+/** Register `agents secrets import-keyring` on the parent secrets Command. */
+export function registerSecretsImportKeyringCommand(secrets) {
+    secrets
+        .command('import-keyring')
+        .description('Migrate agents-cli secrets from the OS keyring / Credential Manager into the encrypted file store (headless-safe). Dry-run by default.')
+        .option('--commit', 'Perform the import (default is dry-run reporting only)')
+        .option('--prefix <p>', 'Only import items beginning with PREFIX (default: all agents-cli items)')
+        .action((opts) => {
+        try {
+            if (process.platform === 'darwin') {
+                throw new Error('import-keyring is for the Linux/Windows file-store fallback. On macOS use `agents secrets migrate-acl`.');
+            }
+            const commit = !!opts.commit;
+            const report = importNativeItems(opts.prefix ?? '', commit);
+            if (!report.available) {
+                console.log(chalk.gray('No native credential tooling found (secret-tool / PowerShell) — nothing to import.'));
+                return;
+            }
+            if (report.locked) {
+                console.error(chalk.yellow('The native credential store is locked/unreachable, so its secrets can\'t be read. ' +
+                    'Unlock it and retry (a locked store can\'t be migrated).'));
+                process.exit(1);
+            }
+            if (report.results.length === 0) {
+                console.log(chalk.green('Nothing to import — no native secrets outside the file store.'));
+                return;
+            }
+            const imported = report.results.filter((r) => r.status === 'imported' || r.status === 'would-import');
+            const existing = report.results.filter((r) => r.status === 'exists');
+            const failed = report.results.filter((r) => r.status === 'failed');
+            for (const r of report.results) {
+                if (r.status === 'imported')
+                    console.log(`  ${chalk.green('imported')}  ${r.item}`);
+                else if (r.status === 'would-import')
+                    console.log(`  ${chalk.cyan('would import')}  ${r.item}`);
+                else if (r.status === 'exists')
+                    console.log(`  ${chalk.gray('exists')}    ${r.item} ${chalk.gray('(already in file store)')}`);
+                else
+                    console.log(`  ${chalk.red('failed')}    ${r.item} ${chalk.gray(r.detail ?? '')}`);
+            }
+            console.log();
+            if (!commit) {
+                console.log(chalk.gray(`Dry-run: ${imported.length} would be imported, ${existing.length} already present, ${failed.length} unreadable. Pass --commit to write.`));
+                return;
+            }
+            if (failed.length > 0) {
+                console.error(chalk.yellow(`Imported ${imported.length}; ${existing.length} already present; ${failed.length} failed.`));
+                process.exit(1);
+            }
+            console.log(chalk.green(`Imported ${imported.length} secret(s) into the file store (${existing.length} already present).`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/secrets.js

@@ -25,6 +25,7 @@ import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { registerSecretsSyncCommands } from './secrets-sync.js';
 import { registerSecretsMigrateAclCommand } from './secrets-migrate.js';
+import { registerSecretsImportKeyringCommand } from './secrets-import.js';
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -1817,6 +1818,7 @@ Examples:
     });
     registerSecretsSyncCommands(cmd);
     registerSecretsMigrateAclCommand(cmd);
+    registerSecretsImportKeyringCommand(cmd);
 }
 /** Validate a prompt-policy value, throwing a clear message on a bad one (the
  * caller's try/catch renders it and exits). Accepts the legacy `biometry` /

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;
@@ -451,6 +454,35 @@ export async function runDaemon() {
     };
     const tmuxReconcileInterval = setInterval(() => { void runTmuxReconcile(); }, 5 * 60_000);
     const tmuxReconcileKickoff = setTimeout(() => { void runTmuxReconcile(); }, 20_000);
+    // Launch-health self-heal: probe that each agent's DEFAULT version actually
+    // LAUNCHES (not just that its files exist), and repair a gutted install — the
+    // JS wrapper present but its native binary renamed/missing (a vendor
+    // auto-update that never landed its replacement, or a partially-extracted
+    // tarball) — BEFORE the user's next `agents run` dies with a raw ENOENT. This
+    // is the proactive companion to the run-time heal (ensureAgentRunnable), which
+    // only fires once a run is already starting. Cheap steady-state: one
+    // `--version` probe per default version; a clean reinstall runs only on a real
+    // launch failure. ~every 6h, plus once ~90s after startup (staggered off launch).
+    let checkingLaunchHealth = false;
+    const runLaunchHealthCheck = async () => {
+        if (checkingLaunchHealth)
+            return;
+        checkingLaunchHealth = true;
+        try {
+            const { healBrokenDefaultLaunches } = await import('./versions.js');
+            const repaired = await healBrokenDefaultLaunches((m) => log('INFO', `launch-health: ${m}`));
+            if (repaired.length)
+                log('INFO', `launch-health: repaired ${repaired.join(', ')}`);
+        }
+        catch (err) {
+            log('ERROR', `launch-health check failed: ${err.message}`);
+        }
+        finally {
+            checkingLaunchHealth = false;
+        }
+    };
+    const launchHealthInterval = setInterval(() => { void runLaunchHealthCheck(); }, 6 * 60 * 60_000);
+    const launchHealthKickoff = setTimeout(() => { void runLaunchHealthCheck(); }, 90_000);
     const handleReload = () => {
         log('INFO', 'Reloading jobs (SIGHUP)');
         scheduler.reloadAll();
@@ -472,6 +504,8 @@ export async function runDaemon() {
         clearTimeout(deviceProbeKickoff);
         clearInterval(tmuxReconcileInterval);
         clearTimeout(tmuxReconcileKickoff);
+        clearInterval(launchHealthInterval);
+        clearTimeout(launchHealthKickoff);
         removeDaemonPid();
         process.exit(0);
     };

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

@@ -0,0 +1,48 @@
+/**
+ * Shared helpers for the Linux/Windows encrypted-file fallback.
+ *
+ * When the native credential store (GNOME Keyring / Windows Credential Manager)
+ * is unreachable, both backends route to the AES-256-GCM file store. The routing
+ * is "sticky": once any item is on disk, every op stays on the file store. That
+ * is correct for perf, but on its own it would silently *shadow* secrets that
+ * still live in the native store — reads for them would return empty with no
+ * hint. This module centralizes the two pieces that keep that from being silent:
+ *
+ *   1. `noteNativeShadow()` — a one-time stderr notice, emitted when a read
+ *      falls through to the native store (found something shadowed, or hit a
+ *      locked/unreachable store), pointing at `agents secrets import-keyring`.
+ *   2. The result types for that import command.
+ *
+ * macOS has no file fallback (see ./index.ts) and uses `migrate-acl` /
+ * `migrate-orphans` for its own invisible-item classes, so none of this runs
+ * there.
+ */
+export type NativeImportStatus = 'imported' | 'would-import' | 'exists' | 'failed';
+export interface NativeImportResult {
+    item: string;
+    status: NativeImportStatus;
+    detail?: string;
+}
+/**
+ * Outcome of an `import-keyring` run. `available` is false when no native
+ * tooling exists (no `secret-tool` / no `powershell.exe`); `locked` is true when
+ * the native store exists but is locked/unreachable, so nothing could be read.
+ */
+export interface NativeImportReport {
+    available: boolean;
+    locked: boolean;
+    results: NativeImportResult[];
+}
+/**
+ * Emit a one-time stderr notice that the file fallback is masking the native
+ * credential store. Both backends share the copy so the guidance is identical.
+ *
+ *   'shadowed' — a secret was just read from the native store that isn't in the
+ *                file store. It works, but each read pays a native lookup and it
+ *                won't survive the store locking; suggest migrating it.
+ *   'locked'   — the native store is locked/unreachable, so its secrets can't be
+ *                read in this session at all; the user must unlock, then migrate.
+ */
+export declare function noteNativeShadow(kind: 'shadowed' | 'locked', fileDir: string): void;
+/** Test-only: clear the one-time notice guard between cases. */
+export declare function _resetFallbackNoticeForTest(): void;

package/dist/lib/secrets/fallback.js

@@ -0,0 +1,48 @@
+/**
+ * Shared helpers for the Linux/Windows encrypted-file fallback.
+ *
+ * When the native credential store (GNOME Keyring / Windows Credential Manager)
+ * is unreachable, both backends route to the AES-256-GCM file store. The routing
+ * is "sticky": once any item is on disk, every op stays on the file store. That
+ * is correct for perf, but on its own it would silently *shadow* secrets that
+ * still live in the native store — reads for them would return empty with no
+ * hint. This module centralizes the two pieces that keep that from being silent:
+ *
+ *   1. `noteNativeShadow()` — a one-time stderr notice, emitted when a read
+ *      falls through to the native store (found something shadowed, or hit a
+ *      locked/unreachable store), pointing at `agents secrets import-keyring`.
+ *   2. The result types for that import command.
+ *
+ * macOS has no file fallback (see ./index.ts) and uses `migrate-acl` /
+ * `migrate-orphans` for its own invisible-item classes, so none of this runs
+ * there.
+ */
+let noticeEmitted = false;
+/**
+ * Emit a one-time stderr notice that the file fallback is masking the native
+ * credential store. Both backends share the copy so the guidance is identical.
+ *
+ *   'shadowed' — a secret was just read from the native store that isn't in the
+ *                file store. It works, but each read pays a native lookup and it
+ *                won't survive the store locking; suggest migrating it.
+ *   'locked'   — the native store is locked/unreachable, so its secrets can't be
+ *                read in this session at all; the user must unlock, then migrate.
+ */
+export function noteNativeShadow(kind, fileDir) {
+    if (noticeEmitted)
+        return;
+    noticeEmitted = true;
+    if (kind === 'locked') {
+        process.stderr.write(`[agents] the native credential store is locked/unreachable — secrets stored there are not ` +
+            `readable in this session. Unlock it, then run \`agents secrets import-keyring\` to migrate ` +
+            `them into the encrypted file store at ${fileDir}.\n`);
+    }
+    else {
+        process.stderr.write(`[agents] read a secret from the native credential store that is not in the file store at ` +
+            `${fileDir}. Run \`agents secrets import-keyring\` to migrate it so it stays readable headless.\n`);
+    }
+}
+/** Test-only: clear the one-time notice guard between cases. */
+export function _resetFallbackNoticeForTest() {
+    noticeEmitted = false;
+}

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

@@ -22,6 +22,8 @@
  * through the explicit export/import flow in src/lib/secrets/sync.ts
  * rather than the system's cloud-keychain path.
  */
+import type { NativeImportReport } from './fallback.js';
+export type { NativeImportReport, NativeImportResult, NativeImportStatus } from './fallback.js';
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
 /** A typed reference to a secret, consisting of a provider and a provider-specific value. */
@@ -181,6 +183,15 @@ export declare function parseOrphanMigrationOutput(stdout: string): OrphanMigrat
  * aborted" from "nothing to do" (empty array).
  */
 export declare function migrateOrphanedKeychainItems(prefix: string): OrphanMigrationResult[];
+/**
+ * Import agents-cli secrets from the native store (GNOME Keyring / Windows
+ * Credential Manager) into the encrypted file store — the Linux/Windows
+ * analogue of the macOS orphan/legacy migration, exposed as
+ * `agents secrets import-keyring`. Requires the native store to be
+ * reachable/unlocked; `commit=false` is a dry-run. macOS returns an empty
+ * report (it has no file fallback and uses `migrate-acl` instead).
+ */
+export declare function importNativeItems(prefix: string, commit: boolean): NativeImportReport;
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */

package/dist/lib/secrets/index.js

@@ -26,8 +26,8 @@ import { execFileSync, spawnSync } from 'child_process';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { linuxBackend, usesFileFallback as linuxUsesFileFallback } from './linux.js';
-import { windowsBackend, usesFileFallback as windowsUsesFileFallback } from './windows.js';
+import { linuxBackend, usesFileFallback as linuxUsesFileFallback, importNativeSecretToolItems } from './linux.js';
+import { windowsBackend, usesFileFallback as windowsUsesFileFallback, importNativeCredManItems } from './windows.js';
 import { getKeychainHelperPath } from './install-helper.js';
 const SERVICE_PREFIX = 'agents-cli';
 const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
@@ -518,6 +518,24 @@ export function migrateOrphanedKeychainItems(prefix) {
     }
     return parseOrphanMigrationOutput(result.stdout?.toString() || '');
 }
+/**
+ * Import agents-cli secrets from the native store (GNOME Keyring / Windows
+ * Credential Manager) into the encrypted file store — the Linux/Windows
+ * analogue of the macOS orphan/legacy migration, exposed as
+ * `agents secrets import-keyring`. Requires the native store to be
+ * reachable/unlocked; `commit=false` is a dry-run. macOS returns an empty
+ * report (it has no file fallback and uses `migrate-acl` instead).
+ */
+export function importNativeItems(prefix, commit) {
+    if (backend)
+        return { available: false, locked: false, results: [] };
+    assertSupportedPlatform();
+    if (isLinux())
+        return importNativeSecretToolItems(prefix, commit);
+    if (isWindows())
+        return importNativeCredManItems(prefix, commit);
+    return { available: false, locked: false, results: [] };
+}
 function expandHome(p) {
     if (p.startsWith('~/') || p === '~') {
         return path.join(os.homedir(), p.slice(1));

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

@@ -17,6 +17,7 @@
  *   item    = the secret identifier
  */
 import type { KeychainBackend } from './index.js';
+import { type NativeImportReport } from './fallback.js';
 export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
 /**
  * True when secret operations currently route to the encrypted-file store
@@ -55,6 +56,12 @@ export declare function parseSecretToolItems(output: string, prefix: string): st
  * so we use secret-tool search which outputs in a specific format.
  */
 export declare function listSecretToolItems(prefix: string): string[];
+/**
+ * Copy agents-cli items from the keyring into the file store (the `import-keyring`
+ * backend for Linux). Requires an unlocked keyring; items already in the file
+ * store are left untouched. With `commit=false` it reports what it *would* do.
+ */
+export declare function importNativeSecretToolItems(prefix: string, commit: boolean): NativeImportReport;
 /** KeychainBackend implementation for Linux. Routes through secret-tool
  *  with a transparent encrypted-file fallback when the default Secret
  *  Service collection is locked (or libsecret-tools is not installed but