@bridge_gpt/mcp-server 0.2.18 → 0.2.20

package/build/executor/worker-finalization.js

@@ -0,0 +1,177 @@
+/**
+ * Fail-loud worker-finalization check (BAPI-551).
+ *
+ * An implementation-style worker (`implement`/`resume`/`remediate`/`ci_fix`/
+ * `rebase`) can exit cleanly yet strand its work if its push never landed on
+ * origin and no PR was opened — e.g. the worker backgrounds a slow push (the
+ * advisory pre-push suite) and returns before it completes. Without this check
+ * the executor still reports `clean_exit`/`succeeded`, and the gap is only ever
+ * caught by the reconciler's 3h watchdog. `validateWorkerFinalization` converts
+ * that condition into an explicit executor failure instead, using an authoritative
+ * local `git ls-remote` check (no Bridge API credentials, no conductor identity)
+ * that reads the real origin tip — never a stale local `origin/<branch>` tracking
+ * ref. That lookup is optionally repeated a few times with a short bounded delay
+ * before reporting `WorkerFinalizationMissingRemoteBranchAndPr`, so a recovery
+ * job whose push has landed but whose remote visibility settles just after the
+ * worker exits is not spuriously failed (BAPI-566 Bug A).
+ *
+ * For `resume`/`remediate`/`ci_fix`/`rebase`, the branch is fetched from origin
+ * BEFORE the worker starts (worktree.ts's recovery reuse path, resume-pre-spawn's
+ * "recreate ONLY from the pushed branch" path) — so the ref existing on origin is
+ * not proof THIS session's commit landed; a stale pre-existing branch would pass
+ * an existence-only check. The check instead compares the authoritative origin
+ * branch tip SHA against the worker's own HEAD commit (`headSha`, from git
+ * telemetry) whenever that comparison is available.
+ */
+import { secretFreeErrorMessage, WorkerFinalizationMissingRemoteBranchAndPr } from "./job-errors.js";
+import { isImplementationStyleJobType } from "./job-types.js";
+/** Bounded settling re-check defaults for the authoritative origin-tip lookup. */
+const DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS = 3;
+const DEFAULT_ORIGIN_FINALIZATION_RETRY_DELAY_MS = 500;
+/** Real-timer sleep; overridable via the `sleep` seam for deterministic tests. */
+function sleepMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function normalizeAttempts(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : DEFAULT_ORIGIN_FINALIZATION_ATTEMPTS;
+}
+function normalizeRetryDelay(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : DEFAULT_ORIGIN_FINALIZATION_RETRY_DELAY_MS;
+}
+function extractPrUrl(result) {
+    const raw = result.pr_url;
+    return typeof raw === "string" && raw.trim().length > 0 ? raw.trim() : undefined;
+}
+/** Normalize to exactly one `refs/heads/` prefix — never `refs/heads/refs/heads/...`. */
+function normalizeBranchRef(branch) {
+    return branch.startsWith("refs/heads/") ? branch : `refs/heads/${branch}`;
+}
+/**
+ * Scan `git ls-remote` stdout and return the SHA for EXACTLY `expectedRef`.
+ * `ls-remote` lines are `<sha>\t<ref>`; only an exact ref match counts, so a
+ * prefix/suffix/child ref (`…-old`, `…/retry`) is never accepted. The returned
+ * SHA is trimmed and lower-cased so callers compare against a normalized worker
+ * HEAD. Raw stderr and credentials are never touched here.
+ */
+function parseLsRemoteHeadSha(stdout, expectedRef) {
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        const parts = trimmed.split(/\s+/);
+        if (parts.length < 2)
+            continue;
+        const [sha, ref] = parts;
+        if (ref === expectedRef) {
+            const normalized = sha.trim().toLowerCase();
+            return normalized.length > 0 ? normalized : null;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the origin branch's authoritative current tip SHA (normalized), or
+ * `null` if the ref is absent. Uses `git ls-remote` against the exact normalized
+ * ref — never a local `origin/<branch>` remote-tracking ref, which can be stale
+ * on a recovery worktree. A non-zero exit is treated as "branch not found"
+ * without copying raw stderr into diagnostics.
+ */
+export async function resolveOriginBranchSha(runCommand, worktreePath, branch) {
+    const normalizedRef = normalizeBranchRef(branch);
+    const result = await runCommand("git", ["ls-remote", "--exit-code", "--heads", "origin", normalizedRef], { cwd: worktreePath });
+    if (result.exitCode !== 0)
+        return null;
+    return parseLsRemoteHeadSha(result.stdout, normalizedRef);
+}
+/**
+ * Repeatedly resolve the authoritative origin tip until it either satisfies
+ * finalization or the bounded retry budget is exhausted. Stops early (no further
+ * lookups) when the origin tip matches the worker HEAD, or when the branch exists
+ * and the worker HEAD is unavailable (degraded telemetry, existence-only). Retries
+ * when the tip is `null` (branch not yet visible) or, with a known HEAD, does not
+ * yet match. Returns the LAST authoritative observation — the caller decides
+ * loud-failure from that final value, so true negatives are preserved.
+ */
+async function resolveOriginBranchShaForFinalization(runCommand, worktreePath, branch, trimmedHeadSha, attempts, retryDelayMs, sleep) {
+    const total = Math.max(1, attempts);
+    let remoteSha = null;
+    for (let attempt = 0; attempt < total; attempt++) {
+        remoteSha = await resolveOriginBranchSha(runCommand, worktreePath, branch);
+        if (remoteSha !== null) {
+            // Existence-only success when HEAD is unknown; exact-match success otherwise.
+            if (!trimmedHeadSha || remoteSha === trimmedHeadSha)
+                return remoteSha;
+        }
+        if (attempt < total - 1)
+            await sleep(retryDelayMs);
+    }
+    return remoteSha;
+}
+function missingBranchAndPrFailure(job, detail) {
+    const label = job.ticket_key ? `${job.ticket_key} (job ${job.id})` : `job ${job.id}`;
+    return {
+        error_kind: WorkerFinalizationMissingRemoteBranchAndPr,
+        error_message: `${label} exited cleanly but ${detail}`,
+        classification: "crashed",
+    };
+}
+/**
+ * Validate that an implementation-style job's clean exit actually produced a PR
+ * or a pushed origin branch. Non-implementation-style jobs (verdict jobs) and
+ * any result carrying a non-empty `pr_url` bypass the git check entirely.
+ */
+export async function validateWorkerFinalization(input) {
+    const { job, branch, worktreePath, result, runCommand, headSha } = input;
+    if (!isImplementationStyleJobType(job.job_type)) {
+        return { ok: true };
+    }
+    if (extractPrUrl(result)) {
+        return { ok: true };
+    }
+    const trimmedBranch = typeof branch === "string" ? branch.trim() : "";
+    if (!trimmedBranch) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, "produced no PR URL and no expected branch to verify on origin"),
+        };
+    }
+    // Recovery/resume jobs fetch `origin/<branch>` before the worker even starts,
+    // so the ref merely existing is not proof this session's commit landed. When
+    // the worker's own HEAD is known, require the authoritative origin tip to match
+    // it exactly — a stale pre-existing branch (this session's push never happened)
+    // fails loud instead of passing. When HEAD is unresolved (degraded telemetry),
+    // fall back to the existence-only check rather than inventing a new failure
+    // mode. The authoritative lookup is retried a few times so a push that settles
+    // just after the worker exits still finalizes (BAPI-566 Bug A).
+    const trimmedHeadSha = typeof headSha === "string" ? headSha.trim().toLowerCase() : "";
+    const attempts = normalizeAttempts(input.originResolveAttempts);
+    const retryDelayMs = normalizeRetryDelay(input.originResolveRetryDelayMs);
+    const sleep = input.sleep ?? sleepMs;
+    let remoteSha;
+    try {
+        remoteSha = await resolveOriginBranchShaForFinalization(runCommand, worktreePath, trimmedBranch, trimmedHeadSha, attempts, retryDelayMs, sleep);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, `produced no PR URL and branch '${trimmedBranch}' could not be verified on origin: ${secretFreeErrorMessage(err)}`),
+        };
+    }
+    if (remoteSha === null) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, `produced no PR URL and branch '${trimmedBranch}' is not on origin`),
+        };
+    }
+    if (trimmedHeadSha && remoteSha !== trimmedHeadSha) {
+        return {
+            ok: false,
+            failure: missingBranchAndPrFailure(job, `produced no PR URL and origin branch '${trimmedBranch}' is at ${remoteSha.slice(0, 12)}, which does not match this worker's HEAD ${trimmedHeadSha.slice(0, 12)} — the worker's commit was not pushed`),
+        };
+    }
+    return { ok: true };
+}

