@bridge_gpt/mcp-server 0.2.38 → 0.2.39

package/build/executor/job-errors.js

@@ -1,3 +1,97 @@
+/**
+ * Executor-local named error helpers (BAPI-535, TDD §7/§9).
+ *
+ * Fail-loud executor conditions carry an explicit, stable `errorKind` so the
+ * runner can post the right `/fail` payload without coupling the executor to the
+ * v1 conductor error/ledger graph (see `types.ts` for the boundary contract).
+ * These are the ONLY named executor failure kinds this slice introduces:
+ *
+ *  - `MissingVerdictArtifact` — a `spec_review`/`smoke` job exited cleanly but its
+ *    fixed-path `<worktree>/.conductor/result.json` was missing/unreadable/invalid
+ *    (TDD §9: "a verdict can never be silently absent").
+ *  - `WorktreeLostBeforePush` — a `resume` job's worktree is gone AND its branch was
+ *    never pushed, so there is nothing to recreate from (TDD §7).
+ *  - `BranchMismatch` — a `resume` worktree is on the wrong branch; working there
+ *    would corrupt an unrelated branch, so abort rather than proceed (TDD §7).
+ *  - `WorkerFinalizationMissingRemoteBranchAndPr` — an implementation-style job
+ *    (BAPI-551) exited cleanly but produced neither a PR URL nor a pushed origin
+ *    branch, stranding the implement gate; see `worker-finalization.ts`.
+ *  - `WorkerFinalizationPrBaseMismatch` — an implementation-style job (BAPI-586)
+ *    opened a PR whose base branch is not the run base, so `claude-review.yml`
+ *    (triggered only on `branches: [main]`) never fires and the `code_review`
+ *    gate would hang forever; see `worker-finalization.ts`.
+ *  - `WorkerFinalizationSavedButUnfinalized` — an implementation-style job
+ *    (BAPI-762) exited cleanly, and an origin branch exists at an authoritative
+ *    tip that does NOT match the worker's own HEAD — durable work exists on
+ *    origin, but not this worker's latest commit. Distinct from
+ *    `WorkerFinalizationMissingRemoteBranchAndPr` (which covers "no evidence any
+ *    work reached origin") because this case has positive proof of recoverable
+ *    state: an operator can resume/finalize from the existing branch rather than
+ *    re-running from scratch; see `worker-finalization.ts`.
+ *  - `ContractError.WorkerConfigIsolation` — a per-job isolated Claude config
+ *    directory could not be established (unsupported platform, unsupported auth
+ *    layout, unseedable directory, or a missing required MCP registration), so
+ *    the worker would have fallen back to the operator's configuration and
+ *    inherited operator-scoped MCP servers. Fail-CLOSED (BAPI-731 WS-A);
+ *    see `worker-config-isolation.ts`.
+ *  - `ContractError.PreSpawnVerification` — the prepared worktree was not
+ *    provably clean at the expected commit immediately before spawn, so the
+ *    attempt could have committed leftover unrelated work (the F11a class).
+ *    Fail-CLOSED, including on a DEGRADED git read: "could not verify" is
+ *    never reported as "verified clean" (BAPI-731 WS-E).
+ *  - `ContractError.McpSurfaceMismatch` — the worker reported, on its own
+ *    `system`/`init` event, a set of loaded MCP servers that is not the set
+ *    provisioned into its worktree. Either it inherited a server it was never
+ *    granted, or a provisioned server is missing, or the event could not be read
+ *    at all. Fail-CLOSED and mid-flight: the worker is terminated before it does
+ *    work (BAPI-790); see `createMcpSurfaceObserver` in `observation.ts`.
+ *  - `ContractError.RequiredMcpRegistration` — the prepared worktree's
+ *    `.mcp.json` is absent, unreadable, malformed, or carries no `bridge-api`
+ *    entry. Since a worker loads MCP servers strictly from that file, it would
+ *    run with no Bridge tools and exit "cleanly" having done nothing
+ *    (RUN-FINDINGS-2026-08-05 F2). Fail-CLOSED, pre-spawn. Renamed from the
+ *    isolation-era kind by BAPI-790, because the condition is now about the file
+ *    itself rather than about an isolation directory.
+ *  - `ContractError.WorkerStartupFatal` — the worker exited non-zero having
+ *    emitted no stream-json event whatsoever, i.e. it died before reporting its
+ *    MCP surface. Distinguished from an ordinary `WorkerCrashed` because the
+ *    known cause under strict MCP loading is an enterprise `managed-mcp.json`
+ *    policy rejecting the strict flags, and the executor deliberately does NOT
+ *    retry without them (BAPI-790).
+ *  - `ContractError.ClaudeNotAuthenticated` — the worker's own stream-json
+ *    terminal `result` event reports one of the two Claude CLI authentication
+ *    failures measured and recorded in
+ *    `docs/claude/claude-cli-config-isolation-inventory.md` (Findings 4/5): no
+ *    credential at all (`Not logged in · Please run /login`), or a present but
+ *    invalid/expired `CLAUDE_CODE_OAUTH_TOKEN` (`OAuth access token is
+ *    invalid`, HTTP 401). Since BAPI-791 removed spawn-time credential
+ *    resolution, authentication is no longer checked before spawning — it
+ *    succeeds or fails at the real worker spawn, and a recognized failure here
+ *    is reported with this fixed, secret-free kind instead of a generic
+ *    `WorkerCrashed`.
+ *  - `ContractError.ExecutorAdapterUnavailable` — the configured agent has no
+ *    usable executor adapter (BAPI-781): unknown agent, no adapter registration,
+ *    an unimplemented strategy, an identity mismatch against the registry, a
+ *    missing/unsupported required capability, or a spawn shape inconsistent with
+ *    what the adapter declared. Fail-CLOSED and pre-spawn. This exists so the
+ *    refusal is DISTINGUISHABLE from a worker that ran and failed: the
+ *    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.
+ *
+ * These kinds are deliberately DISTINCT from each other so the refusals stay
+ * tellable apart in `executor_jobs.error_kind`.
+ *
+ * RETIRED (BAPI-790), kept exported so historical rows stay decodable and so a
+ * reader who greps a stored `error_kind` still lands on its definition:
+ *  - `ContractError.WorkerConfigIsolation` and
+ *    `ContractError.BridgeCredentialUnavailable` belonged to the per-job Claude
+ *    config-directory isolation retired by BAPI-790. Nothing posts them now.
+ *  - `ContractError.McpShadowing` was the BAPI-727 shadowing refusal, now an
+ *    advisory warning — strict loading means an operator registration cannot
+ *    shadow a worker.
+ */
+import { normalizeMcpServerNames } from "./observation.js";
 /** Stable executor failure-kind constants (posted verbatim as `error_kind`). */
 export const MissingVerdictArtifact = "MissingVerdictArtifact";
 export const WorktreeLostBeforePush = "WorktreeLostBeforePush";
