agentplane 0.3.10 → 0.3.12

package/dist/commands/pr/close-superseded.js

@@ -0,0 +1,129 @@
+import { readFile } from "node:fs/promises";
+import { mapCoreError } from "../../cli/error-map.js";
+import { exitCodeForError } from "../../cli/exit-codes.js";
+import { createCliEmitter, infoMessage, workflowModeMessage } from "../../cli/output.js";
+import { fileExists } from "../../cli/fs-utils.js";
+import { CliError } from "../../shared/errors.js";
+import { loadBackendTask, loadCommandContext, } from "../shared/task-backend.js";
+import { parsePrMetaForwardCompatible } from "../shared/pr-meta.js";
+import { cmdPrClose } from "./close.js";
+import { isGhNotFound, resolveDefaultGithubRepo, runGhApiJson, runGhApiNoOutput, } from "./internal/gh-api.js";
+import { resolvePrPaths } from "./internal/pr-paths.js";
+async function deleteRemoteBranch(opts) {
+    const endpoint = `repos/${opts.repo}/git/refs/heads/${encodeURIComponent(opts.branch)}`;
+    try {
+        await runGhApiNoOutput(opts.cwd, [endpoint, "-X", "DELETE"]);
+        return "deleted";
+    }
+    catch (err) {
+        if (isGhNotFound(err))
+            return "already-absent";
+        throw err;
+    }
+}
+export async function cmdPrCloseSuperseded(opts) {
+    try {
+        const output = createCliEmitter();
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const { task } = await loadBackendTask({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+        });
+        if (String(task.status ?? "")
+            .trim()
+            .toUpperCase() !== "DONE") {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: `Task ${opts.taskId} must be DONE before closing superseded PRs.`,
+            });
+        }
+        const { config, metaPath, resolved } = await resolvePrPaths({ ...opts, ctx });
+        if (config.workflow_mode !== "branch_pr") {
+            throw new CliError({
+                exitCode: exitCodeForError("E_USAGE"),
+                code: "E_USAGE",
+                message: workflowModeMessage(config.workflow_mode, "branch_pr"),
+            });
+        }
+        if (!(await fileExists(metaPath))) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: `Missing PR metadata: ${metaPath}`,
+            });
+        }
+        const meta = parsePrMetaForwardCompatible(await readFile(metaPath, "utf8"), opts.taskId);
+        const branch = meta.branch?.trim() ?? "";
+        if (!branch) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: `Missing PR branch for ${opts.taskId}`,
+            });
+        }
+        const repo = await resolveDefaultGithubRepo(resolved.gitRoot);
+        const owner = repo.split("/", 1)[0]?.trim() ?? "";
+        if (!owner) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: "Could not derive GitHub owner from remote origin.",
+            });
+        }
+        const openPrs = await runGhApiJson(resolved.gitRoot, [
+            `repos/${repo}/pulls?head=${encodeURIComponent(`${owner}:${branch}`)}&state=open&per_page=100`,
+        ]);
+        if (openPrs.length === 0) {
+            const remoteBranchAction = opts.deleteRemoteBranch
+                ? await deleteRemoteBranch({ cwd: resolved.gitRoot, repo, branch })
+                : "skipped";
+            output.report([
+                { label: "task", value: opts.taskId },
+                { label: "branch", value: branch },
+                { label: "state", value: "skipped" },
+                { label: "reason", value: "no open task PR found" },
+                { label: "remote_branch_action", value: remoteBranchAction },
+            ], { header: infoMessage(`pr close-superseded ${opts.taskId}`) });
+            return 0;
+        }
+        if (openPrs.length > 1) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: `Multiple open PRs match task ${opts.taskId} branch ${branch}: ${openPrs
+                    .map((pr) => pr.number)
+                    .filter((value) => typeof value === "number" && Number.isInteger(value) && value > 0)
+                    .map((value) => `#${value}`)
+                    .join(", ")}`,
+            });
+        }
+        const prNumber = Number(openPrs[0]?.number ?? 0);
+        if (!Number.isInteger(prNumber) || prNumber <= 0) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: `Could not determine open PR number for task ${opts.taskId}.`,
+            });
+        }
+        return await cmdPrClose({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            prNumber,
+            comment: `Superseded by protected-main closure of task ${opts.taskId}.`,
+            deleteRemoteBranch: opts.deleteRemoteBranch,
+        });
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, {
+            command: "pr close-superseded",
+            root: opts.rootOverride ?? null,
+        });
+    }
+}

package/dist/commands/pr/close.d.ts

@@ -0,0 +1,11 @@
+import { type CommandContext } from "../shared/task-backend.js";
+export declare function cmdPrClose(opts: {
+    ctx?: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    prNumber: number;
+    repo?: string;
+    comment?: string;
+    deleteRemoteBranch: boolean;
+}): Promise<number>;
+//# sourceMappingURL=close.d.ts.map

package/dist/commands/pr/close.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"close.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/close.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AA+CpF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,OAAO,CAAC;CAC7B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuGlB"}

package/dist/commands/pr/close.js

@@ -0,0 +1,116 @@
+import { mapCoreError } from "../../cli/error-map.js";
+import { exitCodeForError } from "../../cli/exit-codes.js";
+import { createCliEmitter, successMessage } from "../../cli/output.js";
+import { CliError } from "../../shared/errors.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { isGhNotFound, resolveDefaultGithubRepo, runGhApiJson, runGhApiNoOutput, } from "./internal/gh-api.js";
+function ensureNonEmptyFlag(name, value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_USAGE"),
+            code: "E_USAGE",
+            message: `Invalid value for --${name}.`,
+        });
+    }
+    return trimmed;
+}
+export async function cmdPrClose(opts) {
+    try {
+        if (!Number.isInteger(opts.prNumber) || opts.prNumber <= 0) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_USAGE"),
+                code: "E_USAGE",
+                message: "Invalid PR number.",
+            });
+        }
+        const output = createCliEmitter();
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const commandCwd = ctx.resolvedProject.gitRoot;
+        const repo = opts.repo
+            ? ensureNonEmptyFlag("repo", opts.repo)
+            : await resolveDefaultGithubRepo(commandCwd);
+        const comment = opts.comment?.trim() ? ensureNonEmptyFlag("comment", opts.comment) : null;
+        const pr = await runGhApiJson(commandCwd, [
+            `repos/${repo}/pulls/${opts.prNumber}`,
+        ]);
+        if (!pr.number) {
+            throw new CliError({
+                exitCode: exitCodeForError("E_VALIDATION"),
+                code: "E_VALIDATION",
+                message: `GitHub pull request #${opts.prNumber} was not found in ${repo}.`,
+            });
+        }
+        if (comment) {
+            await runGhApiNoOutput(commandCwd, [
+                `repos/${repo}/issues/${opts.prNumber}/comments`,
+                "-X",
+                "POST",
+                "-f",
+                `body=${comment}`,
+            ]);
+        }
+        const closed = await runGhApiJson(commandCwd, [
+            `repos/${repo}/pulls/${opts.prNumber}`,
+            "-X",
+            "PATCH",
+            "-f",
+            "state=closed",
+        ]);
+        const headRepo = closed.head?.repo?.full_name?.trim() ?? pr.head?.repo?.full_name?.trim() ?? null;
+        const headRef = closed.head?.ref?.trim() ?? pr.head?.ref?.trim() ?? null;
+        let remoteBranchAction = "skipped";
+        if (opts.deleteRemoteBranch) {
+            if (!headRef) {
+                remoteBranchAction = "skipped-missing-head";
+            }
+            else if (headRepo && headRepo !== repo) {
+                remoteBranchAction = "skipped-fork";
+            }
+            else {
+                try {
+                    await runGhApiNoOutput(commandCwd, [
+                        `repos/${repo}/git/refs/heads/${encodeURIComponent(headRef)}`,
+                        "-X",
+                        "DELETE",
+                    ]);
+                    remoteBranchAction = "deleted";
+                }
+                catch (err) {
+                    if (isGhNotFound(err)) {
+                        remoteBranchAction = "already-absent";
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+        }
+        const result = {
+            repo,
+            prNumber: opts.prNumber,
+            url: closed.html_url?.trim() ?? pr.html_url?.trim() ?? null,
+            state: closed.state?.trim() ?? pr.state?.trim() ?? "closed",
+            comment: comment ? "added" : "skipped",
+            remoteBranch: headRef,
+            remoteBranchAction,
+        };
+        output.report([
+            { label: "repo", value: result.repo },
+            { label: "state", value: result.state },
+            { label: "url", value: result.url ?? "unknown" },
+            { label: "comment", value: result.comment },
+            { label: "remote_branch", value: result.remoteBranch ?? "unknown" },
+            { label: "remote_branch_action", value: result.remoteBranchAction },
+        ], {
+            header: successMessage("pr close", `#${result.prNumber}`),
+        });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "pr close", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/pr/index.d.ts

@@ -2,5 +2,7 @@ export { cmdPrOpen } from "./open.js";
 export { cmdPrUpdate } from "./update.js";
 export { cmdPrCheck } from "./check.js";
 export { cmdPrNote } from "./note.js";
+export { cmdPrClose } from "./close.js";
+export { cmdPrCloseSuperseded } from "./close-superseded.js";
 export { cmdIntegrate } from "./integrate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/pr/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/commands/pr/index.js

@@ -2,4 +2,6 @@ export { cmdPrOpen } from "./open.js";
 export { cmdPrUpdate } from "./update.js";
 export { cmdPrCheck } from "./check.js";
 export { cmdPrNote } from "./note.js";
+export { cmdPrClose } from "./close.js";
+export { cmdPrCloseSuperseded } from "./close-superseded.js";
 export { cmdIntegrate } from "./integrate.js";

package/dist/commands/pr/integrate/artifacts.d.ts

@@ -11,4 +11,11 @@ export declare function readAndValidatePrArtifacts(opts: {
 }): Promise<{
     verifyLogText: string | null;
 }>;
+export declare function ensureCommittedPrArtifactsOnBranch(opts: {
+    resolved: {
+        gitRoot: string;
+    };
+    prDir: string;
+    branch: string;
+}): Promise<void>;
 //# sourceMappingURL=artifacts.d.ts.map

package/dist/commands/pr/integrate/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/artifacts.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAWnE,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC,CA8CD"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/artifacts.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAYnE,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC;IACV,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,CAAC,CAkDD;AAED,wBAAsB,kCAAkC,CAAC,IAAI,EAAE;IAC7D,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkEhB"}

package/dist/commands/pr/integrate/artifacts.js

@@ -1,7 +1,8 @@
 import path from "node:path";
 import { exitCodeForError } from "../../../cli/exit-codes.js";
 import { CliError } from "../../../shared/errors.js";
-import { readPrArtifact } from "../internal/pr-paths.js";
+import { readPrArtifact, readPrArtifactFromBranch } from "../internal/pr-paths.js";
+import { findWorktreeForBranch } from "../../shared/git-worktree.js";
 import { validateReviewContents } from "../internal/review-template.js";
 export async function readAndValidatePrArtifacts(opts) {
     const readPrArtifactTyped = readPrArtifact;
@@ -9,6 +10,7 @@ export async function readAndValidatePrArtifacts(opts) {
     const diffstatPath = path.join(prDir, "diffstat.txt");
     const verifyLogPath = path.join(prDir, "verify.log");
     const reviewPath = path.join(prDir, "review.md");
+    const worktreePath = await findWorktreeForBranch(opts.resolved.gitRoot, opts.branch);
     const errors = [];
     const relDiffstat = path.relative(opts.resolved.gitRoot, diffstatPath);
     const relVerifyLog = path.relative(opts.resolved.gitRoot, verifyLogPath);
@@ -18,6 +20,7 @@ export async function readAndValidatePrArtifacts(opts) {
         prDir,
         fileName: "diffstat.txt",
         branch: opts.branch,
+        worktreePath,
     });
     if (diffstatText === null)
         errors.push(`Missing ${relDiffstat}`);
@@ -26,6 +29,7 @@ export async function readAndValidatePrArtifacts(opts) {
         prDir,
         fileName: "verify.log",
         branch: opts.branch,
+        worktreePath,
     });
     if (verifyLogText === null)
         errors.push(`Missing ${relVerifyLog}`);
@@ -34,6 +38,7 @@ export async function readAndValidatePrArtifacts(opts) {
         prDir,
         fileName: "review.md",
         branch: opts.branch,
+        worktreePath,
     });
     if (reviewText === null)
         errors.push(`Missing ${relReview}`);
@@ -48,3 +53,63 @@ export async function readAndValidatePrArtifacts(opts) {
     }
     return { verifyLogText };
 }