package/build/executor/worker-log.js

@@ -0,0 +1,92 @@
+/**
+ * Per-job worker log tee primitives (BAPI-535, TDD §8, G5).
+ *
+ * Every worker's output is teed to the fixed path `<worktree>/.conductor/worker.log`
+ * in human-readable form so `tail -f` reproduces the v1 tab experience on demand.
+ * The tee is PURELY a recorder: it never owns, signals, or kills the worker
+ * process — closing/finalizing the log affects the file only. All filesystem
+ * access is behind injected boundaries so this is unit-testable with no real I/O.
+ */
+import { pathApiForExecutorPlatform } from "./worktree-inspection.js";
+/** The fixed `.conductor` worker-log directory (relative to the worktree). */
+export const CONDUCTOR_WORKER_LOG_DIR = ".conductor";
+/** The fixed worker-log filename. */
+export const CONDUCTOR_WORKER_LOG_FILE = "worker.log";
+/** Resolve `<worktree>/.conductor/worker.log` with platform-correct separators. */
+export function buildWorkerLogPath(worktreePath, platform = process.platform) {
+    const pathApi = pathApiForExecutorPlatform(platform);
+    return pathApi.join(worktreePath, CONDUCTOR_WORKER_LOG_DIR, CONDUCTOR_WORKER_LOG_FILE);
+}
+/**
+ * Render one stdout/stderr chunk as human-readable log text. The worker's stream
+ * is already text; this passes it through WITHOUT JSON framing, process metadata,
+ * or secret-bearing envelope fields. `stream` is accepted for future labeling but
+ * the default rendering is a faithful passthrough so `tail -f` shows raw output.
+ */
+export function renderWorkerLogChunk(chunk, _stream = "stdout") {
+    return chunk;
+}
+/**
+ * Create the `.conductor` directory, initialize an empty `worker.log`, and return
+ * a tee handle. When an `appendFile` boundary is supplied, chunks are appended
+ * incrementally; otherwise a buffered fallback re-writes the accumulated content
+ * via `writeFile` so all consumed chunks are preserved in order.
+ */
+export async function createWorkerLogTee(worktreePath, deps) {
+    const platform = deps.platform ?? process.platform;
+    const pathApi = pathApiForExecutorPlatform(platform);
+    const dir = pathApi.join(worktreePath, CONDUCTOR_WORKER_LOG_DIR);
+    const logPath = pathApi.join(dir, CONDUCTOR_WORKER_LOG_FILE);
+    await deps.mkdir(dir, { recursive: true });
+    await deps.writeFile(logPath, "");
+    let buffer = "";
+    let closed = false;
+    return {
+        logPath,
+        async append(chunk) {
+            if (closed)
+                return;
+            try {
+                if (deps.appendFile) {
+                    await deps.appendFile(logPath, chunk);
+                }
+                else {
+                    buffer += chunk;
+                    await deps.writeFile(logPath, buffer);
+                }
+            }
+            catch {
+                /* the log tee is a visibility nicety — a write failure never fails a job */
+            }
+        },
+        async close() {
+            closed = true;
+        },
+    };
+}
+/**
+ * Wrap an `AsyncIterable<string>` so every consumed chunk is rendered and written
+ * to the worker log before being yielded to the existing runner logic. The
+ * original chunks pass through UNCHANGED, so downstream observation/classification
+ * is unaffected.
+ */
+export async function* teeAsyncIterable(source, tee, stream = "stdout") {
+    for await (const chunk of source) {
+        await tee.append(renderWorkerLogChunk(chunk, stream));
+        yield chunk;
+    }
+}
+/**
+ * Safely finalize a tee. Tolerates a `null`/`undefined` tee and repeated calls;
+ * NEVER kills or signals the worker process.
+ */
+export async function closeWorkerLogTee(tee) {
+    if (!tee)
+        return;
+    try {
+        await tee.close();
+    }
+    catch {
+        /* finalization is best-effort */
+    }
+}

