@wildorder/nightshift 0.11.1 → 0.13.0

package/dist/preflight.d.ts

@@ -0,0 +1,73 @@
+import type { LedgerEvent } from "./decision-ledger.js";
+import type { ProgramManifest } from "./manifest.js";
+/**
+ * The preflight stage: at run start, before baseline verification and any
+ * agent spawn, executes every *pending* prerequisite's `verifyCommand` as a
+ * deterministic, bounded subprocess. Exit zero flips it to `satisfied` (in
+ * memory — the caller decides when to persist); anything else — nonzero
+ * exit, spawn failure, timeout — uniformly means unmet, with a captured
+ * reason, and never throws out of this module. See
+ * `tasks/human-prerequisites/ws-02-*.md` for the full design.
+ */
+/** The wall-clock ceiling on a single prerequisite check. A deterministic
+ *  check that has not answered in this long is treated as unmet, and the
+ *  process tree is killed so it can never outlive the run. A constant, never
+ *  a config key — the charter keeps tuning knobs off the config surface. */
+export declare const PREREQUISITE_TIMEOUT_MS = 60000;
+export interface PrerequisiteRun {
+    exitCode: number;
+    output: string;
+    /** True when the process tree was killed for exceeding the timeout. */
+    timedOut: boolean;
+}
+export type PrerequisiteRunner = (command: string, cwd: string) => Promise<PrerequisiteRun>;
+/**
+ * Builds a bounded, process-tree-killing `PrerequisiteRunner`. Fixing the
+ * timeout inside a `(command, cwd)` runner would leave a timeout test no
+ * choice but to wait out the real production ceiling; this factory keeps the
+ * ceiling a test seam while {@link defaultPrerequisiteRunner} wires the
+ * production constant once.
+ */
+export declare function makePrerequisiteRunner(timeoutMs?: number): PrerequisiteRunner;
+/** The production runner: the 60 s ceiling, wired once. */
+export declare const defaultPrerequisiteRunner: PrerequisiteRunner;
+export interface PrerequisiteCheck {
+    id: string;
+    met: boolean;
+    /** Captured reason when unmet — always non-empty so the report never
+     *  renders a blank line. The tailed verify output on a nonzero exit; on a
+     *  nonzero exit that emitted no output, a fallback naming the exit code;
+     *  the spawn error message (or a generic notice) on a spawn failure; a
+     *  notice naming the ceiling on a timeout. Absent only when met. */
+    reason?: string;
+    /** True when this run's preflight flipped it pending → satisfied. False
+     *  for an already-satisfied prerequisite (not re-run) and for an unmet
+     *  one. */
+    newlySatisfied: boolean;
+}
+export interface PreflightResult {
+    checks: PrerequisiteCheck[];
+    /** Ledger events for the prerequisites this run newly satisfied. The
+     *  caller appends these once its own baseline verification admits the run
+     *  — see run-program.ts's staged-persistence wiring. */
+    events: LedgerEvent[];
+}
+/**
+ * Runs every pending prerequisite's `verifyCommand` once. Mutates
+ * `manifest.prerequisites` in place on a met check (pending → satisfied);
+ * the caller decides when (and whether) to persist that mutation to disk. An
+ * already-`satisfied` prerequisite is never re-run — settled facts stay
+ * settled (SC-06). No `verifyCommand` outcome can throw out of this
+ * function or halt the run (SC-03): a thrown spawn failure is caught here.
+ */
+export declare function runPreflight(args: {
+    manifest: ProgramManifest;
+    cwd: string;
+    runner: PrerequisiteRunner;
+    now: () => Date;
+    /** The run's identity, stamped on each `prerequisite-verified` event. */
+    runId: string;
+    runStartCommit: string | undefined;
+    log: (line: string) => void;
+}): Promise<PreflightResult>;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD;;;;;;;;GAQG;AAEH;;;4EAG4E;AAC5E,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAe9C,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,KACR,OAAO,CAAC,eAAe,CAAC,CAAC;AAiD9B;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,GAAE,MAAgC,GAC1C,kBAAkB,CAqEpB;AAED,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,EAAE,kBACd,CAAC;AAE3B,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,OAAO,CAAC;IACb;;;;wEAIoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;eAEW;IACX,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B;;4DAEwD;IACxD,MAAM,EAAE,WAAW,EAAE,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,kBAAkB,CAAC;IAC3B,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,yEAAyE;IACzE,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B,GAAG,OAAO,CAAC,eAAe,CAAC,CA0E3B"}

