vexp-cli 3.3.4 → 3.3.7

package/README.md

@@ -60,6 +60,17 @@ vexp shield scan
 vexp doctor
 ```
 
+## Daemons and memory
+
+vexp runs one small daemon per project, started by your agent's first call. By default it runs until you stop it (`vexp stop`, or `vexp stop --all`). To have the daemons nobody is using stop on their own, add this to `~/.vexp/config.toml`:
+
+```toml
+[daemon]
+idle_timeout_minutes = 30
+```
+
+The next tool call or prompt starts the daemon again. `VEXP_IDLE_TIMEOUT_MINUTES` sets it for one daemon. A daemon the VS Code extension started for a window stops when that window closes. `vexp daemons` lists what is running, with each daemon's memory, and `vexp doctor` shows whether the setting is on.
+
 ## Supported agents
 
 Claude Code · Cursor · Windsurf · GitHub Copilot · OpenAI Codex · Zed · Continue.dev · Cline · Aider · Kiro · Kilo Code · opencode · Augment · Antigravity · ZCode · Friday Code

package/dist/cli.js

@@ -33,6 +33,23 @@ program
     .description("Vexp — Graph-RAG context engine for AI coding agents")
     .version(CLI_VERSION)
     .option("-i, --trace", "Verbose trace mode: print every step with timing (IPs/tokens redacted)");
+// The idle stop was only to be found by reading the binary (field report,
+// 2026-10-17). Said under the root help and under the commands that list
+// and stop daemons.
+const IDLE_STOP_HELP = `
+Daemons:
+  vexp runs one daemon per project. It runs until it is stopped (vexp stop, vexp stop --all),
+  or, with this setting, until it has gone unused that many minutes; the next tool call or
+  prompt starts it again:
+
+    # ~/.vexp/config.toml
+    [daemon]
+    idle_timeout_minutes = 30
+
+  VEXP_IDLE_TIMEOUT_MINUTES sets it for one daemon. A daemon an editor window started stops
+  with that window instead. vexp daemons lists them; vexp doctor says whether the setting is on.
+`;
+program.addHelpText("after", IDLE_STOP_HELP);
 // Propagate -i / --trace to spawned children via env var so subprocess
 // (daemon, MCP, serve) inherits the trace flag.
 if (isTraceEnabled()) {
@@ -599,6 +616,7 @@ program
     .command("daemons")
     .description("List every vexp daemon on this machine: which workspace holds each concurrent-workspace slot, version, process id, memory, index size, uptime")
     .option("--json", "Emit machine-readable JSON")
+    .addHelpText("after", IDLE_STOP_HELP)
     .action(async (opts) => {
     const binaryPath = ensureBinary();
     const args = ["daemons"];
@@ -673,6 +691,7 @@ program
     .command("stop [workspace]")
     .description("Stop the vexp daemon of a workspace (default: current directory), or with --all every daemon on this machine. Accepts any path shown by the concurrent-workspace cap message")
     .option("--all", "Stop every live vexp daemon on this machine, one after the other")
+    .addHelpText("after", IDLE_STOP_HELP)
     .action(async (workspace, opts) => {
     if (opts.all && workspace !== undefined) {
         console.error(`--all stops every daemon on this machine and takes no workspace: run 'vexp stop --all', or 'vexp stop "${workspace}"' for that one.`);
@@ -832,6 +851,7 @@ program
     .command("daemon-cmd <action>")
     .description("Manage the vexp daemon (start, stop, restart, status, logs)")
     .option("--follow", "Follow log output (with 'logs' action)")
+    .addHelpText("after", IDLE_STOP_HELP)
     .action(async (action, opts) => {
     const binaryPath = ensureBinary();
     const args = ["daemon-cmd", action];

package/dist/doctor.js

@@ -605,6 +605,42 @@ function withoutVexpCommands(line) {
         .filter((sentence) => !/[`']vexp /.test(sentence))
         .join(" ");
 }
