@repo-os/repoos 0.5.45

package/dist/server/integration-orchestrator.js

@@ -0,0 +1,1299 @@
+/**
+ * Orchestrates individual close-out jobs through their lifecycle. Each job:
+ *   1. Validates the candidate away from live main (temporary worktree/branch)
+ *   2. Checks for main SHA drift and rebuilds if needed
+ *   3. Publishes only a green candidate while holding the repo lock
+ *   4. Cleans up the candidate and task resources
+ *
+ * Phases track recovery: if interrupted mid-flight, retry resumes from the current phase.
+ */
+import { readFileSync, existsSync, symlinkSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { spawn } from "node:child_process";
+import { currentBranch, runGit, worktreePathForBranch, ensureWorktree, removeWorktree, deleteBranch, pruneWorktrees, isGitRepo, commitDirtyFiles, mergeBranch, dirtyFiles, getDiff, getDiffStats, getChangedFilePaths, GitDirtyCheckError, } from "../core/git.js";
+import { sweepAndWarn } from "../core/worktree-gc.js";
+import { redactSecrets, stripAnsi } from "./done.js";
+import { markTaskReleased } from "./write.js";
+import { saveDiffSnapshot } from "./diff-snapshot.js";
+import { parseTask } from "../core/task.js";
+import { summarizeCheckFailure } from "../core/check-failure-summary.js";
+// Candidate branch prefix. Must be a valid git refname: a leading dot is
+// rejected by git (`'.repoos/integrate/…' is not a valid branch name`), which
+// silently failed every close-out job at worktree creation.
+const CANDIDATE_BRANCH_PREFIX = "repoos/integrate/";
+/** Shared literal for the failed job phase so recovery paths stay consistent. */
+const PHASE_FAILED = "failed";
+/**
+ * Cap on consecutive publish-time "main advanced" resyncs (#0386). Every
+ * OTHER retry path in the close-out pipeline is capped (#0216's validate
+ * retry, handoff.ts's MAX_*_RETRY_ATTEMPTS) — this one wasn't, so on a busy
+ * board a task could restart forever, never winning the race to publish.
+ * Deliberately generous: a single trivial `docs(<id>): update task` commit
+ * for an unrelated task is common and harmless to resync past once or
+ * twice; this only fires once retries are clearly not converging.
+ */
+const MAX_PUBLISH_DRIFT_RETRIES = 5;
+function candidateBranchName(taskId) {
+    return `${CANDIDATE_BRANCH_PREFIX}${taskId}`;
+}
+/**
+ * The merge that just ran left the candidate at exactly base main — it added
+ * nothing. That is legitimate when the feature branch was already fully
+ * integrated (a re-run of a close-out, a branch cherry-picked onto main
+ * earlier): the close-out is idempotent and the task genuinely has nothing
+ * left to land.
+ *
+ * It is a BUG when the branch still carries commits main lacks and the merge —
+ * or, far more often, the conflict auto-resolution in `mergeBranch` — silently
+ * dropped them. Left unguarded, the gate then runs `build` + `check` against
+ * what is effectively bare main (which trivially passes) and the task publishes
+ * as `done` with none of its code integrated. This bit #0306/#0307/#0309/#0312.
+ *
+ * Returns an actionable failure reason in the bug case, `null` when the no-op
+ * is legitimate (or when git errored and a downstream step should surface it).
+ */
+export async function detectDroppedMerge(root, mainBranch, featureBranch, postMergeHead, baseMainSha) {
+    if (postMergeHead !== baseMainSha)
+        return null;
+    // `git diff --quiet A...B` — exit 0: B adds nothing over the merge-base
+    // (branch already in main → legit); exit 1: B carries a real delta that the
+    // merge failed to bring across; >1: git error, leave it for a later step.
+    const delta = await runGit(root, ["diff", "--quiet", `${mainBranch}...${featureBranch}`], 15_000);
+    if (delta.status !== 1)
+        return null;
+    return (`merge of ${featureBranch} produced no change to ${mainBranch}, but the branch still carries ` +
+        `commits ${mainBranch} does not have — the merge, or its conflict auto-resolution, dropped them. ` +
+        `Rebase ${featureBranch} onto ${mainBranch} and resolve the conflicts there, then retry.`);
+}
+/**
+ * Make main's `<workDir>/*.md` state authoritative for every task file the
+ * merged candidate changed that is NOT the closing task's own file, and commit
+ * the restore.
+ *
+ * A feature branch can carry stale edits to other tasks' files — a concurrent
+ * board write, a `repoos` CLI call in the worktree, a partial merge — that git
+ * folds in without a conflict (main untouched since the merge-base), so the
+ * close-out's conflict-only `autoResolveOurs` never catches them and the stale
+ * version publishes to main. This closes that gap: a foreign file modified or
+ * deleted by the branch is restored to main's copy; one the branch newly added
+ * is removed (a close-out never creates another task's file). Returns the paths
+ * touched (empty when there were none); throws only if the git ops fail.
+ *
+ * Exported for tests.
+ */
+export async function resetForeignWorkFiles(opts) {
+    const { candidateWtPath, baseMainSha, workDir, ownWorkFile } = opts;
+    const changed = await runGit(candidateWtPath, ["diff", "--name-only", `${baseMainSha}..HEAD`, "--", workDir], 10_000);
+    if (changed.status !== 0)
+        return [];
+    const foreign = changed.stdout
+        .split("\n")
+        .map((s) => s.trim())
+        .filter((p) => p && p.endsWith(".md") && p !== ownWorkFile);
+    if (foreign.length === 0)
+        return [];
+    // Partition by whether the file exists at main's tip: modified/deleted files
+    // get main's version back; branch-added files get removed.
+    const onMain = [];
+    const addedByBranch = [];
+    for (const p of foreign) {
+        const exists = await runGit(candidateWtPath, ["cat-file", "-e", `${baseMainSha}:${p}`], 5_000);
+        (exists.status === 0 ? onMain : addedByBranch).push(p);
+    }
+    if (onMain.length > 0) {
+        const restore = await runGit(candidateWtPath, ["checkout", baseMainSha, "--", ...onMain], 15_000);
+        if (restore.status !== 0) {
+            throw new Error(`could not restore unrelated task files: ${restore.stderr.trim()}`);
+        }
+        await runGit(candidateWtPath, ["add", "--", ...onMain], 10_000);
+    }
+    if (addedByBranch.length > 0) {
+        const removed = await runGit(candidateWtPath, ["rm", "-q", "--", ...addedByBranch], 10_000);
+        if (removed.status !== 0) {
+            throw new Error(`could not drop stray task files: ${removed.stderr.trim()}`);
+        }
+    }
+    const staged = await runGit(candidateWtPath, ["diff", "--cached", "--quiet"], 10_000);
+    if (staged.status !== 1)
+        return []; // nothing actually differed after all
+    await runGit(candidateWtPath, [
+        "commit",
+        "--no-edit",
+        "-m",
+        `chore: keep main's copy of ${foreign.length} unrelated task file(s) during close-out`,
+    ], 10_000);
+    return foreign;
+}
+/**
+ * Whether a candidate's merged diff is documentation-only, so the expensive
+ * build + check gate in `validateCandidate` can be skipped (#0355).
+ *
+ * Deliberately literal and mechanical: a path qualifies only if it lives under
+ * `docs/` or `user-docs/`, or ends in `.md`. The closing task's own
+ * `work/<id>-*.md` file is the common `.md` case — it always changes, and
+ * `resetForeignWorkFiles` has already restored every OTHER task's work file to
+ * main's copy before this runs, so no foreign task file reaches this check.
+ * Anything else — `repoos.toml`, `package.json`, `src/`, `scripts/`,
+ * `.github/`, … — disqualifies the fast path. No scoring, no "mostly docs".
+ *
+ * An empty path list is vacuously docs-only: a legitimate no-op merge (the
+ * branch was already fully integrated) leaves nothing for build/test to
+ * examine, and the dropped-merge guard in `validateCandidate` runs earlier and
+ * already rejects an empty merge that actually swallowed real branch work.
+ */
+export function isDocsOnlyChange(paths) {
+    return paths.every((p) => p.startsWith("docs/") || p.startsWith("user-docs/") || p.endsWith(".md"));
+}
+/**
+ * Resolve the repository's actual default branch name.
+ * Tries (in order):
+ * 1. git symbolic-ref refs/remotes/origin/HEAD (when remote exists)
+ * 2. git config --get init.defaultBranch
+ * 3. currently checked-out branch
+ * 4. fallback to "main"
+ */
+/**
+ * Whether this project is expected to build its own `dist/cli/index.js` at
+ * all. True only for RepoOS itself (self-hosting) and any other managed
+ * project that happens to declare the same `bin` target — the vast majority
+ * of managed projects (a Vue app, a backend service, ...) never produce a
+ * CLI there, so a missing local CLI for them is normal, not a regression.
+ * Detected via `package.json`'s `bin` field rather than a name check so any
+ * project that legitimately ships a `dist/cli/index.js` binary is covered.
+ */
+function expectsOwnCli(wtPath) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(wtPath, "package.json"), "utf8"));
+        const binPaths = typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin ?? {});
+        return binPaths.some((p) => p.replace(/^\.\//, "") === "dist/cli/index.js");
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveDefaultBranch(root) {
+    // Try remote HEAD first (most reliable for cloned repos)
+    const remoteHeadRes = await runGit(root, ["symbolic-ref", "refs/remotes/origin/HEAD"], 4000);
+    if (remoteHeadRes.status === 0) {
+        // Output format: "ref: refs/remotes/origin/main" -> extract "main"
+        const match = remoteHeadRes.stdout.trim().match(/refs\/remotes\/origin\/(.+)$/);
+        if (match)
+            return match[1];
+    }
+    // Try init.defaultBranch config
+    const configRes = await runGit(root, ["config", "--get", "init.defaultBranch"], 4000);
+    if (configRes.status === 0 && configRes.stdout.trim()) {
+        return configRes.stdout.trim();
+    }
+    // Fall back to currently checked-out branch
+    const currentRes = await runGit(root, ["rev-parse", "--abbrev-ref", "HEAD"], 4000);
+    if (currentRes.status === 0 && currentRes.stdout.trim() && currentRes.stdout.trim() !== "HEAD") {
+        return currentRes.stdout.trim();
+    }
+    // Final fallback
+    return "main";
+}
+// How much of a failed command's output to keep as the failure reason.
+const TAIL_LINES = 15;
+const TAIL_MAX_CHARS = 800;
+/**
+ * Locate a task's file directly on disk by id, independent of the live
+ * index's freshness. Used only as a fallback when `getTask` misses — the
+ * normal, common path is the index lookup, which is far cheaper than a
+ * directory scan. Task ids are unique by filename convention (`<id>-*.md`).
+ */
+function findTaskFileById(root, workDir, taskId) {
+    const dir = join(root, workDir);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return null;
+    }
+    const match = entries.find((f) => f.startsWith(`${taskId}-`) && f.endsWith(".md"));
+    return match ? join(dir, match) : null;
+}
+/**
+ * The useful part of a failed command's combined output. bun/npm wrap a child
+ * failure with a generic trailing line (`error: script "repoos" exited with
+ * code 1`) that is useless as a reason on its own, so keep the last several
+ * meaningful lines — the real cause (a failing test, a compiler error) sits
+ * just above the wrapper.
+ *
+ * The reason is persisted to `.repoos/integration-jobs/<id>.json` and shown
+ * verbatim in the UI, so it must be free of ANSI escapes (the gate's test
+ * output is colored) and of anything that looks like a credential. When the
+ * excerpt exceeds the character cap it is cut from the front at a WORD
+ * boundary — cutting mid-word produced reasons like `check failed: …eletion
+ * detected by…` (0215) that read as garbage.
+ */
+export function tailLine(stdout, stderr) {
+    const cleaned = redactSecrets(stripAnsi(`${stdout}\n${stderr}`));
+    // Vitest's final lines are usually the least useful part of a failure: a
+    // partial received/expected diff followed by its generic runner summary.
+    // Prefer its explicit FAIL block when present; the full transcript remains
+    // available in the task's Debug tab.
+    const testFailure = summarizeCheckFailure(cleaned);
+    if (testFailure)
+        return testFailure;
+    const lines = cleaned
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+    if (lines.length === 0)
+        return "unknown error";
+    let tail = lines.slice(-TAIL_LINES).join("\n");
+    if (tail.length > TAIL_MAX_CHARS) {
+        const cut = tail.length - TAIL_MAX_CHARS;
+        const lastWs = Math.max(tail.lastIndexOf(" ", cut), tail.lastIndexOf("\n", cut));
+        const start = lastWs >= 0 ? lastWs + 1 : cut;
+        return `…${tail.slice(start)}`;
+    }
+    return tail;
+}
+function runProcess(cmd, args, opts) {
+    return new Promise((resolve) => {
+        const child = spawn(cmd, args, { cwd: opts.cwd, env: opts.env });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let errorCode;
+        let settled = false;
+        let timer;
+        const finish = (status) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve({ status, stdout, stderr, timedOut, errorCode });
+        };
+        child.stdout.on("data", (d) => {
+            const text = d.toString("utf8");
+            stdout += text;
+            opts.onChunk?.(text);
+        });
+        child.stderr.on("data", (d) => {
+            const text = d.toString("utf8");
+            stderr += text;
+            opts.onChunk?.(text);
+        });
+        child.on("error", (err) => {
+            errorCode = err.code;
+            finish(null);
+        });
+        child.on("close", (code) => finish(code));
+        timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, opts.timeout);
+    });
+}
+/**
+ * True when the command couldn't be launched at all (not installed), as
+ * opposed to running and failing. Only then is falling back to another tool
+ * (npm instead of bun) useful; a build that ran and failed is the real result.
+ */
+function commandMissing(res) {
+    return res.errorCode === "ENOENT" || res.errorCode === "EACCES";
+}
+/** Candidate validation and publication orchestrator for one job. */
+export class CloseOutOrchestrator {
+    config;
+    coordinator;
+    repoLock;
+    rootLock;
+    getTask;
+    onProgress;
+    logger;
+    onMergeConflict;
+    remoteValidator;
+    taskChecks;
+    onTaskCheckEvent;
+    constructor(config, coordinator, repoLock, rootLock, getTask, onProgress, logger, 
+    /**
+     * Fired when `validating` fails on a REAL, named merge conflict (never
+     * for the task's own bookkeeping file or generated paths, which
+     * auto-resolve; never for infra failures). The job itself is still
+     * marked `failed` as before — this is a separate, best-effort trigger
+     * to auto-resume the engineer to fix it and resubmit (#0271 follow-up).
+     */
+    onMergeConflict, 
+    /**
+     * Runs the expensive half of the gate (build + test) on a cloud VM when
+     * `config.remoteValidation.enabled` — see validateCandidate. Undefined
+     * disables remote validation regardless of config.
+     */
+    remoteValidator, 
+    /** Records the MTD merge-gate `repoos check` run for the Debug tab (0310). */
+    taskChecks, onTaskCheckEvent) {
+        this.config = config;
+        this.coordinator = coordinator;
+        this.repoLock = repoLock;
+        this.rootLock = rootLock;
+        this.getTask = getTask;
+        this.onProgress = onProgress;
+        this.logger = logger;
+        this.onMergeConflict = onMergeConflict;
+        this.remoteValidator = remoteValidator;
+        this.taskChecks = taskChecks;
+        this.onTaskCheckEvent = onTaskCheckEvent;
+    }
+    /**
+     * Whether the task is, on disk, already `done`. The live index is an
+     * in-memory cache that can lag the actual file (a duplicate/stale close-out
+     * — #0289 — can run right after the first successful publish, before the
+     * index rebuilds), so this reads the authoritative task file directly,
+     * falling back to the index only when the file cannot be located or parsed.
+     */
+    taskIsDone(taskId) {
+        const live = this.getTask?.(taskId);
+        const workDir = this.config.workDir;
+        const path = live?.absPath ?? (workDir ? findTaskFileById(this.config.root, workDir, taskId) : null);
+        if (path && existsSync(path)) {
+            try {
+                const task = parseTask({
+                    content: readFileSync(path, "utf8"),
+                    absPath: path,
+                    root: this.config.root,
+                    defaultStatus: this.config.defaultStatus ?? "inbox",
+                    defaultAssignee: this.config.defaultAssignee ?? "unassigned",
+                });
+                if (task.status === "done")
+                    return true;
+            }
+            catch {
+                /* fall through to the index below */
+            }
+        }
+        return live?.status === "done";
+    }
+    /**
+     * Record a close-out job failure, OR reconcile it away when it is moot.
+     *
+     * A failure is moot when the task is already `done`: the failing job is a
+     * duplicate/stale enqueue against a task that already finished successfully
+     * through an earlier job (#0289). That earlier close-out's cleanup deleted
+     * the worktree/branch, which is exactly why a later redundant enqueue fails
+     * (e.g. "worktree not found"). There is no gate failure here needing a
+     * human's attention, and the failed job record would otherwise sit forever
+     * with no path to resolution, so it is dropped instead.
+     *
+     * Returns the `{ ok, reason }` the caller should return: `ok: true` for a
+     * reconciled (moot) failure so the pipeline treats it as a normal completion
+     * and never surfaces it as an actionable error; `ok: false` for a genuine
+     * failure, which is recorded as `failed` (and `onRecorded`, e.g. the merge-
+     * conflict retry, runs) so the UI and status bar can surface it.
+     */
+    /**
+     * Tear down the `repoos/integrate/<id>` candidate worktree + branch. Safe to
+     * call whether or not the candidate exists. The candidate is a throwaway
+     * scratch area rebuilt from scratch on the next run, so its branch is
+     * force-deleted (git will not see it as merged after a failed job).
+     *
+     * Runs on EVERY terminal job outcome — success (`cleanup`), genuine failure,
+     * and moot/reconciled — so a candidate never outlives its job. Without this,
+     * every failed close-out leaked a worktree that inflated cold-boot `git
+     * status` fan-out until someone ran gc.
+     */
+    removeCandidate(taskId) {
+        const root = this.config.root;
+        const branch = candidateBranchName(taskId);
+        removeWorktree(root, branch);
+        deleteBranch(root, branch, { force: true });
+        pruneWorktrees(root);
+    }
+    failOrReconcile(job, failedPhase, reason, onRecorded) {
+        this.removeCandidate(job.taskId);
+        if (this.taskIsDone(job.taskId)) {
+            this.logger?.integration(job.taskId, "info", "close-out failure is moot — task already done; dropping job", { reason });
+            this.coordinator.removeJob(job.taskId);
+            return { ok: true };
+        }
+        this.coordinator.updateJob(job.taskId, { phase: PHASE_FAILED, failedPhase, reason });
+        onRecorded?.();
+        return { ok: false, reason };
+    }
+    /**
+     * Process the next job in the queue: validate and publish it.
+     * Phases are atomic; a retry at any phase resumes from that phase.
+     * May return early if the job transitions back to an earlier phase (e.g., on main drift).
+     */
+    async processNext() {
+        const job = this.coordinator.peekNext();
+        if (!job)
+            return { ok: true, reason: "queue empty" };
+        return this.processJob(job);
+    }
+    async processJob(job) {
+        const root = this.config.root;
+        this.logger?.integration(job.taskId, "info", `Processing job phase: ${job.phase}`, {
+            taskId: job.taskId,
+            phase: job.phase,
+        });
+        try {
+            if (!isGitRepo(root)) {
+                return { ok: false, reason: "not a git repository" };
+            }
+            // Transition from queued to syncing.
+            if (job.phase === "queued") {
+                const updated = this.coordinator.updateJob(job.taskId, {
+                    phase: "syncing",
+                    startedAt: new Date().toISOString(),
+                });
+                if (!updated)
+                    return { ok: false, reason: "job disappeared" };
+                job = updated;
+            }
+            // Syncing phase: ensure the candidate worktree exists and is up to date with main.
+            if (job.phase === "syncing") {
+                const syncRes = await this.syncCandidate(job);
+                if (!syncRes.ok) {
+                    this.logger?.integration(job.taskId, "error", "sync failed", { reason: syncRes.reason });
+                    if (syncRes.conflict) {
+                        // A real conflict caught by the pre-flight (#0358): the candidate
+                        // worktree was never created, but the outcome is identical to one
+                        // found during `validating` — same reason format, same
+                        // non-retryable handling, same repair handoff. Recorded against
+                        // `validating` so nothing downstream can tell the timing moved.
+                        return this.failOrReconcile(job, "validating", syncRes.reason, () => this.onMergeConflict?.(job.taskId, syncRes.reason));
+                    }
+                    return this.failOrReconcile(job, "syncing", syncRes.reason);
+                }
+                job = this.coordinator.updateJob(job.taskId, { phase: "validating" });
+            }
+            // Validating phase: run the full gate (build, check) on the candidate.
+            //
+            // The gate is retried once before the job is failed (#0216). A false
+            // failure here is expensive — the branch is green, but the task is
+            // stranded in review and the user cannot tell contention from a real
+            // regression. The retry also classifies the failure, which is the part
+            // that actually helps: a genuine defect reproduces with the SAME reason
+            // (Node-version-dependent breakage did exactly this on #0205, failing
+            // identically twice), whereas load-induced failures land on a different
+            // test each run (#0211 failed on two unrelated tests). Two attempts is
+            // the cap — this must never loop.
+            if (job.phase === "validating") {
+                let validateRes = await this.validateCandidate(job);
+                if (!validateRes.ok && validateRes.retryable === false) {
+                    // Deterministic by construction — a second run proves nothing and
+                    // costs the user another full gate cycle.
+                    this.logger?.integration(job.taskId, "error", "validation failed (non-retryable)", {
+                        reason: validateRes.reason,
+                    });
+                    // A named, real conflict (not the task's own bookkeeping file or a
+                    // generated path — those auto-resolve inside validateCandidate and
+                    // never reach here) is the one non-retryable failure with an
+                    // actionable fix: merge main into the FEATURE branch and resolve it
+                    // there. Give the engineer a shot at that automatically instead of
+                    // leaving the job sitting `failed` until a human notices (#0271
+                    // follow-up).
+                    const conflict = validateRes.reason?.startsWith("merge conflict in ");
+                    return this.failOrReconcile(job, "validating", validateRes.reason, conflict ? () => this.onMergeConflict?.(job.taskId, validateRes.reason) : undefined);
+                }
+                if (!validateRes.ok) {
+                    const firstReason = validateRes.reason ?? "unknown";
+                    validateRes = await this.validateCandidate(job);
+                    if (!validateRes.ok) {
+                        const secondReason = validateRes.reason ?? "unknown";
+                        const reason = firstReason === secondReason
+                            ? `${secondReason} — reproduced identically on retry, so this is a real failure in the branch, not machine load`
+                            : `${secondReason} — NOTE: the first attempt failed differently (${firstReason}). Two unrelated failures point at machine load or infrastructure rather than a regression in this branch; check for stray serve processes and retry.`;
+                        return this.failOrReconcile(job, "validating", reason);
+                    }
+                }
+                job = this.coordinator.updateJob(job.taskId, {
+                    phase: "publishing",
+                    candidateSha: validateRes.candidateSha,
+                });
+            }
+            // Publishing phase: merge candidate to live main, holding the repo lock.
+            if (job.phase === "publishing") {
+                const pubRes = await this.publishCandidate(job);
+                if (!pubRes.ok) {
+                    // Check if the job phase was changed by publishCandidate() (e.g., drift handling).
+                    // If it was moved back to "syncing" for retry, don't overwrite it to "failed".
+                    const currentJob = this.coordinator.getJob(job.taskId);
+                    if (currentJob && currentJob.phase === "syncing") {
+                        // Drift detected and handled - will retry on next processNext() call
+                        this.logger?.integration(job.taskId, "info", "main drifted during publish — resyncing", {
+                            reason: pubRes.reason,
+                        });
+                        return pubRes;
+                    }
+                    this.logger?.integration(job.taskId, "error", "publish failed", {
+                        reason: pubRes.reason,
+                    });
+                    return this.failOrReconcile(job, "publishing", pubRes.reason);
+                }
+                job = this.coordinator.updateJob(job.taskId, { phase: "cleanup" });
+            }
+            // Cleanup phase: remove candidate worktree, delete candidate branch, remove task worktree.
+            if (job.phase === "cleanup") {
+                const cleanRes = await this.cleanup(job);
+                if (!cleanRes.ok) {
+                    // Log but don't fail: the merge succeeded, so task is done even if cleanup is messy.
+                    this.logger?.integration(job.taskId, "warn", "cleanup warning", {
+                        reason: cleanRes.reason,
+                    });
+                    console.warn(`Cleanup warning for task ${job.taskId}: ${cleanRes.reason}`);
+                }
+                job = this.coordinator.updateJob(job.taskId, { phase: "done" });
+                this.logger?.integration(job.taskId, "info", "close-out complete — published to main");
+            }
+            return { ok: true };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : "unknown error";
+            this.logger?.integration(job.taskId, "error", "orchestrator error", { reason });
+            return this.failOrReconcile(job, job.phase ?? "unknown", `orchestrator error: ${reason}`);
+        }
+    }
+    /**
+     * Cheap, non-destructive pre-flight (#0358): would merging the task's feature
+     * branch into current main hit a REAL (non-auto-resolvable) conflict?
+     *
+     * Runs BEFORE any candidate worktree exists, in the feature branch's own
+     * worktree (`worktreePathForBranch`, already checked out and cheap to use)
+     * against the CURRENT main SHA, reusing `mergeBranch`'s dry-run mode so the
+     * classification is literally the real merge's — never a second, drifting
+     * definition of "a real conflict". Returns the conflict reason in the exact
+     * format `validateCandidate` uses, or `null` when there is no real conflict.
+     *
+     * Fail-open by construction: a missing feature worktree, any git error, or a
+     * dry-run that cannot run cleanly all return `null`, so the caller falls
+     * through to the existing sync/validate flow rather than blocking on a broken
+     * optimization.
+     */
+    async preflightConflict(job, baseMainSha) {
+        const root = this.config.root;
+        const featureBranch = job.branch ?? job.taskId;
+        // No worktree to run against: let the normal flow report the real failure
+        // ("feature branch … worktree not found") rather than guessing here.
+        const featureWtPath = worktreePathForBranch(root, featureBranch);
+        if (!featureWtPath)
+            return null;
+        const task = this.getTask?.(job.taskId);
+        const autoResolve = ["dist/", "screenshots/", ...(task ? [relative(root, task.absPath)] : [])];
+        // Same semantics as `validateCandidate`: unrelated task files keep main's
+        // side, everything else in `autoResolve` takes the branch's side. Only the
+        // real-conflict classification is needed here, so the direction is moot.
+        const autoResolveOurs = ["work/"];
+        let preflight;
+        try {
+            preflight = await mergeBranch(featureWtPath, baseMainSha, {
+                autoResolve,
+                autoResolveOurs,
+                dryRun: true,
+            });
+        }
+        catch (err) {
+            this.logger?.integration(job.taskId, "warn", "pre-flight conflict check failed — falling through to the normal sync/validate flow", { reason: err instanceof Error ? err.message : String(err) });
+            return null;
+        }
+        if (preflight.merged || preflight.conflicts.length === 0)
+            return null;
+        return (`merge conflict in ${preflight.conflicts.join(", ")} — resolve it in ` +
+            `the feature branch's own worktree (merge main into the branch), then retry`);
+    }
+    async syncCandidate(job) {
+        this.onProgress?.("sync");
+        const root = this.config.root;
+        const branch = candidateBranchName(job.taskId);
+        // Resolve the repository's actual default branch
+        const mainBranch = await resolveDefaultBranch(root);
+        // Record main SHA at validation start.
+        const mainShaRes = await runGit(root, ["rev-parse", `${mainBranch}^{commit}`], 4000);
+        if (mainShaRes.status !== 0) {
+            return { ok: false, reason: "could not get main SHA" };
+        }
+        const baseMainSha = mainShaRes.stdout.trim();
+        this.coordinator.updateJob(job.taskId, { baseMainSha });
+        // Pre-flight (#0358): a real, non-auto-resolvable conflict against current
+        // main is fully knowable from cheap git plumbing, so detect it BEFORE the
+        // candidate worktree is created and route straight to the conflict-repair
+        // handoff the validating phase already uses. This job then never pays for
+        // a candidate worktree (or a doomed merge) just to rediscover a conflict
+        // that was predictable in advance. Any failure of the check itself is
+        // fail-open — fall through to the normal sync/validate flow unchanged.
+        const preflightReason = await this.preflightConflict(job, baseMainSha);
+        if (preflightReason) {
+            return { ok: false, conflict: true, reason: preflightReason };
+        }
+        // Ensure candidate worktree exists and is on main.
+        const wtRes = ensureWorktree(root, branch, `candidate-${job.taskId}`);
+        if (!wtRes.ok) {
+            return { ok: false, reason: `could not create candidate worktree: ${wtRes.reason}` };
+        }
+        // A fresh candidate worktree has no dependencies, and the gate below runs a
+        // full `bun run build` + check. Reuse the main checkout's node_modules via
+        // a symlink instead of a slow cold install; fail-soft so a missing install
+        // surfaces as a build/check error rather than a misleading sync failure.
+        const candidateNodeModules = join(wtRes.path, "node_modules");
+        if (!existsSync(candidateNodeModules)) {
+            const rootNodeModules = join(root, "node_modules");
+            if (existsSync(rootNodeModules)) {
+                try {
+                    symlinkSync(rootNodeModules, candidateNodeModules, "dir");
+                }
+                catch {
+                    /* fail-soft: the build step will report the real error */
+                }
+            }
+        }
+        // Reset candidate to main so it's a clean base for the merge.
+        const resetRes = await runGit(wtRes.path, ["reset", "--hard", mainBranch], 30_000);
+        if (resetRes.status !== 0) {
+            return { ok: false, reason: `could not reset candidate to main: ${resetRes.stderr}` };
+        }
+        // Validate and record the feature branch SHA.
+        const taskBranch = job.branch ?? job.taskId;
+        // Check if the feature branch exists (critical: avoid merging unrelated history)
+        const taskWtPath = worktreePathForBranch(root, taskBranch);
+        if (!taskWtPath) {
+            return { ok: false, reason: `feature branch ${taskBranch} worktree not found` };
+        }
+        const branchShaRes = await runGit(taskWtPath, ["rev-parse", "HEAD"], 4000);
+        if (branchShaRes.status !== 0) {
+            return { ok: false, reason: "could not get feature branch SHA" };
+        }
+        this.coordinator.updateJob(job.taskId, { branchSha: branchShaRes.stdout.trim() });
+        return { ok: true, candidateSha: baseMainSha };
+    }
+    /**
+     * Merge the feature branch into the candidate, then run the gate on it.
+     *
+     * `retryable: false` marks a failure that cannot possibly resolve on a second
+     * identical run — a merge conflict is the same conflict every time — so the
+     * caller can skip its retry instead of spending another few minutes proving
+     * the point. Everything else defaults to retryable: build and check failures
+     * are where genuine flakiness lives.
+     */
+    async validateCandidate(job) {
+        const root = this.config.root;
+        const branch = candidateBranchName(job.taskId);
+        const wtPath = worktreePathForBranch(root, branch);
+        if (!wtPath) {
+            return { ok: false, reason: "candidate worktree not found" };
+        }
+        // Check for main SHA changes. If main advanced, discard candidate and rebuild.
+        const mainBranch = await resolveDefaultBranch(root);
+        const currentMainRes = await runGit(root, ["rev-parse", `${mainBranch}^{commit}`], 4000);
+        if (currentMainRes.status !== 0) {
+            return { ok: false, reason: "could not get current main SHA" };
+        }
+        const currentMainSha = currentMainRes.stdout.trim();
+        if (job.baseMainSha && currentMainSha !== job.baseMainSha) {
+            // Main advanced: discard candidate, rebuild from new SHA, and revalidate.
+            removeWorktree(root, branch);
+            this.coordinator.updateJob(job.taskId, {
+                phase: "syncing",
+                baseMainSha: null,
+                candidateSha: null,
+            });
+            // The resync runs the same pre-flight; a conflict it finds must keep the
+            // non-retryable classification so the caller still routes it to repair.
+            const resync = await this.syncCandidate(job);
+            if (!resync.ok && resync.conflict) {
+                return { ok: false, retryable: false, reason: resync.reason };
+            }
+            return resync;
+        }
+        // Merge feature branch into candidate.
+        const featureBranch = job.branch ?? job.taskId;
+        // Verify feature branch still exists before attempting merge
+        const branchListRes = await runGit(root, ["branch", "--list", featureBranch], 4000);
+        if (branchListRes.status !== 0 || !branchListRes.stdout.trim()) {
+            return { ok: false, reason: `feature branch ${featureBranch} no longer exists` };
+        }
+        // In the candidate worktree, merge the feature branch from its location.
+        // dist/ and screenshots/ are generated output — the build step right
+        // after this merge (below) regenerates them from source regardless of
+        // what the merge produced, so a conflict there must never block the
+        // merge. The task's own doc file routinely differs between main and the
+        // branch (status/review_rounds bookkeeping on either side), so its
+        // branch version is taken as authoritative, same as the legacy done.ts
+        // close-out path. Reuses the existing, tested autoResolve semantics in
+        // core/git.ts rather than reimplementing conflict resolution here.
+        //
+        // dist/ is gitignored on main as of 2026-08-15 (see docs/dogfooding-vs-
+        // general.md), so most new merges won't touch this entry at all — a
+        // branch that never modified dist/ resolves as a clean deletion. It stays
+        // in the list because a branch cut BEFORE that change can still have
+        // dist/ tracked and modified; mergeBranch's `-X theirs` fallback already
+        // handles that as a modify/delete conflict. Safe to drop once no such
+        // branch remains, but harmless to leave indefinitely.
+        const task = this.getTask?.(job.taskId);
+        const autoResolve = ["dist/", "screenshots/", ...(task ? [relative(root, task.absPath)] : [])];
+        // The task currently closing is authoritative on its branch. Other task
+        // files can change independently on main (for example, a CTO nudge), so
+        // preserve main's version for those rather than blocking close-out.
+        const autoResolveOurs = ["work/"];
+        this.onProgress?.("merge");
+        const merge = await mergeBranch(wtPath, featureBranch, { autoResolve, autoResolveOurs });
+        if (!merge.merged) {
+            // A conflict is a property of the two trees, not of the machine. Retrying
+            // re-derives the identical conflict; the fix is always to merge main into
+            // the feature branch and resolve it there (see docs/close-out-pipeline.md).
+            return {
+                ok: false,
+                retryable: false,
+                reason: merge.conflicts.length
+                    ? `merge conflict in ${merge.conflicts.join(", ")} — resolve it in the feature branch's own worktree (merge main into the branch), then retry`
+                    : (merge.reason ?? "merge failed"),
+            };
+        }
+        // The merge "succeeded" but must have actually changed something, unless
+        // the branch was already fully in main. A no-op merge that swallowed real
+        // branch work would otherwise sail through the gate (it validates bare
+        // main) and publish the task as done with nothing integrated (#0306 et al).
+        const postMergeHead = await runGit(wtPath, ["rev-parse", "HEAD"], 4000);
+        if (postMergeHead.status === 0) {
+            const dropped = await detectDroppedMerge(root, mainBranch, featureBranch, postMergeHead.stdout.trim(), currentMainSha);
+            if (dropped) {
+                return { ok: false, retryable: false, reason: dropped };
+            }
+        }
+        // A clean merge still carries any edits the feature branch made to OTHER
+        // tasks' work/*.md files (branch changed them, main did not touch them since
+        // the merge-base → git merged them with no conflict, so `autoResolveOurs`,
+        // which only runs on conflicts, never fired). Restore main's copy of each.
+        // Observed live: #0319's close-out published #0202/#0275 frontmatter drift.
+        try {
+            const reset = await resetForeignWorkFiles({
+                candidateWtPath: wtPath,
+                baseMainSha: currentMainSha,
+                workDir: this.config.workDir,
+                ownWorkFile: task ? relative(root, task.absPath) : null,
+            });
+            if (reset.length > 0) {
+                this.logger?.integration(job.taskId, "info", "restored unrelated task files to main during close-out", { files: reset });
+            }
+        }
+        catch (err) {
+            this.logger?.integration(job.taskId, "warn", "could not restore unrelated task files during close-out", { reason: err instanceof Error ? err.message : String(err) });
+        }
+        // Check for merge conflict markers in text files (unresolved conflicts in content).
+        const lsRes = await runGit(wtPath, ["ls-files"], 5000);
+        if (lsRes.status === 0) {
+            const files = lsRes.stdout.split("\n").filter(Boolean);
+            const textExtensions = [".json", ".md", ".ts", ".tsx", ".js", ".jsx", ".css", ".html"];
+            for (const file of files) {
+                if (textExtensions.some((ext) => file.endsWith(ext))) {
+                    try {
+                        const content = readFileSync(join(wtPath, file), "utf8");
+                        // Check for git conflict markers: exactly 7 of each character at line start
+                        if (/^<{7}$|^={7}$|^>{7}$/m.test(content)) {
+                            return { ok: false, reason: `unresolved conflict markers in ${file}` };
+                        }
+                    }
+                    catch {
+                        /* skip unreadable files */
+                    }
+                }
+            }
+        }
+        // Docs-only fast path (#0355): a candidate whose merged diff touches
+        // nothing but documentation cannot be affected by build/typecheck/tests/
+        // ui-smoke, so the whole expensive post-merge gate is skipped. The
+        // predicate is literal — ANY path outside the allowlist (one line in
+        // src/, repoos.toml, package.json, scripts/, .github/, …) runs the full
+        // gate unchanged — and a git error (`null`) always fails safe to the full
+        // gate too.
+        const changedPaths = await getChangedFilePaths(wtPath, mainBranch);
+        const docsOnly = changedPaths !== null && isDocsOnlyChange(changedPaths);
+        if (docsOnly) {
+            this.logger?.integration(job.taskId, "info", "docs-only candidate — skipping the full build + check gate (no code/source paths changed)", { paths: changedPaths });
+        }
+        else {
+            // Run the post-merge gate: build + check via bun/npm.
+            this.onProgress?.("build");
+            let buildRes = await runProcess("bun", ["run", "build"], { cwd: wtPath, timeout: 300_000 });
+            if (commandMissing(buildRes)) {
+                buildRes = await runProcess("npm", ["run", "build"], { cwd: wtPath, timeout: 300_000 });
+            }
+            if (buildRes.status !== 0) {
+                return { ok: false, reason: `build failed: ${tailLine(buildRes.stdout, buildRes.stderr)}` };
+            }
+            // Remote Validation Runner (docs/remote-validation.md): hand the expensive
+            // half of the gate — `bun install` + `bun run build` + `bun run test` — to a
+            // disposable cloud VM, which is where MTD keeps failing under local memory
+            // pressure. On a remote pass, the LOCAL `repoos check` below runs only the
+            // cheap static guards + UI smoke (REPOOS_SKIP_TESTS=1). On a transient infra
+            // failure the job fails RETRYABLY (resumes from this phase) unless
+            // `remoteValidation.fallbackToLocal` is set; a real remote test failure is
+            // non-retryable — fix it in the feature branch and resubmit.
+            let skipTestsLocally = false;
+            if (this.remoteValidator && this.config.remoteValidation?.enabled) {
+                this.onProgress?.("check");
+                const headRes = await runGit(wtPath, ["rev-parse", "HEAD"], 4000);
+                if (headRes.status !== 0) {
+                    return { ok: false, reason: "could not resolve candidate HEAD before remote validation" };
+                }
+                const remote = await this.remoteValidator.validate({
+                    taskId: job.taskId,
+                    worktreePath: wtPath,
+                    candidateSha: headRes.stdout.trim(),
+                });
+                if (remote.ok) {
+                    skipTestsLocally = true;
+                }
+                else if (remote.transient && !this.config.remoteValidation.fallbackToLocal) {
+                    return {
+                        ok: false,
+                        retryable: true,
+                        reason: `${remote.detail ?? "remote validation unavailable"} — the branch IS merged into the candidate; retrying resumes from the check step`,
+                    };
+                }
+                else if (!remote.transient) {
+                    return {
+                        ok: false,
+                        retryable: false,
+                        reason: `remote validation failed: ${remote.detail ?? "build or test suite failed on the runner"} — fix it in the feature branch and resubmit`,
+                    };
+                }
+                else {
+                    this.logger?.integration(job.taskId, "warn", "remote validation unavailable — falling back to the full local gate (remoteValidation.fallbackToLocal)", { detail: remote.detail });
+                }
+            }
+            this.onProgress?.("check");
+            // The candidate's OWN freshly-built CLI comes first, same as the legacy
+            // done.ts close-out gate (#0130): a globally linked `repoos` resolves
+            // build freshness and gate code against its own install snapshot, which
+            // can disagree with the checkout actually being validated here. Running
+            // `check` via the candidate's own `dist/cli/index.js` guarantees the gate
+            // evaluates the exact code that was just merged and built above.
+            // The build above already ran `bun run build` with nothing changed since,
+            // and `bun run build` is staleness-aware now (#0377), so `check`'s own
+            // "Full build" step detects the fresh marker and skips itself — no
+            // private skip env flag needed.
+            const checkEnv = {
+                ...process.env,
+                ...(skipTestsLocally ? { REPOOS_SKIP_TESTS: "1" } : {}),
+            };
+            const localCli = join(wtPath, "dist", "cli", "index.js");
+            const localCliPresent = existsSync(localCli);
+            const checkHandle = this.taskChecks && this.onTaskCheckEvent
+                ? this.taskChecks.start(job.taskId, "merge-gate", this.onTaskCheckEvent)
+                : undefined;
+            const rawCheck = (cli, args) => runProcess(cli, args, {
+                cwd: wtPath,
+                timeout: 600_000,
+                env: checkEnv,
+                onChunk: checkHandle?.chunk,
+            });
+            // A check whose ONLY failure is a stale build marker: the same marker the
+            // close-out build above should have refreshed. This is the self-resolving
+            // staleness pattern (#0276 Flavour B) — refreshing the marker and re-running
+            // the identical check on the same tree passes. Cases that are NOT this (a
+            // genuine non-staleness failure, or the local CLI being absent entirely) must
+            // not be absorbed; see the branching below.
+            const isStalenessFailure = (res) => /stale build|no build found|build-info\.json|build is stale|cannot verify build freshness/i.test(`${res.stdout}\n${res.stderr}`);
+            let checkRes;
+            // Why the check result deviates from a plain local-CLI pass:
+            //   'local-ok'     — candidate's own CLI passed (common case)
+            //   'absorbed'     — local CLI reported staleness; marker refreshed and
+            //                    re-check passed on the same tree (self-resolving)
+            //   'fallback'     — local CLI failed for a genuine non-staleness reason;
+            //                    fell through to the global CLI fallback
+            //   'local-missing'— candidate's own CLI was absent AND this project is
+            //                    meant to build one — only the global CLI fallback
+            //                    could run (Flavour A, not self-resolving)
+            //   'no-cli-expected' — candidate's own CLI was absent, but this project
+            //                    never builds a dist/cli/index.js at all (the common
+            //                    case for a managed web/backend project) — the
+            //                    fallback is expected, not a regression signal
+            let outcome;
+            if (!localCliPresent) {
+                // Only a project that is itself meant to build dist/cli/index.js
+                // (RepoOS self-hosting, or another project with the same bin target)
+                // can suffer the #0213/3fbbd707 CLI-selection regression, where the
+                // global CLI fallback compares this candidate's src hash against a
+                // DIFFERENT install's marker — a guaranteed "stale" mismatch regardless
+                // of how fresh the candidate really is. For every other managed
+                // project (the common case) there was never a local CLI to find, so a
+                // missing one is expected, not a regression; labelling it as one on
+                // every such MTD (#0345) buried the real failure reason behind a false
+                // lead.
+                const cliExpected = expectsOwnCli(wtPath);
+                checkRes = await rawCheck("repoos", ["check"]);
+                outcome = cliExpected ? "local-missing" : "no-cli-expected";
+                if (cliExpected) {
+                    this.logger?.integration(job.taskId, "error", "candidate dist/cli/index.js is missing — gate fell back to the globally linked repoos; any 'stale' result here is a CLI-selection regression (#0276 Flavour A), not self-resolving staleness");
+                }
+            }
+            else {
+                checkRes = await rawCheck(process.execPath, [localCli, "check"]);
+                if (checkRes.status === 0) {
+                    outcome = "local-ok";
+                }
+                else if (isStalenessFailure(checkRes)) {
+                    // Self-resolving build staleness: only the stale-marker report failed,
+                    // and that same marker is what `bun run build` below refreshes. Refresh
+                    // it provably for the current source — `bun run build` is
+                    // staleness-aware (#0377) and rebuilds because the marker is stale —
+                    // then re-run the SAME check on the same candidate tree. Bounded to
+                    // this one re-check — it never loops, and it stays inside
+                    // validateCandidate rather than triggering an extra orchestrator-level
+                    // retry / re-sync / debugger.
+                    this.logger?.integration(job.taskId, "info", "check reported self-resolving build staleness — refreshing marker and re-checking the same tree in place (no debugger detour)");
+                    await runProcess("bun", ["run", "build"], { cwd: wtPath, timeout: 300_000 });
+                    checkRes = await rawCheck(process.execPath, [localCli, "check"]);
+                    if (checkRes.status !== 0) {
+                        checkHandle?.done(checkRes.status);
+                        return {
+                            ok: false,
+                            reason: `check failed after in-place staleness re-check: ${tailLine(checkRes.stdout, checkRes.stderr)}`,
+                        };
+                    }
+                    outcome = "absorbed";
+                }
+                else {
+                    // Genuine non-staleness failure from the local CLI: preserve the prior
+                    // fallback behaviour (retry via the global repoos, then bun run repoos).
+                    outcome = "fallback";
+                    checkRes = await rawCheck("repoos", ["check"]);
+                    if (checkRes.status !== 0) {
+                        checkRes = await rawCheck("bun", ["run", "repoos", "check"]);
+                    }
+                }
+            }
+            checkHandle?.done(checkRes.status);
+            if (checkRes.status !== 0) {
+                return {
+                    ok: false,
+                    reason: outcome === "local-missing"
+                        ? `check failed: the candidate's own dist/cli/index.js was not used (CLI-selection regression — the globally linked repoos evaluates a different install's build marker). ${tailLine(checkRes.stdout, checkRes.stderr)}`
+                        : `check failed: ${tailLine(checkRes.stdout, checkRes.stderr)}`,
+                };
+            }
+        }
+        // Candidate is green. Capture its SHA.
+        const candidateShaRes = await runGit(wtPath, ["rev-parse", "HEAD"], 4000);
+        if (candidateShaRes.status !== 0) {
+            return { ok: false, reason: "could not get candidate SHA after validation" };
+        }
+        // Capture the reviewable source diff before publication removes the task
+        // branch/worktree. The candidate is based on the exact main SHA checked
+        // above and contains the validated feature merge, so this records the
+        // precise change that is about to land (not a later, polluted main diff).
+        const snapshotDiff = await getDiff(wtPath, mainBranch);
+        const snapshotStats = getDiffStats(wtPath, mainBranch);
+        saveDiffSnapshot(root, this.config.cacheDir, job.taskId, snapshotStats, snapshotDiff);
+        return { ok: true, candidateSha: candidateShaRes.stdout.trim() };
+    }
+    async publishCandidate(job) {
+        const root = this.config.root;
+        const mainBranch = await resolveDefaultBranch(root);
+        const branch = candidateBranchName(job.taskId);
+        const wtPath = worktreePathForBranch(root, branch);
+        if (!wtPath) {
+            return { ok: false, reason: "candidate worktree missing at publish time" };
+        }
+        // Acquire the repository lock before publishing.
+        if (this.repoLock) {
+            let acquireAttempts = 0;
+            while (!this.repoLock.acquire(job.taskId) && acquireAttempts < 60) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                acquireAttempts++;
+            }
+            if (acquireAttempts >= 60) {
+                return { ok: false, reason: "could not acquire publication lock (timeout)" };
+            }
+        }
+        // Publishing mutates the live checkout.  It must therefore mutually
+        // exclude a hotfix, which also owns that checkout for its entire run.
+        // Acquire after the publication lock so concurrent close-outs retain
+        // their existing serialization, but before inspecting or merging main.
+        if (this.rootLock && !this.rootLock.acquire(job.taskId, "close-out")) {
+            const holder = this.rootLock.getHolder();
+            this.repoLock?.release(job.taskId);
+            return {
+                ok: false,
+                reason: `main checkout is held by ${holder?.kind ?? "another operation"} (task #${holder?.taskId ?? "unknown"}); wait for it to finish before moving this task to done`,
+            };
+        }
+        try {
+            // Final SHA check: ensure candidate is still based on current main (holding the lock).
+            const currentMainRes = await runGit(root, ["rev-parse", `${mainBranch}^{commit}`], 4000);
+            if (currentMainRes.status !== 0) {
+                return { ok: false, reason: "could not verify main before publish" };
+            }
+            const currentMainSha = currentMainRes.stdout.trim();
+            if (job.baseMainSha !== currentMainSha) {
+                // Main advanced between validation and publishing. Every OTHER retry
+                // path in this close-out pipeline is capped (#0216's validate-phase
+                // 2-attempt cap; handoff.ts's MAX_*_RETRY_ATTEMPTS for merge-conflict/
+                // check-failure/handoff-signal repairs) — this one wasn't, so a task
+                // whose sync→validate→publish cycle takes longer than the interval
+                // between OTHER tasks landing on main could retry forever, never
+                // winning the race. Reproduced live twice in one session (#0376,
+                // #0382): 3-4 consecutive resets, ~2 minutes each, on a busy board.
+                const driftCount = (job.publishDriftCount ?? 0) + 1;
+                if (driftCount > MAX_PUBLISH_DRIFT_RETRIES) {
+                    // Deliberately do NOT set phase: "syncing" here — leaving it
+                    // unchanged (still "publishing") means processJob's own existing
+                    // `currentJob.phase === "syncing"` check below is false, so it
+                    // falls through to failOrReconcile exactly the way a genuine
+                    // publish failure already does. No new give-up path needed; this
+                    // reuses the one that's already there.
+                    return {
+                        ok: false,
+                        reason: `main advanced ${driftCount} times in a row while trying to publish — giving up ` +
+                            "rather than retrying forever. The branch itself is fine, it's just losing the race " +
+                            "to land; retry Move-to-done once main quiets down.",
+                    };
+                }
+                removeWorktree(root, branch);
+                this.coordinator.updateJob(job.taskId, {
+                    phase: "syncing",
+                    baseMainSha: null,
+                    candidateSha: null,
+                    publishDriftCount: driftCount,
+                });
+                return { ok: false, reason: "main advanced, revalidating" };
+            }
+            // Ensure the main checkout is on the actual main branch before merging.
+            // A branch-mode hotfix leaves the main checkout on its hotfix branch
+            // (ensureHotfix checks it out there). Merging the candidate into the
+            // hotfix branch instead of main silently succeeds (FF or no-op) but
+            // leaves main unchanged and blocks hotfix-branch cleanup. Switch to
+            // main first so the merge, dirty check, and subsequent branch deletion
+            // all target the correct branch.
+            const currentHead = currentBranch(root);
+            if (currentHead && currentHead !== mainBranch) {
+                const checkoutRes = await runGit(root, ["checkout", mainBranch], 10_000);
+                if (checkoutRes.status !== 0) {
+                    return {
+                        ok: false,
+                        reason: `could not switch main checkout from ${currentHead} to ${mainBranch} before publishing (${checkoutRes.stderr.trim()}). The candidate was NOT merged; retry.`,
+                    };
+                }
+            }
+            // Publish-time dirty-main guard (#0211): the main working tree can be
+            // dirtied between enqueue and publish (validation runs minutes-long
+            // builds in the candidate worktree while `repoos check` regenerates a
+            // dirty `dist/` on main). Re-check right before the merge so a dirty
+            // main is surfaced as an actionable message instead of git's raw
+            // "your local changes would be overwritten" at the tail of a long job.
+            // Fails closed: an error/timeout in the check is "unknown", never
+            // "clean", so we never merge blindly.
+            let dirtyOnMain;
+            try {
+                dirtyOnMain = await dirtyFiles(root);
+            }
+            catch (err) {
+                if (err instanceof GitDirtyCheckError) {
+                    return {
+                        ok: false,
+                        reason: `could not verify main is clean at publish time (${err.message}). The candidate was NOT merged; retry, or commit/stash main's working tree first.`,
+                    };
+                }
+                throw err;
+            }
+            if (dirtyOnMain.length > 0) {
+                // Auto-checkpoint routine, server-written churn instead of blocking
+                // the merge on it (#0271 follow-up, confirmed live: #0293's close-out
+                // was refused because an UNRELATED task's `work/*.md` file — an
+                // activity-log stamp from a normal status/override change — was
+                // dirty on main at publish time). Every routine task write already
+                // auto-commits this exact way via `commitTaskFile`/`recordChange`
+                // elsewhere in the system; a task file being dirty for a moment
+                // between that write and this check is expected traffic on a busy
+                // board, not a signal something risky is in flight.
+                //
+                // `repoos.toml` gets the same treatment: it's always written whole by
+                // the settings API (agent config, maxActiveTasks, etc.), never
+                // hand-edited mid-change the way a source file might be, so a dirty
+                // moment there is the same class of routine churn, not a signal of
+                // in-progress human work.
+                //
+                // Scoped narrowly: only when EVERY dirty path is under the work dir
+                // or is exactly `repoos.toml` — anything else (source, other config,
+                // a stray build artifact) still fails closed exactly as before,
+                // since that's genuinely ambiguous and worth a human's attention
+                // rather than a blind auto-commit.
+                const workPrefix = `${this.config.workDir}/`;
+                const isSafeChurn = (p) => p.startsWith(workPrefix) || p === "repoos.toml";
+                const onlySafeChurn = dirtyOnMain.every(isSafeChurn);
+                if (onlySafeChurn) {
+                    try {
+                        await commitDirtyFiles(root, "chore: checkpoint bookkeeping/config before publish");
+                    }
+                    catch {
+                        return {
+                            ok: false,
+                            reason: `main has ${dirtyOnMain.length} uncommitted file${dirtyOnMain.length === 1 ? "" : "s"} at publish time and the automatic checkpoint commit failed: ${dirtyOnMain.slice(0, 8).join(", ")}${dirtyOnMain.length > 8 ? ", …" : ""}. The candidate was NOT merged; commit or stash those on main and retry.`,
+                        };
+                    }
+                }
+                else {
+                    return {
+                        ok: false,
+                        reason: `main has ${dirtyOnMain.length} uncommitted file${dirtyOnMain.length === 1 ? "" : "s"} at publish time, so the merge would abort: ${dirtyOnMain.slice(0, 8).join(", ")}${dirtyOnMain.length > 8 ? ", …" : ""}. The candidate was NOT merged; commit or stash those on main (or use "Commit & continue") and retry.`,
+                    };
+                }
+            }
+            // Merge candidate to live main. Reuses mergeBranch's tested
+            // autoResolve semantics (already used above, in the opposite
+            // direction, to merge main into the candidate worktree) instead of a
+            // hand-rolled ff-only/no-edit pair with no conflict recovery — that
+            // older version left a genuine conflict as a dangling, uncommitted
+            // `git merge` on the LIVE main checkout (MERGE_HEAD set, conflict
+            // markers on disk) rather than aborting it, so every later retry's
+            // dirty-main check just re-discovered the same stuck merge and
+            // reported it as generic "uncommitted changes" (task #0338's
+            // close-out hit exactly this on work/0338-*.md — main had picked up
+            // its own bookkeeping commits for that same task file while the
+            // candidate was in flight, a routine, expected divergence that should
+            // never have blocked a merge in the first place).
+            // dist/screenshots/ are generated output (never worth keeping main's
+            // stale copy over the candidate's); every work/*.md file keeps MAIN's
+            // copy — main is authoritative for task bookkeeping by publish time
+            // (routine writes land there throughout the task's lifetime), the
+            // reverse of the validate-phase merge above where the candidate's own
+            // file is what's being tested in isolation.
+            const publishMerge = await mergeBranch(root, branch, {
+                autoResolve: ["dist/", "screenshots/"],
+                autoResolveOurs: ["work/"],
+            });
+            if (!publishMerge.merged) {
+                if (publishMerge.conflicts.length > 0) {
+                    return {
+                        ok: false,
+                        reason: `main has a genuine merge conflict with the candidate (not auto-resolvable): ${publishMerge.conflicts.slice(0, 8).join(", ")}${publishMerge.conflicts.length > 8 ? ", …" : ""}. The candidate was NOT merged and the attempt was cleanly aborted; resolve this on the branch (merge main into it) and retry.`,
+                    };
+                }
+                // A dirty main that slipped in between the check and the merge
+                // surfaces as git's raw "would be overwritten" failure with no
+                // conflict list — re-frame as an actionable instruction.
+                if (/would be overwritten by merge/i.test(publishMerge.reason ?? "")) {
+                    return {
+                        ok: false,
+                        reason: `main has uncommitted files blocking the merge. The candidate was NOT merged; commit or stash those on main (or use "Commit & continue") and retry.`,
+                    };
+                }
+                return {
+                    ok: false,
+                    reason: `could not merge to main: ${publishMerge.reason ?? "unknown error"}`,
+                };
+            }
+            // Guard against the same failure class detectDroppedMerge exists for
+            // (#0306/#0307/#0309/#0312, see its docstring above): the autoResolve
+            // this merge just used is new here (the old ff-only/no-edit pair had
+            // none), so confirm it didn't silently discard real candidate content
+            // the way conflict auto-resolution has before. Cheap and specific:
+            // only fires when the merge produced no change at all AND the branch
+            // still genuinely differs from main.
+            const postMergeHead = await runGit(root, ["rev-parse", "HEAD"], 4000);
+            if (postMergeHead.status === 0) {
+                const dropped = await detectDroppedMerge(root, mainBranch, branch, postMergeHead.stdout.trim(), currentMainSha);
+                if (dropped) {
+                    return { ok: false, reason: dropped };
+                }
+            }
+            // Rebuild the live checkout's dist/ so the running `repoos serve`
+            // process (which loads compiled JS at boot and never reloads on its
+            // own) has something newer to notice. dist/ is gitignored, so the
+            // merge above brought in new source but left dist/ exactly as it was.
+            // This runs while rootLock/repoLock are still held (released in the
+            // `finally` below), so ReloadManager's closingOut() check correctly
+            // parks the resulting build for a user-triggered reload instead of
+            // restarting the server out from under this still-running publish.
+            // Fail-soft: the merge already succeeded, so a failed rebuild here
+            // must not fail the whole publish — it just leaves dist/ stale, the
+            // same pre-existing failure mode this is fixing, now at least logged.
+            //
+            // Skip entirely when there's no package.json: neither `bun run build`
+            // nor the `npm run build` fallback can ever succeed without one, so
+            // attempting them is two guaranteed-useless subprocess spawns every
+            // time — real cost under load, and observed contributing to orphaned
+            // build processes outliving a fixture test's own vitest timeout
+            // (testTimeout: 15_000 vs. up to 300s per attempt here). Root without
+            // a package.json only happens in this orchestrator's own unit-test
+            // fixtures (bare git repos with no app to build) — a real repo always
+            // has one, so this never skips a build that could have mattered.
+            const canBuild = existsSync(join(root, "package.json"));
+            let rebuildRes;
+            if (canBuild) {
+                rebuildRes = await runProcess("bun", ["run", "build"], { cwd: root, timeout: 300_000 });
+                if (commandMissing(rebuildRes)) {
+                    rebuildRes = await runProcess("npm", ["run", "build"], { cwd: root, timeout: 300_000 });
+                }
+            }
+            if (!canBuild) {
+                console.error(`Post-merge rebuild of ${root} skipped for task ${job.taskId}: no package.json`);
+            }
+            else if (rebuildRes && rebuildRes.status !== 0) {
+                console.error(`Post-merge rebuild of ${root} failed for task ${job.taskId}: ${tailLine(rebuildRes.stdout, rebuildRes.stderr)}`);
+            }
+            this.onProgress?.("done");
+            return { ok: true };
+        }
+        finally {
+            this.rootLock?.release(job.taskId);
+            // Always release the lock when done publishing.
+            if (this.repoLock) {
+                this.repoLock.release(job.taskId);
+            }
+        }
+    }
+    async cleanup(job) {
+        const root = this.config.root;
+        const featureBranch = job.branch ?? job.taskId;
+        // Candidate worktree + throwaway branch.
+        this.removeCandidate(job.taskId);
+        // Task's feature worktree + branch. The branch was just merged into main, so
+        // `-d` is correct; a false return means the worktree is still registered
+        // (leak) — log the path so a human/gc can see which one.
+        if (!removeWorktree(root, featureBranch)) {
+            const stuck = worktreePathForBranch(root, featureBranch);
+            this.logger?.integration(job.taskId, "warn", "feature worktree not removed at close-out", {
+                branch: featureBranch,
+                path: stuck ?? "unknown",
+            });
+            console.warn(`Close-out for ${job.taskId}: feature worktree for ${featureBranch} still registered (${stuck ?? "unknown"})`);
+        }
+        deleteBranch(root, featureBranch);
+        pruneWorktrees(root);
+        // Mark the task as done in the main checkout.
+        //
+        // The live index can miss a lookup right after a reload (its in-memory
+        // rebuild is not instant, and this cleanup step can land in that window —
+        // observed live, 2026-08-15, #0195: publish succeeded, main fast-forwarded
+        // to the candidate, but this step silently no-op'd — `task` was undefined,
+        // the `if (task)` guard skipped markTaskReleased with no error, and the
+        // task sat published-but-not-released until a manual retry). Falling back
+        // to a direct on-disk lookup by id makes this step independent of index
+        // freshness — the file is exactly what markTaskReleased writes to anyway.
+        try {
+            const absPath = this.getTask?.(job.taskId)?.absPath ??
+                findTaskFileById(root, this.config.workDir, job.taskId);
+            if (absPath) {
+                markTaskReleased(this.config, absPath);
+            }
+            else {
+                console.error(`Could not locate task ${job.taskId} on disk to mark it released — publish succeeded but release marking was skipped`);
+            }
+        }
+        catch (err) {
+            console.error(`Failed to mark task ${job.taskId} as done:`, err);
+            // Don't fail cleanup - the important part (merge) already succeeded
+        }
+        // Opportunistic GC: every close-out is a natural moment to reclaim
+        // `repoos/integrate/*` candidates that failed jobs left behind (this
+        // task's own were just removed above). Conservative — never touches
+        // `feat/*`. Also logs a "run `repoos gc`" warning if the worktree count is
+        // over the advisory ceiling. Fail-soft and not awaited-critical.
+        sweepAndWarn(this.config, {
+            activeJobIds: new Set(this.coordinator
+                .allJobs()
+                .filter((j) => j.phase !== "done" && j.phase !== "failed")
+                .map((j) => j.taskId)),
+            threshold: this.config.worktreeWarnThreshold,
+            log: (level, msg, meta) => this.logger?.integration(job.taskId, level, msg, meta),
+        });
+        return { ok: true };
+    }
+}