package/build/executor/worktree-gc.js

@@ -0,0 +1,134 @@
+/**
+ * Conservative executor worktree GC sweep (BAPI-535, TDD §7 teardown).
+ *
+ * Removes ONLY executor/conductor-managed worktrees whose branch is merged into
+ * the base branch (`git merge-base --is-ancestor <branch> origin/<base>`) and
+ * idle for more than 24h. CONSERVATIVE by construction: a worktree that is the
+ * base branch, unmanaged, dirty, recently active, on an unknown/detached branch,
+ * unmerged, or whose merged/idle status cannot be PROVEN is always retained. Any
+ * inability to prove eligibility retains the worktree; per-worktree failures
+ * never abort the whole sweep. All I/O is injected for offline unit testing.
+ */
+import { listGitWorktrees, pathApiForExecutorPlatform, } from "./worktree-inspection.js";
+/** Idle cutoff: a worktree must be idle strictly longer than 24h to be eligible. */
+export const EXECUTOR_WORKTREE_GC_IDLE_MS = 24 * 60 * 60 * 1000;
+function conductorMarkerPaths(worktreePath, platform) {
+    const pathApi = pathApiForExecutorPlatform(platform);
+    const dir = pathApi.join(worktreePath, ".conductor");
+    return {
+        dir,
+        workerLog: pathApi.join(dir, "worker.log"),
+        resultJson: pathApi.join(dir, "result.json"),
+    };
+}
+/**
+ * Conservatively identify an executor/conductor-managed worktree by the presence
+ * of a `.conductor` directory, `.conductor/worker.log`, or `.conductor/result.json`.
+ */
+export async function isExecutorManagedWorktree(worktreePath, deps) {
+    const markers = conductorMarkerPaths(worktreePath, deps.platform ?? process.platform);
+    for (const marker of [markers.workerLog, markers.resultJson, markers.dir]) {
+        if ((await deps.statMtimeMs(marker)) !== null)
+            return true;
+    }
+    return false;
+}
+/**
+ * Compute last activity as the NEWEST mtime among `.conductor/worker.log`,
+ * `.conductor/result.json`, and the worktree directory itself. Returns `null`
+ * when none can be stat'd (activity cannot be proven → the caller retains).
+ */
+export async function getWorktreeLastActivityMs(worktreePath, deps) {
+    const markers = conductorMarkerPaths(worktreePath, deps.platform ?? process.platform);
+    const candidates = [markers.workerLog, markers.resultJson, worktreePath];
+    let newest = null;
+    for (const candidate of candidates) {
+        const mtime = await deps.statMtimeMs(candidate);
+        if (mtime !== null && (newest === null || mtime > newest))
+            newest = mtime;
+    }
+    return newest;
+}
+/** Idle when the last activity is STRICTLY more than 24h before `now`. */
+export function isWorktreeIdle(lastActivityMs, nowMs) {
+    return nowMs - lastActivityMs > EXECUTOR_WORKTREE_GC_IDLE_MS;
+}
+/** True only when `git merge-base --is-ancestor <branch> origin/<base>` exits 0. */
+export async function isBranchMergedIntoBase(runCommand, cwd, branch, baseBranch) {
+    const result = await runCommand("git", ["merge-base", "--is-ancestor", branch, `origin/${baseBranch}`], { cwd });
+    return result.exitCode === 0;
+}
+/** True when `git status --porcelain` inside the worktree is non-empty. */
+export async function isWorktreeDirty(runCommand, worktreePath) {
+    const result = await runCommand("git", ["status", "--porcelain"], { cwd: worktreePath });
+    return result.stdout.trim().length > 0;
+}
+/**
+ * Sweep worktrees, removing ONLY managed, clean, idle, non-base, merged
+ * worktrees. Everything else — including any worktree whose eligibility cannot be
+ * proven — is retained with a structured reason. Per-worktree failures are
+ * recorded and the sweep continues; the sweep never throws globally.
+ */
+export async function sweepExecutorWorktrees(deps) {
+    const summary = { removed: [], retained: [], errors: [] };
+    const listWorktrees = deps.listWorktrees ?? listGitWorktrees;
+    const nowMs = deps.now();
+    let entries;
+    try {
+        entries = await listWorktrees(deps.runCommand, deps.cwd);
+    }
+    catch (err) {
+        summary.errors.push({ path: deps.cwd, error: err instanceof Error ? err.message : String(err) });
+        return summary;
+    }
+    for (const entry of entries) {
+        try {
+            if (!entry.branch) {
+                summary.retained.push({ path: entry.path, reason: "detached/unknown branch" });
+                continue;
+            }
+            if (entry.branch === deps.baseBranch) {
+                summary.retained.push({ path: entry.path, reason: "base branch" });
+                continue;
+            }
+            if (!(await isExecutorManagedWorktree(entry.path, deps))) {
+                summary.retained.push({ path: entry.path, reason: "unmanaged (no .conductor marker)" });
+                continue;
+            }
+            if (await isWorktreeDirty(deps.runCommand, entry.path)) {
+                summary.retained.push({ path: entry.path, reason: "dirty" });
+                continue;
+            }
+            const lastActivity = await getWorktreeLastActivityMs(entry.path, deps);
+            if (lastActivity === null) {
+                summary.retained.push({ path: entry.path, reason: "activity unprovable" });
+                continue;
+            }
+            if (!isWorktreeIdle(lastActivity, nowMs)) {
+                summary.retained.push({ path: entry.path, reason: "recent activity" });
+                continue;
+            }
+            if (!(await isBranchMergedIntoBase(deps.runCommand, deps.cwd, entry.branch, deps.baseBranch))) {
+                summary.retained.push({ path: entry.path, reason: "not merged into base" });
+                continue;
+            }
+            const removeResult = await deps.runCommand("git", ["worktree", "remove", entry.path], {
+                cwd: deps.cwd,
+            });
+            if (removeResult.exitCode === 0) {
+                summary.removed.push(entry.path);
+            }
+            else {
+                summary.errors.push({
+                    path: entry.path,
+                    error: (removeResult.stderr || removeResult.stdout || "git worktree remove failed").trim(),
+                });
+            }
+        }
+        catch (err) {
+            // Any failure to prove eligibility retains the worktree.
+            summary.errors.push({ path: entry.path, error: err instanceof Error ? err.message : String(err) });
+        }
+    }
+    return summary;
+}

