vexp-cli 3.2.5 → 3.3.0

package/dist/cli.js

@@ -8,9 +8,11 @@ import * as fs from "fs";
 import * as net from "net";
 import { checkbox, confirm } from "@inquirer/prompts";
 import { getBinaryPath, getInstalledVersion, getMcpServerPath, binaryEnv } from "./binary.js";
-import { detectAgents, getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName, setGuardMode, setInterventionMode, plannedWrites, takeSkippedConfigs, takeUnreachableTargets } from "./agent-config.js";
+import { getAgentList, configureSelectedAgents, resolveAgentName, suggestAgentName, setGuardMode, setInterventionMode, plannedWrites, takeSkippedConfigs, takeUnreachableTargets, takeCodexHookApprovals, codexHookApprovalStep, planAgentSetup, nonInteractiveAgentChoice, setupAgentsCommand } from "./agent-config.js";
+import { recordAgentConsent } from "./agent-consent.js";
 import { CLI_VERSION } from "./version.js";
-import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocked, tryOnlineRefresh, } from "./license.js";
+import { deactivateLicense, readLicenseLimits, readDeviceBlocked, refreshFromDisk, } from "./license.js";
+import { runActivation, planLabel as licensePlanLabel, isLifetimePlan, printCheckInStatus, } from "./license-activate.js";
 import { checkForUpdate } from "./update-check.js";
 import { ensureMcpHttpServer, mcpHttpStatus } from "./mcp-supervisor.js";
 import { installAutostart, uninstallAutostart, autostartStatus, migrateClaudeUnpinIfNeeded } from "./autostart.js";
@@ -67,6 +69,13 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
         return;
     if (AUTOSTART_SKIP.has(actionCmd.name()))
         return;
+    // `capsule --explain` runs in the engine's own process, read-only, and
+    // promises to write nothing. Booting a daemon for it installed git hooks,
+    // wrote .vexp/.gitignore, synced the index and left a daemon running on a
+    // workspace whose daemon was down (review of the explain stream,
+    // 2026-09-25).
+    if (actionCmd.name() === "capsule" && (actionCmd.opts().explain ?? []).length > 0)
+        return;
     // Effective workspace: inside a connected secondary repo this resolves to
     // the parent, so we boot (or reuse) the parent daemon instead of spawning
     // a conflicting one for the child.
@@ -430,6 +439,10 @@ program
     .option("--repos <repos>", "Comma-separated repo aliases")
     .option("--max-tokens <n>", "Max tokens", "8000")
     .option("--format <fmt>", "Output format: text, json", "text")
+    .option("--explain <path>", "Follow a file through every stage of the retrieval and say where it left and why " +
+    "(never a candidate, not admitted, cut at the ten, under the floor, past the pivot cap, published at rank k). " +
+    "A repo-relative path, a path suffix, or a file name (every indexed file of that name). " +
+    "Repeatable. Writes nothing: the next real answer is unchanged", (value, previous) => previous.concat([value]), [])
     .action(async (query, opts) => {
     const binaryPath = ensureBinary();
     const args = ["capsule", query, "--max-tokens", opts.maxTokens];
@@ -438,6 +451,9 @@ program
     // The Rust binary's clap arg is `--format <json|markdown>` (there is no
     // `--json` flag). Map the CLI's "text"/"json" to the binary's vocabulary.
     args.push("--format", opts.format === "json" ? "json" : "markdown");
+    // One flag per file, in the order given: the binary expands a file name.
+    for (const p of opts.explain)
+        args.push("--explain", p);
     runBinary(binaryPath, args);
 });
 program
@@ -714,11 +730,40 @@ program
     .action(async (opts) => {
     await runDoctor({ report: opts.report });
 });
