@phnx-labs/agents-cli 1.20.45 → 1.20.47

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

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

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

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

package/dist/lib/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/shim-heal.d.ts

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

package/dist/lib/shim-heal.js

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

package/dist/lib/shims.d.ts

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

package/dist/lib/shims.js

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

package/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.45",
+  "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",