vexp-cli 3.2.4 → 3.3.0

package/dist/agent-config.js

@@ -11,7 +11,9 @@ import * as path from "path";
 import * as os from "os";
 import { spawnSync } from "child_process";
 import * as crypto from "crypto";
-import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook } from "./hook-template.js";
+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";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -39,7 +41,9 @@ const CANONICAL_VEXP_TOML_SECTION_RE = /\n?\[mcp_servers\.vexp(?:\.[a-z_]+)?\][\
  * MUST stay in lockstep with that function.
  */
 function workspaceHash(workspaceRoot) {
-    const input = workspaceRoot.toLowerCase();
+    // The route hash must name the row the daemon registers: its canonical
+    // root, which on a mapped drive is the share, not the drive letter.
+    const input = canonicalWorkspaceRoot(workspaceRoot).toLowerCase();
     let hash = BigInt("0xcbf29ce484222325");
     const prime = BigInt("0x100000001b3");
     const mask = BigInt("0xffffffffffffffff");
@@ -113,10 +117,29 @@ export function interventionMode() {
 // ---------------------------------------------------------------------------
 // Agent detectors - mirrors VS Code extension's AGENT_DETECTORS
 // ---------------------------------------------------------------------------
+/**
+ * What Codex itself leaves under `~/.codex`: the login, the session store,
+ * the history. Any one of them means Codex has run on this machine. The
+ * folder alone does not: configureCodexGlobal creates it for config.toml.
+ * Lockstep with the extension.
+ */
+function codexHomeArtefacts() {
+    // CODEX_HOME is where Codex keeps all of it when set (Codex's documented
+    // relocation); the home folder alone missed such a user, and the
+    // extension's orphan sweep then took his working hooks for leftovers.
+    const codexHome = process.env.CODEX_HOME ? path.resolve(process.env.CODEX_HOME) : path.join(os.homedir(), ".codex");
+    return ["auth.json", "sessions", "session_index.jsonl", "history.jsonl", "installation_id", "version.json"].map((f) => path.join(codexHome, f));
+}
 const AGENT_DETECTORS = [
     {
         agent: "Claude Code",
         detectPath: ".claude",
+        // Machine marker: the ~/.claude DIRECTORY, which only Claude Code
+        // creates. Never ~/.claude.json — configureClaudeCodeGlobal writes that
+        // file itself, so it would keep Claude Code "found" forever. Without a
+        // machine marker the one tool a user had needed Setup Agents while two
+        // he did not have were set up on their own (field report, 2026-09-24).
+        detectHome: ".claude",
         configFile: ".claude/CLAUDE.md",
         templateName: "claude-code",
         // MCP configured in ~/.claude.json (user-scope) via configureClaudeCodeGlobal()
@@ -182,7 +205,19 @@ const AGENT_DETECTORS = [
     },
     {
         agent: "Codex",
-        detectPath: "AGENTS.md",
+        // Codex's own footprint: the login, sessions and history it keeps under
+        // `~/.codex` (see codexHomeArtefacts), or a project-level config Codex
+        // itself keeps. Nothing vexp writes is a marker: not AGENTS.md (written
+        // for Antigravity, opencode and ZCode too), not the `.codex/` folder our
+        // hooks.json lands in, and not `~/.codex` itself, which
+        // configureCodexGlobal creates for its config.toml; any of those would
+        // keep Codex "detected" forever on a machine that never had it (field
+        // report, 2026-09-24). The ~/.codex footprint is a machine-only marker:
+        // it says Codex ran on this PC weeks ago, not that this project uses it,
+        // so it gets Codex set up here only once the user says so
+        // (planAgentSetup). Lockstep with the extension.
+        detectPath: ".codex/config.toml",
+        detectAbsPaths: codexHomeArtefacts,
         configFile: "AGENTS.md",
         templateName: "agents-md",
         // MCP configured in ~/.codex/config.toml (global) via configureCodexGlobal()
@@ -263,13 +298,152 @@ const AGENT_DETECTORS = [
         // same mandate every AGENTS.md agent gets, under a name of its own. It
         // connects to vexp on its side, so there is no MCP file to write here:
         // the instructions are the whole integration. Detected by the file
-        // itself, as Codex is by AGENTS.md.
+        // itself (Codex, by contrast, by its own ~/.codex footprint).
         agent: "Friday Code",
         detectPath: "friday.md",
         configFile: "friday.md",
         templateName: "agents-md",
     },
 ];
+/**
+ * Every file vexp writes as an agent's instructions. As a detection marker
+ * such a file proves only that vexp ran here: a `.clinerules` written because
+ * Cline's VS Code storage exists "detected" Cline in that project at every
+ * start after, the loop AGENTS.md closed for Codex through 3.2.5. It counts
+ * only when someone put content of their own in it.
+ */
+const VEXP_WRITTEN_MARKERS = new Set(AGENT_DETECTORS.map((d) => d.configFile));
+/** `text` without vexp's `<!-- vexp ... -->` … `<!-- /vexp -->` block (to
+ *  the end of the file for the old unterminated format). */
+function withoutVexpSection(text) {
+    const m = VEXP_MARKER_RE.exec(text);
+    if (!m)
+        return text;
+    let start = m.index;
+    while (start > 0 && text[start - 1] !== "\n")
+        start--;
+    const endIdx = text.indexOf(VEXP_MARKER_END, m.index);
+    const end = endIdx === -1 ? text.length : endIdx + VEXP_MARKER_END.length;
+    return text.slice(0, start) + text.slice(end);
+}
+/** Does a vexp-written marker hold anything of the user's? Unreadable counts
+ *  as yes: when in doubt, detection behaves as it always did. */
+function hasOwnContent(p) {
+    let st;
+    try {
+        st = fs.statSync(p);
+    }
+    catch {
+        return false;
+    }
+    if (st.isDirectory()) {
+        // appendOrCreate writes `<dir>/vexp.md` when the target is a directory.
+        let entries;
+        try {
+            entries = fs.readdirSync(p);
+        }
+        catch {
+            return true;
+        }
+        return entries.some((e) => e !== "vexp.md" || hasOwnContent(path.join(p, e)));
+    }
+    try {
+        return withoutVexpSection(fs.readFileSync(p, "utf-8")).trim() !== "";
+    }
+    catch {
+        return true;
+    }
+}
+function isDirectory(p) {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Where `d` is found for this workspace, if anywhere. */
+export function classifyAgent(d, workspaceRoot) {
+    const markers = [d.detectPath, ...(d.detectPaths ?? [])];
+    const inProject = markers.some((m) => {
+        const p = path.join(workspaceRoot, m);
+        if (!fs.existsSync(p))
+            return false;
+        return !VEXP_WRITTEN_MARKERS.has(m) || hasOwnContent(p);
+    });
+    if (inProject)
+        return "project";
+    if (d.detectHome && isDirectory(path.join(os.homedir(), d.detectHome)))
+        return "machine";
+    if (d.detectAbsPaths && d.detectAbsPaths().some((p) => fs.existsSync(p)))
+        return "machine";
+    return undefined;
+}
+/** Every agent found for this workspace, in detector order. */
+export function classifyAgents(workspaceRoot) {
+    const out = [];
+    for (const d of AGENT_DETECTORS) {
+        const kind = classifyAgent(d, workspaceRoot);
+        if (kind)
+            out.push({ agent: d.agent, kind });
+    }
+    return out;
+}
+/**
+ * What a setup does without asking. Project markers and earlier "yes"
+ * answers are configured as they always were; traces on the machine alone
+ * (Codex's login, Antigravity's folder, Cline's storage, ~/.claude) wait for
+ * the user. Nothing vexp wrote counts as an answer: a 3.2.5 user whose Codex
+ * setup came from AGENTS.md is asked once, like everyone else.
+ */
+export function planAgentSetup(workspaceRoot, consent = readAgentConsent()) {
+    const plan = { configure: [], offer: [], declined: [], kinds: {} };
+    const key = consentKey(workspaceRoot);
+    for (const d of AGENT_DETECTORS) {
+        const kind = classifyAgent(d, workspaceRoot);
+        if (kind)
+            plan.kinds[d.agent] = kind;
+        const decision = decisionForKey(consent, key, d.agent);
+        if (kind === "project" || decision === "yes")
+            plan.configure.push(d.agent);
+        else if (kind === "machine")
+            (decision === "no" || decision === "never" ? plan.declined : plan.offer).push(d.agent);
+    }
+    return plan;
+}
+/** The command that configures `agents` here and does nothing else: `vexp
+ *  setup` without --no-index indexes the project again first. */
+export function setupAgentsCommand(agents, dir) {
+    return `vexp setup ${dir ? `"${dir}" ` : ""}--no-index --agents "${agents.join(",")}"`;
+}
+/**
+ * `vexp setup` with no one at the keyboard (an agent following doctor's
+ * advice, a script): the agents it sets up, the lines it prints about the
+ * ones it leaves alone, and whether it found no agent at all, the one case
+ * that exits 1. It used to exit 1 also when every agent found was only on
+ * the machine and waiting for a choice, right after naming the command that
+ * adds them, and that command indexed the project again (review of the
+ * 2026-09-24 fix). A tool waiting for a choice, or declined, is left alone
+ * as the user wants: nothing to configure then is no failure.
+ */
+export function nonInteractiveAgentChoice(plan, dir) {
+    const notes = [];
+    if (plan.offer.length > 0) {
+        notes.push(`Found on this machine, not set up for this project: ${plan.offer.join(", ")}.`);
+        notes.push(`To set ${plan.offer.length === 1 ? "it" : "them"} up here: ${setupAgentsCommand(plan.offer, dir)}`);
+    }
+    if (plan.configure.length === 0) {
+        if (plan.declined.length > 0)
+            notes.push(`Not set up, as answered earlier: ${plan.declined.join(", ")}.`);
+        if (plan.offer.length > 0 || plan.declined.length > 0)
+            notes.push("No agent set up for this project.");
+    }
+    return {
+        selected: [...plan.configure],
+        notes,
+        noAgentFound: plan.configure.length === 0 && plan.offer.length === 0 && plan.declined.length === 0,
+    };
+}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -306,8 +480,9 @@ export function plannedWrites(agent, guard = guardMode(), interventions = interv
             }
             break;
         case "Codex":
-            out.push("~/.codex/config.toml or .codex/config.toml  (MCP server entry)");
-            out.push(".codex/vexp-hint.sh + .codex/hooks.json hooks.UserPromptSubmit  (orientation)");
+            // Only the user config: the entry names no project, so one serves them all.
+            out.push("~/.codex/config.toml [mcp_servers.vexp]  (MCP server entry, machine-wide)");
+            out.push(`.codex/vexp-hint.sh${process.platform === "win32" ? " + .codex/vexp-hint.cmd" : ""} + .codex/hooks.json hooks.UserPromptSubmit  (orientation; approve it once in codex with /hooks)`);
             break;
         case "Cline":
             out.push("cline_mcp_settings.json in each installed VS Code variant  (MCP, machine-global)");
@@ -353,37 +528,29 @@ export function plannedWrites(agent, guard = guardMode(), interventions = interv
     return out;
 }
 /**
- * Detect which AI coding agents are present in the workspace.
+ * Detect which AI coding agents are present — in the workspace or, for the
+ * machine-only markers, on this machine (see classifyAgent).
  */
 export function detectAgents(workspaceRoot) {
-    return AGENT_DETECTORS.filter((d) => {
-        const markers = [d.detectPath, ...(d.detectPaths ?? [])];
-        if (markers.some((m) => fs.existsSync(path.join(workspaceRoot, m)))) {
-            return true;
-        }
-        // Home-level marker: the IDE is installed on this machine even though
-        // the workspace carries no footprint (e.g. Antigravity).
-        if (d.detectHome && fs.existsSync(path.join(os.homedir(), d.detectHome))) {
-            return true;
-        }
-        if (d.detectAbsPaths && d.detectAbsPaths().some((p) => fs.existsSync(p))) {
-            return true;
-        }
-        return false;
-    });
+    return AGENT_DETECTORS.filter((d) => classifyAgent(d, workspaceRoot) !== undefined);
 }
 /**
- * Configure all detected agents: write instruction files + MCP configs.
- * If `agentFilter` is provided, only configure those agents.
+ * Configure agents: write instruction files + MCP configs. With
+ * `agentFilter`, the detected agents it names; without, what
+ * planAgentSetup configures without asking.
  */
 export function configureAgents(workspaceRoot, binaryPath, version, agentFilter, mcpServerPath) {
     const results = [];
     const mcpConfigs = [];
     const writtenConfigFiles = new Set();
-    let agents = detectAgents(workspaceRoot);
+    let agents;
     if (agentFilter && agentFilter.length > 0) {
         const filter = agentFilter.map((a) => a.toLowerCase());
-        agents = agents.filter((d) => filter.includes(d.agent.toLowerCase()));
+        agents = detectAgents(workspaceRoot).filter((d) => filter.includes(d.agent.toLowerCase()));
+    }
+    else {
+        const plan = planAgentSetup(workspaceRoot);
+        agents = AGENT_DETECTORS.filter((d) => plan.configure.includes(d.agent));
     }
     for (const detected of agents) {
         const detector = withCursorTarget(detected, workspaceRoot);
@@ -470,7 +637,7 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         }
         // Claude Code: configure MCP in ~/.claude.json (user-scope, stdio)
         if (detector.agent === "Claude Code") {
-            const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
+            const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot, version);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
             // Event-driven hint hook: default-on (non-blocking, fail-open — the
@@ -847,7 +1014,7 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             removeDeadWindsurfMcpJson(workspaceRoot);
         }
         if (detector.agent === "Claude Code") {
-            const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
+            const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot, version);
             if (wrote)
                 mcpConfigs.push("~/.claude.json");
             installClaudeCodeHintHook(workspaceRoot, binaryPath);
@@ -1223,6 +1390,50 @@ export function isBareInterpreter(entry) {
 function adoptableEntry(entry) {
     return vexpEntryStillResolves(entry) && !isBareInterpreter(entry) && !isEditorExecutable(entry);
 }
+/**
+ * Is `recorded` strictly older than `mine`? Copy of the extension's
+ * isOlderVexpVersion (itself one of several: mcp-supervisor.ts carries the
+ * tests of the order). Unparseable is never older: such an entry is kept.
+ */
+function isOlderVexpVersion(recorded, mine) {
+    if (recorded === mine)
+        return false;
+    const parts = (v) => {
+        const nums = v.split("-")[0].split(".").map((n) => Number.parseInt(n, 10));
+        return nums.length === 3 && nums.every((n) => Number.isFinite(n)) ? nums : null;
+    };
+    const a = parts(recorded);
+    const b = parts(mine);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] < b[i];
+    }
+    return false;
+}
+/** The extension version an MCP entry points into (`vexp.vexp-vscode-3.2.5`,
+ *  with or without a platform suffix), or undefined when it is not one of
+ *  the extension's folders. Lockstep with the extension. */
+function vexpInstallVersion(entry) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    const e = entry;
+    const parts = [];
+    if (typeof e.command === "string")
+        parts.push(e.command);
+    if (Array.isArray(e.args)) {
+        for (const a of e.args)
+            if (typeof a === "string")
+                parts.push(a);
+    }
+    for (const p of parts) {
+        const m = p.match(/vexp\.vexp-vscode-(\d+\.\d+\.\d+)/);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
 function vexpEntryStillResolves(entry) {
     if (!entry || typeof entry !== "object")
         return false;
@@ -1350,6 +1561,38 @@ const unreachableTargets = [];
 export function takeUnreachableTargets() {
     return unreachableTargets.splice(0, unreachableTargets.length);
 }
+/**
+ * Projects whose Codex hook was written for the first time, or whose hook
+ * definition changed, in this run. Codex runs a project hook only once the
+ * user has approved that exact definition (a trust record in its own
+ * config.toml, keyed by the hook's position and hashed over its command);
+ * vexp never writes that record for them. Nothing in the project shows the
+ * hook is waiting for that, so the step has to be said where the hook was
+ * written.
+ */
+const codexHookApprovals = [];
+/** Drain the list of projects whose Codex hook needs the user's approval. */
+export function takeCodexHookApprovals() {
+    return codexHookApprovals.splice(0, codexHookApprovals.length);
+}
+/**
+ * The approval step, in the words the VS Code extension shows too
+ * (agent-auto-config.ts codexHookApprovalStep, lockstep-tested). ASCII only.
+ *
+ * Both places that approve a hook are named: the Codex extension for VS Code
+ * has its own Trust action (Settings > Hooks), and a terminal has /hooks. On
+ * Windows an approval in one does not reach the other: Codex keys the record
+ * by the folder as the session spells it, `C:\` in a terminal and `c:\` in
+ * the VS Code extension (codex.exe 0.155, hooks/list).
+ */
+export function codexHookApprovalStep(workspaceRoot, platform = process.platform) {
+    const step = "Codex runs vexp's orientation hook only after you approve it once. " +
+        "In the Codex extension for VS Code: open the Codex panel > Settings > Hooks and trust vexp-hint. " +
+        `In a terminal: run codex in ${workspaceRoot}, type /hooks and approve vexp-hint (trust the folder first if Codex asks).`;
+    return platform === "win32"
+        ? `${step} On Windows the two keep separate approvals (they spell the drive letter differently), so approve it in each one you use; 'vexp doctor' shows which have it.`
+        : `${step} 'vexp doctor' shows whether Codex has it approved.`;
+}
 /**
  * Cline keeps its MCP registry inside the VS Code extension's globalStorage,
  * so there is nothing to write until the extension has been installed once.
@@ -1942,6 +2185,10 @@ function readMcpPort(workspaceRoot) {
 // tell OUR config apart from a config the user hand-wrote. Must stay in sync
 // with packages/vexp-vscode/src/providers/agent-auto-config.ts.
 const CODEX_MANAGED_MARKER = "# vexp-managed";
+// What marks a section `vexp use --pin` pinned on purpose. Setup and every
+// VS Code start keep such a pin; only `vexp use` (another project, or
+// --unpin) changes it. Twin: agent-auto-config.ts.
+const CODEX_USE_PIN_MARK = "pinned by 'vexp use'";
 /** Quote a value as a TOML literal string (single quotes, no escaping) so
  *  Windows paths work verbatim. Falls back to a basic escaped string if the
  *  value contains a single quote. */
@@ -1979,6 +2226,13 @@ function codexDirectBinary(section) {
         return undefined;
     return cmd;
 }
+/** The project `vexp use --pin` pinned our section to, when it did. Twin: agent-auto-config.ts. */
+function explicitCodexPin(section) {
+    if (!section.includes(CODEX_MANAGED_MARKER) || !section.includes(CODEX_USE_PIN_MARK))
+        return undefined;
+    const m = /^\s*VEXP_WORKSPACE\s*=\s*(.+?)\s*$/m.exec(section);
+    return m ? parseTomlString(m[1]) : undefined;
+}
 function extractCodexVexpSection(content) {
     const m = content.match(CANONICAL_VEXP_TOML_SECTION_RE);
     return m ? m.join("\n") : "";
@@ -1999,6 +2253,19 @@ export function codexGlobalSectionIsUserManaged() {
     }
     return isUserManagedCodexSection(extractCodexVexpSection(content));
 }
+/** The project an explicit `vexp use --pin` pinned ~/.codex/config.toml's
+ *  vexp entry to, if it did. */
+export function codexGlobalExplicitPin() {
+    const home = os.homedir();
+    if (!home)
+        return undefined;
+    try {
+        return explicitCodexPin(extractCodexVexpSection(fs.readFileSync(path.join(home, ".codex", "config.toml"), "utf-8")));
+    }
+    catch {
+        return undefined;
+    }
+}
 /** True when the existing [mcp_servers.vexp] section was written by the user
  *  (not by vexp) and must NOT be overwritten. */
 function isUserManagedCodexSection(section) {
@@ -2015,7 +2282,19 @@ function isUserManagedCodexSection(section) {
     return false;
 }
 /** Build the canonical [mcp_servers.vexp] section for the chosen transport.
- *  Returns null for `direct` when no usable core binary is available. */
+ *  Returns null for `direct` when no usable core binary is available.
+ *
+ *  The direct section names no project unless `pinTo` says so: Codex starts a
+ *  stdio server per thread, in that thread's folder, and restarts it when the
+ *  folder changes (codex-rs rmcp-client stdio_server_launcher + codex-mcp
+ *  runtime, since openai/codex#19031, 2026-04), and `vexp-core mcp` finds the
+ *  project from there. The pin it carried until 3.2.5 named the project set
+ *  up LAST, so with two projects Codex queried the wrong index in one of
+ *  them. `pinTo` is `vexp use --pin`, on purpose. The http section keeps its
+ *  project: the URL routes to one workspace's daemon.
+ *
+ *  BYTE-IDENTICAL with the extension's buildCodexSection, marker lines
+ *  included, or the two rewrite this machine-wide file in turn. */
 function buildCodexSection(opts) {
     if (opts.transport === "direct") {
         if (!opts.coreBinaryPath)
@@ -2023,18 +2302,21 @@ function buildCodexSection(opts) {
         const lines = [
             "",
             "[mcp_servers.vexp]",
-            `${CODEX_MANAGED_MARKER}: direct transport (set VEXP_CODEX_TRANSPORT=http for the HTTP supervisor)`,
+            opts.pinTo
+                ? `${CODEX_MANAGED_MARKER}: direct transport, ${CODEX_USE_PIN_MARK} --pin (run 'vexp use --unpin' to follow each Codex session's folder again)`
+                : `${CODEX_MANAGED_MARKER}: direct transport, started in each Codex session's folder (VEXP_CODEX_TRANSPORT or the vexp.codexMcpTransport setting chooses the transport)`,
             `command = ${tomlString(opts.coreBinaryPath)}`,
-            // Pass --workspace explicitly (highest precedence in cmd_mcp) IN ADDITION to
-            // the env pin below, so a stale cwd / stale cached env can't drift the child
-            // to the wrong repo. JSON.stringify yields a TOML-valid quoted string array.
-            `args = ${opts.workspaceRoot ? JSON.stringify(["mcp", "--workspace", opts.workspaceRoot]) : '["mcp"]'}`,
+            // A pin passes --workspace explicitly (highest precedence in cmd_mcp)
+            // IN ADDITION to the env pin below, so a stale cwd / stale cached env
+            // can't drift the child to another repo. JSON.stringify yields a
+            // TOML-valid quoted string array.
+            `args = ${opts.pinTo ? JSON.stringify(["mcp", "--workspace", opts.pinTo]) : '["mcp"]'}`,
         ];
-        if (opts.workspaceRoot)
-            lines.push(`cwd = ${tomlString(opts.workspaceRoot)}`);
+        if (opts.pinTo)
+            lines.push(`cwd = ${tomlString(opts.pinTo)}`);
         lines.push("tool_timeout_sec = 120", "", "[mcp_servers.vexp.env]");
-        if (opts.workspaceRoot)
-            lines.push(`VEXP_WORKSPACE = ${tomlString(opts.workspaceRoot)}`);
+        if (opts.pinTo)
+            lines.push(`VEXP_WORKSPACE = ${tomlString(opts.pinTo)}`);
         if (opts.home)
             lines.push(`VEXP_HOME = ${tomlString(opts.home)}`);
         lines.push("");
@@ -2045,7 +2327,7 @@ function buildCodexSection(opts) {
     const desiredUrl = `http://127.0.0.1:${opts.mcpPort}${urlPath}`;
     return `
 [mcp_servers.vexp]
-${CODEX_MANAGED_MARKER}: http transport (set VEXP_CODEX_TRANSPORT=direct for stdio)
+${CODEX_MANAGED_MARKER}: http transport, routed to one project (VEXP_CODEX_TRANSPORT or the vexp.codexMcpTransport setting chooses the transport)
 url = "${desiredUrl}"
 tool_timeout_sec = 120
 
@@ -2055,16 +2337,30 @@ Authorization = "Bearer ${opts.token}"
 }
 /**
  * Configure MCP in ~/.codex/config.toml (global).
- * Codex only reads the global config, not project-level .codex/config.toml.
+ *
+ * Codex reads MCP servers from its user config and, for a project the user
+ * has trusted, from every `.codex/config.toml` between the project root and
+ * the session's folder, deep-merged over the user entry key by key
+ * (codex-rs config loader). vexp writes only the user file: a project file
+ * counts only once the project is trusted, a parse error in it stops Codex
+ * from loading its config at all, it is usually committed with this
+ * machine's paths in it, and Codex's "Always allow" would start writing
+ * into it. Nothing is lost by it: the direct entry names no project (see
+ * buildCodexSection), so one user entry serves every project.
  *
  * Default transport is `direct` (stdio: `vexp-core mcp`), which works with AND
  * without VS Code/daemon: `vexp-core mcp` auto-proxies to a running daemon when
  * reachable and otherwise runs an embedded in-process index. Override with the
  * VEXP_CODEX_TRANSPORT env var ("direct" | "http").
  *
+ * `pin` is `vexp use <project> --pin`: the one way to name a project in the entry,
+ * kept by every later setup until `vexp use` changes it. `unpin` is
+ * `vexp use --unpin`. [mcp_servers.vexp.tools.*] tables (Codex's per-tool
+ * approvals) are never touched.
+ *
  * Never clobbers a config the user wrote by hand.
  */
-export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot) {
+export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot, opts = {}) {
     const home = os.homedir();
     if (!home)
         return false;
@@ -2102,13 +2398,14 @@ export function configureCodexGlobal(binaryPath, _mcpServerPath, workspaceRoot)
     // Step 2b: adopt the binary a previous install already pinned here, when it
     // still exists. Our own sections are not "user-managed", so `vexp setup` and
     // every IDE activation rewrote this file with their own binary path — and the
-    // file is machine-global while Codex is detected by AGENTS.md, so it churned
-    // for every project at once. Adopting rather than skipping is what keeps this
-    // safe: the binary is interchangeable, but the workspace pin below is not and
-    // must still follow the project being configured. See the twin comment in
+    // file is machine-global, so it churned for every project at once. The
+    // binary is interchangeable; adopting it keeps the section byte-identical
+    // whoever writes it. See the twin comment in
     // vexp-vscode/src/providers/agent-auto-config.ts.
     const coreBinaryPath = (transport === "direct" ? codexDirectBinary(existingSection) : undefined) ?? ourCoreBinary;
-    const newSection = buildCodexSection({ transport, coreBinaryPath, workspaceRoot, mcpPort, token, home });
+    // A pin `vexp use --pin` made stays until `vexp use` says otherwise.
+    const pinTo = opts.pin ? workspaceRoot : opts.unpin ? undefined : explicitCodexPin(existingSection);
+    const newSection = buildCodexSection({ transport, coreBinaryPath, workspaceRoot, pinTo, mcpPort, token, home });
     if (!newSection) {
         // direct requested but binary missing → preserve the existing section (only
         // persist any legacy cleanup we already did); never emit a url fallback.
@@ -2420,7 +2717,9 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
  * Configure vexp MCP in ~/.claude.json (user-scope) using the Rust binary.
  * Returns true if config was written/updated.
  */
-export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot) {
+export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot, 
+/** This install's version: an entry left by an OLDER extension is taken over. */
+version) {
     const home = os.homedir();
     if (!home)
         return false;
@@ -2458,8 +2757,19 @@ export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRo
     // pinning VEXP_WORKSPACE must be rewritten no matter whose it is, because
     // this file applies to EVERY project and the pin forces all parallel
     // sessions onto one daemon (the migration described above).
-    if (removed.length === 0 && prevEnv === undefined && vexpEntryStillResolves(existing))
-        return false;
+    //
+    // Ordered, not symmetric: an entry inside an OLDER vexp.vexp-vscode-<ver>
+    // folder still resolves right after an update, and keeping it meant
+    // Claude Code lost vexp the moment VS Code reaped that folder (seen on
+    // 3.2.5 machines still pointing at 3.2.4, 2026-09-24). Take over an older
+    // one, keep a newer one, and keep anything we cannot version (the npm
+    // CLI's own path, a custom launcher). Lockstep with the extension.
+    if (removed.length === 0 && prevEnv === undefined && vexpEntryStillResolves(existing)) {
+        const theirs = vexpInstallVersion(existing);
+        const ours = vexpInstallVersion({ command: desiredCommand, args: desiredArgs }) ?? version;
+        if (!theirs || !ours || !isOlderVexpVersion(theirs, ours))
+            return false;
+    }
     const servers = config.mcpServers ?? {};
     servers["vexp"] = {
         command: desiredCommand,
@@ -2972,7 +3282,7 @@ export function installClaudeCodeHintHook(workspaceRoot, binaryPath) {
     const hookDir = path.join(workspaceRoot, ".claude", "hooks");
     const hookPath = path.join(hookDir, "vexp-hint.sh");
     const settingsPath = path.join(workspaceRoot, ".claude", "settings.json");
-    const script = vexpHintHookScript(binaryPath);
+    const script = vexpHintHookScript(binaryPath, "claude-code");
     fs.mkdirSync(hookDir, { recursive: true });
     // v5: the edit-time coupling hook, written beside the prompt-time one -
     // but only when interventions are on. It is one of the two mechanisms that
@@ -3094,7 +3404,7 @@ export function installOpencodeCompressPlugin(workspaceRoot, binaryPath, pluginD
 }
 export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir) {
     const pluginPath = path.join(workspaceRoot, pluginDir, "vexp-hint.js");
-    const content = vexpOpencodeHintPlugin(binaryPath);
+    const content = vexpOpencodeHintPlugin(binaryPath, opencodeFamilyAgent(pluginDir));
     fs.mkdirSync(path.dirname(pluginPath), { recursive: true });
     const existed = fs.existsSync(pluginPath);
     if (existed && fs.readFileSync(pluginPath, "utf-8") === content)
@@ -3110,25 +3420,26 @@ export function installOpencodeHintPlugin(workspaceRoot, binaryPath, pluginDir)
  * Fail-open: missing bash/binary/daemon => no output => vanilla.
  */
 export function installCodexHintHook(workspaceRoot, binaryPath) {
-    const dir = path.join(workspaceRoot, ".codex");
+    // Codex has no project-dir variable, so the command names the script by
+    // its absolute path: spelled with the drive letter the extension uses
+    // too, or each installer rewrites what the other wrote (upperDriveLetter).
+    const dir = path.join(upperDriveLetter(workspaceRoot), ".codex");
     const hookPath = path.join(dir, "vexp-hint.sh");
     const hooksJsonPath = path.join(dir, "hooks.json");
-    const script = vexpHintHookScript(binaryPath);
+    const script = vexpHintHookScript(binaryPath, "codex");
     fs.mkdirSync(dir, { recursive: true });
     const existed = fs.existsSync(hookPath);
     let scriptIdentical = existed && fs.readFileSync(hookPath, "utf-8") === script;
     if (!scriptIdentical) {
         fs.writeFileSync(hookPath, script, { mode: 0o755 });
     }
-    // Windows gets a batch twin. Codex runs a hook command through
-    // `cmd.exe /C` (COMSPEC, codex-rs/hooks command_runner), so `bash "..."`
-    // reaches a shell that has never heard of bash: a user with neither Git
-    // Bash nor WSL got "bash not found" on every prompt and orientation was
-    // inert. Codex's own answer is `commandWindows`, an optional per-OS
-    // override on the command handler (openai/codex#22159, ~0.131, months
-    // before the version that requires the nested `hooks` shape we already
-    // write). Older builds ignore the field rather than reject the file —
-    // the handler is not deny_unknown_fields, unlike the top level.
+    // Windows gets a batch twin. `bash "..."` needs a bash, and a user with
+    // neither Git Bash nor WSL got "bash not found" on every prompt, so
+    // orientation was inert. Codex's own answer is `commandWindows`, an
+    // optional per-OS override on the command handler (openai/codex#22159,
+    // ~0.131, months before the version that requires the nested `hooks` shape
+    // we already write). Older builds ignore the field rather than reject the
+    // file — the handler is not deny_unknown_fields, unlike the top level.
     const cmdPath = path.join(dir, "vexp-hint.cmd");
     let cmdCommand;
     if (process.platform === "win32") {
@@ -3138,10 +3449,10 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
             fs.writeFileSync(cmdPath, cmdScript);
             scriptIdentical = false;
         }
-        // Quoted: Codex hands `cmd /C` the whole line wrapped in one more pair
-        // of quotes, and cmd then strips the outermost pair — which leaves this
-        // path quoted and therefore safe to contain spaces.
-        cmdCommand = `"${cmdPath}"`;
+        // Through `cmd /d /c call`, not the bare path: Codex runs the line in
+        // PowerShell by default, where a quoted path is only a string to print
+        // (codexWindowsHookCommand has the details).
+        cmdCommand = codexWindowsHookCommand(cmdPath);
     }
     let root = {};
     if (fs.existsSync(hooksJsonPath)) {
@@ -3177,9 +3488,8 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
         ? codexHooks.UserPromptSubmit
         : [];
     const existing = [...wrapped, ...legacyTopLevel];
-    const filtered = existing.filter((h) => !isVexpHintHookEntry(h));
     // Absolute path: Codex has no $CLAUDE_PROJECT_DIR substitution.
-    filtered.push({
+    const ours = {
         hooks: [
             {
                 type: "command",
@@ -3188,11 +3498,16 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
                 timeout: 5,
             },
         ],
-    });
+    };
+    const merged = placeCodexHintEntry(existing, ours);
     const before = JSON.stringify(root);
-    codexHooks.UserPromptSubmit = filtered;
+    codexHooks.UserPromptSubmit = merged;
     root.hooks = codexHooks;
     const identical = before === JSON.stringify(root);
+    if (codexHookDefinitionChanged(wrapped, merged, ours)) {
+        if (!codexHookApprovals.includes(workspaceRoot))
+            codexHookApprovals.push(workspaceRoot);
+    }
     if (scriptIdentical && identical)
         return null;
     if (!identical) {
@@ -3200,6 +3515,36 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     }
     return existed ? "updated" : "created";
 }
+/**
+ * vexp's UserPromptSubmit group, put where the previous one was.
+ *
+ * Codex keys a hook's trust record by its position in the event's list
+ * (`<hooks.json>:user_prompt_submit:<group>:<handler>`, codex-rs hooks
+ * hook_key). Removing our group and appending it at the end moved it whenever
+ * the user had a hook of their own after it: our key changed, and theirs
+ * shifted onto hashes recorded for other hooks, so every one of them read as
+ * modified and stopped running until approved again. In place, nothing moves.
+ * Twin: agent-auto-config.ts placeCodexHintEntry.
+ */
+export function placeCodexHintEntry(existing, ours) {
+    const at = existing.findIndex((h) => isVexpHintHookEntry(h));
+    const merged = existing.flatMap((h, i) => (i === at ? [ours] : isVexpHintHookEntry(h) ? [] : [h]));
+    if (at < 0)
+        merged.push(ours);
+    return merged;
+}
+/**
+ * Did writing `ours` change what Codex trusts: a first write, a different
+ * definition, or a different position? `before` is the list Codex read until
+ * now (the nested one; a legacy top-level list is not loaded by a Codex that
+ * reads hooks.json this way). Twin: agent-auto-config.ts.
+ */
+export function codexHookDefinitionChanged(before, after, ours) {
+    const was = before.findIndex((h) => isVexpHintHookEntry(h));
+    if (was < 0)
+        return true;
+    return was !== after.indexOf(ours) || JSON.stringify(before[was]) !== JSON.stringify(ours);
+}
 // ---------------------------------------------------------------------------
 // opencode plugin - blocks grep/glob (and shelled-out search) when the daemon
 // is healthy. opencode has no PreToolUse hook, but auto-loads plugins from