package/dist/preflight.js

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { tail } from "./agent-runner.js";
+/**
+ * The preflight stage: at run start, before baseline verification and any
+ * agent spawn, executes every *pending* prerequisite's `verifyCommand` as a
+ * deterministic, bounded subprocess. Exit zero flips it to `satisfied` (in
+ * memory — the caller decides when to persist); anything else — nonzero
+ * exit, spawn failure, timeout — uniformly means unmet, with a captured
+ * reason, and never throws out of this module. See
+ * `tasks/human-prerequisites/ws-02-*.md` for the full design.
+ */
+/** The wall-clock ceiling on a single prerequisite check. A deterministic
+ *  check that has not answered in this long is treated as unmet, and the
+ *  process tree is killed so it can never outlive the run. A constant, never
+ *  a config key — the charter keeps tuning knobs off the config surface. */
+export const PREREQUISITE_TIMEOUT_MS = 60_000;
+// In-memory output is kept to a bounded tail, mirroring agent-runner.ts's
+// own OUTPUT_TAIL_LIMIT — this module intentionally does not import that
+// private constant.
+const OUTPUT_TAIL_LIMIT = 200_000;
+/** How long a timed-out check waits, past its own ceiling, for the kill
+ *  request to take effect before giving up on `close` and settling anyway.
+ *  A kill (`taskkill`, a signalled process group) has no completion callback
+ *  to await, so without this bound a slow or failed kill would turn a
+ *  *bounded* check into an unbounded one — this is the backstop that keeps
+ *  the promise settling promptly regardless. */
+const KILL_GRACE_MS = 3_000;
+/**
+ * Kills a spawned shell line's whole process tree, not just the shell
+ * process `spawn` returned — a `verifyCommand` may fork descendants (node,
+ * curl, a helper script), and `child.kill()` alone would orphan them: on
+ * Windows in particular, killing only the returned `cmd.exe` process leaves
+ * its own child (say, `node`) running and still holding the inherited stdio
+ * pipe handles, so `close` never fires until that orphan exits on its own —
+ * confirmed empirically (see the git history of this function's tests): a
+ * `child.kill()` issued *before* `taskkill /T` gets a chance to walk the
+ * still-live tree kills the wrapper first, orphans the descendant, and
+ * taskkill then reports "not found" for a pid that is already gone —
+ * reproducing exactly the unbounded-wait failure this function exists to
+ * prevent. So the whole tree is killed as a single unit, by pid, while the
+ * tree is still intact — never a separate signal to the immediate child
+ * first.
+ *
+ * POSIX: the child was spawned `detached: true`, making it its own
+ * process-group leader; signalling the negative pid signals the whole group
+ * atomically. `ESRCH` (the group already exited) is swallowed — best effort.
+ *
+ * Windows: there is no process-group signal, so `taskkill /T /F` is used,
+ * which walks the live process tree from `pid` and terminates it forcibly in
+ * one call. Fire-and-forget as far as this function is concerned — its
+ * caller (the grace timer in {@link makePrerequisiteRunner}) is what bounds
+ * the wait, since an external kill request has no completion callback of its
+ * own to await; a spawn failure for `taskkill` itself (e.g. an unusual PATH)
+ * is swallowed the same way.
+ */
+function killProcessTree(pid) {
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
+            windowsHide: true,
+            stdio: "ignore",
+        });
+        killer.on("error", () => {
+            // taskkill itself failed to spawn — the grace timer still bounds the
+            // wait regardless.
+        });
+        return;
+    }
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        // Already exited, or never became a group leader — best effort.
+    }
+}
+/**
+ * Builds a bounded, process-tree-killing `PrerequisiteRunner`. Fixing the
+ * timeout inside a `(command, cwd)` runner would leave a timeout test no
+ * choice but to wait out the real production ceiling; this factory keeps the
+ * ceiling a test seam while {@link defaultPrerequisiteRunner} wires the
+ * production constant once.
+ */
+export function makePrerequisiteRunner(timeoutMs = PREREQUISITE_TIMEOUT_MS) {
+    return (command, cwd) => new Promise((resolvePromise, rejectPromise) => {
+        // shell: true, exactly like defaultVerifyRunner — a verifyCommand is a
+        // whole shell line the human/planner authored, run under cmd /c or
+        // /bin/sh -c. detached: true on POSIX makes the child a process-group
+        // leader so killProcessTree can signal the whole tree; Windows has no
+        // such option and uses taskkill /T instead.
+        const child = spawn(command, [], {
+            cwd,
+            shell: true,
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            ...(process.platform === "win32" ? {} : { detached: true }),
+        });
+        let buffered = "";
+        const push = (chunk) => {
+            buffered = (buffered + chunk).slice(-OUTPUT_TAIL_LIMIT);
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", push);
+        child.stderr?.on("data", push);
+        // Never reads stdin, and ends it immediately — the same headless
+        // posture as defaultVerifyRunner (agent-runner.ts).
+        child.stdin?.end();
+        let settled = false;
+        let timedOut = false;
+        let graceTimer;
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            resolvePromise(result);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (child.pid !== undefined)
+                killProcessTree(child.pid);
+            // The kill above is a request, not a confirmation — `taskkill` and a
+            // signalled process group have no completion callback this runner
+            // can await, and a slow or failed kill must never turn a *bounded*
+            // check into an unbounded one (SC-03/SC-11: the run always
+            // terminates). `close` still wins the race in the overwhelmingly
+            // common case where the kill lands promptly; this grace window is
+            // strictly a backstop for the rest.
+            graceTimer = setTimeout(() => {
+                settle({ exitCode: 1, output: buffered, timedOut: true });
+            }, KILL_GRACE_MS);
+            graceTimer.unref();
+        }, timeoutMs);
+        timer.unref();
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(graceTimer);
+            rejectPromise(error);
+        });
+        child.on("close", (code) => {
+            settle({ exitCode: code ?? 1, output: buffered, timedOut });
+        });
+    });
+}
+/** The production runner: the 60 s ceiling, wired once. */
+export const defaultPrerequisiteRunner = makePrerequisiteRunner();
+/**
+ * Runs every pending prerequisite's `verifyCommand` once. Mutates
+ * `manifest.prerequisites` in place on a met check (pending → satisfied);
+ * the caller decides when (and whether) to persist that mutation to disk. An
+ * already-`satisfied` prerequisite is never re-run — settled facts stay
+ * settled (SC-06). No `verifyCommand` outcome can throw out of this
+ * function or halt the run (SC-03): a thrown spawn failure is caught here.
+ */
+export async function runPreflight(args) {
+    const { manifest, cwd, runner, now, runId, runStartCommit, log } = args;
+    const checks = [];
+    const events = [];
+    for (const prerequisite of manifest.prerequisites) {
+        if (prerequisite.status === "satisfied") {
+            checks.push({ id: prerequisite.id, met: true, newlySatisfied: false });
+            continue;
+        }
+        let run;
+        try {
+            run = await runner(prerequisite.verifyCommand, cwd);
+        }
+        catch (error) {
+            const message = error?.message?.trim();
+            const reason = message && message !== ""
+                ? message
+                : "the verify command could not be started";
+            checks.push({
+                id: prerequisite.id,
+                met: false,
+                reason,
+                newlySatisfied: false,
+            });
+            log(`preflight: ${prerequisite.id} unmet — ${reason}`);
+            continue;
+        }
+        if (run.timedOut) {
+            const reason = `the verify command did not finish within ` +
+                `${PREREQUISITE_TIMEOUT_MS}ms and was terminated`;
+            checks.push({
+                id: prerequisite.id,
+                met: false,
+                reason,
+                newlySatisfied: false,
+            });
+            log(`preflight: ${prerequisite.id} unmet — ${reason}`);
+            continue;
+        }
+        if (run.exitCode !== 0) {
+            const tailed = tail(run.output, 1500).trim();
+            const reason = tailed !== ""
+                ? tailed
+                : `the verify command exited ${run.exitCode} with no output`;
+            checks.push({
+                id: prerequisite.id,
+                met: false,
+                reason,
+                newlySatisfied: false,
+            });
+            log(`preflight: ${prerequisite.id} unmet — ${reason}`);
+            continue;
+        }
+        prerequisite.status = "satisfied";
+        checks.push({ id: prerequisite.id, met: true, newlySatisfied: true });
+        events.push({
+            kind: "prerequisite-verified",
+            at: now().toISOString(),
+            id: prerequisite.id,
+            verifyCommand: prerequisite.verifyCommand,
+            runId,
+            ...(runStartCommit === undefined ? {} : { commit: runStartCommit }),
+        });
+        log(`preflight: ${prerequisite.id} satisfied`);
+    }
+    return { checks, events };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"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"}

