@bragi-gmbh/codebus 1.4.0 → 1.6.0

package/dist/commands/install.js

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, copyFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, openSync, closeSync, fsyncSync, renameSync, unlinkSync, statSync, lstatSync, realpathSync, readlinkSync, accessSync, constants as fsConstants, } from "node:fs";
 import { homedir } from "node:os";
-import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+import { join, dirname, basename, isAbsolute, delimiter } from "node:path";
 import { fileURLToPath } from "node:url";
 import { OK, WARN } from "./login.js";
 import { readCachedDigest } from "./digest.js";
@@ -11,6 +12,9 @@ import { hookEventHasCommand } from "../mail-latency.js";
 import { loadFileConfig, saveFileConfig } from "../config.js";
 import { ONE_LINER } from "../positioning.js";
 import { createClient } from "@supabase/supabase-js";
+import { isDevLinkedInstall, isCheckoutShapedPackageRoot } from "../version-check.js";
+import { findTopLevelTableBlock, parseSimpleTomlTable, replaceSimpleTomlValues, mightReferenceOurTable } from "../toml-lite.js";
+import { replaceJsonValue } from "../json-lite.js";
 // F5: derive the reported tool count from the actual registry instead of a
 // hardcoded number that rots every time a tool is added/removed. Imported
 // from mcp-registry.ts, NOT mcp.ts (F1): mcp-registry.ts is side-effect-free
@@ -46,13 +50,33 @@ function manualClaudeInstructions() {
         '  "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "codebus session start --hook" } ] } ] }',
     ].join("\n");
 }
