@bridge_gpt/mcp-server 0.2.54 → 0.2.55

package/build/executor/job-runner.js

@@ -40,6 +40,8 @@ import { acquireExecutorWorktreeLock, } from "./worktree-lock.js";
 import { activateJobLog, deactivateJobLog, registerExecutorJobLog, markExecutorJobLogFinished, } from "./job-log-registry.js";
 import { executorViewerTabsEnabled, openExecutorViewerTab } from "./viewer-tabs.js";
 import { isImplementationStyleJobType, isRecoveryJobType, isSpawnJobType } from "./job-types.js";
+import { cleanupInterruptedWorktree } from "./interrupted-worktree.js";
+import { lazyProviderCheckPoller, runReconcileOverlapJob, } from "./reconcile-overlap-job.js";
 import { resolveExecutorJobBaseBranch } from "./base-branch.js";
 import { resolveExecutorJobIndexScope } from "./index-scope.js";
 import { validateWorkerFinalization } from "./worker-finalization.js";
@@ -613,6 +615,21 @@ control) {
     if (job.job_type === "smoke") {
         return runSmokeJob(job, httpClient, options, deps, ownership, observation, control);
     }
+    // BAPI-1152: `reconcile_overlap` takes its OWN branch, after `merge`/`smoke`
+    // and before the generic spawn path. It needs a prepared, locked worktree like
+    // a spawn job, but its body is the reconcile module's state machine: the
+    // payload is validated there BEFORE any subprocess, and the worker — when one
+    // is needed at all — is launched through the SAME locked `runSpawnJob` path
+    // via a driver, so there is still exactly one worker spawn boundary.
+    if (job.job_type === "reconcile_overlap") {
+        return await runReconcileOverlapJob(job, {
+            fail: async (failure) => {
+                await httpClient.fail(job, failure);
+                return { status: "failed", reason: "reconcile_overlap_payload" };
+            },
+            runLockedSpawn: (driver) => runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, control, driver),
+        }, buildReconcileOverlapSeams(deps));
+    }
     // `implement`/`resume`/`spec_review` and the recovery jobs (`remediate`/
     // `ci_fix`/`rebase`) all run through the real headless-spawn path — dispatched
     // via the shared `isSpawnJobType` policy (`job-types.ts`) AFTER the dedicated
