@phnx-labs/agents-cli 1.20.46 → 1.20.47

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## 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`.
@@ -9,6 +17,7 @@
 - **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/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/lib/daemon.js

@@ -454,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();
@@ -475,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

package/dist/lib/secrets/linux.js

@@ -19,6 +19,7 @@
 import { spawnSync } from 'child_process';
 import * as os from 'os';
 import { fileStore, fileDir, fileStoreHasItems, machinePassphraseExists, _resetFileStoreForTest, } from './filestore.js';
+import { noteNativeShadow, _resetFallbackNoticeForTest, } from './fallback.js';
 // Re-exported so existing importers (and tests) can keep reaching these via
 // './linux.js'. The implementations live in ./filestore.ts.
 export { encryptForFallback, decryptForFallback, fileBackend, } from './filestore.js';
@@ -35,13 +36,16 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
+// Set once the keyring is observed locked/unreachable in this process, so the
+// read-through in get/has stops re-probing it (and stops re-emitting notices).
+let nativeUnreachable = false;
 function activateFileFallback() {
     if (useFileFallback)
         return;
     useFileFallback = true;
     if (!warnedFallback) {
         warnedFallback = true;
-        process.stderr.write(`[agents] secret-service collection locked, using file-based store at ${fileDir()}\n`);
+        process.stderr.write(`[agents] using the encrypted file store at ${fileDir()}\n`);
     }
 }
 function isLockedCollectionError(stderr) {
@@ -111,8 +115,21 @@ export function usesFileFallback() {
 /** secret-tool lookup attributes:
  *   service=agents-cli account=<user> item=<itemName> */
 export function hasSecretToolToken(item) {
-    if (preflight() === 'file')
-        return fileStore.has(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return true;
+        // The file store is primary under the fallback, but an item can still live
+        // only in an (unlocked) keyring that predates it — read through so it isn't
+        // silently shadowed.
+        const probe = readNativeItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return true;
+        }
+        if (probe.locked)
+            noteNativeShadow('locked', fileDir());
+        return false;
+    }
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -125,14 +142,25 @@ export function hasSecretToolToken(item) {
     }
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.has(item);
     }
     return false;
 }
 export function getSecretToolToken(item) {
-    if (preflight() === 'file')
-        return fileStore.get(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return fileStore.get(item);
+        const probe = readNativeItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return probe.value;
+        }
+        if (probe.locked)
+            noteNativeShadow('locked', fileDir());
+        throw new Error(`Secret '${item}' not found in the file store or keyring.`);
+    }
     const user = os.userInfo().username;
     const result = spawnSync('secret-tool', [
         'lookup',
@@ -148,6 +176,7 @@ export function getSecretToolToken(item) {
     }
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.get(item);
     }
@@ -171,6 +200,7 @@ export function setSecretToolToken(item, value) {
         return;
     const stderr = result.stderr?.toString().trim() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         fileStore.set(item, value);
         return;
@@ -193,6 +223,7 @@ export function deleteSecretToolToken(item) {
         return true;
     const stderr = result.stderr?.toString() ?? '';
     if (isLockedCollectionError(stderr)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.delete(item);
     }
@@ -252,6 +283,81 @@ export function listSecretToolItems(prefix) {
     const output = `${result.stdout?.toString() || ''}\n${result.stderr?.toString() || ''}`;
     return parseSecretToolItems(output, prefix);
 }
+// ---------- native-direct helpers (bypass preflight routing) ----------
+//
+// These always talk to secret-tool regardless of whether the process has fallen
+// back to the file store. They power (a) the read-through that keeps the file
+// store from silently shadowing keyring items, and (b) `import-keyring`.
+/**
+ * Read one item straight from the keyring. Returns `{value}` on a hit,
+ * `{locked:true}` when the collection is locked/unreachable, and `{}` on a plain
+ * miss. Never throws and never emits — the caller decides whether to notice.
+ */
+function readNativeItemRaw(item) {
+    if (nativeUnreachable)
+        return { locked: true };
+    if (!secretToolAvailable())
+        return {};
+    const user = os.userInfo().username;
+    const r = spawnSync('secret-tool', [
+        'lookup', 'service', SERVICE, 'account', user, 'item', item,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status === 0) {
+        const v = r.stdout?.toString().trim();
+        return v && v.length ? { value: v } : {};
+    }
+    if (isLockedCollectionError(r.stderr?.toString() ?? '')) {
+        nativeUnreachable = true;
+        return { locked: true };
+    }
+    return {};
+}
+/**
+ * Enumerate agents-cli items in the keyring whose name starts with `prefix`.
+ * `available` is false when secret-tool isn't installed; `locked` is true when
+ * the collection is locked.
+ */
+function listNativeItemsRaw(prefix) {
+    if (!secretToolAvailable())
+        return { items: [], locked: false, available: false };
+    const r = spawnSync('secret-tool', [
+        'search', '--all', 'service', SERVICE,
+    ], { stdio: ['ignore', 'pipe', 'pipe'] });
+    if (r.status !== 0) {
+        const locked = isLockedCollectionError(r.stderr?.toString() ?? '');
+        if (locked)
+            nativeUnreachable = true;
+        return { items: [], locked, available: true };
+    }
+    const output = `${r.stdout?.toString() || ''}\n${r.stderr?.toString() || ''}`;
+    return { items: parseSecretToolItems(output, prefix), locked: false, available: true };
+}
+/**
+ * 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 function importNativeSecretToolItems(prefix, commit) {
+    const { items, locked, available } = listNativeItemsRaw(prefix);
+    if (!available || locked)
+        return { available, locked, results: [] };
+    const results = [];
+    for (const item of items) {
+        if (fileStore.has(item)) {
+            results.push({ item, status: 'exists' });
+            continue;
+        }
+        const probe = readNativeItemRaw(item);
+        if (probe.value === undefined) {
+            results.push({ item, status: 'failed', detail: probe.locked ? 'keyring locked' : 'unreadable' });
+            continue;
+        }
+        if (commit)
+            fileStore.set(item, probe.value);
+        results.push({ item, status: commit ? 'imported' : 'would-import' });
+    }
+    return { available, locked, results };
+}
 /** 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
@@ -280,6 +386,8 @@ export function _resetForTest(opts = {}) {
     _resetFileStoreForTest({ fileDir: opts.fileDir ?? null, passphrase: opts.passphrase ?? null });
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
+    nativeUnreachable = false;
     checkedAvailability = false;
     isAvailable = false;
+    _resetFallbackNoticeForTest();
 }

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

@@ -27,6 +27,7 @@
  * names directly.
  */
 import type { KeychainBackend } from './index.js';
+import { type NativeImportReport } from './fallback.js';
 export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
 /**
  * CRED_MAX_CREDENTIAL_BLOB_SIZE — Credential Manager rejects a generic
@@ -53,6 +54,12 @@ export declare function listCredManItems(prefix: string): string[];
  * parseSecretToolItems (linux.ts). Exported for tests.
  */
 export declare function parseWindowsCredList(output: string, prefix: string): string[];
+/**
+ * Copy agents-cli credentials from Credential Manager into the file store (the
+ * `import-keyring` backend for Windows). Requires a reachable store; items
+ * already in the file store are left untouched.
+ */
+export declare function importNativeCredManItems(prefix: string, commit: boolean): NativeImportReport;
 /**
  * KeychainBackend implementation for Windows. Routes through Windows Credential
  * Manager (via PowerShell P/Invoke) with a transparent encrypted-file fallback

package/dist/lib/secrets/windows.js

@@ -29,6 +29,7 @@
 import { spawnSync } from 'child_process';
 import { encodePwshBase64 } from '../pwsh.js';
 import { fileStore, fileDir, fileStoreHasItems, machinePassphraseExists, _resetFileStoreForTest, } from './filestore.js';
+import { noteNativeShadow, _resetFallbackNoticeForTest, } from './fallback.js';
 // Re-exported so importers (and tests) can keep reaching these via './windows.js'.
 export { encryptForFallback, decryptForFallback, fileBackend, } from './filestore.js';
 const POWERSHELL = 'powershell.exe';
@@ -250,13 +251,16 @@ let isAvailable = false;
 // ---------- file fallback state ----------
 let useFileFallback = false;
 let warnedFallback = false;
+// Set once Credential Manager is observed unreachable in this process, so the
+// read-through in get/has stops re-probing it (and re-emitting notices).
+let nativeUnreachable = false;
 function activateFileFallback() {
     if (useFileFallback)
         return;
     useFileFallback = true;
     if (!warnedFallback) {
         warnedFallback = true;
-        process.stderr.write(`[agents] Windows Credential Manager unavailable, using file-based store at ${fileDir()}\n`);
+        process.stderr.write(`[agents] using the encrypted file store at ${fileDir()}\n`);
     }
 }
 /**
@@ -316,22 +320,45 @@ export function usesFileFallback() {
 }
 // ---------- Credential Manager ops with fallback ----------
 export function hasCredManToken(item) {
-    if (preflight() === 'file')
-        return fileStore.has(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return true;
+        // Read through to Credential Manager so an item that predates the fallback
+        // isn't silently shadowed by the file store.
+        const probe = readNativeCredItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return true;
+        }
+        if (probe.unavailable)
+            noteNativeShadow('locked', fileDir());
+        return false;
+    }
     const r = runCred('has', { target: item });
     if (r.status === 0)
         return true;
     if (r.status === 3)
         return false;
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.has(item);
     }
     return false;
 }
 export function getCredManToken(item) {
-    if (preflight() === 'file')
-        return fileStore.get(item);
+    if (preflight() === 'file') {
+        if (fileStore.has(item))
+            return fileStore.get(item);
+        const probe = readNativeCredItemRaw(item);
+        if (probe.value !== undefined) {
+            noteNativeShadow('shadowed', fileDir());
+            return probe.value;
+        }
+        if (probe.unavailable)
+            noteNativeShadow('locked', fileDir());
+        throw new Error(`Secret '${item}' not found in the file store or Credential Manager.`);
+    }
     const r = runCred('get', { target: item });
     if (r.status === 0) {
         // stdout is base64 of the raw UTF-8 blob (dodges PowerShell encoding corruption).
@@ -340,6 +367,7 @@ export function getCredManToken(item) {
     if (r.status === 3)
         throw new Error(`Secret '${item}' not found in Credential Manager.`);
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.get(item);
     }
@@ -362,6 +390,7 @@ export function setCredManToken(item, value) {
     if (r.status === 0)
         return;
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         fileStore.set(item, value);
         return;
@@ -377,6 +406,7 @@ export function deleteCredManToken(item) {
     if (r.status === 3)
         return false;
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.delete(item);
     }
@@ -389,6 +419,7 @@ export function listCredManItems(prefix) {
     if (r.status === 0)
         return parseWindowsCredList(r.stdout, prefix);
     if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
         activateFileFallback();
         return fileStore.list(prefix);
     }
@@ -407,6 +438,78 @@ export function parseWindowsCredList(output, prefix) {
         .filter((s) => s.startsWith(prefix));
     return [...new Set(items)]; // dedupe
 }
+// ---------- native-direct helpers (bypass preflight routing) ----------
+//
+// Always talk to Credential Manager regardless of the file fallback. They power
+// (a) the read-through that keeps the file store from shadowing credman items,
+// and (b) `import-keyring`.
+/**
+ * Read one item straight from Credential Manager. `{value}` on hit,
+ * `{unavailable:true}` when the store is unreachable, `{}` on a plain miss.
+ * Never throws, never emits.
+ */
+function readNativeCredItemRaw(item) {
+    if (nativeUnreachable)
+        return { unavailable: true };
+    if (!powershellAvailable())
+        return {};
+    const r = runCred('get', { target: item });
+    if (r.status === 0)
+        return { value: Buffer.from(r.stdout.trim(), 'base64').toString('utf8') };
+    if (r.status === 3)
+        return {};
+    if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
+        return { unavailable: true };
+    }
+    return {};
+}
+/**
+ * Enumerate agents-cli credentials under `prefix`. Windows credentials have no
+ * service scoping — the target IS the identifier — so we NEVER enumerate with an
+ * empty filter (that returns unrelated machine credentials). The filter is
+ * floored to the `agents-cli.` namespace; bare items (unprefixed targets) are
+ * therefore out of scope for auto-discovery on Windows.
+ */
+function listNativeCredItemsRaw(prefix) {
+    if (!powershellAvailable())
+        return { items: [], locked: false, available: false };
+    const floor = prefix && prefix.startsWith('agents-cli.') ? prefix : 'agents-cli.';
+    const r = runCred('list', { prefix: floor });
+    if (r.status === 0)
+        return { items: parseWindowsCredList(r.stdout, floor), locked: false, available: true };
+    if (isCredManUnavailableError(r)) {
+        nativeUnreachable = true;
+        return { items: [], locked: true, available: true };
+    }
+    return { items: [], locked: false, available: true };
+}
+/**
+ * Copy agents-cli credentials from Credential Manager into the file store (the
+ * `import-keyring` backend for Windows). Requires a reachable store; items
+ * already in the file store are left untouched.
+ */
+export function importNativeCredManItems(prefix, commit) {
+    const { items, locked, available } = listNativeCredItemsRaw(prefix);
+    if (!available || locked)
+        return { available, locked, results: [] };
+    const results = [];
+    for (const item of items) {
+        if (fileStore.has(item)) {
+            results.push({ item, status: 'exists' });
+            continue;
+        }
+        const probe = readNativeCredItemRaw(item);
+        if (probe.value === undefined) {
+            results.push({ item, status: 'failed', detail: probe.unavailable ? 'credential manager unavailable' : 'unreadable' });
+            continue;
+        }
+        if (commit)
+            fileStore.set(item, probe.value);
+        results.push({ item, status: commit ? 'imported' : 'would-import' });
+    }
+    return { available, locked, results };
+}
 /**
  * KeychainBackend implementation for Windows. Routes through Windows Credential
  * Manager (via PowerShell P/Invoke) with a transparent encrypted-file fallback
@@ -440,6 +543,8 @@ export function _resetForTest(opts = {}) {
     _resetFileStoreForTest({ fileDir: opts.fileDir ?? null, passphrase: opts.passphrase ?? null });
     useFileFallback = opts.forceFileFallback ?? false;
     warnedFallback = false;
+    nativeUnreachable = false;
+    _resetFallbackNoticeForTest();
     if (opts.forceAvailable === undefined || opts.forceAvailable === null) {
         checkedAvailability = false;
         isAvailable = false;

package/dist/lib/session/discover.js

@@ -2456,6 +2456,8 @@ export function readKimiMeta(filePath) {
             project = parts.slice(0, -1).join('/');
         }
     }
+    // Parse wire.jsonl to extract message count and token usage
+    const { messageCount, tokenCount } = parseKimiWireMetrics(sessionDir);
     const meta = {
         id: sessionId,
         shortId,
@@ -2464,9 +2466,48 @@ export function readKimiMeta(filePath) {
         project,
         filePath,
         topic,
+        messageCount,
+        tokenCount: tokenCount > 0 ? tokenCount : undefined,
     };
     return { meta, content: lastPrompt || '' };
 }
+/** Parse Kimi's wire.jsonl to extract message count and token usage.
+ * TODO: optimize to stream (like scanClaudeSession) to avoid loading large files into memory.
+ * For now, synchronous readFileSync matches the pattern of reading state.json and is acceptable
+ * since session dirs are usually fresh in FS cache during incremental scans. */
+function parseKimiWireMetrics(sessionDir) {
+    const wirePath = path.join(sessionDir, 'agents', 'main', 'wire.jsonl');
+    let messageCount = 0;
+    let tokenCount = 0;
+    if (!fs.existsSync(wirePath)) {
+        return { messageCount: 0, tokenCount: 0 };
+    }
+    try {
+        const lines = fs.readFileSync(wirePath, 'utf-8').split('\n');
+        for (const line of lines) {
+            if (!line.trim())
+                continue;
+            try {
+                const event = JSON.parse(line);
+                if (event.type === 'context.append_message') {
+                    messageCount++;
+                }
+                else if (event.type === 'usage.record' && event.usage) {
+                    // Kimi usage structure: inputOther + output + inputCacheRead + inputCacheCreation
+                    const u = event.usage;
+                    tokenCount += (u.inputOther || 0) + (u.output || 0) + (u.inputCacheRead || 0) + (u.inputCacheCreation || 0);
+                }
+            }
+            catch {
+                // Malformed line, skip
+            }
+        }
+    }
+    catch {
+        // If wire.jsonl can't be read, return 0s (graceful degradation)
+    }
+    return { messageCount, tokenCount };
+}
 /** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export function parseTimeFilter(input) {
     const relativeMatch = input.match(/^(\d+)([mhdw])$/i);

package/dist/lib/versions.d.ts

@@ -320,6 +320,21 @@ export declare function isMissingBinarySignature(output: string): boolean;
  * missing-binary signature (see isMissingBinarySignature) fails the check; a
  * plain nonzero exit or a timeout is treated as healthy so we never false-fail.
  */
+/**
+ * Compose the spawn spec for a `<binary> --version` launch probe. On Windows the
+ * `.cmd` wrapper runs through cmd.exe, so the path is fully quoted into ONE
+ * command line and the args array is emptied (composeWin32CommandLine) — the
+ * DEP0190-safe pattern the real launch uses. Critically this keeps a spaced
+ * Windows profile path (`C:\Users\John Doe\…\claude.cmd`) intact; passing the raw
+ * path to a shell would split it at the space and false-fail a HEALTHY install.
+ * On POSIX no shell is involved and the binary is exec'd directly. Pure/exported
+ * so the quoting is unit-testable without spawning.
+ */
+export declare function probeSpawnSpec(binary: string, isWin: boolean): {
+    command: string;
+    args: string[];
+    shell: boolean;
+};
 export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: string): Promise<{
     ok: boolean;
     detail?: string;
@@ -344,6 +359,7 @@ export declare function verifyInstalledBinaryLaunches(agent: AgentId, version: s
  * droid) have no such tarball and are returned unchanged.
  */
 export declare function ensureAgentRunnable(agent: AgentId, version: string, log?: (message: string) => void): Promise<string | null>;
+export declare function healBrokenDefaultLaunches(log?: (m: string) => void): Promise<string[]>;
 /** Outcome of syncing resources to a version home, keyed by resource type. */
 export interface SyncResult {
     commands: boolean;

package/dist/lib/versions.js

@@ -33,7 +33,7 @@ import { discoverPermissionGroups, getActivePermissionPresetName, readPermission
 import { parseMcpServerConfig } from './mcp.js';
 import { createVersionedAlias, removeVersionedAlias, getConfigSymlinkVersion, ensureClaudeInsideSymlink } from './shims.js';
 import { importInstallScriptBinary } from './import.js';
-import { IS_WINDOWS } from './platform/index.js';
+import { IS_WINDOWS, composeWin32CommandLine } from './platform/index.js';
 import { pruneVersionHomeHookEntriesFromSettings } from './hooks.js';
 import { supports, explainSkip } from './capabilities.js';
 import { discoverPlugins } from './plugins.js';
@@ -1621,22 +1621,48 @@ export function isMissingBinarySignature(output) {
  * missing-binary signature (see isMissingBinarySignature) fails the check; a
  * plain nonzero exit or a timeout is treated as healthy so we never false-fail.
  */
+/**
+ * Compose the spawn spec for a `<binary> --version` launch probe. On Windows the
+ * `.cmd` wrapper runs through cmd.exe, so the path is fully quoted into ONE
+ * command line and the args array is emptied (composeWin32CommandLine) — the
+ * DEP0190-safe pattern the real launch uses. Critically this keeps a spaced
+ * Windows profile path (`C:\Users\John Doe\…\claude.cmd`) intact; passing the raw
+ * path to a shell would split it at the space and false-fail a HEALTHY install.
+ * On POSIX no shell is involved and the binary is exec'd directly. Pure/exported
+ * so the quoting is unit-testable without spawning.
+ */
+export function probeSpawnSpec(binary, isWin) {
+    if (isWin)
+        return { command: composeWin32CommandLine(binary, ['--version']), args: [], shell: true };
+    return { command: binary, args: ['--version'], shell: false };
+}
 export async function verifyInstalledBinaryLaunches(agent, version) {
-    // Windows: `getBinaryPath` returns the extensionless `.bin/<cli>` (a shell
-    // wrapper), NOT the `.cmd`/`.exe` that actually launches there — `execFile`ing
-    // it would ENOENT on a perfectly healthy install, and the integrity gate would
-    // then WIPE it. The gutted-native-binary failure this guards against is a POSIX
-    // concern in practice; treat win32 as healthy rather than risk destroying a
-    // good install. (isVersionInstalled already validates presence on Windows.)
-    if (process.platform === 'win32')
-        return { ok: true };
-    const binary = getBinaryPath(agent, version);
+    // The real launch target differs by platform, so probe whatever `agents run`
+    // actually execs. On Windows that's the npm `.cmd` wrapper (exec.ts uses
+    // `absPath + '.cmd'`), which chains to the native `.exe`; a gutted install
+    // (renamed/missing `.exe`) makes that wrapper emit "is not recognized" — the
+    // exact win-mini failure a vendor auto-update leaves behind. Probing the
+    // extensionless `.bin/<cli>` instead would ENOENT even on a HEALTHY Windows
+    // install, so we DON'T. On POSIX the `.bin/<cli>` binary is the launch target
+    // and is probed directly.
+    const isWin = process.platform === 'win32';
+    const binary = isWin ? getBinaryPath(agent, version) + '.cmd' : getBinaryPath(agent, version);
     if (!fs.existsSync(binary)) {
-        return { ok: false, detail: `binary not found at ${binary}` };
+        // Windows: a missing `.cmd` means a non-npm/global agent (droid.exe) we can't
+        // safely probe — treat as healthy (isVersionInstalled validates presence).
+        // POSIX: a missing launch binary is a genuine gutted install.
+        return isWin ? { ok: true } : { ok: false, detail: `binary not found at ${binary}` };
     }
     try {
-        await execFileAsync(binary, ['--version'], {
+        // On Windows the `.cmd` runs via cmd.exe (shell). Pass a single FULLY-QUOTED
+        // command line + EMPTY args (composeWin32CommandLine) — the same DEP0190-safe
+        // pattern the real launch uses (exec.ts) — so a space in the Windows profile
+        // path (`C:\Users\John Doe\…`) can't split the path and false-fail a healthy
+        // install into a destructive reinstall.
+        const spec = probeSpawnSpec(binary, isWin);
+        await execFileAsync(spec.command, spec.args, {
             timeout: 15000,
+            shell: spec.shell,
             env: { ...process.env, HOME: getVersionHomePath(agent, version) },
         });
         return { ok: true };
@@ -1703,6 +1729,51 @@ export async function ensureAgentRunnable(agent, version, log) {
     }
     return null;
 }
+/**
+ * Proactive launch-health pass for the daemon. Probe the DEFAULT version of
+ * every npm-package agent and repair any that won't launch (via
+ * ensureAgentRunnable), so a gutted install is healed BEFORE the user's next
+ * `agents run` hits a raw ENOENT — the run-time heal (ensureAgentRunnable) only
+ * fires once a run is already starting; this catches it in the background.
+ *
+ * Returns a label (`agent@broken→healed`) for each version actually repaired, so
+ * the daemon can log/notify. A version that already launches costs one cheap
+ * `--version` probe and is left untouched.
+ */
+const failedRepairAt = new Map();
+const REPAIR_COOLDOWN_MS = 24 * 60 * 60_000;
+export async function healBrokenDefaultLaunches(log) {
+    const repaired = [];
+    for (const agent of Object.keys(AGENTS)) {
+        if (!AGENTS[agent].npmPackage)
+            continue; // native/global agents have no gutted-tarball failure mode
+        const version = getGlobalDefault(agent);
+        if (!version)
+            continue;
+        if ((await verifyInstalledBinaryLaunches(agent, version)).ok)
+            continue;
+        // Backoff: a version whose repair just failed (offline, npm 404, an arch the
+        // registry can't serve) must NOT re-trigger a full clean-reinstall +
+        // install-latest on every 6h pass. Skip it for a day; a daemon restart clears
+        // the memo, giving a fresh attempt.
+        const key = `${agent}@${version}`;
+        const last = failedRepairAt.get(key);
+        if (last !== undefined && Date.now() - last < REPAIR_COOLDOWN_MS) {
+            log?.(`${AGENTS[agent].name}@${version} still won't launch — repair attempted recently, skipping until cooldown elapses.`);
+            continue;
+        }
+        log?.(`${AGENTS[agent].name}@${version} won't launch — repairing…`);
+        const healed = await ensureAgentRunnable(agent, version, log);
+        if (healed) {
+            failedRepairAt.delete(key);
+            repaired.push(`${agent}@${version}${healed === version ? '' : `→${healed}`}`);
+        }
+        else {
+            failedRepairAt.set(key, Date.now());
+        }
+    }
+    return repaired;
+}
 async function getCliVersionFromPath(agent) {
     const agentConfig = AGENTS[agent];
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.46",
+  "version": "1.20.47",
   "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",