@bridge_gpt/mcp-server 0.2.67 → 0.2.68

package/build/bridge-permissions.js

@@ -0,0 +1,829 @@
+/**
+ * Bridge-managed Claude Code permission rules for the `/drive-epic-run`
+ * supervisor (BAPI-1398, AC-8).
+ *
+ * The supervisor runs in auto mode. Every in-scope action it takes — a
+ * sanctioned CLI verb, a Bridge MCP tool, a read, a tally write — must resolve
+ * without a permission prompt or a classifier denial. Narrow
+ * `permissions.allow` rules resolve before the auto-mode classifier, so the
+ * installer writes one exact rule for every shell and tool form the posture
+ * prescribes, into the project's LOCAL settings file,
+ * `.claude/settings.local.json`. Claude Code reads that file as project-scoped
+ * settings, and it is per developer and gitignored. The rules must never go into
+ * the committed `.claude/settings.json`: they can hold a developer's own
+ * launcher path, they belong to one developer's manifest, and a committed allow
+ * rule would widen every teammate's sessions. The MCP tool rules are written
+ * under the key the server is actually registered as in `.mcp.json` (canonical
+ * `bridge`, or a kept legacy registration key), so they match the tool
+ * names Claude Code really sees. The auto-mode
+ * classifier ignores `autoMode` in project settings, so the prose
+ * `autoMode.allow` / `autoMode.environment` entries go into the USER's
+ * `~/.claude/settings.json` — and only with the user's explicit consent.
+ *
+ * Ownership. A JSON string in an allow list cannot carry a marker, and Claude
+ * Code's settings loader is not given unknown keys. Bridge therefore records the
+ * exact strings it inserted in its own manifest, `.bridge/bridge-permissions.json`
+ * (gitignored, per developer). `doctor` reads it to report present / missing /
+ * drifted, and removal deletes exactly those strings. A string the user already
+ * had before Bridge wrote it is never claimed, so removal never takes it away.
+ * The manifest is separate from `.bridge/install-state.json` because that file's
+ * contract forbids absolute home paths, and a local launcher override is often
+ * one.
+ *
+ * File discipline matches `claude-settings.ts`: a missing settings file is `{}`;
+ * a malformed one is reported as `malformed` and never written; changed files
+ * are written with a 2-space indent and one trailing newline; an unchanged file
+ * is not rewritten, so a second run leaves every file byte-identical.
+ *
+ * Never broad: no `Bash(*)`, no wildcard launcher, and no rule that covers a
+ * credential file. A launcher override that cannot be written as an exact,
+ * secret-free command prefix is refused rather than approximated.
+ */
+import path from "node:path";
+import { MCP_PACKAGE_NAME, MCP_SERVER_NAME, resolveRegistrationKey } from "./mcp-identity.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** The environment variable the posture reads for a local launcher override. */
+export const BRIDGE_LAUNCHER_ENV = "BAPI_MCP_CLI";
+/** The default packaged launcher prefix — byte-identical to the posture's default. */
+export const BRIDGE_DEFAULT_LAUNCHER = `npx -y ${MCP_PACKAGE_NAME}`;
+/** Repository-relative path of Bridge's permission-ownership manifest. */
+export const BRIDGE_PERMISSIONS_MANIFEST_RELPATH = ".bridge/bridge-permissions.json";
+/**
+ * Repository-relative path of the project settings file the rules go into. It is
+ * the per-developer, gitignored local file — never the committed
+ * `.claude/settings.json`.
+ */
+export const BRIDGE_PROJECT_SETTINGS_RELPATH = ".claude/settings.local.json";
+/** Current manifest schema version. */
+export const BRIDGE_PERMISSIONS_MANIFEST_VERSION = 1;
+/** The auto-mode sentinel that keeps Claude Code's built-in entries in a list. */
+export const AUTO_MODE_DEFAULTS_SENTINEL = "$defaults";
+/**
+ * The sanctioned recovery verbs, as their packaged CLI subcommands, in
+ * the posture's verb-table order. Adding a verb here without adding it to the
+ * posture's verb table (or the reverse) is caught by the static coverage test.
+ */
+export const BRIDGE_SANCTIONED_VERB_SUBCOMMANDS = [
+    "unpark",
+    "continue-child",
+    "grant-continuation",
+    "adopt-current-head-and-unpark",
+    "stop-run",
+    "abandon-run",
+    "scope-reparse",
+    "dispatch-remediation",
+    "merge-child",
+    "scope-catch-up",
+    "patch-policy",
+    "resume-run",
+    "resume-ci",
+    "rerun-ci",
+];
+/** The Bridge MCP tools the supervisor calls. */
+export const BRIDGE_SUPERVISOR_MCP_TOOLS = [
+    "ping",
+    "explain_run",
+    "get_epic_snapshot",
+    "poll_ci_checks",
+    "second_opinion",
+    "report_mcp_bug",
+    // BAPI-1399: the prerequisite scan reads the epic and its child tickets.
+    "get_ticket",
+];
+/** The private run-state directory the tally, patch, and context files live in. */
+export const BRIDGE_RUN_STATE_DIR = "~/.local/state/bapi-conductor-runs";
+/**
+ * Launcher override characters that cannot be part of an exact, safe rule
+ * prefix: shell operators, quotes (the posture writes the launcher unquoted),
+ * rule-pattern metacharacters, an environment assignment (`=`), and a home
+ * shorthand that the shell would expand differently from the rule.
+ */
+const UNSAFE_LAUNCHER_PATTERN = /[;&|<>$`\\'"*?()[\]{}=~\n\r\t\0]/;
+/** Upper bound on a launcher override, so a pasted blob is never a rule. */
+const MAX_LAUNCHER_CHARS = 256;
+/** Tokens that suggest a credential was pasted into the launcher value. */
+const SECRET_LIKE_PATTERN = /(api[_-]?key|token|secret|passw(or)?d|bearer|bapi_[a-z0-9]{8,})/i;
+/**
+ * Resolve the launcher prefix exactly as the posture resolves it: unset, empty,
+ * or whitespace-only means the default packaged launcher; anything else is used
+ * verbatim. Internal runs of whitespace collapse to one space, because that is
+ * how the posture writes the launcher's words. An override that cannot be an
+ * exact, secret-free prefix is refused — never approximated with a wildcard.
+ * The refusal reason never echoes the value.
+ */
+export function resolvePermissionLauncher(env) {
+    const raw = env[BRIDGE_LAUNCHER_ENV];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { ok: true, prefix: BRIDGE_DEFAULT_LAUNCHER, source: "default" };
+    }
+    const trimmed = raw.trim();
+    if (trimmed.length > MAX_LAUNCHER_CHARS) {
+        return { ok: false, reason: `${BRIDGE_LAUNCHER_ENV} is longer than ${MAX_LAUNCHER_CHARS} characters` };
+    }
+    if (UNSAFE_LAUNCHER_PATTERN.test(trimmed)) {
+        return {
+            ok: false,
+            reason: `${BRIDGE_LAUNCHER_ENV} contains a quote, shell operator, wildcard, or assignment, ` +
+                "so it cannot be matched by an exact permission rule",
+        };
+    }
+    if (SECRET_LIKE_PATTERN.test(trimmed)) {
+        return {
+            ok: false,
+            reason: `${BRIDGE_LAUNCHER_ENV} looks like it carries a credential, which must never be part of a rule`,
+        };
+    }
+    return { ok: true, prefix: trimmed.split(/\s+/).join(" "), source: "override" };
+}
+// ---------------------------------------------------------------------------
+// Rule catalogs
+// ---------------------------------------------------------------------------
+/**
+ * The project `permissions.allow` catalog for one launcher prefix. Every entry is
+ * an exact command or an exact prefix followed by its arguments — never a broad
+ * rule. `serverNames` are the MCP registration keys the tool rules are written
+ * under (see {@link resolveSupervisorServerNames}). Order is stable so output and
+ * the manifest are deterministic.
+ */
+export function buildProjectPermissionRules(launcherPrefix, serverNames = [MCP_SERVER_NAME]) {
+    const rules = [];
+    // The sanctioned verbs, in the launcher's exact form.
+    for (const verb of BRIDGE_SANCTIONED_VERB_SUBCOMMANDS) {
+        rules.push(`Bash(${launcherPrefix} epic-implementer ${verb} *)`);
+    }
+    // drive-epic preview and attach, and the readiness reads.
+    rules.push(`Bash(${launcherPrefix} drive-epic *)`);
+    rules.push(`Bash(${launcherPrefix} epic-implementer readiness *)`);
+    // Read-only supporting commands.
+    rules.push(`Bash(${launcherPrefix} epic-implementer continuation-receipt *)`);
+    rules.push(`Bash(${launcherPrefix} epic-implementer doctor)`);
+    rules.push(`Bash(${launcherPrefix} plane status)`);
+    rules.push("Bash(pmset -g log)");
+    rules.push("Bash(git ls-tree *)");
+    rules.push("Bash(gh auth status)");
+    // Stage 0's local checks, exactly as the posture spells them.
+    rules.push("Bash(source .venv/bin/activate)");
+    rules.push("Bash(ENVIRONMENT=TEST python scripts/conductor_health_check.py --json)");
+    rules.push("Bash(alembic -c alembic.ini heads)");
+    rules.push("Bash(alembic -c alembic.ini current)");
+    // The private tally directory: create, restrict, read, and append.
+    rules.push(`Bash(mkdir -p ${BRIDGE_RUN_STATE_DIR}/*)`);
+    rules.push(`Bash(chmod 700 ${BRIDGE_RUN_STATE_DIR}/*)`);
+    rules.push(`Bash(chmod 600 ${BRIDGE_RUN_STATE_DIR}/*)`);
+    rules.push(`Read(${BRIDGE_RUN_STATE_DIR}/**)`);
+    rules.push(`Edit(${BRIDGE_RUN_STATE_DIR}/**)`);
+    rules.push(`Write(${BRIDGE_RUN_STATE_DIR}/**)`);
+    // BAPI-1399: the value-free prerequisite presence check, exactly as prescribed.
+    // Only a validated variable name fills the `*`; the form prints present or missing.
+    rules.push('Bash([ -n "${*:+x}" ] && echo present || echo missing)');
+    // Claude Code checks each `&&` / `||` segment of a compound command on its
+    // own, so each segment of the prescribed form has its own exact rule. A
+    // segment outside these three (for example one that prints a value) matches
+    // no rule.
+    rules.push('Bash([ -n "${*:+x}" ])');
+    rules.push("Bash(echo present)");
+    rules.push("Bash(echo missing)");
+    // BAPI-1399: reading `.bridge/epic-workarounds/` at the fetched epic head, and
+    // the marker-checked hand-off comment on the run's own integration PR. The
+    // `workarounds.md` write is covered by the run-state Write rule above.
+    rules.push("Bash(git fetch origin 'epic/*')");
+    rules.push("Bash(git rev-parse 'origin/epic/*')");
+    rules.push("Bash(git show '*:.bridge/epic-workarounds/*.md')");
+    rules.push("Bash(gh pr view 'epic/*' --json number,isDraft,state,headRefOid,baseRefName,comments)");
+    rules.push(`Bash(gh pr comment * --body-file ${BRIDGE_RUN_STATE_DIR}/*/workarounds.md)`);
+    // The notes-log commit on docs/<KEY>-conductor-run-notes.
+    rules.push("Bash(git switch -c 'docs/*-conductor-run-notes')");
+    rules.push("Bash(git add docs/epic-implementer/run-notes/)");
+    rules.push("Bash(git commit -m * -- docs/epic-implementer/run-notes/)");
+    // The Bridge MCP tools the supervisor uses, under each installed server key.
+    for (const serverName of serverNames) {
+        for (const tool of BRIDGE_SUPERVISOR_MCP_TOOLS) {
+            rules.push(`mcp__${serverName}__${tool}`);
+        }
+    }
+    return rules;
+}
+/**
+ * The user-settings `autoMode` prose. It describes the run sandbox — the run's
+ * branches and worktrees, the Bridge server, and third-party sandbox accounts the
+ * project explicitly names — so the classifier treats the supervisor's in-scope
+ * work as routine. `sandboxAccounts` adds named accounts when a caller knows them;
+ * none is ever inferred.
+ */
+export function buildUserAutoModeEntries(sandboxAccounts = []) {
+    const named = sandboxAccounts.map((a) => a.trim()).filter((a) => a.length > 0);
+    const accounts = named.length > 0
+        ? `the third-party sandbox accounts the project names (${named.join(", ")})`
+        : "any third-party sandbox account the project explicitly names as a sandbox in its configuration or documentation";
+    return {
+        environment: [
+            "Bridge Epic Implementer runs (/drive-epic-run): a run's sandbox is its own branches " +
+                "(epic/<KEY> and each child ticket's branch_name) and the worktrees made for them, " +
+                `the Bridge server, and ${accounts}.`,
+        ],
+        allow: [
+            "Bridge /drive-epic-run supervisor: the packaged Bridge CLI's sanctioned " +
+                "epic-implementer recovery verbs, drive-epic preview and attach, and readiness, applied " +
+                "to the run's own sandbox; reads, waits, the private tally under " +
+                `${BRIDGE_RUN_STATE_DIR}/, and Bridge bug reports.`,
+        ],
+    };
+}
+/** Absolute path of the project's local (gitignored) Claude settings file. */
+export function projectSettingsPath(cwd) {
+    return path.join(cwd, ...BRIDGE_PROJECT_SETTINGS_RELPATH.split("/"));
+}
+/**
+ * The MCP registration keys the tool rules must be written under, read from the
+ * project's `.mcp.json`. A canonical or legacy registration yields its own key;
+ * a conflict (both keys present) yields both, so whichever one Claude Code loads
+ * is covered. A missing, malformed, or Bridge-less file yields the canonical key,
+ * because that is the key a fresh install writes.
+ */
+export async function resolveSupervisorServerNames(cwd, deps) {
+    let servers;
+    try {
+        const parsed = JSON.parse(await deps.readFile(path.join(cwd, ".mcp.json")));
+        servers =
+            parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+                ? parsed.mcpServers
+                : undefined;
+    }
+    catch {
+        servers = undefined;
+    }
+    const resolution = resolveRegistrationKey(servers);
+    if (resolution.state === "canonical" || resolution.state === "legacy")
+        return [resolution.key];
+    if (resolution.state === "conflict")
+        return [...resolution.keys];
+    return [MCP_SERVER_NAME];
+}
+/** Absolute path of the user's Claude settings file. */
+export function userSettingsPath(homeDir) {
+    return path.join(homeDir, ".claude", "settings.json");
+}
+/** Absolute path of Bridge's permission-ownership manifest. */
+export function bridgePermissionsManifestPath(cwd) {
+    return path.join(cwd, ...BRIDGE_PERMISSIONS_MANIFEST_RELPATH.split("/"));
+}
+/** Read a settings file: missing is `{}`-equivalent, malformed is never used. */
+export async function readSettingsFile(filePath, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(filePath);
+    }
+    catch {
+        return { status: "missing" };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { status: "malformed" };
+        }
+        return { status: "valid", settings: parsed, raw };
+    }
+    catch {
+        return { status: "malformed" };
+    }
+}
+function serializeSettings(settings) {
+    return `${JSON.stringify(settings, null, 2)}\n`;
+}
+function emptyManifest() {
+    return {
+        version: BRIDGE_PERMISSIONS_MANIFEST_VERSION,
+        launcher: null,
+        project: [],
+        userAllow: [],
+        userEnvironment: [],
+    };
+}
+function stringList(value) {
+    if (!Array.isArray(value))
+        return null;
+    return value.every((v) => typeof v === "string") ? value : null;
+}
+/** Read and validate the manifest. An invalid manifest owns nothing. */
+export async function readBridgePermissionsManifest(cwd, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(bridgePermissionsManifestPath(cwd));
+    }
+    catch {
+        return { status: "missing" };
+    }
+    try {
+        const doc = JSON.parse(raw);
+        if (doc === null || typeof doc !== "object" || Array.isArray(doc))
+            return { status: "invalid" };
+        if (doc.version !== BRIDGE_PERMISSIONS_MANIFEST_VERSION)
+            return { status: "invalid" };
+        const project = stringList(doc.project);
+        const userAllow = stringList(doc.userAllow);
+        const userEnvironment = stringList(doc.userEnvironment);
+        const launcher = doc.launcher;
+        if (!project || !userAllow || !userEnvironment)
+            return { status: "invalid" };
+        if (launcher !== null && typeof launcher !== "string")
+            return { status: "invalid" };
+        return {
+            status: "valid",
+            manifest: { version: BRIDGE_PERMISSIONS_MANIFEST_VERSION, launcher, project, userAllow, userEnvironment },
+        };
+    }
+    catch {
+        return { status: "invalid" };
+    }
+}
+/** Serialize the manifest with a stable key order. */
+export function serializeBridgePermissionsManifest(manifest) {
+    return `${JSON.stringify({
+        version: manifest.version,
+        launcher: manifest.launcher,
+        project: manifest.project,
+        userAllow: manifest.userAllow,
+        userEnvironment: manifest.userEnvironment,
+    }, null, 2)}\n`;
+}
+async function writeManifestIfChanged(cwd, next, deps) {
+    const target = bridgePermissionsManifestPath(cwd);
+    const text = serializeBridgePermissionsManifest(next);
+    let current = null;
+    try {
+        current = await deps.readFile(target);
+    }
+    catch {
+        current = null;
+    }
+    if (current === text)
+        return true;
+    try {
+        await deps.mkdir(path.dirname(target), { recursive: true });
+        await deps.writeFile(target, text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeSettings(filePath, settings, deps) {
+    try {
+        await deps.mkdir(path.dirname(filePath), { recursive: true });
+        await deps.writeFile(filePath, serializeSettings(settings));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// List helpers
+// ---------------------------------------------------------------------------
+/** The `permissions.allow` list, `[]` when absent, or null when not a string list. */
+function projectAllowList(settings) {
+    const permissions = settings.permissions;
+    if (permissions === undefined)
+        return [];
+    if (permissions === null || typeof permissions !== "object" || Array.isArray(permissions))
+        return null;
+    const allow = permissions.allow;
+    if (allow === undefined)
+        return [];
+    return stringList(allow);
+}
+function withProjectAllowList(settings, allow) {
+    const permissions = settings.permissions && typeof settings.permissions === "object"
+        ? settings.permissions
+        : {};
+    return { ...settings, permissions: { ...permissions, allow } };
+}
+/** An `autoMode` list, `undefined` when absent, or null when not a string list. */
+function autoModeList(settings, key) {
+    const autoMode = settings.autoMode;
+    if (autoMode === undefined)
+        return undefined;
+    if (autoMode === null || typeof autoMode !== "object" || Array.isArray(autoMode))
+        return null;
+    const list = autoMode[key];
+    if (list === undefined)
+        return undefined;
+    return stringList(list);
+}
+function withAutoModeLists(settings, lists) {
+    const autoMode = settings.autoMode && typeof settings.autoMode === "object"
+        ? settings.autoMode
+        : {};
+    return { ...settings, autoMode: { ...autoMode, ...lists } };
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+/**
+ * Write the project `permissions.allow` catalog for the resolved launcher.
+ *
+ * Only missing strings are appended; every other entry and key is kept. Strings
+ * Bridge recorded earlier that are no longer desired (for example after the
+ * launcher changed) are removed. The manifest gains exactly the strings this run
+ * inserted. Nothing is written when nothing changes.
+ */
+export async function applyProjectPermissions(params, deps) {
+    const launcher = resolvePermissionLauncher(params.env);
+    if (!launcher.ok) {
+        return { launcher, project: { status: "launcher-refused", skipped: [] }, manifestRecorded: false };
+    }
+    const desired = buildProjectPermissionRules(launcher.prefix, await resolveSupervisorServerNames(params.cwd, deps));
+    const settingsPath = projectSettingsPath(params.cwd);
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    const read = await readSettingsFile(settingsPath, deps);
+    const current = read.status === "valid" ? read.settings : {};
+    const allow = read.status === "malformed" ? null : projectAllowList(current);
+    if (allow === null) {
+        return {
+            launcher,
+            project: { status: "malformed", path: settingsPath, skipped: desired },
+            manifestRecorded: false,
+        };
+    }
+    const desiredSet = new Set(desired);
+    const stale = manifest.project.filter((rule) => !desiredSet.has(rule));
+    const staleSet = new Set(stale);
+    const removedStale = allow.filter((rule) => staleSet.has(rule));
+    const kept = allow.filter((rule) => !staleSet.has(rule));
+    const keptSet = new Set(kept);
+    const inserted = desired.filter((rule) => !keptSet.has(rule));
+    const alreadyPresent = desired.filter((rule) => keptSet.has(rule));
+    const nextAllow = [...kept, ...inserted];
+    let status = "unchanged";
+    if (inserted.length > 0 || removedStale.length > 0) {
+        const ok = await writeSettings(settingsPath, withProjectAllowList(current, nextAllow), deps);
+        if (!ok) {
+            return { launcher, project: { status: "io-error", path: settingsPath, skipped: inserted }, manifestRecorded: false };
+        }
+        status = "written";
+    }
+    const ownedStill = manifest.project.filter((rule) => desiredSet.has(rule));
+    const manifestRecorded = await writeManifestIfChanged(params.cwd, { ...manifest, launcher: launcher.prefix, project: unique([...ownedStill, ...inserted]) }, deps);
+    return {
+        launcher,
+        project: { status, path: settingsPath, inserted, alreadyPresent, removedStale },
+        manifestRecorded,
+    };
+}
+/**
+ * Write Bridge's `autoMode.allow` and `autoMode.environment` prose into the
+ * user's settings. Call ONLY after the user consented. A list Bridge creates
+ * starts with `"$defaults"` so Claude Code's built-in entries are kept; an
+ * existing list keeps every entry it had, `"$defaults"` included, except an
+ * entry this project's manifest recorded as Bridge's own that Bridge no longer
+ * wants (its wording changed): that one is replaced, so an upgrade never leaves
+ * stale Bridge prose beside the new text. Entries Bridge did not record are
+ * never touched.
+ */
+export async function applyUserAutoModeEntries(params, deps) {
+    const entries = buildUserAutoModeEntries(params.sandboxAccounts);
+    const settingsPath = userSettingsPath(params.homeDir);
+    const proposed = [...entries.allow, ...entries.environment];
+    const read = await readSettingsFile(settingsPath, deps);
+    if (read.status === "malformed") {
+        return { user: { status: "malformed", path: settingsPath, skipped: proposed }, manifestRecorded: false };
+    }
+    const current = read.status === "valid" ? read.settings : {};
+    const allowList = autoModeList(current, "allow");
+    const environmentList = autoModeList(current, "environment");
+    if (allowList === null || environmentList === null) {
+        return { user: { status: "malformed", path: settingsPath, skipped: proposed }, manifestRecorded: false };
+    }
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    const merge = (existing, wanted, recorded) => {
+        const wantedSet = new Set(wanted);
+        const staleSet = new Set(recorded.filter((entry) => !wantedSet.has(entry)));
+        const prior = existing ?? [AUTO_MODE_DEFAULTS_SENTINEL];
+        const removed = prior.filter((entry) => staleSet.has(entry));
+        const base = prior.filter((entry) => !staleSet.has(entry));
+        const have = new Set(base);
+        const added = wanted.filter((entry) => !have.has(entry));
+        const present = wanted.filter((entry) => have.has(entry));
+        const owned = recorded.filter((entry) => wantedSet.has(entry));
+        return { next: [...base, ...added], added, present, removed, owned, created: existing === undefined };
+    };
+    const allowMerge = merge(allowList, entries.allow, manifest.userAllow);
+    const environmentMerge = merge(environmentList, entries.environment, manifest.userEnvironment);
+    const inserted = [...allowMerge.added, ...environmentMerge.added];
+    const alreadyPresent = [...allowMerge.present, ...environmentMerge.present];
+    const removedStale = [...allowMerge.removed, ...environmentMerge.removed];
+    let status = "unchanged";
+    if (inserted.length > 0 || removedStale.length > 0) {
+        const next = withAutoModeLists(current, { allow: allowMerge.next, environment: environmentMerge.next });
+        const ok = await writeSettings(settingsPath, next, deps);
+        if (!ok) {
+            return { user: { status: "io-error", path: settingsPath, skipped: inserted }, manifestRecorded: false };
+        }
+        status = "written";
+    }
+    const manifestRecorded = await writeManifestIfChanged(params.cwd, {
+        ...manifest,
+        userAllow: unique([...allowMerge.owned, ...allowMerge.added]),
+        userEnvironment: unique([...environmentMerge.owned, ...environmentMerge.added]),
+    }, deps);
+    return {
+        user: { status, path: settingsPath, inserted, alreadyPresent, removedStale },
+        manifestRecorded,
+    };
+}
+/**
+ * Inspect both scopes without writing anything. Project rules are `present`
+ * when every desired rule is in the allow list, `missing` when any is absent,
+ * and `drifted` when the manifest's launcher differs from the one resolved now
+ * or a Bridge-owned rule is no longer desired. User entries are `present` when
+ * every proposed entry is in its list and `missing` otherwise.
+ */
+export async function inspectBridgePermissions(params, deps) {
+    const launcher = resolvePermissionLauncher(params.env);
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    let project;
+    const projectPath = projectSettingsPath(params.cwd);
+    if (!launcher.ok) {
+        project = { state: "launcher-refused" };
+    }
+    else {
+        const read = await readSettingsFile(projectPath, deps);
+        const allow = read.status === "malformed" ? null : projectAllowList(read.status === "valid" ? read.settings : {});
+        if (allow === null) {
+            project = { state: "malformed", path: projectPath };
+        }
+        else {
+            const desired = buildProjectPermissionRules(launcher.prefix, await resolveSupervisorServerNames(params.cwd, deps));
+            const have = new Set(allow);
+            const missing = desired.filter((rule) => !have.has(rule));
+            const desiredSet = new Set(desired);
+            const stale = manifest.project.filter((rule) => !desiredSet.has(rule) && have.has(rule));
+            const launcherChanged = manifest.launcher !== null && manifest.launcher !== launcher.prefix;
+            if (launcherChanged || stale.length > 0) {
+                project = {
+                    state: "drifted",
+                    path: projectPath,
+                    missing,
+                    stale,
+                    reason: launcherChanged
+                        ? "the launcher prefix changed since the rules were written"
+                        : "Bridge-written rules no longer match the current catalog or MCP server key",
+                };
+            }
+            else if (missing.length > 0) {
+                project = { state: "missing", path: projectPath, missing };
+            }
+            else {
+                project = { state: "present", path: projectPath, count: desired.length };
+            }
+        }
+    }
+    const userPath = userSettingsPath(params.homeDir);
+    const userRead = await readSettingsFile(userPath, deps);
+    let user;
+    if (userRead.status === "malformed") {
+        user = { state: "malformed", path: userPath };
+    }
+    else {
+        const settings = userRead.status === "valid" ? userRead.settings : {};
+        const allowList = autoModeList(settings, "allow");
+        const environmentList = autoModeList(settings, "environment");
+        if (allowList === null || environmentList === null) {
+            user = { state: "malformed", path: userPath };
+        }
+        else {
+            const entries = buildUserAutoModeEntries();
+            const haveAllow = new Set(allowList ?? []);
+            const haveEnvironment = new Set(environmentList ?? []);
+            const missing = [
+                ...entries.allow.filter((e) => !haveAllow.has(e)),
+                ...entries.environment.filter((e) => !haveEnvironment.has(e)),
+            ];
+            user =
+                missing.length === 0
+                    ? { state: "present", path: userPath, count: entries.allow.length + entries.environment.length }
+                    : { state: "missing", path: userPath, missing };
+        }
+    }
+    return { launcher, recordedLauncher: manifest.launcher, project, user };
+}
+/**
+ * Remove ONLY the strings Bridge recorded in its manifest, from both settings
+ * files. Every other entry and key stays, including a user's own identical
+ * string that predates Bridge (it was never recorded). A malformed file is never
+ * written; its recorded strings stay recorded and are reported as unremovable.
+ */
+export async function removeBridgePermissions(params, deps) {
+    const manifestRead = await readBridgePermissionsManifest(params.cwd, deps);
+    const manifest = manifestRead.status === "valid" ? manifestRead.manifest : emptyManifest();
+    const next = { ...manifest };
+    // Project scope.
+    const projectPath = projectSettingsPath(params.cwd);
+    let project;
+    if (manifest.project.length === 0) {
+        project = { status: "nothing-recorded", path: projectPath, removed: [] };
+    }
+    else {
+        const read = await readSettingsFile(projectPath, deps);
+        const allow = read.status === "malformed" ? null : projectAllowList(read.status === "valid" ? read.settings : {});
+        if (allow === null) {
+            project = { status: "malformed", path: projectPath, unremovable: manifest.project };
+        }
+        else {
+            const owned = new Set(manifest.project);
+            const removed = allow.filter((rule) => owned.has(rule));
+            let ok = true;
+            if (removed.length > 0 && read.status === "valid") {
+                ok = await writeSettings(projectPath, withProjectAllowList(read.settings, allow.filter((rule) => !owned.has(rule))), deps);
+            }
+            if (ok) {
+                project = { status: "removed", path: projectPath, removed };
+                next.project = [];
+                next.launcher = null;
+            }
+            else {
+                project = { status: "io-error", path: projectPath, unremovable: removed };
+            }
+        }
+    }
+    // User scope.
+    const userPath = userSettingsPath(params.homeDir);
+    let user;
+    const ownedUser = [...manifest.userAllow, ...manifest.userEnvironment];
+    if (ownedUser.length === 0) {
+        user = { status: "nothing-recorded", path: userPath, removed: [] };
+    }
+    else {
+        const read = await readSettingsFile(userPath, deps);
+        const settings = read.status === "valid" ? read.settings : {};
+        const allowList = read.status === "malformed" ? null : autoModeList(settings, "allow");
+        const environmentList = read.status === "malformed" ? null : autoModeList(settings, "environment");
+        if (allowList === null || environmentList === null) {
+            user = { status: "malformed", path: userPath, unremovable: ownedUser };
+        }
+        else {
+            const ownedAllow = new Set(manifest.userAllow);
+            const ownedEnvironment = new Set(manifest.userEnvironment);
+            const removedAllow = (allowList ?? []).filter((e) => ownedAllow.has(e));
+            const removedEnvironment = (environmentList ?? []).filter((e) => ownedEnvironment.has(e));
+            const removed = [...removedAllow, ...removedEnvironment];
+            let ok = true;
+            if (removed.length > 0 && read.status === "valid") {
+                const lists = {};
+                if (allowList !== undefined)
+                    lists.allow = allowList.filter((e) => !ownedAllow.has(e));
+                if (environmentList !== undefined)
+                    lists.environment = environmentList.filter((e) => !ownedEnvironment.has(e));
+                ok = await writeSettings(userPath, withAutoModeLists(read.settings, lists), deps);
+            }
+            if (ok) {
+                user = { status: "removed", path: userPath, removed };
+                next.userAllow = [];
+                next.userEnvironment = [];
+            }
+            else {
+                user = { status: "io-error", path: userPath, unremovable: removed };
+            }
+        }
+    }
+    const changed = next.project.length !== manifest.project.length ||
+        next.userAllow.length !== manifest.userAllow.length ||
+        next.userEnvironment.length !== manifest.userEnvironment.length;
+    const manifestUpdated = manifestRead.status === "valid" && changed ? await writeManifestIfChanged(params.cwd, next, deps) : true;
+    return { project, user, manifestUpdated };
+}
+/** The one consent question for the user-settings write. */
+export const USER_AUTO_MODE_CONSENT_PROMPT = "Add Bridge's auto-mode sandbox description to ~/.claude/settings.json, so /drive-epic-run's " +
+    "in-scope work is not stopped by the auto-mode classifier? (y/N) ";
+function logList(log, items) {
+    for (const item of items)
+        log(`    ${item}`);
+}
+/**
+ * The installer's permission step. Writes the project rules, then asks ONCE for
+ * consent before touching the user's settings. A declined or non-interactive
+ * install leaves the user file untouched and prints what it would have added.
+ * Every rule written is listed, with the launcher prefix it covers. A malformed
+ * file is reported on stderr and skipped; the rest of the install continues.
+ */
+export async function runBridgePermissionsInstallStep(deps) {
+    const { log, errorLog } = deps;
+    log("");
+    log("Bridge permission rules for /drive-epic-run (auto mode):");
+    if (deps.ensureGitignored) {
+        for (const relPath of [BRIDGE_PERMISSIONS_MANIFEST_RELPATH, BRIDGE_PROJECT_SETTINGS_RELPATH]) {
+            try {
+                await deps.ensureGitignored(relPath);
+            }
+            catch {
+                errorLog(`  warning: could not add ${relPath} to .gitignore (non-fatal).`);
+            }
+        }
+    }
+    const project = await applyProjectPermissions({ cwd: deps.cwd, env: deps.env }, deps);
+    if (!project.launcher.ok) {
+        errorLog(`  warning: project permission rules were not written: ${project.launcher.reason}.`);
+        errorLog(`  Unset ${BRIDGE_LAUNCHER_ENV}, or set it to a plain command prefix, then re-run install.`);
+    }
+    else {
+        log(`  Launcher prefix covered: ${project.launcher.prefix}`);
+        const scope = project.project;
+        if (scope.status === "written" || scope.status === "unchanged") {
+            log(`  ${scope.path}:`);
+            if (scope.inserted.length > 0) {
+                log(`  Wrote ${scope.inserted.length} permissions.allow rule(s):`);
+                logList(log, scope.inserted);
+            }
+            if (scope.alreadyPresent.length > 0) {
+                log(`  Already present (${scope.alreadyPresent.length}):`);
+                logList(log, scope.alreadyPresent);
+            }
+            if (scope.removedStale.length > 0) {
+                log(`  Removed ${scope.removedStale.length} rule(s) Bridge wrote for an earlier launcher:`);
+                logList(log, scope.removedStale);
+            }
+        }
+        else if (scope.status === "malformed" || scope.status === "io-error") {
+            errorLog(`  warning: ${scope.path} ${scope.status === "malformed" ? "is not valid JSON settings and was left unchanged" : "could not be written"}; ` +
+                `these ${scope.skipped.length} rule(s) were NOT written:`);
+            logList(errorLog, scope.skipped);
+        }
+        if (!project.manifestRecorded && (scope.status === "written" || scope.status === "unchanged")) {
+            errorLog(`  warning: could not update ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}; doctor and removal may not see these rules.`);
+        }
+    }
+    // User settings: one question, and nothing written without a yes.
+    const entries = buildUserAutoModeEntries();
+    const proposed = [...entries.allow, ...entries.environment];
+    const userPath = userSettingsPath(deps.homeDir);
+    if (!deps.promptLine) {
+        log(`  ${userPath} was not changed (non-interactive install). It would add, to autoMode.allow and autoMode.environment:`);
+        logList(log, proposed);
+        log("  Re-run install in a terminal to add them.");
+        return { project, userConsent: "non-interactive", user: null };
+    }
+    const answer = (await deps.promptLine(USER_AUTO_MODE_CONSENT_PROMPT)).trim().toLowerCase();
+    if (answer !== "y" && answer !== "yes") {
+        log(`  ${userPath} was not changed. These entries were not added:`);
+        logList(log, proposed);
+        return { project, userConsent: "declined", user: null };
+    }
+    const user = await applyUserAutoModeEntries({ cwd: deps.cwd, homeDir: deps.homeDir }, deps);
+    const scope = user.user;
+    if (scope.status === "written" || scope.status === "unchanged") {
+        log(`  ${scope.path}:`);
+        if (scope.inserted.length > 0) {
+            log(`  Wrote ${scope.inserted.length} autoMode entr${scope.inserted.length === 1 ? "y" : "ies"} ("$defaults" kept):`);
+            logList(log, scope.inserted);
+        }
+        if (scope.alreadyPresent.length > 0) {
+            log(`  Already present (${scope.alreadyPresent.length}):`);
+            logList(log, scope.alreadyPresent);
+        }
+    }
+    else if (scope.status === "malformed" || scope.status === "io-error") {
+        errorLog(`  warning: ${scope.path} ${scope.status === "malformed" ? "is not valid JSON settings and was left unchanged" : "could not be written"}; ` +
+            "these autoMode entries were NOT written:");
+        logList(errorLog, scope.skipped);
+    }
+    return { project, userConsent: "granted", user };
+}
+/**
+ * The removal flag's step. Removes only Bridge-recorded strings and reports what
+ * it removed and what it could not. Returns a process exit code: 0 when every
+ * recorded string is gone, 1 when a malformed or unwritable file kept some.
+ */
+export async function runBridgePermissionsRemoval(deps) {
+    const { log, errorLog } = deps;
+    const result = await removeBridgePermissions({ cwd: deps.cwd, homeDir: deps.homeDir }, deps);
+    let failed = false;
+    for (const [label, scope] of [
+        ["project permissions.allow", result.project],
+        ["user autoMode", result.user],
+    ]) {
+        if (scope.status === "nothing-recorded") {
+            log(`${label}: nothing Bridge wrote is recorded (${scope.path}).`);
+        }
+        else if (scope.status === "removed") {
+            log(`${label}: removed ${scope.removed.length} Bridge entr${scope.removed.length === 1 ? "y" : "ies"} from ${scope.path}.`);
+            logList(log, scope.removed);
+        }
+        else if (scope.status === "malformed" || scope.status === "io-error") {
+            failed = true;
+            errorLog(`${label}: ${scope.path} ${scope.status === "malformed" ? "is not valid JSON settings" : "could not be written"}; ` +
+                "these Bridge entries could not be removed:");
+            logList(errorLog, scope.unremovable);
+        }
+    }
+    if (!result.manifestUpdated) {
+        failed = true;
+        errorLog(`warning: could not update ${BRIDGE_PERMISSIONS_MANIFEST_RELPATH}.`);
+    }
+    log("Entries you added yourself were left in place.");
+    return failed ? 1 : 0;
+}