@bridge_gpt/mcp-server 0.2.53 → 0.2.54

package/build/executor/claim-scope.js

@@ -0,0 +1,104 @@
+/**
+ * The executor CLAIM SCOPE: one vocabulary, one validator, two commands.
+ *
+ * BAPI-1026 (R54) made the claim scope mandatory and explicit: an executor
+ * started with neither `--epic-run-id` nor `--repo-wide` REFUSES TO START,
+ * because the server no longer treats an omitted scope as repository-wide and
+ * such an executor would poll forever and claim nothing. Refusing loudly at
+ * startup replaced that silent idle.
+ *
+ * BAPI-1102 gave `plane up` executor lanes of its own to spawn, which made the
+ * refusal reachable from a second command — and made a copied string literal the
+ * obvious hazard. A plane that re-worded the executor's refusal would tell an
+ * operator something subtly different about the same rule, and the two wordings
+ * would drift the first time either was edited. So the vocabulary and the rule
+ * move HERE, and both CLIs render what this module returns, verbatim.
+ *
+ * Deliberately free of process startup, filesystem access, network access, and
+ * CLI output. It is imported by `executor/cli.ts` and by `plane/`, and a shared
+ * module that reached for any of those would drag the whole executor runtime into
+ * the plane's import graph to validate two flags.
+ */
+/**
+ * The exact refusal for an invocation carrying BOTH forms of scope.
+ *
+ * Module-level constants, not inline literals, and exported so a test can assert
+ * that the plane renders the executor's own wording rather than a lookalike.
+ * Neither interpolates anything: these are fixed prose about flags.
+ */
+export const EXECUTOR_CLAIM_SCOPE_MUTUALLY_EXCLUSIVE_MESSAGE = "--repo-wide cannot be combined with --epic-run-id: pass one claim scope, not both";
+/**
+ * The shape of a server-minted epic run id (BAPI-794).
+ *
+ * `epic_run_id` is always minted as `str(uuid.uuid4())` in
+ * `api/library/db/epic_runs.py`, so a standard UUID shape — any version — is a
+ * cheap, safe pre-validation: it rejects an obvious typo before any credential
+ * resolution or executor-loop startup, without over-constraining the CLI to a
+ * version the server does not itself enforce.
+ *
+ * It lives HERE, with the rest of the scope vocabulary, rather than in
+ * `executor/cli.ts` where it began. `plane up` accepted any non-blank id and the
+ * executor it spawns then refused the same value at startup — the operator saw a
+ * plane come up and a lane die, instead of one refusal at the point of entry
+ * (BAPI-1102 review).
+ */
+export const EXECUTOR_EPIC_RUN_ID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+/** Is this a plausibly server-minted epic run id? */
+export function isValidExecutorEpicRunId(value) {
+    return EXECUTOR_EPIC_RUN_ID_PATTERN.test(value.trim());
+}
+/**
+ * The refusal for an id that cannot be a server-minted run id. Interpolates the
+ * offending value, which is argv the operator just typed — never a credential.
+ */
+export function executorEpicRunIdRefusal(value) {
+    return `--epic-run-id has an invalid value: ${value}`;
+}
+/** The exact refusal for an invocation carrying NO scope at all. */
+export const EXECUTOR_CLAIM_SCOPE_REQUIRED_MESSAGE = "a claim scope is required: pass --epic-run-id <id> (repeatable) to serve " +
+    "specific epic runs, or --repo-wide to deliberately claim repository-wide";
+/**
+ * Validate a parsed scope selection.
+ *
+ * Order matters and is part of the contract: the mutual-exclusion refusal is
+ * reported BEFORE the missing-scope refusal, so an invocation that supplies both
+ * is told it supplied both rather than being told to supply one. One invocation
+ * therefore yields exactly one message, deterministically.
+ *
+ * Blank and whitespace-only ids are dropped before the emptiness test, so
+ * `--epic-run-id ""` is "no scope supplied" rather than a scope naming a run that
+ * cannot exist — the same reading the executor's own argv parse already takes.
+ *
+ * Each surviving id is then checked for the server-minted UUID shape, and that
+ * check runs LAST: an invocation with no scope at all is told to supply one
+ * rather than being told its zero ids are malformed.
+ */
+export function validateExecutorClaimScope(input) {
+    const epicRunIds = input.epicRunIds.map((id) => id.trim()).filter((id) => id.length > 0);
+    if (input.repoWide && epicRunIds.length > 0) {
+        return { ok: false, message: EXECUTOR_CLAIM_SCOPE_MUTUALLY_EXCLUSIVE_MESSAGE };
+    }
+    if (input.repoWide)
+        return { ok: true, scope: { kind: "repo-wide" } };
+    if (epicRunIds.length === 0) {
+        return { ok: false, message: EXECUTOR_CLAIM_SCOPE_REQUIRED_MESSAGE };
+    }
+    const malformed = epicRunIds.find((id) => !isValidExecutorEpicRunId(id));
+    if (malformed !== undefined) {
+        return { ok: false, message: executorEpicRunIdRefusal(malformed) };
+    }
+    return { ok: true, scope: { kind: "epic-runs", epicRunIds } };
+}
+/**
+ * Render a validated scope as executor argv, in the executor's own flag spelling.
+ *
+ * The single place that knows how a scope becomes arguments, so the plane's lane
+ * roster cannot spell the flags differently from the executor that parses them.
+ * One `--epic-run-id <id>` PAIR per id, in the supplied order; `--repo-wide`
+ * exactly once and valueless.
+ */
+export function executorClaimScopeArgs(scope) {
+    if (scope.kind === "repo-wide")
+        return ["--repo-wide"];
+    return scope.epicRunIds.flatMap((id) => ["--epic-run-id", id]);
+}