+/** ~/.vexp/config.toml, under VEXP_HOME when that is set: where the engine reads it. */
+function configTomlPath() {
+    return path.join(vexpHome(), ".vexp", "config.toml");
+}
+/** Minutes as the setting gives them: whole, else seconds. */
+function spokenMinutes(minutes) {
+    return Number.isInteger(minutes) ? `${minutes} min` : `${Math.round(minutes * 60)} s`;
+}
+/**
+ * The idle stop, as the daemon that answered sees it (index_status
+ * `idle_stop`, 3.3.6 and later). The setting was only to be found by reading
+ * the binary (field report, 2026-10-17): doctor names it, on, off, or passed
+ * over for a window's daemon. Null for a daemon from before it.
+ */
+export function idleStopFinding(idle) {
+    if (!idle || typeof idle !== "object")
+        return null;
+    const st = idle;
+    const after = typeof st.after_minutes === "number" && st.after_minutes > 0 ? st.after_minutes : null;
+    if (after === null) {
+        return {
+            level: INFO,
+            message: `idle stop: off, so this daemon runs until it is stopped. To stop the daemons nobody uses, set [daemon] idle_timeout_minutes = 30 in ${configTomlPath()} ` +
+                `(or VEXP_IDLE_TIMEOUT_MINUTES for one daemon); the next tool call or prompt starts one again. A daemon an editor window started stops with that window instead.`,
+        };
+    }
+    if (st.editor_owned === true) {
+        return {
+            level: OK,
+            message: `idle stop: after ${spokenMinutes(after)} without use, but not this daemon: an editor window started it, and it stops when that window closes`,
+        };
+    }
+    const idleS = typeof st.idle_s === "number" ? st.idle_s : null;
+    const unused = idleS === null ? "" : idleS >= 60 ? ` (unused for ${Math.floor(idleS / 60)} min now)` : " (used in the last minute)";
+    return { level: OK, message: `idle stop: after ${spokenMinutes(after)} without use${unused}; the next tool call or prompt starts it again` };
+}
 /**
  * What doctor says when no daemon answers for this workspace.
  *
@@ -654,6 +690,18 @@ export function daemonDownFindings(o) {
             },
         ];
     }
+    // Stopped on purpose: idle_timeout_minutes. Nothing to restart by hand,
+    // and the marker goes as soon as a daemon starts here again.
+    const idle = (o.idleExit ?? "").split(/\r?\n/)[0].trim();
+    if (idle) {
+        return [
+            {
+                level: INFO,
+                message: `no daemon is running for this project (${o.sock}): it ${idle}.\n` +
+                    `        nothing to do: the next tool call or prompt starts it again. The setting is [daemon] idle_timeout_minutes in ${configTomlPath()}.`,
+            },
+        ];
+    }
     if (ext && !o.hasIndex) {
         return [
             {
@@ -1009,7 +1057,11 @@ export function partialParseVerdict(cov, coveragePath = ".vexp/coverage.json") {
     const files = list;
     const examples = files
         .slice(0, 5)
-        .map((f) => `${f.path} (${Number(f.lines) || 0} line(s) from line ${Number(f.first_line) || 0})`);
+        .map((f) => {
+        const broke = Number(f.broke_line) || 0;
+        const at = broke > 0 ? `, the reading broke at line ${broke}` : "";
+        return `${f.path} (${Number(f.lines) || 0} line(s) from line ${Number(f.first_line) || 0}${at})`;
+    });
     const more = files.length - examples.length;
     return {
         level: WARN,
@@ -3257,6 +3309,11 @@ async function doctorChecks(onWorkspace) {
             startBlocked = fs.readFileSync(path.join(ws.root, ".vexp", "start-blocked"), "utf-8");
         }
         catch { /* the last start was not refused */ }
+        let idleExit;
+        try {
+            idleExit = fs.readFileSync(path.join(ws.root, ".vexp", "idle-exit"), "utf-8");
+        }
+        catch { /* the last daemon did not stop for idleness */ }
         const what = notAProject(ws.root);
         const down = daemonDownFindings({
             sock,
@@ -3264,6 +3321,7 @@ async function doctorChecks(onWorkspace) {
             hasIndex: fs.existsSync(path.join(ws.root, ".vexp", "index.db")),
             startBlocked,
             outside: what ? { root: ws.root, what } : undefined,
+            idleExit,
         });
         closedInIde = down.every((f) => f.level === INFO);
         for (const f of down)
@@ -3303,6 +3361,9 @@ async function doctorChecks(onWorkspace) {
                     ? "loading (the model is still starting — this is not the rule compressor settling in)"
                     : st.compressor ?? "unknown (older daemon)";
             line(OK, `index: ${st.total_files ?? "?"} files · ${st.total_nodes ?? "?"} nodes · state ${st.status ?? "?"} · compressor ${comp}`);
+            const idleStop = idleStopFinding(st.idle_stop);
+            if (idleStop)
+                emit(idleStop);
             if (st.llm_configured_but_inactive === true) {
                 // The daemon knows WHY, and doctor was throwing it away: it printed
                 // the same "restart to load the model" the sidebar prints, to a user