-async function installClaude(o) {
+/**
+ * Luna finding: this used to read, mutate, and `writeFileSync` ~/.claude/
+ * settings.json DIRECTLY — no acquireConfigLock, no atomicWriteFileSync, no
+ * TOCTOU re-check — even though installMcp writes this EXACT SAME file
+ * through writeIfUnchanged() elsewhere in this file. Two concurrent
+ * `codebus install claude` runs (or an install racing a hand edit) could
+ * both read the same old file and the later plain write would silently
+ * discard the other's changes. Now routed through the same machinery —
+ * see installCodexHooks (hooks.json) for the identical fix applied there
+ * first. Existing contract preserved: this function has always treated a
+ * failure to safely write settings.json as fatal (process.exit(1) on a
+ * parse error, below) — a write-time conflict now gets the same treatment,
+ * rather than inventing a new boolean-return contract nothing here or in
+ * its one caller (installAll) currently consumes.
+ */
+export async function installClaude(o) {
     const path = CLAUDE_SETTINGS();
     let settings = {};
+    let existingText = "";
     try {
         if (existsSync(path)) {
-            settings = JSON.parse(readFileSync(path, "utf8"));
-            copyFileSync(path, `${path}.codebus-backup`); // never destroy user settings
+            existingText = readFileSync(path, "utf8");
+            settings = JSON.parse(existingText);
+            // Backup is now handled by writeIfUnchanged()'s own atomic backup
+            // write below (against whatever the file's content actually is right
+            // before the write, not this initial read) — no separate copyFileSync
+            // needed here any more.
         }
     }
     catch (e) {
@@ -84,7 +108,15 @@ async function installClaude(o) {
             }
         }
     }
-    const already = JSON.stringify(sessionStart).includes("codebus session start --hook");
+    // Luna finding: a serialized substring check over the WHOLE hook array
+    // (JSON.stringify(...).includes(...)) is fooled by any unrelated hook
+    // whose description, argument, or command merely CONTAINS this text —
+    // reporting "already installed" and skipping the real write while turn-
+    // boundary/session-start coverage is actually absent. hookEventHasCommand
+    // checks only the `command` field of each entry for an EXACT match,
+    // mirroring the same precision installCodexHooks already uses below (and
+    // the manual per-entry command check in the upgrade loop just above).
+    const already = hookEventHasCommand(sessionStart, "codebus session start --hook");
     if (upgraded) {
         settings.hooks.SessionStart = sessionStart;
         console.log(`${OK} SessionStart hook upgraded → codebus session start --hook (bound dirs auto-orient; others stay silent)`);
@@ -98,9 +130,39 @@ async function installClaude(o) {
         console.log(`${OK} SessionStart hook already installed`);
     }
     // Stop hook: turn-boundary mail surfacing (identity-explicit; silent elsewhere).
+    // Luna finding: an existing hook wired with the OLDER bare "codebus tick"
+    // (no --hook) was left untouched by the exact-match check below, AND a
+    // second, --hook-form entry got appended alongside it — the old hook
+    // stays active, still resolving the author's config.json identity in
+    // every unrelated machine-wide session, exactly the identity-leak class
+    // of bug the --hook form exists to close (same shape as the pre-fix
+    // SessionStart bug above). Fixed with the identical in-place-migration
+    // pattern the SessionStart loop just above already uses: find an entry
+    // whose command is EXACTLY the old bare form and rewrite that SAME hook
+    // object's `command` field (same position, same object, every other
+    // field on it untouched) rather than remove-then-add.
     const stop = settings.hooks.Stop ?? [];
-    const stopAlready = JSON.stringify(stop).includes("codebus tick");
-    if (!stopAlready) {
+    let stopUpgraded = false;
+    for (const entry of stop) {
+        for (const h of entry?.hooks ?? []) {
+            if (h?.command === "codebus tick") {
+                h.command = "codebus tick --hook";
+                stopUpgraded = true;
+            }
+        }
+    }
+    // Luna finding: same class of bug as the SessionStart check above — a
+    // serialized substring match ("codebus tick" over the WHOLE Stop array) is
+    // fooled by any unrelated hook whose description/command/argument happens
+    // to contain those words, silently suppressing the real install while the
+    // installer still reports success. Exact command-field match instead,
+    // mirroring installCodexHooks's Stop-hook check below.
+    const stopAlready = hookEventHasCommand(stop, "codebus tick --hook");
+    if (stopUpgraded) {
+        settings.hooks.Stop = stop;
+        console.log(`${OK} Stop hook upgraded → codebus tick --hook (new-mail surfacing at turn boundaries)`);
+    }
+    else if (!stopAlready) {
         stop.push(STOP_HOOK);
         settings.hooks.Stop = stop;
         console.log(`${OK} Stop hook → codebus tick --hook (new-mail surfacing at turn boundaries)`);
@@ -109,8 +171,21 @@ async function installClaude(o) {
         console.log(`${OK} Stop hook already installed`);
     }
     mkdirSync(join(homedir(), ".claude"), { recursive: true });
-    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
-    console.log(`${OK} Wrote ${path}${existsSync(`${path}.codebus-backup`) ? ` (backup: ${path}.codebus-backup)` : ""}`);
+    const newText = JSON.stringify(settings, null, 2) + "\n";
+    const backupPath = `${path}.codebus-backup`;
+    // Same lock+atomic-write+TOCTOU-guard machinery installMcp/installCodexMcp/
+    // installCodexHooks already use. `existingText` is what THIS call
+    // originally read; if another `codebus install claude` (or a hand edit)
+    // changed the file in between, this aborts as `reason: "changed"` — fatal
+    // here (process.exit(1)), matching this function's own pre-existing
+    // "can't safely write settings.json → exit(1)" contract (see the parse-
+    // error catch above) rather than silently clobbering the concurrent edit.
+    const result = writeIfUnchanged(path, existingText, newText, existingText ? backupPath : undefined);
+    if (!result.ok) {
+        console.log(`${WARN} ${describeWriteFailure(result, path)} Re-run \`codebus install claude\`.`);
+        process.exit(1);
+    }
+    console.log(`${OK} Wrote ${path}${existingText ? ` (backup: ${backupPath})` : ""}`);
     // Verify the statusline path works (local read only — never network).
     const snap = await readCachedDigest();
     console.log(snap
@@ -147,6 +222,19 @@ const CODEX_SESSION_START_HOOK_GROUP = { hooks: [{ type: "command", command: "co
  * auto-check installed" when this silently failed to write anything, or a
  * malformed/unreadable hooks.json leaves the user believing coverage exists
  * when it doesn't (an undetected mail-delivery gap).
+ *
+ * Luna finding: this used to read, mutate, and `writeFileSync` the file
+ * directly — no lock, no atomic temp-file rename, no TOCTOU re-check —
+ * despite installMcp/installCodexMcp/installClaude's settings.json and
+ * config.toml writes ALL having already been brought under
+ * writeIfUnchanged()/acquireConfigLock()/atomicWriteFileSync() elsewhere in
+ * this file. Two concurrent `codebus install codex` runs could both read
+ * the same old file and the later plain write would silently discard the
+ * other run's changes; a Codex process reading hooks.json mid-write could
+ * also observe a partially-written file and fail to load its hooks. Now
+ * routed through the SAME existing machinery every other managed config
+ * file in this installer already gets — the read/validate/mutate logic
+ * below is otherwise unchanged, only the final write mechanism is.
  */
 // A plain JSON object: not null, not an array. Used to validate every level
 // of hooks.json we're about to read/mutate — ai-review finding: checking only
@@ -160,12 +248,14 @@ const CODEX_SESSION_START_HOOK_GROUP = { hooks: [{ type: "command", command: "co
 function isPlainObject(x) {
     return typeof x === "object" && x !== null && !Array.isArray(x);
 }
-function installCodexHooks() {
+export function installCodexHooks() {
     const path = CODEX_HOOKS_FILE();
     let file = {};
+    let existingText = "";
     try {
         if (existsSync(path)) {
-            const parsed = JSON.parse(readFileSync(path, "utf8"));
+            existingText = readFileSync(path, "utf8");
+            const parsed = JSON.parse(existingText);
             if (!isPlainObject(parsed)) {
                 throw new Error(`expected a JSON object at the top level, got ${Array.isArray(parsed) ? "an array" : typeof parsed}`);
             }
@@ -179,7 +269,10 @@ function installCodexHooks() {
                 }
             }
             file = parsed;
-            copyFileSync(path, `${path}.codebus-backup`); // never destroy user hooks
+            // Backup is now handled by writeIfUnchanged()'s own atomic backup
+            // write below (against whatever the file's content actually is right
+            // before the write, not this initial read) — no separate copyFileSync
+            // needed here any more.
         }
     }
     catch (e) {
@@ -211,22 +304,156 @@ function installCodexHooks() {
         console.log(`${OK} Codex SessionStart hook already installed`);
     }
     mkdirSync(join(homedir(), ".codex"), { recursive: true });
-    writeFileSync(path, JSON.stringify(file, null, 2) + "\n");
-    console.log(`${OK} Wrote ${path}${existsSync(`${path}.codebus-backup`) ? ` (backup: ${path}.codebus-backup)` : ""}`);
+    const newText = JSON.stringify(file, null, 2) + "\n";
+    const backupPath = `${path}.codebus-backup`;
+    // Same lock+atomic-write+TOCTOU-guard machinery installMcp/installCodexMcp/
+    // installClaude's settings.json and config.toml writes already use — see
+    // writeIfUnchanged. `existingText` is what THIS call originally read; if
+    // another `codebus install codex` (or a hand edit) changed the file in
+    // between, this aborts as `reason: "changed"` rather than silently
+    // clobbering it, instead of the bare writeFileSync this replaces, which
+    // had no such check at all.
+    const result = writeIfUnchanged(path, existingText, newText, existingText ? backupPath : undefined);
+    if (!result.ok) {
+        console.log(`${WARN} ${describeWriteFailure(result, path)} Re-run \`codebus install codex\`.`);
+        return false;
+    }
+    console.log(`${OK} Wrote ${path}${existingText ? ` (backup: ${backupPath})` : ""}`);
     return true;
 }
-export function installCodex() {
+/**
+ * Luna finding: the wrapper written below shadows `codex` on PATH (per the
+ * `export PATH="$HOME/.codebus/bin:$PATH"` instruction this function
+ * prints), and its own body used to `exec codex "$@"` — a BARE name, not an
+ * absolute path. Bash's `exec` re-resolves a bare command against the
+ * CURRENT PATH on every invocation; since the wrapper never strips its own
+ * directory out of that PATH first, `codex` inside the wrapper's own body
+ * resolves right back to the SAME wrapper. Confirmed empirically with a
+ * standalone reproduction of this exact script and PATH ordering: it hangs
+ * indefinitely (an unbounded chain of `exec` self-replacements — not a stack
+ * overflow, since `exec` replaces the process image each time, just a
+ * process that never reaches the real Codex and never returns). Codex would
+ * never actually start. Confirmed via `git log -S` that this shape has
+ * existed since the wrapper's introduction (commit 9b51231) — pre-existing,
+ * not introduced by this PR's earlier changes; found and fixed now.
+ *
+ * Fixed by resolving the REAL `codex` binary's absolute path ONCE, here, at
+ * wrapper-GENERATION time — searching PATH in the same left-to-right order a
+ * shell would, but excluding `excludeDir` (our own ~/.codebus/bin) so a
+ * re-run of `codebus install codex`, with the wrapper already active on this
+ * process's own PATH, can't find itself and hardcode its own path back into
+ * itself. The resolved absolute path is then hardcoded into the wrapper's
+ * `exec` line instead of a bare name — simpler and more robust than trying
+ * to strip/reconstruct PATH inside the wrapper script itself, and it means
+ * the wrapper's behavior no longer depends on whatever PATH happens to be
+ * live at the moment it runs.
+ *
+ * Luna follow-up finding: `join(dir, "codex")` alone does NOT make the
+ * result absolute — if a PATH entry is itself relative (e.g. `./bin`, a real
+ * if unusual PATH entry), the candidate stays relative too, and `statSync`
+ * still finds it because it resolves against THIS process's cwd at
+ * generation time. But the STRING gets hardcoded into the wrapper verbatim,
+ * so a later invocation from a different cwd would resolve that same
+ * relative string against ITS cwd instead and fail to find Codex — silently
+ * reintroducing a cwd-dependence the whole point of hardcoding was to
+ * remove. Fixed by canonicalizing the match through `realpathSync` before
+ * returning it: guaranteed absolute, and it also collapses any `.`/`..`
+ * segments or symlinks, which for an already-absolute, non-symlinked PATH
+ * entry is a no-op (returns the same path) but for anything else produces
+ * the genuinely stable target the wrapper needs. Wrapped in its own
+ * try/catch — realpathSync failing here (e.g. a symlink loop) just means
+ * this candidate isn't usable; the loop's existing "keep looking" contract
+ * already handles that correctly by falling through to the next PATH entry.
+ *
+ * Luna follow-up finding: `st.mode & 0o111` only asks "does SOME execute
+ * bit exist anywhere in this file's mode (owner, group, OR other)" — it
+ * says nothing about whether THIS process, running as this uid/gid, is
+ * actually one of the parties that bit applies to. A file mode 0700 owned
+ * by root has an execute bit set, so the old check accepted it — but an
+ * ordinary user's process can't execute it (only root can), and would hit
+ * a real EACCES the moment the generated wrapper actually tried to run it,
+ * long after `codebus install codex` had already reported success. Fixed by
+ * also requiring `accessSync(candidate, X_OK)` to succeed — the correct,
+ * kernel-backed way to ask "can the CALLING process execute this," which
+ * properly accounts for uid/gid/mode-bit interaction rather than eyeballing
+ * the mode bits ourselves. Wrapped in the same try/catch as the existing
+ * per-candidate checks: accessSync throwing (EACCES, or the file
+ * disappearing between statSync and here) just means this candidate isn't
+ * usable — keep looking, same as any other per-candidate failure.
+ */
+function resolveRealCodexBinary(excludeDir) {
+    const pathEnv = process.env.PATH ?? "";
+    let excludeReal = null;
+    try {
+        excludeReal = realpathSync(excludeDir);
+    }
+    catch { /* doesn't exist yet — nothing to exclude */ }
+    for (const dir of pathEnv.split(delimiter)) {
+        if (!dir)
+            continue;
+        if (dir === excludeDir)
+            continue;
+        let dirReal = null;
+        try {
+            dirReal = realpathSync(dir);
+        }
+        catch { /* dir may not exist on disk — fall through to the raw-string check above */ }
+        if (dirReal !== null && excludeReal !== null && dirReal === excludeReal)
+            continue;
+        const candidate = join(dir, "codex");
+        try {
+            const st = statSync(candidate);
+            if (st.isFile() && (st.mode & 0o111) !== 0) {
+                accessSync(candidate, fsConstants.X_OK); // throws if THIS process can't actually execute it (wrong uid/gid, etc.) — caught below, keep looking
+                return realpathSync(candidate); // canonical absolute path — first match wins, same as shell PATH resolution
+            }
+        }
+        catch { /* not here, not executable by us, or not resolvable — keep looking */ }
+    }
+    return null;
+}
+/** Safely single-quotes a string for embedding in a POSIX sh/bash command line. */
+function shQuoteSingle(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+export async function installCodex(o = {}) {
     const binDir = join(homedir(), ".codebus", "bin");
     const wrapper = join(binDir, "codex");
     mkdirSync(binDir, { recursive: true });
+    const realCodexPath = resolveRealCodexBinary(binDir);
+    if (!realCodexPath) {
+        console.log(`${WARN} Could not find a real \`codex\` binary anywhere on PATH (excluding ${binDir}) — refusing to write a wrapper that could never launch Codex.`);
+        console.log(`   Install Codex first (so a real \`codex\` executable is reachable on PATH), then re-run \`codebus install codex\`.`);
+        process.exit(1);
+    }
     // Safer v1 (deliberate): session start only. No auto session-end posts until
     // users trust the ritual — an unwanted handoff message erodes trust fast.
+    //
+    // Luna/PR#110 finding: this wrapper shadows `codex` on PATH, so it fires on
+    // EVERY invocation of the `codex` binary on the machine — a human's own
+    // deliberate terminal session and any unattended/automated launch alike;
+    // the wrapper has no way to tell those apart, and `runStart` never blocks
+    // on input either way, so there is no legitimate case here that needs the
+    // plain (non-hook) path's fuller identity resolution. Plain `codebus
+    // session start` calls resolveConfig() directly, which — unlike --hook —
+    // lets identitySource "file" (the bare author-credential fallback) through;
+    // that's precisely how a machine-wide wrapper like this one ends up
+    // orienting an unrelated Codex launch as the author's own personal agent
+    // identity. `--hook` applies the same identity-explicit-or-silent contract
+    // this repo already uses for the JSON SessionStart hooks above (see
+    // CODEX_SESSION_START_HOOK_GROUP / hookEventHasCommand): only ever prints
+    // when identity resolves via this session's own checkin or a deliberate
+    // cwd binding, silent otherwise, and swallows every failure internally
+    // (see startCmd's hook branch in session.ts) rather than throwing. The
+    // trailing `|| true` is kept anyway as a second, redundant layer of the
+    // same "a bus outage must never block coding" guarantee — belt and
+    // suspenders, not load-bearing on its own now.
     writeFileSync(wrapper, [
         "#!/usr/bin/env bash",
         "# CodeBus wrapper: pull the bus before Codex starts. Best-effort — a bus",
         "# outage must never block coding.",
-        "codebus session start || true",
-        'exec codex "$@"',
+        "codebus session start --hook || true",
+        `exec ${shQuoteSingle(realCodexPath)} "$@"`,
         "",
     ].join("\n"));
     chmodSync(wrapper, 0o755);
@@ -235,8 +462,11 @@ export function installCodex() {
     console.log(`  export PATH="$HOME/.codebus/bin:$PATH"`);
     console.log(`(session end stays manual for now: codebus session end --summary "...")`);
     // Register the MCP server so a Codex session can PULL (codebus_inbox/
-    // codebus_next) natively via tool calls.
-    installCodexMcp();
+    // codebus_next) natively via tool calls. installCodexMcp returns true when
+    // a write was NEEDED but skipped specifically because consent couldn't be
+    // obtained non-interactively — that outcome must not let this command
+    // exit 0 (see the check after installCodexHooks below).
+    const mcpConsentSkippedNonInteractively = await installCodexMcp(o);
     // Durable turn-boundary auto-check (the actual RC3 fix): wire Codex's own
     // Stop hook, same mechanism/command as Claude Code's Stop hook above. Only
     // claim coverage when the write actually succeeded (ai-review finding: a
@@ -251,6 +481,18 @@ export function installCodex() {
         console.log(`${WARN} Durable auto-check NOT installed — fix ~/.codex/hooks.json (see above) and re-run \`codebus install codex\`.`);
         console.log(`   Until then, \`codebus checkin\` falls back to arming one watch window at a time.`);
     }
+    // sol round-5 finding #2: the wrapper + hooks steps above are intentionally
+    // independent and still run regardless of the MCP step's outcome — but a
+    // non-interactive run that never got to ask for consent must not exit 0,
+    // or a script/CI run has no way to tell that from a real success. Mirrors
+    // installMcp's own non-interactive-skip handling (process.exit(1)) for
+    // consistency between the two installers, run only after every
+    // independent step above has already had its chance to complete.
+    if (mcpConsentSkippedNonInteractively) {
+        console.log(`${WARN} codebus-mcp registration in ~/.codex/config.toml needed consent but couldn't get it (no TTY, no --yes) — treat this run as incomplete.`);
+        console.log(`   Pass --yes, or re-run \`codebus install codex\` interactively.`);
+        process.exit(1);
+    }
 }
 /**
  * installMcp — register the codebus-mcp server in Claude Code settings.
@@ -259,57 +501,156 @@ export function installCodex() {
  */
 export async function installMcp(o = {}) {
     const path = CLAUDE_SETTINGS();
+    let existingText = "";
     let settings = {};
     try {
         if (existsSync(path)) {
-            settings = JSON.parse(readFileSync(path, "utf8"));
+            // Any failure here (a permissions error, a corrupt/unreadable file, a
+            // JSON syntax error) must abort loudly, never be silently treated as
+            // "file doesn't exist" — existsSync() already told us it does (sol
+            // round-2 finding #4: only ENOENT may ever mean "safe to treat as
+            // absent"; existsSync()+readFileSync() throwing here is by
+            // construction NOT that case).
+            existingText = readFileSync(path, "utf8");
+            const parsed = JSON.parse(existingText);
+            // Luna/PR#110 finding: a syntactically valid settings.json can still
+            // have the WRONG shape — e.g. "mcpServers": [] (an array, not an
+            // object). Without this check, `mcpServers.codebus` reads as
+            // undefined, so the drift branch never fires, and the fresh-
+            // registration branch's `settings.mcpServers.codebus = mcpConfig`
+            // sets a non-index property on an ARRAY — syntactically legal in JS,
+            // but JSON.stringify silently DROPS non-index properties on arrays.
+            // The write would then "succeed" (valid JSON goes out, the command
+            // reports success) having registered nothing at all. Same validation
+            // style installCodexHooks already uses for its own file: fail
+            // closed with a clear, specific message rather than silently
+            // mis-writing or claiming success.
+            if (!isPlainObject(parsed)) {
+                throw new Error(`expected a JSON object at the top level, got ${Array.isArray(parsed) ? "an array" : typeof parsed}`);
+            }
+            if (parsed.mcpServers !== undefined && !isPlainObject(parsed.mcpServers)) {
+                throw new Error(`expected "mcpServers" to be a JSON object, got ${Array.isArray(parsed.mcpServers) ? "an array" : typeof parsed.mcpServers}`);
+            }
+            settings = parsed;
         }
     }
     catch (e) {
-        console.log(`${WARN} Could not parse ${path}: ${e.message}`);
+        console.log(`${WARN} Could not read/parse ${path}: ${e.message}`);
         console.log("Manual fallback — add to ~/.claude/settings.json:");
         printMcpServerConfig();
         process.exit(1);
     }
     // Prepare the MCP server config.
     const mcpConfig = buildMcpServerConfig();
-    // Check if already installed.
+    const currentIsCheckout = isDevLinkedInstall();
+    printDevCheckoutWarning(currentIsCheckout);
+    assertMcpServerPathExists(mcpConfig);
+    // Check if already installed — and if so, whether the registered pointer
+    // has drifted from the canonical one this running install would write
+    // today. See decideMcpPointerAction() for the bug this guards: a one-shot
+    // "already registered, no-op forever" check let a stale/mutable pointer
+    // (e.g. written from a dev checkout) survive every future `install mcp`
+    // re-run with no way to self-heal. DESIGN (sol round 2): every drift heal
+    // — regardless of direction — requires the SAME explicit consent as a
+    // fresh registration. Earlier revisions tried to auto-heal the "obviously
+    // safe" direction unattended, gated on an ownership check; sol correctly
+    // pointed out that check is forgeable (a copied manifest or symlinked
+    // target can satisfy it) and isn't a sound basis for an unattended write.
+    // Ownership is now purely ADVISORY — it colors the confirmation prompt's
+    // wording, never whether a prompt happens at all.
     const mcpServers = settings.mcpServers ?? {};
     if (mcpServers.codebus) {
-        console.log(`${OK} codebus-mcp already registered in mcpServers`);
+        const decision = decideMcpPointerAction(mcpServers.codebus, mcpConfig, currentIsCheckout);
+        if (decision.kind === "noop") {
+            console.log(`${OK} codebus-mcp already registered in mcpServers`);
+            return;
+        }
+        if (decision.kind === "unrecognized-shape") {
+            console.log(`${WARN} codebus-mcp is already registered in mcpServers but not in the shape \`codebus install mcp\` writes (looks hand-edited or customized) — leaving it untouched.`);
+            console.log(`   If this should be reset, remove the "codebus" entry from ${path} and re-run \`codebus install mcp\`.`);
+            return;
+        }
+        // decision.kind === "consent-required" — ALWAYS, for every drift.
+        printDriftConsentExplanation(path, decision.oldPointer, mcpConfig.args[0], decision.existingOwnership, decision.currentIsCheckout);
+        const driftConsent = await requestConsent(o, "Update the registered codebus-mcp pointer? (y/n): ");
+        if (driftConsent === "non-interactive") {
+            console.log(`${WARN} non-interactive: re-run with --yes to accept this pointer update`);
+            process.exit(1);
+        }
+        if (driftConsent === "declined") {
+            console.log(`${WARN} Pointer left unchanged.`);
+            return;
+        }
+        // Surgical patch: rewrite ONLY mcpServers.codebus's value, byte-for-byte
+        // preserving everything else in the file (indentation, unrelated keys,
+        // formatting) — a full JSON.parse+stringify round trip would silently
+        // renormalize all of that for an edit the user approved by DIFF, not by
+        // re-reading the whole file.
+        const patched = replaceJsonValue(existingText, ["mcpServers", "codebus"], JSON.stringify(mcpConfig));
+        if (patched === null) {
+            // Either the value genuinely isn't there any more (shouldn't happen —
+            // we just parsed this exact document above), OR findJsonValueSpan
+            // detected a duplicate key along the path and refused to guess which
+            // occurrence is real (sol round-2 finding #2). Either way: never fall
+            // back to a full reserialize here; fail loudly instead of silently
+            // reformatting or patching the wrong occurrence.
+            console.log(`${WARN} Could not surgically patch ${path} (possibly a duplicate "mcpServers" or "codebus" key) — leaving it untouched. Please resolve any duplicate keys and update mcpServers.codebus by hand.`);
+            return;
+        }
+        mkdirSync(join(homedir(), ".claude"), { recursive: true });
+        const backupPath = `${path}.codebus-backup`;
+        const result = writeIfUnchanged(path, existingText, patched, backupPath);
+        if (!result.ok) {
+            console.log(`${WARN} ${describeWriteFailure(result, path)} Re-run \`codebus install mcp\`.`);
+            process.exit(1);
+        }
+        console.log(`${OK} codebus-mcp pointer updated (was pointing at ${decision.oldPointer}, drifted from the current install)`);
+        console.log(`${OK} Backup saved to ${backupPath}`);
         return;
     }
-    // A12 / artifacts-hook policy: non-interactive without explicit opt-in → abort.
-    // Non-TTY (piped, CI, another tool) + no --yes → user cannot consent.
-    if (!process.stdin.isTTY && !o.yes) {
-        console.log(`${WARN} non-interactive: re-run with --yes to opt in`);
-        process.exit(1);
-    }
-    // Print what will be written (A12 explicit consent gate).
+    // Print what will be written (A12 explicit consent gate). Full disclosure
+    // (sol round-2 finding #7): this write reserializes the ENTIRE file, not
+    // just inserts the fragment shown below — say so explicitly so consent to
+    // the diff isn't mistaken for consent to an undisclosed whole-file
+    // transformation (formatting/duplicate-key normalization included).
     console.log("\nWill register codebus-mcp in ~/.claude/settings.json:\n");
     console.log(JSON.stringify({ mcpServers: { codebus: mcpConfig } }, null, 2));
     console.log();
-    // Confirm before writing (interactive mode only — non-TTY would have aborted above).
-    if (!o.yes) {
-        const answer = await getUserConfirmation("Proceed with registration? (y/n): ");
-        if (!answer.toLowerCase().startsWith("y")) {
-            console.log(`${WARN} Installation cancelled.`);
-            process.exit(0);
-        }
+    if (existingText) {
+        console.log(`${WARN} This reserializes the ENTIRE file — formatting, key order, and any duplicate keys will be`);
+        console.log(`   normalized to a fresh JSON.stringify, not just have this fragment inserted in place.`);
+    }
+    // A12 / artifacts-hook policy: explicit consent required (non-TTY + no
+    // --yes → user cannot consent → abort).
+    const freshConsent = await requestConsent(o, "Proceed with registration? (y/n): ");
+    if (freshConsent === "non-interactive") {
+        console.log(`${WARN} non-interactive: re-run with --yes to opt in`);
+        process.exit(1);
+    }
+    if (freshConsent === "declined") {
+        console.log(`${WARN} Installation cancelled.`);
+        process.exit(0);
     }
-    // Write the config.
+    // Write the config. This is a first-time, explicitly-confirmed write (the
+    // user just saw and approved the exact JSON above, plus the disclosure
+    // that it reserializes the whole file), so a full reserialize is
+    // acceptable here — unlike the drift repair above, which patches only the
+    // one value it's allowed to touch.
     mkdirSync(join(homedir(), ".claude"), { recursive: true });
     if (!settings.mcpServers) {
         settings.mcpServers = {};
     }
     settings.mcpServers.codebus = mcpConfig;
-    // Backup existing config.
-    if (existsSync(path)) {
-        copyFileSync(path, `${path}.codebus-backup`);
+    const newText = JSON.stringify(settings, null, 2) + "\n";
+    const backupPath = `${path}.codebus-backup`;
+    const freshResult = writeIfUnchanged(path, existingText, newText, existingText ? backupPath : undefined);
+    if (!freshResult.ok) {
+        console.log(`${WARN} ${describeWriteFailure(freshResult, path)} Re-run \`codebus install mcp --yes\`.`);
+        process.exit(1);
     }
-    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
     console.log(`${OK} Registered codebus-mcp in ${path}`);
-    console.log(`${OK} Backup saved to ${path}.codebus-backup`);
+    if (existingText)
+        console.log(`${OK} Backup saved to ${backupPath}`);
     console.log("\nCodeBus MCP tools are now available in Claude Code:");
     console.log("  • ask_graph — Query CodeBus graph snapshot");
     console.log("  • codebus_state — Session digest (counts, next item)");
@@ -329,8 +670,20 @@ export async function installMcp(o = {}) {
     console.log("  • graph_search — Search a connected repo's remote graph");
     console.log("  • blast_radius — What breaks if I change this (local or remote)");
     console.log("  • graph_gaps — Knowledge gaps in a connected repo's graph");
+    console.log("  • ticket_suspect_code — Rank code evidence related to a ticket");
     console.log("  • plan_status — Per-plan task/ticket/PR/coverage/health rollup");
     console.log("  • delivery_status — Paginated per-plan delivery + quality rollup");
+    console.log("  • doc_add — Store a shared text document");
+    console.log("  • doc_get — Fetch a shared text document");
+    console.log("  • plan_list — List visible plans");
+    console.log("  • plan_show — Show one visible plan");
+    console.log("  • plan_who — List current plan assignments");
+    console.log("  • plan_stuck — List currently stuck plans");
+    console.log("  • knowledge_list — List knowledge items");
+    console.log("  • knowledge_show — Show a knowledge item");
+    console.log("  • digest — Fetch the current attention digest");
+    console.log("  • factory_run_status — Get factory run status");
+    console.log("  • factory_run_events — Get factory run events");
 }
 function buildMcpServerConfig() {
     // Absolute paths, deliberately: a bare "codebus-mcp" resolves only through
@@ -346,15 +699,77 @@ function buildMcpServerConfig() {
         args: [join(dirname(fileURLToPath(import.meta.url)), "..", "mcp.js")],
     };
 }
+/**
+ * Luna/PR#110 finding: buildMcpServerConfig() computes args[0] relative to
+ * THIS module's own location (import.meta.url). When running from a BUILT
+ * checkout that's .../dist/commands/install.js, so args[0] lands on
+ * .../dist/mcp.js — which the build step actually produces. But when the
+ * CLI runs directly from source with no build step (e.g. `npm run dev`,
+ * tsx/ts-node), import.meta.url is under .../src/commands/install.ts
+ * instead, so the SAME computation lands on .../src/mcp.js — which does not
+ * exist; the source file is src/mcp.ts, never compiled to .js in place.
+ * isDevLinkedInstall()'s warning above is a DIFFERENT, survivable risk (a
+ * MUTABLE pointer that can later break); this is a pointer that cannot ever
+ * launch, from the moment it's written. Deliberately a general existsSync
+ * check rather than special-casing the .ts/.js mismatch specifically — it
+ * equally catches any OTHER future reason the computed path might not
+ * exist (a broken build, a relocated install, …). Called before ANY write
+ * (fresh registration or drift-heal) in both installMcp and installCodexMcp;
+ * never called from printMcpServerConfig()'s manual-fallback path, which
+ * must keep printing best-effort instructions to a human even when this
+ * check would fail (that path is presented, not executed).
+ */
+function assertMcpServerPathExists(mcpConfig) {
+    const mcpJsPath = mcpConfig.args[0];
+    // Luna finding: existsSync() alone returns true for a DIRECTORY too — a
+    // directory happening to sit at the computed path (an odd but real
+    // possibility: a botched build, a stray mkdir) would pass this check and
+    // let a pointer that can never launch (Node can't `node <a directory>`)
+    // get written anyway, contradicting this function's whole purpose.
+    // statSync(...).isFile() is the real check; wrapped in try/catch since
+    // statSync throws on a path that doesn't exist at all, which must be
+    // treated identically to "not a file" (the existing not-found case below).
+    let isFile = false;
+    try {
+        isFile = statSync(mcpJsPath).isFile();
+    }
+    catch { /* doesn't exist — not a file either */ }
+    if (isFile)
+        return;
+    console.log(`${WARN} Computed codebus-mcp server path does not exist: ${mcpJsPath}`);
+    console.log(`   Registering this pointer would leave Claude/Codex unable to start the MCP server on next launch — refusing to write it.`);
+    console.log(`   This usually means the CLI is running from source with no build step (e.g. \`npm run dev\`) — run \`npm run build\` first, or install the published package (\`codebus upgrade\`).`);
+    process.exit(1);
+}
 /**
  * Register the codebus MCP server in Codex's ~/.codex/config.toml
  * ([mcp_servers.codebus]). Append-only with a backup — Codex configs carry
  * hand-written sections (the user's real one has several mcp_servers already),
- * so we never parse/rewrite, only add our section when it's absent.
+ * so we never parse/rewrite the rest of the file, only add our section when
+ * it's GENUINELY absent (per findTopLevelTableBlock's lexically-aware
+ * search — never a raw substring match, AND never when the cheaper
+ * mightReferenceOurTable() fallback sniff finds a plausible-but-unsupported
+ * trace of the table, e.g. array-of-tables syntax) — or, when present but
+ * its pointer has drifted from the canonical one this install computes
+ * today, rewrite just the command/args VALUES of OUR OWN section in place,
+ * ALWAYS with explicit consent first (see decideMcpPointerAction()).
+ *
+ * Returns true when a write was NEEDED but skipped specifically because
+ * consent couldn't be obtained non-interactively (no TTY, no --yes) — sol
+ * round-5 finding #2: installCodex previously completed (and the overall
+ * process exited 0) in this case exactly as if registration had succeeded,
+ * which a script or CI run has no way to tell apart from success. Every
+ * OTHER skip reason (unrecognized shape, unreadable file, an interactive
+ * decline, an already-matching pointer, a write that failed for its own
+ * reason) returns false — those are deliberate, already-explained outcomes,
+ * not "we never even got to ask."
  */
-function installCodexMcp() {
+async function installCodexMcp(o = {}) {
     const path = join(homedir(), ".codex", "config.toml");
     const cfg = buildMcpServerConfig();
+    const currentIsCheckout = isDevLinkedInstall();
+    printDevCheckoutWarning(currentIsCheckout);
+    assertMcpServerPathExists(cfg);
     const section = [
         "",
         "# CodeBus MCP server (written by `codebus install codex`)",
@@ -364,20 +779,673 @@ function installCodexMcp() {
         "",
     ].join("\n");
     let existing = "";
+    let fileExisted = false;
     try {
         existing = readFileSync(path, "utf8");
+        fileExisted = true;
     }
-    catch { /* no config yet — we'll create it */ }
-    if (existing.includes("[mcp_servers.codebus]")) {
-        console.log(`${OK} codebus MCP already registered in ${path}`);
-        return;
+    catch (e) {
+        const err = e;
+        if (err.code !== "ENOENT") {
+            // Only ENOENT may mean "no config yet, safe to create fresh" (sol
+            // round-2 finding #4). Anything else — EACCES, a corrupt/unreadable
+            // file, a symlink loop — must abort loudly: silently treating an
+            // existing-but-unreadable file as empty risks appending our section
+            // into what we WRONGLY believe is a brand-new file, potentially
+            // discarding everything already there.
+            console.log(`${WARN} Could not read ${path}: ${err.message} — leaving Codex MCP registration untouched.`);
+            console.log(`   Manual fallback — add to ${path}:`);
+            console.log(`     [mcp_servers.codebus]`);
+            console.log(`     command = ${JSON.stringify(cfg.command)}`);
+            console.log(`     args = [${cfg.args.map((a) => JSON.stringify(a)).join(", ")}]`);
+            return false; // soft — installCodex's remaining steps (hooks etc.) still run; not a consent-skip
+        }
+        // ENOENT: genuinely no config yet — the ONE case that skips consent below.
+    }
+    const block = findTopLevelTableBlock(existing, ["mcp_servers", "codebus"]);
+    if (block !== null) {
+        const blockText = existing.slice(block.blockStart, block.blockEnd);
+        const parsed = parseSimpleTomlTable(blockText); // null when the body isn't a simple key="string"/["string"] shape we can safely reason about
+        const decision = decideMcpPointerAction(parsed, cfg, currentIsCheckout);
+        if (decision.kind === "noop") {
+            console.log(`${OK} codebus MCP already registered in ${path}`);
+            return false;
+        }
+        if (decision.kind === "unrecognized-shape") {
+            console.log(`${WARN} [mcp_servers.codebus] already exists in ${path} but not in the shape \`codebus install codex\` writes (looks hand-edited, customized, or uses TOML syntax we don't safely rewrite) — leaving it untouched.`);
+            console.log(`   If this should be reset, remove that section from ${path} and re-run \`codebus install codex\`.`);
+            return false;
+        }
+        // decision.kind === "consent-required" — ALWAYS, for every drift.
+        printDriftConsentExplanation(path, decision.oldPointer, cfg.args[0], decision.existingOwnership, decision.currentIsCheckout);
+        const driftConsent = await requestConsent(o, "Update the registered codebus MCP pointer? (y/n): ");
+        if (driftConsent === "non-interactive") {
+            console.log(`${WARN} non-interactive: re-run \`codebus install codex --yes\` to accept this pointer update`);
+            return true; // soft on installCodex's OTHER steps (hooks etc. still run) — but the OVERALL command must exit nonzero (sol round-5 finding #2)
+        }
+        if (driftConsent === "declined") {
+            console.log(`${WARN} Pointer left unchanged.`);
+            return false; // the human was asked, and answered — not a "never got to ask" outcome
+        }
+        const updatedBlock = replaceSimpleTomlValues(blockText, { command: cfg.command, args: cfg.args });
+        if (updatedBlock === null) {
+            // Shouldn't happen — parseSimpleTomlTable already proved this block
+            // tokenizes cleanly — but never fall back to a cruder rewrite; fail
+            // loudly instead of guessing at the file's structure.
+            console.log(`${WARN} Could not surgically patch ${path} — leaving it untouched. Please update [mcp_servers.codebus] by hand.`);
+            return false;
+        }
+        const updatedText = existing.slice(0, block.blockStart) + updatedBlock + existing.slice(block.blockEnd);
+        mkdirSync(join(homedir(), ".codex"), { recursive: true });
+        const backupPath = `${path}.codebus-backup`;
+        const result = writeIfUnchanged(path, existing, updatedText, backupPath);
+        if (!result.ok) {
+            console.log(`${WARN} ${describeWriteFailure(result, path)} Re-run \`codebus install codex\`.`);
+            return false;
+        }
+        console.log(`${OK} codebus-mcp pointer updated in ${path} (was pointing at ${decision.oldPointer}, drifted from the current install)`);
+        console.log(`${OK} Backup saved to ${backupPath}`);
+        return false;
+    }
+    // Our strict scanner found no genuine table — but "null" is also what a
+    // structurally-unsupported-but-real header produces (array-of-tables, a
+    // BOM/escape edge case, anything neither scanner anticipated). Appending
+    // our own section in that case risks invalid/duplicate/conflicting TOML
+    // (sol round-2 finding #3). Only conclude "genuinely absent" when there's
+    // no trace of the marker at all.
+    if (mightReferenceOurTable(existing)) {
+        console.log(`${WARN} ${path} seems to already reference an mcp_servers.codebus table in a form \`codebus install codex\` doesn't recognize (e.g. array-of-tables syntax) — leaving it untouched rather than risking a duplicate or conflicting table.`);
+        console.log(`   Please check ${path} manually.`);
+        return false;
+    }
+    // The table is genuinely absent — but that's not on its own license to
+    // write unattended (sol round-4 finding #1): a config.toml that already
+    // EXISTS (any content, ours or not) gets the same consent gate as every
+    // other write in this file. Only a config.toml that doesn't exist AT ALL
+    // yet — the very first time this file is created — is exempt, matching
+    // Codex's long-standing "we create this file once, no confirmation
+    // needed" convention (unchanged since before this security review).
+    if (fileExisted) {
+        console.log(`\nWill register [mcp_servers.codebus] in ${path} (which already exists):\n`);
+        console.log(section.trim());
+        console.log();
+        const freshConsent = await requestConsent(o, "Add this section to the existing file? (y/n): ");
+        if (freshConsent === "non-interactive") {
+            console.log(`${WARN} non-interactive: re-run \`codebus install codex --yes\` to register codebus-mcp in ${path}`);
+            return true; // soft on installCodex's OTHER steps (hooks etc. still run) — but the OVERALL command must exit nonzero (sol round-5 finding #2)
+        }
+        if (freshConsent === "declined") {
+            console.log(`${WARN} Registration skipped; ${path} left unchanged.`);
+            return false; // the human was asked, and answered — not a "never got to ask" outcome
+        }
     }
-    if (existing)
-        copyFileSync(path, `${path}.codebus-backup`);
     mkdirSync(join(homedir(), ".codex"), { recursive: true });
-    writeFileSync(path, existing + section);
-    console.log(`${OK} Registered [mcp_servers.codebus] in ${path}${existing ? ` (backup: ${path}.codebus-backup)` : ""}`);
+    const backupPath = `${path}.codebus-backup`;
+    const freshResult = writeIfUnchanged(path, existing, existing + section, fileExisted ? backupPath : undefined);
+    if (!freshResult.ok) {
+        console.log(`${WARN} ${describeWriteFailure(freshResult, path)} Re-run \`codebus install codex\`.`);
+        return false;
+    }
+    console.log(`${OK} Registered [mcp_servers.codebus] in ${path}${fileExisted ? ` (backup: ${backupPath})` : ""}`);
     console.log(`   Codex sessions get the ${TOOL_REGISTRY.length} codebus tools on next launch.`);
+    return false;
+}
+/**
+ * Resolves an MCP pointer's args[0] (an mcp.js path) to the package root that
+ * looks like it OWNS it, by resolving symlinks (tightening sol round-2
+ * finding #1's suggestion for prompt accuracy) and reading THAT root's own
+ * package.json for a matching name — not just trusting that the path shape
+ * "looks like ours" (a hand-written wrapper can trivially end its one arg
+ * in "mcp.js" too).
+ *
+ * IMPORTANT — this is now ADVISORY ONLY (sol round-2 finding #1): earlier
+ * revisions treated a successful resolution here as a security boundary
+ * that gated an UNATTENDED write. That was unsound — a copied manifest, a
+ * symlinked target, or an unrelated checkout of this same repo can all
+ * satisfy "package.json says @bragi-gmbh/codebus" without this installer
+ * having ever written the entry being examined. Since every drift heal now
+ * requires a human's explicit consent (decideMcpPointerAction never
+ * auto-writes), this function's result only colors the CONFIRMATION
+ * PROMPT'S wording ("this looks like our own install" vs. "unrecognized —
+ * proceed carefully") — a human makes the actual call either way. Returns
+ * null when the path doesn't resolve to what looks like a real
+ * `@bragi-gmbh/codebus` install: no package.json there, a parse failure, a
+ * different package's name, or (a moved/rebuilt/deleted checkout) the path
+ * simply no longer exists.
+ */
+function resolveOwnedPackageRoot(mcpJsPath) {
+    try {
+        // Resolve symlinks where possible — a symlinked mcp.js pointing at a
+        // real codebus install should still be recognized as such. ENOENT (the
+        // common case: a moved/rebuilt/deleted checkout) falls back to the raw
+        // path, since the package root's OWN package.json may still exist even
+        // if the mcp.js file itself is currently missing.
+        let resolved = mcpJsPath;
+        try {
+            resolved = realpathSync(mcpJsPath);
+        }
+        catch { /* file may not currently exist — advisory only, not fatal */ }
+        // Our own writer always builds args[0] as <packageRoot>/(dist|src)/mcp.js
+        // (see buildMcpServerConfig) — so the package root is two levels up.
+        const pkgRoot = dirname(dirname(resolved));
+        const parsed = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+        if (isPlainObject(parsed) && parsed.name === "@bragi-gmbh/codebus")
+            return pkgRoot;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function classifyOwnership(mcpJsPath) {
+    const pkgRoot = resolveOwnedPackageRoot(mcpJsPath);
+    if (pkgRoot === null)
+        return "unknown";
+    return isCheckoutShapedPackageRoot(pkgRoot) ? "owned-checkout" : "owned-published";
+}
+/**
+ * Compares an EXISTING registered MCP server pointer (parsed out of
+ * settings.json's `mcpServers.codebus`, or config.toml's
+ * `[mcp_servers.codebus]` via toml-lite) against the CANONICAL pointer
+ * buildMcpServerConfig() computes right now for the currently-running
+ * install. See decideMcpPointerAction() for how callers turn this analysis
+ * into an action — this function only classifies, it never decides whether
+ * writing is safe.
+ */
+export function analyzeMcpPointer(existing, canonical) {
+    if (!isPlainObject(existing) || Object.keys(existing).length !== 2) {
+        return { recognized: false, matches: false, ownership: "unknown" };
+    }
+    const { command, args } = existing;
+    if (typeof command !== "string" ||
+        !Array.isArray(args) ||
+        args.length !== 1 ||
+        typeof args[0] !== "string" ||
+        !args[0].endsWith("mcp.js")) {
+        return { recognized: false, matches: false, ownership: "unknown" };
+    }
+    const args0 = args[0];
+    const matches = command === canonical.command && args0 === canonical.args[0];
+    return { recognized: true, matches, ownership: classifyOwnership(args0) };
+}
+/**
+ * Turns an McpPointerAnalysis into an action.
+ *
+ * DESIGN (sol round-2): every drift — regardless of direction, regardless
+ * of whether ownership resolves — requires explicit consent, the SAME
+ * --yes/interactive-y-n gate installMcp's fresh registration already uses.
+ * An earlier revision tried to auto-heal one "unambiguous" direction
+ * unattended, gated on resolveOwnedPackageRoot(); sol correctly found that
+ * gate forgeable (see resolveOwnedPackageRoot's docstring) — a security
+ * boundary needs to be sound, not just "usually right." Requiring consent
+ * uniformly is a real simplification, not a workaround: it collapses two
+ * write paths into one, and shrinks the TOCTOU blast radius to "did the
+ * file change between the read and the (now human-paced) write" rather
+ * than "was this decision even safe to make unattended."
+ *
+ * "unrecognized-shape" is the one case that still never even OFFERS a
+ * prompt: the existing entry isn't in the shape any version of this
+ * installer has ever written (extra keys, wrong arg count, a completely
+ * different command) — we don't have a confident diff to show, so we leave
+ * it alone with a message rather than guessing at what "the same value,
+ * updated" would even mean for it.
+ */
+export function decideMcpPointerAction(existing, canonical, currentIsCheckout) {
+    const analysis = analyzeMcpPointer(existing, canonical);
+    if (!analysis.recognized)
+        return { kind: "unrecognized-shape" };
+    if (analysis.matches)
+        return { kind: "noop" };
+    const oldPointer = existing.args[0];
+    return { kind: "consent-required", oldPointer, existingOwnership: analysis.ownership, currentIsCheckout };
+}
+function describeInstallKind(isCheckout) {
+    return isCheckout ? "a dev checkout" : "a published install";
+}
+function describeExistingOwnership(ownership) {
+    switch (ownership) {
+        case "owned-checkout": return "a dev checkout of codebus";
+        case "owned-published": return "a published codebus install";
+        case "unknown": return "an install we can't confirm is codebus (path doesn't resolve, or belongs to a different package)";
+    }
+}
+/** Explains a drift before decideMcpPointerAction's caller asks for consent to write anything. */
+function printDriftConsentExplanation(path, oldPointer, newPointer, existingOwnership, currentIsCheckout) {
+    console.log(`${WARN} codebus-mcp's registered pointer in ${path} has drifted from what this install would write:`);
+    console.log(`   currently registered: ${oldPointer}  (${describeExistingOwnership(existingOwnership)})`);
+    console.log(`   this install would write: ${newPointer}  (${describeInstallKind(currentIsCheckout)})`);
+    if (existingOwnership === "unknown") {
+        console.log(`   Ownership of the current entry couldn't be confirmed (advisory check only — never a security`);
+        console.log(`   gate) — review before proceeding; this could be a hand-configured entry that merely LOOKS`);
+        console.log(`   like ours, not a genuinely drifted codebus pointer.`);
+    }
+    else if (currentIsCheckout && existingOwnership === "owned-published") {
+        console.log(`   This would replace a stable published pointer with one from a mutable dev checkout —`);
+        console.log(`   confirm that's intentional; it will break the next time this checkout changes.`);
+    }
+    else if (currentIsCheckout && existingOwnership === "owned-checkout") {
+        console.log(`   Both the registered pointer and this install are dev checkouts — confirm this move is intentional.`);
+    }
+    else if (existingOwnership === "owned-checkout") {
+        console.log(`   The registered pointer looks like a dev checkout that's since moved, rebuilt, or been removed —`);
+        console.log(`   this looks like the common case this check exists to catch.`);
+    }
+    else {
+        console.log(`   Both pointers look like real installs, just at different paths — confirm this move is`);
+        console.log(`   intentional (e.g. an npm reinstall elsewhere) before overwriting.`);
+    }
+}
+/**
+ * Lines to print when the running install is a dev/source checkout (see
+ * isDevLinkedInstall() in version-check.ts, which this mirrors verbatim —
+ * same "src/ next to package.json" signal docs/CLI-DISTRIBUTION.md already
+ * uses to flag an arbitrary/unpinned CLI build). The MCP pointer this install
+ * computes points INTO that checkout's dist/mcp.js, which is exactly the
+ * mutable-path drift class decideMcpPointerAction() exists to catch — this
+ * warning fires at the moment of registration, before drift can happen, so
+ * the bug doesn't get reintroduced by a future `install codex`/`install mcp`
+ * run against a dev checkout. Deliberately a warning, not a hard failure:
+ * testing against a local checkout is a legitimate dev workflow.
+ */
+export function devCheckoutWarningLines(devLinked) {
+    if (!devLinked)
+        return [];
+    return [
+        `${WARN} codebus install is running from a DEV CHECKOUT (src/ present next to package.json), not the published package.`,
+        `   The MCP server pointer just registered points into THIS checkout's dist/mcp.js and will break the next`,
+        `   time this checkout changes (rebuild, git pull/checkout, deletion). If that's not intentional, install`,
+        `   the published CLI and re-run this command: codebus upgrade`,
+    ];
+}
+function printDevCheckoutWarning(currentIsCheckout) {
+    for (const line of devCheckoutWarningLines(currentIsCheckout))
+        console.log(line);
+}
+/**
+ * Same-directory temp file + fsync + atomic rename, instead of truncating
+ * the live file in place with a plain writeFileSync(path, …). Protects a
+ * concurrent reader (a Codex/Claude session reloading its config mid-write)
+ * from ever observing a partially-written file, and protects the write
+ * itself from a crash leaving `path` empty. The temp file must be in the
+ * SAME directory as the file it will replace for the rename to be atomic
+ * (no cross-filesystem rename, which the OS can't do atomically).
+ *
+ * Symlink-aware (PR #110 finding): if `path` is itself a symlink — common
+ * with dotfile managers (chezmoi, GNU stow, rcm, …) that manage
+ * ~/.claude/settings.json or ~/.codex/config.toml as a symlink into their
+ * own store — a rename() onto the symlink's OWN path would replace the
+ * symlink itself with a plain file, silently severing it from wherever it
+ * pointed. The pre-existing plain `writeFileSync(path, …)` this replaced
+ * followed the symlink and wrote through it, which is the behavior users
+ * of those tools expect. So: resolve the symlink first (realpathSync) and
+ * perform the WHOLE atomic dance (temp file + fsync + rename) against the
+ * RESOLVED target path instead — including creating the temp file in the
+ * TARGET's own directory, which may differ from the symlink's directory,
+ * since that's what the rename needs to be atomic on the same filesystem.
+ * The symlink itself is never touched; only the file it points at changes.
+ *
+ * Dangling symlinks (PR #110 follow-up finding): realpathSync throws when
+ * the symlink's target doesn't currently exist. Falling back to writing at
+ * `path` itself in that case would replace (sever) the symlink — the exact
+ * bug this function exists to avoid, just reached via a different door.
+ * Instead: resolve the symlink's own RAW target string (readlinkSync,
+ * resolved against the symlink's directory if relative) and write there —
+ * this creates the file the symlink already points at, preserving the
+ * link — but only when that target's parent directory demonstrably
+ * exists. If it doesn't, fail LOUD (a thrown Error naming the broken
+ * symlink and its target) rather than silently converting the symlink into
+ * a plain file. The old plain `writeFileSync` would likewise have errored
+ * trying to open a dangling link's nonexistent target — this matches that,
+ * rather than papering over it.
+ *
+ * Preserves the target file's POSIX mode bits (sol round-2 finding #6) —
+ * a plain new 0600 inode would otherwise silently tighten permissions on
+ * a file the user had, say, group-readable. Documented limitation: ACLs,
+ * extended attributes, and ownership beyond the mode bits are NOT
+ * preserved; acceptable for a small personal config file like this one. The
+ * containing directory is not separately fsynced, so on a crash exactly at
+ * the wrong instant the rename's durability (not its atomicity) is best-effort.
+ */
+function atomicWriteFileSync(path, data) {
+    // Resolve a symlink to its real target BEFORE doing anything else — every
+    // subsequent step (temp file location, mode read, rename destination)
+    // operates on the resolved path, so the symlink at `path` is left
+    // completely untouched. A `path` that doesn't exist at all yet falls back
+    // to operating on `path` itself, same as the non-symlink case.
+    let targetPath = path;
+    let lstat;
+    try {
+        lstat = lstatSync(path);
+    }
+    catch {
+        lstat = null; // doesn't exist yet — ordinary "brand new file" case
+    }
+    if (lstat !== null && lstat.isSymbolicLink()) {
+        try {
+            targetPath = realpathSync(path);
+        }
+        catch {
+            // Dangling: resolve the raw link target ourselves rather than ever
+            // falling back to writing at the symlink's own path.
+            const rawTarget = readlinkSync(path);
+            const resolvedTarget = isAbsolute(rawTarget) ? rawTarget : join(dirname(path), rawTarget);
+            if (!existsSync(dirname(resolvedTarget))) {
+                throw new Error(`${path} is a symlink to ${rawTarget} (resolves to ${resolvedTarget}), but that target's directory doesn't exist — refusing to replace the symlink with a plain file. Create ${dirname(resolvedTarget)} (or fix the broken symlink) and try again.`);
+            }
+            targetPath = resolvedTarget;
+        }
+    }
+    const dir = dirname(targetPath);
+    let mode = 0o600;
+    try {
+        mode = statSync(targetPath).mode & 0o777;
+    }
+    catch { /* no existing file — default to a private mode */ }
+    const { tmp, fd } = openUniqueTempFileExclusive(dir, basename(targetPath), mode);
+    // Luna finding: a throw from writeFileSync/fsyncSync used to escape through
+    // the finally below (which only closes the fd) without ever reaching the
+    // unlink in the second try/catch — leaking the uniquely-created temp file
+    // on disk. The whole write/fsync/chmod/rename sequence is now one try, so
+    // ANY failure along it — write, fsync, chmod, or rename — falls through to
+    // the same best-effort cleanup before rethrowing the original error.
+    try {
+        try {
+            writeFileSync(fd, data);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        chmodSync(tmp, mode); // openSync's mode argument is subject to umask; make it exact
+        renameSync(tmp, targetPath);
+    }
+    catch (e) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* best-effort cleanup of the temp file; swallow a secondary error here so the original `e` is what propagates */ }
+        throw e;
+    }
+}
+const TEMP_FILE_MAX_ATTEMPTS = 5;
+/**
+ * Opens a fresh, exclusively-created temp file in `dir` for the atomic-write
+ * dance above, and returns both its path and open fd.
+ *
+ * Luna/PR#110 finding: the previous name — `.${basename}.codebus-tmp-${pid}-
+ * ${Date.now()}` — is fully PREDICTABLE by anyone who can see the target
+ * directory and roughly when the installer runs (pid space is small, and
+ * Date.now() is guessable to within a small window). Worse, it was opened
+ * with plain "w", which — like a plain writeFileSync — follows an existing
+ * symlink at that path rather than refusing to touch it. Combined, a local
+ * attacker could pre-create a symlink at the exact predictable name pointing
+ * anywhere they choose (e.g. ~/.ssh/authorized_keys), and the installer
+ * would then write its config data straight through that symlink to the
+ * attacker's chosen target the next time it ran — an arbitrary-file-write
+ * primitive via a config file write nobody would think to audit for it.
+ *
+ * Fixed two ways, both required: (a) "wx" (O_CREAT|O_EXCL) instead of "w" —
+ * refuses to open if ANYTHING already exists at the path, symlink included,
+ * so a pre-placed symlink is never followed, full stop; (b) an unpredictable
+ * name (a crypto-random suffix, not just pid+timestamp) so an attacker can't
+ * even aim a symlink at the right path in the first place. (a) alone would
+ * already close the vulnerability, but without (b) an attacker who wins the
+ * race to pre-create the (still predictable) name first would simply cause
+ * our "wx" open to fail instead — a self-inflicted denial of service. Both
+ * together close the write primitive AND keep the legitimate write reliable.
+ *
+ * EEXIST from "wx" should now be vanishingly rare (only a genuine random-
+ * suffix collision, or another process/attacker independently guessing the
+ * same random suffix) — retried a handful of times with a fresh suffix
+ * before giving up LOUD; never silently falls back to a non-exclusive open.
+ */
+function openUniqueTempFileExclusive(dir, targetBasename, mode) {
+    let lastError;
+    for (let attempt = 0; attempt < TEMP_FILE_MAX_ATTEMPTS; attempt++) {
+        const suffix = randomBytes(8).toString("hex");
+        const tmp = join(dir, `.${targetBasename}.codebus-tmp-${process.pid}-${suffix}`);
+        try {
+            const fd = openSync(tmp, "wx", mode);
+            return { tmp, fd };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                throw e;
+            lastError = e; // extremely unlikely — a genuine random-suffix collision; try again with a fresh one
+        }
+    }
+    throw new Error(`Could not create a unique temp file in ${dir} after ${TEMP_FILE_MAX_ATTEMPTS} attempts (each collided with something already at the generated path) — refusing to fall back to a non-exclusive open. Last error: ${lastError?.message ?? String(lastError)}`);
+}
+/** Busy-wait for `ms` milliseconds — see acquireConfigLock's retry loop for why. */
+function sleepSyncMs(ms) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) { /* deliberately blocking: bounded, a handful of times at most */ }
+}
+const DEFAULT_LOCK_MAX_WAIT_MS = 8_000;
+const DEFAULT_LOCK_RETRY_DELAY_MS = 100;
+/**
+ * Attempts to claim `lockPath` via exclusive create, writing `myPid` as its
+ * content (a human diagnostic hint ONLY — see acquireConfigLock's docstring;
+ * no code path ever reads this back to make a decision). Returns true on
+ * success, false on EEXIST (someone else holds it), throws on any other
+ * error.
+ */
+function tryCreateLockFile(lockPath, myPid) {
+    let fd;
+    try {
+        fd = openSync(lockPath, "wx");
+    }
+    catch (e) {
+        if (e.code !== "EEXIST")
+            throw e;
+        return false; // someone else already holds it — we created nothing, nothing to clean up
+    }
+    // Luna finding: the exclusive create above already brought the lock FILE
+    // into existence — a failure from here on (the write, or closeSync) used
+    // to rethrow without ever removing it, leaving an empty/stale lock behind
+    // that blocks every subsequent `codebus install` for the full retry
+    // period and then needs a human to delete it manually. Mirrors the same
+    // "clean up what we just created on failure" pattern atomicWriteFileSync
+    // uses for its own temp file: best-effort unlink (swallowing a secondary
+    // error from the unlink itself) before rethrowing the ORIGINAL error
+    // unchanged.
+    try {
+        try {
+            writeFileSync(fd, myPid);
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    }
+    catch (e) {
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* best-effort cleanup of the lock file we just created */ }
+        throw e;
+    }
+}
+/**
+ * Best-effort mutual exclusion between concurrent `codebus install`
+ * invocations touching the SAME config file, via a sibling lockfile.
+ *
+ * DESIGN (sol round-6): this replaces TWO prior attempts at automatic
+ * stale-lock reclamation — an mtime-based staleness heuristic, then a
+ * pid-liveness check paired with an atomic-rename claim — each of which
+ * left a residual race under closer scrutiny. The pid-liveness version's
+ * gap: a DELAYED contender can read a dead pid, pause for a genuine
+ * scheduling delay, and by the time it acts on that stale knowledge (even
+ * via the atomic rename), a second contender has already reclaimed and
+ * recreated the lock as live — `rename()`/`unlink()` operate on the PATH,
+ * not the specific file the delayed contender originally inspected, so the
+ * operation succeeds anyway and destroys the live successor's lock. This is
+ * the classic ABA problem for file-based reclaim: there is no POSIX
+ * primitive for "touch this path only if it still contains what I saw."
+ * Two rounds of hardening the RECLAIM mechanism each left a version of this
+ * same gap — the fix is to stop reclaiming automatically at all, not to
+ * harden it a third time.
+ *
+ * The new contract: the ONLY thing that ever creates or destroys the
+ * lockfile is (a) an exclusive create ('wx') by whoever successfully
+ * acquires it, and (b) that SAME holder's own release() — never a third
+ * party inspecting and acting on its content. If the exclusive create
+ * fails (EEXIST), we simply wait and retry — no inspection, no decision,
+ * nothing racy to get wrong — until either it frees up or a bounded total
+ * wait (maxWaitMs) is exhausted, at which point we fail LOUD (see
+ * describeWriteFailure) naming the exact lock file and telling the human to
+ * delete it themselves if they're sure nothing else is running — never
+ * deleting it for them.
+ *
+ * The pid written into the lockfile is now PURELY a human diagnostic hint
+ * for that failure message (so it can say "held by pid NNNN, possibly a
+ * crashed process" without lying about it) — no code path here ever reads
+ * it back to decide anything.
+ *
+ * Honest scope (unchanged): this protects against a SECOND `codebus
+ * install` process racing this one — a real, plausible scenario — not
+ * against a non-cooperating writer (a hand edit, or Codex/Claude itself
+ * rewriting its own config). Closing that gap completely would need
+ * mandatory OS-level locking this file format doesn't support; we do not
+ * claim atomicity we don't have.
+ */
+export function acquireConfigLock(path, opts = {}) {
+    const lockPath = `${path}.codebus-lock`;
+    const myPid = String(process.pid);
+    const maxWaitMs = opts.maxWaitMs ?? DEFAULT_LOCK_MAX_WAIT_MS;
+    const retryDelayMs = opts.retryDelayMs ?? DEFAULT_LOCK_RETRY_DELAY_MS;
+    // We are the ONLY legitimate creator/destroyer of our own lockfile via any
+    // AUTOMATED path — no reclaim mechanism exists any more that could replace
+    // it with a successor's while we still think we hold it. But the bound-
+    // exhausted failure message (above) deliberately tells a stuck HUMAN to
+    // delete the lock file themselves if they're sure nothing else is running.
+    // If they do that while we are, in fact, still alive and holding it, a
+    // second `codebus install` can now acquire a fresh, live lock at the same
+    // path. Our own release() must not then blow that fresh lock away just
+    // because it happens to sit at the path we remember — that's not "acting
+    // on stale knowledge about someone else's file" in the old reclaim sense,
+    // but it's the same shape of bug: a path-based unlink can hit a file we
+    // didn't create. So we re-read the lockfile's content immediately before
+    // unlinking and only proceed if it still holds OUR pid — a lightweight
+    // courtesy check, not a decision mechanism (we never act on someone
+    // ELSE's lock, only ever verify our own is still ours before touching it).
+    // Luna finding: the read of currentHolder just below and the unlinkSync
+    // further down are two separate syscalls, not one — there is no POSIX
+    // call that atomically says "delete this path only if its content/inode
+    // still matches what I just read". So a successor's lock created in the
+    // gap between them (freed by the bound-exhausted human deletion above,
+    // then immediately re-acquired by a second `codebus install`) could in
+    // principle be unlinked by this stale holder anyway, pid check
+    // notwithstanding — the check narrows the window, it does not close it.
+    // We've tightened the gap as far as plain JS allows: the pid-match check
+    // is the very next statement after the read, and the unlink is the very
+    // next statement after that, with no logging or other I/O between either
+    // pair. This is an ACCEPTED, INHERENT residual limitation of path-based
+    // file locking, not something this code claims to fully solve — the same
+    // honesty standard as the atomic-write comments above. Closing it
+    // completely needs a different primitive: an OS-level flock() held on an
+    // open file descriptor, tied to the open file description rather than
+    // the path, so no unlink-race is even expressible. Node's core `fs`
+    // doesn't expose that (it would need a native addon like fs-ext, or a
+    // well-vetted lockfile library) — deliberately not pursued here given
+    // this tool's actual risk profile: a human running `codebus install` on
+    // their own machine, where the realistic collision is running the
+    // command twice nearly simultaneously, not an adversarial multi-tenant
+    // race. The realistic residual of this gap is therefore an adversarial
+    // or extraordinarily-unlucky-timing scenario, not ordinary use.
+    const release = () => {
+        let currentHolder;
+        try {
+            currentHolder = readFileSync(lockPath, "utf8").trim();
+        }
+        catch {
+            // Already gone — nothing more to do (the common, expected case).
+            return;
+        }
+        if (currentHolder !== myPid) {
+            // Someone else's lock now occupies this path — ours was already
+            // removed out from under us (almost certainly a human manually
+            // deleting it per the bound-exhausted failure message, while we were
+            // still alive). Deleting it now would destroy a legitimate second
+            // holder's lock. Leave it alone.
+            console.log(`${WARN} Lock file ${lockPath} no longer matches this process (pid ${myPid}); leaving it in place — it now belongs to another process (pid ${currentHolder || "unknown"}).`);
+            return;
+        }
+        try {
+            unlinkSync(lockPath);
+        }
+        catch { /* already gone — nothing more to do */ }
+    };
+    const deadline = Date.now() + maxWaitMs;
+    while (true) {
+        if (tryCreateLockFile(lockPath, myPid))
+            return { ok: true, release };
+        if (Date.now() >= deadline) {
+            let holderHint = null;
+            try {
+                holderHint = readFileSync(lockPath, "utf8").trim() || null;
+            }
+            catch { /* gone/unreadable — no hint available */ }
+            return { ok: false, lockPath, holderHint };
+        }
+        sleepSyncMs(retryDelayMs);
+    }
+}
+/**
+ * TOCTOU guard + atomic write: writes `newText` to `path` (and, if
+ * `backupPath` is given, the pre-write content to `backupPath`) ONLY IF the
+ * file's on-disk content still equals `expectedCurrentText` — what was read
+ * at the start of the calling operation — checked again right here,
+ * immediately before committing, and guarded by acquireConfigLock() so a
+ * second concurrent `codebus install` can't interleave with this check-and-
+ * write. If something else modified the file in between (another process,
+ * a hand edit, Codex itself), aborts instead of silently clobbering that
+ * change — see WriteResult's `reason` for which case fired. Only ENOENT on
+ * the re-read means "file doesn't exist, treat as empty" (sol round-2
+ * finding #4); any OTHER read error aborts as `reason: "read-error"` rather
+ * than being silently treated as an empty file. The lock is released via
+ * `finally` unconditionally — on success, on a "changed"/"read-error"
+ * abort, and on the write itself throwing — so a well-behaved holder never
+ * leaves its lockfile behind.
+ */
+export function writeIfUnchanged(path, expectedCurrentText, newText, backupPath, lockOpts) {
+    const lock = acquireConfigLock(path, lockOpts);
+    if (!lock.ok)
+        return { ok: false, reason: "locked", lockPath: lock.lockPath, holderHint: lock.holderHint };
+    try {
+        let freshText;
+        try {
+            freshText = readFileSync(path, "utf8");
+        }
+        catch (e) {
+            const err = e;
+            if (err.code !== "ENOENT")
+                return { ok: false, reason: "read-error", error: err };
+            freshText = "";
+        }
+        if (freshText !== expectedCurrentText)
+            return { ok: false, reason: "changed" };
+        if (backupPath && freshText.length > 0) {
+            atomicWriteFileSync(backupPath, freshText);
+        }
+        atomicWriteFileSync(path, newText);
+        return { ok: true };
+    }
+    finally {
+        lock.release();
+    }
+}
+/** Human-readable explanation for a failed writeIfUnchanged() — see WriteResult. */
+export function describeWriteFailure(result, path) {
+    if (result.reason === "changed")
+        return `${path} changed since it was read — not writing, to avoid clobbering a concurrent edit.`;
+    if (result.reason === "locked") {
+        const hint = result.holderHint
+            ? ` The lock file records pid ${result.holderHint} — it may still be running, or it may be a crashed process that never cleaned up.`
+            : "";
+        return `${path} is locked by another \`codebus install\` run (${result.lockPath} exists).${hint} If you're sure no other \`codebus install\` is running, delete that file yourself and re-run — this tool will not delete it for you.`;
+    }
+    return `Could not verify ${path} before writing (${result.error.message}) — aborting without writing.`;
 }
 function printMcpServerConfig() {
     const config = buildMcpServerConfig();
@@ -401,8 +1469,41 @@ function getUserConfirmation(prompt) {
         process.stdin.resume();
     });
 }
+/**
+ * Shared by every write path in this file that needs sign-off —
+ * installMcp's fresh registration, both installers' drift-heal, and
+ * installCodexMcp's write into an existing-but-tableless config.toml — so
+ * the prompt/--yes/non-interactive mechanics live in exactly one place.
+ * (sol round-4 finding #1: these were hand-rolled slightly differently at
+ * each call site, and the gap that opened up — one call site skipping the
+ * gate entirely — came from that duplication, not from any one of the
+ * individual gates being wrong in isolation.)
+ */
+async function requestConsent(o, promptText) {
+    if (o.yes)
+        return "granted";
+    if (!process.stdin.isTTY)
+        return "non-interactive";
+    const answer = await getUserConfirmation(promptText);
+    return answer.toLowerCase().startsWith("y") ? "granted" : "declined";
+}
 export async function installAll(o = {}) {
     const repoRoot = o.cwd ?? process.cwd();
+    // ── 0. T0 CI hooks (opt-in subcommand) ───────────────────────────────────
+    // `codebus install --ci-hooks [--dry-run]`: pre-commit guards — lint,
+    // affected unit tests, and the DIFF-SIZE GUARD (>2500 added lines in one
+    // file vs merge base without an authorised ci/large-diff label -> stop).
+    // Time-capped at 10s; every outage swallowed (never blocks coding).
+    if (o.ciHooks) {
+        const { runCiHooks } = await import("../ci-hooks/ci-hooks.js");
+        const result = runCiHooks({ dryRun: o.dryRun, cwd: repoRoot });
+        for (const note of result.notes)
+            console.log(`${OK} ${note}`);
+        console.log(`${OK} T0 hooks ${result.ok ? "pass" : "STOP"} (${result.elapsedMs}ms${result.dryRun ? ", dry-run" : ""})`);
+        if (!result.ok)
+            process.exit(2);
+        return;
+    }
     // ── 1. Build graph out-of-band ───────────────────────────────────────────
     if (!o.skipGraph) {
         const isGitDir = existsSync(join(repoRoot, ".git"));
@@ -509,9 +1610,13 @@ export function registerInstall(program, g) {
     const install = program
         .command("install")
         .description("wire CodeBus into agent launchers (run without subcommand for zero-config setup)")
+        .option("--ci-hooks", "run T0 pre-commit guards (diff-size/lint/affected tests)")
+        .option("--dry-run", "with --ci-hooks: report without executing lint/tests")
         .action(installAll);
     g(install.command("claude")).option("--force", "replace an existing statusLine").action(installClaude);
-    g(install.command("codex")).action(installCodex);
+    g(install.command("codex"))
+        .option("--yes", "skip confirmation when an MCP pointer needs consent before updating")
+        .action(installCodex);
     g(install.command("mcp"))
         .option("--yes", "skip confirmation prompt (opt-in gate)")
         .description("register codebus-mcp server in Claude Code settings (opt-in only)")