+export async function ensureCommittedPrArtifactsOnBranch(opts) {
+    const readCommittedPrArtifact = readPrArtifactFromBranch;
+    const { prDir } = opts;
+    const diffstatPath = path.join(prDir, "diffstat.txt");
+    const verifyLogPath = path.join(prDir, "verify.log");
+    const reviewPath = path.join(prDir, "review.md");
+    const metaPath = path.join(prDir, "meta.json");
+    const errors = [];
+    const relMeta = path.relative(opts.resolved.gitRoot, metaPath);
+    const relDiffstat = path.relative(opts.resolved.gitRoot, diffstatPath);
+    const relVerifyLog = path.relative(opts.resolved.gitRoot, verifyLogPath);
+    const relReview = path.relative(opts.resolved.gitRoot, reviewPath);
+    const metaText = await readCommittedPrArtifact({
+        resolved: opts.resolved,
+        prDir,
+        fileName: "meta.json",
+        branch: opts.branch,
+    });
+    if (metaText === null)
+        errors.push(`Missing committed ${relMeta} on branch ${opts.branch}`);
+    const diffstatText = await readCommittedPrArtifact({
+        resolved: opts.resolved,
+        prDir,
+        fileName: "diffstat.txt",
+        branch: opts.branch,
+    });
+    if (diffstatText === null) {
+        errors.push(`Missing committed ${relDiffstat} on branch ${opts.branch}`);
+    }
+    const verifyLogText = await readCommittedPrArtifact({
+        resolved: opts.resolved,
+        prDir,
+        fileName: "verify.log",
+        branch: opts.branch,
+    });
+    if (verifyLogText === null) {
+        errors.push(`Missing committed ${relVerifyLog} on branch ${opts.branch}`);
+    }
+    const reviewText = await readCommittedPrArtifact({
+        resolved: opts.resolved,
+        prDir,
+        fileName: "review.md",
+        branch: opts.branch,
+    });
+    if (reviewText === null) {
+        errors.push(`Missing committed ${relReview} on branch ${opts.branch}`);
+    }
+    else {
+        validateReviewContents(reviewText, errors);
+    }
+    if (errors.length > 0) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_VALIDATION"),
+            code: "E_VALIDATION",
+            message: `Task branch ${opts.branch} is missing committed PR artifacts required for integrate.\n` +
+                `${errors.join("\n")}\n` +
+                "Commit the task README/PR artifacts on the task branch (for example via `agentplane pr open` + git add/commit) before rerunning integrate.",
+        });
+    }
+}

