@bridge_gpt/mcp-server 0.2.53 → 0.2.55

package/build/epic-implementer-bundle-cli.js

@@ -0,0 +1,264 @@
+/**
+ * BAPI-634: thin CLI handler exposing the deterministic conductor-bundle helpers
+ * to `emit-conductor-bundle.md`.
+ *
+ * Why this exists: the instruction ships **compiled** to consuming repositories
+ * inside `build/pipelines.generated.js`. `mcp_server/src/` does not exist there,
+ * so an instruction that told the agent to "call `validateConductorBundleInputs`"
+ * would be referencing a path only this repository has. This subcommand is the
+ * reachable surface, mirroring how `store-and-approve-epic-plan.md` invokes
+ * `setup-epic` rather than hand-rolling HTTP calls.
+ *
+ * It holds no policy of its own: it parses argv, delegates to
+ * `conductor-bundle-artifacts.ts`, and prints a JSON envelope. All I/O is behind
+ * an injectable seam so tests never touch a real disk or construct a server.
+ *
+ * S4 (BAPI-1080): this file and its exported public surface were renamed from
+ * `conductor-bundle-cli.ts` (`emit-conductor-bundle` -> `emit-epic-implementer-bundle`).
+ * The delegated artifact helper module below, `conductor-bundle-artifacts.ts`
+ * (and its `validateConductorBundleInputs` export), intentionally keeps its
+ * current name — deferred to a later slice.
+ */
+import path from "node:path";
+import { finalizeEpicPlanSidecar, serializeSiblingTicketManifest, validateConductorBundleInputs, writeJsonAtomically, } from "./conductor-bundle-artifacts.js";
+const USAGE = [
+    "Usage: emit-epic-implementer-bundle <validate|finalize> --input <file> [--docs-dir <dir>] [--json]",
+    "",
+    "  validate   Validate identities, the node->ticket mapping, manifest agreement,",
+    "             and path containment. Writes nothing.",
+    "  finalize   Validate, then finalize epic-plan.dag.json with real keys and",
+    "             per-node touched_files, and write the sibling-ticket manifest.",
+    "",
+    "Options:",
+    "  --input <file>     JSON document with epic_key, epic_slug, mappings,",
+    "                     decomposition_fingerprint, and (for finalize)",
+    "                     touched_files_by_key.",
+    "  --docs-dir <dir>   Docs directory (default: $BAPI_DOCS_DIR, else docs/tmp).",
+    "  --json             Emit a machine-readable result on stdout.",
+    "  -h, --help         Show this help.",
+].join("\n");
+/** Read a flag's value, rejecting a missing or flag-shaped value. */
+function takeValue(argv, index, flag) {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("-")) {
+        throw new Error(`Flag "${flag}" requires a value.`);
+    }
+    return value;
+}
+/** Parse argv into options, or throw with an actionable message. */
+export function parseEpicImplementerBundleArgs(argv) {
+    const mode = argv[0];
+    if (mode === "-h" || mode === "--help" || mode === undefined) {
+        return { mode: "validate", inputFile: "", json: false, help: true };
+    }
+    if (mode !== "validate" && mode !== "finalize") {
+        throw new Error(`Unknown subcommand "${mode}". Expected "validate" or "finalize".`);
+    }
+    let inputFile;
+    let docsDir;
+    let json = false;
+    let help = false;
+    for (let i = 1; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--input":
+                inputFile = takeValue(argv, i, "--input");
+                i++;
+                break;
+            case "--docs-dir":
+                docsDir = takeValue(argv, i, "--docs-dir");
+                i++;
+                break;
+            case "--json":
+                json = true;
+                break;
+            case "-h":
+            case "--help":
+                help = true;
+                break;
+            default:
+                throw new Error(`Unknown argument "${arg}".`);
+        }
+    }
+    if (help)
+        return { mode, inputFile: inputFile ?? "", docsDir, json, help: true };
+    if (!inputFile)
+        throw new Error('Flag "--input" is required.');
+    return { mode, inputFile, docsDir, json, help: false };
+}
+/** Parse JSON, converting a syntax error into an actionable message. */
+async function readJson(filePath, fs, label) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath);
+    }
+    catch (err) {
+        throw new Error(`Could not read ${label} at ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${label} at ${filePath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Read an optional JSON file, returning null when it does not exist. */
+async function readOptionalJson(filePath, fs, label) {
+    try {
+        await fs.readFile(filePath);
+    }
+    catch {
+        return null;
+    }
+    return readJson(filePath, fs, label);
+}
+/**
+ * Run the `emit-epic-implementer-bundle` subcommand. Returns a process exit
+ * code; never throws for an expected validation failure.
+ *
+ * S4 (BAPI-1080): renamed from `runConductorBundleCli`.
+ */
+export async function runEpicImplementerBundleCli(argv, overrides = {}) {
+    const deps = {
+        env: process.env,
+        cwd: process.cwd(),
+        fs: createDefaultBundleFs(),
+        log: (m) => console.log(m),
+        // Diagnostics go to stderr so `--json` keeps stdout a single result object.
+        errorLog: (m) => console.error(m),
+        ...overrides,
+    };
+    let opts;
+    try {
+        opts = parseEpicImplementerBundleArgs(argv);
+    }
+    catch (err) {
+        deps.errorLog(err instanceof Error ? err.message : String(err));
+        deps.errorLog(USAGE);
+        return 1;
+    }
+    if (opts.help) {
+        deps.log(USAGE);
+        return 0;
+    }
+    const emitFailure = (error) => {
+        if (opts.json)
+            deps.log(JSON.stringify({ ok: false, error }));
+        else
+            deps.errorLog(`Error: ${error}`);
+        return 1;
+    };
+    const docsDir = path.resolve(deps.cwd, opts.docsDir ?? deps.env.BAPI_DOCS_DIR ?? path.join("docs", "tmp"));
+    let input;
+    try {
+        input = (await readJson(path.resolve(deps.cwd, opts.inputFile), deps.fs, "--input document"));
+    }
+    catch (err) {
+        return emitFailure(err instanceof Error ? err.message : String(err));
+    }
+    if (!input || typeof input !== "object") {
+        return emitFailure("--input document must be a JSON object.");
+    }
+    const epicDir = path.resolve(docsDir, "epic-plans", String(input.epic_slug));
+    const sidecarPath = path.join(epicDir, "epic-plan.dag.json");
+    const manifestPath = path.join(epicDir, "sibling-ticket-manifest.json");
+    let sidecar;
+    let existingManifest;
+    try {
+        sidecar = await readJson(sidecarPath, deps.fs, "epic-plan.dag.json");
+        existingManifest = await readOptionalJson(manifestPath, deps.fs, "sibling-ticket-manifest.json");
+    }
+    catch (err) {
+        return emitFailure(err instanceof Error ? err.message : String(err));
+    }
+    const validation = await validateConductorBundleInputs({
+        epic_key: input.epic_key,
+        epic_slug: input.epic_slug,
+        docs_dir: docsDir,
+        mappings: input.mappings,
+        sidecar,
+        existing_manifest: existingManifest ?? undefined,
+        decomposition_fingerprint: input.decomposition_fingerprint,
+    }, deps.fs);
+    if (!validation.ok)
+        return emitFailure(validation.error);
+    if (opts.mode === "validate") {
+        const result = {
+            ok: true,
+            mode: "validate",
+            epic_key: validation.value.epic_key,
+            plan_version: validation.value.plan_version,
+            mapped_nodes: validation.value.mappings.length,
+            sidecar_path: validation.value.sidecar_path,
+        };
+        if (opts.json)
+            deps.log(JSON.stringify(result));
+        else {
+            deps.log(`Validated ${result.mapped_nodes} node mapping(s) for ${result.epic_key} ` +
+                `(plan v${result.plan_version}). Nothing was written.`);
+        }
+        return 0;
+    }
+    // ---- finalize ----------------------------------------------------------
+    const nodeKeyMap = {};
+    for (const m of validation.value.mappings) {
+        nodeKeyMap[m.plan_node_id] = m.ticket_key;
+    }
+    const finalized = finalizeEpicPlanSidecar({
+        sidecar,
+        node_key_map: nodeKeyMap,
+        touched_files_by_key: input.touched_files_by_key ?? {},
+        plan_version_already_stored: input.plan_version_already_stored === true,
+    });
+    if (!finalized.ok)
+        return emitFailure(finalized.error);
+    const sidecarWrite = await writeJsonAtomically(validation.value.sidecar_path, finalized.value, deps.fs);
+    if (!sidecarWrite.ok)
+        return emitFailure(sidecarWrite.error);
+    const manifest = serializeSiblingTicketManifest({
+        schema_version: 1,
+        epic_key: validation.value.epic_key,
+        epic_slug: validation.value.epic_slug,
+        plan_version: validation.value.plan_version,
+        decomposition_fingerprint: input.decomposition_fingerprint,
+        finalized_fingerprint: null,
+        run_phase: input.run_phase ?? "staged",
+        mappings: validation.value.mappings.map((m) => ({
+            plan_node_id: m.plan_node_id,
+            ticket_key: m.ticket_key,
+            exploration_path: m.exploration_path,
+            draft_path: m.draft_path,
+        })),
+        decisions: [],
+        completed_mutations: [],
+    });
+    const manifestWrite = await writeJsonAtomically(validation.value.manifest_path, manifest, deps.fs);
+    if (!manifestWrite.ok)
+        return emitFailure(manifestWrite.error);
+    const result = {
+        ok: true,
+        mode: "finalize",
+        epic_key: validation.value.epic_key,
+        plan_version: validation.value.plan_version,
+        sidecar_path: validation.value.sidecar_path,
+        manifest_path: validation.value.manifest_path,
+        ticket_keys: validation.value.mappings.map((m) => m.ticket_key),
+    };
+    if (opts.json)
+        deps.log(JSON.stringify(result));
+    else {
+        deps.log(`Finalized ${result.sidecar_path} with ${result.ticket_keys.length} real key(s) ` +
+            `and per-node touched_files. Manifest: ${result.manifest_path}`);
+    }
+    return 0;
+}
+/** Real filesystem seam, loaded lazily so importing this module stays cheap. */
+function createDefaultBundleFs() {
+    return {
+        readFile: async (p) => (await import("node:fs/promises")).readFile(p, "utf-8"),
+        writeFile: async (p, data) => (await import("node:fs/promises")).writeFile(p, data, "utf-8"),
+        rename: async (from, to) => (await import("node:fs/promises")).rename(from, to),
+        unlink: async (p) => (await import("node:fs/promises")).unlink(p),
+        realpath: async (p) => (await import("node:fs/promises")).realpath(p),
+    };
+}

package/build/epic-implementer-claude-hook-bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import path from"node:path";import{fileURLToPath}from"node:url";import{spawnSync}from"node:child_process";import{readFileSync}from"node:fs";var CONDUCTOR_HOOK_EMIT_FAILED_WARNING="Warning: conductor hook emit failed.";function resolveClaudeHookEventName(payload){if(payload===null||typeof payload!="object"||Array.isArray(payload))return null;let record=payload,candidates=["hook_event_name","hookEventName","event_name","event"];for(let key of candidates){let value=record[key];if(typeof value=="string"&&value.trim().length>0)return value.trim()}return null}function mapClaudeHookEventToSemanticType(eventName){switch(eventName){case"SessionStart":return"run.started";case"SessionEnd":return"run.stopped";case"Stop":return null;case"SubagentStop":return null;case"Notification":return"agent.notification";case"PreToolUse":return"tool.intent";default:return null}}var REQUIRED_IDENTITY_ENV=["BAPI_CONDUCTOR_RUN_ID","BAPI_CONDUCTOR_WORKER_ID","BAPI_CONDUCTOR_TICKET_KEY","BAPI_CONDUCTOR_WORKTREE_PATH"];function nonEmpty(value){return typeof value=="string"&&value.trim().length>0}function buildClaudeHookConductorEvent(payload,env){let eventName=resolveClaudeHookEventName(payload),type=mapClaudeHookEventToSemanticType(eventName);if(type===null||env.BAPI_CONDUCTOR_ENABLED!=="1")return null;for(let key of REQUIRED_IDENTITY_ENV)if(!nonEmpty(env[key]))return null;let ticketKey=env.BAPI_CONDUCTOR_TICKET_KEY.trim(),worktreePath=env.BAPI_CONDUCTOR_WORKTREE_PATH.trim(),details={ticket_key:ticketKey,worktree_path:worktreePath};nonEmpty(env.BAPI_CONDUCTOR_REPO_NAME)&&(details.repo=env.BAPI_CONDUCTOR_REPO_NAME.trim());let raw=payload!==null&&typeof payload=="object"&&!Array.isArray(payload)?payload:{payload};return{source:"claude-code",type,subject:ticketKey,run_id:env.BAPI_CONDUCTOR_RUN_ID.trim(),worker_id:env.BAPI_CONDUCTOR_WORKER_ID.trim(),producer:"claude-code-hook",observed_via:"claude-code-hook",data:{details,raw}}}function buildConductorEmitEventArgs(event){let args=["--type",event.type,"--source",event.source];return nonEmpty(event.subject??void 0)&&args.push("--subject",event.subject),nonEmpty(event.run_id??void 0)&&args.push("--run-id",event.run_id),nonEmpty(event.worker_id??void 0)&&args.push("--worker-id",event.worker_id),nonEmpty(event.producer??void 0)&&args.push("--producer",event.producer),nonEmpty(event.observed_via??void 0)&&args.push("--observed-via",event.observed_via),args.push("--data-json-stdin","--json"),args}function resolveConductorEmitCommand(env,emitArgs){let cliFile=env.BAPI_CONDUCTOR_CLI_FILE;return nonEmpty(cliFile)?{command:process.execPath,args:[cliFile.trim(),"emit-event",...emitArgs]}:{command:nonEmpty(env.BAPI_CONDUCTOR_BIN)?env.BAPI_CONDUCTOR_BIN.trim():"epic-implementer",args:["emit-event",...emitArgs]}}var defaultConductorSpawn=(command,args,input)=>{let result=spawnSync(command,args,{input,encoding:"utf-8",shell:!1});return{status:result.status,error:result.error}};function emitClaudeHookEventWithConductorCli(event,deps={}){let env=deps.env??process.env,spawn=deps.spawn??defaultConductorSpawn,emitArgs=buildConductorEmitEventArgs(event),{command,args}=resolveConductorEmitCommand(env,emitArgs),stdinPayload=JSON.stringify(event.data??{});try{let result=spawn(command,args,stdinPayload);return result.error?!1:result.status===0}catch{return!1}}function runClaudeConductorHookCli(deps={}){let env=deps.env??process.env,readStdin=deps.readStdin??(()=>readStdinSync()),warn=deps.warn??(m=>process.stderr.write(`${m}
+`)),payload;try{let raw=readStdin();payload=JSON.parse(raw)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}let event;try{event=buildClaudeHookConductorEvent(payload,env)}catch{return warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}return event===null||emitClaudeHookEventWithConductorCli(event,{env,spawn:deps.spawn})||warn(CONDUCTOR_HOOK_EMIT_FAILED_WARNING),0}function readStdinSync(){return readFileSync(0,"utf-8")}function runEpicImplementerClaudeHookBin(deps={}){let handler=deps.handler??runClaudeConductorHookCli,exit=deps.exit??process.exit.bind(process),exitCode=0;try{exitCode=handler()}catch{exitCode=0}exit(exitCode)}var invokedDirectly=process.argv[1]!==void 0&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url);invokedDirectly&&runEpicImplementerClaudeHookBin();export{runEpicImplementerClaudeHookBin};

package/build/epic-integration-pr.js

@@ -30,9 +30,11 @@ export const EPIC_BRANCH_PREFIX = "epic/";
 /** The production call sites this helper is invoked from. */
 export const EPIC_INTEGRATION_PR_COMMANDS = [
     "setup-epic",
-    "conduct-epic init",
-    "conduct-epic catch-up",
-    "conduct-epic finish",
+    // S4 (BAPI-1080): renamed from "conduct-epic init" / "conduct-epic catch-up"
+    // / "conduct-epic finish".
+    "implement-epic init",
+    "implement-epic catch-up",
+    "implement-epic finish",
     "executor merge",
     // BAPI-1010: the executor's one-shot wind-down observer, distinct from
     // "executor merge" so the generated PR body and diagnostics never mislabel

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/env.js

@@ -53,6 +53,7 @@
  * (`Read(~/.config/bridge/**)` in `permissions.ts`).
  */
 import { PR_BASE_BRANCH_ENV_VAR, WORKER_BRANCH_ENV_VAR } from "../pr-base-contract.js";
+import { DECLARED_TOUCHED_FILES_ENV, normalizeDeclaredTouchedFiles, } from "../conductor/file-scope-guard.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 = [
@@ -232,6 +233,11 @@ export function buildExecutorBaseWorkerEnv(parentEnv, options = {}) {
     if (indexScope !== undefined) {
         env[INDEX_SCOPE_ENV_VAR] = indexScope;
     }
+    // BAPI-1152 — normalized through the guard's own normalizer, so an unsafe path
+    // (absolute, `..`) in the declaration is dropped rather than widening the scope.
+    if (Array.isArray(options.declaredTouchedFiles)) {
+        env[DECLARED_TOUCHED_FILES_ENV] = JSON.stringify(normalizeDeclaredTouchedFiles(options.declaredTouchedFiles));
+    }
     // Nothing agent-specific is added here, and deliberately nothing secret. An
     // adapter that needs to forward an operator-owned credential declares it as a
     // passthrough and copies it onto the object this function returns; see

package/build/executor/interrupted-worktree.js

@@ -0,0 +1,60 @@
+/**
+ * Cleanup after a worker is interrupted — timed out or killed (BAPI-1152).
+ *
+ * In the BAPI-1111 run an implement worker was SIGTERMed at its wall-clock
+ * timeout while git held the index lock. The stale `index.lock` it left behind
+ * made the NEXT job's `git reset --hard` fail with `WorktreeError`, and the
+ * worktree only recovered through crashed-job recovery. This removes that residue
+ * the moment the executor knows the worker is gone.
+ *
+ * Scope is deliberately narrow, and the narrowness is the point (accepted review
+ * decision): for EVERY spawn job this only removes a stale `index.lock` and aborts
+ * an in-progress merge. It never hard-resets. A `resume` continues committed
+ * progress from a prior attempt and an implement worker may hold valid local
+ * commits when it times out — resetting them would destroy exactly the work the
+ * recovery path exists to keep. Only `reconcile_overlap`, whose anchor is its
+ * dispatch-time child head, additionally resets, through its own driver.
+ *
+ * Called ONLY after the worker process's `wait()` has resolved, i.e. after the
+ * executor has observed the child exit (after the termination controller's
+ * SIGTERM grace period and any SIGKILL). A lock held by a git grandchild that
+ * outlived the worker is not distinguishable from a stale one by this check —
+ * a known limit, stated rather than papered over; the worker's own git commands
+ * are short-lived, so the window is small. Never throws.
+ */
+import path from "node:path";
+const GIT_TIMEOUT_MS = 30_000;
+export async function cleanupInterruptedWorktree(worktreePath, seams) {
+    const outcome = { removedIndexLock: false, abortedMerge: false };
+    try {
+        const gitDir = await seams.runCommand("git", ["rev-parse", "--absolute-git-dir"], {
+            cwd: worktreePath,
+            timeoutMs: GIT_TIMEOUT_MS,
+        });
+        const dir = gitDir.stdout.trim();
+        if (gitDir.exitCode === 0 && dir.length > 0 && path.isAbsolute(dir)) {
+            try {
+                await seams.removeFile(path.join(dir, "index.lock"));
+                outcome.removedIndexLock = true;
+            }
+            catch {
+                // Absent is the common case and is not an error.
+            }
+        }
+        const mergeHead = await seams.runCommand("git", ["rev-parse", "-q", "--verify", "MERGE_HEAD"], {
+            cwd: worktreePath,
+            timeoutMs: GIT_TIMEOUT_MS,
+        });
+        if (mergeHead.exitCode === 0) {
+            const aborted = await seams.runCommand("git", ["merge", "--abort"], {
+                cwd: worktreePath,
+                timeoutMs: GIT_TIMEOUT_MS,
+            });
+            outcome.abortedMerge = aborted.exitCode === 0;
+        }
+    }
+    catch {
+        seams.errorLog("[executor] interrupted-worktree cleanup could not complete; the next preparation resets it");
+    }
+    return outcome;
+}