@@ -8,6 +102,112 @@ export const WorkerFinalizationSavedButUnfinalized = "WorkerFinalizationSavedBut
 export const WorkerConfigIsolation = "ContractError.WorkerConfigIsolation";
 export const PreSpawnVerification = "ContractError.PreSpawnVerification";
 export const BridgeCredentialUnavailable = "ContractError.BridgeCredentialUnavailable";
+export const McpSurfaceMismatch = "ContractError.McpSurfaceMismatch";
+export const WorkerStartupFatal = "ContractError.WorkerStartupFatal";
+export const RequiredMcpRegistration = "ContractError.RequiredMcpRegistration";
+export const ClaudeNotAuthenticated = "ContractError.ClaudeNotAuthenticated";
+export const WorktreeBusy = "ContractError.WorktreeBusy";
+export const ExecutorAdapterUnavailable = "ContractError.ExecutorAdapterUnavailable";
+/**
+ * BAPI-814/D1: a previous attempt's `.conductor/result.json` / `critique.md`
+ * could not be removed before the worker spawned. Fail-closed on purpose — the
+ * alternative is running an attempt that may read a stale verdict as its own.
+ */
+export const StaleArtifactCleanupFailed = "ContractError.StaleArtifactCleanupFailed";
+/** 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. */
+const MCP_SURFACE_NAME_LIMIT = 20;
+/**
+ * Render a name list for a containment diagnostic: already-normalized names,
+ * comma-joined, bounded, with a fixed marker for the empty case.
+ *
+ * NAMES ONLY, and that is a hard constraint rather than a stylistic one. This
+ * text is posted to the server as `error_message` and stored on the job row, so
+ * anything else that could ride along — a registration command, an argv array, an
+ * env block, the `.mcp.json` path (which contains a username), or a raw stream
+ * line — would turn a containment failure into a disclosure.
+ */
+function formatMcpServerNameList(names) {
+    // Normalized HERE rather than trusted from the caller. Both call sites already
+    // pass normalized sets, but determinism is the property that makes two job rows
+    // comparable, and a guarantee that depends on every caller remembering to
+    // normalize is not a guarantee.
+    const normalized = normalizeMcpServerNames(names);
+    if (normalized.length === 0)
+        return EMPTY_MCP_SERVER_NAME_MARKER;
+    const shown = normalized.slice(0, MCP_SURFACE_NAME_LIMIT);
+    const suffix = normalized.length > shown.length ? `, +${normalized.length - shown.length} more` : "";
+    return `${shown.join(", ")}${suffix}`;
+}
+/**
+ * The fixed message posted with {@link McpSurfaceMismatch}.
+ *
+ * Deterministic for a given pair of name sets: both sides arrive already sorted
+ * and deduplicated from `normalizeMcpServerNames`, so the same mismatch always
+ * renders the same text and an operator can compare two job rows directly.
+ */
+export function formatMcpSurfaceMismatch(expected, observed) {
+    return ("worker MCP surface mismatch: the worker reported loading a different set of MCP servers " +
+        "than its worktree provisions, so it was terminated before doing work. " +
+        `Expected: ${formatMcpServerNameList(expected)}. Observed: ${formatMcpServerNameList(observed)}. ` +
+        "An observed set of 'none' means the init event's server list could not be read at all. " +
+        "Check that the installed Claude CLI supports --strict-mcp-config and that nothing adds MCP " +
+        "servers outside the worktree registration.");
+}
+/**
+ * The fixed message posted with {@link WorkerStartupFatal}.
+ *
+ * States only what was OBSERVED — a non-zero exit with no stream-json output —
+ * and names enterprise managed MCP policy as the known cause to check, without
+ * claiming to have identified it. That distinction is deliberate: the enterprise
+ * `managed-mcp.json` fatal signature has not been measured on any host available
+ * to this repository (see inventory Finding 6), so asserting it would be a guess
+ * printed as a diagnosis.
+ */
+export const WORKER_STARTUP_FATAL_MESSAGE = "the worker exited before reporting its MCP surface: it produced no stream-json output at all " +
+    "and exited non-zero, which is a fatal startup failure rather than a failure during work. The " +
+    "known cause under strict MCP loading is an enterprise managed MCP policy (managed-mcp.json) " +
+    "rejecting --strict-mcp-config; also verify the installed Claude CLI supports the strict MCP " +
+    "flags. The executor does not retry without them, because falling back to unscoped loading " +
+    "would silently restore full inheritance of the operator's MCP servers.";
+/**
+ * The fixed message posted with {@link ClaudeNotAuthenticated}.
+ *
+ * Names only the two remediation paths, never the raw stream-json content that
+ * triggered classification — the adapter's detector returns a verdict and a
+ * reason code, never the matched line. The headless alternative names the
+ * environment variable only, never a value.
+ */
+export const CLAUDE_NOT_AUTHENTICATED_MESSAGE = "the worker could not authenticate as the Claude CLI. Run `claude login` on this host; on a " +
+    "headless host with no interactive login available, export CLAUDE_CODE_OAUTH_TOKEN yourself " +
+    "before starting the executor.";
+/**
+ * The fixed message posted with {@link WorktreeBusy} (BAPI-793).
+ *
+ * FIXED, and carrying no identity at all — not the worktree path, not the
+ * conflicting job's id, not a claim token. This string is stored on the job row
+ * and read back by anyone with access to the run, while the worktree path
+ * contains an operator's username and the claim token is a fencing credential.
+ * The attributable detail (this job, the conflicting job, ticket, repo, worktree
+ * basename) goes to the executor's OWN stderr instead, where it stays on the
+ * host that already has all of it.
+ */
+export const WORKTREE_BUSY_MESSAGE = "another executor job already holds this ticket's worktree, so no worker was started for this " +
+    "job. Two workers in one working tree corrupt each other's edits, index, and commits, so the " +
+    "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 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
+// in a generic error module meant every future agent's auth failure would have
+// to be recognized by Claude's shape or not at all.
+//
+// The ERROR KIND and the fixed message above stay here on purpose: mapping a
+// 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;
 /**