package/build/executor/worktree-inspection.js

@@ -0,0 +1,86 @@
+/**
+ * Local worktree inspection utilities for executor job behaviors (BAPI-535).
+ *
+ * Safe, read-only Git worktree lookup, branch verification, and remote-branch
+ * probes used by the `resume` pre-spawn protocol and the worktree GC sweep. All
+ * subprocess access is behind the injected `RunCommand` boundary so every helper
+ * is unit-testable on Linux CI with no real `git`. NONE of these helpers ever
+ * mutates repository state (no reset/checkout/clean/branch writes).
+ */
+import path from "node:path";
+import { BranchMismatch, ExecutorNamedError } from "./job-errors.js";
+/** Return the Node `path` API matching a platform (`win32` vs POSIX). */
+export function pathApiForExecutorPlatform(platform) {
+    return platform === "win32" ? path.win32 : path.posix;
+}
+/**
+ * Parse `git worktree list --porcelain` output into entries. Each record is a
+ * blank-line-separated block whose first line is `worktree <path>`; a `branch
+ * refs/heads/<name>` line carries the local branch, which is normalized to the
+ * short branch name. Detached/no-branch worktrees are represented without a
+ * `branch` (never an invented one).
+ */
+export function parseGitWorktreePorcelain(porcelain) {
+    const entries = [];
+    let current = null;
+    for (const rawLine of porcelain.split("\n")) {
+        const line = rawLine.replace(/\r$/, "");
+        if (line.startsWith("worktree ")) {
+            if (current)
+                entries.push(current);
+            current = { path: line.slice("worktree ".length).trim() };
+        }
+        else if (line.startsWith("branch ") && current) {
+            const ref = line.slice("branch ".length).trim();
+            current.branch = ref.startsWith("refs/heads/")
+                ? ref.slice("refs/heads/".length)
+                : ref;
+        }
+        // `detached`, `bare`, `HEAD <sha>`, and blank lines carry no branch.
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+/** Run `git worktree list --porcelain` from the repo root and parse the result. */
+export async function listGitWorktrees(runCommand, cwd) {
+    const result = await runCommand("git", ["worktree", "list", "--porcelain"], { cwd });
+    if (result.exitCode !== 0)
+        return [];
+    return parseGitWorktreePorcelain(result.stdout);
+}
+/**
+ * Return the worktree path whose local branch EXACTLY equals `branch` (not a
+ * substring / prefix match), or `undefined` when none matches.
+ */
+export function findWorktreeByBranch(entries, branch) {
+    const match = entries.find((e) => e.branch === branch);
+    return match?.path;
+}
+/** Run `git rev-parse --abbrev-ref HEAD` inside a worktree and return the branch. */
+export async function getCurrentBranch(runCommand, worktreePath) {
+    const result = await runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+        cwd: worktreePath,
+    });
+    return result.stdout.trim();
+}
+/**
+ * Verify a worktree is on the expected branch; throw {@link ExecutorNamedError}
+ * with kind {@link BranchMismatch} otherwise. Working on the wrong branch would
+ * corrupt an unrelated branch, so this aborts rather than proceeding (TDD §7).
+ */
+export async function assertWorktreeOnBranch(runCommand, worktreePath, expectedBranch) {
+    const actual = await getCurrentBranch(runCommand, worktreePath);
+    if (actual !== expectedBranch) {
+        throw new ExecutorNamedError(BranchMismatch, `worktree '${worktreePath}' is on '${actual}', expected '${expectedBranch}'`);
+    }
+}
+/**
+ * Non-mutating probe for whether `origin/<branch>` exists. Uses
+ * `git rev-parse --verify --quiet origin/<branch>` (exit 0 ⇒ exists). Never
+ * fetches, never writes a ref.
+ */
+export async function remoteBranchExists(runCommand, cwd, branch) {
+    const result = await runCommand("git", ["rev-parse", "--verify", "--quiet", `origin/${branch}`], { cwd });
+    return result.exitCode === 0;
+}