package/build/executor/cli.js

@@ -11,6 +11,7 @@ import { VERSION } from "../version.generated.js";
 import { resolveWorktrunkBinary } from "../start-tickets-prereqs.js";
 import { resolveStartTicketsRepoName } from "../start-tickets-repo.js";
 import { DEFAULT_EXECUTOR_AGENT_ID } from "./agent-identity.js";
+import { executorEpicRunIdRefusal, isValidExecutorEpicRunId, validateExecutorClaimScope, } from "./claim-scope.js";
 import { createDefaultExecutorDeps } from "./deps.js";
 import { resolveBaseUrl, resolveExecutorApiAccess, EXECUTOR_BASE_URL_REQUIRED_MESSAGE, } from "./credentials.js";
 import { createExecutorHttpClient } from "./http-client.js";
@@ -72,17 +73,6 @@ function parseIntArg(value, flag) {
     }
     return { ok: true, value: n };
 }
-/**
- * BAPI-794 — `epic_run_id` is always server-minted as `str(uuid.uuid4())`
- * (`api/library/db/epic_runs.py`), so a standard UUID shape (any version) is a
- * cheap, safe pre-validation: it rejects an obvious typo before any credential
- * resolution or executor-loop startup, without over-constraining the CLI to a
- * version the server does not itself enforce.
- */
-const EPIC_RUN_ID_PATTERN = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
-function isValidEpicRunId(value) {
-    return EPIC_RUN_ID_PATTERN.test(value);
-}
 /** Parse the executor CLI arguments into resolved options (pure, synchronous). */
 export function parseExecutorArgs(argv, context) {
     const repos = [];
@@ -121,8 +111,11 @@ export function parseExecutorArgs(argv, context) {
             if (!v || !v.trim())
                 return { kind: "error", message: "--epic-run-id requires a value" };
             const trimmed = v.trim();
-            if (!isValidEpicRunId(trimmed)) {
-                return { kind: "error", message: `--epic-run-id has an invalid value: ${trimmed}` };
+            // BAPI-1102 — the shape rule moved to the shared claim-scope module, so
+            // `plane up` refuses the same value at ITS entry point instead of coming
+            // up and letting the lane it spawned die on the same argument.
+            if (!isValidExecutorEpicRunId(trimmed)) {
+                return { kind: "error", message: executorEpicRunIdRefusal(trimmed) };
             }
             if (!epicRunIds.includes(trimmed))
                 epicRunIds.push(trimmed);
@@ -200,18 +193,14 @@ export function parseExecutorArgs(argv, context) {
     // forever and claim nothing. Refusing to START is the loud failure that
     // replaces that silent idle: a misconfiguration is a startup error, visible
     // immediately, rather than an executor that looks healthy and does no work.
-    if (repoWide && epicRunIds.length > 0) {
-        return {
-            kind: "error",
-            message: "--repo-wide cannot be combined with --epic-run-id: pass one claim scope, not both",
-        };
-    }
-    if (!repoWide && epicRunIds.length === 0) {
-        return {
-            kind: "error",
-            message: "a claim scope is required: pass --epic-run-id <id> (repeatable) to serve " +
-                "specific epic runs, or --repo-wide to deliberately claim repository-wide",
-        };
+    //
+    // BAPI-1102 moved the rule and both messages into `./claim-scope.js` so
+    // `plane up` — which now spawns executor lanes of its own — enforces the SAME
+    // rule and renders the SAME wording, rather than carrying a second copy that
+    // drifts. The returned message is rendered VERBATIM; nothing is re-worded here.
+    const scope = validateExecutorClaimScope({ epicRunIds, repoWide });
+    if (!scope.ok) {
+        return { kind: "error", message: scope.message };
     }
     const options = {
         executorId: executorIdFinal,

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

@@ -31,6 +31,27 @@
  * all produce `ok: false`; only a second listing that shows no matching entry
  * produces `ok: true`.
  *
+ * TRACKED TEMPLATES SURVIVE (BAPI-1104, R81). The `.env.` prefix rule below is
+ * deliberately wide, and it caught this repository's own git-TRACKED
+ * `.env.example` — deleting it from every worker worktree, which showed up as a
+ * spurious dirty tree in the BAPI-1061 run. A tracked file is not an operator's
+ * environment file: it is repository content the worker is entitled to see, and
+ * its contents are already public in the checkout. So a candidate that git
+ * reports as tracked is kept, reported as `kept_tracked`, and excluded from the
+ * confirming re-list below.
+ *
+ * The exemption does NOT widen this module's reach. The lookup is a narrow seam
+ * that takes basenames and returns basenames — it never resolves, reads, or stats
+ * a path, so the symlink guarantee above is untouched. And it is best-effort by
+ * design: when the lookup fails, NOTHING is exempt and every match is stripped
+ * exactly as before. That is strictly the safer direction. The guarantee this
+ * module makes is about what reaches the worker, and it is proven by the
+ * post-removal re-list, not by knowing which files were tracked — so a failed
+ * lookup leaves the proof exactly as strong as it was and costs only the
+ * convenience the exemption was added for. Refusing the spawn instead would
+ * convert a transient git hiccup into a dead job, adding a failure mode the guard
+ * never had.
+ *
  * 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.
@@ -53,6 +74,29 @@ import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
 export function isWorkerEnvFileName(name) {
     return name === ".env" || name.startsWith(".env.");
 }
+/**
+ * True for a name safe to hand to a subprocess as a literal pathspec (BAPI-1104).
+ *
+ * `readdir` cannot produce a name containing a separator or a NUL, so in
+ * production this is already true of every candidate. It is checked anyway
+ * because the value crosses a process boundary: the property that matters —
+ * "only exact `.env`/`.env.*` root basenames ever reach git" — should be
+ * enforced at the boundary rather than inferred from what `readdir` happens to
+ * guarantee. A name that fails this is simply not exempted; it is still stripped.
+ *
+ * Shell metacharacters need no handling here and none is attempted:
+ * `deps.runCommand` is `execFile` with `shell: false`, so a name like
+ * `.env; rm -rf /` is delivered as one inert argv element and no shell ever
+ * parses it. The real (narrow) hazard is git reading a leading-dash argument as
+ * an OPTION, which the `--` pathspec separator at the call site closes — and
+ * which the `.env` prefix rule above already makes unreachable.
+ */
+function isSafePathspecBasename(name) {
+    return (isWorkerEnvFileName(name) &&
+        !name.includes("/") &&
+        !name.includes("\\") &&
+        !name.includes("\0"));
+}
 /**
  * Strip every `.env` / `.env.*` entry from a worktree ROOT and prove it worked.
  *
@@ -74,7 +118,37 @@ export async function stripWorkerEnvFiles(worktreePath, deps) {
     // 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) {
+    // BAPI-1104 — which matches are git-TRACKED repository content rather than an
+    // operator's environment file. Asked ONCE for the whole candidate set: one
+    // bounded subprocess at the last step before every worker spawn is a cost worth
+    // paying; one per `.env*` entry is not.
+    //
+    // Every value that comes back is re-intersected against `matches`. The seam is
+    // narrow but it is still a seam, and a lookup that returned a path, a nested
+    // name, or a name that was never a candidate must not be able to exempt
+    // anything — so the guard trusts the set it computed itself, not the answer.
+    let keptTracked = [];
+    const lookupCandidates = matches.filter(isSafePathspecBasename);
+    if (deps.listTrackedNames && lookupCandidates.length > 0) {
+        try {
+            const reported = await deps.listTrackedNames(worktreePath, lookupCandidates);
+            if (Array.isArray(reported)) {
+                const candidateSet = new Set(lookupCandidates);
+                keptTracked = Array.from(new Set(reported.filter((name) => typeof name === "string" && candidateSet.has(name)))).sort();
+            }
+        }
+        catch {
+            // Exempt NOTHING and continue. The guarantee is proven by the re-list
+            // below, which a failed lookup does not weaken — so stripping the tracked
+            // file too is strictly safer than refusing a spawn the guard can still
+            // confirm clean. No category, no diagnostic: the caller that owns the
+            // subprocess owns the one bounded log line about it.
+            keptTracked = [];
+        }
+    }
+    const keptSet = new Set(keptTracked);
+    const removed = matches.filter((name) => !keptSet.has(name));
+    for (const name of removed) {
         const target = pathApi.join(worktreePath, name);
         try {
             // Non-following metadata. The result is deliberately unused for a decision:
@@ -106,8 +180,13 @@ export async function stripWorkerEnvFiles(worktreePath, deps) {
     catch {
         return { ok: false, category: "verification_listing_failed" };
     }
-    if (remaining.some(isWorkerEnvFileName)) {
+    // A KEPT tracked name is an expected survivor, not a failure. Without this the
+    // exemption would be self-defeating: the re-list would see the `.env.example`
+    // it deliberately preserved and refuse the spawn with `entry_survived`.
+    if (remaining.some((name) => isWorkerEnvFileName(name) && !keptSet.has(name))) {
         return { ok: false, category: "entry_survived" };
     }
-    return { ok: true, removed: matches };
+    return keptTracked.length > 0
+        ? { ok: true, removed, kept_tracked: keptTracked }
+        : { ok: true, removed };
 }

package/build/executor/job-runner.js

@@ -48,6 +48,23 @@ import { buildPrBaseContractLaunchInstruction } from "../pr-base-contract.js";
 import { resolveExecutorPrompt, resolveWorkerPermissionPosture, } from "./worker-command.js";
 import { collectGitTelemetry, collectRemoteTrackingSha, createMcpSurfaceObserver, evaluatePreSpawnGitVerification, formatWorkerRateLimitAdvisory, normalizeMcpServerNames, } from "./observation.js";
 import { isRecognizedServerName, MCP_SERVER_NAME } from "../mcp-identity.js";
+/**
+ * Bound on the pre-spawn git tracked-file lookup (BAPI-1104, R81).
+ *
+ * This runs at the LAST step before every worker spawn, so a hung `git ls-files`
+ * would stall spawning rather than merely delay one exemption. Five seconds is
+ * far beyond what an index read of a handful of pathspecs takes, and a timeout
+ * degrades to "exempt nothing" rather than to a refusal.
+ */
+const ENV_FILE_TRACKED_LOOKUP_TIMEOUT_MS = 5_000;
+/**
+ * The ONE fixed line emitted when that lookup fails. No path (a worktree path
+ * carries an operator's username), no filename, no errno, no command output, no
+ * exception text — the same bar `WORKER_ENV_FILE_PRESENT_MESSAGE` and the guard's
+ * closed categories hold. It is advisory: the spawn proceeds, with nothing
+ * exempted.
+ */
+const ENV_FILE_TRACKED_LOOKUP_FAILED_MESSAGE = "[executor] tracked env-file lookup unavailable; exempting nothing";
 /** Default runtime for the no-op smoke process (ms). */
 const DEFAULT_SMOKE_DURATION_MS = 100;
 /** ProcessClassification maps 1:1 onto the wire ExecutorClassification. */
@@ -1599,6 +1616,49 @@ async function runPreparedSpawn(params) {
         // enforcement: no `stat`, `readlink`, or `readFile` is reachable from here.
         lstat: (target) => lstat(target),
         unlink: (target) => unlink(target),
+        // BAPI-1104 (R81): which candidates git reports as TRACKED. This repository's
+        // own `.env.example` is tracked content, not an operator's environment file,
+        // and the `.env.` prefix rule was deleting it from every worker worktree.
+        //
+        // `deps.runCommand` is `execFile` with `shell: false`, so the basenames are
+        // delivered as inert argv elements and no shell parses them. `--` is
+        // mandatory: it stops git reading any argument as an option (unreachable for
+        // `.env*` names, but the separator is what makes that a property rather than
+        // an argument). `--error-unmatch` is deliberately NOT used — it exits 1 and
+        // prints nothing for the WHOLE invocation as soon as one pathspec is
+        // untracked, so on the mixed tracked/untracked worktree this feature exists
+        // for it would silently report "nothing is tracked" and delete the
+        // `.env.example` anyway. Plain `ls-files` lists only tracked paths and exits
+        // zero, so the tracked subset falls out of stdout directly.
+        listTrackedNames: async (root, candidates) => {
+            let result;
+            try {
+                result = await deps.runCommand("git", ["ls-files", "-z", "--", ...candidates], { cwd: root, timeoutMs: ENV_FILE_TRACKED_LOOKUP_TIMEOUT_MS });
+            }
+            catch {
+                // `runCommand` surfaces a non-zero exit as `exitCode` rather than
+                // throwing, so reaching here means the process could not be run at all.
+                deps.errorLog(ENV_FILE_TRACKED_LOOKUP_FAILED_MESSAGE);
+                return [];
+            }
+            if (result.exitCode !== 0 || typeof result.stdout !== "string") {
+                // Fail-OPEN into "nothing is exempt": the guard then strips every match,
+                // which is strictly safer than refusing a spawn it can still confirm
+                // clean. One fixed line, and nothing from the command in it — stdout
+                // would carry worktree-relative paths and stderr an errno.
+                deps.errorLog(ENV_FILE_TRACKED_LOOKUP_FAILED_MESSAGE);
+                return [];
+            }
+            // NUL-delimited, never logged. Filtered to the exact candidate set here as
+            // well as in the guard: the seam's contract is basenames-in / basenames-out
+            // restricted to what was asked about, and a producer that honors its own
+            // contract is easier to reason about than one that relies on its consumer
+            // to clean up after it. The guard's re-intersection stays the enforcement.
+            const asked = new Set(candidates);
+            return result.stdout
+                .split("\0")
+                .filter((name) => name.length > 0 && asked.has(name));
+        },
         platform: deps.platform,
     });
     if (!stripped.ok) {