@bridge_gpt/mcp-server 0.2.50 → 0.2.52

package/build/executor/env-file-guard.js

@@ -0,0 +1,113 @@
+/**
+ * Fail-closed pre-spawn env-file strip for an executor worktree (BAPI-1019, A.3).
+ *
+ * Architecture Miss 28: a v2 conductor worker ran an allowed `pytest` whose
+ * harness truncated the operator's real operational database. The worker could
+ * reach that database because its worktree carried a copy of the operator's
+ * `.env`, delivered by Worktrunk's `copy-ignored` step. `.config/wt.toml` now
+ * excludes `.env*` from that copy, which removes the cause — but Worktrunk runs
+ * `post-start` hooks in the BACKGROUND after `wt switch` returns, and any local
+ * tooling an operator adds can write into a worktree at any time. A source-level
+ * exclusion therefore cannot be the whole answer: the executor has to check, at
+ * the last possible moment, that the worktree it is about to hand a worker is
+ * actually free of environment files.
+ *
+ * That is this module. It runs as the FINAL step before `deps.spawnProcess` and
+ * it fails CLOSED — following `StaleArtifactCleanupFailed`, not the fail-open
+ * deny-layer posture. "Could not confirm clean" and "confirmed clean" must be
+ * distinguishable outcomes, and only the second one is allowed to spawn.
+ *
+ * THE SINGLE MOST IMPORTANT DETAIL: this module uses `lstat` and `unlink` and
+ * NEVER follows a symbolic link. An interactive worktree's `.env` is a symlink
+ * into the main checkout (see `../env-file-link.ts`), and if an entry like that
+ * ever appeared in an executor worktree, resolving it and unlinking the RESOLVED
+ * target would delete the operator's real `.env`. `unlink` removes the directory
+ * entry itself, so a link is removed as a link. There is deliberately no `stat`,
+ * `realpath`, `readlink`, or `readFile` in the dependency surface — the guarantee
+ * is enforced by what the module cannot reach, not by remembering not to call it.
+ *
+ * The re-list after removal is what makes the two outcomes tellable apart. An
+ * unreadable directory, a failed `lstat`, a failed `unlink`, or a surviving entry
+ * all produce `ok: false`; only a second listing that shows no matching entry
+ * produces `ok: true`.
+ *
+ * REDACTION. A failure returns a fixed CATEGORY and nothing else — no filename,
+ * no path, no resolved target, no exception text. This value reaches the job row
+ * and the executor's stderr, and a worktree path contains an operator's username.
+ * Successful `removed` names are safe by construction: they are basenames drawn
+ * from a fixed pattern, and knowing that `.env` was removed is the diagnostic. See
+ * `secretFreeErrorMessage()` / `ERROR_MESSAGE_MAX_CHARS` in `job-errors.ts` for
+ * the bounding posture these strings satisfy.
+ */
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/**
+ * True for `.env` and anything under the `.env.` prefix.
+ *
+ * Deliberately WIDER than the interactive linker's closed two-name list: removing
+ * too much from a worker worktree is harmless, and an operator's `.env.staging`
+ * is exactly as dangerous as their `.env`. It is still a PREFIX rule, not a
+ * substring one — `.envrc` (direnv) and `.envx` do not match, because they are
+ * not environment files this contract is about and silently deleting an
+ * operator's direnv config would be a surprise well outside this ticket.
+ */
+export function isWorkerEnvFileName(name) {
+    return name === ".env" || name.startsWith(".env.");
+}
+/**
+ * Strip every `.env` / `.env.*` entry from a worktree ROOT and prove it worked.
+ *
+ * Only the root is examined. A nested `.env` (a fixture under `tests/`, a
+ * vendored example) is not what reaches a process's environment loader, and
+ * walking the tree would turn a fast pre-spawn gate into an unbounded traversal
+ * of a whole checkout.
+ */
+export async function stripWorkerEnvFiles(worktreePath, deps) {
+    const pathApi = pathApiForExecutorPlatform(deps.platform ?? process.platform);
+    let entries;
+    try {
+        entries = await deps.readdir(worktreePath);
+    }
+    catch {
+        // Cannot even see the directory ⇒ cannot confirm it is clean. Refuse.
+        return { ok: false, category: "listing_failed" };
+    }
+    // Sorted so a successful `removed` list is deterministic and two job rows for
+    // the same condition render identically.
+    const matches = entries.filter(isWorkerEnvFileName).sort();
+    for (const name of matches) {
+        const target = pathApi.join(worktreePath, name);
+        try {
+            // Non-following metadata. The result is deliberately unused for a decision:
+            // a regular file and a symlink are both removed the same way, by `unlink`.
+            // The call is here so an entry that cannot be inspected refuses the spawn
+            // instead of being unlinked blind.
+            await deps.lstat(target);
+        }
+        catch {
+            return { ok: false, category: "metadata_failed" };
+        }
+        try {
+            await deps.unlink(target);
+        }
+        catch {
+            // Includes the directory case (`EISDIR`/`EPERM`): a `.env` that is a
+            // DIRECTORY is not removable by `unlink`, and this guard deliberately does
+            // not escalate to a recursive delete inside a worktree.
+            return { ok: false, category: "unlink_failed" };
+        }
+    }
+    // The confirmation half. Without this, "we called unlink" would be reported as
+    // "the worktree is clean", which is exactly the claim this gate must not make
+    // on faith.
+    let remaining;
+    try {
+        remaining = await deps.readdir(worktreePath);
+    }
+    catch {
+        return { ok: false, category: "verification_listing_failed" };
+    }
+    if (remaining.some(isWorkerEnvFileName)) {
+        return { ok: false, category: "entry_survived" };
+    }
+    return { ok: true, removed: matches };
+}