package/dist/publish.d.ts

@@ -1,3 +1,5 @@
+import { type AgentRunner } from "./agent-runner.js";
+import { type NightshiftConfig } from "./config.js";
 /**
  * The handover from a finished run to a reviewable pull request: pushes the
  * program branch, opens or updates exactly one draft PR through `gh`,
@@ -65,6 +67,32 @@ export interface PublishGit {
     /** Is the branch ahead of base? `git rev-list --count <base>..<branch>`. */
     commitsAhead(cwd: string, base: string, branch: string): Promise<number>;
     push(cwd: string, remote: string, branch: string): Promise<void>;
+    /**
+     * Fetches `branch` from `remote` so a subsequent merge sees its current
+     * tip, not whatever this checkout last saw at clone/checkout time.
+     */
+    fetchBranch(cwd: string, remote: string, branch: string): Promise<void>;
+    /**
+     * Merges `ref` into the checked-out branch without committing
+     * (`git merge --no-commit --no-ff`). `"up-to-date"` means `ref` was
+     * already an ancestor of HEAD and nothing happened; `"merged"` means it
+     * merged cleanly and is staged, waiting for `commitMerge`; `"conflict"`
+     * means it left unmerged paths and the merge is still in progress.
+     */
+    mergeNoCommit(cwd: string, ref: string): Promise<{
+        status: "up-to-date";
+    } | {
+        status: "merged";
+    } | {
+        status: "conflict";
+        paths: string[];
+    }>;
+    /** Aborts an in-progress merge, restoring the pre-merge working tree. */
+    abortMerge(cwd: string): Promise<void>;
+    /** Resolves one unmerged path to the checked-out branch's own side, and stages it. */
+    checkoutOurs(cwd: string, path: string): Promise<void>;
+    /** Commits a merge staged by `mergeNoCommit`/`checkoutOurs`. */
+    commitMerge(cwd: string, message: string): Promise<void>;
 }
 export declare const defaultPublishGit: PublishGit;
 export declare const defaultGhClient: GhClient;