+/**
+ * How the agent lists name an agent. Pre-selected (●) are only the agents
+ * the project itself shows and the ones chosen for it before; a tool vexp
+ * finds only on this machine is labelled so and waits for a pick. Enter used
+ * to set up everything found, which put Codex and Antigravity into the
+ * project of a user who ran neither (field report, 2026-09-24).
+ */
+/**
+ * The one step vexp cannot take for the user: approving its Codex hook. Said
+ * whenever this run wrote the hook for the first time or changed its
+ * definition, because until then Codex does not run it
+ * (codexHookApprovalStep).
+ */
+function printCodexHookApprovals() {
+    for (const root of takeCodexHookApprovals()) {
+        console.log("");
+        console.log(chalk.yellow(`  ! ${codexHookApprovalStep(root)}`));
+    }
+}
+function agentMark(plan, agent) {
+    const pre = plan.configure.includes(agent);
+    const kind = plan.kinds[agent];
+    if (kind === "project")
+        return chalk.green(" ● detected");
+    if (kind === "machine") {
+        return pre ? chalk.green(" ● (found on this machine, chosen for this project)") : chalk.dim(" (found on this machine)");
+    }
+    return pre ? chalk.green(" ● (chosen for this project)") : "";
+}
 program
     .command("setup [dir]")
     .description("Complete one-command setup: index, detect agents, configure MCP")
     .option("--no-index", "Skip indexing (if already indexed)")
-    .option("--agents [list]", "Filter agents to configure (comma-separated). Without value: auto-detect all")
+    .option("--agents [list]", "Agents to configure (comma-separated). Without it: the ones this project shows, plus the ones chosen for it before")
     .option("--dry-run", "Show what would be configured without writing files")
     .option("--personal", "Personal mode: index locally without writing agent configs or git hooks to the shared repo")
     .option("--guard-strict", "Install the Grep/Glob deny hooks (opt-in since 2.3; default setup removes them)")
@@ -743,6 +788,9 @@ program
     }
     // Set once the agents are known: only editor-hosted ones need a restart.
     let editorHosted = false;
