@bridge_gpt/mcp-server 0.2.16 → 0.2.19

package/build/conductor/errors.js

@@ -10,6 +10,43 @@
  * generic message.
  */
 import { redactSecretString } from "./redaction.js";
+/**
+ * Redact a diagnostic string destined for BACKEND LOGS ONLY (never the client
+ * envelope): strip secret-shaped material (tokens, keys, bearer creds) via
+ * {@link redactSecretString}, then additionally mask user home-dir path segments
+ * (`/Users/<name>/…`, `/home/<name>/…`) which leak usernames and credential-bearing
+ * locations. The rest of a stack trace is preserved so operators can still diagnose.
+ */
+function redactDiagnostic(value) {
+    return redactSecretString(value).replace(/(\/(?:Users|home)\/)[^/\s:]+/g, "$1[REDACTED_USER]");
+}
+/**
+ * FINDING 5 (BAPI-463): surface an unexpected (INTERNAL_ERROR) error with its
+ * class + message (redacted so no secret or credential-bearing path leaks) so
+ * operators can root-cause the underlying fault that the sanitized client
+ * envelope intentionally hides (e.g. the recurring `check_messages` failure).
+ *
+ * Emitted as a SINGLE LINE with NO stack frames: the conductor's `console.error`
+ * IS the CLI's stderr surface, which a committed security invariant requires to
+ * stay stack-trace-free (`security-regressions.test.ts`). The error class +
+ * message is the diagnostic essence the acceptance criterion calls for; a raw
+ * stack would both violate that invariant and risk leaking internal file paths.
+ * Best-effort: a logging failure must never mask the original error, and NOTHING
+ * here is returned to the MCP/CLI caller.
+ */
+function logInternalErrorDiagnostic(error) {
+    try {
+        const name = error instanceof Error ? error.name : typeof error;
+        const rawMessage = error instanceof Error ? error.message : String(error);
+        // Collapse any newlines so the single-line diagnostic can never resemble a
+        // multi-line stack trace to the CLI-surface guard.
+        const message = redactDiagnostic(rawMessage).replace(/\s*\n\s*/g, " ");
+        console.error(`[conductor:INTERNAL_ERROR] [${name}] ${message}`);
+    }
+    catch {
+        /* diagnostic logging must never throw */
+    }
+}
 /** Raised when caller input violates a conductor validation rule. */
 export class ConductorValidationError extends Error {
     constructor(message) {
@@ -24,6 +61,76 @@ export class ConductorStoreError extends Error {
         this.name = "ConductorStoreError";
     }
 }
+/**
+ * Raised when the frozen v1 `conductor epic-tick` entrypoint is invoked
+ * (BAPI-534, Epic Conductor v2 slice 0). The v1 local reconciler/ledger tick is
+ * frozen: Epic Conductor v2 replaces it with a server-side reconciler plus the
+ * local executor (`mcp-server executor`). The message points operators at the v2
+ * path and is path-free / secret-free.
+ */
+export class ConductorEpicTickV1FrozenError extends Error {
+    constructor() {
+        super("The v1 `conductor epic-tick` path is frozen (EPIC_TICK_V1_FROZEN). Epic " +
+            "Conductor v2 replaces the local epic tick with a server-side reconciler " +
+            "plus the local executor — run `mcp-server executor` instead.");
+        this.name = "ConductorEpicTickV1FrozenError";
+    }
+}
+/**
+ * Raised (BAPI-527) when the worker-side ledger subprocess boundary cannot run.
+ *
+ * Worker-facing ledger operations (`check_messages`, `wait_for_done_gate` event
+ * emission) MUST execute through `conductor-bin.js` under the captured conductor
+ * Node (`CONDUCTOR_NODE_PATH`) so the worker Node never loads the `better-sqlite3`
+ * native binary. When that runtime is missing or invalid, this error makes the
+ * failure LOUD and structured rather than silently falling back to the worker
+ * Node. The carried `reason`/`envVar` are the ONLY diagnostic surface — both are
+ * fixed, non-secret, path-free tokens. No caught error, path, argv, stdout,
+ * stderr, or credential value is ever attached.
+ */
+export class ConductorLedgerSubprocessRuntimeError extends Error {
+    reason;
+    envVar;
+    constructor(reason, envVar) {
+        // Single-line, path-free, secret-free (the committed CLI-stderr invariant in
+        // security-regressions.test.ts requires it). Names only the reason token.
+        super(`Conductor worker ledger subprocess is unavailable (reason: ${reason}).`);
+        this.name = "ConductorLedgerSubprocessRuntimeError";
+        this.reason = reason;
+        this.envVar = envVar;
+    }
+}
+/**
+ * Structural guard for a native-module-load failure raised by the conductor
+ * store (BAPI-526). Detected structurally (by `name` + a valid `details` object)
+ * rather than by importing `ConductorNativeModuleLoadError` from `store.ts`, so
+ * `errors.ts` avoids a runtime import cycle with the store.
+ */
+export function isConductorNativeModuleLoadError(error) {
+    if (!(error instanceof Error))
+        return false;
+    if (error.name !== "ConductorNativeModuleLoadError")
+        return false;
+    const details = error.details;
+    if (!details || typeof details !== "object" || Array.isArray(details))
+        return false;
+    const d = details;
+    return (typeof d.node_version === "string" &&
+        typeof d.node_modules_abi === "string" &&
+        typeof d.module === "string");
+}
+/**
+ * Copy ONLY the three allowlisted native-load detail fields. Never spreads
+ * arbitrary properties from the error, so a secret/path smuggled onto the error
+ * object cannot round-trip into the client envelope.
+ */
+function nativeModuleDetailsEnvelope(details) {
+    return {
+        node_version: details.node_version,
+        node_modules_abi: details.node_modules_abi,
+        module: details.module,
+    };
+}
 /**
  * Heuristically detect SQLite busy/locked failures so they can be surfaced as a
  * retryable 503 rather than an opaque 500. Matches the `better-sqlite3` error
@@ -64,11 +171,37 @@ function isSqliteBusyError(error) {
  *     the raw error text, stack, and any secret material are discarded.
  */
 export function toConductorErrorEnvelope(error) {
+    // v1 epic-tick freeze (BAPI-534): the frozen entrypoint maps to a stable,
+    // named 400 pointing operators at Epic Conductor v2 (server-side reconciler +
+    // local executor). Checked first — it is a fail-loud guard, not a runtime fault.
+    if (error instanceof ConductorEpicTickV1FrozenError) {
+        return {
+            error: "EPIC_TICK_V1_FROZEN",
+            status: 400,
+            message: error.message,
+        };
+    }
+    // Native-module LOAD failure (BAPI-526): `better-sqlite3` is present but fails
+    // to load for this Node runtime (ABI/dlopen mismatch). Checked BEFORE the
+    // generic persistence-unavailable branch below (the native-load error subclasses
+    // it) so an ABI/dlopen failure surfaces as a distinct, machine-readable kind
+    // carrying node_version/ABI — never masked as INTERNAL_ERROR or the
+    // undifferentiated PERSISTENCE_UNAVAILABLE. `details` is a fixed three-field
+    // allowlist copied explicitly, never spread from the error object.
+    if (isConductorNativeModuleLoadError(error)) {
+        return {
+            error: "LEDGER_NATIVE_MODULE_LOAD_FAILED",
+            status: 500,
+            message: "Conductor ledger native module failed to load for this Node runtime.",
+            details: nativeModuleDetailsEnvelope(error.details),
+        };
+    }
     // Optional-native-binding degradation (BAPI-451): the conductor `store.ts`
     // throws ConductorPersistenceUnavailableError when `better-sqlite3` could not be
-    // loaded. Detected by name (not instanceof) to avoid an import cycle with
-    // store.ts. Surfaced as a retryable-shaped 503 with a fixed, secret-free message
-    // so the caller learns persistence is unavailable instead of getting an opaque 500.
+    // loaded (or is not installed). Detected by name (not instanceof) to avoid an
+    // import cycle with store.ts. Surfaced as a retryable-shaped 503 with a fixed,
+    // secret-free message so the caller learns persistence is unavailable instead of
+    // getting an opaque 500.
     if (error instanceof Error && error.name === "ConductorPersistenceUnavailableError") {
         return {
             error: "PERSISTENCE_UNAVAILABLE",
@@ -76,6 +209,22 @@ export function toConductorErrorEnvelope(error) {
             message: "Conductor persistence is unavailable (the optional better-sqlite3 native module is not loaded). Conductor coordination features are disabled; core tools are unaffected.",
         };
     }
+    // Worker-ledger subprocess runtime failure (BAPI-527): CONDUCTOR_NODE_PATH /
+    // BAPI_CONDUCTOR_CLI_FILE is missing or invalid so the worker cannot reach the
+    // local ledger through the captured conductor Node. Surfaced as a retryable-
+    // shaped 503 with a fixed, secret-free message plus a small non-secret details
+    // bag (env_var + stable reason). NOTHING path/secret-bearing is echoed. This is
+    // distinct from LEDGER_NATIVE_MODULE_LOAD_FAILED / PERSISTENCE_UNAVAILABLE,
+    // which cover conductor-owned processes that still load better-sqlite3 directly.
+    if (error instanceof ConductorLedgerSubprocessRuntimeError) {
+        return {
+            error: "LEDGER_SUBPROCESS_RUNTIME_UNAVAILABLE",
+            status: 503,
+            message: "Conductor worker ledger subprocess is unavailable; the worker Node cannot reach the local ledger. " +
+                "The dispatched conductor Node runtime is missing or invalid — conductor worker coordination is degraded; core tools are unaffected.",
+            details: { env_var: error.envVar, reason: error.reason },
+        };
+    }
     if (error instanceof ConductorValidationError) {
         // Validation messages are conductor-authored and name the offending field,
         // never its value — but redact defensively so an adversarial/secret-bearing
@@ -89,6 +238,10 @@ export function toConductorErrorEnvelope(error) {
             message: "Conductor ledger is busy; retry shortly.",
         };
     }
+    // Unexpected error: log the redacted class + message + stack to backend logs so
+    // the real cause is diagnosable, then return the fixed generic client envelope
+    // (no trace context, no secret material) to the MCP/CLI caller.
+    logInternalErrorDiagnostic(error);
     return {
         error: "INTERNAL_ERROR",
         status: 500,

package/build/conductor/event-accessors.js

@@ -0,0 +1,252 @@
+/**
+ * Canonical conductor event payload model + typed, fail-closed read accessors
+ * (BAPI-493).
+ *
+ * The stored ledger envelope is deliberately loose (`ConductorEventData.details?:
+ * unknown`), so every consumer historically re-parsed `data.details` by hand and
+ * producers/consumers silently drifted on field location and nesting. This module
+ * makes the read side type-enforced:
+ *
+ *   - {@link EventDetailsByType} maps EVERY {@link SemanticEventType} to an explicit
+ *     details payload shape (details-less families get a conservative empty payload),
+ *     with `never`-based exhaustiveness guards that fail the TypeScript build if a
+ *     new semantic type is added without a payload member.
+ *   - {@link getEventDetails} is discriminant-constrained (E-27): it validates
+ *     `event.type === expectedType` at RUNTIME before narrowing and returns `null`
+ *     on mismatch, so a caller can never obtain a payload for the wrong type.
+ *   - {@link getHeadSha} / {@link getMergeIdentity} are the behavior-critical
+ *     accessors that fail closed (a head/identity that cannot be proven is never
+ *     treated as valid), matching the pre-refactor `extractEventHeadSha` /
+ *     `extractMergeActionIdentityFromGateEvent` behavior byte-for-byte.
+ *
+ * This is READ-SIDE typing only: the stored `data_json` envelope shape is unchanged
+ * and there is NO ledger migration. The module depends only on lower-level,
+ * dependency-light modules (`taxonomy`, `types`, `git-ci-types`, `merge-identity`)
+ * so it can be imported by both `epic-state.ts` and `merge-ledger.ts` without a
+ * cycle. It is NEVER applied to backend HTTP response envelopes (which use a
+ * `detail` wrapper, not `data.details`) — those keep their own normalizers.
+ */
+import { normalizePrNumber, normalizeRepoName, normalizeSha, } from "./git-ci-types.js";
+import { buildGateIdentity, makeMergeActionKey, } from "./merge-identity.js";
+// Re-export the merge identity primitives so downstream consumers can import the
+// whole merge-identity surface from a single typed-accessor entry point.
+export { buildGateIdentity, makeMergeActionKey };
+// ---------------------------------------------------------------------------
+// Small structural helpers
+// ---------------------------------------------------------------------------
+/** Narrow an unknown value to a plain, indexable object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Runtime exhaustiveness guard for switch/dispatch fall-through. */
+export function assertNever(value) {
+    throw new Error(`Unexpected value: ${String(value)}`);
+}
+/**
+ * Normalize a PR head SHA read from a conductor ledger event's
+ * `data.details.head_sha`. Preserves the exact behavior of the pre-refactor
+ * `epic-state.extractEventHeadSha`: accept only a trimmed 7–40 character
+ * hexadecimal string and return it lowercased; every other shape yields `null`.
+ * Deliberately looser than {@link normalizeSha} (which requires a full 40/64-char
+ * object id) because head observations may carry an abbreviated SHA.
+ */
+export function normalizeEventHeadSha(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    if (!/^[0-9a-f]{7,40}$/i.test(trimmed))
+        return null;
+    return trimmed.toLowerCase();
+}
+/** Read ONLY `event.data.details` as a plain object, or `null`. */
+function getRawEventDetails(event) {
+    const details = event.data?.details;
+    return isPlainObject(details) ? details : null;
+}
+// ---------------------------------------------------------------------------
+// Per-type parsers
+// ---------------------------------------------------------------------------
+/** The conservative empty payload shared by all details-less families. */
+const EMPTY_DETAILS = Object.freeze({});
+/** Parse a head-observation payload: read only `details.head_sha`, fail closed. */
+function parseHeadObservation(event) {
+    const details = getRawEventDetails(event);
+    return { head_sha: details ? normalizeEventHeadSha(details.head_sha) : null };
+}
+/** Parse a `merge.*` lifecycle payload: `action_key` string or null. */
+function parseMergeLifecycle(event) {
+    const details = getRawEventDetails(event);
+    const actionKey = details && typeof details.action_key === "string" && details.action_key.trim().length > 0
+        ? details.action_key.trim()
+        : null;
+    return { action_key: actionKey };
+}
+/**
+ * Parse the canonical `gate.met` payload. `head_sha`/`repo`/`pr_number` use the
+ * STRICT normalizers (a merge binding requires a full SHA); `required_checks`
+ * preserves the top-level → nested `ci_check_status.required_checks` dual path.
+ */
+function parseGateMet(event) {
+    const details = getRawEventDetails(event);
+    if (!details) {
+        return {
+            head_sha: null,
+            repo: null,
+            pr_number: null,
+            gate_name: null,
+            config_hash: null,
+            required_checks: [],
+        };
+    }
+    const gateName = typeof details.gate_name === "string" && details.gate_name.trim().length > 0
+        ? details.gate_name.trim()
+        : null;
+    const configHash = typeof details.config_hash === "string" && details.config_hash.trim().length > 0
+        ? details.config_hash.trim()
+        : null;
+    const ciCheckStatus = isPlainObject(details.ci_check_status) ? details.ci_check_status : null;
+    const rawRequiredChecks = Array.isArray(details.required_checks)
+        ? details.required_checks
+        : ciCheckStatus && Array.isArray(ciCheckStatus.required_checks)
+            ? ciCheckStatus.required_checks
+            : [];
+    const requiredChecks = rawRequiredChecks.filter((c) => typeof c === "string" && c.trim().length > 0);
+    return {
+        head_sha: normalizeSha(details.head_sha),
+        repo: normalizeRepoName(details.repo),
+        pr_number: normalizePrNumber(details.pr_number),
+        gate_name: gateName,
+        config_hash: configHash,
+        required_checks: requiredChecks,
+    };
+}
+/** Parse a spec-review verdict payload (conservative head read). */
+function parseSpecReview(event) {
+    const details = getRawEventDetails(event);
+    return { head_sha: details ? normalizeEventHeadSha(details.head_sha) : null };
+}
+/** Return the shared conservative empty payload for details-less families. */
+function parseEmpty() {
+    return EMPTY_DETAILS;
+}
+/**
+ * Exhaustive parser table keyed by every {@link SemanticEventType}. There is no
+ * catch-all default branch that returns raw `data.details` for an unrecognized
+ * type — a missing key breaks the `satisfies` check and fails the build.
+ */
+const EVENT_PARSERS = {
+    "run.started": parseEmpty,
+    "run.heartbeat": parseEmpty,
+    "run.stopped": parseEmpty,
+    "agent.notification": parseEmpty,
+    "tool.intent": parseEmpty,
+    "worktree.changed": parseEmpty,
+    "git.commit_created": parseEmpty,
+    "git.pr_opened": parseHeadObservation,
+    "ci.passed": parseHeadObservation,
+    "ci.failed": parseHeadObservation,
+    "gate.met": parseGateMet,
+    "supervisor.assessment": parseEmpty,
+    "message.sent": parseEmpty,
+    "message.delivered": parseEmpty,
+    "message.acked": parseEmpty,
+    "merge.dry_run": parseMergeLifecycle,
+    "merge.attempted": parseMergeLifecycle,
+    "merge.succeeded": parseHeadObservation,
+    "merge.failed": parseMergeLifecycle,
+    "merge.conflict": parseHeadObservation,
+    "merge.pending_approval": parseMergeLifecycle,
+    "review.passed": parseHeadObservation,
+    "review.changes_requested": parseHeadObservation,
+    "spec_review.passed": parseSpecReview,
+    "spec_review.changes_requested": parseSpecReview,
+    "parse.triggered": parseEmpty,
+    // BAPI-527: parse-after-merge terminal markers (details-less typed payload).
+    "parse.succeeded": parseEmpty,
+    "parse.failed": parseEmpty,
+};
+// ---------------------------------------------------------------------------
+// Public accessors
+// ---------------------------------------------------------------------------
+/**
+ * Typed, discriminant-constrained details accessor (E-27). Returns the parsed
+ * payload for `expectedType` ONLY when `event.type === expectedType` at runtime;
+ * returns `null` on any discriminant mismatch so a caller can never obtain a
+ * `PayloadFor<T>` by passing the wrong expected type. Details-less families return
+ * a conservative empty payload (never the raw `unknown` details).
+ */
+export function getEventDetails(event, expectedType) {
+    if (event.type !== expectedType)
+        return null;
+    const parser = EVENT_PARSERS[expectedType];
+    return parser(event);
+}
+/**
+ * Read and normalize a PR head SHA from the CANONICAL `event.data.details.head_sha`
+ * path only. No fallback locations are consulted — a valid-looking head at
+ * `data.head_sha` or a nested snapshot is deliberately ignored. Returns a lowercased
+ * 7–40 char hex SHA, or `null` for missing/non-object details, non-string,
+ * malformed, or out-of-range values. Fail-closed: a head that cannot be proven is
+ * never treated as valid.
+ */
+export function getHeadSha(event) {
+    const details = getRawEventDetails(event);
+    if (!details)
+        return null;
+    return normalizeEventHeadSha(details.head_sha);
+}
+/**
+ * Read and normalize a PR number from the CANONICAL `event.data.details.pr_number`
+ * path only (BAPI-525). Returns a positive integer PR number or `null` for
+ * missing/non-object details or a malformed value. Fail-closed. Used by the
+ * dispatched-backstop's local-first PR binding resolver to bind a ticket's PR from
+ * ledger events (e.g. `gate.met`) that carry both `pr_number` and `head_sha`,
+ * before falling back to a `gh` lookup.
+ */
+export function getPrNumber(event) {
+    const details = getRawEventDetails(event);
+    if (!details)
+        return null;
+    return normalizePrNumber(details.pr_number);
+}
+/**
+ * Resolve the immutable {@link MergeActionIdentity} from a PR-bound `gate.met`
+ * event. The true merge identity is `(repo, pr_number, head_sha, gate_name)`;
+ * `worker_id` is attribution metadata only and is NOT required for identity
+ * extraction (BAPI-525 Change A). Returns `null` unless the event is a `gate.met`
+ * carrying a complete PR binding (repo, pr_number, head_sha, gate_name) — an
+ * incomplete PR binding remains fail-closed regardless of `worker_id`. A
+ * worker_id-less `gate.met` produced by the autonomous git-hook chain therefore
+ * yields the SAME non-null identity (and byte-identical `action_key`) as its
+ * worker-stamped twin. Preserves the historical `required_checks` dual path
+ * (top-level then nested `ci_check_status`) and never throws. Branch-name fields,
+ * if present, are ignored.
+ */
+export function getMergeIdentity(event) {
+    if (event.type !== "gate.met")
+        return null;
+    const details = getEventDetails(event, "gate.met");
+    if (details === null)
+        return null;
+    const { repo, pr_number: prNumber, head_sha: headSha, gate_name: gateName } = details;
+    if (repo === null || prNumber === null || headSha === null || gateName === null) {
+        return null;
+    }
+    const gateIdentity = buildGateIdentity(gateName, details.config_hash);
+    const actionKey = makeMergeActionKey(repo, prNumber, headSha, gateIdentity);
+    return {
+        repo,
+        pr_number: prNumber,
+        head_sha: headSha,
+        gate_name: gateName,
+        config_hash: details.config_hash,
+        required_checks: details.required_checks,
+        gate_identity: gateIdentity,
+        action_key: actionKey,
+        gate_event: {
+            id: typeof event.id === "string" ? event.id : undefined,
+            seq: typeof event.seq === "number" ? event.seq : undefined,
+            time: typeof event.time === "string" ? event.time : undefined,
+        },
+    };
+}

package/build/conductor/file-scope-guard.js

@@ -0,0 +1,201 @@
+/**
+ * BAPI-507 (N-2): warn-only worker file-scope guard.
+ *
+ * Compares a branch's changed files against the planner-declared touched-file
+ * set (delivered to the worker via `BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON`)
+ * and warns when the diff strays outside that set. It is strictly warn-only /
+ * fail-open: it NEVER blocks PR creation, mutates the branch, or exits non-zero.
+ * A worker that implements a sibling's files (the N-2 over-reach observed in the
+ * BAPI-488 run) surfaces here as a bounded, secret-free warning rather than a
+ * silent clobber.
+ *
+ * Byte-identical false-positive protection: the guard analyzes ONLY the
+ * branch-local diff against `origin/main` (`git diff --name-only
+ * origin/main...HEAD`), which excludes files that are byte-identical to
+ * `origin/main`. So a legitimate `git merge origin/main` that carries
+ * sibling-owned files in branch history but does not change them at the tip
+ * produces no false positive.
+ *
+ * All subprocess calls are list-based `spawnSync` with `shell: false` — no shell
+ * string is ever constructed.
+ */
+import { spawnSync } from "node:child_process";
+/** Env var carrying the compact JSON array of declared repo-relative paths. */
+export const DECLARED_TOUCHED_FILES_ENV = "BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON";
+/** Env var carrying the dispatched ticket key (used only to label warnings). */
+export const FILE_SCOPE_GUARD_TICKET_KEY_ENV = "BAPI_CONDUCTOR_TICKET_KEY";
+/** Base ref the branch diff is computed against. */
+export const FILE_SCOPE_GUARD_BASE_REF = "origin/main";
+/**
+ * Normalize a single declared/changed path to a repo-relative POSIX path, or
+ * `null` when it is unsafe/unusable. Rejects blank paths, POSIX- and
+ * Windows-absolute paths, and any parent traversal (`..`). Converts `\` → `/`
+ * and strips a single leading `./`. Never consults the filesystem.
+ */
+export function normalizeRepoRelativePath(input) {
+    if (typeof input !== "string")
+        return null;
+    const trimmed = input.trim();
+    if (trimmed.length === 0)
+        return null;
+    // Reject absolute paths (POSIX `/…`, `\…`, or Windows drive `C:\…` / `C:/…`)
+    // BEFORE separator normalization so both separator styles are caught.
+    if (trimmed.startsWith("/") ||
+        trimmed.startsWith("\\") ||
+        /^[A-Za-z]:[\\/]/.test(trimmed)) {
+        return null;
+    }
+    let p = trimmed.replace(/\\/g, "/");
+    if (p.startsWith("./"))
+        p = p.slice(2);
+    const segments = p.split("/");
+    if (segments.some((s) => s === ".."))
+        return null;
+    const cleaned = segments.filter((s) => s !== "" && s !== ".").join("/");
+    return cleaned.length > 0 ? cleaned : null;
+}
+/**
+ * Normalize a raw list of declared paths: drop non-strings and unsafe paths,
+ * dedupe, and sort. Anything that is not an array yields an empty list. This is
+ * the single source of truth for the declared-file normalization contract shared
+ * by the env producer (`buildEpicIdentityEnv`), the runtime plan mapper, and the
+ * guard's env parser.
+ */
+export function normalizeDeclaredTouchedFiles(list) {
+    if (!Array.isArray(list))
+        return [];
+    const out = new Set();
+    for (const item of list) {
+        const norm = normalizeRepoRelativePath(item);
+        if (norm)
+            out.add(norm);
+    }
+    return Array.from(out).sort();
+}
+/**
+ * Parse `BAPI_CONDUCTOR_DECLARED_TOUCHED_FILES_JSON` into a normalized
+ * declaration. Returns an "unspecified" result on a missing, blank, invalid-JSON,
+ * non-array, or empty (after normalization) value — the guard no-ops in every
+ * such case.
+ */
+export function parseDeclaredTouchedFilesFromEnv(env = process.env) {
+    const raw = env[DECLARED_TOUCHED_FILES_ENV];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return { specified: false };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { specified: false };
+    }
+    if (!Array.isArray(parsed))
+        return { specified: false };
+    const files = normalizeDeclaredTouchedFiles(parsed);
+    if (files.length === 0)
+        return { specified: false };
+    return { specified: true, files };
+}
+const defaultSpawnSync = (command, args, options) => spawnSync(command, args, options);
+/**
+ * Collect the files changed on the current branch relative to `origin/main`
+ * using a list-based `git diff --name-only origin/main...HEAD` invocation with
+ * `shell: false`. Byte-identical files (unchanged at the branch tip) are excluded
+ * by git itself. Any spawn error / non-zero exit yields `{ ok: false }` so the
+ * caller can fail open. Never spawns a shell.
+ */
+export function collectBranchChangedFiles(opts = {}) {
+    const baseRef = opts.baseRef ?? FILE_SCOPE_GUARD_BASE_REF;
+    const spawn = opts.spawnSyncFn ?? defaultSpawnSync;
+    let result;
+    try {
+        result = spawn("git", ["diff", "--name-only", `${baseRef}...HEAD`], {
+            cwd: opts.cwd,
+            encoding: "utf-8",
+            shell: false,
+        });
+    }
+    catch {
+        return { ok: false, files: [] };
+    }
+    if (result.error || result.status !== 0) {
+        return { ok: false, files: [] };
+    }
+    const stdout = typeof result.stdout === "string"
+        ? result.stdout
+        : result.stdout?.toString("utf-8") ?? "";
+    const files = [];
+    const seen = new Set();
+    for (const line of stdout.split("\n")) {
+        const norm = normalizeRepoRelativePath(line);
+        if (norm && !seen.has(norm)) {
+            seen.add(norm);
+            files.push(norm);
+        }
+    }
+    return { ok: true, files };
+}
+/**
+ * Compare `changedFiles` against a declaration using EXACT-PATH matching (v1: no
+ * directory-ownership inference). Returns `checked:false`/no warning when the
+ * declaration is unspecified. Otherwise flags every changed file not in the
+ * declared set as out-of-scope and builds a bounded, secret-free warning naming
+ * the ticket, the out-of-scope files, and the declared set size.
+ */
+export function analyzeDiffScope(input) {
+    if (!input.declared.specified) {
+        return { checked: false, outOfScopeFiles: [], warning: null };
+    }
+    const declaredSet = new Set(input.declared.files);
+    const outOfScope = input.changedFiles
+        .filter((f) => !declaredSet.has(f))
+        .sort();
+    if (outOfScope.length === 0) {
+        return { checked: true, outOfScopeFiles: [], warning: null };
+    }
+    const ticket = input.ticketKey && input.ticketKey.trim().length > 0
+        ? input.ticketKey.trim()
+        : "unknown-ticket";
+    const warning = `[file-scope-guard] ${ticket}: ${outOfScope.length} file(s) changed outside the ` +
+        `declared touched-file set (${input.declared.files.length} declared): ` +
+        `${outOfScope.join(", ")}. Warn-only — PR creation continues.`;
+    return { checked: true, outOfScopeFiles: outOfScope, warning };
+}
+/**
+ * CLI entrypoint: parse the declaration from the env, collect the branch diff,
+ * analyze scope, and print a warning for an out-of-scope diff. ALWAYS returns
+ * exit code `0` — an unspecified declaration, a git failure, or an out-of-scope
+ * diff all leave PR creation unblocked (warn-only / fail-open). Output is bounded
+ * and secret-free; the scope warning goes to stdout (explicit CLI-mode output),
+ * the fail-open diagnostic to stderr.
+ */
+export function runFileScopeGuardCli(deps = {}) {
+    const env = deps.env ?? process.env;
+    const writeOut = deps.writeOut ?? ((m) => process.stdout.write(`${m}\n`));
+    const writeErr = deps.writeErr ?? ((m) => process.stderr.write(`${m}\n`));
+    const ticketKey = env[FILE_SCOPE_GUARD_TICKET_KEY_ENV];
+    const declared = parseDeclaredTouchedFilesFromEnv(env);
+    if (!declared.specified) {
+        // No/blank/invalid/empty declaration → nothing to check (fail-open no-op).
+        return 0;
+    }
+    const collected = collectBranchChangedFiles({
+        cwd: deps.cwd,
+        spawnSyncFn: deps.spawnSyncFn,
+    });
+    if (!collected.ok) {
+        writeErr(`[file-scope-guard] ${ticketKey ?? "unknown-ticket"}: unable to check file ` +
+            `scope (git diff failed); continuing — PR creation is not blocked.`);
+        return 0;
+    }
+    const analysis = analyzeDiffScope({
+        ticketKey,
+        declared,
+        changedFiles: collected.files,
+    });
+    if (analysis.warning) {
+        writeOut(analysis.warning);
+    }
+    return 0;
+}