@@ -75,6 +103,14 @@ export interface PublishOptions {
     gh?: GhClient;
     /** Injected git boundary; default execFile-backed. */
     git?: PublishGit;
+    /**
+     * Loaded internally via `loadConfig` when omitted, exactly like `run` and
+     * `author` load it in `cli.ts` — publish has no dedicated action of its
+     * own to load it first. Test seam only; production never needs to pass it.
+     */
+    config?: NightshiftConfig;
+    /** Passed straight through to the pre-publish as-built refresh; default reviewer runner. */
+    agentRunner?: AgentRunner;
     log?: (line: string) => void;
 }
 export interface PublishResult {

package/dist/publish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../src/publish.ts"],"names":[],"mappings":"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"}

package/dist/publish.js

@@ -4,11 +4,14 @@ import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { sanitizedEnvironment } from "./agent-runner.js";
+import { refreshAsBuilt } from "./as-built.js";
+import { loadConfig } from "./config.js";
 import { readDecisionLedger } from "./decision-ledger.js";
 import { escalatedRecords, renderRecord, } from "./decision-view.js";
 import { loadManifest } from "./manifest.js";
 import { detectDefaultBranch, programBranchName } from "./program-branch.js";
 import { runReportPath } from "./report-path.js";
+import { AS_BUILT_PATH } from "./whole-program-review.js";
 const execFileAsync = promisify(execFile);
 /**
  * The handover from a finished run to a reviewable pull request: pushes the
@@ -81,6 +84,59 @@ export const defaultPublishGit = {
             throw new Error(`git push -u ${remote} ${branch} failed:\n${stderr.trim()}`, { cause: error });
         }
     },
+    async fetchBranch(cwd, remote, branch) {
+        try {
+            await execFileAsync("git", ["fetch", remote, branch], { cwd });
+        }
+        catch (error) {
+            const stderr = String(error.stderr ?? error.message);
+            throw new Error(`git fetch ${remote} ${branch} failed:\n${stderr.trim()}`, { cause: error });
+        }
+    },
+    async mergeNoCommit(cwd, ref) {
+        try {
+            await execFileAsync("git", ["merge", "--no-commit", "--no-ff", ref], { cwd });
+        }
+        catch (error) {
+            const { stdout: unmerged } = await execFileAsync("git", ["diff", "--name-only", "--diff-filter=U"], { cwd });
+            const paths = unmerged.split(/\r?\n/u).filter((line) => line.trim() !== "");
+            if (paths.length === 0) {
+                // Merge failed for a reason other than a content conflict (a dirty
+                // tree, a mid-merge repository, ...) — not ours to resolve.
+                const stderr = String(error.stderr ?? error.message);
+                throw new Error(`git merge --no-ff ${ref} failed:\n${stderr.trim()}`, {
+                    cause: error,
+                });
+            }
+            return { status: "conflict", paths };
+        }
+        // `--no-commit` still leaves a real merge (one that was not a no-op)
+        // staged rather than committed; `MERGE_HEAD` is git's own record of
+        // that, and is absent exactly when there was nothing to merge.
+        try {
+            await execFileAsync("git", ["rev-parse", "--verify", "-q", "MERGE_HEAD"], { cwd });
+            return { status: "merged" };
+        }
+        catch {
+            return { status: "up-to-date" };
+        }
+    },
+    async abortMerge(cwd) {
+        await execFileAsync("git", ["merge", "--abort"], { cwd });
+    },
+    async checkoutOurs(cwd, path) {
+        await execFileAsync("git", ["checkout", "--ours", "--", path], { cwd });
+        await execFileAsync("git", ["add", "--", path], { cwd });
+    },
+    async commitMerge(cwd, message) {
+        try {
+            await execFileAsync("git", ["commit", "-m", message], { cwd });
+        }
+        catch (error) {
+            const stderr = String(error.stderr ?? error.message);
+            throw new Error(`git commit (merge) failed:\n${stderr.trim()}`, { cause: error });
+        }
+    },
 };
 /**
  * Spawns `gh` through the same primitives the rest of the codebase spawns
@@ -491,6 +547,122 @@ async function reconcileComments(gh, cwd, prNumber, desired) {
     }
     return { escalationComments, continuationComments };
 }
+// ---- pre-publish as-built sync -------------------------------------------
+/**
+ * `docs/as-built.md` is regenerated wholesale, not patched, so once the base
+ * branch and the program branch have each regenerated it independently, a
+ * GitHub merge sees two unrelated full rewrites of the same file and
+ * conflicts almost every time content differs, even though nothing about the
+ * change is actually incompatible. Merging the base into the branch first —
+ * so the branch's copy of the file descends from the base's — turns that
+ * into an ordinary fast-forward-compatible history and the PR stops
+ * conflicting on it.
+ *
+ * This step is entirely best-effort and never turns a publish that would
+ * have succeeded before this existed into one that fails: any git failure
+ * along the way — fetch, merge, or commit — is logged and the merge is left
+ * alone (aborted, when one was left in progress) rather than surfaced as a
+ * publish failure. A merge that conflicts on files other than
+ * `docs/as-built.md` is not this function's to resolve at all; it aborts and
+ * leaves the branch exactly as publish found it, the same as if this step
+ * did not exist.
+ */
+async function syncAsBuiltWithBase(args) {
+    const { root, git, base, branch, programId, config, agentRunner, log } = args;
+    const baseRef = `origin/${base}`;
+    try {
+        await git.fetchBranch(root, "origin", base);
+    }
+    catch (error) {
+        log(`pre-publish as-built sync: could not fetch \`${base}\`, skipping — ` +
+            error.message);
+        return;
+    }
+    let mergeResult;
+    try {
+        mergeResult = await git.mergeNoCommit(root, baseRef);
+    }
+    catch (error) {
+        // A failure here is not necessarily "never started" — abort defensively
+        // so a merge git did leave in progress (a shape `mergeNoCommit`'s own
+        // conflict detection did not recognize) never lingers in the working
+        // tree after this function returns.
+        try {
+            await git.abortMerge(root);
+        }
+        catch {
+            // Best-effort only; nothing was left staged if there was no merge to
+            // abort, and the original failure below is what matters.
+        }
+        log(`pre-publish as-built sync: could not merge \`${baseRef}\` into ` +
+            `\`${branch}\`, skipping — ${error.message}`);
+        return;
+    }
+    if (mergeResult.status === "up-to-date")
+        return;
+    if (mergeResult.status === "conflict") {
+        const other = mergeResult.paths.filter((path) => path !== AS_BUILT_PATH);
+        if (other.length > 0) {
+            await git.abortMerge(root);
+            log(`pre-publish as-built sync: merging \`${baseRef}\` into \`${branch}\` ` +
+                `conflicts outside \`${AS_BUILT_PATH}\` (${other.join(", ")}); left ` +
+                `the branch as publish found it. Merge \`${base}\` into \`${branch}\` ` +
+                "yourself, resolve the conflicts, and re-run publish.");
+            return;
+        }
+        try {
+            await git.checkoutOurs(root, AS_BUILT_PATH);
+        }
+        catch (error) {
+            await git.abortMerge(root);
+            log(`pre-publish as-built sync: could not resolve the \`${AS_BUILT_PATH}\` ` +
+                `conflict, skipping — ${error.message}`);
+            return;
+        }
+    }
+    try {
+        await git.commitMerge(root, `nightshift(${programId}): merge ${base} before publish`);
+    }
+    catch (error) {
+        try {
+            await git.abortMerge(root);
+        }
+        catch {
+            // Best-effort cleanup only; the commit failure below is what matters.
+        }
+        log(`pre-publish as-built sync: could not commit the merge of \`${baseRef}\`, ` +
+            `skipping — ${error.message}`);
+        return;
+    }
+    log(`pre-publish as-built sync: merged \`${baseRef}\` into \`${branch}\``);
+    try {
+        const result = await refreshAsBuilt({
+            cwd: root,
+            programId,
+            config,
+            log,
+            ...(agentRunner === undefined ? {} : { agentRunner }),
+        });
+        log(`pre-publish as-built sync: as-built refresh ${result.outcome.status}` +
+            (result.commit ? ` (${result.commit})` : ""));
+    }
+    catch (error) {
+        log(`pre-publish as-built sync: could not refresh \`${AS_BUILT_PATH}\` after ` +
+            `merging \`${base}\` — ${error.message}`);
+    }
+}
+async function resolvePublishConfig(root, provided, log) {
+    if (provided !== undefined)
+        return provided;
+    try {
+        return (await loadConfig(root)).config;
+    }
+    catch (error) {
+        log("pre-publish as-built sync: could not load nightshift.config.json, " +
+            `skipping — ${error.message}`);
+        return undefined;
+    }
+}
 // ---- publish ------------------------------------------------------------
 export async function publish(options) {
     const root = resolve(options.cwd);
@@ -526,6 +698,19 @@ export async function publish(options) {
         throw new Error(`Program ${options.programId} has no commits on \`${branch}\` beyond ` +
             `\`${base}\`; there is nothing to publish.`);
     }
+    const config = await resolvePublishConfig(root, options.config, log);
+    if (config !== undefined) {
+        await syncAsBuiltWithBase({
+            root,
+            git,
+            base,
+            branch,
+            programId: options.programId,
+            config,
+            agentRunner: options.agentRunner,
+            log,
+        });
+    }
     await git.push(root, "origin", branch);
     log(`pushed ${branch} to origin`);
     const chunks = splitReportIntoChunks(report);