+    // Whether any agent was set up: a run that set up none must not end on
+    // "Your AI coding agents are configured".
+    let agentsWritten = false;
     const isPersonal = !!opts.personal;
     if (isPersonal) {
         console.log(chalk.cyan("  Personal mode: skipping agent configs and git hooks\n"));
@@ -783,9 +831,13 @@ program
     if (!isPersonal) {
         // Step 3: Select agents
         const allAgents = getAgentList();
-        const detected = detectAgents(workspaceRoot);
-        const detectedNames = new Set(detected.map((a) => a.agent));
+        const plan = planAgentSetup(workspaceRoot);
         let selectedNames;
+        // What the user picked (the flag, the list, Enter on the list) is
+        // remembered as "yes" for this project, so the extension sets up and
+        // refreshes the same agents instead of asking again. The non-TTY
+        // default is not a pick: nobody chose anything there.
+        let picked = false;
         if (typeof opts.agents === "string") {
             // Explicit list from --agents flag. Resolve every name BEFORE writing
             // anything: matching is exact downstream, so an unrecognised name used
@@ -805,6 +857,7 @@ program
                 process.exit(1);
             }
             selectedNames = requested.map((n) => resolveAgentName(n));
+            picked = true;
             console.log(chalk.dim(`  Agents (from flag): ${selectedNames.join(", ")}`));
         }
         else if (!process.stdin.isTTY) {
@@ -813,31 +866,39 @@ program
             // reading that line — cannot answer a prompt: it hangs until it is
             // killed, which is worse than failing (field report, 2026-09-07: a
             // tester followed doctor's advice and had to abandon the command).
-            // Configure what is detected, and say that is what happened.
-            selectedNames = allAgents.filter((a) => detectedNames.has(a.agent)).map((a) => a.agent);
-            if (selectedNames.length === 0) {
+            // Configure what the project shows (or was chosen for it), and say
+            // that is what happened. A tool found only on this machine is named,
+            // never set up: that default put Codex and Antigravity into the
+            // project of a user who ran neither (field report, 2026-09-24).
+            // Exit 1 only when no agent was found at all (nonInteractiveAgentChoice).
+            const choice = nonInteractiveAgentChoice(plan, dir);
+            selectedNames = choice.selected;
+            for (const note of choice.notes)
+                console.log(chalk.dim(`  ${note}`));
+            if (choice.noAgentFound) {
                 console.error(chalk.yellow("  No AI agent detected here and stdin is not a terminal — nothing to configure."));
-                console.error(chalk.dim("  Name them explicitly: vexp setup --agents \"Claude Code,Codex\""));
+                console.error(chalk.dim(`  Name them explicitly: ${setupAgentsCommand(["Claude Code", "Codex"], dir)}`));
                 process.exit(1);
             }
-            console.log(chalk.dim(`  Agents (detected, non-interactive): ${selectedNames.join(", ")}`));
+            if (selectedNames.length > 0) {
+                console.log(chalk.dim(`  Agents (detected, non-interactive): ${selectedNames.join(", ")}`));
+            }
         }
         else {
             // Interactive selection
             console.log(chalk.bold("\n  Select AI agents to configure:\n"));
             for (let i = 0; i < allAgents.length; i++) {
-                const isDetected = detectedNames.has(allAgents[i].agent);
-                const marker = isDetected ? chalk.green(" ● detected") : "";
-                console.log(`    ${chalk.cyan(String(i + 1).padStart(2))}. ${allAgents[i].agent}${marker}`);
+                console.log(`    ${chalk.cyan(String(i + 1).padStart(2))}. ${allAgents[i].agent}${agentMark(plan, allAgents[i].agent)}`);
             }
             const readline = await import("readline");
             const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-            const answer = await new Promise((resolve) => rl.question(chalk.cyan("\n  Select (numbers separated by spaces, Enter for detected): "), resolve));
+            const answer = await new Promise((resolve) => rl.question(chalk.cyan("\n  Select (numbers separated by spaces, Enter for the ● ones): "), resolve));
             rl.close();
             const trimmed = answer.trim();
+            picked = true;
             if (trimmed === "") {
-                // Enter with no input → use detected agents
-                selectedNames = detected.map((a) => a.agent);
+                // Enter with no input → the pre-selected agents
+                selectedNames = allAgents.filter((a) => plan.configure.includes(a.agent)).map((a) => a.agent);
                 if (selectedNames.length === 0) {
                     console.log(chalk.yellow("\n  No agents detected. Skipping agent configuration."));
                     console.log(chalk.dim("  Tip: run 'vexp setup-agents' to choose agents manually.\n"));
@@ -871,6 +932,10 @@ program
                 const version = (await getInstalledVersion()) ?? CLI_VERSION;
                 const mcpServerPath = getMcpServerPath();
                 const result = configureSelectedAgents(workspaceRoot, binaryPath, version, selectedNames, mcpServerPath);
+                if (picked)
+                    for (const name of selectedNames)
+                        recordAgentConsent(workspaceRoot, name, "yes");
+                agentsWritten = true;
                 spinner4.succeed("Agent configurations written");
                 // Only editor-hosted agents need the host restarted. Telling a
                 // Codex-only or Claude-Code-only user to restart VS Code invites
@@ -932,6 +997,7 @@ program
                     for (const f of unreachable)
                         console.log(chalk.yellow(`    ${f}`));
                 }
+                printCodexHookApprovals();
             }
         }
     }
@@ -997,7 +1063,7 @@ program
         console.log("MCP tools are available locally via your agent's user-scope config.");
     }
     else {
-        console.log("Your AI coding agents are configured to use vexp MCP tools.");
+        console.log(agentsWritten ? "Your AI coding agents are configured to use vexp MCP tools." : "No AI agent was set up for this project (see above).");
         console.log("The vexp daemon is running and ready to serve context.");
     }
     console.log("");