package/build/executor/env.js

@@ -33,13 +33,26 @@
  * executor must not reach a worker and silently change which configuration —
  * and which MCP registrations — the CLI resolves.
  *
+ * BAPI-1019: this builder also injects four SENTINEL DATABASE literals
+ * (`DATABASE_URL`, `POSTGRES_DATABASE`, `POSTGRES_DB`, `PGDATABASE`), all naming a
+ * database that does not exist. Architecture Miss 28 was a worker that ran an
+ * allowed `pytest` whose harness truncated the operator's real operational
+ * database; it could name that database because a copied `.env` reached its
+ * worktree and nothing in the worker environment said otherwise. The env-file
+ * strip in `env-file-guard.ts` removes the file, and these constants are the
+ * SECOND layer: code inside a worker that resolves a database from the
+ * environment resolves a name that connects to nothing. The two layers are
+ * independent on purpose — the harness calls `load_dotenv(override=False)`, so a
+ * value already in the environment WINS over a `.env` entry, which is what makes
+ * the sentinel effective even if a file ever survived the strip.
+ *
  * The `mcp-invoke` shim (a separate process) resolves `BAPI_API_KEY` itself at
  * call time from the operator's real user-scoped credential store, exactly as it
  * did before BAPI-731, so this worker environment never carries it. The model is
  * still denied direct reads of that store by the deny layer
  * (`Read(~/.config/bridge/**)` in `permissions.ts`).
  */
