@cortexkit/aft 0.19.4 → 0.19.5

package/README.md

@@ -5,10 +5,10 @@ Unified CLI for [Agent File Tools (AFT)](https://github.com/cortexkit/aft) — s
 ## Usage
 
 ```bash
-bunx --bun @cortexkit/aft setup            # interactive setup for one or more harnesses
-bunx --bun @cortexkit/aft doctor           # check and fix configuration issues
-bunx --bun @cortexkit/aft doctor --force   # force clear plugin cache
-bunx --bun @cortexkit/aft doctor --issue   # collect diagnostics and open a GitHub issue
+npx @cortexkit/aft setup            # interactive setup for one or more harnesses
+npx @cortexkit/aft doctor           # check and fix configuration issues
+npx @cortexkit/aft doctor --force   # force clear plugin cache
+npx @cortexkit/aft doctor --issue   # collect diagnostics and open a GitHub issue
 ```
 
 By default the CLI auto-detects which harnesses are installed on your system (OpenCode, Pi). When multiple are detected, it prompts you to choose. Use `--harness opencode` or `--harness pi` to target one explicitly.

package/dist/adapters/pi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pi.d.ts","sourceRoot":"","sources":["../../src/adapters/pi.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAuDpB,qBAAa,SAAU,YAAW,cAAc;IAC9C,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;IAC9B,QAAQ,CAAC,WAAW,QAAQ;IAC5B,QAAQ,CAAC,iBAAiB,uBAAe;IACzC,QAAQ,CAAC,sBAAsB,2BAAgB;IAE/C,WAAW,IAAI,OAAO;IAStB,cAAc,IAAI,MAAM,GAAG,IAAI;IAQ/B,iBAAiB,IAAI,kBAAkB;IAevC,cAAc,IAAI,OAAO;IAInB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAmCrD,kBAAkB,IAAI,eAAe;IA6BrC,aAAa,IAAI,MAAM;IAKvB,UAAU,IAAI,MAAM;IAIpB,cAAc,IAAI,MAAM;IAIlB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;QAC/C,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAC;QAC5E,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IASF,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAUlD"}
+{"version":3,"file":"pi.d.ts","sourceRoot":"","sources":["../../src/adapters/pi.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAuDpB,qBAAa,SAAU,YAAW,cAAc;IAC9C,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;IAC9B,QAAQ,CAAC,WAAW,QAAQ;IAC5B,QAAQ,CAAC,iBAAiB,uBAAe;IACzC,QAAQ,CAAC,sBAAsB,2BAAgB;IAE/C,WAAW,IAAI,OAAO;IAStB,cAAc,IAAI,MAAM,GAAG,IAAI;IAQ/B,iBAAiB,IAAI,kBAAkB;IAevC,cAAc,IAAI,OAAO;IAInB,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAmCrD,kBAAkB,IAAI,eAAe;IA6BrC,aAAa,IAAI,MAAM;IAKvB,UAAU,IAAI,MAAM;IAIpB,cAAc,IAAI,MAAM;IAIlB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;QAC/C,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAC;QAC5E,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAUF,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;CAUlD"}

package/dist/adapters/types.d.ts

@@ -66,8 +66,8 @@ export interface HarnessAdapter {
     getInstallHint(): string;
     /**
      * Harness-aware version of `doctor --force` cache clearing. OpenCode nukes
-     * its bunx package cache; Pi may be a no-op because Pi caches are managed by
-     * `pi install` itself.
+     * its npm/npx package cache (`~/.cache/opencode/packages/...`); Pi may be a
+     * no-op because Pi caches are managed by `pi install` itself.
      */
     clearPluginCache(force: boolean): Promise<{
         action: "cleared" | "up_to_date" | "not_found" | "not_applicable" | "error";

package/dist/commands/doctor.d.ts

@@ -1,6 +1,6 @@
 import type { HarnessAdapter } from "../adapters/types.js";
 import { type ClearResult } from "../lib/lsp-cache.js";
-export type DoctorClearTarget = "plugin-cache" | "lsp-cache";
+export type DoctorClearTarget = "plugin-cache" | "lsp-cache" | "binary-cache";
 export declare const DOCTOR_CLEAR_TARGET_OPTIONS: {
     label: string;
     value: DoctorClearTarget;
@@ -8,6 +8,7 @@ export declare const DOCTOR_CLEAR_TARGET_OPTIONS: {
 export declare const DOCTOR_FORCE_CLEAR_TARGETS: DoctorClearTarget[];
 export interface DoctorOptions {
     clear: boolean;
+    fix: boolean;
     force: boolean;
     issue: boolean;
     argv: string[];
@@ -24,6 +25,11 @@ export interface CacheClearSummary {
         totalBytes: number;
         errors: number;
     };
+    binaryCache?: {
+        cleared: number;
+        totalBytes: number;
+        errors: number;
+    };
 }
 export interface CacheClearOptions {
     clearLspCaches?: () => ClearResult;
@@ -31,4 +37,25 @@ export interface CacheClearOptions {
 }
 export declare function runDoctor(options: DoctorOptions): Promise<number>;
 export declare function clearDoctorCaches(adapters: HarnessAdapter[], targets: readonly DoctorClearTarget[], options?: CacheClearOptions): Promise<CacheClearSummary>;
+/**
+ * Clear cached `aft` binaries except the version this CLI ships with.
+ *
+ * Each release of `@cortexkit/aft` bundles a matching binary version; the
+ * plugin downloads it on first use into `~/.cache/aft/bin/v<version>/aft`.
+ * Older versions are kept around for rollback and to handle the
+ * "old plugin instance still running" scenario, but they pile up over
+ * time and a single binary is ~30 MB on macOS / Linux. Clearing keeps
+ * the version that matches the running CLI so we don't yank the binary
+ * a live OpenCode/Pi process is currently executing from.
+ */
+export interface BinaryCacheClearResult {
+    cleared: number;
+    bytesReclaimed: number;
+    errors: {
+        path: string;
+        error: string;
+    }[];
+    keptVersion: string | null;
+}
+export declare function clearOldBinaries(): BinaryCacheClearResult;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAIvE,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,WAAW,CAAC;AAE7D,eAAO,MAAM,2BAA2B,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,EASpF,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,iBAAiB,EAAqB,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,MAAM,WAAW,CAAC;IACnC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAgGvE;AA4BD,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAoC5B"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAM3D,OAAO,EAAE,KAAK,WAAW,EAAkB,MAAM,qBAAqB,CAAC;AAMvE,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAE9E,eAAO,MAAM,2BAA2B,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,EAapF,CAAC;AAEF,eAAO,MAAM,0BAA0B,EAAE,iBAAiB,EAAqB,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,QAAQ,CAAC,EAAE;QACT,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,WAAW,CAAC,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,MAAM,WAAW,CAAC;IACnC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAoGvE;AA4BD,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,cAAc,EAAE,EAC1B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,iBAAiB,CAAC,CAgD5B;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC1C,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,gBAAgB,IAAI,sBAAsB,CAsDzD"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,QAAA,MAAM,OAAO,QAAkB,CAAC;AAChC,QAAA,MAAM,IAAI,UAAwB,CAAC;AAEnC,iBAAS,SAAS,IAAI,IAAI,CAwBzB;AAED,iBAAe,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAkBrC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,QAAA,MAAM,OAAO,QAAkB,CAAC;AAChC,QAAA,MAAM,IAAI,UAAwB,CAAC;AAEnC,iBAAS,SAAS,IAAI,IAAI,CAyBzB;AAED,iBAAe,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAmBrC"}

package/dist/index.js

@@ -9007,7 +9007,7 @@ var import_sisteransi, E, G, u, Y, C, O = (r) => ("columns" in r) && typeof r.co
       this.output.write(t), this.state === "initial" && (this.state = "active"), this._prevFrame = t;
     }
   }
-}, H, X, et, st, it, nt, at;
+}, H, Q, X, et, st, it, nt, at;
 var init_dist3 = __esm(() => {
   init_main();
   import_sisteransi = __toESM(require_src3(), 1);
@@ -9082,6 +9082,23 @@ var init_dist3 = __esm(() => {
       }
     }
   };
+  Q = class Q extends p {
+    get cursor() {
+      return this.value ? 0 : 1;
+    }
+    get _value() {
+      return this.cursor === 0;
+    }
+    constructor(t) {
+      super(t, false), this.value = !!t.initialValue, this.on("userInput", () => {
+        this.value = this._value;
+      }), this.on("confirm", (e) => {
+        this.output.write(import_sisteransi.cursor.move(0, -1)), this.value = e, this.state = "submit", this.close();
+      }), this.on("cursor", () => {
+        this.value = !this.value;
+      });
+    }
+  };
   X = { Y: { type: "year", len: 4 }, M: { type: "month", len: 2 }, D: { type: "day", len: 2 } };
   et = class et extends p {
     #e;
@@ -9435,6 +9452,32 @@ var import_sisteransi2, ee, w2 = (e, i) => ee ? e : i, _e, oe, ue, F2, le, d2, E
     for (const x of b)
       C2.push(x);
   return g && C2.push(l), C2;
+}, ot2 = (e) => {
+  const i = e.active ?? "Yes", s = e.inactive ?? "No";
+  return new Q({ active: i, inactive: s, signal: e.signal, input: e.input, output: e.output, initialValue: e.initialValue ?? true, render() {
+    const r = e.withGuide ?? u.withGuide, u2 = `${V2(this.state)}  `, n = r ? `${t("gray", d2)}  ` : "", o = R(e.output, e.message, n, u2), c2 = `${r ? `${t("gray", d2)}
+` : ""}${o}
+`, a = this.value ? i : s;
+    switch (this.state) {
+      case "submit": {
+        const l = r ? `${t("gray", d2)}  ` : "";
+        return `${c2}${l}${t("dim", a)}`;
+      }
+      case "cancel": {
+        const l = r ? `${t("gray", d2)}  ` : "";
+        return `${c2}${l}${t(["strikethrough", "dim"], a)}${r ? `
+${t("gray", d2)}` : ""}`;
+      }
+      default: {
+        const l = r ? `${t("cyan", d2)}  ` : "", $2 = r ? t("cyan", E2) : "";
+        return `${c2}${l}${this.value ? `${t("green", z2)} ${i}` : `${t("dim", H2)} ${t("dim", i)}`}${e.vertical ? r ? `
+${t("cyan", d2)}  ` : `
+` : ` ${t("dim", "/")} `}${this.value ? `${t("dim", H2)} ${t("dim", s)}` : `${t("green", z2)} ${s}`}
+${$2}
+`;
+      }
+    }
+  } }).prompt();
 }, O2, mt = (e = "", i) => {
   const s = i?.output ?? process.stdout, r = i?.withGuide ?? u.withGuide ? `${t("gray", le)}  ` : "";
   s.write(`${r}${e}
@@ -9658,6 +9701,14 @@ function handleCancel(value, message = "Cancelled.") {
     process.exit(0);
   }
 }
+async function confirm(message, defaultYes = true) {
+  const result = await ot2({
+    message,
+    initialValue: defaultYes
+  });
+  handleCancel(result);
+  return result;
+}
 async function selectOne(message, options) {
   const clackOptions = options.map((option) => {
     const hint = option.hint ?? (option.recommended ? "recommended" : undefined);
@@ -9800,7 +9851,7 @@ function printNextSteps(adapter) {
   if (adapter.kind === "opencode") {
     wt([
       "Restart OpenCode (or reload your session) so the plugin loads.",
-      "Verify with: `bunx --bun @cortexkit/aft doctor`."
+      "Verify with: `npx @cortexkit/aft doctor`."
     ].join(`
 `), "Next steps");
     return;
@@ -9808,7 +9859,7 @@ function printNextSteps(adapter) {
   if (adapter.kind === "pi") {
     wt([
       "Restart your Pi session so the extension registers.",
-      "Verify with: `bunx --bun @cortexkit/aft doctor`."
+      "Verify with: `npx @cortexkit/aft doctor`."
     ].join(`
 `), "Next steps");
   }
@@ -9826,6 +9877,7 @@ async function sendAftRequests(binaryPath, requests) {
       stdio: ["pipe", "pipe", "pipe"]
     });
     const responses = [];
+    const noiseLines = [];
     let stdout = "";
     let stderr = "";
     let settled = false;
@@ -9839,14 +9891,18 @@ async function sendAftRequests(binaryPath, requests) {
     const handleLine = (line) => {
       if (!line)
         return;
-      try {
-        responses.push(JSON.parse(line));
-      } catch (error) {
-        finish(() => reject(error));
+      if (!line.startsWith("{")) {
+        noiseLines.push(line);
         return;
       }
-      if (responses.length === requests.length) {
-        finish(() => resolve2(responses));
+      try {
+        const parsed = JSON.parse(line);
+        responses.push(parsed);
+        if (responses.length === requests.length) {
+          finish(() => resolve2(responses));
+        }
+      } catch {
+        noiseLines.push(line);
       }
     };
     child.stdout.setEncoding("utf-8");
@@ -9874,7 +9930,7 @@ async function sendAftRequests(binaryPath, requests) {
     child.on("exit", (code) => {
       if (settled)
         return;
-      finish(() => reject(new Error(`aft exited before responding (code ${code}): ${stderr.trim()}`)));
+      finish(() => reject(buildBridgeError({ binaryPath, code, stderr, noiseLines, responses })));
     });
     for (const request of requests) {
       child.stdin.write(`${JSON.stringify(request)}
@@ -9883,6 +9939,34 @@ async function sendAftRequests(binaryPath, requests) {
     child.stdin.end();
   });
 }
+function buildBridgeError(ctx) {
+  const parts = [];
+  parts.push(`aft exited before responding (binary: ${ctx.binaryPath}, exit code: ${ctx.code ?? "unknown"}).`);
+  if (ctx.responses.length > 0) {
+    parts.push(`Got ${ctx.responses.length} valid response(s) before exit.`);
+  }
+  if (ctx.noiseLines.length > 0) {
+    parts.push(`
+The binary printed ${ctx.noiseLines.length} non-JSON line(s) to stdout — this usually means ` + "the resolved binary isn't an AFT release binary (wrapper script, panic output, or unrelated tool):");
+    const sample = ctx.noiseLines.slice(0, MAX_NOISE_LINES_IN_ERROR).map((line) => `  | ${line}`);
+    parts.push(sample.join(`
+`));
+    if (ctx.noiseLines.length > MAX_NOISE_LINES_IN_ERROR) {
+      parts.push(`  | (… ${ctx.noiseLines.length - MAX_NOISE_LINES_IN_ERROR} more line(s) omitted)`);
+    }
+    parts.push(`
+Try: npx @cortexkit/aft doctor (full diagnostics) or check ~/.cache/aft/bin/ for the right binary.`);
+  }
+  const stderrTrimmed = ctx.stderr.trim();
+  if (stderrTrimmed) {
+    parts.push(`
+stderr:
+${stderrTrimmed}`);
+  }
+  return new Error(parts.join(`
+`));
+}
+var MAX_NOISE_LINES_IN_ERROR = 5;
 var init_aft_bridge = () => {};
 
 // src/lib/binary-probe.ts
@@ -10647,21 +10731,108 @@ function createGitHubIssue(repo, title, body) {
 }
 var init_github = () => {};
 
+// src/lib/onnx-fix.ts
+import { existsSync as existsSync11, rmSync as rmSync3 } from "node:fs";
+import { join as join10 } from "node:path";
+function findOnnxFixCandidates(report) {
+  const candidates = [];
+  for (const harness of report.harnesses) {
+    if (!harness.onnxRuntime.required)
+      continue;
+    if (!harness.storageDir.exists)
+      continue;
+    const storageOnnxDir = join10(harness.storageDir.path, "onnxruntime");
+    const systemTooOld = harness.onnxRuntime.systemPath !== null && harness.onnxRuntime.systemCompatible === false;
+    const cachedTooOld = harness.onnxRuntime.cachedPath !== null && harness.onnxRuntime.cachedCompatible === false;
+    const hasCompatibleCached = harness.onnxRuntime.cachedCompatible === true;
+    if (cachedTooOld) {
+      candidates.push({
+        harness,
+        reason: `cached ONNX Runtime at ${harness.onnxRuntime.cachedPath} is v${harness.onnxRuntime.cachedVersion}, but AFT requires ${harness.onnxRuntime.requirement}. Clearing forces a fresh download on next start.`,
+        storageOnnxDir,
+        storageOnnxBytes: existsSync11(storageOnnxDir) ? dirSize(storageOnnxDir) : 0
+      });
+      continue;
+    }
+    if (systemTooOld && !hasCompatibleCached) {
+      candidates.push({
+        harness,
+        reason: `system ONNX Runtime at ${harness.onnxRuntime.systemPath} is v${harness.onnxRuntime.systemVersion}, but AFT requires ${harness.onnxRuntime.requirement}, and no AFT-managed install is present. AFT v0.19.5+ skips incompatible system installs and auto-downloads v1.24 on next start; clearing any stale state here ensures a clean slate.`,
+        storageOnnxDir,
+        storageOnnxBytes: existsSync11(storageOnnxDir) ? dirSize(storageOnnxDir) : 0
+      });
+    }
+  }
+  return candidates;
+}
+async function runOnnxFix(adapters, report, options = {}) {
+  const candidates = findOnnxFixCandidates(report);
+  if (candidates.length === 0) {
+    return null;
+  }
+  O2.warn(`Found ${candidates.length} ONNX Runtime issue(s) that --fix can address by clearing AFT-managed cache:`);
+  for (const c2 of candidates) {
+    O2.info(`  • ${c2.harness.displayName}: ${c2.reason}`);
+    if (c2.storageOnnxBytes > 0) {
+      O2.info(`    will delete: ${c2.storageOnnxDir} (${formatBytes(c2.storageOnnxBytes)})`);
+    } else {
+      O2.info(`    no AFT-managed ONNX cache to delete; nothing to reclaim`);
+    }
+  }
+  wt("This NEVER touches system paths like /usr/lib. It only deletes AFT's own ONNX download cache. " + "On next bridge start, AFT will re-download ONNX Runtime v1.24 and use that instead of the " + "incompatible system library.", "Safe operation");
+  const confirmFn = options.confirmFn ?? confirm;
+  const proceed = options.yes ? true : await confirmFn("Proceed with the fixes above?", true);
+  if (!proceed) {
+    O2.info("Skipped — no changes made.");
+    return null;
+  }
+  const result = { cleared: 0, bytesReclaimed: 0, errors: [] };
+  const rmFn = options.rmFn ?? rmSync3;
+  for (const c2 of candidates) {
+    if (!existsSync11(c2.storageOnnxDir)) {
+      O2.success(`${c2.harness.displayName}: no cached state to clear; restart your harness to trigger a fresh ONNX download`);
+      continue;
+    }
+    try {
+      rmFn(c2.storageOnnxDir, { recursive: true, force: true });
+      result.cleared += 1;
+      result.bytesReclaimed += c2.storageOnnxBytes;
+      O2.success(`${c2.harness.displayName}: cleared ${c2.storageOnnxDir} (reclaimed ${formatBytes(c2.storageOnnxBytes)})`);
+    } catch (err) {
+      const message = err.message ?? "unknown error";
+      O2.error(`${c2.harness.displayName}: failed to clear ${c2.storageOnnxDir}: ${message}`);
+      result.errors.push({ path: c2.storageOnnxDir, error: message });
+    }
+  }
+  if (result.cleared > 0 || candidates.some((c2) => c2.storageOnnxBytes === 0)) {
+    wt("Restart your AFT-using harness (OpenCode / Pi) to trigger a fresh ONNX Runtime download. " + "Watch the TUI sidebar — the Semantic Index status should move from 'failed' → 'building' → 'ready'.", "Next step");
+  }
+  return result;
+}
+var init_onnx_fix = __esm(() => {
+  init_fs_util();
+  init_prompts();
+});
+
 // src/commands/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
   runDoctor: () => runDoctor,
+  clearOldBinaries: () => clearOldBinaries,
   clearDoctorCaches: () => clearDoctorCaches,
   DOCTOR_FORCE_CLEAR_TARGETS: () => DOCTOR_FORCE_CLEAR_TARGETS,
   DOCTOR_CLEAR_TARGET_OPTIONS: () => DOCTOR_CLEAR_TARGET_OPTIONS
 });
-import { writeFileSync as writeFileSync2 } from "node:fs";
-import { join as join10 } from "node:path";
+import { existsSync as existsSync12, rmSync as rmSync4, statSync as statSync8, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join11 } from "node:path";
 async function runDoctor(options) {
   if (options.issue) {
     return runIssueFlow(options.argv);
   }
   mt("AFT doctor");
+  if (options.fix) {
+    return runFixFlow(options.argv);
+  }
   if (options.clear) {
     return runClearFlow(options.argv);
   }
@@ -10771,8 +10942,80 @@ async function clearDoctorCaches(adapters, targets, options = {}) {
       errors: cleanup.errors.length
     };
   }
+  if (targets.includes("binary-cache")) {
+    const result = clearOldBinaries();
+    if (result.errors.length > 0) {
+      summary.hadErrors = true;
+    }
+    summary.binaryCache = {
+      cleared: result.cleared,
+      totalBytes: result.bytesReclaimed,
+      errors: result.errors.length
+    };
+  }
   return summary;
 }
+function clearOldBinaries() {
+  const cliVersion = getSelfVersion();
+  const keepTag = `v${cliVersion.replace(/^v/, "")}`;
+  const info = getBinaryCacheInfo(cliVersion);
+  const result = {
+    cleared: 0,
+    bytesReclaimed: 0,
+    errors: [],
+    keptVersion: keepTag
+  };
+  if (!existsSync12(info.path)) {
+    O2.info(`Binary cache: nothing to clear at ${info.path}`);
+    return result;
+  }
+  const stale = info.versions.filter((v) => v !== keepTag);
+  if (stale.length === 0) {
+    O2.info(`Binary cache: only the active version (${keepTag}) is present at ${info.path}; nothing to clear`);
+    return result;
+  }
+  for (const version of stale) {
+    const dir = join11(info.path, version);
+    let bytes = 0;
+    try {
+      bytes = statSync8(dir).isDirectory() ? dirSize(dir) : 0;
+    } catch {
+      bytes = 0;
+    }
+    try {
+      rmSync4(dir, { recursive: true, force: true });
+      result.cleared += 1;
+      result.bytesReclaimed += bytes;
+      O2.success(`Binary cache: cleared ${dir} (reclaimed ${formatBytes(bytes)})`);
+    } catch (err) {
+      const message = err.message ?? "unknown error";
+      O2.error(`Binary cache: failed to remove ${dir}: ${message}`);
+      result.errors.push({ path: dir, error: message });
+    }
+  }
+  if (result.cleared > 0) {
+    O2.success(`Binary cache: kept ${keepTag}, removed ${result.cleared} old version(s), reclaimed ${formatBytes(result.bytesReclaimed)}`);
+  }
+  return result;
+}
+async function runFixFlow(argv) {
+  const adapters = await resolveAdaptersForCommand(argv, {
+    allowMulti: true,
+    verb: "auto-fix issues for"
+  });
+  O2.info("Running diagnostics to identify auto-fixable issues…");
+  const report = await collectDiagnostics(adapters);
+  const onnxResult = await runOnnxFix(adapters, report);
+  if (onnxResult === null) {
+    O2.info("No auto-fixable issues detected.");
+    wt("If you're still seeing 'Semantic Index: failed' in the TUI sidebar, run " + "`aft doctor` (without --fix) for a full diagnostic dump.", "Tip");
+    gt("Done.");
+    return 0;
+  }
+  const hadErrors = onnxResult.errors.length > 0;
+  gt(hadErrors ? "Done — some fixes failed." : "Done.");
+  return hadErrors ? 1 : 0;
+}
 async function clearPluginCache(adapter, includeBytes) {
   const info = adapter.getPluginCacheInfo();
   const bytes = info.exists ? dirSize(info.path) : 0;
@@ -10870,7 +11113,7 @@ ${tail || "<no log output>"}
 `);
   const body = sanitizeContent(rawBody);
   const title = `AFT issue: ${description.slice(0, 72)}`;
-  const outPath = join10(process.cwd(), `aft-issue-${Date.now()}.md`);
+  const outPath = join11(process.cwd(), `aft-issue-${Date.now()}.md`);
   writeFileSync2(outPath, `${body}
 `);
   O2.success(`Wrote sanitized issue body to ${outPath}`);
@@ -10894,13 +11137,16 @@ ${tail || "<no log output>"}
 }
 var DOCTOR_CLEAR_TARGET_OPTIONS, DOCTOR_FORCE_CLEAR_TARGETS;
 var init_doctor = __esm(() => {
+  init_binary_cache();
   init_diagnostics();
   init_fs_util();
   init_github();
   init_harness_select();
   init_lsp_cache();
+  init_onnx_fix();
   init_prompts();
   init_sanitize();
+  init_self_version();
   DOCTOR_CLEAR_TARGET_OPTIONS = [
     {
       label: "Plugin npm cache (~/.cache/opencode/packages/@cortexkit/aft-opencode@latest, etc.)",
@@ -10909,6 +11155,10 @@ var init_doctor = __esm(() => {
     {
       label: "LSP install cache (~/.cache/aft/lsp-packages/, ~/.cache/aft/lsp-binaries/)",
       value: "lsp-cache"
+    },
+    {
+      label: "Old aft binaries (~/.cache/aft/bin/v* — keeps the version matching this CLI)",
+      value: "binary-cache"
     }
   ];
   DOCTOR_FORCE_CLEAR_TARGETS = ["plugin-cache"];
@@ -10926,6 +11176,7 @@ function printHelp() {
   console.log("    setup            Interactive setup wizard");
   console.log("    doctor           Check and fix configuration issues");
   console.log("    doctor lsp <file> Inspect LSP setup for one file");
+  console.log("    doctor --fix     Auto-fix common issues (e.g. ONNX Runtime mismatch)");
   console.log("    doctor --clear   Select caches to clear with an interactive prompt");
   console.log("    doctor --issue   Collect diagnostics and open a GitHub issue");
   console.log("");
@@ -10935,11 +11186,11 @@ function printHelp() {
   console.log("    (default: auto-detect, prompt if multiple detected)");
   console.log("");
   console.log("  Usage:");
-  console.log("    bunx --bun @cortexkit/aft setup");
-  console.log("    bunx --bun @cortexkit/aft doctor");
-  console.log("    bunx --bun @cortexkit/aft doctor lsp ./src/main.py");
-  console.log("    bunx --bun @cortexkit/aft doctor --clear");
-  console.log("    bunx --bun @cortexkit/aft doctor --issue");
+  console.log("    npx @cortexkit/aft setup");
+  console.log("    npx @cortexkit/aft doctor");
+  console.log("    npx @cortexkit/aft doctor lsp ./src/main.py");
+  console.log("    npx @cortexkit/aft doctor --clear");
+  console.log("    npx @cortexkit/aft doctor --issue");
   console.log("");
 }
 async function main() {
@@ -10955,8 +11206,9 @@ async function main() {
     const { runDoctor: runDoctor2 } = await Promise.resolve().then(() => (init_doctor(), exports_doctor));
     const force = args.includes("--force");
     const clear = args.includes("--clear");
+    const fix = args.includes("--fix");
     const issue = args.includes("--issue");
-    return runDoctor2({ clear, force, issue, argv: args });
+    return runDoctor2({ clear, fix, force, issue, argv: args });
   }
   printHelp();
   return command ? 1 : 0;

package/dist/lib/aft-bridge.d.ts

@@ -11,5 +11,20 @@ export interface AftResponse {
     [key: string]: unknown;
 }
 export declare function sendAftRequest(binaryPath: string, request: AftRequest): Promise<AftResponse>;
+/**
+ * Send NDJSON requests to a long-running `aft` binary and collect
+ * matching responses.
+ *
+ * The contract is forgiving by design: any stdout line that isn't valid
+ * JSON is treated as binary noise (panic message, banner from a wrapper
+ * script, log line that escaped to stdout, etc.) and remembered for
+ * diagnostics rather than crashing the caller. We only report failure
+ * when the binary exits without producing the expected number of valid
+ * responses — and when we do, the error message names the specific
+ * binary path, the noise we observed, and the stderr tail so the user
+ * gets actionable context (issue #29 was a raw `SyntaxError` stack from
+ * `JSON.parse` on the first leaked stdout line, with no hint what to
+ * try next).
+ */
 export declare function sendAftRequests(binaryPath: string, requests: AftRequest[]): Promise<AftResponse[]>;
 //# sourceMappingURL=aft-bridge.d.ts.map

package/dist/lib/aft-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aft-bridge.d.ts","sourceRoot":"","sources":["../../src/lib/aft-bridge.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,WAAW,CAAC,CAKtB;AAED,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,EAAE,GACrB,OAAO,CAAC,WAAW,EAAE,CAAC,CAgExB"}
+{"version":3,"file":"aft-bridge.d.ts","sourceRoot":"","sources":["../../src/lib/aft-bridge.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAUD,wBAAsB,cAAc,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,WAAW,CAAC,CAKtB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,UAAU,EAAE,GACrB,OAAO,CAAC,WAAW,EAAE,CAAC,CAuExB"}

package/dist/lib/onnx-fix.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ONNX Runtime auto-fix logic for `aft doctor --fix`.
+ *
+ * The most common ONNX failure mode in production is: a distro ships an
+ * old `libonnxruntime.so` (Ubuntu 22.04 still has v1.9, etc.), AFT's
+ * resolver picks it up, the Rust pre-validator rejects it as too old,
+ * and semantic search shows "failed" forever in the TUI sidebar.
+ *
+ * The error message tells users to either:
+ *   1. `rm /usr/lib/.../libonnxruntime.so` — needs sudo, breaks anything
+ *      else linking that library, irreversible.
+ *   2. Install ONNX 1.24 system-wide — manual, slow, distro-specific.
+ *   3. Run doctor — diagnostics only.
+ *
+ * None of those is automatable safely. But there's a fourth option AFT
+ * actually owns end-to-end: clear `<storage_dir>/onnxruntime/` and let
+ * the bridge re-download v1.24 on next start. That's what `--fix` does.
+ *
+ * Pair this with the resolver fix in `packages/aft-bridge/src/onnx-runtime.ts`
+ * (which now skips system installs below v1.20) and the user gets a working
+ * AFT-managed ONNX even when the system library is too old, with NO change
+ * to system files.
+ */
+import type { HarnessAdapter } from "../adapters/types.js";
+import type { DiagnosticReport, HarnessDiagnostic } from "./diagnostics.js";
+export interface OnnxFixCandidate {
+    harness: HarnessDiagnostic;
+    reason: string;
+    storageOnnxDir: string;
+    storageOnnxBytes: number;
+}
+/**
+ * Identify harnesses where AFT's ONNX resolution is broken and could be
+ * auto-fixed by clearing `<storage_dir>/onnxruntime/`. Each entry carries
+ * a human-readable reason so the prompt explains exactly what's wrong.
+ */
+export declare function findOnnxFixCandidates(report: DiagnosticReport): OnnxFixCandidate[];
+export interface OnnxFixResult {
+    cleared: number;
+    bytesReclaimed: number;
+    errors: {
+        path: string;
+        error: string;
+    }[];
+}
+export interface OnnxFixOptions {
+    /** Skip the user prompt and act immediately (used by tests + scripted flows). */
+    yes?: boolean;
+    /** Inject a custom confirm impl for testing. */
+    confirmFn?: (message: string, defaultYes?: boolean) => Promise<boolean>;
+    /** Inject a custom rmSync impl for testing. */
+    rmFn?: (path: string, options: {
+        recursive: boolean;
+        force: boolean;
+    }) => void;
+}
+/**
+ * Interactive ONNX fix flow. Returns the apply result (or null if no
+ * fixable issues were found, or the user declined).
+ *
+ * Safety contract:
+ *   - Only deletes paths inside `<storage_dir>/onnxruntime/` (AFT-owned).
+ *   - NEVER touches `/usr/lib/...`, `/opt/homebrew/lib/...`, or any other
+ *     system path.
+ *   - Asks consent before any deletion (unless `options.yes` is set).
+ *   - Reports byte counts so the user knows what's being reclaimed.
+ */
+export declare function runOnnxFix(adapters: HarnessAdapter[], report: DiagnosticReport, options?: OnnxFixOptions): Promise<OnnxFixResult | null>;
+//# sourceMappingURL=onnx-fix.d.ts.map

package/dist/lib/onnx-fix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onnx-fix.d.ts","sourceRoot":"","sources":["../../src/lib/onnx-fix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAI5E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAyClF;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,gDAAgD;IAChD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxE,+CAA+C;IAC/C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAChF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,cAAc,EAAE,EAC1B,MAAM,EAAE,gBAAgB,EACxB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA6E/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/aft",
-  "version": "0.19.4",
+  "version": "0.19.5",
   "type": "module",
   "description": "Unified CLI for Agent File Tools (AFT) — setup, doctor, and diagnostics across supported agent harnesses (OpenCode, Pi)",
   "license": "MIT",