@@ -1026,18 +1092,16 @@ async function runSetupAgents(dir) {
     console.log(chalk.bold("  Setup AI Coding Agents"));
     console.log(chalk.dim("  Use ↑↓ to navigate, Space to toggle, Enter to confirm\n"));
     const agents = getAgentList();
+    // The same detection and answers `vexp setup` uses (see agentMark): an
+    // agent found only on this machine is shown, labelled, not pre-checked.
+    const plan = planAgentSetup(workspaceRoot);
     const selectedNames = await checkbox({
         message: "Select agents to configure",
-        choices: agents.map((a) => {
-            const detected = fs.existsSync(path.join(workspaceRoot, a.detectPath));
-            return {
-                name: detected
-                    ? `${a.agent} ${chalk.green("● detected")}`
-                    : a.agent,
-                value: a.agent,
-                checked: detected,
-            };
-        }),
+        choices: agents.map((a) => ({
+            name: `${a.agent}${agentMark(plan, a.agent)}`,
+            value: a.agent,
+            checked: plan.configure.includes(a.agent),
+        })),
         theme: { prefix: chalk.cyan("  ") },
     });
     if (selectedNames.length === 0) {
@@ -1047,6 +1111,8 @@ async function runSetupAgents(dir) {
     const spinner = ora("  Writing agent configurations...").start();
     const version = (await getInstalledVersion()) ?? CLI_VERSION;
     const result = configureSelectedAgents(workspaceRoot, binaryPath, version, selectedNames);
+    for (const name of selectedNames)
+        recordAgentConsent(workspaceRoot, name, "yes");
     spinner.succeed("Agent configurations written");
     console.log("");
     for (const agent of result.agents) {
@@ -1067,6 +1133,7 @@ async function runSetupAgents(dir) {
             console.log(chalk.dim(`    → ${mcpFile}`));
         }
     }
+    printCodexHookApprovals();
     console.log(chalk.green(`\n  ✓ ${result.agents.length} agent(s) configured\n`));
 }
 /** Full setup from REPL — reuses the existing readline to avoid stdin conflicts. */
@@ -1094,19 +1161,16 @@ async function runSetupInteractive(rl) {
     rl.resume();
     // Step 2: Select agents
     const allAgents = getAgentList();
-    const detected = detectAgents(workspaceRoot);
-    const detectedNames = new Set(detected.map((a) => a.agent));
+    const plan = planAgentSetup(workspaceRoot);
     console.log(chalk.bold("\n  Select AI agents to configure:\n"));
     for (let i = 0; i < allAgents.length; i++) {
-        const isDetected = detectedNames.has(allAgents[i].agent);
-        const marker = isDetected ? chalk.green(" ● detected") : "";
-        console.log(`    ${chalk.cyan(String(i + 1).padStart(2))}. ${allAgents[i].agent}${marker}`);
+        console.log(`    ${chalk.cyan(String(i + 1).padStart(2))}. ${allAgents[i].agent}${agentMark(plan, allAgents[i].agent)}`);
     }
-    const answer = await ask(rl, chalk.cyan("\n  Select (numbers separated by spaces, Enter for detected): "));
+    const answer = await ask(rl, chalk.cyan("\n  Select (numbers separated by spaces, Enter for the ● ones): "));
     const trimmed = answer.trim();
     let selectedNames;
     if (trimmed === "") {
-        selectedNames = detected.map((a) => a.agent);
+        selectedNames = allAgents.filter((a) => plan.configure.includes(a.agent)).map((a) => a.agent);
         if (selectedNames.length === 0) {
             console.log(chalk.yellow("\n  No agents detected. Skipping."));
             return;
@@ -1121,6 +1185,8 @@ async function runSetupInteractive(rl) {
     if (selectedNames.length > 0) {
         const version = (await getInstalledVersion()) ?? CLI_VERSION;
         const result = configureSelectedAgents(workspaceRoot, binaryPath, version, selectedNames);
+        for (const name of selectedNames)
+            recordAgentConsent(workspaceRoot, name, "yes");
         console.log("");
         for (const agent of result.agents) {
             const actionLabel = agent.action === "created" ? chalk.green("created")
@@ -1132,6 +1198,7 @@ async function runSetupInteractive(rl) {
         if (result.mcpConfigs.length > 0) {
             console.log(chalk.dim(`\n  MCP configs: ${result.mcpConfigs.join(", ")}`));
         }
+        printCodexHookApprovals();
         console.log(chalk.green(`\n  ✓ Setup complete — ${result.agents.length} agent(s) configured\n`));
     }
     // Login autostart — opt-in only. The daemon already cold-starts on demand,
@@ -1176,30 +1243,17 @@ program
             isTTY: process.stdin.isTTY === true,
         });
     }
-    try {
-        const claims = activateLicense(key.trim());
-        console.log(chalk.green("\n✓ License activated!"));
-        console.log(`  Plan:    ${claims.plan}`);
-        console.log(`  Email:   ${claims.sub}`);
-        console.log(`  Expires: ${new Date(claims.exp * 1000).toLocaleDateString()}`);
-        // Register this machine NOW, while the user is watching, instead of
-        // whenever a later command happens to fall outside the 24h refresh
-        // window. The dashboard tells people to "open vexp on any machine to
-        // register it" and activating IS that — a tier-4 user read 0 of 10
-        // devices immediately after activating and reasonably thought something
-        // had failed. Best effort by design: the refresh has its own short
-        // timeout and never throws, so an offline activation still succeeds and
-        // simply registers later.
-        try {
-            await tryOnlineRefresh(key.trim());
-        }
-        catch { /* offline or server down: registration happens on a later run */ }
-        console.log("");
-    }
-    catch (err) {
-        console.error(chalk.red(`✗ ${err instanceof Error ? err.message : err}`));
+    // Register this machine NOW, while the user is watching, and say whether
+    // it worked. The dashboard tells people to "open vexp on any machine to
+    // register it" and activating IS that — a tier-4 user read 0 of 10
+    // devices immediately after activating and reasonably thought something
+    // had failed. An offline activation still succeeds and registers later;
+    // the line printed says which of the two happened. Same helper as the
+    // interactive menu, so the two can never drift apart again.
+    const report = await runActivation(key, { indent: "" });
+    console.log("");
+    if (!report.ok)
         process.exit(1);
-    }
 });
 program
     .command("deactivate")
@@ -1211,17 +1265,18 @@ program
 program
     .command("license")
     .description("Show current license status")
-    .action(() => {
-    const limits = readLicenseLimits();
+    .action(async () => {
+    // Check in first (throttled to once a day), so `vexp license` is also the
+    // way to register this machine and the date printed below is current.
+    const outcome = await refreshFromDisk();
+    const limits = readLicenseLimits({ refresh: false });
     // AppSumo lifetime tiers print as the raw internal string ("tier3") with a
     // "Renews" date one month out — which is the local token's expiry, not the
     // licence's. It rolls forward by itself on every check-in. A tier-3 buyer
     // read that as a monthly deadline and re-activated his key by hand every
     // month for nothing, and he was right to be alarmed by what it said.
-    const ltd = /^tier[1-4]$/.test(limits.plan);
-    const planLabel = ltd
-        ? `Lifetime · Tier ${limits.plan.slice(4)}`
-        : limits.plan;
+    const ltd = isLifetimePlan(limits.plan);
+    const planLabel = licensePlanLabel(limits.plan);
     console.log(chalk.bold("\nvexp License Status\n"));
     console.log(`  Plan:      ${planLabel}`);
     if (limits.email)
@@ -1238,11 +1293,12 @@ program
                 `current one valid to ${limits.renewsAt.toLocaleDateString()})`
             : `  Renews:    ${limits.renewsAt.toLocaleDateString()}`);
     }
-    const blocked = readDeviceBlocked();
+    printCheckInStatus(outcome, "  ");
+    const blocked = outcome.kind === "device_limit_exceeded" ? null : readDeviceBlocked();
     if (blocked) {
         console.log("");
         console.log(chalk.yellow(`  ⚠ This machine is not registered (${blocked.maxDevices}/${blocked.maxDevices} slots used).`));
-        console.log(chalk.dim(`    Free a slot at ${blocked.manageUrl} and run a vexp command\n    to re-register this device.`));
+        console.log(chalk.dim(`    Free a slot at ${blocked.manageUrl} and run \`vexp license\`\n    to re-register this device.`));
     }
     console.log("");
 });
@@ -1300,34 +1356,81 @@ program
     }
 });
 program
