@bluenotelogic/harness 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * bnl-harness — point this machine at Blue Note Memory in one command.
+ * bnl-harness — point this machine at ProofMEM in one command.
  *
  *     npx @bluenotelogic/harness init
  *
@@ -10,29 +10,30 @@
  *
  * THE IMPORTANT PART — the `.mcp.json` this writes carries NO TOKEN:
  *
- *     { "mcpServers": { "mem": { "type": "http", "url": "https://mem.bnlgit.com/mcp" } } }
+ *     { "mcpServers": { "proofmem": { "type": "http", "url": "https://proofmem.com/mcp" } } }
  *
  * OAuth-capable hosts (Claude Code, VS Code) discover auth from the endpoint's 401 +
  * WWW-Authenticate, run the browser flow against Blue Note ID, and store their own
  * credentials. Nothing secret is written into a repo file, so the file is safe to commit
  * and there is nothing to rotate.
  *
- * Codex and CI cannot do that yet, so `--mint-token` exists for them — and it writes the
- * token to `~/.codex/.env`, never into a repo. Minting is OPT-IN precisely so the default
- * path creates no credential and no database row.
+ * Codex and hook subprocesses cannot do that yet, so token minting remains explicit: `--codex`
+ * writes only to `~/.codex/.env`, while `--antigravity` writes a separate owner-only hook key.
  */