-import { PR_BASE_BRANCH_ENV_VAR } from "../pr-base-contract.js";
+import { PR_BASE_BRANCH_ENV_VAR, WORKER_BRANCH_ENV_VAR } from "../pr-base-contract.js";
 import { INDEX_SCOPE_ENV_VAR, validateOptionalIndexScope } from "../index-scope-contract.js";
 /** Non-secret operational keys forwarded to the worker when present. */
 const ALLOWED_ENV_KEYS = [
@@ -56,6 +69,36 @@ const ALLOWED_ENV_KEYS = [
     "TERM",
     "NO_COLOR",
 ];
+/**
+ * The database name every worker resolves, and it exists nowhere (BAPI-1019).
+ *
+ * A NAME rather than an empty value, deliberately: an unset `POSTGRES_DB` makes a
+ * client fall back to a default (often the connecting user's name, which on a
+ * developer host is a real database), while a name nothing has ever created fails
+ * at connect and says so. The failure text carries this string, which is what the
+ * harness drill asserts on — proving the name reached the driver rather than
+ * merely that a connection failed.
+ */
+export const WORKER_SENTINEL_DATABASE_NAME = "bridge_worker_no_database";
+/**
+ * The sentinel connection URL. Points at port 1 on loopback — a privileged port
+ * nothing binds — so the failure is immediate and local rather than a DNS lookup
+ * or a timeout against something real.
+ */
+export const WORKER_SENTINEL_DATABASE_URL = `postgresql://${WORKER_SENTINEL_DATABASE_NAME}@127.0.0.1:1/${WORKER_SENTINEL_DATABASE_NAME}`;
+/**
+ * Every environment key that names a database target, in the order they are set.
+ *
+ * `DATABASE_URL` is listed first because it WINS over the `POSTGRES_*` trio in
+ * `db/utils.py`; the other three are set anyway so a code path that reads only
+ * the discrete parts is covered too.
+ */
+export const WORKER_SENTINEL_DATABASE_ENV_KEYS = [
+    "DATABASE_URL",
+    "POSTGRES_DATABASE",
+    "POSTGRES_DB",
+    "PGDATABASE",
+];
 /** Substrings that mark a key as secret-bearing (case-insensitive). */
 const SECRET_NAME_FRAGMENTS = ["TOKEN", "SECRET", "PASSWORD", "API_KEY"];
 /**
@@ -101,6 +144,24 @@ export const EXPLICIT_DENY_KEYS = [
     // decision, and inheriting one would route an unscoped worker's plan and review
     // at another epic's shadow index while nothing in the job said so.
     INDEX_SCOPE_ENV_VAR,
+    // BAPI-1020: the worker's own branch follows the same rule, and for this key the
+    // rule is the guard's integrity rather than a research-scope mistake. The
+    // deterministic PreToolUse guard decides "is this push destination my own
+    // branch?" by comparing against this value, so an operator's ambient
+    // `BAPI_WORKER_BRANCH` reaching a worker would let the environment redefine what
+    // the guard treats as safe. Absent from ALLOWED_ENV_KEYS so it is never copied
+    // from `parentEnv`, and denied EXPLICITLY here so the answer is local and
+    // auditable rather than inferred from an omission.
+    WORKER_BRANCH_ENV_VAR,
+    // BAPI-1019: the four database keys follow the BAPI_INDEX_SCOPE precedent
+    // exactly — absent from ALLOWED_ENV_KEYS so they are never copied from
+    // `parentEnv`, and denied EXPLICITLY here so an operator's ambient value can
+    // never win over the sentinel constants the builder sets. Denying a key the
+    // builder also sets is not redundant: the deny list is what makes
+    // `isExecutorEnvKeyAllowed` answer "no" for these names locally and
+    // auditably, rather than relying on a reader noticing they are missing from
+    // the allowlist.
+    ...WORKER_SENTINEL_DATABASE_ENV_KEYS,
 ];
 /**
  * True only when `key` is a safe, allowlisted operational key. Exported so the
@@ -140,10 +201,26 @@ export function buildExecutorBaseWorkerEnv(parentEnv, options = {}) {
     }
     env.BRIDGE_SKIP_PREPUSH = "1";
     env.MAX_MCP_OUTPUT_TOKENS = "50000";
+    // BAPI-1019 — the sentinel database target, set for EVERY job type and every
+    // adapter, from constants and never from `parentEnv`. Set here rather than in
+    // an adapter because "a worker cannot name a real database" is a property of
+    // being a worker, not of being a Claude worker.
+    env.DATABASE_URL = WORKER_SENTINEL_DATABASE_URL;
+    env.POSTGRES_DATABASE = WORKER_SENTINEL_DATABASE_NAME;
+    env.POSTGRES_DB = WORKER_SENTINEL_DATABASE_NAME;
+    env.PGDATABASE = WORKER_SENTINEL_DATABASE_NAME;
     if (typeof options.effectiveBaseBranch === "string" &&
         options.effectiveBaseBranch.length > 0) {
         env[PR_BASE_BRANCH_ENV_VAR] = options.effectiveBaseBranch;
     }
+    // BAPI-1020 — the worker's own branch, set ONLY from the explicit job value and
+    // ONLY when it is a non-empty string. An empty or absent value adds no key at
+    // all, so an unscoped job's environment stays byte-identical to the
+    // pre-BAPI-1020 one rather than carrying an empty string the guard would have to
+    // special-case.
+    if (typeof options.workerBranch === "string" && options.workerBranch.length > 0) {
+        env[WORKER_BRANCH_ENV_VAR] = options.workerBranch;
+    }
     // BAPI-844: the index-scope declaration, set ONLY from the explicit option and
     // only after the shared shape check. A malformed explicit value throws here —
     // before an environment exists — rather than being dropped: silently omitting it

package/build/executor/heartbeat.js

@@ -79,6 +79,15 @@ export async function runHeartbeatLoop(params) {
             killOwnedProcess(proc, "server_stop");
             return { kind: "server_stop" };
         }
+        if (result.outcome === "auth_fatal") {
+            // BAPI-1021 (AC-5): bypass the dead-man wait entirely — an auth failure
+            // will never resolve itself by waiting out `deadmanMs`. Deliberately does
+            // NOT reset `lastSuccessfulHeartbeatAt`, set `ownership.abandoned`/
+            // `abandonReason` (this is not a lost/stale claim), or invoke worktree
+            // reset/recreation/cleanup: the current job drains normally while the
+            // runner's process-level handler stops future claiming.
+            return { kind: "auth_fatal", httpStatus: result.authHttpStatus ?? 401 };
+        }
         if (result.outcome === "updated") {
             ownership.lastSuccessfulHeartbeatAt = deps.now();
             return null;

package/build/executor/http-client.js

@@ -1,3 +1,14 @@
+/**
+ * Executor `/executor/jobs/*` protocol HTTP client (BAPI-534, TDD §7, §10).
+ *
+ * Encapsulates the T2 protocol behind an injected `fetch` boundary with correct
+ * fencing-token semantics. The claim response `repo_name` and `claim_token` are
+ * echoed on every heartbeat/complete/fail (the server mutation guards are
+ * repo-bound and fenced on `claim_token`). The `X-API-Key` header value is never
+ * logged and never included in any error string.
+ */
+import { RECONCILER_LIVENESS_VALUES } from "./types.js";
+import { readEpicRunCompletionState, } from "../conductor/bridge-api-client.js";
 /** Bound a server-provided diagnostic snippet included in error strings. */
 function boundedDetail(text) {
     const trimmed = (text ?? "").trim();
@@ -39,13 +50,6 @@ function parseStopRequested(bodyText) {
  * (BAPI-871). Exported so the client and its tests name it once.
  */
 export const RECONCILER_LIVENESS_HEADER = "X-BAPI-Reconciler-Liveness";
-/** The only values the server is documented to send. */
-const RECONCILER_LIVENESS_VALUES = [
-    "fresh",
-    "stale",
-    "never_seen",
-    "unknown",
-];
 /**
  * Read the liveness header off a claim response, admitting ONLY documented
  * values.
@@ -76,17 +80,43 @@ export function parseReconcilerLivenessHeader(headers) {
 /**
  * Map a mutation (heartbeat/complete/fail) HTTP response onto the fencing
  * outcome. `allowInvalidResult` maps 422 to `invalid_job_result` (complete only).
+ *
+ * BAPI-1021 (AC-5): 401/403 map to `auth_fatal` with the exact status attached,
+ * BEFORE the generic `fatal_http_error` fallback — the response body is never
+ * retained on this path (never logged, never echoed into the returned metadata).
  */
 function mapMutationResponse(status, bodyText, allowInvalidResult) {
     if (status === 409)
-        return "stale_claim";
+        return { outcome: "stale_claim" };
     if (status === 503)
-        return "retry_later";
+        return { outcome: "retry_later" };
     if (status === 422 && allowInvalidResult)
-        return "invalid_job_result";
+        return { outcome: "invalid_job_result" };
     if (status >= 200 && status < 300 && isOkBody(bodyText))
-        return "updated";
-    return "fatal_http_error";
+        return { outcome: "updated" };
+    if (status === 401 || status === 403)
+        return { outcome: "auth_fatal", authHttpStatus: status };
+    return { outcome: "fatal_http_error" };
+}
+/**
+ * Adapt the executor's injected `FetchLike` transport to the narrower
+ * `ConductorFetch` shape the shared read-only Bridge API GET helper expects
+ * (BAPI-1010). GET-only; deliberately ignores the caller's `AbortSignal` —
+ * `FetchLike`'s production implementation (`createDefaultExecutorDeps`)
+ * already wraps every request in its own `AbortController` timeout, so no
+ * request is ever left uncancelled by discarding this one.
+ */
+function toConductorGetFetch(fetchLike) {
+    return async (url, init) => {
+        const requestInit = { method: "GET", headers: init.headers };
+        const res = await fetchLike(url, requestInit);
+        const text = await res.text();
+        return {
+            ok: res.status >= 200 && res.status < 300,
+            status: res.status,
+            json: async () => JSON.parse(text),
+        };
+    };
 }
 export function createExecutorHttpClient(config) {
     const base = config.baseUrl.replace(/\/+$/, "") + "/executor/jobs";
@@ -119,7 +149,7 @@ export function createExecutorHttpClient(config) {
         catch {
             // Transient network error — treat as fatal for a single mutation attempt;
             // the caller's retry/dead-man logic decides whether to keep the worker alive.
-            return "fatal_http_error";
+            return { outcome: "fatal_http_error" };
         }
     }
     return {
@@ -158,7 +188,18 @@ export function createExecutorHttpClient(config) {
                     return { kind: "fatal", error: "claim returned invalid JSON" };
                 }
             }
-            if (status === 401 || status === 403 || status === 422) {
+            if (status === 401 || status === 403) {
+                // BAPI-1021 (AC-5): carry the auth category + exact status alongside the
+                // existing error string, distinguishing this from the non-auth fatal 422
+                // contract response below without parsing `error`.
+                return {
+                    kind: "fatal",
+                    error: `claim rejected (HTTP ${status}): ${boundedDetail(text)}`,
+                    authCategory: "auth_fatal",
+                    authHttpStatus: status,
+                };
+            }
+            if (status === 422) {
                 return { kind: "fatal", error: `claim rejected (HTTP ${status}): ${boundedDetail(text)}` };
             }
             // 5xx and any other unexpected status are retryable.
@@ -171,13 +212,14 @@ export function createExecutorHttpClient(config) {
             let status;
             let text;
             try {
-                const res = await post(`/${job.id}/heartbeat`, {
+                const body = {
                     repo_name: job.repo_name,
                     claim_token: job.claim_token,
                     local_commit_count: payload.local_commit_count,
                     last_commit_sha: payload.last_commit_sha,
                     telemetry: payload.telemetry,
-                }, job.repo_name);
+                };
+                const res = await post(`/${job.id}/heartbeat`, body, job.repo_name);
                 status = res.status;
                 text = res.text;
             }
@@ -186,8 +228,10 @@ export function createExecutorHttpClient(config) {
                 // caller's dead-man logic decides whether to keep the worker alive.
                 return { outcome: "fatal_http_error" };
             }
-            const outcome = mapMutationResponse(status, text, false);
-            const result = { outcome };
+            const mapped = mapMutationResponse(status, text, false);
+            const result = { outcome: mapped.outcome };
+            if (mapped.authHttpStatus !== undefined)
+                result.authHttpStatus = mapped.authHttpStatus;
             if (parseStopRequested(text))
                 result.stop_requested = true;
             return result;
@@ -211,7 +255,7 @@ export function createExecutorHttpClient(config) {
             }
         },
         complete(job, completion) {
-            return mutate(`/${job.id}/complete`, {
+            const body = {
                 repo_name: job.repo_name,
                 claim_token: job.claim_token,
                 job_type: completion.job_type,
@@ -222,10 +266,11 @@ export function createExecutorHttpClient(config) {
                 local_commit_count: completion.local_commit_count,
                 last_commit_sha: completion.last_commit_sha,
                 telemetry: completion.telemetry,
-            }, true, job.repo_name);
+            };
+            return mutate(`/${job.id}/complete`, body, true, job.repo_name);
         },
         fail(job, failure) {
-            return mutate(`/${job.id}/fail`, {
+            const body = {
                 repo_name: job.repo_name,
                 claim_token: job.claim_token,
                 error_kind: failure.error_kind,
@@ -234,7 +279,30 @@ export function createExecutorHttpClient(config) {
                 local_commit_count: failure.local_commit_count,
                 last_commit_sha: failure.last_commit_sha,
                 telemetry: failure.telemetry,
-            }, false, job.repo_name);
+            };
+            return mutate(`/${job.id}/fail`, body, false, job.repo_name);
+        },
+        /**
+         * Read-only epic-run completion-state projection (BAPI-1010). Delegates
+         * URL construction, timeout handling, response validation, and failure
+         * sanitization entirely to {@link readEpicRunCompletionState} — this
+         * method only resolves the repo-scoped access and adapts the transport.
+         * Never throws: `readEpicRunCompletionState` is itself non-throwing, and
+         * the try/catch below is belt-and-braces so a future change there can
+         * never surface an exception through this public contract.
+         */
+        async readEpicRunState(epicRunId, repoName) {
+            const access = {
+                repoName,
+                apiKey: keyForRepo(repoName),
+                baseUrl: config.baseUrl,
+            };
+            try {
+                return await readEpicRunCompletionState(access, epicRunId, toConductorGetFetch(config.fetch));
+            }
+            catch {
+                return { ok: false, reason: "network" };
+            }
         },
     };
 }

package/build/executor/job-errors.js

@@ -86,6 +86,14 @@
  *    alternative to reporting it is defaulting to Claude's behavior for an agent
  *    nobody implemented, which would spawn a real worker under containment the
  *    operator never declared.
+ *  - `ContractError.WorkerEnvFilePresent` — the worktree could not be CONFIRMED
+ *    free of `.env` / `.env.*` entries at the last moment before spawn
+ *    (BAPI-1019). An operator environment file inside a worker's worktree is how
+ *    Architecture Miss 28 happened: the worker resolved a real database from one
+ *    and a test harness then truncated that database. Fail-CLOSED, pre-spawn, and
+ *    NON-RETRYABLE — the condition is a property of the HOST's worktree tooling
+ *    rather than of the ticket, so the next job on the same host reproduces it
+ *    identically; see `env-file-guard.ts`.
  *
  * These kinds are deliberately DISTINCT from each other so the refusals stay
  * tellable apart in `executor_jobs.error_kind`.
@@ -123,6 +131,14 @@ export const ExecutorAdapterUnavailable = "ContractError.ExecutorAdapterUnavaila
  * alternative is running an attempt that may read a stale verdict as its own.
  */
 export const StaleArtifactCleanupFailed = "ContractError.StaleArtifactCleanupFailed";
+/**
+ * BAPI-1019 (A.4): the worktree still held — or could not be proven free of — an
+ * operator environment file at the spawn boundary. Sits beside
+ * {@link PreSpawnVerification} and {@link StaleArtifactCleanupFailed} because it
+ * is the same shape: a pre-spawn assertion about the worktree that refuses rather
+ * than proceeding on an unverified premise.
+ */
+export const WorkerEnvFilePresent = "ContractError.WorkerEnvFilePresent";
 /** Rendered in place of an empty name list, so "none" is never ambiguous. */
 export const EMPTY_MCP_SERVER_NAME_MARKER = "none";
 /** Bound the rendered name lists so a pathological registration cannot spam a job row. */
@@ -207,6 +223,25 @@ export const WORKTREE_BUSY_MESSAGE = "another executor job already holds this ti
     "second claim is refused rather than allowed in. The refusal is expected when two jobs exist " +
     "for one ticket; the job that holds the worktree continues normally, and this one is safe to " +
     "retry once it finishes. See the executor's stderr for the conflicting job id.";
+/**
+ * The fixed message posted with {@link WorkerEnvFilePresent} (BAPI-1019).
+ *
+ * FIXED and identity-free, following {@link WORKTREE_BUSY_MESSAGE} and
+ * {@link WORKER_STARTUP_FATAL_MESSAGE}: it states what was OBSERVED (an
+ * environment file was present in the worktree at spawn and could not be
+ * confirmed removed) and names the remediation, and it carries no worktree path,
+ * no username, no discovered filename, no link target, no file content, and no
+ * exception text. This string is stored on the job row and read back by anyone
+ * with access to the run; the attributable detail (job id, guard category) goes
+ * to the executor's own stderr, on the host that already has it.
+ *
+ * It does NOT say "retry" anywhere, deliberately. The condition recurs
+ * identically until an operator changes the host's worktree tooling.
+ */
+export const WORKER_ENV_FILE_PRESENT_MESSAGE = "an environment file was present in this job's worktree at spawn and could not be confirmed " +
+    "removed, so no worker was started. A worker that reads one resolves real credentials and a " +
+    "real database. Check the copy-ignored exclusions in .config/wt.toml and any local tooling " +
+    "that writes into worktrees.";
 // The Claude-specific matcher that used to live here moved into the Claude
 // executor adapter as `classifyClaudeAuthFailure` (BAPI-781). Recognizing one
 // CLI's not-logged-in output is precisely a per-agent capability, and leaving it
@@ -217,8 +252,14 @@ export const WORKTREE_BUSY_MESSAGE = "another executor job already holds this ti
 // classification onto a stable executor failure remains executor-owned, so an
 // adapter cannot invent its own error kinds or its own operator-facing
 // remediation text.
-/** Bound a failure message so no unbounded/secret-bearing text is posted. */
-const ERROR_MESSAGE_MAX_CHARS = 300;
+/**
+ * Bound a failure message so no unbounded/secret-bearing text is posted.
+ *
+ * EXPORTED (BAPI-1019) so a fixed-message contract test can assert against the
+ * same number {@link ExecutorNamedError} truncates at, rather than restating
+ * `300` and silently going vacuous the day the bound changes.
+ */
+export const ERROR_MESSAGE_MAX_CHARS = 300;
 /**
  * An `Error` subclass carrying a stable `errorKind` plus a bounded
  * `errorMessage`. Named executor failures default to the `crashed` wire