vexp-cli 3.3.6 → 3.3.8

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/agent-config.js

@@ -13,7 +13,7 @@ import { spawnSync } from "child_process";
 import * as crypto from "crypto";
 import { canonicalWorkspaceRoot } from "./socket-path.js";
 import { readAgentConsent, consentKey, decisionForKey } from "./agent-consent.js";
-import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, codexWindowsHookCommand, opencodeFamilyAgent, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook, upperDriveLetter } from "./hook-template.js";
+import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSubagentHookScript, vexpSearchHookScript, vexpHintHookCmdScript, codexWindowsHookCommand, opencodeFamilyAgent, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook, upperDriveLetter } from "./hook-template.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -561,6 +561,7 @@ export function plannedWrites(agent, guard = guardMode(), interventions = interv
         case "Claude Code":
             out.push("~/.claude.json  (MCP server entry, user scope)");
             out.push(".claude/hooks/vexp-hint.sh + settings.json hooks.UserPromptSubmit  (orientation)");
+            out.push(".claude/hooks/vexp-subagent.sh + settings.json hooks.PreToolUse on Agent  (subagent orientation)");
             out.push(".claude/hooks/vexp-restore.sh + settings.json hooks.SessionStart  (context restore)");
             if (interventions === "on") {
                 out.push(".claude/hooks/vexp-verify.sh + settings.json hooks.Stop  (verification gate, opt-in)");
@@ -734,6 +735,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
             // Event-driven hint hook: default-on (non-blocking, fail-open — the
             // 2.3 A2 opt-in applies to DENY hooks, this one cannot block).
             const hintResult = installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeSubagentHook(workspaceRoot, binaryPath);
             installClaudeCodeSearchHook(workspaceRoot, binaryPath);
             // Both doors. Bounding either alone measured as no change at all: the
             // work simply moves to the other one.
@@ -1109,6 +1111,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
             installClaudeCodeHintHook(workspaceRoot, binaryPath);
+            installClaudeCodeSubagentHook(workspaceRoot, binaryPath);
             if (interventionMode() === "on") {
                 installClaudeCodeReadHint(workspaceRoot, binaryPath);
                 installClaudeCodeBashCap(workspaceRoot, binaryPath);
@@ -3045,8 +3048,9 @@ export function uninstallClaudeCodeHook(workspaceRoot) {
         const settings = read.data;
         const hooks = (settings.hooks ?? {});
         const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-        const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
-        if (filtered.length !== existingPreToolUse.length) {
+        // vexp's hooks out, a user's hook in their group kept (placeVexpHook).
+        const filtered = placeVexpHook(existingPreToolUse, isVexpGuardHookEntry, null);
+        if (JSON.stringify(filtered) !== JSON.stringify(existingPreToolUse)) {
             if (filtered.length > 0)
                 hooks.PreToolUse = filtered;
             else
@@ -3087,9 +3091,10 @@ export function installClaudeCodeHook(workspaceRoot) {
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    // Aggressively remove ALL vexp-related hook entries (old format, stale matchers, malformed)
-    const filtered = existingPreToolUse.filter((h) => !isVexpGuardHookEntry(h));
-    // Shell form with an explicit `bash` prefix and a QUOTED path — the one
+    // Aggressively remove ALL vexp-related hook entries (old format, stale
+    // matchers, malformed); ours goes where the first of them stood, and a
+    // user's hook in that group stays (placeVexpHook).
+    // Shell form with an explicit `sh` prefix and a QUOTED path — the one
     // shape that works on every OS Claude Code supports:
     //  - the quotes fix the historical spaces bug (unquoted
     //    `$CLAUDE_PROJECT_DIR/...` word-split and the guard never ran);
@@ -3097,15 +3102,20 @@ export function installClaudeCodeHook(workspaceRoot) {
     //    Windows entirely: the OS cannot spawn a `.sh` without a shell, the
     //    hook errored, failed open, and enforced nothing (field report) —
     //    Claude Code on Windows runs shell-form hooks through Git Bash, so
-    //    `bash "$VAR"` works there and on unix alike.
+    //    `sh "$VAR"` works there and on unix alike.
+    //  - `sh`, not the `bash` of earlier entries: Alpine (BusyBox) has no
+    //    bash, so every vexp hook failed there. On Windows Claude Code puts
+    //    Git Bash's folder first on PATH, and Git for Windows ships sh.exe
+    //    beside bash.exe, so `sh` resolves there and never to WSL's bash.exe.
+    //    An old `bash` entry is matched by its script name and replaced.
     // `timeout` is SECONDS (default 600), not ms: 3000 once configured a
     // 50-minute hook timeout.
-    filtered.push({
+    const placed = placeVexpHook(existingPreToolUse, isVexpGuardHookEntry, {
         matcher: "Grep|Glob|Regex",
         hooks: [
             {
                 type: "command",
-                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh"',
+                command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-guard.sh"',
                 timeout: 5,
             },
         ],
@@ -3113,7 +3123,7 @@ export function installClaudeCodeHook(workspaceRoot) {
     // Idempotence check AFTER the merge is computed: skip the write (and the
     // backup) only when settings already contain exactly the entry we would
     // write AND the script was already current.
-    const merged = { ...hooks, PreToolUse: filtered };
+    const merged = { ...hooks, PreToolUse: placed };
     const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
     if (scriptIdentical && settingsIdentical)
         return null;
@@ -3138,6 +3148,63 @@ function isVexpHookEntry(h, needle) {
         return hook.command?.includes(needle) ?? false;
     });
 }
+/**
+ * One event's groups with vexp's hook in them once, or with none of it when
+ * `ours` is null (an opt-in switched off). Every Claude Code installer and
+ * removal goes through here, so `isOurs` must answer for a group and for a
+ * hook object alike.
+ *
+ * A group holding only vexp's hooks is replaced where the first one stood,
+ * not moved to the end: the PreToolUse installers took theirs out and pushed
+ * it back last, so with two of them on they swapped places at every setup,
+ * each rewriting settings.json, with a backup, to undo the other; and an old
+ * `bash` entry went to the end of the list on its way to `sh`.
+ *
+ * A group that also holds someone else's hook keeps it. Claude Code's /hooks
+ * menu adds a hook to the group of a matcher that already exists, so a user
+ * who hooks Agent|Task, Bash or the prompt after setup lands inside vexp's
+ * group, and replacing the group whole deleted that hook at the next setup,
+ * and from the extension at every VS Code start (review, 2026-10-24). In such
+ * a group vexp's hook object is put back in its own slot while the group
+ * keeps vexp's matcher; under any other matcher, or when vexp's hook is being
+ * removed, it is taken out and the user's hooks stay where they were, so
+ * vexp's never fires on a matcher vexp did not choose.
+ *
+ * Keep in lockstep with the VS Code extension copy: both rewrite the same
+ * file, and a drift would move a user's hook back and forth between them.
+ */
+function placeVexpHook(existing, isOurs, ours) {
+    const placed = [];
+    let done = ours === null;
+    for (const h of existing) {
+        if (!isOurs(h)) {
+            placed.push(h);
+            continue;
+        }
+        const entry = h;
+        const inner = Array.isArray(entry.hooks) ? entry.hooks : [];
+        const theirs = inner.filter((x) => !isOurs(x));
+        if (theirs.length === 0) {
+            if (!done)
+                placed.push(ours);
+            done = true;
+        }
+        else if (!done && ours !== null && entry.matcher === ours.matcher && theirs.length < inner.length) {
+            const at = inner.findIndex(isOurs);
+            placed.push({
+                ...entry,
+                hooks: inner.flatMap((x, i) => (i === at ? ours.hooks : isOurs(x) ? [] : [x])),
+            });
+            done = true;
+        }
+        else {
+            placed.push({ ...entry, hooks: theirs });
+        }
+    }
+    if (!done)
+        placed.push(ours);
+    return placed;
+}
 /**
  * Horizon F2a: install the Stop-hook verification gate for Claude Code.
  * Same fail-open family as the hint hook: the Rust `stop-gate` command
@@ -3172,17 +3239,16 @@ export function installClaudeCodeSessionContext(workspaceRoot, binaryPath) {
     const existing = Array.isArray(hooks.SessionStart)
         ? hooks.SessionStart
         : [];
-    const filtered = existing.filter((h) => !isVexpHookEntry(h, "vexp-restore"));
-    filtered.push({
+    const placed = placeVexpHook(existing, (h) => isVexpHookEntry(h, "vexp-restore"), {
         hooks: [
             {
                 type: "command",
-                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-restore.sh"',
+                command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-restore.sh"',
                 timeout: 5,
             },
         ],
     });
-    const merged = { ...hooks, SessionStart: filtered };
+    const merged = { ...hooks, SessionStart: placed };
     const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
     if (scriptIdentical && settingsIdentical)
         return null;
@@ -3229,19 +3295,18 @@ export function installClaudeCodeStopGate(workspaceRoot, binaryPath) {
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existing = Array.isArray(hooks.Stop) ? hooks.Stop : [];
-    const filtered = existing.filter((h) => !isVexpHookEntry(h, "vexp-verify"));
-    // Cross-OS shape as everywhere: bash + QUOTED path; timeout in SECONDS.
-    if (gateOn) {
-        filtered.push({
+    // Cross-OS shape as everywhere: sh + QUOTED path; timeout in SECONDS.
+    const filtered = placeVexpHook(existing, (h) => isVexpHookEntry(h, "vexp-verify"), gateOn
+        ? {
             hooks: [
                 {
                     type: "command",
-                    command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-verify.sh"',
+                    command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-verify.sh"',
                     timeout: 15,
                 },
             ],
-        });
-    }
+        }
+        : null);
     const merged = { ...hooks, Stop: filtered };
     if (filtered.length === 0)
         delete merged.Stop;
@@ -3285,13 +3350,9 @@ function isVexpHintHookEntry(h) {
  * opt-in applies to DENY hooks, which add a failure mode; this one cannot
  * block anything).
  */
-/** Does this PreToolUse entry belong to us? */
+/** Does this PreToolUse entry, or hook object in one, belong to us? Both, for placeVexpHook. */
 function isVexpSearchHookEntry(h) {
-    if (!h || typeof h !== "object")
-        return false;
-    const hks = h.hooks;
-    return Array.isArray(hks) && hks.some((hook) => typeof hook?.command === "string" &&
-        hook.command.includes("vexp-search"));
+    return isVexpHookEntry(h, "vexp-search");
 }
 /**
  * v4 M1: install the search answer as a PreToolUse hook on Bash.
@@ -3342,8 +3403,8 @@ function removeClaudeCodePreToolHooks(workspaceRoot) {
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    const filtered = existing.filter((h) => !/vexp-(read-hint|bash-cap)/.test(JSON.stringify(h)));
-    if (filtered.length === existing.length)
+    const filtered = placeVexpHook(existing, (h) => /vexp-(read-hint|bash-cap)/.test(JSON.stringify(h ?? "")), null);
+    if (JSON.stringify(filtered) === JSON.stringify(existing))
         return;
     const merged = { ...hooks, PreToolUse: filtered };
     if (filtered.length === 0)
@@ -3369,20 +3430,20 @@ function installClaudeCodePreToolHook(workspaceRoot, binaryPath, name, matcher,
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    const filtered = existing.filter((h) => !JSON.stringify(h).includes(`vexp-${name}`));
     // Shell form with a quoted path: exec form cannot run a .sh on Windows, and
-    // an unquoted path word-splits on "C:\\Program Files" (c4a0b9e).
-    filtered.push({
+    // an unquoted path word-splits on "C:\\Program Files" (c4a0b9e). In place,
+    // beside the other PreToolUse installers (placeVexpHook).
+    const placed = placeVexpHook(existing, (h) => JSON.stringify(h ?? "").includes(`vexp-${name}`), {
         matcher,
         hooks: [
             {
                 type: "command",
-                command: `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-${name}.sh"`,
+                command: `sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-${name}.sh"`,
                 timeout: 10,
             },
         ],
     });
-    const merged = { ...hooks, PreToolUse: filtered };
+    const merged = { ...hooks, PreToolUse: placed };
     const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
     if (scriptIdentical && settingsIdentical)
         return null;
@@ -3415,21 +3476,21 @@ export function installClaudeCodeSearchHook(workspaceRoot, binaryPath) {
     const settings = read.data;
     const hooks = (settings.hooks ?? {});
     const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
-    const filtered = existing.filter((h) => !isVexpSearchHookEntry(h));
     // Same shell-form-with-quoted-path shape as every other hook we write: exec
     // form cannot run a .sh on Windows, and an unquoted path word-splits on
-    // "C:\Program Files" (both learned the hard way, c4a0b9e).
-    filtered.push({
+    // "C:\Program Files" (both learned the hard way, c4a0b9e). In place,
+    // beside the other PreToolUse installers (placeVexpHook).
+    const placed = placeVexpHook(existing, isVexpSearchHookEntry, {
         matcher: "Bash",
         hooks: [
             {
                 type: "command",
-                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-search.sh"',
+                command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-search.sh"',
                 timeout: 10,
             },
         ],
     });
-    const merged = { ...hooks, PreToolUse: filtered };
+    const merged = { ...hooks, PreToolUse: placed };
     const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
     if (scriptIdentical && settingsIdentical)
         return null;
@@ -3490,14 +3551,13 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     const existing = Array.isArray(hooks.UserPromptSubmit)
         ? hooks.UserPromptSubmit
         : [];
-    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
-    // Same cross-OS shape as the guard entry: bash prefix + QUOTED path
+    // Same cross-OS shape as the guard entry: sh prefix + QUOTED path
     // (spaces-safe on unix, Git Bash on Windows). timeout is SECONDS.
-    filtered.push({
+    const filtered = placeVexpHook(existing, isVexpHintHookEntry, {
         hooks: [
             {
                 type: "command",
-                command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-hint.sh"',
+                command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-hint.sh"',
                 // The prompt-hint client's budget ceiling (HINT_BUDGET_CEILING_MS,
                 // main.rs) stays under these 5 s: past them the agent kills the
                 // hook while the daemon still believes the client is waiting.
@@ -3512,19 +3572,18 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     const existingPost = Array.isArray(hooks.PostToolUse)
         ? hooks.PostToolUse
         : [];
-    const filteredPost = existingPost.filter((h) => !isVexpEditHintHookEntry(h));
-    if (couplingOn) {
-        filteredPost.push({
+    const filteredPost = placeVexpHook(existingPost, isVexpEditHintHookEntry, couplingOn
+        ? {
             matcher: "Edit|Write|NotebookEdit",
             hooks: [
                 {
                     type: "command",
-                    command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-edit-hint.sh"',
+                    command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-edit-hint.sh"',
                     timeout: 5,
                 },
             ],
-        });
-    }
+        }
+        : null);
     const merged = {
         ...hooks,
         UserPromptSubmit: filtered,
@@ -3545,6 +3604,65 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     }
     return existed ? "updated" : "created";
 }
+function isVexpSubagentHookEntry(h) {
+    return JSON.stringify(h ?? "").includes("vexp-subagent");
+}
+/**
+ * The subagent orientation hook (see VEXP_SUBAGENT_HOOK): PreToolUse on
+ * Agent, and on Task, the tool's old name, which Claude Code still matches.
+ * Default-on like the prompt hook and for the same reason: it cannot block
+ * (the script always exits 0 and sets no permissionDecision) and it adds no
+ * turn, only text in the subagent's first message. Installed wherever the
+ * prompt hook is. Keep in lockstep with the VS Code extension copy: same
+ * script, same entry.
+ *
+ * The script and its registration go together: a settings.json we cannot
+ * read stops both, where the older installers still write a script nothing
+ * runs. vexp's entry is replaced where it stands, and a user's hook in its
+ * Agent|Task group stays (placeVexpHook).
+ */
+export function installClaudeCodeSubagentHook(workspaceRoot, binaryPath) {
+    const hookDir = path.join(workspaceRoot, ".claude", "hooks");
+    const hookPath = path.join(hookDir, "vexp-subagent.sh");
+    const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
+    const script = vexpSubagentHookScript(binaryPath);
+    const read = readJsonConfigSafe(settingsPath);
+    if (!read.ok) {
+        warnUnparseable(settingsPath);
+        return null;
+    }
+    fs.mkdirSync(hookDir, { recursive: true });
+    const existed = fs.existsSync(hookPath);
+    const scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
+    if (!scriptIdentical)
+        fs.writeFileSync(hookPath, script, { mode: 0o755 });
+    const settings = read.data;
+    const hooks = (settings.hooks ?? {});
+    const existing = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+    // Same cross-OS shape as every other hook: sh prefix + QUOTED path.
+    // timeout is SECONDS, the prompt hook's: the same daemon call answers both.
+    const ours = {
+        matcher: "Agent|Task",
+        hooks: [
+            {
+                type: "command",
+                command: 'sh "$CLAUDE_PROJECT_DIR/.claude/hooks/vexp-subagent.sh"',
+                timeout: 5,
+            },
+        ],
+    };
+    const merged = { ...hooks, PreToolUse: placeVexpHook(existing, isVexpSubagentHookEntry, ours) };
+    const settingsIdentical = JSON.stringify(merged) === JSON.stringify(settings.hooks ?? {});
+    if (scriptIdentical && settingsIdentical)
+        return null;
+    settings.hooks = merged;
+    if (!settingsIdentical) {
+        if (read.existed)
+            backupConfig(settingsPath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    }
+    return existed ? "updated" : "created";
+}
 /**
  * opencode/Kilo hint plugin (2.4.0): default-ON, non-blocking, fail-open —
  * unlike the deny guard (strict-only), this cannot break a session; it only
@@ -3651,7 +3769,11 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
         ? codexHooks.UserPromptSubmit
         : [];
     const existing = [...wrapped, ...legacyTopLevel];
-    // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution.
+    // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution. And
+    // `bash`, not the `sh` of the Claude Code entries: Codex hashes its trust
+    // record over this line (codex-trust.ts codexHookHash), so a change would
+    // make every Codex user approve the hook again. The script it runs is
+    // POSIX sh all the same, and a new script needs no new approval.
     const ours = {
         hooks: [
             {
@@ -4054,7 +4176,10 @@ export function uninstallCursorHook(workspaceRoot) {
  * So this keeps only the three things a schema cannot carry:
  *
  *   1. WHEN to call, and when not to - the schema says what a tool returns,
- *      not whether this task wants it.
+ *      not whether this task wants it. Only run_pipeline is skippable: every
+ *      seeded prompt, a subagent's included, names its files, and the old
+ *      "SKIP vexp" then told the agent to drop verify_done and get_skeleton
+ *      along with it.
  *   2. The two guardrails that stop wasted calls: text sweeps belong to
  *      native search, and the index covers repo source only (logs, dist/,
  *      node_modules are not in it - read those directly).
@@ -4064,7 +4189,7 @@ export function uninstallCursorHook(workspaceRoot) {
  * mcp_stdio.rs for the same argument applied one layer down.
  */
 const MANDATE_CORE = `### Context strategy: call run_pipeline ONCE at task start
-If the task already names the files/symbols to touch, SKIP vexp. Otherwise one
+If the task already names the files/symbols to touch, skip run_pipeline. Otherwise one
 \`run_pipeline({ "task": "..." })\` returns ranked pivot files with line ranges and
 blast radius. Do NOT open files one by one to find your way around - every extra
 tool call costs a turn. Call it again ONLY when the task moves to a new area.

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];