+import { execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
-import { discover, registerClient, authorizeViaBrowser, authorizeViaDevice, } from "./oauth.js";
-import { exchangeForTenantToken, fetchBundle, SubscriptionRequiredError, } from "./bundle.js";
-import { planMcpJson, planSettingsLocal, planCodexConfig, planEnvVar, planRoutingFile, assertNoSecret, readIfExists, isNoop, apply, } from "./writers.js";
-const DEFAULT_BASE_URL = "https://mem.bnlgit.com";
-const DEFAULT_CLIENT_ID = "blue-note-mem-mcp";
+import { discover, registerClient, authorizeViaBrowser, authorizeViaDevice, revokeRefreshToken, AccessDeniedError, } from "./oauth.js";
+import { tenantTokenForSignIn, fetchBundle, SubscriptionRequiredError, IdentityIncompleteError, } from "./bundle.js";
+import { planMcpJson, planCodexConfig, planEnvVar, legacyEnvVarsPresent, planRoutingFile, assertNoSecret, readIfExists, isNoop, apply, } from "./writers.js";
+import { assertAntigravityInstallTarget, antigravityConfigHome, antigravityHookTokenPath, antigravityInstallPaths, planAntigravityInstall, } from "./antigravity.js";
+const DEFAULT_BASE_URL = "https://proofmem.com";
+const DEFAULT_CLIENT_ID = "proofmem-mcp";
 /**
  * `blue_note_identity`, NOT `email`. The two are easy to confuse and the failure is silent
  * until the very last step:
  *
- * The `blue-note-mem-mcp` provider has exactly four scope mappings attached — openid, profile,
+ * The `proofmem-mcp` provider has exactly four scope mappings attached — openid, profile,
  * offline_access and blue_note_identity. The stock `email` mapping is deliberately NOT among
  * them, and Authentik ignores a scope it has no mapping for rather than refusing it. So asking
  * for `email` succeeded all the way through consent and the code exchange, then produced a
@@ -44,7 +45,14 @@ const DEFAULT_CLIENT_ID = "blue-note-mem-mcp";
  * BlueNoteOidc.php:201 in caveau-mem, which is the same identity resolution this trades into.
  */
 const DEFAULT_SCOPE = "openid profile blue_note_identity offline_access";
-const TOKEN_ENV_VAR = "BNL_MEMORY_MCP_TOKEN";
+/** Where a Blue Note ID's email address is verified. */
+const BLUE_NOTE_ID_URL = "https://id.bluenotelogic.com";
+const TOKEN_ENV_VAR = "PROOFMEM_TOKEN";
+/**
+ * Earlier names for the Codex token. Left in `~/.codex/.env` untouched — BNL staff machines still
+ * run tools that read them — and only ever named (never their values) in a notice.
+ */
+const LEGACY_TOKEN_ENV_VARS = ["BNL_MEMORY_MCP_TOKEN", "CAVEAU_MCP_TOKEN"];
 /**
  * `--timeout`, in seconds. Refused rather than coerced: a typo'd `--timeout abc` silently
  * becoming NaN — and therefore an instant timeout — would be a second, quieter version of the
@@ -65,11 +73,15 @@ function parseArgs(argv) {
         device: false,
         token: null,
         mintToken: false,
+        explicitMintToken: false,
         harnessHome: null,
         serverName: null,
         clientId: DEFAULT_CLIENT_ID,
         openBrowser: true,
         codex: false,
+        antigravity: false,
+        antigravityHome: null,
+        verifyGate: false,
         timeoutMs: null,
     };
     let command = "init";
@@ -102,11 +114,22 @@ function parseArgs(argv) {
                 break;
             case "--mint-token":
                 opts.mintToken = true;
+                opts.explicitMintToken = true;
                 break;
             case "--codex":
                 opts.codex = true;
                 opts.mintToken = true;
                 break;
+            case "--antigravity":
+                opts.antigravity = true;
+                opts.mintToken = true;
+                break;
+            case "--antigravity-home":
+                opts.antigravityHome = resolve(next());
+                break;
+            case "--verify-gate":
+                opts.verifyGate = true;
+                break;
             case "--harness-home":
                 opts.harnessHome = resolve(next());
                 break;
@@ -136,18 +159,24 @@ function parseArgs(argv) {
     return { command, opts };
 }
 const HELP = `
-bnl-harness — configure this machine for Blue Note Memory
+bnl-harness — configure this machine for ProofMEM
 
   npx @bluenotelogic/harness init [options]
+  npx @bluenotelogic/harness doctor [options]
 
 Options
   --url <base>          Server base URL (default ${DEFAULT_BASE_URL})
   --dir <path>          Repo to configure (default: current directory)
-  --dry-run             Show every file that would change; write nothing
+  --dry-run             Show every file that would change; write nothing and mint no
+                        long-lived token (signing in still creates one 1-hour session key)
   --device              Device-code login, for headless boxes and SSH sessions
   --token <token>       Use an existing cmem_ token instead of logging in (CI)
   --mint-token          Also mint a token for hosts that cannot do OAuth
   --codex               Configure Codex too (implies --mint-token)
+  --antigravity         Install the ProofMEM Antigravity plugin (implies --mint-token)
+  --antigravity-home    Override Antigravity config home (default ~/.gemini/config)
+  --verify-gate         Antigravity: run the open project's own build/test/lint when the
+                        agent stops (off by default: it runs that project's code)
   --harness-home <dir>  Also materialize hosted routing into <dir>/state/routing/
   --server-name <name>  Override the MCP server key written into .mcp.json
   --client-id <id>      OAuth client_id (default ${DEFAULT_CLIENT_ID})
@@ -157,8 +186,8 @@ Options
   -h, --help            This text
   -v, --version         Version
 
-By default nothing secret is written: Claude Code and VS Code authenticate over OAuth and
-keep their own credentials, so the .mcp.json this produces is safe to commit.
+By default nothing secret is written: OAuth-capable hosts keep their own credentials. The
+Antigravity plugin also stays tokenless; only its lifecycle hooks use a separate owner-only key.
 `;
 async function main() {
     const { command, opts } = parseArgs(process.argv.slice(2));
@@ -170,8 +199,26 @@ async function main() {
         console.log(await version());
         return;
     }
+    if (command === "doctor") {
+        runDoctor(opts);
+        return;
+    }
     if (command !== "init")
         fail(`unknown command: ${command}\nRun \`bnl-harness --help\`.`);
+    if (opts.antigravity && !opts.harnessHome) {
+        const fromEnv = process.env["HARNESS_HOME"];
+        if (fromEnv)
+            opts.harnessHome = resolve(fromEnv);
+    }
+    if (opts.antigravity && !opts.harnessHome) {
+        fail("--antigravity requires --harness-home <caveau-harness-v2> (or HARNESS_HOME).\n" +
+            "The Antigravity hooks need a Caveau Harness v2 checkout, set up with our team in a guided Caveau Harness session; contact ProofMEM to book one.");
+    }
+    if (opts.harnessHome)
+        assertHarnessV2(opts.harnessHome);
+    if (opts.antigravity) {
+        assertAntigravityInstallTarget(antigravityConfigHome(opts.antigravityHome));
+    }
     const bundle = await getBundle(opts);
     const changes = planAll(bundle, opts);
     report(changes, opts, bundle);
@@ -181,40 +228,276 @@ async function main() {
     if (!opts.dryRun)
         printNextSteps(bundle, opts, changes);
 }
-/** Authenticate (unless given a token) and fetch the bundle. */
+const CODEX_BLOCK_START = "# BEGIN @bluenotelogic/harness managed MCP";
+const CODEX_BLOCK_END = "# END @bluenotelogic/harness managed MCP";
+const HARNESS_GENERATION = "caveau-harness-v2";
+const TOKEN_PATTERN = /\b(?:cmem|mcp)_[A-Za-z0-9_-]{16,}/;
+/** Refuse an archived or unidentified harness before writing hosted routing into it. */
+function assertHarnessV2(harnessHome) {
+    const markerPath = join(harnessHome, ".harness-generation");
+    const marker = readIfExists(markerPath)?.trim();
+    if (marker !== HARNESS_GENERATION) {
+        const observed = marker ? `generation ${JSON.stringify(marker)}` : "no .harness-generation marker";
+        fail(`HARNESS_HOME must identify ${HARNESS_GENERATION}; ${harnessHome} has ${observed}. ` +
+            "The archived caveau-harness tree is not supported.");
+    }
+}
+/** Read-only installation validation. It deliberately never prints credential values. */
+function runDoctor(opts) {
+    const failures = [];
+    const warnings = [];
+    let harnessHome = opts.harnessHome ?? process.env["HARNESS_HOME"] ?? null;
+    const checkCodex = !opts.antigravity || opts.codex;
+    if (checkCodex) {
+        const codexHome = process.env["CODEX_HOME"] ?? join(homedir(), ".codex");
+        const configPath = join(codexHome, "config.toml");
+        const envPath = join(codexHome, ".env");
+        const config = readIfExists(configPath);
+        const envFile = readIfExists(envPath);
+        if (config === null) {
+            failures.push(`missing Codex config: ${configPath}`);
+        }
+        else {
+            const startCount = config.split(CODEX_BLOCK_START).length - 1;
+            const endCount = config.split(CODEX_BLOCK_END).length - 1;
+            if (startCount !== 1 || endCount !== 1) {
+                failures.push("Codex config must contain exactly one installer-managed MCP block");
+            }
+            if (!config.includes(`bearer_token_env_var = "${TOKEN_ENV_VAR}"`)) {
+                failures.push(`Codex config must reference ${TOKEN_ENV_VAR}`);
+            }
+            if (TOKEN_PATTERN.test(config) || /authorization\s*=\s*["']?bearer\s+/i.test(config)) {
+                failures.push("Codex config contains a literal bearer credential");
+            }
+        }
+        if (envFile === null || !new RegExp(`^${TOKEN_ENV_VAR}=\\S+`, "m").test(envFile)) {
+            failures.push(`Codex owner credential store must define ${TOKEN_ENV_VAR}`);
+        }
+        for (const legacy of legacyEnvVarsPresent(envFile, LEGACY_TOKEN_ENV_VARS)) {
+            warnings.push(`${legacy} is a legacy variable in ${envPath}; remove it by hand once nothing uses it`);
+        }
+    }
+    if (opts.antigravity) {
+        const configHome = antigravityConfigHome(opts.antigravityHome);
+        const { pluginRoot, tokenFile } = antigravityInstallPaths(configHome);
+        const manifestRaw = readIfExists(join(pluginRoot, "plugin.json"));
+        const hooks = readIfExists(join(pluginRoot, "hooks.json"));
+        const mcpRaw = readIfExists(join(pluginRoot, "mcp_config.json"));
+        const localRaw = readIfExists(join(pluginRoot, "harness-home.json"));
+        try {
+            const manifest = JSON.parse(manifestRaw ?? "null");
+            if (manifest?.["name"] !== "proofmem")
+                throw new Error("missing proofmem manifest");
+        }
+        catch {
+            failures.push(`Antigravity plugin manifest is missing or invalid: ${pluginRoot}`);
+        }
+        if (hooks === null
+            || !hooks.includes("node ./scripts/antigravity-hook.mjs session-start")
+            || hooks.includes('node \\"./scripts/antigravity-hook.mjs')) {
+            failures.push("Antigravity hooks are missing or use Windows-unsafe quoted script paths");
+        }
+        try {
+            const mcp = JSON.parse(mcpRaw ?? "null");
+            const servers = mcp?.["mcpServers"];
+            const server = servers && Object.values(servers)[0];
+            if (!server || typeof server["serverUrl"] !== "string")
+                throw new Error("missing serverUrl");
+            for (const forbidden of ["command", "args", "headers", "oauth", "env"]) {
+                if (Object.hasOwn(server, forbidden))
+                    throw new Error(`forbidden ${forbidden}`);
+            }
+            if (TOKEN_PATTERN.test(mcpRaw ?? "") || /authorization\s*["':=]+\s*["']?bearer\s+/i.test(mcpRaw ?? "")) {
+                throw new Error("literal credential");
+            }
+        }
+        catch (error) {
+            failures.push(`Antigravity MCP config is not a tokenless native HTTP server (${error.message})`);
+        }
+        try {
+            const local = JSON.parse(localRaw ?? "null");
+            if (typeof local?.["harnessHome"] !== "string")
+                throw new Error("missing harnessHome");
+            if (typeof local?.["hookTokenFile"] !== "string")
+                throw new Error("missing hookTokenFile");
+            if (resolve(String(local["hookTokenFile"])) !== resolve(tokenFile)) {
+                throw new Error("hook token path is outside the installer-owned credential store");
+            }
+            harnessHome ??= String(local["harnessHome"]);
+        }
+        catch (error) {
+            failures.push(`Antigravity local Harness config is missing or invalid (${error.message})`);
+        }
+        const hookToken = readIfExists(tokenFile)?.trim() ?? "";
+        if (!/^(?:cmem|mcp)_[A-Za-z0-9_-]{16,}$/.test(hookToken)) {
+            failures.push("Antigravity owner credential store is missing or invalid");
+        }
+        // The hook credential is bounded (90 days). Expired, every hook fails open with no memory, so
+        // say so here rather than leaving the user to read 401 diagnostics in a session.
+        let expiresAt;
+        try {
+            const raw = JSON.parse(localRaw ?? "null")?.["hookTokenExpiresAt"];
+            expiresAt = typeof raw === "string" ? raw : undefined;
+        }
+        catch {
+            /* reported above */
+        }
+        const expiresMs = expiresAt ? Date.parse(expiresAt) : NaN;
+        const renew = "rerun `init --antigravity` to renew it";
+        if (!Number.isNaN(expiresMs) && expiresMs <= Date.now()) {
+            failures.push(`Antigravity hook credential expired at ${expiresAt}; ${renew}`);
+        }
+        else if (!Number.isNaN(expiresMs) && expiresMs - Date.now() <= 14 * 24 * 60 * 60 * 1000) {
+            warnings.push(`Antigravity hook credential expires at ${expiresAt}; ${renew}`);
+        }
+        // Every hook runs the Harness core through bash. Without it they all fail open silently.
+        const resolver = join(pluginRoot, "scripts", "resolve-bash.mjs");
+        try {
+            execFileSync(process.execPath, [resolver, "-c", "exit 0"], { stdio: "ignore", timeout: 15_000, windowsHide: true });
+        }
+        catch {
+            failures.push("Antigravity hooks cannot find bash (on Windows, install Git for Windows; WSL bash is not used)");
+        }
+    }
+    if (!harnessHome) {
+        failures.push("HARNESS_HOME is not set");
+    }
+    else {
+        const marker = readIfExists(join(harnessHome, ".harness-generation"))?.trim();
+        if (marker !== HARNESS_GENERATION) {
+            failures.push(`HARNESS_HOME must point at ${HARNESS_GENERATION}`);
+        }
+    }
+    const repoMcpPath = join(opts.dir, ".mcp.json");
+    const repoMcp = readIfExists(repoMcpPath);
+    if (repoMcp !== null && (TOKEN_PATTERN.test(repoMcp) || /authorization\s*["':=]+\s*["']?bearer\s+/i.test(repoMcp))) {
+        failures.push(`${repoMcpPath} contains a literal bearer credential`);
+    }
+    console.log("bnl-harness doctor");
+    if (checkCodex) {
+        console.log(`  Codex config  ${failures.some((v) => v.startsWith("Codex config") || v.startsWith("missing Codex")) ? "FAIL" : "ok"}`);
+    }
+    if (opts.antigravity) {
+        console.log(`  Antigravity   ${failures.some((v) => v.startsWith("Antigravity")) ? "FAIL" : "ok"}`);
+    }
+    console.log(`  credential    ${failures.some((v) => v.includes("credential store")) ? "FAIL" : "ok"}`);
+    console.log(`  HARNESS_HOME  ${failures.some((v) => v.startsWith("HARNESS_HOME")) ? "FAIL" : "ok"}`);
+    console.log(`  repo config   ${failures.some((v) => v.startsWith(repoMcpPath)) ? "FAIL" : "ok"}`);
+    for (const warning of warnings)
+        console.log(`  WARN ${warning}`);
+    if (failures.length)
+        fail(`doctor found ${failures.length} problem(s):\n- ${failures.join("\n- ")}`);
+    console.log("\nInstallation is healthy.");
+}
+/**
+ * `--codex --antigravity` used to write ONE minted value into both ~/.codex/.env and the
+ * Antigravity hook-token file, so the "separate hook credential" was not separate and revoking
+ * one revoked both. When both stores are written, the hook gets its own mint from this sign-in.
+ */
+async function withHookToken(opts, credential, bundle) {
+    if (!opts.antigravity || !(opts.codex || opts.explicitMintToken) || opts.dryRun)
+        return bundle;
+    const second = await fetchBundle(opts.baseUrl, credential, { mintToken: true });
+    return { ...bundle, hookToken: second.token };
+}
 async function getBundle(opts) {
+    const mintToken = opts.mintToken && !opts.dryRun;
     if (opts.token) {
         log(`Using the token supplied on the command line (skipping login).`);
-        return fetchBundle(opts.baseUrl, opts.token, { mintToken: opts.mintToken });
+        return withHookToken(opts, opts.token, await fetchBundle(opts.baseUrl, opts.token, { mintToken }));
     }
     log(`Discovering ${opts.baseUrl}…`);
     const meta = await discover(opts.baseUrl);
     const clientId = await registerClient(meta, opts.clientId);
-    const tokens = opts.device
-        ? await authorizeViaDevice({
-            meta, clientId, scope: DEFAULT_SCOPE, resource: `${opts.baseUrl}/mcp`,
-            timeoutMs: opts.timeoutMs ?? undefined, log,
-        })
-        : await authorizeViaBrowser({
-            meta, clientId, scope: DEFAULT_SCOPE, resource: `${opts.baseUrl}/mcp`,
-            timeoutMs: opts.timeoutMs ?? undefined, openBrowser: opts.openBrowser, log,
-        });
+    let tokens;
+    try {
+        tokens = opts.device
+            ? await authorizeViaDevice({
+                meta, clientId, scope: DEFAULT_SCOPE, resource: `${opts.baseUrl}/mcp`,
+                timeoutMs: opts.timeoutMs ?? undefined, log,
+            })
+            : await authorizeViaBrowser({
+                meta, clientId, scope: DEFAULT_SCOPE, resource: `${opts.baseUrl}/mcp`,
+                timeoutMs: opts.timeoutMs ?? undefined, openBrowser: opts.openBrowser, log,
+            });
+    }
+    catch (e) {
+        // No token was issued, so there is no refresh grant to end here.
+        if (e instanceof AccessDeniedError)
+            fail(signInRefusedMessage(opts.baseUrl, e.flow));
+        throw e;
+    }
+    // The sign-in's refresh token is never used: end it on every way out of here, success or not
+    // (see revokeRefreshToken). Before fail(), too — fail() exits without running a finally.
+    const endSignIn = async () => {
+        if (!tokens.refresh_token)
+            return;
+        if (!(await revokeRefreshToken(meta, clientId, tokens.refresh_token))) {
+            log("Note: the server did not confirm ending this sign-in's refresh grant. This CLI never uses it;\n" +
+                "      it lapses on its own when it expires (through proofmem.com, within 35 days).");
+        }
+    };
     log("Signed in. Resolving your memory tenant…");
     let tenantToken;
     try {
-        tenantToken = await exchangeForTenantToken(opts.baseUrl, tokens.access_token);
+        // Through the proofmem.com gateway the access token already is the tenant key; only a Blue
+        // Note ID token is exchanged (see tenantTokenForSignIn).
+        tenantToken = await tenantTokenForSignIn(opts.baseUrl, tokens.access_token);
     }
     catch (e) {
+        await endSignIn();
         if (e instanceof SubscriptionRequiredError) {
             // Authenticated fine — they just do not have the product. Say that, and say where to
             // go, rather than leaving them re-trying a login that already worked.
             fail(`${e.message}\n\n` +
-                `Your Blue Note Account signed in successfully — it just has no Blue Note Memory\n` +
+                `Your Blue Note Account signed in successfully — it just has no ProofMEM\n` +
                 `subscription attached. Start one at ${opts.baseUrl}/pricing.php`);
         }
+        if (e instanceof IdentityIncompleteError) {
+            // Same shape of mistake as above: the login worked. Do not let this read as an auth
+            // failure, or the user re-runs `init` forever against a problem no login can fix.
+            fail(`${e.message}\n\n` +
+                `Your Blue Note Account signed in successfully — the sign-in itself is not the problem,\n` +
+                `so running this again will not help until the account or client scope is corrected.`);
+        }
         throw e;
     }
-    return fetchBundle(opts.baseUrl, tenantToken, { mintToken: opts.mintToken });
+    try {
+        return await withHookToken(opts, tenantToken, await fetchBundle(opts.baseUrl, tenantToken, { mintToken }));
+    }
+    finally {
+        await endSignIn();
+    }
+}
+/**
+ * What an `access_denied` from the token endpoint means (AccessDeniedError). Through proofmem.com
+ * the gateway answers it for a Blue Note ID sign-in that WORKED, when the account has no ProofMEM
+ * subscription or no verified email; printed raw it read as a failed login and sent people round
+ * the sign-in again. On the device flow the request may also have been declined. Nothing from the
+ * server's response is echoed.
+ */
+function signInRefusedMessage(baseUrl, flow) {
+    const opening = flow === "device"
+        ? `${baseUrl} would not issue a ProofMEM key for this sign-in (access_denied).\n` +
+            `The cause is one of:\n` +
+            `  - The request was declined on the approval page.\n`
+        : `Blue Note ID signed you in, but ${baseUrl} would not issue a ProofMEM key\n` +
+            `for this account (access_denied). Signing in again will not change that. The cause is one of:\n`;
+    return (opening +
+        `  - The account has no ProofMEM subscription. Start one at ${baseUrl}/pricing.php\n` +
+        `  - The Blue Note ID has no verified email address. Verify it at ${BLUE_NOTE_ID_URL}\n` +
+        `Then run this command again.`);
+}
+/** The server's expiry ("2027-01-01 00:00:00Z" or ISO) as ISO-8601, or undefined if unparseable. */
+function isoExpiry(raw) {
+    if (!raw)
+        return undefined;
+    const at = Date.parse(raw.trim().replace(" ", "T"));
+    return Number.isNaN(at) ? undefined : new Date(at).toISOString();
+}
+/** The token the Antigravity hooks get: its own mint when Codex also gets one, else the one mint. */
+function antigravityHookToken(bundle, opts) {
+    return opts.codex || opts.explicitMintToken ? bundle.hookToken : bundle.token;
 }
 /** Everything this run would write, as data. Nothing here touches the filesystem twice. */
 function planAll(bundle, opts) {
@@ -229,20 +512,55 @@ function planAll(bundle, opts) {
     const mcpPath = join(opts.dir, ".mcp.json");
     changes.push(planMcpJson(mcpPath, readIfExists(mcpPath), servers));
     // --- Optional: a real credential, for hosts that cannot do OAuth. ---------------------
-    const minted = bundle.token?.value;
-    if (minted) {
-        const codexHome = process.env["CODEX_HOME"] ?? join(homedir(), ".codex");
-        const serverName = opts.serverName ?? Object.keys(servers)[0] ?? "mem";
-        if (opts.codex) {
-            const cfg = join(codexHome, "config.toml");
-            changes.push(planCodexConfig(cfg, readIfExists(cfg), serverName, bundle.endpoint.mcp_url, TOKEN_ENV_VAR));
+    //
+    // 🔴 NEVER a repo-tree write, not even .claude/settings.local.json (Codex review,
+    // 2026-08-26: that file used to carry the literal token so the VS Code extension's editor
+    // button -- which launches `claude` without sourcing a shell env file -- could see it). Per
+    // the bundle's own declared auth split (bundle.auth.oauth_hosts/token_hosts), Claude Code
+    // and VS Code are OAuth-capable and need no token at all; minting exists for Codex/CI, which
+    // read ~/.codex/.env, a user-level file outside every repo. A VS Code user who wants the
+    // token-based flow no longer gets an editor-button shortcut -- they get OAuth instead, which
+    // is the tokenless path this tool exists to make the default.
+    //
+    // opts.mintToken alone gates this (not bundle.token): a --dry-run never requests a mint
+    // (see getBundle()), so bundle.token is never present here during a preview, but the preview
+    // must still show what a real run would create -- with an inert placeholder standing in for
+    // the value, and every such change marked `sensitive` so report() never echoes it either way.
+    if (opts.mintToken) {
+        const minted = bundle.token?.value;
+        if (!opts.dryRun && !minted) {
+            fail("--mint-token/--codex/--antigravity was requested but the server returned no token; " +
+                "refusing to write a placeholder in place of a real credential.");
+        }
+        const tokenValue = minted ?? "<minted on --apply, not shown here>";
+        const serverName = opts.serverName ?? Object.keys(servers)[0] ?? "proofmem";
+        // A bare --mint-token retains the original Codex-env behavior. --antigravity by itself does
+        // not create or modify Codex files: its one credential belongs only to hook subprocesses.
+        if (opts.codex || opts.explicitMintToken) {
+            const codexHome = process.env["CODEX_HOME"] ?? join(homedir(), ".codex");
+            if (opts.codex) {
+                const cfg = join(codexHome, "config.toml");
+                changes.push(planCodexConfig(cfg, readIfExists(cfg), serverName, bundle.endpoint.mcp_url, TOKEN_ENV_VAR));
+            }
+            const envPath = join(codexHome, ".env");
+            changes.push(planEnvVar(envPath, readIfExists(envPath), TOKEN_ENV_VAR, tokenValue, LEGACY_TOKEN_ENV_VARS));
+        }
+        if (opts.antigravity) {
+            const hook = antigravityHookToken(bundle, opts);
+            if (!opts.dryRun && !hook?.value) {
+                fail("--antigravity was requested but the server returned no hook token; refusing to write a placeholder.");
+            }
+            const configHome = antigravityConfigHome(opts.antigravityHome);
+            changes.push(...planAntigravityInstall({
+                configHome,
+                harnessHome: opts.harnessHome,
+                mcpUrl: bundle.endpoint.mcp_url,
+                serverName,
+                hookToken: hook?.value ?? tokenValue,
+                hookTokenExpiresAt: isoExpiry(hook?.expires_at),
+                verifyGate: opts.verifyGate,
+            }));
         }
-        const envPath = join(codexHome, ".env");
-        changes.push(planEnvVar(envPath, readIfExists(envPath), TOKEN_ENV_VAR, minted));
-        // The VS Code extension launches `claude` without a shell, so an env block in
-        // settings.local.json is what makes a token-based setup work from the editor button.
-        const settings = join(opts.dir, ".claude", "settings.local.json");
-        changes.push(planSettingsLocal(settings, readIfExists(settings), { [TOKEN_ENV_VAR]: minted }));
     }
     // --- Optional: materialize the hosted routing the console edits. -----------------------
     if (opts.harnessHome && bundle.routing) {
@@ -259,16 +577,20 @@ function planAll(bundle, opts) {
     return changes;
 }
 /**
- * The secret guard applies to REPO files only. `~/.codex/.env` and
- * `.claude/settings.local.json` are where a minted token is supposed to live — asserting
- * against them would forbid the very thing `--mint-token` is for.
+ * The secret guard applies to REPO files only. `~/.codex/.env` is the one place a minted
+ * token is supposed to live — asserting against it would forbid the very thing `--mint-token`
+ * is for. Nothing else is exempt: in particular, no path under `opts.dir` (the target repo)
+ * ever qualifies, which is what makes this guard meaningful rather than a formality.
  */
 function assertNoSecret2(c, opts) {
-    const credentialStores = [
-        join(opts.dir, ".claude", "settings.local.json"),
-        join(process.env["CODEX_HOME"] ?? join(homedir(), ".codex"), ".env"),
-    ];
-    if (credentialStores.includes(c.path))
+    const allowedCredentialStores = new Set();
+    if (opts.codex || opts.explicitMintToken) {
+        allowedCredentialStores.add(join(process.env["CODEX_HOME"] ?? join(homedir(), ".codex"), ".env"));
+    }
+    if (opts.antigravity) {
+        allowedCredentialStores.add(antigravityHookTokenPath(antigravityConfigHome(opts.antigravityHome)));
+    }
+    if (allowedCredentialStores.has(c.path))
         return;
     assertNoSecret(c);
 }
@@ -284,13 +606,17 @@ function report(changes, opts, bundle) {
             console.log(`  SKIP   ${c.path}\n         ${c.skipped.replace(/\n/g, "\n         ")}`);
             continue;
         }
-        if (isNoop(c)) {
-            console.log(`  same   ${c.path}`);
+        console.log(`  ${isNoop(c) ? "same  " : c.before === null ? "create" : "update"} ${c.path}`);
+        if (c.notice)
+            console.log(`         NOTICE ${c.notice}`);
+        if (isNoop(c))
             continue;
-        }
-        console.log(`  ${c.before === null ? "create" : "update"} ${c.path}`);
         if (opts.dryRun && c.after) {
-            const body = c.after.split("\n").map((l) => `         │ ${l}`).join("\n");
+            // Sensitive changes never echo `after` -- not the real value on an apply preview, and
+            // not even the inert placeholder, so a dry-run's output looks identical either way and
+            // teaches nobody to expect a real secret to show up here (Codex review, 2026-08-26).
+            const shown = c.sensitive ? "[redacted — holds a credential; not shown]" : c.after;
+            const body = shown.split("\n").map((l) => `         │ ${l}`).join("\n");
             console.log(body.replace(/\n\s+│\s*$/, ""));
         }
     }
@@ -299,16 +625,24 @@ function report(changes, opts, bundle) {
         console.log("  --dry-run: nothing was written.\n");
 }
 function printNextSteps(bundle, opts, changes) {
-    const oauth = !bundle.token;
     console.log("Done.\n");
-    if (oauth) {
-        console.log("  Your .mcp.json carries no token — Claude Code and VS Code will authenticate");
-        console.log("  over OAuth on first use and keep their own credentials. It is safe to commit.\n");
-    }
-    console.log(`  1. Open ${opts.dir} in Claude Code or VS Code`);
+    console.log("  Your .mcp.json carries no token — OAuth-capable hosts authenticate on first use");
+    console.log("  and keep their own credentials. It is safe to commit.\n");
+    console.log(`  1. Open ${opts.dir} in your editor`);
     console.log(`  2. The '${Object.keys(bundle.mcp_json.mcpServers)[0]}' server appears automatically`);
-    if (bundle.token) {
-        console.log(`  3. A token was minted into ${TOKEN_ENV_VAR} — it is in your Codex env file, not this repo`);
+    if (bundle.token && (opts.codex || opts.explicitMintToken)) {
+        const expiry = bundle.token.expires_at ? `, expires ${bundle.token.expires_at}` : "";
+        console.log(`  3. A token was minted into ${TOKEN_ENV_VAR} — it is in your Codex env file, not this repo${expiry}`);
+    }
+    const hook = antigravityHookToken(bundle, opts);
+    if (hook && opts.antigravity) {
+        const expiry = hook.expires_at ? `; it expires ${hook.expires_at}` : "";
+        console.log("  3. Restart Antigravity, enable the ProofMEM plugin, then authenticate its MCP server.");
+        console.log(`     Its separate hook credential is owner-only and is never placed in MCP config${expiry}.`);
+        console.log("     To renew it, run this same command again (`doctor --antigravity` warns 14 days ahead).");
+        console.log(opts.verifyGate
+            ? "     The stop-time verify gate is ON: the open project's build/test/lint runs when the agent stops."
+            : "     The stop-time verify gate is off; pass --verify-gate to run the project's build/test on stop.");
     }
     const notes = changes.filter((c) => c.note && !isNoop(c));
     if (notes.length) {