-    .command("use <workspacePath>")
-    .description("Switch codex (global MCP config) to point at a different configured workspace")
-    .action(async (workspacePath) => {
-    const resolved = path.resolve(workspacePath);
-    const manifest = path.join(resolved, ".vexp", "manifest.json");
-    if (!fs.existsSync(manifest)) {
-        console.error(chalk.red(`No .vexp/manifest.json at ${resolved}. Run 'vexp setup' there first.`));
-        process.exit(1);
-    }
+    .command("use [workspacePath]")
+    .description("Set Codex up for a configured workspace; --pin makes every Codex session use its index, --unpin undoes that")
+    .option("--pin", "pin Codex's global vexp entry to this workspace, whatever folder a session starts in")
+    .option("--unpin", "drop the pin: Codex starts vexp in each session's own folder (the default)")
+    .action(async (workspacePath, opts) => {
     const binaryPath = ensureBinary();
     const mcpServerPath = getMcpServerPath();
     // Import lazily so configureCodexGlobal's side effects (TOML rewrite + legacy cleanup) only fire here.
-    const { configureSelectedAgents, codexGlobalSectionIsUserManaged } = await import("./agent-config.js");
+    const { configureSelectedAgents, configureCodexGlobal, codexGlobalSectionIsUserManaged, codexGlobalExplicitPin } = await import("./agent-config.js");
     // A hand-written [mcp_servers.vexp] is never rewritten (no-clobber), and
     // this command used to print its success line anyway — the user then
     // "repointed" Codex and watched it launch from the old cwd (field
     // report, 2026-09-19). Say what did not happen and how to do it by hand.
     if (codexGlobalSectionIsUserManaged()) {
         console.error(chalk.yellow(`~/.codex/config.toml has a hand-written [mcp_servers.vexp] section, and vexp never rewrites one: Codex keeps launching it exactly as written, so nothing changed.`));
-        console.error(chalk.dim(`  Point it yourself — under [mcp_servers.vexp] add cwd = ${JSON.stringify(resolved)}, and under [mcp_servers.vexp.env] add VEXP_WORKSPACE = ${JSON.stringify(resolved)} — or delete the section and run 'vexp use' again.`));
+        if (opts.pin && workspacePath) {
+            const resolved = path.resolve(workspacePath);
+            console.error(chalk.dim(`  Point it yourself — under [mcp_servers.vexp] add cwd = ${JSON.stringify(resolved)}, and under [mcp_servers.vexp.env] add VEXP_WORKSPACE = ${JSON.stringify(resolved)} — or delete the section and run 'vexp use' again.`));
+        }
+        else {
+            console.error(chalk.dim("  Delete the section and run 'vexp use' again to have vexp manage it."));
+        }
+        process.exit(1);
+    }
+    if (opts.unpin) {
+        // The HTTP transport routes to one workspace's daemon by URL: there is
+        // no project-free form of it to go back to.
+        if ((process.env.VEXP_CODEX_TRANSPORT ?? "direct").toLowerCase() === "http") {
+            console.error(chalk.yellow("VEXP_CODEX_TRANSPORT=http: the HTTP entry always names one project. Unset it to use the direct transport, which follows each Codex session's folder."));
+            process.exit(1);
+        }
+        configureCodexGlobal(binaryPath, mcpServerPath, undefined, { unpin: true });
+        console.log(chalk.green("OK: codex now starts vexp in each session's own folder"));
+        return;
+    }
+    if (!workspacePath) {
+        console.error(chalk.red("Name the workspace ('vexp use <path>', add --pin to pin Codex to it), or pass --unpin."));
+        process.exit(1);
+    }
+    const resolved = path.resolve(workspacePath);
+    const manifest = path.join(resolved, ".vexp", "manifest.json");
+    if (!fs.existsSync(manifest)) {
+        console.error(chalk.red(`No .vexp/manifest.json at ${resolved}. Run 'vexp setup' there first.`));
         process.exit(1);
     }
     const version = (await getInstalledVersion()) ?? CLI_VERSION;
-    // "Codex" is a no-op file-wise in non-detect mode but the shared flow
-    // also writes codex global config via configureCodexGlobal — pass an
-    // empty agent list so only the MCP side runs.
+    // Codex's entry names no project any more: Codex starts vexp in each
+    // session's folder, and pinning the project set up last broke every
+    // other one. Setting Codex up here therefore pins nothing: doctor sends
+    // Codex users here, and a machine-wide pin is not what they asked for. A
+    // pin is --pin, and a pin made that way follows this command to the next
+    // project named, as 'vexp use' always did.
+    const pin = opts.pin || codexGlobalExplicitPin() !== undefined;
     configureSelectedAgents(resolved, binaryPath, version, ["Codex"], mcpServerPath);
-    console.log(chalk.green(`✓ codex now points at ${resolved}`));
+    if (pin)
+        configureCodexGlobal(binaryPath, mcpServerPath, resolved, { pin: true });
+    // Setting Codex up for a project is a choice of Codex for it: remembered,
+    // so the extension keeps it set up there instead of asking.
+    recordAgentConsent(resolved, "Codex", "yes");
+    // The HTTP entry is a URL routed to one workspace's daemon: whatever
+    // was asked, it now names this project for every session.
+    const http = (process.env.VEXP_CODEX_TRANSPORT ?? "direct").toLowerCase() === "http";
+    if (pin) {
+        console.log(chalk.green(`OK: codex now points at ${resolved}`));
+        console.log(chalk.dim("  every Codex session, in any folder, queries this project's index; 'vexp use --unpin' undoes it"));
+    }
+    else if (http) {
+        console.log(chalk.green(`OK: codex set up for ${resolved}`));
+        console.log(chalk.dim("  VEXP_CODEX_TRANSPORT=http: the HTTP entry routes every Codex session, in any folder, to this project's index. Unset it to use the direct transport, which follows each session's folder."));
+    }
+    else {
+        console.log(chalk.green(`OK: codex set up for ${resolved}`));
+        console.log(chalk.dim(`  Codex starts vexp in each session's own folder; 'vexp use ${JSON.stringify(resolved)} --pin' would make every session use this project instead`));
+    }
+    printCodexHookApprovals();
 });
 // ────────────────────────────────────────────────────
 // Version
@@ -1352,7 +1455,7 @@ const MENU_CONFIG = [
 ];
 // ── Sub-menu: Explore & Analyze ──
 const MENU_EXPLORE = [
-    { key: "1", label: "capsule", hint: "Generate context capsule for a task", description: "Given a natural-language query, returns the most relevant files\n    and symbols as a compressed context capsule (markdown).\n    70-90% token savings vs reading full files." },
+    { key: "1", label: "capsule", hint: "Generate context capsule for a task", description: "Given a natural-language query, returns the most relevant files\n    and symbols as a compressed context capsule (markdown),\n    much smaller than reading the full files." },
     { key: "2", label: "skeleton", hint: "Show a file's token-efficient skeleton", description: "Prints a compact outline of a file (functions, classes, signatures).\n    Detail levels: minimal / standard / detailed." },
     { key: "3", label: "impact", hint: "Impact graph for a symbol", description: "Shows every symbol that depends on a given function/class\n    (direct + transitive).\n    Output: tree, list, or mermaid diagram." },
     { key: "4", label: "flow", hint: "Logic flow between two symbols", description: "Finds execution paths (call chains) from symbol A to symbol B.\n    Output: up to N shortest paths with cost." },
@@ -1370,7 +1473,7 @@ const MENU_REPOS = [
 // ── Sub-menu: License ──
 const MENU_LICENSE = [
     { key: "1", label: "status", hint: "Show current license plan and limits", description: "Displays your current plan (free / pro / team), node limits,\n    repo limits, and license expiry." },
-    { key: "2", label: "activate", hint: "Activate a Pro/Team license key", description: "Enter a license key to unlock Pro or Team features.\n    Get your key at https://vexp.dev/#pricing" },
+    { key: "2", label: "activate", hint: "Activate your license key", description: "Enter your license key (Pro, Team or lifetime) to unlock your plan.\n    Find your key at https://vexp.dev/account" },
     { key: "3", label: "deactivate", hint: "Remove current license", description: "Removes the active license. Free plan limits will apply." },
 ];
 /** Format a duration as a compact uptime string (e.g. "2h 14m", "47s"). */
@@ -1872,11 +1975,12 @@ async function executeCommand(label, rl, outCtl) {
             }
             // ── License commands ──
             case "status": {
-                const limits = readLicenseLimits();
+                const outcome = await refreshFromDisk();
+                const limits = readLicenseLimits({ refresh: false });
                 // Same wording as `vexp license`: a lifetime tier must not be shown as
                 // a raw "tier3" with a monthly renewal date it does not have.
-                const ltd = /^tier[1-4]$/.test(limits.plan);
-                console.log(`    Plan:      ${ltd ? `Lifetime · Tier ${limits.plan.slice(4)}` : limits.plan}`);
+                const ltd = isLifetimePlan(limits.plan);
+                console.log(`    Plan:      ${licensePlanLabel(limits.plan)}`);
                 if (limits.email)
                     console.log(`    Email:     ${limits.email}`);
                 console.log(`    Max nodes: ${limits.maxNodes === 0 ? "unlimited" : limits.maxNodes.toLocaleString()}`);
@@ -1890,21 +1994,19 @@ async function executeCommand(label, rl, outCtl) {
                         ? `    Renewal:   none — lifetime licence (token auto-refreshes, valid to ${limits.renewsAt.toLocaleDateString()})`
                         : `    Renews:    ${limits.renewsAt.toLocaleDateString()}`);
                 }
+                printCheckInStatus(outcome, "    ");
+                const blocked = outcome.kind === "device_limit_exceeded" ? null : readDeviceBlocked();
+                if (blocked) {
+                    console.log(chalk.yellow(`    This machine is not registered (${blocked.maxDevices}/${blocked.maxDevices} slots used). Free a slot at ${blocked.manageUrl}.`));
+                }
                 break;
             }
             case "activate": {
                 const key = await askSecretOn(rl, chalk.cyan("    License key: "), outCtl, process.stdout);
                 if (key.trim()) {
-                    try {
-                        const claims = activateLicense(key.trim());
-                        console.log(chalk.green("\n    ✓ License activated!"));
-                        console.log(`      Plan:    ${claims.plan}`);
-                        console.log(`      Email:   ${claims.sub}`);
-                        console.log(`      Expires: ${new Date(claims.exp * 1000).toLocaleDateString()}`);
-                    }
-                    catch (err) {
-                        console.error(chalk.red(`    ✗ ${err instanceof Error ? err.message : err}`));
-                    }
+                    // Awaits the check-in exactly like `vexp activate`: this path used
+                    // to write the key and stop, so the device never registered.
+                    await runActivation(key, { indent: "    " });
                 }
                 break;
             }