package/build/executor/worktree.js

@@ -0,0 +1,103 @@
+/**
+ * Executor worktree ensure (BAPI-534, TDD §7, §12).
+ *
+ * Real worker jobs run in a Worktrunk-created worktree via the SHARED primitive
+ * (`worktree-core.createWorktreeForTicket`) — no duplicated `wt switch` argument
+ * construction or Worktrunk JSON path parsing here. Per-job create failures are
+ * returned as structured job failures (→ `/fail`), never thrown.
+ */
+import { commandSucceeded } from "../start-tickets-prereqs.js";
+import { createWorktreeForTicket } from "../worktree-core.js";
+/**
+ * Resolve the branch for a real spawn job: `expected_branch` wins; else
+ * `feature/<ticket_key>`; else a structured contract failure.
+ */
+export function resolveExecutorBranch(job) {
+    const expected = typeof job.expected_branch === "string" && job.expected_branch.trim().length > 0
+        ? job.expected_branch.trim()
+        : null;
+    if (expected)
+        return { ok: true, branch: expected };
+    const ticketKey = typeof job.ticket_key === "string" && job.ticket_key.trim().length > 0
+        ? job.ticket_key.trim()
+        : null;
+    if (ticketKey)
+        return { ok: true, branch: `feature/${ticketKey}` };
+    return { ok: false, error: "no branch could be resolved (no expected_branch and no ticket_key)" };
+}
+/** Build the lean shared-worktree deps from the executor deps. */
+function toWorktreeCoreDeps(deps) {
+    return {
+        runCommand: deps.runCommand,
+        platform: deps.platform,
+        env: deps.env,
+        cwd: deps.cwd,
+    };
+}
+/**
+ * Ensure the worktree for a job exists, delegating to the shared Worktrunk
+ * primitive. A create failure is returned as a structured failure that the job
+ * runner can send to `/fail`.
+ *
+ * `policy.reuseExistingBranch` selects between the two supported modes (see
+ * {@link EnsureExecutorWorktreePolicy}); it defaults to the fresh-off-base,
+ * F7-guarded behavior so callers that omit it are unchanged.
+ */
+export async function ensureExecutorWorktree(job, options, deps, policy = {}) {
+    const branchResult = resolveExecutorBranch(job);
+    if (!branchResult.ok)
+        return { ok: false, error: branchResult.error };
+    const branch = branchResult.branch;
+    // The shared primitive resolves the branch from `key` via a per-key override,
+    // so we pin the exact resolved branch through the override map.
+    const key = typeof job.ticket_key === "string" && job.ticket_key.trim().length > 0
+        ? job.ticket_key.trim()
+        : branch;
+    const reuseExistingBranch = policy.reuseExistingBranch === true;
+    // The F7 guard applies to FRESH implementation-style jobs — refuse to reuse a
+    // stale pre-existing branch carrying commits not on base (mirrors the v1
+    // conductor's `!isResume` guard). RECOVERY jobs intentionally continue from the
+    // ticket's bound branch (BAPI-542): they cut from `origin/<branch>` — the pushed
+    // PR branch, so a missing local branch is recreated from it rather than from
+    // base — with the guard OFF, because that branch legitimately carries the
+    // implement commit and later correction rounds.
+    const baseStartPoint = reuseExistingBranch ? `origin/${branch}` : options.baseBranch;
+    const guardStaleWorktree = !reuseExistingBranch;
+    // BAPI-528: recovery correction is ALWAYS post-push (the PR exists), so the
+    // pushed head is the source of truth. Two gaps this closes:
+    //   1. A multi-consumer executor that only cloned/fetched main has NEITHER the
+    //      local branch NOR the `origin/<branch>` tracking ref, so cutting from
+    //      `origin/<branch>` cannot resolve its start point → WorktreeError → the
+    //      run strands at code_review. Fetch the pushed head first so it can.
+    //   2. When a local branch already exists but has DIVERGED from origin, reusing
+    //      it as-is would address review comments on stale code and force-push over
+    //      newer origin commits. Freshen it onto `origin/<branch>` (below).
+    // A failed fetch surfaces as a structured job failure — never a silent stale
+    // reuse. (§16's "no fetch && reset --hard" rule is scoped to the RESUME path,
+    // which must preserve unpushed local work; it does not apply here.)
+    if (reuseExistingBranch) {
+        const originRef = `origin/${branch}`;
+        const fetch = await deps.runCommand("git", ["fetch", "origin", branch], { cwd: deps.cwd });
+        if (!commandSucceeded(fetch)) {
+            const reason = (fetch.stderr || fetch.stdout || "").trim();
+            return {
+                ok: false,
+                error: `git fetch origin ${branch} failed${reason ? `: ${reason}` : ""}`,
+            };
+        }
+        const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseStartPoint, guardStaleWorktree, 
+        // Hard-reset a reused existing local branch onto the freshly fetched
+        // pushed head; a missing local branch is instead cut from `baseStartPoint`
+        // (= `origin/<branch>`) inside the primitive, so both land at origin.
+        { freshenFromOrigin: originRef });
+        if (row.status === "created" && typeof row.path === "string") {
+            return { ok: true, worktreePath: row.path, branch };
+        }
+        return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
+    }
+    const row = await createWorktreeForTicket(toWorktreeCoreDeps(deps), key, { [key]: branch }, options.worktrunkBinary, baseStartPoint, guardStaleWorktree);
+    if (row.status === "created" && typeof row.path === "string") {
+        return { ok: true, worktreePath: row.path, branch };
+    }
+    return { ok: false, error: row.error ?? `worktree creation failed for branch '${branch}'` };
+}