package/dist/commands/pr/integrate/cmd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cmd.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/cmd.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAQnE,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoMlB"}
+{"version":3,"file":"cmd.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/cmd.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAUnE,wBAAsB,YAAY,CAAC,IAAI,EAAE;IACvC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+OlB"}

package/dist/commands/pr/integrate/cmd.js

@@ -1,12 +1,16 @@
 import path from "node:path";
 import { mapBackendError } from "../../../cli/error-map.js";
+import { exitCodeForError } from "../../../cli/exit-codes.js";
 import { createCliEmitter } from "../../../cli/output.js";
 import { CliError } from "../../../shared/errors.js";
 import { cleanupIntegratedBranch } from "./internal/cleanup.js";
+import { renderPostIntegrateBootstrapFailureGuidance, renderPostIntegrateBootstrapGuidance, shouldRecommendPostIntegrateBootstrap, } from "./internal/bootstrap-guidance.js";
 import { execFileAsync, gitEnv } from "../../shared/git.js";
 import { gitRevParse } from "../../shared/git-ops.js";
 import { finalizeIntegrate } from "./internal/finalize.js";
 import { runMergeCommit, runRebaseFastForward, runSquashMerge } from "./internal/merge.js";
+import { maybeRunPreIntegrateBootstrap } from "./internal/pre-integrate-bootstrap.js";
+import { maybeRunPostIntegrateBootstrap } from "./internal/post-integrate-bootstrap.js";
 import { prepareIntegrate } from "./internal/prepare.js";
 import { resolveWorktreeForIntegrate } from "./internal/worktree.js";
 import { runVerifyCommands } from "./verify.js";
