@juspay/neurolink 11.21.4 → 11.22.1

package/dist/cli/commands/ollama.js

@@ -29,10 +29,16 @@ export function addOllamaCommands(cli) {
             .demandCommand(1, "Please specify a command");
     }, () => { });
 }
+/** See the note on the identically-named constant in ../utils/ollamaUtils.ts. */
+const OLLAMA_QUERY_TIMEOUT_MS = 15_000;
 async function listModelsHandler() {
     const spinner = ora("Fetching installed models...").start();
     try {
-        const res = spawnSync("ollama", ["list"], { encoding: "utf8" });
+        const res = spawnSync("ollama", ["list"], {
+            encoding: "utf8",
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
         if (res.error) {
             throw res.error;
         }
@@ -58,6 +64,9 @@ async function pullModelHandler(argv) {
     logger.always(chalk.blue(`Downloading model: ${model}`));
     logger.always(chalk.gray("This may take several minutes..."));
     try {
+        // Deliberately unbounded: a model pull is hundreds of megabytes and
+        // legitimately runs for many minutes. It also inherits stdio, so the user
+        // sees progress and can Ctrl-C — the two things a wedged query lacks.
         const res = spawnSync("ollama", ["pull", model], { stdio: "inherit" });
         if (res.error) {
             throw res.error;
@@ -91,7 +100,11 @@ async function removeModelHandler(argv) {
     }
     const spinner = ora(`Removing model ${model}...`).start();
     try {
-        const res = spawnSync("ollama", ["rm", model], { encoding: "utf8" });
+        const res = spawnSync("ollama", ["rm", model], {
+            encoding: "utf8",
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
         if (res.error) {
             throw res.error;
         }
@@ -110,7 +123,11 @@ async function removeModelHandler(argv) {
 async function statusHandler() {
     const spinner = ora("Checking Ollama service status...").start();
     try {
-        const res = spawnSync("ollama", ["list"], { encoding: "utf8" });
+        const res = spawnSync("ollama", ["list"], {
+            encoding: "utf8",
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
         if (res.error) {
             throw res.error;
         }
@@ -134,22 +151,42 @@ async function stopHandler() {
     try {
         if (process.platform === "darwin") {
             try {
-                spawnSync("pkill", ["ollama"], { encoding: "utf8" });
+                spawnSync("pkill", ["ollama"], {
+                    encoding: "utf8",
+                    timeout: OLLAMA_QUERY_TIMEOUT_MS,
+                    killSignal: "SIGKILL",
+                });
             }
             catch {
-                spawnSync("killall", ["Ollama"], { encoding: "utf8" });
+                spawnSync("killall", ["Ollama"], {
+                    encoding: "utf8",
+                    timeout: OLLAMA_QUERY_TIMEOUT_MS,
+                    killSignal: "SIGKILL",
+                });
             }
         }
         else if (process.platform === "linux") {
             try {
-                spawnSync("systemctl", ["stop", "ollama"], { encoding: "utf8" });
+                spawnSync("systemctl", ["stop", "ollama"], {
+                    encoding: "utf8",
+                    timeout: OLLAMA_QUERY_TIMEOUT_MS,
+                    killSignal: "SIGKILL",
+                });
             }
             catch {
-                spawnSync("pkill", ["ollama"], { encoding: "utf8" });
+                spawnSync("pkill", ["ollama"], {
+                    encoding: "utf8",
+                    timeout: OLLAMA_QUERY_TIMEOUT_MS,
+                    killSignal: "SIGKILL",
+                });
             }
         }
         else {
-            spawnSync("taskkill", ["/F", "/IM", "ollama.exe"], { encoding: "utf8" });
+            spawnSync("taskkill", ["/F", "/IM", "ollama.exe"], {
+                encoding: "utf8",
+                timeout: OLLAMA_QUERY_TIMEOUT_MS,
+                killSignal: "SIGKILL",
+            });
         }
         spinner.succeed("Ollama service stopped");
     }
@@ -165,7 +202,11 @@ async function setupHandler() {
     const checkSpinner = ora("Checking Ollama installation...").start();
     let isInstalled = false;
     try {
-        spawnSync("ollama", ["--version"], { encoding: "utf8" });
+        spawnSync("ollama", ["--version"], {
+            encoding: "utf8",
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
         isInstalled = true;
         checkSpinner.succeed("Ollama is installed");
     }
@@ -204,7 +245,11 @@ async function setupHandler() {
     // Check if service is running
     let serviceRunning = false;
     try {
-        spawnSync("ollama", ["list"], { encoding: "utf8" });
+        spawnSync("ollama", ["list"], {
+            encoding: "utf8",
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
+        });
         serviceRunning = true;
         logger.always(chalk.green("\n✅ Ollama service is running"));
     }

package/dist/cli/commands/usage.d.ts

@@ -0,0 +1,17 @@
+import type { CommandModule } from "yargs";
+import type { LocalUsageCommandArgs } from "../../types/index.js";
+/**
+ * `neurolink usage local` — token spend read from each CLI's own session logs.
+ *
+ * The proxy's ledger only sees traffic that went through it, which is a
+ * fraction of what a developer actually spends: it depends on each vendor
+ * shipping a base-URL override, and most do not. Every CLI writes a local
+ * transcript regardless, so this reads those instead — no auth, no vendor
+ * cooperation, no proxy in the request path, and it recovers history from
+ * before the proxy was ever installed.
+ */
+export declare class UsageCommandFactory {
+    static createUsageCommands(): CommandModule<object, LocalUsageCommandArgs>;
+    private static formatTokens;
+    private static executeLocal;
+}

package/dist/cli/commands/usage.js

@@ -0,0 +1,146 @@
+import chalk from "chalk";
+import { logger } from "../../utils/logger.js";
+/**
+ * `neurolink usage local` — token spend read from each CLI's own session logs.
+ *
+ * The proxy's ledger only sees traffic that went through it, which is a
+ * fraction of what a developer actually spends: it depends on each vendor
+ * shipping a base-URL override, and most do not. Every CLI writes a local
+ * transcript regardless, so this reads those instead — no auth, no vendor
+ * cooperation, no proxy in the request path, and it recovers history from
+ * before the proxy was ever installed.
+ */
+export class UsageCommandFactory {
+    static createUsageCommands() {
+        return {
+            command: "usage <subcommand>",
+            describe: "Token usage read from local CLI session logs",
+            builder: (yargs) => yargs.command({
+                command: "local",
+                describe: "Summarise token spend from each installed CLI's own session logs",
+                builder: (sub) => sub
+                    .option("since", {
+                    type: "number",
+                    default: 30,
+                    description: "Only read sessions modified within this many days (0 = all history)",
+                })
+                    .option("cli", {
+                    type: "string",
+                    description: "Limit to one CLI id (e.g. claude-code, codex, opencode)",
+                })
+                    .option("json", {
+                    type: "boolean",
+                    default: false,
+                    description: "Emit the raw report as JSON",
+                }),
+                handler: async (argv) => {
+                    // Single assertion, not a double. yargs types the sub-builder's
+                    // argv structurally; the fields below are the ones the builder
+                    // declares, so this stays overlap-checked by the compiler.
+                    await UsageCommandFactory.executeLocal({
+                        since: Number(argv.since ?? 30),
+                        json: Boolean(argv.json),
+                        ...(typeof argv.cli === "string" ? { cli: argv.cli } : {}),
+                    });
+                },
+            }),
+            handler: () => {
+                // yargs prints subcommand help when none is given.
+            },
+        };
+    }
+    static formatTokens(value) {
+        // Plain grouped digits rather than 1.2M: these are billing-adjacent
+        // figures and a reader comparing two rows needs the magnitudes to line up,
+        // not to be rounded into looking similar.
+        return value.toLocaleString("en-US");
+    }
+    static async executeLocal(argv) {
+        const { readAllLocalUsage, getLocalUsageDescriptors } = await import("../../localUsage/index.js");
+        // `--since 0` means all history — Infinity is the reader's sentinel for
+        // "no time filter", but 0 is what a person types. A NEGATIVE value is a
+        // mistake and must be rejected rather than folded in with 0: the previous
+        // expression sent -1 down the all-history path, so a typo produced the
+        // most expensive possible scan while the option's own help text says 0 is
+        // the way to ask for that.
+        if (!Number.isFinite(argv.since) || argv.since < 0) {
+            console.error(chalk.red(`--since must be zero or greater (0 means all history). Received: ${String(argv.since)}`));
+            process.exitCode = 1;
+            return;
+        }
+        const sinceDays = argv.since > 0 ? argv.since : Infinity;
+        // Validate BEFORE scanning. A typo should cost nothing, not a full sweep
+        // of every store followed by an empty result.
+        // `undefined` means the flag was not given. An empty string means it was
+        // given with no value, which is a mistake and must be rejected — a
+        // truthiness check treats the two as the same and silently scans every
+        // reader instead, reporting everything for a request that named nothing.
+        const wanted = argv.cli;
+        const known = getLocalUsageDescriptors().map((d) => d.id);
+        if (wanted !== undefined &&
+            !known.includes(wanted)) {
+            console.error(chalk.red(`Unknown CLI "${wanted}". Known readers: ${known.join(", ")}`));
+            process.exitCode = 1;
+            return;
+        }
+        const report = await readAllLocalUsage({
+            sinceDays,
+            // Passed down so only the requested reader opens its store at all.
+            ...(wanted !== undefined
+                ? { only: [wanted] }
+                : {}),
+        });
+        const rows = Object.entries(report.totals);
+        if (argv.json) {
+            logger.always(JSON.stringify(wanted ? { ...report, totals: Object.fromEntries(rows) } : report, null, 2));
+            return;
+        }
+        const window = sinceDays === Infinity ? "all history" : `last ${argv.since} days`;
+        logger.always(chalk.bold(`\nLocal CLI token usage — ${window}\n`));
+        // A reader that ran and found nothing in the window is a different fact
+        // from one that is not installed, and from one that failed. Printing a
+        // block of zeros for it buries the rows that matter, so it gets one line.
+        const quiet = rows.filter(([, t]) => t && t.requests === 0);
+        const active = rows.filter(([, t]) => t && t.requests > 0);
+        for (const [cliId, totals] of active) {
+            if (!totals) {
+                continue;
+            }
+            const cached = totals.cacheReadTokens + totals.cacheCreationTokens;
+            logger.always(chalk.cyan(`  ${cliId}`));
+            logger.always(`    turns   ${UsageCommandFactory.formatTokens(totals.requests)}`);
+            logger.always(`    input   ${UsageCommandFactory.formatTokens(totals.inputTokens)}` +
+                `    output ${UsageCommandFactory.formatTokens(totals.outputTokens)}` +
+                `    cached ${UsageCommandFactory.formatTokens(cached)}`);
+            // Cost and its confidence are printed together, always. A dollar figure
+            // shown without saying how it was arrived at is the thing this whole
+            // subsystem is trying not to do: "unavailable" means the CLI is a
+            // subscription and a per-token price would be invented, not that the
+            // lookup failed.
+            if (totals.costConfidence === "modeled") {
+                logger.always(`    cost    ${chalk.green(`$${totals.costUsd.toFixed(2)}`)} (modeled)` +
+                    (totals.unpricedRequests > 0
+                        ? chalk.dim(`  — ${totals.unpricedRequests} turns unpriced: ${totals.unpricedModels.join(", ")}`)
+                        : ""));
+            }
+            else {
+                logger.always(`    cost    ${chalk.dim("unavailable")} ` +
+                    chalk.dim(totals.costConfidence === "heuristic"
+                        ? "(estimated, not measured)"
+                        : "(subscription — a per-token price would be invented)"));
+            }
+            logger.always("");
+        }
+        if (quiet.length > 0) {
+            logger.always(chalk.dim(`  no usage in this window: ${quiet.map(([id]) => id).join(", ")}`));
+        }
+        if (report.notInstalled.length > 0) {
+            logger.always(chalk.dim(`  not installed: ${report.notInstalled.join(", ")}`));
+        }
+        for (const failure of report.failures) {
+            logger.always(chalk.yellow(`  ${failure.cliId} failed: ${failure.message}`));
+        }
+        logger.always("");
+    }
+}
+//# sourceMappingURL=usage.js.map

package/dist/cli/factories/ollamaCommandFactory.d.ts

@@ -1,7 +1,4 @@
 import type { CommandModule } from "yargs";
-/**
- * Factory for creating Ollama CLI commands using the Factory Pattern
- */
 export declare class OllamaCommandFactory {
     /**
      * Secure wrapper around spawnSync to prevent command injection.
@@ -10,6 +7,17 @@ export declare class OllamaCommandFactory {
     /**
      * Create the Ollama command group
      */
+    /**
+     * Every handler is registered `.bind(this)`.
+     *
+     * yargs invokes the handler as a plain function, so a bare `this.xHandler`
+     * reference arrives with `this` unset and the first `this.safeSpawn(...)`
+     * throws `TypeError: this.safeSpawn is not a function`. That made EVERY
+     * subcommand here fail on its first line — list-models, pull, remove, status
+     * and stop all reported their generic "Failed to ..." message regardless of
+     * whether Ollama was installed or running, which is exactly why the real
+     * cause stayed hidden.
+     */
     static createOllamaCommands(): CommandModule;
     /**
      * Handler for listing installed models

package/dist/cli/factories/ollamaCommandFactory.js

@@ -9,6 +9,17 @@ import { AIProviderName } from "../../types/index.js";
 /**
  * Factory for creating Ollama CLI commands using the Factory Pattern
  */
+/** See the note on the identically-named constant in cli/utils/ollamaUtils.ts. */
+const OLLAMA_QUERY_TIMEOUT_MS = 15_000;
+/**
+ * Explicit opt-out from the query bound, for commands that are long by design.
+ *
+ * `spawnSync` treats 0 as "no timeout" (verified: a 3s child under
+ * `timeout: 0` runs to completion with no error, while `timeout: 1000` returns
+ * at 1.0s with ETIMEDOUT). Named rather than written as a bare 0 at the call
+ * site, because `timeout: 0` reads like "expire immediately".
+ */
+const OLLAMA_NO_TIMEOUT = 0;
 export class OllamaCommandFactory {
     /**
      * Secure wrapper around spawnSync to prevent command injection.
@@ -16,6 +27,12 @@ export class OllamaCommandFactory {
     static safeSpawn(command, args, options = {}) {
         // Command validation is now handled by TypeScript with AllowedCommand type
         const defaultOptions = {
+            // spawnSync blocks the event loop, so an unresponsive daemon hangs the
+            // whole CLI with no output and no error. SIGKILL because spawnSync's
+            // timeout otherwise sends SIGTERM and keeps waiting. Callers with
+            // legitimately long commands override via `options`.
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
             ...options,
             encoding: "utf8", // Always enforce utf8 encoding
         };
@@ -24,31 +41,42 @@ export class OllamaCommandFactory {
     /**
      * Create the Ollama command group
      */
+    /**
+     * Every handler is registered `.bind(this)`.
+     *
+     * yargs invokes the handler as a plain function, so a bare `this.xHandler`
+     * reference arrives with `this` unset and the first `this.safeSpawn(...)`
+     * throws `TypeError: this.safeSpawn is not a function`. That made EVERY
+     * subcommand here fail on its first line — list-models, pull, remove, status
+     * and stop all reported their generic "Failed to ..." message regardless of
+     * whether Ollama was installed or running, which is exactly why the real
+     * cause stayed hidden.
+     */
     static createOllamaCommands() {
         return {
             command: "ollama <command>",
             describe: "Manage Ollama local AI models",
             builder: (yargs) => {
                 return yargs
-                    .command("list-models", "List installed Ollama models", {}, this.listModelsHandler)
+                    .command("list-models", "List installed Ollama models", {}, this.listModelsHandler.bind(this))
                     .command("pull <model>", "Download an Ollama model", {
                     model: {
                         describe: "Model name to download",
                         type: "string",
                         demandOption: true,
                     },
-                }, this.pullModelHandler)
+                }, this.pullModelHandler.bind(this))
                     .command("remove <model>", "Remove an Ollama model", {
                     model: {
                         describe: "Model name to remove",
                         type: "string",
                         demandOption: true,
                     },
-                }, this.removeModelHandler)
-                    .command("status", "Check Ollama service status", {}, this.statusHandler)
-                    .command("start", "Start Ollama service", {}, this.startHandler)
-                    .command("stop", "Stop Ollama service", {}, this.stopHandler)
-                    .command("setup", "Interactive Ollama setup", {}, this.setupHandler)
+                }, this.removeModelHandler.bind(this))
+                    .command("status", "Check Ollama service status", {}, this.statusHandler.bind(this))
+                    .command("start", "Start Ollama service", {}, this.startHandler.bind(this))
+                    .command("stop", "Stop Ollama service", {}, this.stopHandler.bind(this))
+                    .command("setup", "Interactive Ollama setup", {}, this.setupHandler.bind(this))
                     .demandCommand(1, "Please specify a command");
             },
             handler: () => { }, // No-op handler as subcommands handle everything
@@ -89,8 +117,16 @@ export class OllamaCommandFactory {
         logger.always(chalk.blue(`Downloading model: ${model}`));
         logger.always(chalk.gray("This may take several minutes..."));
         try {
+            // A model pull is hundreds of megabytes and legitimately runs for many
+            // minutes, so it MUST opt out of safeSpawn's default query bound.
+            // Passing only `stdio` here is what made the first revision of this
+            // change kill downloads at 15s: the wrapper spreads `options` over its
+            // defaults, so an unmentioned `timeout` keeps the default rather than
+            // being absent. It inherits stdio, so the user sees progress and can
+            // interrupt it — the two things a wedged query lacks.
             const res = this.safeSpawn("ollama", ["pull", model], {
                 stdio: "inherit",
+                timeout: OLLAMA_NO_TIMEOUT,
             });
             if (res.error || res.status !== 0) {
                 throw res.error || new Error("pull failed");
@@ -211,25 +247,36 @@ export class OllamaCommandFactory {
      */
     static async stopHandler() {
         const spinner = ora("Stopping Ollama service...").start();
+        // `safeSpawn` RETURNS a result; it does not throw on a failed command. So
+        // the try/catch fallbacks that used to sit here never fired — `killall`
+        // and the pkill fallback were unreachable, and the handler reported
+        // "stopped" whatever happened. Bounding these calls made that worse rather
+        // than better: a timeout now yields `error: ETIMEDOUT` with `status: null`,
+        // which is still not a throw, so a wedged kill would be reported as a
+        // successful stop while Ollama stayed up.
+        //
+        // Branch on the result instead, which both restores the fallback and makes
+        // the success message conditional on something actually succeeding.
+        const ok = (r) => !r.error && r.status === 0;
         try {
+            let stopped;
             if (process.platform === "darwin") {
-                try {
-                    this.safeSpawn("pkill", ["ollama"]);
-                }
-                catch {
-                    this.safeSpawn("killall", ["Ollama"]);
-                }
+                stopped =
+                    ok(this.safeSpawn("pkill", ["ollama"])) ||
+                        ok(this.safeSpawn("killall", ["Ollama"]));
             }
             else if (process.platform === "linux") {
-                try {
-                    this.safeSpawn("systemctl", ["stop", "ollama"]);
-                }
-                catch {
-                    this.safeSpawn("pkill", ["ollama"]);
-                }
+                stopped =
+                    ok(this.safeSpawn("systemctl", ["stop", "ollama"])) ||
+                        ok(this.safeSpawn("pkill", ["ollama"]));
             }
             else {
-                this.safeSpawn("taskkill", ["/F", "/IM", "ollama.exe"]);
+                stopped = ok(this.safeSpawn("taskkill", ["/F", "/IM", "ollama.exe"]));
+            }
+            if (!stopped) {
+                spinner.fail("Could not confirm Ollama service stopped");
+                logger.error(chalk.red("No stop command succeeded — it may not have been running, or it may still be up. Check with: ollama list"));
+                return;
             }
             spinner.succeed("Ollama service stopped");
         }

package/dist/cli/parser.js

@@ -29,6 +29,7 @@ import { TaskCommandFactory } from "./commands/task.js";
 import { AutoresearchCommandFactory } from "./commands/autoresearch.js";
 import { voiceServerCommand } from "./commands/voiceServer.js";
 import { DocsCommandFactory } from "./commands/docs.js";
+import { UsageCommandFactory } from "./commands/usage.js";
 // Enhanced CLI with Professional UX
 export function initializeCliParser() {
     return (yargs(hideBin(process.argv))
@@ -156,6 +157,7 @@ export function initializeCliParser() {
         .command(CLICommandFactory.createGenerateCommand())
         // Docs MCP Server Command
         .command(DocsCommandFactory.createDocsCommand())
+        .command(UsageCommandFactory.createUsageCommands())
         // Stream Text Command - Using CLICommandFactory
         .command(CLICommandFactory.createStreamCommand())
         // Batch Processing Command - Using CLICommandFactory

package/dist/cli/utils/ollamaUtils.d.ts

@@ -8,6 +8,15 @@ export declare class OllamaUtils {
      * Secure wrapper around spawnSync to prevent command injection.
      */
     static safeSpawn(command: AllowedCommand, args: string[], options?: SpawnSyncOptions): SpawnSyncReturns<string>;
+    /**
+     * Whether a `safeSpawn` call actually succeeded.
+     *
+     * `spawnSync` reports failure by RETURNING — `error` set (ENOENT, ETIMEDOUT)
+     * or a non-zero `status` — never by throwing. Every `try/catch` around one of
+     * these calls was therefore dead code, which is why several fallbacks in this
+     * file had never run.
+     */
+    private static spawnSucceeded;
     /**
      * Check if Ollama command line is available
      */

package/dist/cli/utils/ollamaUtils.js

@@ -2,6 +2,32 @@ import { spawnSync, spawn, } from "child_process";
 import chalk from "chalk";
 import ora from "ora";
 import { logger } from "../../utils/logger.js";
+/**
+ * Ceiling for a synchronous Ollama query (`list`, `--version`, `rm`, …).
+ *
+ * `spawnSync` blocks the event loop, so an unresponsive daemon does not make
+ * the CLI slow — it makes it unkillable by anything short of Ctrl-C, with no
+ * output and no error. These calls are local IPC that normally answer in
+ * milliseconds, so a ceiling this generous only ever fires on a genuine wedge.
+ *
+ * `killSignal: "SIGKILL"` is not decoration. `spawnSync`'s `timeout` sends
+ * SIGTERM by default and then keeps waiting, so a child that ignores SIGTERM
+ * hangs forever anyway and the timeout buys nothing.
+ *
+ * Long-running commands (`ollama pull`) must pass their own `timeout` — the
+ * spread below lets a caller override this — because a model download
+ * legitimately runs for many minutes.
+ */
+const OLLAMA_QUERY_TIMEOUT_MS = 15_000;
+/**
+ * Ceiling for the whole readiness loop, not one probe inside it.
+ *
+ * Ollama normally answers within seconds of starting; a wait longer than this
+ * means it is not coming up, and continuing to spin helps nobody. Sized to
+ * outlast a slow cold start while staying far below the ~15 minutes that 30
+ * attempts of bounded probes could otherwise reach.
+ */
+const READINESS_DEADLINE_MS = 90_000;
 /**
  * Shared Ollama utilities for CLI commands
  */
@@ -11,11 +37,24 @@ export class OllamaUtils {
      */
     static safeSpawn(command, args, options = {}) {
         const defaultOptions = {
+            timeout: OLLAMA_QUERY_TIMEOUT_MS,
+            killSignal: "SIGKILL",
             ...options,
             encoding: "utf8", // Always enforce utf8 encoding
         };
         return spawnSync(command, args, defaultOptions);
     }
+    /**
+     * Whether a `safeSpawn` call actually succeeded.
+     *
+     * `spawnSync` reports failure by RETURNING — `error` set (ENOENT, ETIMEDOUT)
+     * or a non-zero `status` — never by throwing. Every `try/catch` around one of
+     * these calls was therefore dead code, which is why several fallbacks in this
+     * file had never run.
+     */
+    static spawnSucceeded(result) {
+        return !result.error && result.status === 0;
+    }
     /**
      * Check if Ollama command line is available
      */
@@ -70,7 +109,16 @@ export class OllamaUtils {
      */
     static async waitForOllamaReady(maxAttempts = 30, initialDelay = 500) {
         let delay = initialDelay;
+        // A per-call bound alone is not enough here, and adding one made this
+        // worse before it made it better: each attempt can now burn the full
+        // command bound plus the API bound, so 30 attempts is up to ~15 minutes of
+        // spinner rather than the seconds this loop was written to take. The
+        // per-attempt bound stops one wedged call; this stops the loop around it.
+        const deadline = Date.now() + READINESS_DEADLINE_MS;
         for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            if (Date.now() >= deadline) {
+                return false;
+            }
             try {
                 // Try command line check first
                 if (!this.isOllamaCommandReady()) {
@@ -117,11 +165,17 @@ export class OllamaUtils {
         try {
             if (process.platform === "darwin") {
                 logger.always(chalk.gray("Starting Ollama on macOS..."));
-                try {
-                    this.safeSpawn("open", ["-a", "Ollama"]);
+                // `safeSpawn` RETURNS a result; it does not throw on a failed command,
+                // so this catch only ever fired on a programming error and the
+                // `ollama serve` fallback beneath it was effectively unreachable.
+                // Bounding these calls made that worse: a timeout yields
+                // `error: ETIMEDOUT` with `status: null`, still not a throw, so a
+                // wedged launcher would have been reported as a successful start.
+                // Branch on the result so the fallback actually runs.
+                if (this.spawnSucceeded(this.safeSpawn("open", ["-a", "Ollama"]))) {
                     logger.always(chalk.green("✅ Ollama app started"));
                 }
-                catch {
+                else {
                     const child = spawn("ollama", ["serve"], {
                         stdio: "ignore",
                         detached: true,
@@ -135,11 +189,10 @@ export class OllamaUtils {
             }
             else if (process.platform === "linux") {
                 logger.always(chalk.gray("Starting Ollama service on Linux..."));
-                try {
-                    this.safeSpawn("systemctl", ["start", "ollama"]);
+                if (this.spawnSucceeded(this.safeSpawn("systemctl", ["start", "ollama"]))) {
                     logger.always(chalk.green("✅ Ollama service started"));
                 }
-                catch {
+                else {
                     const child = spawn("ollama", ["serve"], {
                         stdio: "ignore",
                         detached: true,
@@ -156,11 +209,16 @@ export class OllamaUtils {
                 // Security Note: Windows shell=true usage is intentional here for 'start' command.
                 // Arguments are controlled internally (no user input) and safeSpawn validates command names.
                 // This is safer than alternative Windows process creation methods for this specific use case.
-                this.safeSpawn("start", ["ollama", "serve"], {
+                const started = this.safeSpawn("start", ["ollama", "serve"], {
                     stdio: "ignore",
                     shell: true,
                 });
-                logger.always(chalk.green("✅ Ollama service started"));
+                if (this.spawnSucceeded(started)) {
+                    logger.always(chalk.green("✅ Ollama service started"));
+                }
+                else {
+                    logger.always(chalk.yellow("⚠️ Could not confirm Ollama started — check with: ollama list"));
+                }
             }
             // Wait for service to become ready with readiness probe
             const readinessSpinner = ora("Waiting for Ollama service to be ready...").start();

package/dist/localUsage/index.d.ts

@@ -6,7 +6,7 @@
  * a local transcript regardless, so reading those covers the rest — and covers
  * history from before the proxy existed.
  */
-import type { LocalUsageAggregateReport, LocalUsageScanOptions } from "../types/index.js";
+import type { LocalUsageAggregateOptions, LocalUsageAggregateReport } from "../types/index.js";
 export { createLocalUsageReader, getLocalUsageDescriptors, getRegisteredLocalUsageCliIds, registerLocalUsageReader, } from "./localUsageReaderRegistry.js";
 /**
  * Scan every registered reader whose CLI is actually present on this machine.
@@ -15,4 +15,4 @@ export { createLocalUsageReader, getLocalUsageDescriptors, getRegisteredLocalUsa
  * the user never installed is not an error, and collapsing the two would make
  * a broken reader indistinguishable from an absent one.
  */
-export declare function readAllLocalUsage(options?: LocalUsageScanOptions): Promise<LocalUsageAggregateReport>;
+export declare function readAllLocalUsage(options?: LocalUsageAggregateOptions): Promise<LocalUsageAggregateReport>;

package/dist/localUsage/index.js

@@ -19,7 +19,14 @@ export async function readAllLocalUsage(options) {
     const totals = {};
     const failures = [];
     const notInstalled = [];
-    for (const cliId of getRegisteredLocalUsageCliIds()) {
+    // Filtered BEFORE construction, not after: `only` decides which stores are
+    // opened at all. Reading all of them and discarding the rest cost 28s for a
+    // single-CLI query that needs 10.
+    const requested = options?.only;
+    const cliIds = requested
+        ? getRegisteredLocalUsageCliIds().filter((id) => requested.includes(id))
+        : getRegisteredLocalUsageCliIds();
+    for (const cliId of cliIds) {
         try {
             const reader = await createLocalUsageReader(cliId);
             if (!(await reader.detect())) {