agentplane 0.3.11 → 0.3.13

package/dist/commands/guard/impl/commands.js

@@ -1,5 +1,6 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { extractTaskSuffix } from "@agentplaneorg/core";
 import { resolveTaskIndexPath } from "../../../backends/task-index.js";
 import { mapCoreError } from "../../../cli/error-map.js";
 import { infoMessage, successMessage } from "../../../cli/output.js";
@@ -7,6 +8,7 @@ import { stripAnsi } from "../../../cli/shared/ansi.js";
 import { withDiagnosticContext } from "../../../shared/diagnostics.js";
 import { CliError } from "../../../shared/errors.js";
 import { refreshBranchPrArtifactsAfterTaskCommit } from "../../shared/post-commit-pr-artifacts.js";
+import { isTaskLocalAdvancePath } from "../../shared/task-local-freshness.js";
 import { loadCommandContext } from "../../shared/task-backend.js";
 import { loadTaskFromContext } from "../../shared/task-backend.js";
 import { execFileAsync, gitEnv } from "../../shared/git.js";
@@ -111,6 +113,64 @@ function detectCommitFailureSignal(output) {
     }
     return null;
 }
+function taskArtifactRefreshCommitMessage(taskId) {
+    return `📝 ${extractTaskSuffix(taskId)} task: refresh PR artifacts`;
+}
+async function commitRefreshedTaskArtifacts(opts) {
+    const changedPaths = await opts.ctx.git.statusChangedPaths();
+    const taskArtifactPaths = changedPaths.filter((relPath) => isTaskLocalAdvancePath({
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        tasksPath: opts.ctx.config.paths.tasks_path,
+        relPath,
+    }));
+    if (taskArtifactPaths.length === 0)
+        return false;
+    await stageAllowlist({
+        ctx: opts.ctx,
+        allow: [],
+        allowTasks: true,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        tasksPath: opts.ctx.config.paths.tasks_path,
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        allowTaskOnly: true,
+        emptyAllowMessage: "PR artifact refresh produced no task-local files to stage for the follow-up commit.",
+        noMatchMessage: "PR artifact refresh produced changes outside the active task artifact scope; inspect the working tree before retrying the commit flow.",
+    });
+    const message = taskArtifactRefreshCommitMessage(opts.taskId);
+    await guardCommitCheck({
+        ctx: opts.ctx,
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride,
+        baseBranchOverride: null,
+        taskId: opts.taskId,
+        message,
+        allow: [],
+        allowBase: false,
+        allowTasks: true,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+        requireClean: true,
+        quiet: opts.quiet,
+    });
+    const env = buildGitCommitEnv({
+        taskId: opts.taskId,
+        allowTasks: true,
+        allowBase: false,
+        allowPolicy: false,
+        allowConfig: false,
+        allowHooks: false,
+        allowCI: false,
+    });
+    await opts.ctx.git.commit({ message, env });
+    return true;
+}
 function commitFailureDiagnostic(phase, output) {
     const signal = detectCommitFailureSignal(output);
     if (signal === "formatter") {
@@ -327,15 +387,17 @@ export async function cmdCommit(opts) {
                 return 0;
             }
             if (opts.closeStageTaskArtifacts === true) {
-                await refreshBranchPrArtifactsAfterTaskCommit({
-                    ctx,
-                    cwd: opts.cwd,
-                    rootOverride: opts.rootOverride,
-                    taskId: opts.taskId,
-                    quiet: opts.quiet,
-                });
+                if (opts.closeRefreshTaskArtifacts !== false) {
+                    await refreshBranchPrArtifactsAfterTaskCommit({
+                        ctx,
+                        cwd: opts.cwd,
+                        rootOverride: opts.rootOverride,
+                        taskId: opts.taskId,
+                        quiet: opts.quiet,
+                    });
+                }
                 // Artifact refresh writes tracked task files on disk; invalidate the memoized
-                // porcelain snapshot so staging/cleanliness checks see the refreshed state.
+                // porcelain snapshot so staging/cleanliness checks see the current task artifact state.
                 ctx.git.invalidateStatus();
             }
             await (opts.closeStageTaskArtifacts === true
@@ -459,6 +521,14 @@ export async function cmdCommit(opts) {
             taskId: opts.taskId,
             quiet: opts.quiet,
         });
+        ctx.git.invalidateStatus();
+        await commitRefreshedTaskArtifacts({
+            ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+            quiet: opts.quiet,
+        });
         if (!opts.quiet) {
             const { hash, subject } = await ctx.git.headHashSubject();
             process.stdout.write(`${successMessage("committed", `${hash?.slice(0, 12) ?? ""} ${subject ?? ""}`.trim(), autoStaged.length > 0 ? `staged=${autoStaged.join(", ")}` : undefined)}\n`);

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

@@ -1,4 +1,4 @@
-export declare const HOOK_NAMES: readonly ["commit-msg", "pre-commit", "pre-push"];
+export declare const HOOK_NAMES: readonly ["commit-msg", "pre-commit", "pre-push", "post-merge"];
 export declare function cmdHooksInstall(opts: {
     cwd: string;
     rootOverride?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/index.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,UAAU,mDAAoD,CAAC;AA8K5E,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmClB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiJlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks/index.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,UAAU,iEAAkE,CAAC;AA8K1F,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmClB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoLlB"}

package/dist/commands/hooks/index.js

@@ -8,14 +8,16 @@ import { mapBackendError, mapCoreError } from "../../cli/error-map.js";
 import { fileExists } from "../../cli/fs-utils.js";
 import { infoMessage, successMessage } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
+import { cmdCleanupMerged } from "../branch/index.js";
 import { GitContext } from "../shared/git-context.js";
 import { throwIfPolicyDenied } from "../shared/policy-deny.js";
 import { gitCurrentBranch, gitRevParse } from "../shared/git-ops.js";
 import { parseTaskIdFromBranch, parseTaskIdFromCloseBranch } from "../shared/git-worktree.js";
 import { isPathWithin } from "../shared/path.js";
+import { loadCommandContext } from "../shared/task-backend.js";
 const HOOK_MARKER = "agentplane-hook";
 const SHIM_MARKER = "agentplane-hook-shim";
-export const HOOK_NAMES = ["commit-msg", "pre-commit", "pre-push"];
+export const HOOK_NAMES = ["commit-msg", "pre-commit", "pre-push", "post-merge"];
 async function inferTaskIdFromBranchContext(opts) {
     try {
         const branch = await gitCurrentBranch(opts.gitRoot);
@@ -83,14 +85,14 @@ function shimScriptText() {
         "set -e",
         'SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"',
         'REPO_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"',
-        'ENV_BIN="${AGENTPLANE_HOOK_RUNNER:-}"',
-        'if [ -n "$ENV_BIN" ] && command -v node >/dev/null 2>&1 && [ -f "$ENV_BIN" ]; then',
-        '  exec node "$ENV_BIN" "$@"',
-        "fi",
         'LOCAL_BIN="$REPO_ROOT/packages/agentplane/bin/agentplane.js"',
         'if command -v node >/dev/null 2>&1 && [ -f "$LOCAL_BIN" ]; then',
         '  exec node "$LOCAL_BIN" "$@"',
         "fi",
+        'ENV_BIN="${AGENTPLANE_HOOK_RUNNER:-}"',
+        'if [ -n "$ENV_BIN" ] && command -v node >/dev/null 2>&1 && [ -f "$ENV_BIN" ]; then',
+        '  exec node "$ENV_BIN" "$@"',
+        "fi",
         "if command -v agentplane >/dev/null 2>&1; then",
         '  exec agentplane "$@"',
         "fi",
@@ -344,18 +346,52 @@ export async function cmdHooksRun(opts) {
                 env: process.env,
                 encoding: "utf8",
                 input: await readHookStdinUtf8(),
-                stdio: "pipe",
+                stdio: ["pipe", "inherit", "inherit"],
             });
-            if (typeof result.stdout === "string" && result.stdout.length > 0) {
-                process.stdout.write(result.stdout);
-            }
-            if (typeof result.stderr === "string" && result.stderr.length > 0) {
-                process.stderr.write(result.stderr);
-            }
             if (result.error)
                 throw result.error;
             return result.status ?? (result.signal ? 1 : 0);
         }
+        if (opts.hook === "post-merge") {
+            try {
+                const ctx = await loadCommandContext({
+                    cwd: opts.cwd,
+                    rootOverride: opts.rootOverride ?? null,
+                });
+                if (ctx.config.workflow_mode !== "branch_pr")
+                    return 0;
+                const baseBranch = await resolveBaseBranch({
+                    cwd: opts.cwd,
+                    rootOverride: opts.rootOverride ?? null,
+                    cliBaseOpt: null,
+                    mode: ctx.config.workflow_mode,
+                });
+                if (!baseBranch)
+                    return 0;
+                const currentBranch = await gitCurrentBranch(ctx.resolvedProject.gitRoot);
+                if (currentBranch !== baseBranch)
+                    return 0;
+                return await cmdCleanupMerged({
+                    ctx,
+                    cwd: opts.cwd,
+                    rootOverride: opts.rootOverride,
+                    base: baseBranch,
+                    yes: true,
+                    archive: false,
+                    deleteRemoteBranches: false,
+                    fetch: false,
+                    quiet: true,
+                    skipUnsafeWorktrees: true,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error && error.message.trim().length > 0
+                    ? error.message.trim()
+                    : String(error);
+                process.stderr.write(`warning: post-merge cleanup skipped: ${message}\n`);
+                return 0;
+            }
+        }
         return 0;
     }
     catch (err) {

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

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/check.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAgLnC,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2NlB"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/check.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAkLnC,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CA6NlB"}

package/dist/commands/pr/check.js

@@ -79,6 +79,7 @@ async function evaluateSnapshotFreshness(opts) {
     const freshness = await assessPrArtifactFreshness({
         gitRoot: opts.gitRoot,
         workflowDir: opts.workflowDir,
+        tasksPath: opts.tasksPath,
         taskId: opts.taskId,
         branchHeadSha: opts.branchHeadSha,
         metaHeadSha: opts.snapshot.meta.head_sha ?? null,
@@ -212,6 +213,7 @@ export async function cmdPrCheck(opts) {
             snapshot: localSnapshot,
             gitRoot: resolved.gitRoot,
             workflowDir: config.paths.workflow_dir,
+            tasksPath: config.paths.tasks_path,
             taskId: task.id,
             branchHeadSha,
             taskVerificationState: task.verification?.state ?? null,
@@ -294,6 +296,7 @@ export async function cmdPrCheck(opts) {
                 snapshot: branchSnapshot,
                 gitRoot: resolved.gitRoot,
                 workflowDir: config.paths.workflow_dir,
+                tasksPath: config.paths.tasks_path,
                 taskId: task.id,
                 branchHeadSha,
                 taskVerificationState: task.verification?.state ?? null,

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":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AASnE,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,CAkNlB"}
+{"version":3,"file":"cmd.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/integrate/cmd.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AA0EnE,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,CA6QlB"}

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

@@ -1,17 +1,69 @@
 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 { withDiagnosticContext } from "../../../shared/diagnostics.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 { buildTaskHandoffArtifact, resolveTaskHandoffPaths, writeTaskHandoff, } from "../../shared/task-handoff.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";
+async function recordProtectedBaseIntegrateHandoff(opts) {
+    const paths = resolveTaskHandoffPaths({
+        git_root: opts.ctx.resolvedProject.gitRoot,
+        workflow_dir: opts.ctx.config.paths.workflow_dir,
+        task_id: opts.taskId,
+    });
+    const handoffShowCommand = `agentplane task handoff show ${opts.taskId}`;
+    const prLabel = typeof opts.prNumber === "number" && opts.prNumber > 0
+        ? `GitHub PR #${opts.prNumber}`
+        : `the GitHub PR for branch ${opts.branch}`;
+    const prUrl = opts.prUrl?.trim() ?? "";
+    const prMetaPath = path.join(opts.ctx.config.paths.workflow_dir, opts.taskId, "pr", "meta.json");
+    const taskReadmePath = path.join(opts.ctx.config.paths.workflow_dir, opts.taskId, "README.md");
+    await writeTaskHandoff({
+        paths,
+        handoff: buildTaskHandoffArtifact({
+            task_id: opts.taskId,
+            created_at: new Date().toISOString(),
+            from_role: "INTEGRATOR",
+            reason: `Protected base ${opts.base} requires GitHub pull-request merges.`,
+            note: prUrl.length > 0
+                ? `Merge ${prLabel}: ${prUrl}. After GitHub merge, wait for Task Hosted Close, then pull ${opts.base}.`
+                : `Merge ${prLabel} on GitHub. After GitHub merge, wait for Task Hosted Close, then pull ${opts.base}.`,
+            branch: opts.branch,
+            base_branch: opts.base,
+            head_sha: opts.branchHeadSha,
+            workspace_root: opts.ctx.resolvedProject.gitRoot,
+            pr_branch: opts.branch,
+            route: {
+                kind: "protected_base_integrate",
+                status: "awaiting_github_merge",
+                local_mutation: "not_performed",
+                finalize_via: "github_pr_merge_then_hosted_close",
+                pr_number: opts.prNumber,
+                pr_url: prUrl.length > 0 ? prUrl : null,
+                handoff_show_command: handoffShowCommand,
+                base_pull_command: "git pull --ff-only",
+            },
+            next_actions: [
+                handoffShowCommand,
+                prUrl.length > 0 ? `Merge ${prLabel}: ${prUrl}` : `Merge ${prLabel} on GitHub`,
+                `Wait for Task Hosted Close to finish`,
+                `git pull --ff-only`,
+            ],
+            evidence_paths: [taskReadmePath, prMetaPath],
+        }),
+    });
+}
 export async function cmdIntegrate(opts) {
     let tempWorktreePath = null;
     let createdTempWorktree = false;
@@ -26,7 +78,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;
@@ -34,10 +86,47 @@ 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 prNumber = typeof metaSource.pr_number === "number" && metaSource.pr_number > 0
+                ? metaSource.pr_number
+                : null;
+            const prUrl = typeof metaSource.pr_url === "string" ? metaSource.pr_url : null;
+            const prHint = prNumber === null ? `the GitHub PR for branch ${branch}` : `GitHub PR #${prNumber}`;
+            await recordProtectedBaseIntegrateHandoff({
+                ctx: prepared.ctx,
+                taskId: task.id,
+                branch,
+                base,
+                branchHeadSha,
+                prNumber,
+                prUrl,
+            });
+            throw new CliError({
+                exitCode: exitCodeForError("E_HANDOFF"),
+                code: "E_HANDOFF",
+                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}.`,
+                context: withDiagnosticContext({
+                    task_id: task.id,
+                    branch,
+                    base_branch: base,
+                    reason_code: "protected_base_integrate_handoff",
+                }, {
+                    state: `protected-base integrate routed to GitHub merge handoff for ${task.id}`,
+                    likelyCause: `base branch ${base} is protected by a GitHub pull-request merge policy, so local integrate must stop before mutating ${base}`,
+                    hint: "Inspect the persisted handoff artifact for the canonical finalize route, then merge the PR on GitHub and let Task Hosted Close finish the close tail.",
+                    nextAction: {
+                        command: `agentplane task handoff show ${task.id}`,
+                        reason: "inspect the persisted protected-base finalize route before continuing",
+                        reasonCode: "protected_base_integrate_handoff",
+                    },
+                }),
+            });
+        }
         const wt = await resolveWorktreeForIntegrate({
             gitRoot: resolved.gitRoot,
             worktreesDirRel: loadedConfig.paths.worktrees_dir,
@@ -66,6 +155,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 = "";

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;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,CAwGhB"}
+{"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"}

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

@@ -101,6 +101,9 @@ export async function finalizeIntegrate(opts) {
         baseBranchOverride: opts.base,
         quiet: opts.quiet,
         allowPolicy: collectedIncidents.wrote,
+        // finalizeIntegrate already wrote the canonical MERGED task packet on the base checkout.
+        // Re-running branch-side PR artifact refresh here can regress pr/meta.json back to OPEN.
+        closeRefreshTaskArtifacts: false,
     });
     if (!opts.quiet) {
         output.success("integrate", opts.taskId, `merge=${opts.mergeHash.slice(0, 12)}`);

package/dist/commands/pr/integrate/internal/github-protection.d.ts

@@ -0,0 +1,5 @@
+export declare function requiresPullRequestMergePath(opts: {
+    gitRoot: string;
+    baseBranch: string;
+}): Promise<boolean>;
+//# sourceMappingURL=github-protection.d.ts.map

package/dist/commands/pr/integrate/internal/github-protection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-protection.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/github-protection.ts"],"names":[],"mappings":"AAMA,wBAAsB,4BAA4B,CAAC,IAAI,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CAUnB"}

package/dist/commands/pr/integrate/internal/github-protection.js

@@ -0,0 +1,13 @@
+import { resolveDefaultGithubRepo, runGhApiJson } from "../../internal/gh-api.js";
+export async function requiresPullRequestMergePath(opts) {
+    try {
+        const repo = await resolveDefaultGithubRepo(opts.gitRoot);
+        const protection = await runGhApiJson(opts.gitRoot, [
+            `repos/${repo}/branches/${opts.baseBranch}/protection`,
+        ]);
+        return protection.required_pull_request_reviews !== undefined;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,15 @@
+export type PreIntegrateBootstrapResult = {
+    status: "not-needed";
+} | {
+    status: "skipped";
+} | {
+    status: "ran";
+} | {
+    status: "failed";
+    error: string;
+};
+export declare function maybeRunPreIntegrateBootstrap(opts: {
+    gitRoot: string;
+    changedPaths: string[];
+}): Promise<PreIntegrateBootstrapResult>;
+//# sourceMappingURL=pre-integrate-bootstrap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pre-integrate-bootstrap.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/pre-integrate-bootstrap.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,2BAA2B,GACnC;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAkBxC,wBAAsB,6BAA6B,CAAC,IAAI,EAAE;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAiBvC"}

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

@@ -0,0 +1,35 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { execFileAsync } from "../../../shared/git.js";
+import { shouldAutoBootstrapAfterIntegrate } from "./bootstrap-guidance.js";
+function compactError(err) {
+    if (err instanceof Error) {
+        const text = err.message.trim();
+        return text.length > 0 ? text : err.name;
+    }
+    return String(err);
+}
+function baseRuntimeReady(gitRoot) {
+    return (existsSync(path.join(gitRoot, "node_modules")) &&
+        existsSync(path.join(gitRoot, "packages", "agentplane", "node_modules")) &&
+        existsSync(path.join(gitRoot, "packages", "agentplane", "dist", "cli.js")));
+}
+export async function maybeRunPreIntegrateBootstrap(opts) {
+    if (baseRuntimeReady(opts.gitRoot)) {
+        return { status: "not-needed" };
+    }
+    if (!shouldAutoBootstrapAfterIntegrate(opts)) {
+        return { status: "skipped" };
+    }
+    try {
+        await execFileAsync("bun", ["run", "framework:dev:bootstrap"], {
+            cwd: opts.gitRoot,
+            env: { ...process.env },
+            maxBuffer: 50 * 1024 * 1024,
+        });
+        return { status: "ran" };
+    }
+    catch (err) {
+        return { status: "failed", error: compactError(err) };
+    }
+}

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

@@ -8,6 +8,7 @@ export type PreparedIntegrate = {
     task: TaskData;
     baseBranch: string;
     currentBranch: string;
+    protectedBaseRequiresPrMerge: boolean;
     prDir: string;
     metaPath: string;
     diffstatPath: string;

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

@@ -1 +1 @@
-{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/prepare.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAUrE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iCAAiC,CAAC;AAWzC,OAAO,EAAgC,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGvF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,YAAY,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,EAAE,QAAQ,CAAC;IAEf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IAEtB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAEtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IAEb,aAAa,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,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,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyO7B"}
+{"version":3,"file":"prepare.d.ts","sourceRoot":"","sources":["../../../../../src/commands/pr/integrate/internal/prepare.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AAWrE,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,iCAAiC,CAAC;AAWzC,OAAO,EAAgC,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAIvF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,GAAG,EAAE,cAAc,CAAC;IACpB,QAAQ,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAC5C,YAAY,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,EAAE,QAAQ,CAAC;IAEf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,4BAA4B,EAAE,OAAO,CAAC;IAEtC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IAEtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IAEb,aAAa,EAAE,MAAM,CAAC;IAEtB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,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,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAqR7B"}