@@ -24,7 +28,7 @@ export async function cmdIntegrate(opts) {
             base: opts.base,
             runVerify: opts.runVerify,
         });
-        const { resolved, loadedConfig, task, prDir, metaPath, diffstatPath, verifyLogPath, metaSource, branch, base, verifyLogText, } = prepared;
+        const { resolved, loadedConfig, task, prDir, metaPath, diffstatPath, verifyLogPath, metaSource, branch, base, verifyLogText, protectedBaseRequiresPrMerge, } = prepared;
         const verifyCommands = prepared.verifyCommands;
         let alreadyVerifiedSha = prepared.alreadyVerifiedSha;
         let shouldRunVerify = prepared.shouldRunVerify;
@@ -32,10 +36,21 @@ export async function cmdIntegrate(opts) {
         const changedPaths = prepared.changedPaths;
         if (opts.dryRun) {
             if (!opts.quiet) {
-                output.success("integrate dry-run", task.id, `base=${base} branch=${branch} verify=${shouldRunVerify ? "yes" : "no"}`);
+                output.success("integrate dry-run", task.id, `base=${base} branch=${branch} verify=${shouldRunVerify ? "yes" : "no"} route=${protectedBaseRequiresPrMerge ? "github-pr" : "local"}`);
             }
             return 0;
         }
+        if (protectedBaseRequiresPrMerge) {
+            const prHint = typeof metaSource.pr_number === "number" && metaSource.pr_number > 0
+                ? `GitHub PR #${metaSource.pr_number}`
+                : `the GitHub PR for branch ${branch}`;
+            throw new CliError({
+                exitCode: exitCodeForError("E_GIT"),
+                code: "E_GIT",
+                message: `Base branch ${base} requires GitHub pull-request merges; integrate will not mutate it locally. ` +
+                    `Merge ${prHint} on GitHub, let Task Hosted Close finish the closure tail, then pull ${base}.`,
+            });
+        }
         const wt = await resolveWorktreeForIntegrate({
             gitRoot: resolved.gitRoot,
             worktreesDirRel: loadedConfig.paths.worktrees_dir,
@@ -64,6 +79,18 @@ export async function cmdIntegrate(opts) {
                 taskId: task.id,
             })));
         }
