@sentropic/h2a 0.90.0 → 0.90.2

package/dist/hosts/installation-doctor.js

@@ -0,0 +1,2093 @@
+/**
+ * Host-installation convergence for `h2a doctor`.
+ *
+ * The h2a plugin is the canonical host integration. A direct `mcp-serve`
+ * configuration alongside that plugin starts a second endpoint, and the old
+ * standalone Track MCP starts a competing projection of `track_*` tools. This
+ * module treats both as an incoherent installation rather than a warning.
+ *
+ * Host plugin CLIs retain authority over their own installation registries.
+ * Doctor repairs their plain configuration/cache residue itself, then asks the
+ * native CLI to install/update the canonical `h2a@sentropic` plugin. A command
+ * failure is retained as an unrepaired finding; it must never become a clean
+ * result merely because a config file was edited.
+ */
+import { spawnSync } from "node:child_process";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdtempSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+import { resolveHostConfigCompanionBase, resolveHostConfigRoot } from "../runtime/host-config-root.js";
+import { currentCliVersion } from "../runtime/upgrade/index.js";
+export const H2A_PLUGIN_SELECTOR = "h2a@sentropic";
+export const H2A_MARKETPLACE_NAME = "sentropic";
+export const H2A_MARKETPLACE_REPOSITORY = "rhanka/h2a";
+export const H2A_MARKETPLACE_GIT_URL = "https://github.com/rhanka/h2a.git";
+export const HOST_REPAIR_FRESHNESS_GUARANTEE = "doctor guarantees the coherence of the repairs it performed. It does not detect installation changes made by other tools; after changing your installation by hand, restart your sessions.";
+export const HOST_REPAIR_NATIVE_COMMAND_FAILURE_LIMIT = "If a native host CLI fails after it has already changed the installation, doctor reports the failure as host-command-failed and does not undo what that CLI already did. Doctor's own configuration writes are atomic. It has no snapshot of third-party state and does not simulate one: a partial restore would promise a recovery it cannot deliver. After a reported native failure, verify the host installation before relying on it.";
+function defaultHostCommand(command, args, context) {
+    try {
+        const result = spawnSync(command, [...args], {
+            encoding: "utf8",
+            timeout: 120_000,
+            ...(context?.cwd ? { cwd: context.cwd } : {}),
+            ...(context?.env ? { env: context.env } : {})
+        });
+        if (result.status === 0)
+            return { ok: true };
+        const detail = [result.stderr, result.stdout, result.error?.message]
+            .filter((value) => typeof value === "string" && value.trim().length > 0)
+            .join(" ")
+            .trim();
+        return {
+            ok: false,
+            message: detail || `${command} ${args.join(" ")} exited ${result.status ?? "without a status"}`
+        };
+    }
+    catch (error) {
+        return { ok: false, message: error.message };
+    }
+}
+function finding(code, message, path) {
+    return { code, message, ...(path ? { path } : {}) };
+}
+function isBlockingFinding(entry) {
+    return entry.code !== "config-preserved" && entry.code !== "orphan-cache" && entry.code !== "host-not-installed";
+}
+function hostFindingBucket(entry) {
+    if (["config-preserved", "orphan-cache", "host-not-installed"].includes(entry.code))
+        return "preserved";
+    if (["host-cli-unavailable", "host-config-unavailable", "host-config-unverifiable", "ownership-unverified", "repair-marker-unavailable", "runtime-artifact-unavailable"].includes(entry.code)) {
+        return "unverifiable";
+    }
+    return "failure";
+}
+function uniqueFindings(entries) {
+    const seen = new Set();
+    return entries.filter((entry) => {
+        const key = `${entry.code}\u0000${entry.path ?? ""}\u0000${entry.message}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJson(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        if (!isPlainObject(value))
+            return { error: "JSON root is not an object" };
+        return { value };
+    }
+    catch (error) {
+        return { error: error.message };
+    }
+}
+function writeJson(path, value) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+function validateRenderedToml(raw) {
+    const headers = new Set();
+    const delimiters = [];
+    let quote;
+    let escaped = false;
+    const scanValue = (value, line) => {
+        let hasValue = quote !== undefined || delimiters.length > 0;
+        for (const character of value) {
+            if (quote) {
+                hasValue = true;
+                if (quote === '"' && escaped) {
+                    escaped = false;
+                    continue;
+                }
+                if (quote === '"' && character === "\\") {
+                    escaped = true;
+                    continue;
+                }
+                if (character === quote)
+                    quote = undefined;
+                continue;
+            }
+            if (character === "#")
+                break;
+            if (!/\s/.test(character))
+                hasValue = true;
+            if (character === '"' || character === "'")
+                quote = character;
+            else if (character === "[")
+                delimiters.push("]");
+            else if (character === "{")
+                delimiters.push("}");
+            else if (character === "]" || character === "}") {
+                if (delimiters.pop() !== character)
+                    return `line ${line} has unbalanced TOML delimiters`;
+            }
+        }
+        return hasValue ? undefined : `line ${line} has no TOML value`;
+    };
+    for (const [index, line] of raw.split(/\r?\n/).entries()) {
+        const trimmed = line.trim();
+        if (quote || delimiters.length > 0) {
+            const valueError = scanValue(line, index + 1);
+            if (valueError)
+                return valueError;
+            continue;
+        }
+        if (trimmed.length === 0 || trimmed.startsWith("#"))
+            continue;
+        if (trimmed.startsWith("[")) {
+            const arrayHeader = /^\[\[([^\]\r\n]+)\]\]\s*(?:#.*)?$/.exec(trimmed);
+            if (arrayHeader)
+                continue;
+            const header = /^\[([^\]\r\n]+)\]\s*(?:#.*)?$/.exec(trimmed);
+            if (!header)
+                return `line ${index + 1} has an invalid table header`;
+            if (headers.has(header[1]))
+                return `line ${index + 1} repeats table ${header[1]}`;
+            headers.add(header[1]);
+            continue;
+        }
+        if (!/^(?:[A-Za-z0-9_-]+|"(?:\\.|[^"\\])+")(?:\.(?:[A-Za-z0-9_-]+|"(?:\\.|[^"\\])+"))*\s*=/.test(trimmed)) {
+            return `line ${index + 1} is not a TOML key/value assignment`;
+        }
+        const valueError = scanValue(trimmed.slice(trimmed.indexOf("=") + 1), index + 1);
+        if (valueError)
+            return valueError;
+    }
+    if (quote)
+        return "TOML has an unterminated string";
+    if (delimiters.length > 0)
+        return "TOML has unclosed array or inline-table delimiters";
+    return undefined;
+}
+function validateRenderedConfiguration(raw, format) {
+    if (format === "toml")
+        return validateRenderedToml(raw);
+    try {
+        if (!isPlainObject(JSON.parse(raw)))
+            return "JSON root is not an object";
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
+function atomicConfigurationWrite(path, original, rendered, format, testHooks, beforeReplace) {
+    let temporaryPath;
+    let descriptor;
+    try {
+        const candidate = testHooks?.mutateRendered?.(path, format, rendered) ?? rendered;
+        const validationError = validateRenderedConfiguration(candidate, format);
+        if (validationError)
+            return `rendered ${format.toUpperCase()} cannot be parsed: ${validationError}`;
+        mkdirSync(dirname(path), { recursive: true });
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const candidatePath = join(dirname(path), `.${path.split("/").pop()}.h2a-${process.pid}-${Date.now()}-${attempt}.tmp`);
+            try {
+                descriptor = openSync(candidatePath, "wx", 0o600);
+                temporaryPath = candidatePath;
+                break;
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        if (descriptor === undefined || temporaryPath === undefined)
+            throw new Error("cannot allocate an atomic temporary file");
+        writeFileSync(descriptor, candidate, "utf8");
+        fsyncSync(descriptor);
+        closeSync(descriptor);
+        descriptor = undefined;
+        testHooks?.beforeRename?.(path, temporaryPath);
+        const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+        if (current !== original)
+            throw new Error("configuration changed concurrently before atomic rename");
+        const replacementError = beforeReplace?.();
+        if (replacementError)
+            throw new Error(replacementError);
+        if (testHooks?.rename)
+            testHooks.rename(temporaryPath, path);
+        else
+            renameSync(temporaryPath, path);
+        temporaryPath = undefined;
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+    finally {
+        if (descriptor !== undefined) {
+            try {
+                closeSync(descriptor);
+            }
+            catch { /* preserve the original write error */ }
+        }
+        if (temporaryPath !== undefined) {
+            try {
+                unlinkSync(temporaryPath);
+            }
+            catch { /* cleanup must not hide the original write error */ }
+        }
+    }
+}
+function listDirectories(path) {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+}
+function loadBearingArtifacts(report, roots, hostConfigPaths) {
+    const declared = new Set(hostConfigPaths.filter(existsSync));
+    const inspectedMcpConfigs = new Set();
+    const inspectMcpConfig = (path) => {
+        if (inspectedMcpConfigs.has(path))
+            return;
+        inspectedMcpConfigs.add(path);
+        declared.add(path);
+        if (!existsSync(path))
+            return;
+        const config = readJson(path);
+        if (config.error) {
+            report.findings.push(finding("runtime-artifact-unavailable", `cannot inspect declared MCP config: ${config.error}`, path));
+            return;
+        }
+        const servers = isPlainObject(config.value?.mcpServers) ? config.value.mcpServers : {};
+        for (const entry of Object.values(servers)) {
+            if (!isPlainObject(entry))
+                continue;
+            for (const candidate of [entry.command, ...jsonArgs(entry)]) {
+                if (typeof candidate === "string" && candidate.startsWith(".")) {
+                    declared.add(join(dirname(path), candidate));
+                }
+            }
+        }
+    };
+    for (const root of roots) {
+        for (const manifestPath of [
+            join(root, ".codex-plugin", "plugin.json"),
+            join(root, ".claude-plugin", "plugin.json")
+        ]) {
+            if (!existsSync(manifestPath))
+                continue;
+            declared.add(manifestPath);
+            const manifest = readJson(manifestPath);
+            if (manifest.error) {
+                report.findings.push(finding("runtime-artifact-unavailable", `cannot inspect plugin manifest: ${manifest.error}`, manifestPath));
+                continue;
+            }
+            const pluginRoot = dirname(dirname(manifestPath));
+            const mcpServers = manifest.value?.mcpServers;
+            if (typeof mcpServers === "string" && mcpServers.startsWith(".")) {
+                inspectMcpConfig(join(pluginRoot, mcpServers));
+            }
+            else if (isPlainObject(mcpServers)) {
+                for (const entry of Object.values(mcpServers)) {
+                    if (!isPlainObject(entry))
+                        continue;
+                    for (const candidate of [entry.command, ...jsonArgs(entry)]) {
+                        if (typeof candidate === "string" && candidate.startsWith(".")) {
+                            declared.add(join(pluginRoot, candidate));
+                        }
+                    }
+                }
+            }
+        }
+        const conventionalMcpConfig = join(root, ".mcp.json");
+        if (existsSync(conventionalMcpConfig))
+            inspectMcpConfig(conventionalMcpConfig);
+    }
+    const resolved = [];
+    for (const path of declared) {
+        try {
+            const target = realpathSync(path);
+            const metadata = statSync(target);
+            if (!metadata.isFile())
+                throw new Error("not a regular file");
+            pushUnique(resolved, target);
+        }
+        catch (error) {
+            report.findings.push(finding("runtime-artifact-unavailable", `cannot inspect declared artifact: ${error.message}`, path));
+        }
+    }
+    return resolved;
+}
+function multilineTomlStringStart(line) {
+    // This deliberately accepts only the assignment form which this table
+    // rewriter can frame safely. It is not a full TOML parser: unsupported
+    // regions stay byte-identical, while complex dotted keys and Unicode escape
+    // semantics never grant destructive authorization.
+    const match = /^\s*(?:[A-Za-z0-9_-]+|"(?:\\.|[^"\\])*"|'[^']*')(?:\s*\.\s*(?:[A-Za-z0-9_-]+|"(?:\\.|[^"\\])*"|'[^']*'))*\s*=\s*('''|""")/.exec(line);
+    return match ? { delimiter: match[1], offset: match.index + match[0].length } : undefined;
+}
+function multilineTomlStringEnd(line, delimiter, offset) {
+    for (let cursor = offset; cursor <= line.length - delimiter.length; cursor++) {
+        if (!line.startsWith(delimiter, cursor))
+            continue;
+        if (delimiter === '\"\"\"') {
+            let slashCount = 0;
+            for (let previous = cursor - 1; previous >= 0 && line[previous] === "\\"; previous--)
+                slashCount++;
+            if (slashCount % 2 === 1)
+                continue;
+        }
+        const tail = line.slice(cursor + delimiter.length);
+        return /^\s*(?:#.*)?(?:\r?\n)?$/.test(tail)
+            ? { closed: true }
+            : { closed: false, unavailable: "multiline TOML string has content after its closing delimiter" };
+    }
+    return { closed: false };
+}
+function dottedMcpRegion(line) {
+    const assignment = /^\s*(mcp_servers\.[^\s=]+)\s*=/.exec(line);
+    if (!assignment)
+        return undefined;
+    const lastSeparator = assignment[1].lastIndexOf(".");
+    return lastSeparator > "mcp_servers".length
+        ? `${assignment[1].slice(0, lastSeparator)}.*`
+        : undefined;
+}
+function parseTomlTables(content) {
+    const result = [];
+    let current;
+    let multilineDelimiter;
+    const pushCurrent = () => {
+        if (!current)
+            return;
+        const end = current.trailingTriviaStart ?? current.end;
+        if (end > current.start) {
+            const raw = content.slice(current.start, end);
+            result.push({
+                header: current.header,
+                lines: raw.split(/(?<=\n)/),
+                raw,
+                span: { start: current.start, end },
+                containsMultilineString: current.containsMultilineString,
+                opaqueReason: current.opaqueReason,
+                opaqueLabel: current.opaqueLabel
+            });
+        }
+        current = undefined;
+    };
+    const appendCurrentLine = (line, start, kind) => {
+        if (!current)
+            current = { header: "", start, end: start, containsMultilineString: false };
+        current.end = start + line.length;
+        if (kind === "content")
+            current.trailingTriviaStart = undefined;
+        else if (kind === "comment" ||
+            (kind === "blank" && line.replace(/\r?\n$/, "").length > 0))
+            current.trailingTriviaStart ??= start;
+    };
+    let offset = 0;
+    for (const line of content.split(/(?<=\n)/)) {
+        const lineStart = offset;
+        offset += line.length;
+        if (multilineDelimiter) {
+            if (!current)
+                return { tables: result, unavailable: "multiline TOML string has no containing table" };
+            appendCurrentLine(line, lineStart, "content");
+            current.containsMultilineString = true;
+            const end = multilineTomlStringEnd(line, multilineDelimiter, 0);
+            if (end.unavailable)
+                return { tables: result, unavailable: end.unavailable };
+            if (end.closed)
+                multilineDelimiter = undefined;
+            continue;
+        }
+        const arrayHeader = /^\s*\[\[([^\]]+)\]\]\s*(?:#.*)?(?:\r?\n)?$/.exec(line);
+        if (arrayHeader || /^\s*\[\[/.test(line)) {
+            pushCurrent();
+            current = {
+                header: "",
+                start: lineStart,
+                end: offset,
+                containsMultilineString: false,
+                opaqueReason: "TOML arrays of tables are not framed for targeted rewrite",
+                opaqueLabel: arrayHeader ? `[[${arrayHeader[1]}]]` : line.trim()
+            };
+            continue;
+        }
+        const dottedRegion = dottedMcpRegion(line);
+        if (dottedRegion) {
+            if (current?.header) {
+                current.opaqueReason ??= "dotted MCP keys are not framed for targeted rewrite";
+                current.opaqueLabel ??= dottedRegion;
+                appendCurrentLine(line, lineStart, "content");
+            }
+            else {
+                pushCurrent();
+                current = {
+                    header: "",
+                    start: lineStart,
+                    end: offset,
+                    containsMultilineString: false,
+                    opaqueReason: "dotted MCP keys are not framed for targeted rewrite",
+                    opaqueLabel: dottedRegion
+                };
+            }
+            continue;
+        }
+        const header = /^\s*\[([^\]]+)\]\s*(?:#.*)?(?:\r?\n)?$/.exec(line);
+        if (header) {
+            pushCurrent();
+            current = { header: header[1], start: lineStart, end: offset, containsMultilineString: false };
+        }
+        else {
+            const kind = /^\s*#.*(?:\r?\n)?$/.test(line)
+                ? "comment"
+                : /^\s*(?:\r?\n)?$/.test(line)
+                    ? "blank"
+                    : "content";
+            appendCurrentLine(line, lineStart, kind);
+            if (!current)
+                return { tables: result, unavailable: "TOML line has no containing table" };
+            const start = multilineTomlStringStart(line);
+            if (start) {
+                current.containsMultilineString = true;
+                const end = multilineTomlStringEnd(line, start.delimiter, start.offset);
+                if (end.unavailable)
+                    return { tables: result, unavailable: end.unavailable };
+                if (!end.closed)
+                    multilineDelimiter = start.delimiter;
+            }
+            else if (line.includes("'''") || line.includes('\"\"\"')) {
+                return { tables: result, unavailable: "cannot frame an unsupported triple-quoted TOML string" };
+            }
+        }
+    }
+    if (multilineDelimiter)
+        return { tables: result, unavailable: "unterminated multiline TOML string" };
+    pushCurrent();
+    return { tables: result };
+}
+function tomlQuotedName(header, prefix) {
+    const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`^${escaped}(?:\\.\\\"([^\"]+)\\\"|\\.([^\\.]+))$`).exec(header);
+    return match?.[1] ?? match?.[2];
+}
+function tomlAssignment(table, key) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const line = table.lines.slice(1).find((entry) => new RegExp(`^\\s*${escaped}\\s*=`).test(entry));
+    if (!line)
+        return undefined;
+    return line.slice(line.indexOf("=") + 1).trim().replace(/\s+#.*$/, "");
+}
+function tomlValue(table, key) {
+    const value = tomlAssignment(table, key);
+    if (value === undefined)
+        return undefined;
+    const quoted = /^"((?:\\.|[^"\\])*)"$/.exec(value);
+    if (quoted)
+        return quoted[1].replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+    const literal = /^'([^']*)'$/.exec(value);
+    return literal ? literal[1] : value;
+}
+function decodeTomlBasicString(value) {
+    if (value.length < 2 || value[0] !== '"' || value.at(-1) !== '"')
+        return undefined;
+    let decoded = "";
+    for (let cursor = 1; cursor < value.length - 1; cursor++) {
+        const character = value[cursor];
+        if (character !== "\\") {
+            if (character < " " || character === '"')
+                return undefined;
+            decoded += character;
+            continue;
+        }
+        const escape = value[++cursor];
+        if (cursor >= value.length - 1)
+            return undefined;
+        const escaped = escape === "b" ? "\b"
+            : escape === "t" ? "\t"
+                : escape === "n" ? "\n"
+                    : escape === "f" ? "\f"
+                        : escape === "r" ? "\r"
+                            : escape === '"' ? '"'
+                                : escape === "\\" ? "\\"
+                                    : undefined;
+        if (escaped !== undefined) {
+            decoded += escaped;
+            continue;
+        }
+        const width = escape === "u" ? 4 : escape === "U" ? 8 : undefined;
+        if (width === undefined)
+            return undefined;
+        const hexadecimal = value.slice(cursor + 1, cursor + 1 + width);
+        if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`).test(hexadecimal))
+            return undefined;
+        const codePoint = Number.parseInt(hexadecimal, 16);
+        if (codePoint > 0x10FFFF || (codePoint >= 0xD800 && codePoint <= 0xDFFF))
+            return undefined;
+        decoded += String.fromCodePoint(codePoint);
+        cursor += width;
+    }
+    return decoded;
+}
+/**
+ * Return a fully decoded single-line TOML string, or nothing. This intentionally
+ * does not try to approximate multiline TOML syntax: a path that we cannot
+ * decode exactly must never be used as evidence that a local source is absent.
+ */
+function tomlStringValue(table, key) {
+    const value = tomlAssignment(table, key);
+    if (value === undefined)
+        return undefined;
+    if (/^"/.test(value))
+        return decodeTomlBasicString(value);
+    const literal = /^'([^']*)'$/.exec(value);
+    return literal?.[1];
+}
+function tomlBoolean(table, key) {
+    const value = tomlValue(table, key);
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return undefined;
+}
+function rewriteTomlTables(raw, transform) {
+    const parsed = parseTomlTables(raw);
+    if (parsed.unavailable)
+        throw new Error(`cannot safely frame TOML tables: ${parsed.unavailable}`);
+    const output = [];
+    let cursor = 0;
+    for (const table of parsed.tables) {
+        if (!table.span)
+            throw new Error("cannot safely frame TOML table span");
+        output.push(raw.slice(cursor, table.span.start));
+        const replacement = transform(table);
+        if (replacement)
+            output.push(...replacement);
+        cursor = table.span.end;
+    }
+    output.push(raw.slice(cursor));
+    return output.join("");
+}
+function isNamedOpaqueTomlArray(table) {
+    return (table.opaqueReason === "TOML arrays of tables are not framed for targeted rewrite" &&
+        /^\[\[[^\]\r\n]+\]\]$/.test(table.opaqueLabel ?? ""));
+}
+function reportOpaqueTomlRegions(report, path, tables) {
+    for (const table of tables) {
+        if (!table.opaqueReason)
+            continue;
+        const message = `opaque Codex TOML region ${table.opaqueLabel ?? "<unknown>"}: ${table.opaqueReason}; its existing bytes were retained and no rewrite was attempted.`;
+        if (isNamedOpaqueTomlArray(table)) {
+            report.preserved.push(finding("config-preserved", `preserved ${message}`, path));
+        }
+        else {
+            report.unrepaired.push(finding("config-invalid", `cannot rewrite ${message}`, path));
+        }
+    }
+}
+function tomlTable(header, lines) {
+    return [`[${header}]\n`, ...lines.map((line) => `${line}\n`), "\n"];
+}
+function isLegacySentropicName(name) {
+    return Boolean(name && /^sentropic-local-/i.test(name));
+}
+function isLegacyH2aPlugin(name) {
+    return Boolean(name && (/^h2a-local-/i.test(name) || /^h2a@sentropic-local-/i.test(name)));
+}
+function isAuthorizedClaudePluginUninstall(name) {
+    return Boolean(name && (/^h2a-local-/i.test(name) ||
+        /^h2a@sentropic-local-/i.test(name) ||
+        /^track@sentropic$/i.test(name)));
+}
+function isDirectH2aMcp(table) {
+    const command = tomlValue(table, "command");
+    const args = tomlValue(table, "args") ?? "";
+    return command === "h2a" && /(?:^|[\"\s,])mcp-serve(?:[\"\s,]|$)/.test(args);
+}
+function isDirectTrackMcp(table) {
+    const command = tomlValue(table, "command") ?? "";
+    const rawArgs = tomlValue(table, "args") ?? "";
+    try {
+        const args = JSON.parse(rawArgs);
+        return command === "h2a" && Array.isArray(args) && args.includes("track-mcp");
+    }
+    catch {
+        return false;
+    }
+}
+function isOwnedMarketplace(location) {
+    const marketplace = readJson(join(location, ".claude-plugin", "marketplace.json")).value;
+    return Boolean(marketplace?.name === H2A_MARKETPLACE_NAME &&
+        Array.isArray(marketplace.plugins) &&
+        marketplace.plugins.some((plugin) => isPlainObject(plugin) && plugin.name === "h2a" && plugin.source === "./packages/h2a"));
+}
+function canonicalMarketplace(value) {
+    if (!isPlainObject(value))
+        return false;
+    const source = value.source;
+    return (isPlainObject(source) &&
+        source.source === "github" &&
+        source.repo === H2A_MARKETPLACE_REPOSITORY &&
+        typeof value.installLocation === "string" &&
+        isOwnedMarketplace(value.installLocation));
+}
+function canonicalCodexMarketplace(table, home) {
+    return Boolean(canonicalCodexMarketplaceConfig(table) &&
+        isOwnedMarketplace(join(codexRoot(home), ".tmp", "marketplaces", H2A_MARKETPLACE_NAME)));
+}
+function isOwnedCodexMarketplace(table, home) {
+    return canonicalCodexMarketplace(table, home) || isOwnedLegacyCodexMarketplace(table);
+}
+function hasOwnedCanonicalCodexPlugin(home) {
+    const cache = join(codexRoot(home), "plugins", "cache", H2A_MARKETPLACE_NAME, "h2a");
+    return listDirectories(cache).some((version) => isOwnedPlugin(join(cache, version)));
+}
+/** A configured Git source is distinct from its derived local marketplace cache. */
+function canonicalCodexMarketplaceConfig(table) {
+    return Boolean(table &&
+        tomlValue(table, "source_type") === "git" &&
+        tomlValue(table, "source") === H2A_MARKETPLACE_GIT_URL &&
+        tomlValue(table, "ref") === "main");
+}
+function h2aPluginEntries(value) {
+    return Array.isArray(value) ? value.filter(isPlainObject) : [];
+}
+function pluginEntryIsCurrent(entry, version) {
+    return (entry.version === version &&
+        typeof entry.installPath === "string" &&
+        isOwnedPlugin(entry.installPath) &&
+        cachedPluginVersion(entry.installPath) === version);
+}
+function cachedPluginVersion(path) {
+    for (const manifest of [
+        join(path, ".codex-plugin", "plugin.json"),
+        join(path, ".claude-plugin", "plugin.json")
+    ]) {
+        const parsed = readJson(manifest).value;
+        if (typeof parsed?.version === "string")
+            return parsed.version;
+    }
+    return undefined;
+}
+function isOwnedPlugin(path, expectedName = "h2a") {
+    return [
+        join(path, ".codex-plugin", "plugin.json"),
+        join(path, ".claude-plugin", "plugin.json")
+    ].some((manifest) => readJson(manifest).value?.name === expectedName);
+}
+function pluginEntriesAreOwned(selector, value) {
+    const expectedName = selector === "track@sentropic" ? "track" : "h2a";
+    const entries = h2aPluginEntries(value);
+    return entries.length > 0 && entries.every((entry) => typeof entry.installPath === "string" && isOwnedPlugin(entry.installPath, expectedName));
+}
+function isOwnedLegacyCacheRoot(path) {
+    try {
+        const entries = readdirSync(path, { withFileTypes: true });
+        if (entries.length !== 1 || !entries[0].isDirectory() || entries[0].name !== "h2a")
+            return false;
+        const versions = readdirSync(join(path, "h2a"), { withFileTypes: true });
+        return versions.length > 0 && versions.every((entry) => entry.isDirectory() && isOwnedPlugin(join(path, "h2a", entry.name)));
+    }
+    catch {
+        return false;
+    }
+}
+function cacheVersionMatches(path, version) {
+    return cachedPluginVersion(path) === version;
+}
+function codexCacheVersions(home) {
+    return listDirectories(join(codexRoot(home), "plugins", "cache", H2A_MARKETPLACE_NAME, "h2a"));
+}
+function claudeCacheVersions(home) {
+    return listDirectories(join(claudeRoot(home), "plugins", "cache", H2A_MARKETPLACE_NAME, "h2a"));
+}
+function codexRoot(home) {
+    return resolveHostConfigRoot("codex", home);
+}
+function claudeRoot(home) {
+    return resolveHostConfigRoot("claude", home);
+}
+function codexConfigPath(home) {
+    return join(codexRoot(home), "config.toml");
+}
+function claudeSettingsPath(home) {
+    return join(claudeRoot(home), "settings.json");
+}
+function claudeConfigPaths(home) {
+    const base = resolveHostConfigCompanionBase("claude", home);
+    return [join(base, ".claude.json"), join(base, ".config", "claude", "mcp.json")].filter(existsSync);
+}
+function isProvenAbsentFilesystemError(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+function hostConfigurationArtifactState(path) {
+    try {
+        lstatSync(path);
+    }
+    catch (error) {
+        return isProvenAbsentFilesystemError(error)
+            ? { state: "absent" }
+            : { state: "unavailable", reason: error.code ?? error.message };
+    }
+    try {
+        statSync(path);
+        return { state: "present" };
+    }
+    catch (error) {
+        // lstat succeeded, so ENOENT here is a broken symlink, not proof of absence.
+        return { state: "unavailable", reason: error.code ?? error.message };
+    }
+}
+function explicitlyConfiguredHostRoot(host) {
+    const environment = host === "claude" ? "CLAUDE_CONFIG_DIR" : "CODEX_HOME";
+    const path = process.env[environment];
+    return path && path.length > 0 ? { environment, path } : undefined;
+}
+function hostConfigurationArtifacts(home, host) {
+    const explicitlyConfigured = explicitlyConfiguredHostRoot(host);
+    if (explicitlyConfigured) {
+        try {
+            if (!statSync(explicitlyConfigured.path).isDirectory()) {
+                return {
+                    present: [],
+                    unavailable: [{
+                            path: explicitlyConfigured.path,
+                            reason: `${explicitlyConfigured.environment} is explicitly configured but is not a directory`
+                        }]
+                };
+            }
+        }
+        catch (error) {
+            return {
+                present: [],
+                unavailable: [{
+                        path: explicitlyConfigured.path,
+                        reason: `${explicitlyConfigured.environment} is explicitly configured but cannot be inspected (${error.code ?? error.message})`
+                    }]
+            };
+        }
+    }
+    const candidates = host === "codex"
+        ? [codexRoot(home), codexConfigPath(home)]
+        : [
+            claudeRoot(home),
+            claudeSettingsPath(home),
+            join(resolveHostConfigCompanionBase("claude", home), ".claude.json"),
+            join(resolveHostConfigCompanionBase("claude", home), ".config", "claude", "mcp.json")
+        ];
+    const present = [];
+    const unavailable = [];
+    for (const path of candidates) {
+        const result = hostConfigurationArtifactState(path);
+        if (result.state === "present")
+            present.push(path);
+        if (result.state === "unavailable")
+            unavailable.push({ path, reason: result.reason ?? "unknown error" });
+    }
+    return { present, unavailable };
+}
+function hostCliCanRunNativeRepair(host, hasInjectedRunner, testHostCliReachable) {
+    if (testHostCliReachable)
+        return { state: testHostCliReachable(host) ? "reachable" : "absent" };
+    // A runner is the hermetic test double for a reachable native CLI. Production
+    // never supplies one, so it always resolves the actual executable on PATH.
+    if (hasInjectedRunner)
+        return { state: "reachable" };
+    let unavailable;
+    for (const segment of (process.env.PATH ?? "").split(delimiter)) {
+        // POSIX defines an empty PATH segment as the current working directory.
+        const directory = segment.length === 0 ? "." : segment;
+        try {
+            const metadata = statSync(join(directory, host));
+            if (metadata.isFile() && (metadata.mode & 0o111) !== 0)
+                return { state: "reachable" };
+        }
+        catch (error) {
+            if (!isProvenAbsentFilesystemError(error) && !unavailable) {
+                unavailable = {
+                    path: directory,
+                    reason: error.code ?? error.message
+                };
+            }
+        }
+    }
+    return unavailable
+        ? { state: "unavailable", unavailablePath: unavailable.path, unavailableReason: unavailable.reason }
+        : { state: "absent" };
+}
+function absentHostReport(home, host) {
+    const hostName = host === "claude" ? "Claude" : "Codex";
+    const report = {
+        host,
+        findings: [],
+        diagnostics: [],
+        changed: [],
+        preserved: [],
+        unrepaired: [],
+        coherencePaths: [],
+        plannedActions: [],
+        repairMarkerPath: repairMarkerPath(home, host)
+    };
+    report.findings.push(finding("host-not-installed", `${hostName} is not installed: its CLI is absent from PATH and no host configuration artifacts were found.`));
+    return report;
+}
+function unavailableHostConfigurationReport(home, host, unavailable) {
+    const hostName = host === "claude" ? "Claude" : "Codex";
+    const report = {
+        host,
+        findings: [],
+        diagnostics: [],
+        changed: [],
+        preserved: [],
+        unrepaired: [],
+        coherencePaths: [],
+        plannedActions: [],
+        repairMarkerPath: repairMarkerPath(home, host)
+    };
+    report.findings.push(finding("host-config-unavailable", `${hostName} configuration cannot be inspected safely: ${unavailable.map((entry) => `${entry.path} (${entry.reason})`).join(", ")}.`, unavailable[0]?.path));
+    return report;
+}
+function unavailableHostCliReport(home, host, cli) {
+    const hostName = host === "claude" ? "Claude" : "Codex";
+    const report = {
+        host,
+        findings: [],
+        diagnostics: [],
+        changed: [],
+        preserved: [],
+        unrepaired: [],
+        coherencePaths: [],
+        plannedActions: [],
+        repairMarkerPath: repairMarkerPath(home, host)
+    };
+    report.findings.push(finding("host-cli-unavailable", `${hostName} CLI cannot be inspected safely on PATH: ${cli.unavailablePath} (${cli.unavailableReason}).`, cli.unavailablePath));
+    return report;
+}
+function unreachableHostCliDiagnostic(host, artifacts) {
+    const hostName = host === "claude" ? "Claude" : "Codex";
+    return finding("host-cli-unreachable", `${hostName} CLI could not be reached on PATH; native repair is unavailable while configuration artifacts remain: ${artifacts.join(", ")}.`, artifacts[0]);
+}
+function claudeEnabledPlugins(settings) {
+    return isPlainObject(settings?.enabledPlugins) ? settings.enabledPlugins : {};
+}
+function claudeExtraKnownMarketplaces(settings) {
+    return isPlainObject(settings?.extraKnownMarketplaces) ? settings.extraKnownMarketplaces : {};
+}
+function shellQuote(path) {
+    return `'${path.replace(/'/g, "'\\''")}'`;
+}
+function orphanCacheFinding(host, directories, paths, cacheRoot) {
+    return finding("orphan-cache", `${host} has orphan H2A cache directories: ${directories.join(", ")}. Remove them manually with: rm -rf -- ${paths.map(shellQuote).join(" ")}`, cacheRoot);
+}
+function pushUnique(values, value) {
+    if (!values.includes(value))
+        values.push(value);
+}
+function planAction(report, action) {
+    pushUnique(report.plannedActions, action);
+}
+function repairMarkerPath(home, host) {
+    return join(host === "codex" ? codexRoot(home) : claudeRoot(home), "h2a-repair.json");
+}
+function readRepairMarker(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        const repairedAt = isPlainObject(value) ? value.repairedAt : undefined;
+        const repairedPaths = isPlainObject(value) ? value.repairedPaths : undefined;
+        if (typeof repairedAt !== "string" ||
+            !Number.isFinite(Date.parse(repairedAt)) ||
+            !Array.isArray(repairedPaths) ||
+            repairedPaths.length === 0 ||
+            !repairedPaths.every((entry) => typeof entry === "string" && entry.length > 0)) {
+            return { error: "missing a valid repairedAt timestamp or repairedPaths" };
+        }
+        return { marker: { path, repairedAt, repairedPaths } };
+    }
+    catch (error) {
+        return { error: error.message };
+    }
+}
+function inspectRepairMarker(home, report) {
+    const path = repairMarkerPath(home, report.host);
+    report.repairMarkerPath = path;
+    const result = readRepairMarker(path);
+    if (result.marker) {
+        report.repairMarker = result.marker;
+    }
+    else if (result.error) {
+        report.findings.push(finding("repair-marker-unavailable", `cannot read host repair marker: ${result.error}`, path));
+    }
+}
+function recordRepairMarker(home, report, repairedPaths, writeMarker) {
+    const uniquePaths = [...new Set(repairedPaths)];
+    if (uniquePaths.length === 0)
+        return;
+    const path = repairMarkerPath(home, report.host);
+    const repairedAt = new Date().toISOString();
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeMarker(path, `${JSON.stringify({ repairedAt, repairedPaths: uniquePaths })}\n`);
+        const result = readRepairMarker(path);
+        if (!result.marker)
+            throw new Error(result.error ?? "marker disappeared after write");
+        report.repairMarker = result.marker;
+        pushUnique(report.changed, path);
+    }
+    catch (error) {
+        report.unrepaired.push(finding("repair-marker-write-failed", `cannot write host repair marker: ${error.message}`, path));
+    }
+}
+function inspectCodex(home, version) {
+    const configPath = codexConfigPath(home);
+    const cachePath = join(codexRoot(home), "plugins", "cache");
+    const currentCachePath = join(cachePath, H2A_MARKETPLACE_NAME, "h2a", version);
+    const report = {
+        host: "codex",
+        findings: [],
+        diagnostics: [],
+        changed: [],
+        preserved: [],
+        unrepaired: [],
+        coherencePaths: [],
+        plannedActions: [],
+        repairMarkerPath: repairMarkerPath(home, "codex")
+    };
+    let raw = "";
+    try {
+        raw = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+    }
+    catch (error) {
+        report.findings.push(finding("config-invalid", `cannot read Codex config: ${error.message}`, configPath));
+        return report;
+    }
+    const parsed = parseTomlTables(raw);
+    if (parsed.unavailable) {
+        report.findings.push(finding("config-invalid", `cannot safely frame Codex TOML: ${parsed.unavailable}`, configPath));
+        return report;
+    }
+    const tables = parsed.tables;
+    const marketplaceTables = tables.filter((table) => tomlQuotedName(table.header, "marketplaces") !== undefined);
+    const canonical = marketplaceTables.find((table) => tomlQuotedName(table.header, "marketplaces") === H2A_MARKETPLACE_NAME);
+    if (!canonicalCodexMarketplace(canonical, home)) {
+        const configuredSource = canonical ? tomlValue(canonical, "source") : undefined;
+        report.findings.push(finding("marketplace-missing", configuredSource
+            ? `Codex lacks the canonical sentropic Git marketplace: configured source ${configuredSource} is not the canonical Git source; an enabled h2a MCP/plugin cache alone is an orphaned false-healthy signal.`
+            : "Codex lacks the canonical sentropic Git marketplace; an enabled h2a MCP/plugin cache alone is an orphaned false-healthy signal.", configPath));
+    }
+    const staleMarketplaces = marketplaceTables
+        .map((table) => tomlQuotedName(table.header, "marketplaces"))
+        .filter(isLegacySentropicName);
+    if (staleMarketplaces.length > 0) {
+        report.findings.push(finding("marketplace-stale", `Codex has stale Sentropic marketplaces: ${staleMarketplaces.join(", ")}.`, configPath));
+    }
+    const plugins = tables.filter((table) => tomlQuotedName(table.header, "plugins") !== undefined);
+    const canonicalPlugin = plugins.find((table) => tomlQuotedName(table.header, "plugins") === H2A_PLUGIN_SELECTOR);
+    if (tomlBoolean(canonicalPlugin ?? { header: "", lines: [] }, "enabled") !== true) {
+        report.findings.push(finding("plugin-missing", "Codex does not enable the canonical h2a@sentropic plugin.", configPath));
+    }
+    const stalePlugins = plugins
+        .filter((table) => tomlBoolean(table, "enabled") !== false)
+        .map((table) => tomlQuotedName(table.header, "plugins"))
+        .filter(isLegacyH2aPlugin);
+    if (stalePlugins.length > 0) {
+        report.findings.push(finding("plugin-stale", `Codex has stale H2A plugin entries: ${stalePlugins.join(", ")}.`, configPath));
+    }
+    const versions = codexCacheVersions(home);
+    if (!versions.includes(version) || !cacheVersionMatches(currentCachePath, version)) {
+        report.findings.push(finding("version-skew", `Codex h2a cache is not at npm CLI version ${version}.`, cachePath));
+    }
+    const staleVersions = versions.filter((entry) => entry !== version && isOwnedPlugin(join(cachePath, H2A_MARKETPLACE_NAME, "h2a", entry)));
+    const legacyCaches = listDirectories(cachePath).filter((entry) => isLegacySentropicName(entry) && isOwnedLegacyCacheRoot(join(cachePath, entry)));
+    if (staleVersions.length > 0 || legacyCaches.length > 0) {
+        report.findings.push(orphanCacheFinding("Codex", [...staleVersions, ...legacyCaches], [
+            ...staleVersions.map((entry) => join(cachePath, H2A_MARKETPLACE_NAME, "h2a", entry)),
+            ...legacyCaches.map((entry) => join(cachePath, entry))
+        ], cachePath));
+    }
+    const mcp = tables.filter((table) => tomlQuotedName(table.header, "mcp_servers") !== undefined);
+    const directH2a = mcp.filter(isDirectH2aMcp);
+    const directTrack = mcp.filter(isDirectTrackMcp);
+    const endpointCount = (tomlBoolean(canonicalPlugin ?? { header: "", lines: [] }, "enabled") === true ? 1 : 0) + directH2a.length;
+    if (endpointCount !== 1) {
+        report.findings.push(finding("h2a-endpoint-count", `Codex exposes ${endpointCount} H2A endpoints; exactly one plugin endpoint is required.`, configPath));
+    }
+    if (directTrack.length > 0) {
+        report.findings.push(finding("standalone-track-mcp", "Codex has a standalone track-mcp endpoint; track_* must be served by h2a.", configPath));
+    }
+    report.coherencePaths.push(...loadBearingArtifacts(report, [currentCachePath], [configPath]));
+    inspectRepairMarker(home, report);
+    return report;
+}
+function inspectClaude(home, version) {
+    const knownPath = join(claudeRoot(home), "plugins", "known_marketplaces.json");
+    const installedPath = join(claudeRoot(home), "plugins", "installed_plugins.json");
+    const settingsPath = claudeSettingsPath(home);
+    const report = {
+        host: "claude",
+        findings: [],
+        diagnostics: [],
+        changed: [],
+        preserved: [],
+        unrepaired: [],
+        coherencePaths: [],
+        plannedActions: [],
+        repairMarkerPath: repairMarkerPath(home, "claude")
+    };
+    const known = readJson(knownPath);
+    const settings = readJson(settingsPath);
+    if (known.error) {
+        report.findings.push(finding("config-invalid", `cannot parse Claude marketplace state: ${known.error}`, knownPath));
+    }
+    else if (!canonicalMarketplace(known.value?.[H2A_MARKETPLACE_NAME])) {
+        report.findings.push(finding("marketplace-missing", "Claude lacks the canonical sentropic Git marketplace.", knownPath));
+    }
+    if (settings.error) {
+        report.findings.push(finding("config-invalid", `cannot parse Claude settings: ${settings.error}`, settingsPath));
+    }
+    const staleMarketplaces = [...new Set([
+            ...Object.keys(known.value ?? {}).filter(isLegacySentropicName),
+            ...Object.keys(claudeExtraKnownMarketplaces(settings.value)).filter(isLegacySentropicName)
+        ])];
+    if (staleMarketplaces.length > 0) {
+        report.findings.push(finding("marketplace-stale", `Claude has stale Sentropic marketplaces: ${staleMarketplaces.join(", ")}.`, staleMarketplaces.some((name) => Object.hasOwn(claudeExtraKnownMarketplaces(settings.value), name)) ? settingsPath : knownPath));
+    }
+    const installed = readJson(installedPath);
+    if (installed.error) {
+        report.findings.push(finding("config-invalid", `cannot parse Claude plugin state: ${installed.error}`, installedPath));
+    }
+    const plugins = isPlainObject(installed.value?.plugins) ? installed.value.plugins : {};
+    const canonicalEntries = h2aPluginEntries(plugins[H2A_PLUGIN_SELECTOR]);
+    if (!canonicalEntries.some((entry) => pluginEntryIsCurrent(entry, version))) {
+        report.findings.push(finding("version-skew", `Claude h2a plugin does not match npm CLI version ${version}.`, installedPath));
+    }
+    if (canonicalEntries.length === 0) {
+        report.findings.push(finding("plugin-missing", "Claude does not install the canonical h2a@sentropic plugin.", installedPath));
+    }
+    const enabledPlugins = claudeEnabledPlugins(settings.value);
+    const stalePlugins = Object.keys(plugins).filter((name) => (isLegacyH2aPlugin(name) || /^track@sentropic$/i.test(name)) &&
+        enabledPlugins[name] !== false);
+    if (stalePlugins.length > 0) {
+        report.findings.push(finding("plugin-stale", `Claude has stale Sentropic plugin entries: ${stalePlugins.join(", ")}.`, installedPath));
+    }
+    const cacheVersions = claudeCacheVersions(home);
+    const cacheRoot = join(claudeRoot(home), "plugins", "cache");
+    const staleVersions = cacheVersions.filter((entry) => entry !== version && isOwnedPlugin(join(cacheRoot, H2A_MARKETPLACE_NAME, "h2a", entry)));
+    const legacyCaches = listDirectories(cacheRoot).filter((entry) => isLegacySentropicName(entry) && isOwnedLegacyCacheRoot(join(cacheRoot, entry)));
+    if (staleVersions.length > 0 || legacyCaches.length > 0) {
+        report.findings.push(orphanCacheFinding("Claude", [...staleVersions, ...legacyCaches], [
+            ...staleVersions.map((entry) => join(cacheRoot, H2A_MARKETPLACE_NAME, "h2a", entry)),
+            ...legacyCaches.map((entry) => join(cacheRoot, entry))
+        ], cacheRoot));
+    }
+    let directH2a = 0;
+    let directTrack = 0;
+    for (const path of claudeConfigPaths(home)) {
+        const config = readJson(path);
+        if (config.error) {
+            report.findings.push(finding("config-invalid", `cannot parse Claude MCP config: ${config.error}`, path));
+            continue;
+        }
+        const servers = isPlainObject(config.value?.mcpServers) ? config.value.mcpServers : {};
+        for (const entry of Object.values(servers)) {
+            if (isH2aJsonMcp(entry))
+                directH2a++;
+            if (isTrackJsonMcp(entry))
+                directTrack++;
+        }
+    }
+    const endpointCount = (canonicalEntries.length > 0 ? 1 : 0) + directH2a;
+    if (endpointCount !== 1) {
+        report.findings.push(finding("h2a-endpoint-count", `Claude exposes ${endpointCount} H2A endpoints; exactly one plugin endpoint is required.`));
+    }
+    if (directTrack > 0) {
+        report.findings.push(finding("standalone-track-mcp", "Claude has a standalone track-mcp endpoint; track_* must be served by h2a."));
+    }
+    report.coherencePaths.push(...loadBearingArtifacts(report, canonicalEntries.flatMap((entry) => typeof entry.installPath === "string" ? [entry.installPath] : []), claudeConfigPaths(home)));
+    inspectRepairMarker(home, report);
+    return report;
+}
+function jsonArgs(value) {
+    return isPlainObject(value) && Array.isArray(value.args)
+        ? value.args.filter((entry) => typeof entry === "string")
+        : [];
+}
+function isH2aJsonMcp(value) {
+    if (!isPlainObject(value) || typeof value.command !== "string")
+        return false;
+    return (value.command === "h2a" || /[\\/]h2a(?:\.cmd|\.exe)?$/i.test(value.command)) && jsonArgs(value).includes("mcp-serve");
+}
+function isTrackJsonMcp(value) {
+    if (!isPlainObject(value) || typeof value.command !== "string")
+        return false;
+    return value.command === "h2a" && jsonArgs(value).includes("track-mcp");
+}
+function skipJsonWhitespace(raw, index) {
+    while (/\s/.test(raw[index] ?? ""))
+        index++;
+    return index;
+}
+function jsonStringEnd(raw, index) {
+    if (raw[index] !== '"')
+        return undefined;
+    for (let cursor = index + 1; cursor < raw.length; cursor++) {
+        if (raw[cursor] === "\\") {
+            cursor++;
+            continue;
+        }
+        if (raw[cursor] === '"')
+            return cursor + 1;
+    }
+    return undefined;
+}
+function jsonValueEnd(raw, index) {
+    if (raw[index] === '"')
+        return jsonStringEnd(raw, index);
+    if (raw[index] === "{" || raw[index] === "[") {
+        const stack = [raw[index] === "{" ? "}" : "]"];
+        for (let cursor = index + 1; cursor < raw.length; cursor++) {
+            const char = raw[cursor];
+            if (char === '"') {
+                const end = jsonStringEnd(raw, cursor);
+                if (end === undefined)
+                    return undefined;
+                cursor = end - 1;
+                continue;
+            }
+            if (char === "{")
+                stack.push("}");
+            else if (char === "[")
+                stack.push("]");
+            else if (char === "}" || char === "]") {
+                if (stack.pop() !== char)
+                    return undefined;
+                if (stack.length === 0)
+                    return cursor + 1;
+            }
+        }
+        return undefined;
+    }
+    let cursor = index;
+    while (cursor < raw.length && !/[\s,}\]]/.test(raw[cursor]))
+        cursor++;
+    return cursor > index ? cursor : undefined;
+}
+function jsonObjectProperties(raw, objectStart) {
+    if (raw[objectStart] !== "{")
+        return undefined;
+    const properties = [];
+    let cursor = skipJsonWhitespace(raw, objectStart + 1);
+    while (raw[cursor] !== "}") {
+        const start = cursor;
+        const keyEnd = jsonStringEnd(raw, cursor);
+        if (keyEnd === undefined)
+            return undefined;
+        let key;
+        try {
+            key = JSON.parse(raw.slice(cursor, keyEnd));
+        }
+        catch {
+            return undefined;
+        }
+        cursor = skipJsonWhitespace(raw, keyEnd);
+        if (raw[cursor] !== ":")
+            return undefined;
+        const valueStart = skipJsonWhitespace(raw, cursor + 1);
+        const valueEnd = jsonValueEnd(raw, valueStart);
+        if (valueEnd === undefined)
+            return undefined;
+        properties.push({ key, start, end: valueEnd, valueStart, valueEnd });
+        cursor = skipJsonWhitespace(raw, valueEnd);
+        if (raw[cursor] === ",") {
+            cursor = skipJsonWhitespace(raw, cursor + 1);
+        }
+        else if (raw[cursor] !== "}") {
+            return undefined;
+        }
+    }
+    return properties;
+}
+function removeOwnedJsonMcpEntries(raw) {
+    const root = jsonObjectProperties(raw, skipJsonWhitespace(raw, 0));
+    const mcpServers = root?.find((property) => property.key === "mcpServers");
+    if (!mcpServers || raw[mcpServers.valueStart] !== "{")
+        return raw;
+    const servers = jsonObjectProperties(raw, mcpServers.valueStart);
+    if (!servers)
+        return undefined;
+    const removals = servers
+        .map((property, index) => {
+        try {
+            const entry = JSON.parse(raw.slice(property.valueStart, property.valueEnd));
+            return isH2aJsonMcp(entry) || isTrackJsonMcp(entry) ? index : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    })
+        .filter((index) => index !== undefined);
+    if (removals.length === 0)
+        return raw;
+    const ranges = [];
+    for (let start = 0; start < removals.length;) {
+        let end = start;
+        while (end + 1 < removals.length && removals[end + 1] === removals[end] + 1)
+            end++;
+        const first = removals[start];
+        const last = removals[end];
+        ranges.push(last < servers.length - 1
+            ? [servers[first].start, servers[last + 1].start]
+            : first === 0
+                ? [servers[first].start, servers[last].end]
+                : [servers[first - 1].end, servers[last].end]);
+        start = end + 1;
+    }
+    return ranges.reverse().reduce((rendered, [start, end]) => rendered.slice(0, start) + rendered.slice(end), raw);
+}
+function removeOwnedClaudeMarketplaceEntries(raw) {
+    const root = jsonObjectProperties(raw, skipJsonWhitespace(raw, 0));
+    const extraKnownMarketplaces = root?.find((property) => property.key === "extraKnownMarketplaces");
+    if (!extraKnownMarketplaces)
+        return { rendered: raw, unverified: [] };
+    if (raw[extraKnownMarketplaces.valueStart] !== "{")
+        return undefined;
+    const marketplaces = jsonObjectProperties(raw, extraKnownMarketplaces.valueStart);
+    if (!marketplaces)
+        return undefined;
+    const removals = [];
+    const unverified = [];
+    for (const [index, property] of marketplaces.entries()) {
+        if (!isLegacySentropicName(property.key))
+            continue;
+        try {
+            if (claudeSettingsMarketplaceIsOwned(JSON.parse(raw.slice(property.valueStart, property.valueEnd))))
+                removals.push(index);
+            else
+                unverified.push(property.key);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    if (removals.length === 0)
+        return { rendered: raw, unverified };
+    const ranges = [];
+    for (let start = 0; start < removals.length;) {
+        let end = start;
+        while (end + 1 < removals.length && removals[end + 1] === removals[end] + 1)
+            end++;
+        const first = removals[start];
+        const last = removals[end];
+        ranges.push(last < marketplaces.length - 1
+            ? [marketplaces[first].start, marketplaces[last + 1].start]
+            : first === 0
+                ? [marketplaces[first].start, marketplaces[last].end]
+                : [marketplaces[first - 1].end, marketplaces[last].end]);
+        start = end + 1;
+    }
+    return {
+        rendered: ranges.reverse().reduce((rendered, [start, end]) => rendered.slice(0, start) + rendered.slice(end), raw),
+        unverified
+    };
+}
+function setTomlValue(table, key, value) {
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    let replaced = false;
+    const lines = table.lines.map((line, index) => {
+        if (index === 0 || !new RegExp(`^\\s*${escaped}\\s*=`).test(line))
+            return line;
+        replaced = true;
+        return `${key} = ${value}\n`;
+    });
+    return replaced ? lines : [...lines, `${key} = ${value}\n`];
+}
+function canonicalCodexMarketplaceLines(table) {
+    let lines = table?.lines ?? tomlTable(`marketplaces.${H2A_MARKETPLACE_NAME}`, []);
+    lines = setTomlValue({ header: "", lines }, "source_type", '"git"');
+    lines = setTomlValue({ header: "", lines }, "source", `"${H2A_MARKETPLACE_GIT_URL}"`);
+    return setTomlValue({ header: "", lines }, "ref", '"main"');
+}
+function isOwnedLegacyCodexMarketplace(table) {
+    const source = tomlStringValue(table, "source");
+    return typeof source === "string" && isOwnedMarketplace(source);
+}
+function legacyCodexMarketplaceAuthorization(table) {
+    if (table.opaqueReason) {
+        return { removable: false, unavailable: `legacy table contains an opaque TOML region (${table.opaqueReason})` };
+    }
+    if (table.containsMultilineString) {
+        // This rewriter preserves only the table frame. A legacy table containing
+        // a multiline value is not enough evidence to delete it without a complete
+        // TOML parser, even when its local source appears absent.
+        return { removable: false, unavailable: "legacy table contains a multiline TOML string" };
+    }
+    const sourceType = tomlStringValue(table, "source_type");
+    if (sourceType !== "local")
+        return { removable: false };
+    const source = tomlStringValue(table, "source");
+    if (source === undefined) {
+        return { removable: false, unavailable: "TOML source is not a fully decoded single-line string" };
+    }
+    if (isOwnedMarketplace(source))
+        return { removable: true };
+    try {
+        // statSync follows links, matching the path resolution used by Codex.
+        // An inaccessible path is not evidence that the target is gone.
+        statSync(source);
+        return { removable: false };
+    }
+    catch (error) {
+        const code = error.code;
+        return code === "ENOENT" || code === "ENOTDIR"
+            ? { removable: true }
+            : { removable: false, unavailable: code ?? error.message };
+    }
+}
+function redactTomlTableValues(table) {
+    return table.lines
+        .map((line, index) => {
+        if (index === 0)
+            return line.trim();
+        if (line.trim().length === 0)
+            return undefined;
+        const assignment = /^(\s*[^#=\s][^=]*?)=/.exec(line);
+        return assignment ? `${assignment[1].trimEnd()} = <redacted>` : "<redacted>";
+    })
+        .filter((line) => line !== undefined)
+        .join("; ");
+}
+function legacyCodexMarketplaceRemoveAction(table) {
+    const marketplace = tomlQuotedName(table.header, "marketplaces");
+    const previous = redactTomlTableValues(table);
+    return `remove Codex legacy marketplace ${marketplace ?? "<missing>"} table (was ${previous})`;
+}
+function isEnabledLegacyCodexPlugin(table) {
+    const plugin = tomlQuotedName(table.header, "plugins");
+    return Boolean(plugin && isLegacyH2aPlugin(plugin) && tomlBoolean(table, "enabled") !== false);
+}
+function legacyCodexPluginDisableAction(table) {
+    const plugin = tomlQuotedName(table.header, "plugins");
+    return `disable Codex legacy plugin ${plugin ?? "<missing>"} (previous value redacted)`;
+}
+function legacyCodexPluginMarketplace(table) {
+    const plugin = tomlQuotedName(table.header, "plugins");
+    const separator = plugin?.lastIndexOf("@");
+    const marketplace = separator === undefined || separator < 0 ? undefined : plugin?.slice(separator + 1);
+    return marketplace && isLegacySentropicName(marketplace) ? marketplace.toLowerCase() : undefined;
+}
+function reportLegacyMarketplaceAuthorizationFailure(report, path, marketplace, authorization) {
+    if (!authorization.unavailable) {
+        reportUnverifiedOwnership(report, path, `legacy marketplace ${marketplace}`);
+        return;
+    }
+    report.unrepaired.push(finding("ownership-unverified", `cannot remove legacy marketplace ${marketplace}: its local target cannot be verified absent (${authorization.unavailable}).`, path));
+}
+function reportUnverifiedOwnership(report, path, artifact) {
+    report.unrepaired.push(finding("ownership-unverified", `cannot remove ${artifact}: its content does not identify it as an H2A-owned artifact.`, path));
+}
+function repairCodexConfig(home, report, options) {
+    const path = codexConfigPath(home);
+    let raw = "";
+    try {
+        raw = existsSync(path) ? readFileSync(path, "utf8") : "";
+    }
+    catch (error) {
+        report.unrepaired.push(finding("config-invalid", `cannot read Codex config for repair: ${error.message}`, path));
+        return;
+    }
+    const parsed = parseTomlTables(raw);
+    if (parsed.unavailable) {
+        report.unrepaired.push(finding("config-invalid", `cannot safely frame Codex TOML for repair: ${parsed.unavailable}`, path));
+        return;
+    }
+    const tables = parsed.tables;
+    const canonicalPlugin = tables.find((table) => tomlQuotedName(table.header, "plugins") === H2A_PLUGIN_SELECTOR);
+    const canonicalMarketplace = tables.find((table) => tomlQuotedName(table.header, "marketplaces") === H2A_MARKETPLACE_NAME);
+    const canonicalMarketplaceOwned = Boolean(canonicalMarketplace && isOwnedCodexMarketplace(canonicalMarketplace, home));
+    const canonicalPluginOwned = Boolean(canonicalPlugin && (canonicalMarketplaceOwned || hasOwnedCanonicalCodexPlugin(home)));
+    if (canonicalMarketplace && !canonicalMarketplaceOwned) {
+        reportUnverifiedOwnership(report, path, `marketplace ${H2A_MARKETPLACE_NAME}`);
+        return;
+    }
+    if (canonicalPlugin && !canonicalPluginOwned) {
+        reportUnverifiedOwnership(report, path, `plugin ${H2A_PLUGIN_SELECTOR}`);
+        return;
+    }
+    const legacyMarketplaceTables = tables.filter((table) => isLegacySentropicName(tomlQuotedName(table.header, "marketplaces")));
+    const marketplaceAuthorizations = new Map(legacyMarketplaceTables.map((table) => [table.header, legacyCodexMarketplaceAuthorization(table)]));
+    const unavailableMarketplace = legacyMarketplaceTables.find((table) => marketplaceAuthorizations.get(table.header)?.unavailable !== undefined);
+    if (unavailableMarketplace) {
+        reportLegacyMarketplaceAuthorizationFailure(report, path, tomlQuotedName(unavailableMarketplace.header, "marketplaces"), marketplaceAuthorizations.get(unavailableMarketplace.header) ?? { removable: false });
+        return;
+    }
+    const legacyMarketplacesToRemove = new Set(legacyMarketplaceTables
+        .filter((table) => marketplaceAuthorizations.get(table.header)?.removable === true)
+        .map((table) => table.header));
+    const authorizedLegacyMarketplaceNames = new Set(legacyMarketplaceTables
+        .filter((table) => legacyMarketplacesToRemove.has(table.header))
+        .map((table) => tomlQuotedName(table.header, "marketplaces")?.toLowerCase())
+        .filter((name) => name !== undefined));
+    // This is a reversible configuration change, not a deletion: once the
+    // canonical replacement is verified by repairCodex, an active legacy plugin
+    // is neutralised only when its own legacy marketplace is authorised too.
+    const legacyPluginsToDisable = new Set(tables
+        .filter(isEnabledLegacyCodexPlugin)
+        .filter((table) => authorizedLegacyMarketplaceNames.has(legacyCodexPluginMarketplace(table) ?? ""))
+        .map((table) => table.header));
+    for (const table of legacyMarketplaceTables) {
+        if (!legacyMarketplacesToRemove.has(table.header)) {
+            reportLegacyMarketplaceAuthorizationFailure(report, path, tomlQuotedName(table.header, "marketplaces"), marketplaceAuthorizations.get(table.header) ?? { removable: false });
+        }
+    }
+    const needsConfigRepair = tables.some((table) => {
+        const marketplace = tomlQuotedName(table.header, "marketplaces");
+        if (isLegacySentropicName(marketplace) && legacyMarketplacesToRemove.has(table.header))
+            return true;
+        if (marketplace === H2A_MARKETPLACE_NAME && !canonicalCodexMarketplaceConfig(table))
+            return true;
+        const plugin = tomlQuotedName(table.header, "plugins");
+        if (plugin && legacyPluginsToDisable.has(table.header))
+            return true;
+        const mcp = tomlQuotedName(table.header, "mcp_servers");
+        return mcp !== undefined && (isDirectH2aMcp(table) || isDirectTrackMcp(table));
+    }) ||
+        !canonicalMarketplace ||
+        tomlBoolean(canonicalPlugin ?? { header: "", lines: [] }, "enabled") !== true;
+    if (!needsConfigRepair)
+        return;
+    const next = rewriteTomlTables(raw, (table) => {
+        const marketplace = tomlQuotedName(table.header, "marketplaces");
+        if (isLegacySentropicName(marketplace) && legacyMarketplacesToRemove.has(table.header))
+            return undefined;
+        if (marketplace === H2A_MARKETPLACE_NAME) {
+            return canonicalCodexMarketplaceConfig(table) ? [table.raw ?? table.lines.join("")] : canonicalCodexMarketplaceLines(table);
+        }
+        const plugin = tomlQuotedName(table.header, "plugins");
+        if (plugin === H2A_PLUGIN_SELECTOR) {
+            return tomlBoolean(table, "enabled") === true ? [table.raw ?? table.lines.join("")] : setTomlValue(table, "enabled", "true");
+        }
+        if (plugin && legacyPluginsToDisable.has(table.header))
+            return setTomlValue(table, "enabled", "false");
+        const mcp = tomlQuotedName(table.header, "mcp_servers");
+        if (mcp !== undefined && (isDirectH2aMcp(table) || isDirectTrackMcp(table)))
+            return undefined;
+        return [table.raw ?? table.lines.join("")];
+    });
+    const additions = [
+        ...(canonicalMarketplace ? [] : tomlTable(`marketplaces.${H2A_MARKETPLACE_NAME}`, [
+            'source_type = "git"',
+            `source = "${H2A_MARKETPLACE_GIT_URL}"`,
+            'ref = "main"'
+        ])),
+        ...(canonicalPlugin ? [] : tomlTable(`plugins.\"${H2A_PLUGIN_SELECTOR}\"`, ["enabled = true"]))
+    ];
+    const rendered = additions.length === 0
+        ? next
+        : `${next}${next.endsWith("\n") ? "\n" : "\n\n"}${additions.join("")}`;
+    if (rendered === raw)
+        return;
+    if (options.dryRun) {
+        for (const table of tables.filter((table) => legacyPluginsToDisable.has(table.header))) {
+            planAction(report, legacyCodexPluginDisableAction(table));
+        }
+        for (const table of legacyMarketplaceTables.filter((table) => legacyMarketplacesToRemove.has(table.header))) {
+            planAction(report, legacyCodexMarketplaceRemoveAction(table));
+        }
+        planAction(report, `rewrite ${path}`);
+        return;
+    }
+    const revalidateLegacyMarketplacesBeforeReplace = () => {
+        const revalidatedAuthorizations = new Map(legacyMarketplaceTables.map((table) => [table.header, legacyCodexMarketplaceAuthorization(table)]));
+        const revalidatedUnavailableMarketplace = legacyMarketplaceTables.find((table) => revalidatedAuthorizations.get(table.header)?.unavailable !== undefined);
+        if (revalidatedUnavailableMarketplace) {
+            reportLegacyMarketplaceAuthorizationFailure(report, path, tomlQuotedName(revalidatedUnavailableMarketplace.header, "marketplaces"), revalidatedAuthorizations.get(revalidatedUnavailableMarketplace.header) ?? { removable: false });
+            return "legacy marketplace target became unavailable before atomic rename";
+        }
+        const revalidatedMarketplacesToRemove = new Set(legacyMarketplaceTables
+            .filter((table) => revalidatedAuthorizations.get(table.header)?.removable === true)
+            .map((table) => table.header));
+        if ([...legacyMarketplacesToRemove].some((header) => !revalidatedMarketplacesToRemove.has(header)) ||
+            [...revalidatedMarketplacesToRemove].some((header) => !legacyMarketplacesToRemove.has(header))) {
+            for (const table of legacyMarketplaceTables) {
+                const initial = marketplaceAuthorizations.get(table.header);
+                const revalidated = revalidatedAuthorizations.get(table.header);
+                if (initial?.removable === true && revalidated?.removable !== true) {
+                    reportLegacyMarketplaceAuthorizationFailure(report, path, tomlQuotedName(table.header, "marketplaces"), revalidated ?? { removable: false });
+                }
+            }
+            return "legacy marketplace authorization changed before atomic rename";
+        }
+        return undefined;
+    };
+    for (const table of tables.filter((table) => legacyPluginsToDisable.has(table.header))) {
+        planAction(report, legacyCodexPluginDisableAction(table));
+    }
+    for (const table of legacyMarketplaceTables.filter((table) => legacyMarketplacesToRemove.has(table.header))) {
+        planAction(report, legacyCodexMarketplaceRemoveAction(table));
+    }
+    try {
+        const error = atomicConfigurationWrite(path, raw, rendered, "toml", options.testConfigurationWrite, revalidateLegacyMarketplacesBeforeReplace);
+        if (error)
+            throw new Error(error);
+        pushUnique(report.changed, path);
+    }
+    catch (error) {
+        report.unrepaired.push(finding("config-invalid", `cannot write Codex config: ${error.message}`, path));
+    }
+}
+function repairClaudeMcpConfigs(home, report, dryRun, testConfigurationWrite) {
+    let failed = false;
+    for (const path of claudeConfigPaths(home)) {
+        let raw;
+        try {
+            raw = readFileSync(path, "utf8");
+            const value = JSON.parse(raw);
+            if (!isPlainObject(value))
+                throw new Error("JSON root is not an object");
+        }
+        catch (error) {
+            report.unrepaired.push(finding("config-invalid", `cannot parse Claude MCP config for repair: ${error.message}`, path));
+            failed = true;
+            continue;
+        }
+        const rendered = removeOwnedJsonMcpEntries(raw);
+        if (rendered === undefined) {
+            report.unrepaired.push(finding("config-invalid", "cannot locate Claude MCP entries for safe repair", path));
+            failed = true;
+            continue;
+        }
+        if (rendered === raw)
+            continue;
+        if (dryRun) {
+            planAction(report, `rewrite ${path}`);
+            continue;
+        }
+        try {
+            const error = atomicConfigurationWrite(path, raw, rendered, "json", testConfigurationWrite);
+            if (error)
+                throw new Error(error);
+            pushUnique(report.changed, path);
+        }
+        catch (error) {
+            failed = true;
+            report.unrepaired.push(finding("config-invalid", `cannot write Claude MCP config: ${error.message}`, path));
+        }
+    }
+    return failed;
+}
+function repairClaudeSettingsMarketplaces(home, report, dryRun, testConfigurationWrite) {
+    const path = claudeSettingsPath(home);
+    if (!existsSync(path))
+        return false;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+        if (!isPlainObject(JSON.parse(raw)))
+            throw new Error("JSON root is not an object");
+    }
+    catch (error) {
+        report.unrepaired.push(finding("config-invalid", `cannot parse Claude settings for repair: ${error.message}`, path));
+        return true;
+    }
+    const result = removeOwnedClaudeMarketplaceEntries(raw);
+    if (!result) {
+        report.unrepaired.push(finding("config-invalid", "cannot locate Claude settings marketplaces for safe repair", path));
+        return true;
+    }
+    for (const marketplace of result.unverified) {
+        reportUnverifiedOwnership(report, path, `legacy marketplace ${marketplace}`);
+    }
+    if (result.rendered === raw)
+        return false;
+    if (dryRun) {
+        planAction(report, `rewrite ${path}`);
+        return false;
+    }
+    try {
+        const error = atomicConfigurationWrite(path, raw, result.rendered, "json", testConfigurationWrite);
+        if (error)
+            throw new Error(error);
+        pushUnique(report.changed, path);
+        return false;
+    }
+    catch (error) {
+        report.unrepaired.push(finding("config-invalid", `cannot write Claude settings: ${error.message}`, path));
+        return true;
+    }
+}
+// runCommand contains the installation doctor's only native runner invocation.
+// Claude's native uninstall argv is exactly ["plugin", "uninstall", selector], with no preceding flags.
+// Codex has no native uninstall path; its repair rewrites its own configuration and cache.
+function runCommand(report, runner, command, args, dryRun, nativeCliReachable) {
+    if (command === "claude" &&
+        args[0] === "plugin" &&
+        args[1] === "uninstall" &&
+        !isAuthorizedClaudePluginUninstall(args[2])) {
+        report.unrepaired.push(finding("host-command-refused", `refused native command: ${command} ${args.join(" ")}; selector ${args[2] ?? "<missing>"} is not authorized for uninstall.`));
+        return false;
+    }
+    if (!nativeCliReachable) {
+        report.unrepaired.push(finding("host-command-unavailable", `cannot run ${command} ${args.join(" ")}: the native ${command} CLI is unavailable.`));
+        return false;
+    }
+    if (dryRun) {
+        planAction(report, `${command} ${args.join(" ")}`);
+        return true;
+    }
+    const result = runner(command, args);
+    if (result.ok)
+        return true;
+    report.unrepaired.push(finding("host-command-failed", `${command} ${args.join(" ")} failed: ${result.message ?? "unknown error"}`));
+    return false;
+}
+/**
+ * A TOML region that doctor deliberately leaves alone is only informational if
+ * Codex can still load the resulting configuration.  Its parser is a framing
+ * safeguard, not a second implementation of Codex's configuration grammar;
+ * `codex mcp list` is therefore the acceptance oracle.
+ */
+function codexOracleContext(codexHome) {
+    return {
+        cwd: codexHome,
+        // This only changes the spawned Codex process.  It never reads or writes
+        // the owner's CODEX_HOME while checking the disposable known-good root.
+        env: { ...process.env, CODEX_HOME: codexHome }
+    };
+}
+function verifyCodexOracleKnownGood(testOracle) {
+    if (testOracle)
+        return testOracle.knownGood;
+    let oracleHome;
+    let oracleResult;
+    try {
+        oracleHome = mkdtempSync(join(tmpdir(), "h2a-codex-config-oracle-"));
+        writeFileSync(join(oracleHome, "config.toml"), "# known-good empty Codex configuration\n");
+        oracleResult = defaultHostCommand("codex", ["mcp", "list"], codexOracleContext(oracleHome));
+    }
+    catch (error) {
+        oracleResult = { ok: false, message: error.message };
+    }
+    if (oracleHome) {
+        try {
+            rmSync(oracleHome, { recursive: true, force: true });
+        }
+        catch (error) {
+            return { ok: false, message: `cannot remove disposable oracle root: ${error.message}` };
+        }
+    }
+    return oracleResult;
+}
+function verifyCodexConfiguration(home, report, nativeCliReachable, testOracle) {
+    if (!nativeCliReachable)
+        return false;
+    const oracleSelfTest = verifyCodexOracleKnownGood(testOracle);
+    const configPath = codexConfigPath(home);
+    if (!oracleSelfTest.ok) {
+        report.unrepaired.push(finding("host-config-unverifiable", `Codex configuration oracle could not validate a known-good minimal configuration; it did not judge ${configPath}: ${oracleSelfTest.message ?? "unknown error"}`, configPath));
+        return false;
+    }
+    const result = testOracle?.candidate ?? defaultHostCommand("codex", ["mcp", "list"], codexOracleContext(codexRoot(home)));
+    if (result.ok)
+        return true;
+    // A region is deliberately preserved only when the host accepts the whole
+    // file containing it.  Once the oracle rejects that file, retaining any
+    // config-preserved finding for it would recreate the false-clean verdict.
+    report.preserved = report.preserved.filter((entry) => !(entry.code === "config-preserved" && entry.path === configPath));
+    report.unrepaired.push(finding("config-invalid", `Codex rejected its configuration while running codex mcp list: ${result.message ?? "unknown error"}`, configPath));
+    return false;
+}
+function reportAcceptedOpaqueCodexRegions(home, report) {
+    const path = codexConfigPath(home);
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = parseTomlTables(raw);
+        if (!parsed.unavailable)
+            reportOpaqueTomlRegions(report, path, parsed.tables);
+    }
+    catch {
+        // inspectCodex carries a configuration that cannot be read or framed.
+    }
+}
+function artifactSnapshots(paths) {
+    const snapshots = new Map();
+    for (const path of paths) {
+        try {
+            const metadata = statSync(path);
+            snapshots.set(path, `${metadata.dev}:${metadata.ino}:${metadata.size}:${metadata.mtimeMs}`);
+        }
+        catch {
+            // The host inspection already carries an unavailable load-bearing artifact.
+        }
+    }
+    return snapshots;
+}
+function actualRepairPaths(before, after, beforeArtifacts) {
+    const rewrittenArtifacts = after.coherencePaths.filter((path) => {
+        try {
+            const metadata = statSync(path);
+            const current = `${metadata.dev}:${metadata.ino}:${metadata.size}:${metadata.mtimeMs}`;
+            return beforeArtifacts.get(path) !== current;
+        }
+        catch {
+            return false;
+        }
+    });
+    return [...before.changed, ...rewrittenArtifacts];
+}
+function removeOwnedCache(report, path, artifact, owned, dryRun) {
+    if (!owned) {
+        reportUnverifiedOwnership(report, path, artifact);
+        return;
+    }
+    if (dryRun) {
+        planAction(report, `remove ${path}`);
+        return;
+    }
+    try {
+        rmSync(path, { recursive: true, force: true });
+        pushUnique(report.changed, path);
+    }
+    catch (error) {
+        report.unrepaired.push(finding("orphan-cache", `cannot remove ${path}: ${error.message}`, path));
+    }
+}
+function codexReplacementIsReady(home, version) {
+    return (cacheVersionMatches(join(codexRoot(home), "plugins", "cache", H2A_MARKETPLACE_NAME, "h2a", version), version) &&
+        isOwnedMarketplace(join(codexRoot(home), ".tmp", "marketplaces", H2A_MARKETPLACE_NAME)));
+}
+function claudeKnownMarketplaceIsOwned(value) {
+    return isPlainObject(value) && typeof value.installLocation === "string" && isOwnedMarketplace(value.installLocation);
+}
+function claudeSettingsMarketplaceIsOwned(value) {
+    if (!isPlainObject(value))
+        return false;
+    const source = value.source;
+    return (isPlainObject(source) &&
+        source.source === "directory" &&
+        typeof source.path === "string" &&
+        isOwnedMarketplace(source.path));
+}
+function claudeReplacementIsReady(home, version) {
+    const known = readJson(join(claudeRoot(home), "plugins", "known_marketplaces.json")).value;
+    const installed = readJson(join(claudeRoot(home), "plugins", "installed_plugins.json")).value;
+    const plugins = isPlainObject(installed?.plugins) ? installed.plugins : {};
+    return (canonicalMarketplace(known?.[H2A_MARKETPLACE_NAME]) &&
+        h2aPluginEntries(plugins[H2A_PLUGIN_SELECTOR]).some((entry) => pluginEntryIsCurrent(entry, version)));
+}
+function repairCodex(home, version, runner, writeMarker, dryRun, testConfigurationWrite, nativeCliReachable = true) {
+    const before = inspectCodex(home, version);
+    const beforeArtifacts = artifactSnapshots(before.coherencePaths);
+    // A vanished local marketplace is a distinct recovery case. Codex reports
+    // `plugin marketplace upgrade` success with "No configured Git marketplaces
+    // to upgrade", leaving the dead source and its cached plugin untouched.
+    // Install the native replacement first, and leave every old configuration
+    // and endpoint intact until that replacement is verified.
+    let sourceRecovery = true;
+    try {
+        const config = existsSync(codexConfigPath(home)) ? readFileSync(codexConfigPath(home), "utf8") : "";
+        const parsed = parseTomlTables(config);
+        const canonicalTable = parsed.tables.find((table) => tomlQuotedName(table.header, "marketplaces") === H2A_MARKETPLACE_NAME);
+        sourceRecovery = !parsed.unavailable && !canonicalCodexMarketplaceConfig(canonicalTable);
+    }
+    catch {
+        // repairCodexConfig below records the unreadable config as unrepaired.
+    }
+    const needsPlugin = before.findings.some((entry) => ["marketplace-missing", "marketplace-stale", "plugin-missing", "plugin-stale", "version-skew"].includes(entry.code));
+    let replacementCommandsSucceeded = true;
+    if (sourceRecovery) {
+        replacementCommandsSucceeded = runCommand(before, runner, "codex", [
+            "plugin",
+            "marketplace",
+            "add",
+            H2A_MARKETPLACE_REPOSITORY,
+            "--ref",
+            "main"
+        ], dryRun, nativeCliReachable);
+    }
+    else if (needsPlugin) {
+        replacementCommandsSucceeded = runCommand(before, runner, "codex", ["plugin", "marketplace", "upgrade"], dryRun, nativeCliReachable);
+    }
+    if (needsPlugin && replacementCommandsSucceeded) {
+        replacementCommandsSucceeded = runCommand(before, runner, "codex", ["plugin", "add", H2A_PLUGIN_SELECTOR], dryRun, nativeCliReachable);
+    }
+    const replacementReady = dryRun
+        ? replacementCommandsSucceeded
+        : replacementCommandsSucceeded && codexReplacementIsReady(home, version);
+    if (!replacementReady) {
+        if (replacementCommandsSucceeded && !dryRun) {
+            before.unrepaired.push(finding("plugin-missing", "cannot safely remove existing Codex endpoints because the canonical replacement was not verified."));
+        }
+        return combineAfterRepair(before, inspectCodex(home, version));
+    }
+    repairCodexConfig(home, before, { dryRun, testConfigurationWrite });
+    if (before.unrepaired.some((entry) => entry.code === "config-invalid")) {
+        return combineAfterRepair(before, inspectCodex(home, version));
+    }
+    // v1 deliberately retains legacy orphan caches. A stale version underneath
+    // the canonical, verified cache remains part of the normal version repair.
+    const cache = join(codexRoot(home), "plugins", "cache");
+    if (cacheVersionMatches(join(cache, H2A_MARKETPLACE_NAME, "h2a", version), version)) {
+        for (const stale of codexCacheVersions(home).filter((entry) => entry !== version && isOwnedPlugin(join(cache, H2A_MARKETPLACE_NAME, "h2a", entry)))) {
+            const path = join(cache, H2A_MARKETPLACE_NAME, "h2a", stale);
+            removeOwnedCache(before, path, `Codex cache ${path}`, isOwnedPlugin(path), dryRun);
+        }
+    }
+    const afterNativeRepair = inspectCodex(home, version);
+    if (dryRun) {
+        if (before.plannedActions.length > 0)
+            planAction(before, `record repair marker after verified mutation at ${repairMarkerPath(home, "codex")}`);
+    }
+    else {
+        const repairedPaths = actualRepairPaths(before, afterNativeRepair, beforeArtifacts);
+        recordRepairMarker(home, before, repairedPaths, writeMarker);
+    }
+    return combineAfterRepair(before, inspectCodex(home, version));
+}
+function repairClaude(home, version, runner, writeMarker, dryRun, testClaudePluginUninstalls, testConfigurationWrite, nativeCliReachable = true) {
+    const before = inspectClaude(home, version);
+    const beforeArtifacts = artifactSnapshots(before.coherencePaths);
+    const knownPath = join(claudeRoot(home), "plugins", "known_marketplaces.json");
+    const installedPath = join(claudeRoot(home), "plugins", "installed_plugins.json");
+    const known = readJson(knownPath).value ?? {};
+    const installed = readJson(installedPath).value ?? {};
+    const initialPlugins = isPlainObject(installed.plugins) ? installed.plugins : {};
+    const enabledPlugins = claudeEnabledPlugins(readJson(claudeSettingsPath(home)).value);
+    const needsMarketplace = before.findings.some((entry) => ["marketplace-missing", "marketplace-stale"].includes(entry.code));
+    const needsPlugin = before.findings.some((entry) => ["plugin-missing", "version-skew", "plugin-stale"].includes(entry.code));
+    let replacementCommandsSucceeded = true;
+    if (needsMarketplace) {
+        replacementCommandsSucceeded = runCommand(before, runner, "claude", ["plugin", "marketplace", "add", H2A_MARKETPLACE_REPOSITORY], dryRun, nativeCliReachable);
+    }
+    const canonical = h2aPluginEntries(initialPlugins[H2A_PLUGIN_SELECTOR]);
+    const action = canonical.length === 0 ? "install" : "update";
+    if (needsPlugin && replacementCommandsSucceeded) {
+        replacementCommandsSucceeded = runCommand(before, runner, "claude", ["plugin", action, H2A_PLUGIN_SELECTOR], dryRun, nativeCliReachable);
+    }
+    const replacementReady = dryRun
+        ? replacementCommandsSucceeded
+        : replacementCommandsSucceeded && claudeReplacementIsReady(home, version);
+    if (!replacementReady) {
+        if (replacementCommandsSucceeded && !dryRun) {
+            before.unrepaired.push(finding("plugin-missing", "cannot safely remove existing Claude endpoints because the canonical replacement was not verified."));
+        }
+        return combineAfterRepair(before, inspectClaude(home, version));
+    }
+    if (repairClaudeMcpConfigs(home, before, dryRun, testConfigurationWrite) ||
+        repairClaudeSettingsMarketplaces(home, before, dryRun, testConfigurationWrite)) {
+        return combineAfterRepair(before, inspectClaude(home, version));
+    }
+    const repairedKnown = readJson(knownPath).value ?? {};
+    const repairedInstalled = readJson(installedPath).value ?? {};
+    for (const marketplace of Object.keys(repairedKnown).filter(isLegacySentropicName)) {
+        if (!claudeKnownMarketplaceIsOwned(repairedKnown[marketplace])) {
+            reportUnverifiedOwnership(before, knownPath, `legacy marketplace ${marketplace}`);
+            continue;
+        }
+        runCommand(before, runner, "claude", ["plugin", "marketplace", "remove", marketplace], dryRun, nativeCliReachable);
+    }
+    const plugins = isPlainObject(repairedInstalled.plugins) ? repairedInstalled.plugins : {};
+    for (const plugin of Object.keys(plugins).filter((name) => (isLegacyH2aPlugin(name) || /^track@sentropic$/i.test(name)) &&
+        enabledPlugins[name] !== false)) {
+        if (!pluginEntriesAreOwned(plugin, plugins[plugin])) {
+            reportUnverifiedOwnership(before, installedPath, `legacy plugin ${plugin}`);
+            continue;
+        }
+        runCommand(before, runner, "claude", ["plugin", "uninstall", plugin], dryRun, nativeCliReachable);
+    }
+    for (const plugin of testClaudePluginUninstalls) {
+        runCommand(before, runner, "claude", ["plugin", "uninstall", plugin], dryRun, nativeCliReachable);
+    }
+    // v1 deliberately retains legacy orphan caches. A stale version underneath
+    // the canonical, verified cache remains part of the normal version repair.
+    const cache = join(claudeRoot(home), "plugins", "cache");
+    if (cacheVersionMatches(join(cache, H2A_MARKETPLACE_NAME, "h2a", version), version)) {
+        for (const stale of claudeCacheVersions(home).filter((entry) => entry !== version && isOwnedPlugin(join(cache, H2A_MARKETPLACE_NAME, "h2a", entry)))) {
+            const path = join(cache, H2A_MARKETPLACE_NAME, "h2a", stale);
+            removeOwnedCache(before, path, `Claude cache ${path}`, isOwnedPlugin(path), dryRun);
+        }
+    }
+    const afterNativeRepair = inspectClaude(home, version);
+    if (dryRun) {
+        if (before.plannedActions.length > 0)
+            planAction(before, `record repair marker after verified mutation at ${repairMarkerPath(home, "claude")}`);
+    }
+    else {
+        recordRepairMarker(home, before, actualRepairPaths(before, afterNativeRepair, beforeArtifacts), writeMarker);
+    }
+    return combineAfterRepair(before, inspectClaude(home, version));
+}
+function combineAfterRepair(before, after) {
+    const unrepaired = [...before.unrepaired, ...after.findings].filter(isBlockingFinding);
+    return {
+        ...after,
+        changed: before.changed,
+        preserved: [...before.preserved, ...after.preserved],
+        unrepaired,
+        coherencePaths: [...new Set([...before.coherencePaths, ...after.coherencePaths])],
+        plannedActions: [...new Set([...before.plannedActions, ...after.plannedActions])],
+        repairMarker: after.repairMarker ?? before.repairMarker
+    };
+}
+function freezeReport(report) {
+    const outcomes = uniqueFindings([
+        ...report.preserved,
+        ...report.unrepaired,
+        ...report.findings,
+        ...report.diagnostics
+    ]);
+    const preserved = outcomes.filter((entry) => hostFindingBucket(entry) === "preserved");
+    const failures = outcomes.filter((entry) => hostFindingBucket(entry) === "failure");
+    const unverifiable = outcomes.filter((entry) => hostFindingBucket(entry) === "unverifiable");
+    return {
+        host: report.host,
+        ok: failures.length === 0 && unverifiable.length === 0,
+        findings: report.findings,
+        diagnostics: report.diagnostics,
+        changed: report.changed,
+        preserved,
+        failures,
+        unverifiable,
+        unrepaired: [...failures, ...unverifiable],
+        coherencePaths: report.coherencePaths,
+        plannedActions: report.plannedActions,
+        repairMarkerPath: report.repairMarkerPath,
+        ...(report.repairMarker ? { repairMarker: report.repairMarker } : {})
+    };
+}
+/** Inspect, and optionally repair, the H2A installation state of both supported hosts. */
+export function doctorHostInstallations(options = {}) {
+    const home = options.home ?? homedir();
+    const version = options.version ?? currentCliVersion();
+    const repair = options.repair === true;
+    const dryRun = options.dryRun === true;
+    const runner = options.runHostCommand ?? defaultHostCommand;
+    const writeMarker = options.writeRepairMarker ?? ((path, content) => writeFileSync(path, content));
+    const inspectOrRepair = (host) => {
+        const artifacts = hostConfigurationArtifacts(home, host);
+        const cli = hostCliCanRunNativeRepair(host, options.runHostCommand !== undefined, options.testHostCliReachable);
+        if (artifacts.unavailable.length > 0) {
+            return unavailableHostConfigurationReport(home, host, artifacts.unavailable);
+        }
+        if (cli.state === "unavailable") {
+            return unavailableHostCliReport(home, host, cli);
+        }
+        const cliReachable = cli.state === "reachable";
+        if (!cliReachable && artifacts.present.length === 0) {
+            return absentHostReport(home, host);
+        }
+        let report;
+        if (host === "claude") {
+            report = repair
+                ? repairClaude(home, version, runner, writeMarker, dryRun, options.testClaudePluginUninstalls ?? [], options.testConfigurationWrite, cliReachable)
+                : inspectClaude(home, version);
+        }
+        else {
+            report = repair
+                ? repairCodex(home, version, runner, writeMarker, dryRun, options.testConfigurationWrite, cliReachable)
+                : inspectCodex(home, version);
+            // `testHostCliReachable` deliberately models only CLI presence for
+            // hermetic fixture tests.  It must not accidentally query a developer's
+            // configured Codex installation; the production path has no such
+            // override and always asks the real host.
+            if (cliReachable && (options.testHostCliReachable === undefined || options.testCodexConfigurationOracle !== undefined)) {
+                const accepted = verifyCodexConfiguration(home, report, cliReachable, options.testCodexConfigurationOracle);
+                if (accepted)
+                    reportAcceptedOpaqueCodexRegions(home, report);
+            }
+        }
+        if (!cliReachable)
+            report.unrepaired.push(unreachableHostCliDiagnostic(host, artifacts.present));
+        return report;
+    };
+    const mutable = [inspectOrRepair("claude"), inspectOrRepair("codex")];
+    const hosts = mutable.map(freezeReport);
+    return {
+        ok: hosts.every((host) => host.ok),
+        repair,
+        dryRun,
+        sessionFreshnessGuarantee: HOST_REPAIR_FRESHNESS_GUARANTEE,
+        nativeCommandFailureLimit: HOST_REPAIR_NATIVE_COMMAND_FAILURE_LIMIT,
+        version,
+        hosts
+    };
+}
+/**
+ * A host repair cannot rewire an already-open stdio connection. A recorded
+ * repair marker is authoritative for our repairs. Doctor does not infer the
+ * complete runtime load graph, so externally modified artifacts are diagnostic
+ * only and never become a live-session freshness verdict.
+ */
+export function findLiveSessionsPredatingHostConfig(sessions, hosts) {
+    const byHost = new Map(hosts.map((host) => [host.host, host]));
+    const findings = [];
+    for (const session of sessions) {
+        const host = session.host === "claude" || session.host === "codex" ? session.host : undefined;
+        if (!host)
+            continue;
+        const report = byHost.get(host);
+        if (!report)
+            continue;
+        const startedAt = Date.parse(session.startedAt);
+        if (!Number.isFinite(startedAt)) {
+            findings.push({
+                host,
+                sessionId: session.sessionId,
+                startedAt: session.startedAt,
+                configPath: report.repairMarkerPath,
+                message: `cannot verify when live ${host} session ${session.sessionId} started; ` +
+                    "its temporal order relative to host repairs is unknown and it must be restarted."
+            });
+            continue;
+        }
+        const marker = report.repairMarker;
+        if (!marker) {
+            const markerState = existsSync(report.repairMarkerPath) ? "unavailable" : "missing";
+            findings.push({
+                host,
+                sessionId: session.sessionId,
+                startedAt: session.startedAt,
+                configPath: report.repairMarkerPath,
+                message: `cannot verify host repair marker ${report.repairMarkerPath}: it is ${markerState}; ` +
+                    `live ${host} session ${session.sessionId} must be restarted.`
+            });
+            continue;
+        }
+        const repairedAt = Date.parse(marker.repairedAt);
+        if (!Number.isFinite(repairedAt)) {
+            findings.push({
+                host,
+                sessionId: session.sessionId,
+                startedAt: session.startedAt,
+                configPath: marker.path,
+                message: `cannot verify host repair marker ${marker.path}; live ${host} session ${session.sessionId} must be restarted.`
+            });
+            continue;
+        }
+        if (startedAt < repairedAt) {
+            findings.push({
+                host,
+                sessionId: session.sessionId,
+                startedAt: session.startedAt,
+                configPath: marker.path,
+                message: `live ${host} session ${session.sessionId} started before repair marker ${marker.path}; ` +
+                    "it may still run the pre-repair H2A/Track MCP set and must be restarted."
+            });
+            continue;
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=installation-doctor.js.map