@@ -646,6 +663,18 @@ control) {
  * from the supervised `ProcessRunResult`/`ownership`, not from this adapter).
  */
 function createMergeFlowProcess(startMerge) {
+    const flow = createFlowProcess(startMerge, (result) => result.ok);
+    return { proc: flow.proc, getOutcome: flow.getOutcome, getError: flow.getError };
+}
+/**
+ * The generic form of {@link createMergeFlowProcess} (BAPI-1152): adapt any
+ * in-process flow into an {@link OwnedChildProcess} so it is supervised by the
+ * SAME heartbeat/deadman/timeout path as a worker. `settled` resolves once the
+ * flow's own promise has settled — after a timeout or kill the supervised
+ * process resolves immediately, but the flow may still be finishing a bounded
+ * subprocess, and a caller that is about to reset the worktree must wait for it.
+ */
+function createFlowProcess(start, isOk) {
     const controller = new AbortController();
     let outcome;
     let error;
@@ -654,12 +683,12 @@ function createMergeFlowProcess(startMerge) {
     const waitPromise = new Promise((resolve) => {
         settleWait = resolve;
     });
-    // Start the merge flow immediately; capture its resolution/rejection.
-    startMerge(controller.signal).then((result) => {
+    // Start the flow immediately; capture its resolution/rejection.
+    const settled = start(controller.signal).then((result) => {
         outcome = result;
         if (!done) {
             done = true;
-            settleWait({ exitCode: result.ok ? 0 : 1, signal: null });
+            settleWait({ exitCode: isOk(result) ? 0 : 1, signal: null });
         }
     }, (err) => {
         error = err;
@@ -687,6 +716,7 @@ function createMergeFlowProcess(startMerge) {
         proc,
         getOutcome: () => outcome,
         getError: () => error,
+        settled,
     };
 }
 /**
@@ -884,6 +914,131 @@ async function runSmokeJob(job, httpClient, options, deps, ownership, observatio
     }, job, control);
     return terminalToRunResult(terminal, "completed");
 }
+/** Build the reconcile module's seams from executor deps (BAPI-1152). */
+function buildReconcileOverlapSeams(deps) {
+    return {
+        runCommand: deps.runCommand,
+        readFile: deps.readFile,
+        writeFile: deps.writeFile,
+        mkdir: deps.mkdir,
+        now: deps.now,
+        sleep: deps.sleep,
+        env: deps.env,
+        pollProviderChecks: lazyProviderCheckPoller({
+            env: deps.env,
+            cwd: deps.cwd,
+            homedir: deps.homedir,
+            platform: deps.platform,
+            readFile: deps.readFile,
+            stat: deps.stat,
+        }),
+        errorLog: deps.errorLog,
+    };
+}
+/** Bound on waiting for an aborted driver phase to finish its in-flight command. */
+const DRIVER_PHASE_SETTLE_MAX_MS = 240_000;
+/**
+ * Run one driver phase under the SAME heartbeat/deadman/timeout supervision a
+ * worker gets (BAPI-1152). A deterministic phase can run for many minutes — local
+ * verification commands, a CI wait — and without heartbeats the janitor would
+ * re-queue a healthy job. On a timeout or a lost claim the phase is aborted and
+ * then AWAITED (bounded) before returning, so the caller never resets the
+ * worktree underneath a git command the phase is still running.
+ */
+async function superviseDriverPhase(params) {
+    const flow = createFlowProcess(params.run, () => true);
+    const procResult = await superviseProcess({
+        job: params.job,
+        httpClient: params.httpClient,
+        options: params.options,
+        deps: params.deps,
+        ownership: params.ownership,
+        observation: params.observation,
+        proc: flow.proc,
+        timeoutSeconds: Math.max(1, params.timeoutSeconds),
+        collectTelemetry: params.collectTelemetry,
+        control: params.control,
+    });
+    await Promise.race([flow.settled, params.deps.sleep(DRIVER_PHASE_SETTLE_MAX_MS)]);
+    if (procResult.serverStopRequested)
+        return { kind: "server_stop" };
+    if (params.ownership.abandoned)
+        return { kind: "abandoned" };
+    if (procResult.classification === "timeout")
+        return { kind: "timeout" };
+    const error = flow.getError();
+    if (error !== undefined)
+        return { kind: "error", error };
+    const value = flow.getOutcome();
+    if (value === undefined)
+        return { kind: "error", error: new Error("driver phase produced no outcome") };
+    return { kind: "result", value };
+}
+/** Report a driver's terminal decision through the shared terminal-mutation path. */
+async function reportDriverOutcome(outcome, ctx) {
+    if (outcome.kind === "complete") {
+        const completion = {
+            job_type: ctx.job.job_type,
+            exit_code: 0,
+            classification: "clean_exit",
+            result: outcome.result,
+            // ONLY a pushed head is reported: the server binds `last_commit_sha` as the
+            // job's produced head, and a job that pushed nothing produced none.
+            ...(outcome.lastCommitSha ? { last_commit_sha: outcome.lastCommitSha } : {}),
+            telemetry: ctx.observation.snapshot(),
+        };
+        const terminal = await sendTerminalMutationWithAuthReport({
+            kind: "complete",
+            send: () => ctx.httpClient.complete(ctx.job, completion),
+            deps: ctx.deps,
+            options: ctx.options,
+            ownership: ctx.ownership,
+            log: ctx.deps.log,
+        }, ctx.job, ctx.control);
+        return terminalToRunResult(terminal, "completed");
+    }
+    const terminal = await sendTerminalMutationWithAuthReport({
+        kind: "fail",
+        send: () => ctx.httpClient.fail(ctx.job, { ...outcome.failure, telemetry: ctx.observation.snapshot() }),
+        deps: ctx.deps,
+        options: ctx.options,
+        ownership: ctx.ownership,
+        log: ctx.deps.log,
+    }, ctx.job, ctx.control);
+    return terminalToRunResult(terminal, "failed");
+}
+/** Restore the worktree and report a driver phase that did not finish. */
+async function reportDriverPhaseInterruption(phase, ctx) {
+    await ctx.driver.abandon(ctx.driverBaseContext);
+    if (phase.kind === "abandoned") {
+        return { status: "abandoned", reason: ctx.ownership.abandonReason };
+    }
+    if (phase.kind === "server_stop") {
+        await ctx.httpClient.fail(ctx.job, {
+            error_kind: "ServerStopRequested",
+            error_message: "the server requested this run stop; the reconciliation was stopped",
+            classification: "killed",
+            telemetry: ctx.observation.snapshot(),
+        });
+        ctx.ownership.abandoned = true;
+        ctx.ownership.abandonReason = "server_stop";
+        return { status: "abandoned", reason: "server_stop" };
+    }
+    return await reportDriverOutcome({
+        kind: "fail",
+        failure: phase.kind === "timeout"
+            ? {
+                error_kind: "Timeout",
+                error_message: `${ctx.job.job_type} phase exceeded the job timeout`,
+                classification: "timeout",
+            }
+            : {
+                error_kind: "WorkerCrashed",
+                error_message: `${ctx.job.job_type} phase failed: ${secretFreeErrorMessage(phase.error)}`,
+                classification: "crashed",
+            },
+    }, ctx);
+}
 /**
  * BAPI-862: the payload key the reconciler stamps with the implement gate's last
  * observation reason code. Server-minted and opaque to the executor beyond the
@@ -1048,7 +1203,13 @@ async function prepareSpawn(job, httpClient, options, deps, seams) {
  * returns BEFORE either the deny layer or MCP provisioning runs — neither ever
  * touches a worktree that will not become a runnable worker.
  */
-async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, control) {
+async function runSpawnJob(job, httpClient, options, deps, ownership, observation, seams, control, 
+/**
+ * BAPI-1152: an optional spawn-job driver (`reconcile_overlap`). It runs inside
+ * the SAME lock and the SAME prepared-spawn path as every other spawn job, so it
+ * adds no second worktree entry and no second worker launcher.
+ */
+driver) {
     // --- Per-job base branch (BAPI-586) ----------------------------------
     // Resolve the effective logical base BEFORE any side effect: the persisted
     // run base (`payload.base_branch`) is authoritative, falling back to the
@@ -1239,6 +1400,7 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
             adapter,
             control,
             lifecycle: spawnLifecycle,
+            driver,
         });
     }
     finally {
@@ -1273,12 +1435,12 @@ async function runSpawnJob(job, httpClient, options, deps, ownership, observatio
  * rather than a 500-line indentation nobody can verify by eye.
  */
 async function runPreparedSpawn(params) {
-    const { job, httpClient, options, jobOptions, deps, ownership, observation, seams, worktreePath, branch, prep, effectiveBaseBranch, indexScope, permissionPosture, adapter, control, lifecycle, } = params;
+    const { job, httpClient, options, jobOptions, deps, ownership, observation, seams, worktreePath, branch, prep, effectiveBaseBranch, indexScope, permissionPosture, adapter, control, lifecycle, driver, } = params;
     // BAPI-586: PR-producing spawn jobs (implement/resume/remediate/ci_fix/rebase)
     // are told to open the PR against the injected run base. Verdict-only
     // `spec_review` produces no PR, so it is excluded from the instruction while
     // still using the pinned base for its fresh worktree.
-    const prompt = isImplementationStyleJobType(job.job_type)
+    let prompt = isImplementationStyleJobType(job.job_type)
         ? `${prep.prompt} ${buildPrBaseContractLaunchInstruction()}`
         : prep.prompt;
     // --- Timeout contract ------------------------------------------------
@@ -1291,6 +1453,49 @@ async function runPreparedSpawn(params) {
         });
         return { status: "failed", reason: "timeout_contract" };
     }
+    // --- Spawn-job driver: the pre-worker phase (BAPI-1152) --------------
+    // Runs INSIDE the lock and before every worker-owned side effect. A driver may
+    // finish the whole job here (a clean, green reconciliation pushes with no
+    // worker at all), or hand back the ONE worker it needs and the pre-spawn state
+    // it has already proven. The job's overall timeout budget spans every phase.
+    const jobDeadlineMs = deps.now() + timeout.timeoutSeconds * 1000;
+    const remainingMs = () => Math.max(0, jobDeadlineMs - deps.now());
+    const driverBaseContext = {
+        worktreePath,
+        branch,
+        preparedHeadSha: prep.expectedHeadSha,
+        effectiveBaseBranch,
+    };
+    const driverTelemetry = () => collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
+    let driverStep;
+    if (driver) {
+        const phase = await superviseDriverPhase({
+            job,
+            httpClient,
+            options: jobOptions,
+            deps,
+            ownership,
+            observation,
+            control,
+            timeoutSeconds: Math.ceil(remainingMs() / 1000),
+            collectTelemetry: driverTelemetry,
+            run: (signal) => driver.beforeWorker({ ...driverBaseContext, signal, remainingMs }),
+        });
+        if (phase.kind !== "result") {
+            return await reportDriverPhaseInterruption(phase, {
+                job, httpClient, options, deps, ownership, observation, control, driver, driverBaseContext,
+            });
+        }
+        if (phase.value.kind === "finish") {
+            return await reportDriverOutcome(phase.value.outcome, {
+                job, httpClient, options, deps, ownership, observation, control,
+            });
+        }
+        driverStep = phase.value;
+        // The driver's prompt is used VERBATIM: it is server-rendered, and the PR-base
+        // launch instruction would tell a worker with no push authority to open a PR.
+        prompt = driverStep.prompt;
+    }
     // --- Pre-spawn git verification (FAIL-CLOSED, BAPI-731 WS-E) ---------
     // FIRST of the pre-spawn contracts, and deliberately BEFORE every
     // executor-owned write to the worktree (deny layer, MCP provisioning, worker
@@ -1304,8 +1509,15 @@ async function runPreparedSpawn(params) {
     // untracked-clean / head-verify behavior in `worktree-core.ts`; it is an
     // additional independent check on top of them.
     const preSpawnTelemetry = await collectGitTelemetry({ runCommand: deps.runCommand, now: deps.now }, worktreePath, effectiveBaseBranch);
-    const verification = evaluatePreSpawnGitVerification(preSpawnTelemetry, prep.expectedHeadSha);
+    // BAPI-1152: a driver proves its own pre-spawn state (a reconciliation worker
+    // may start inside an in-progress merge, which the generic "clean at the
+    // prepared commit" check would refuse by design).
+    const verification = driverStep
+        ? driverStep.preSpawnVerification
+        : evaluatePreSpawnGitVerification(preSpawnTelemetry, prep.expectedHeadSha);
     if (!verification.ok) {
+        if (driver)
+            await driver.abandon(driverBaseContext);
         // Record the attempt boundary even for a refusal: an attempt that never
         // spawned still started and ended at the observed commit, so the reconciler
         // sees a machine-readable "went nowhere" rather than a silent gap.
@@ -1555,7 +1767,12 @@ async function runPreparedSpawn(params) {
             // BAPI-1020 — becomes `BAPI_WORKER_BRANCH` in the worker environment, which
             // is the deterministic guard's only source of branch identity. Same
             // provenance as the deny-provisioning value above: the prepared worktree.
-            workerBranch: branch,
+            //
+            // BAPI-1152: a driver that holds the push itself OMITS it, so the guard
+            // denies every `git push` the worker attempts — the worker has no remote
+            // write authority at all.
+            ...(driver?.omitWorkerBranch ? {} : { workerBranch: branch }),
+            ...(driverStep ? { declaredTouchedFiles: driverStep.declaredTouchedFiles } : {}),
             parentEnv: deps.env,
         });
         assertUsableSpawnShape(spawnShape, adapter);
@@ -1736,7 +1953,9 @@ async function runPreparedSpawn(params) {
         ownership,
         observation,
         proc: supervisedProc,
-        timeoutSeconds: timeout.timeoutSeconds,
+        // BAPI-1152: a driver's worker gets what is LEFT of the job budget, since the
+        // pre-worker phase has already spent some of it.
+        timeoutSeconds: driver ? Math.max(1, Math.ceil(remainingMs() / 1000)) : timeout.timeoutSeconds,
         collectTelemetry,
         collectRemoteMarker,
         mcpSurface,
@@ -1786,6 +2005,8 @@ async function runPreparedSpawn(params) {
     if (procResult.serverStopRequested) {
         await closeWorkerLog();
         await finalizeRegistry();
+        if (driver)
+            await driver.abandon(driverBaseContext);
         await httpClient.fail(job, {
             error_kind: "ServerStopRequested",
             error_message: "the server requested this run stop; the owned worker was terminated",
@@ -1813,6 +2034,8 @@ async function runPreparedSpawn(params) {
     await reportWorkerLogSessionInvariant(tee, deps);
     if (ownership.abandoned) {
         await finalizeRegistry();
+        if (driver)
+            await driver.abandon(driverBaseContext);
         return { status: "abandoned", reason: ownership.abandonReason };
     }
     // --- MCP surface containment verdict (FAIL-CLOSED, BAPI-790) ----------
@@ -1833,6 +2056,8 @@ async function runPreparedSpawn(params) {
     const surfaceVerdict = mcpSurface.verdict();
     if (surfaceVerdict.kind === "mismatch") {
         await finalizeRegistry();
+        if (driver)
+            await driver.abandon(driverBaseContext);
         await httpClient.fail(job, {
             error_kind: McpSurfaceMismatch,
             error_message: formatMcpSurfaceMismatch(surfaceVerdict.expected, surfaceVerdict.observed),
@@ -1860,6 +2085,8 @@ async function runPreparedSpawn(params) {
         procResult.classification === "crashed" &&
         procResult.stdoutExcerpt.trim().length === 0) {
         await finalizeRegistry();
+        if (driver)
+            await driver.abandon(driverBaseContext);
         await httpClient.fail(job, {
             error_kind: WorkerStartupFatal,
             error_message: WORKER_STARTUP_FATAL_MESSAGE,
@@ -1886,6 +2113,31 @@ async function runPreparedSpawn(params) {
                 "for this spawn");
     }
     const git = observation.git();
+    // BAPI-1152: a driver owns everything after a clean worker exit — staging, the
+    // governance scan, the commits, the guarded push, and finalization.
+    if (driver && procResult.classification === "clean_exit") {
+        await finalizeRegistry();
+        const phase = await superviseDriverPhase({
+            job,
+            httpClient,
+            options: jobOptions,
+            deps,
+            ownership,
+            observation,
+            control,
+            timeoutSeconds: Math.max(1, Math.ceil(remainingMs() / 1000)),
+            collectTelemetry: driverTelemetry,
+            run: (signal) => driver.afterWorker({ ...driverBaseContext, signal, remainingMs }, { classification: procResult.classification, exitCode: procResult.exitCode }),
+        });
+        if (phase.kind !== "result") {
+            return await reportDriverPhaseInterruption(phase, {
+                job, httpClient, options, deps, ownership, observation, control, driver, driverBaseContext,
+            });
+        }
+        return await reportDriverOutcome(phase.value, {
+            job, httpClient, options, deps, ownership, observation, control,
+        });
+    }
     if (procResult.classification === "clean_exit") {
         // Verdict jobs (`spec_review`) forward the fixed-path artifact verbatim; a
         // missing/invalid artifact is a fail-loud `MissingVerdictArtifact`.
@@ -2028,6 +2280,19 @@ async function runPreparedSpawn(params) {
     // a verdict and a reason code only — never the matched line — so nothing from
     // the worker's stream reaches `/fail` through this path.
     await finalizeRegistry();
+    // BAPI-1152: an interrupted worker (timeout or kill) can leave a stale
+    // `index.lock` or an in-progress merge behind — the BAPI-1111 residue that made
+    // the next job's reset fail. Removed for EVERY spawn job, never with a hard
+    // reset; only a driver (`reconcile_overlap`) additionally resets to its anchor.
+    if (procResult.classification === "timeout" || procResult.classification === "killed") {
+        await cleanupInterruptedWorktree(worktreePath, {
+            runCommand: deps.runCommand,
+            removeFile: deps.removeFile ?? ((filePath) => rm(filePath)),
+            errorLog: deps.errorLog,
+        });
+    }
+    if (driver)
+        await driver.abandon(driverBaseContext);
     const authDetection = adapter.authFailureDetection;
     const authFailure = authDetection?.supported === true &&
         authDetection.value.classify(procResult.stdoutExcerpt).notAuthenticated;

package/build/executor/job-types.js

@@ -2,9 +2,10 @@
  * Shared executor job-type policy (BAPI-542, TDD §9).
  *
  * Single source of truth for which claimed job types the executor spawns and
- * which of those are RECOVERY jobs. Recovery jobs (`remediate`/`ci_fix`/`rebase`)
- * resume the ticket's existing branch/PR through the `/implement-ticket <KEY>
- * --auto` correction loop rather than cutting a fresh branch off base. Dispatch
+ * which of those are RECOVERY jobs. Recovery jobs (`remediate`/`ci_fix`/`rebase`/
+ * `reconcile_overlap`) resume the ticket's existing branch/PR rather than cutting
+ * a fresh branch off base — the first three through the `/implement-ticket <KEY>
+ * --auto` correction loop, `reconcile_overlap` through its own job body. Dispatch
  * (`job-runner.ts` `runClaimedJob`), prompt synthesis (`worker-command.ts`
  * `resolveExecutorPrompt`), and worktree reuse (`job-runner.ts` `prepareSpawn` →
  * `worktree.ts` `ensureExecutorWorktree`) all read from here so the recovery /
@@ -17,21 +18,33 @@
 /**
  * Recovery job types: enqueued by the server-side reconciler when a gate is
  * ACTIONABLE (review changes requested → `remediate`, CI failed → `ci_fix`,
- * merge conflict → `rebase`). They re-enter the correction loop on the ticket's
- * EXISTING branch/PR, so the executor reuses that branch instead of cutting a
- * fresh one off base.
+ * merge conflict → `rebase`, overlapping sibling at `code_review` →
+ * `reconcile_overlap`). They work on the ticket's EXISTING branch/PR, so the
+ * executor reuses that branch instead of cutting a fresh one off base.
+ *
+ * BAPI-1152: `reconcile_overlap` is a recovery job for worktree reuse and prompt
+ * resolution, but it does NOT re-enter `/implement-ticket`: it always carries an
+ * explicit server-rendered `payload.prompt`, which wins over the synthesis in
+ * `worker-command.ts`, and `job-runner.ts` dispatches it to its own body.
  */
 export const RECOVERY_JOB_TYPES = new Set([
     "remediate",
     "ci_fix",
     "rebase",
+    "reconcile_overlap",
 ]);
 /**
  * Real headless-spawn job types (worktree + worker LLM): the first-pass
  * `implement`, the `resume` continuation (own pre-spawn protocol), the
- * `spec_review` verdict job, and the three recovery jobs. `merge` (deterministic,
+ * `spec_review` verdict job, and the recovery jobs. `merge` (deterministic,
  * no worktree/worker) and `smoke` (no-op acceptance) are intentionally EXCLUDED —
  * they have dedicated dispatch branches BEFORE the generic spawn path.
+ *
+ * BAPI-1152: `reconcile_overlap` is here because it needs a prepared, locked
+ * worktree and MAY spawn a worker — but only CONDITIONALLY. A clean merge whose
+ * local checks pass is pushed with no worker at all. It also has a dedicated
+ * dispatch branch ahead of the generic spawn path; membership here is what makes
+ * worktree preparation and `isImplementationStyleJobType` treat it as a spawn job.
  */
 export const SPAWN_JOB_TYPES = new Set([
     "implement",
@@ -40,6 +53,7 @@ export const SPAWN_JOB_TYPES = new Set([
     "remediate",
     "ci_fix",
     "rebase",
+    "reconcile_overlap",
 ]);
 /** True only for the exact lowercase recovery job types. */
 export function isRecoveryJobType(jobType) {
@@ -52,8 +66,10 @@ export function isSpawnJobType(jobType) {
 /**
  * Implementation-style spawn jobs (BAPI-551): every spawn job type expected to
  * end with a pushed origin branch or an opened PR — `implement`, `resume`, and
- * the recovery jobs. Excludes `spec_review`, the one spawn type that is a
- * verdict job (it produces `.conductor/result.json` instead of a branch/PR).
+ * the recovery jobs (`reconcile_overlap` included: when it pushes, finalization
+ * verifies the push against origin). Excludes `spec_review`, the one spawn type
+ * that is a verdict job (it produces `.conductor/result.json` instead of a
+ * branch/PR).
  */
 export function isImplementationStyleJobType(jobType) {
     return isSpawnJobType(jobType) && jobType !== "spec_review";

package/build/executor/merge-tree-classifier.js

@@ -0,0 +1,171 @@
+/**
+ * Deterministic merge classification for `reconcile_overlap` (BAPI-1152).
+ *
+ * Classifies a (child head, required epic SHA) pair with
+ * `git merge-tree --write-tree` BEFORE anything touches the held worktree.
+ * `merge-tree` computes the merge entirely in the object database: it writes a
+ * tree object and reports conflicts, but never touches a working tree, an index,
+ * `HEAD`, or a ref. That is what lets the job decide "clean or conflicted" first
+ * and only then materialize a real merge.
+ *
+ * Output is read in the machine-readable `-z --name-only --messages` form, never
+ * scraped from human text. Verified against git 2.50.1:
+ *
+ *   <tree-oid> NUL <conflicted path> NUL ... NUL NUL
+ *   ( <N> NUL <path 1> NUL ... <path N> NUL <type> NUL <message> NUL )*
+ *
+ * with exit 0 for a clean merge and 1 for a conflicted one. Exit 1 is ALSO what
+ * git returns for an unknown commit — with no tree OID on stdout — so the exit
+ * code alone never decides "conflicted": the parsed tree OID does. Anything that
+ * is not a proven clean or conflicted result is `operational_error`, and the job
+ * fails rather than guessing.
+ *
+ * Every git call is an argv list through the injected `RunCommand` (`execFile`,
+ * `shell: false`); no shell string is ever built.
+ */
+import { normalizeRepoRelativePath } from "../conductor/file-scope-guard.js";
+/** Bound on the conflicted paths recorded. More than this is still `conflicted`. */
+export const MERGE_TREE_MAX_CONFLICTS = 200;
+/** Bound on the informational lines kept per conflicted path. */
+export const MERGE_TREE_MAX_MESSAGES_PER_PATH = 5;
+/** Bound on one message line. */
+export const MERGE_TREE_MESSAGE_MAX_CHARS = 300;
+/** Wall-clock bound on each git call the classifier makes. */
+export const MERGE_TREE_COMMAND_TIMEOUT_MS = 120_000;
+const OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+function descriptorFor(type, message) {
+    // The MESSAGE carries git's user-facing spelling ("CONFLICT (content)"); the
+    // type token is an internal name ("CONFLICT (contents)"). Prefer the message's
+    // own prefix so the descriptor matches what an operator sees in `git merge`.
+    const fromMessage = /^(CONFLICT \([^)]*\))/.exec(message.trim());
+    if (fromMessage)
+        return fromMessage[1];
+    return type.trim().length > 0 ? type.trim() : "CONFLICT (unknown)";
+}
+/**
+ * Parse `git merge-tree --write-tree -z --name-only --messages` stdout.
+ *
+ * Exported for the unit tests; `classifyMergeTree` is the runtime entry point.
+ * Returns `null` when stdout does not start with a tree OID — the caller treats
+ * that as an operational error.
+ */
+export function parseMergeTreeOutput(stdout) {
+    const tokens = stdout.split("\0");
+    const treeOid = (tokens[0] ?? "").trim().toLowerCase();
+    if (!OID_RE.test(treeOid))
+        return null;
+    let i = 1;
+    const conflictedPaths = [];
+    while (i < tokens.length && tokens[i] !== "") {
+        conflictedPaths.push(tokens[i]);
+        i += 1;
+    }
+    i += 1; // the empty token separating conflicted paths from messages
+    const byPath = new Map();
+    const record = (rawPath, descriptor, message) => {
+        const path = normalizeRepoRelativePath(rawPath) ?? rawPath;
+        let entry = byPath.get(path);
+        if (!entry) {
+            entry = { path, descriptor: descriptor ?? "CONFLICT (unknown)", messages: [] };
+            byPath.set(path, entry);
+        }
+        else if (descriptor && entry.descriptor === "CONFLICT (unknown)") {
+            entry.descriptor = descriptor;
+        }
+        if (message && entry.messages.length < MERGE_TREE_MAX_MESSAGES_PER_PATH) {
+            entry.messages.push(message.trim().slice(0, MERGE_TREE_MESSAGE_MAX_CHARS));
+        }
+    };
+    while (i < tokens.length) {
+        const countToken = tokens[i];
+        if (countToken === "" || countToken === undefined)
+            break;
+        const count = Number.parseInt(countToken, 10);
+        // A group is `count` paths plus a type and a message; a truncated group ends
+        // the parse rather than reading past stdout.
+        if (!Number.isInteger(count) || count < 0 || i + count + 2 >= tokens.length)
+            break;
+        const paths = tokens.slice(i + 1, i + 1 + count);
+        const type = tokens[i + 1 + count] ?? "";
+        const message = tokens[i + 2 + count] ?? "";
+        i += count + 3;
+        if (!type.startsWith("CONFLICT"))
+            continue;
+        const descriptor = descriptorFor(type, message);
+        // The FIRST path of a multi-path message (e.g. rename/delete names the new
+        // and the old path) is the one git reports as conflicted; the rest are
+        // context. Recording every named path would report a path that no longer
+        // exists in the merge result as conflicted.
+        const conflicted = paths.find((p) => conflictedPaths.includes(p)) ?? paths[0];
+        if (conflicted !== undefined)
+            record(conflicted, descriptor, message);
+    }
+    // A path git listed as conflicted with no CONFLICT message is still conflicted.
+    for (const path of conflictedPaths) {
+        const normalized = normalizeRepoRelativePath(path) ?? path;
+        if (!byPath.has(normalized))
+            record(path, null, null);
+    }
+    const conflicts = Array.from(byPath.values())
+        .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+        .slice(0, MERGE_TREE_MAX_CONFLICTS);
+    return { treeOid, conflicts };
+}
+/** Verify a commit object is present locally. */
+async function commitPresent(runCommand, repoDir, sha) {
+    try {
+        const result = await runCommand("git", ["cat-file", "-e", `${sha}^{commit}`], {
+            cwd: repoDir,
+            timeoutMs: MERGE_TREE_COMMAND_TIMEOUT_MS,
+        });
+        return result.exitCode === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Classify merging `requiredEpicSha` into `childHead`. Never mutates a worktree,
+ * an index, `HEAD`, or a ref. Both SHAs must already be present in `repoDir`'s
+ * object database (the caller fetches them).
+ */
+export async function classifyMergeTree(runCommand, repoDir, childHead, requiredEpicSha) {
+    for (const sha of [childHead, requiredEpicSha]) {
+        if (!OID_RE.test(sha)) {
+            return { kind: "operational_error", reason: "a merge input is not a full commit SHA" };
+        }
+        if (!(await commitPresent(runCommand, repoDir, sha))) {
+            return {
+                kind: "operational_error",
+                reason: `commit ${sha.slice(0, 12)} is not present in the local object database`,
+            };
+        }
+    }
+    let result;
+    try {
+        result = await runCommand("git", ["merge-tree", "--write-tree", "-z", "--name-only", "--messages", childHead, requiredEpicSha], { cwd: repoDir, timeoutMs: MERGE_TREE_COMMAND_TIMEOUT_MS });
+    }
+    catch {
+        return { kind: "operational_error", reason: "git merge-tree could not be run" };
+    }
+    if (result.exitCode !== 0 && result.exitCode !== 1) {
+        return { kind: "operational_error", reason: `git merge-tree exited ${result.exitCode}` };
+    }
+    const parsed = parseMergeTreeOutput(result.stdout);
+    if (parsed === null) {
+        return { kind: "operational_error", reason: "git merge-tree produced no tree object" };
+    }
+    if (result.exitCode === 0) {
+        return { kind: "clean", treeOid: parsed.treeOid };
+    }
+    if (parsed.conflicts.length === 0) {
+        // Exit 1 WITH a tree but no conflict record: git said "not clean" and did not
+        // say why. Unknown is conflicted, never clean.
+        return {
+            kind: "conflicted",
+            treeOid: parsed.treeOid,
+            conflicts: [{ path: "(unreported)", descriptor: "CONFLICT (unknown)", messages: [] }],
+        };
+    }
+    return { kind: "conflicted", treeOid: parsed.treeOid, conflicts: parsed.conflicts };
+}