+        const preBootstrapResult = await maybeRunPreIntegrateBootstrap({
+            gitRoot: resolved.gitRoot,
+            changedPaths,
+        });
+        if (preBootstrapResult.status === "failed") {
+            throw new CliError({
+                exitCode: 8,
+                code: "E_RUNTIME",
+                message: "Unable to prepare the base worktree for integrate: automatic repo-local runtime refresh " +
+                    `failed (${preBootstrapResult.error}). Run \`bun run framework:dev:bootstrap\` in ${resolved.gitRoot} and retry integrate.`,
+            });
+        }
         const baseShaBeforeMerge = await gitRevParse(resolved.gitRoot, [base]);
         const headBeforeMerge = await gitRevParse(resolved.gitRoot, ["HEAD"]);
         let mergeHash = "";
@@ -159,6 +186,20 @@ export async function cmdIntegrate(opts) {
             tempWorktreePath = null;
             createdTempWorktree = false;
         }
+        if (shouldRecommendPostIntegrateBootstrap(changedPaths)) {
+            const bootstrapResult = await maybeRunPostIntegrateBootstrap({
+                gitRoot: resolved.gitRoot,
+                changedPaths,
+            });
+            if (!opts.quiet) {
+                if (bootstrapResult.status === "skipped") {
+                    output.warn(renderPostIntegrateBootstrapGuidance());
+                }
+                else if (bootstrapResult.status === "failed") {
+                    output.warn(renderPostIntegrateBootstrapFailureGuidance(bootstrapResult.error));
+                }
+            }
+        }
         return 0;
     }
     catch (err) {

package/dist/commands/pr/integrate/internal/bootstrap-guidance.d.ts

@@ -0,0 +1,8 @@
+export declare function shouldRecommendPostIntegrateBootstrap(changedPaths: string[]): boolean;
+export declare function shouldAutoBootstrapAfterIntegrate(opts: {
+    changedPaths: string[];
+    gitRoot: string;
+}): boolean;
+export declare function renderPostIntegrateBootstrapGuidance(): string;
+export declare function renderPostIntegrateBootstrapFailureGuidance(reason: string): string;
+//# sourceMappingURL=bootstrap-guidance.d.ts.map

package/dist/commands/pr/integrate/internal/bootstrap-guidance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-guidance.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/bootstrap-guidance.ts"],"names":[],"mappings":"AA4CA,wBAAgB,qCAAqC,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAErF;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CASV;AAED,wBAAgB,oCAAoC,IAAI,MAAM,CAK7D;AAED,wBAAgB,2CAA2C,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKlF"}

package/dist/commands/pr/integrate/internal/bootstrap-guidance.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { isRuntimeRelevantWatchedFile } from "../../../../../bin/runtime-watch.js";
+const WATCHED_RUNTIME_PACKAGES = [
+    {
+        packageRoot: "packages/agentplane",
+        watchedPaths: [
+            "src",
+            "bin/agentplane.js",
+            "bin/dist-guard.js",
+            "bin/runtime-context.js",
+            "bin/stale-dist-policy.js",
+        ],
+    },
+    {
+        packageRoot: "packages/core",
+        watchedPaths: ["src"],
+    },
+];
+function normalizeRepoPath(filePath) {
+    return filePath.replaceAll("\\", "/");
+}
+function isWatchedRuntimeSourcePath(filePath) {
+    const normalized = normalizeRepoPath(filePath);
+    for (const watchedPackage of WATCHED_RUNTIME_PACKAGES) {
+        for (const watchedPath of watchedPackage.watchedPaths) {
+            if (watchedPath === "src") {
+                const sourcePrefix = `${watchedPackage.packageRoot}/src/`;
+                if (!normalized.startsWith(sourcePrefix))
+                    continue;
+                const packageRelativePath = normalized.slice(watchedPackage.packageRoot.length + 1);
+                return isRuntimeRelevantWatchedFile(packageRelativePath);
+            }
+            if (normalized === `${watchedPackage.packageRoot}/${watchedPath}`) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+export function shouldRecommendPostIntegrateBootstrap(changedPaths) {
+    return changedPaths.some((changedPath) => isWatchedRuntimeSourcePath(changedPath));
+}
+export function shouldAutoBootstrapAfterIntegrate(opts) {
+    if (!shouldRecommendPostIntegrateBootstrap(opts.changedPaths)) {
+        return false;
+    }
+    return (existsSync(path.join(opts.gitRoot, "package.json")) &&
+        existsSync(path.join(opts.gitRoot, "packages", "agentplane", "package.json")) &&
+        existsSync(path.join(opts.gitRoot, "scripts", "bootstrap-framework-dev.mjs")));
+}
+export function renderPostIntegrateBootstrapGuidance() {
+    return ("This merge changed watched runtime sources. Run `bun run framework:dev:bootstrap` " +
+        "before the next command so the repo-local build stays current.");
+}
+export function renderPostIntegrateBootstrapFailureGuidance(reason) {
+    return ("This merge changed watched runtime sources and the automatic repo-local runtime refresh " +
+        `failed (${reason}). Run \`bun run framework:dev:bootstrap\` manually before the next command.`);
+}

package/dist/commands/pr/integrate/internal/cleanup.d.ts

@@ -1,12 +1,2 @@
-export type IntegrateCleanupResult = {
-    removedBranch: boolean;
-    removedWorktree: boolean;
-    worktreePath: string | null;
-    skippedReason: "outside_repo" | "current_worktree" | null;
-};
-export declare function cleanupIntegratedBranch(opts: {
-    gitRoot: string;
-    branch: string;
-    worktreePathHint?: string | null;
-}): Promise<IntegrateCleanupResult>;
+export { cleanupMergedLocalBranch as cleanupIntegratedBranch, type MergedBranchCleanupResult as IntegrateCleanupResult, } from "../../../shared/merged-branch-cleanup.js";
 //# sourceMappingURL=cleanup.d.ts.map

package/dist/commands/pr/integrate/internal/cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/cleanup.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,sBAAsB,GAAG;IACnC,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,cAAc,GAAG,kBAAkB,GAAG,IAAI,CAAC;CAC3D,CAAC;AAEF,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA4ClC"}
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,IAAI,uBAAuB,EACnD,KAAK,yBAAyB,IAAI,sBAAsB,GACzD,MAAM,0CAA0C,CAAC"}

package/dist/commands/pr/integrate/internal/cleanup.js

@@ -1,46 +1 @@
-import { execFileAsync, gitEnv } from "../../../shared/git.js";
-import { gitBranchExists } from "../../../shared/git-ops.js";
-import { findWorktreeForBranch } from "../../../shared/git-worktree.js";
-import { isPathWithin, resolvePathFallback } from "../../../shared/path.js";
-export async function cleanupIntegratedBranch(opts) {
-    const repoRoot = await resolvePathFallback(opts.gitRoot);
-    const discoveredWorktree = await findWorktreeForBranch(opts.gitRoot, opts.branch);
-    const rawWorktreePath = discoveredWorktree ?? opts.worktreePathHint ?? null;
-    const worktreePath = rawWorktreePath ? await resolvePathFallback(rawWorktreePath) : null;
-    if (worktreePath) {
-        if (!isPathWithin(repoRoot, worktreePath)) {
-            return {
-                removedBranch: false,
-                removedWorktree: false,
-                worktreePath,
-                skippedReason: "outside_repo",
-            };
-        }
-        if (worktreePath === repoRoot) {
-            return {
-                removedBranch: false,
-                removedWorktree: false,
-                worktreePath,
-                skippedReason: "current_worktree",
-            };
-        }
-        await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
-            cwd: opts.gitRoot,
-            env: gitEnv(),
-        });
-    }
-    let removedBranch = false;
-    if (await gitBranchExists(opts.gitRoot, opts.branch)) {
-        await execFileAsync("git", ["branch", "-D", opts.branch], {
-            cwd: opts.gitRoot,
-            env: gitEnv(),
-        });
-        removedBranch = true;
-    }
-    return {
-        removedBranch,
-        removedWorktree: Boolean(worktreePath),
-        worktreePath,
-        skippedReason: null,
-    };
-}
+export { cleanupMergedLocalBranch as cleanupIntegratedBranch, } from "../../../shared/merged-branch-cleanup.js";

package/dist/commands/pr/integrate/internal/finalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/finalize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAiBrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAMtE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAE3B,aAAa,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;IAEzB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2EhB"}
+{"version":3,"file":"finalize.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/finalize.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAiBrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAUtE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,cAAc,CAAC;IACpB,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAE3B,aAAa,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACrD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;IAEzB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2GhB"}