@bridge_gpt/mcp-server 0.2.18 → 0.2.19

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}'` };
+}