agentplane 0.3.12 → 0.3.14

package/dist/commands/branch/cleanup-merged.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cleanup-merged.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/cleanup-merged.ts"],"names":[],"mappings":"AAqBA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAgInC,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,CA8JlB"}
+{"version":3,"file":"cleanup-merged.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/cleanup-merged.ts"],"names":[],"mappings":"AAsBA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAgInC,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB,EAAE,OAAO,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyJlB"}

package/dist/commands/branch/cleanup-merged.js

@@ -8,6 +8,7 @@ import { ensureGitClean } from "../guard/index.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
 import { gitDiffNames } from "../shared/git-diff.js";
 import { gitBranchExists, gitCurrentBranch, gitIsAncestor } from "../shared/git-ops.js";
+import { cleanupMergedLocalBranch } from "../shared/merged-branch-cleanup.js";
 import { findWorktreeForBranch, gitListBranchesByPrefixes, parseTaskIdFromCloseBranch, parseTaskIdFromBranch, } from "../shared/git-worktree.js";
 import { isPathWithin, resolvePathFallback } from "../shared/path.js";
 import { parsePrMeta } from "../shared/pr-meta.js";
@@ -216,15 +217,10 @@ export async function cmdCleanupMerged(opts) {
                 const taskDir = path.join(resolved.gitRoot, config.paths.workflow_dir, item.taskId);
                 await archivePrArtifacts(taskDir);
             }
-            if (worktreePath) {
-                await execFileAsync("git", ["worktree", "remove", "--force", worktreePath], {
-                    cwd: resolved.gitRoot,
-                    env: gitEnv(),
-                });
-            }
-            await execFileAsync("git", ["branch", "-D", item.branch], {
-                cwd: resolved.gitRoot,
-                env: gitEnv(),
+            await cleanupMergedLocalBranch({
+                gitRoot: resolved.gitRoot,
+                branch: item.branch,
+                worktreePathHint: worktreePath,
             });
             if (opts.deleteRemoteBranches) {
                 deletedRemoteBranches += (await deleteRemoteBranchIfPresent(resolved.gitRoot, item.branch))

package/dist/commands/branch/work-start.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work-start.command.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/work-start.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAc,MAAM,wBAAwB,CAAC;AAGtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAkDtD,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,GAClE,cAAc,CAAC,eAAe,CAAC,CA4BjC"}
+{"version":3,"file":"work-start.command.d.ts","sourceRoot":"","sources":["../../../src/commands/branch/work-start.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAc,MAAM,wBAAwB,CAAC;AAGtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAGhE,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAmDtD,CAAC;AAEF,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,GAClE,cAAc,CAAC,eAAe,CAAC,CA4BjC"}

package/dist/commands/branch/work-start.command.js

@@ -42,6 +42,7 @@ export const workStartSpec = {
     notes: [
         "When workflow_mode=direct, agentplane does not create task branches; it records a single active task for the workspace.",
         "When workflow_mode=branch_pr, --worktree is required and the command must be run on the base branch.",
+        "After branch_pr work starts, run owner-scoped task commands from the created worktree so task README/PR artifacts stay attached to one checkout.",
     ],
     parse: (raw) => ({
         taskId: raw.args["task-id"],

package/dist/commands/codex/plugin-install.d.ts

@@ -0,0 +1,26 @@
+export declare const AGENTPLANE_CODEX_HOME_ENV = "AGENTPLANE_CODEX_HOME";
+export type CodexPluginInstallScope = "user" | "repo";
+export type CodexPluginInstallResult = {
+    scope: CodexPluginInstallScope;
+    installRoot: string;
+    pluginRoot: string;
+    manifestPath: string;
+    marketplacePath: string;
+    copiedAssets: string[];
+};
+type JsonObject = Record<string, unknown>;
+export declare function buildCodexPluginManifest(version?: string): JsonObject;
+export declare function resolveCodexInstallRoot(opts: {
+    scope: CodexPluginInstallScope;
+    repoRoot?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export declare function resolveCodexPluginRoot(installRoot: string): string;
+export declare function resolveCodexMarketplacePath(installRoot: string): string;
+export declare function installBundledCodexPlugin(opts: {
+    scope: CodexPluginInstallScope;
+    installRoot: string;
+    version?: string;
+}): Promise<CodexPluginInstallResult>;
+export {};
+//# sourceMappingURL=plugin-install.d.ts.map

package/dist/commands/codex/plugin-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-install.d.ts","sourceRoot":"","sources":["../../../src/commands/codex/plugin-install.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtD,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,EAAE,uBAAuB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAwG1C,wBAAgB,wBAAwB,CAAC,OAAO,SAAe,GAAG,UAAU,CA8B3E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,uBAAuB,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB,GAAG,MAAM,CAiBT;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAEvE;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,KAAK,EAAE,uBAAuB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAyCpC"}

package/dist/commands/codex/plugin-install.js

@@ -0,0 +1,209 @@
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CliError } from "../../shared/errors.js";
+import { getVersion } from "../../meta/version.js";
+import { writeJsonStableIfChanged, writeTextIfChanged } from "../../shared/write-if-changed.js";
+const PLUGIN_NAME = "agentplane";
+const DEFAULT_MARKETPLACE_NAME = "agentplane-local-marketplace";
+const DEFAULT_MARKETPLACE_DISPLAY_NAME = "AgentPlane Local Plugins";
+const ASSET_ROOT_URL = new URL("../../../assets/codex-plugin/", import.meta.url);
+const TEXT_ASSETS = [
+    {
+        source: new URL("skills/agentplane/SKILL.md", ASSET_ROOT_URL),
+        relativePath: "skills/agentplane/SKILL.md",
+    },
+];
+const BINARY_ASSETS = [
+    {
+        source: new URL("assets/icon.svg", ASSET_ROOT_URL),
+        relativePath: "assets/icon.svg",
+    },
+    {
+        source: new URL("assets/logo.svg", ASSET_ROOT_URL),
+        relativePath: "assets/logo.svg",
+    },
+    {
+        source: new URL("assets/header.png", ASSET_ROOT_URL),
+        relativePath: "assets/header.png",
+    },
+];
+export const AGENTPLANE_CODEX_HOME_ENV = "AGENTPLANE_CODEX_HOME";
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function invalidMarketplaceError(message) {
+    return new CliError({
+        exitCode: 3,
+        code: "E_VALIDATION",
+        message,
+    });
+}
+async function readTextIfExists(filePath) {
+    try {
+        return await readFile(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function defaultMarketplaceDocument() {
+    return {
+        name: DEFAULT_MARKETPLACE_NAME,
+        interface: {
+            displayName: DEFAULT_MARKETPLACE_DISPLAY_NAME,
+        },
+        plugins: [],
+    };
+}
+function parseMarketplaceDocument(text) {
+    if (text === null)
+        return defaultMarketplaceDocument();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw invalidMarketplaceError(`Invalid Codex marketplace JSON: ${err instanceof Error ? err.message : "unknown parse error"}`);
+    }
+    if (!isJsonObject(parsed)) {
+        throw invalidMarketplaceError("Invalid Codex marketplace JSON: expected a top-level object.");
+    }
+    if ("plugins" in parsed && !Array.isArray(parsed.plugins)) {
+        throw invalidMarketplaceError("Invalid Codex marketplace JSON: `plugins` must be an array.");
+    }
+    if ("interface" in parsed && parsed.interface !== undefined && !isJsonObject(parsed.interface)) {
+        throw invalidMarketplaceError("Invalid Codex marketplace JSON: `interface` must be an object when present.");
+    }
+    return parsed;
+}
+function marketplaceEntry() {
+    return {
+        name: PLUGIN_NAME,
+        source: {
+            source: "local",
+            path: `./plugins/${PLUGIN_NAME}`,
+        },
+        policy: {
+            installation: "AVAILABLE",
+            authentication: "ON_INSTALL",
+        },
+        category: "Productivity",
+    };
+}
+function upsertMarketplaceDocument(text) {
+    const document = parseMarketplaceDocument(text);
+    const interfaceObject = isJsonObject(document.interface) ? { ...document.interface } : {};
+    if (typeof document.name !== "string" || document.name.trim().length === 0) {
+        document.name = DEFAULT_MARKETPLACE_NAME;
+    }
+    if (typeof interfaceObject.displayName !== "string" ||
+        interfaceObject.displayName.trim().length === 0) {
+        interfaceObject.displayName = DEFAULT_MARKETPLACE_DISPLAY_NAME;
+    }
+    const plugins = Array.isArray(document.plugins) ? document.plugins : [];
+    const nextEntry = marketplaceEntry();
+    const existingIndex = plugins.findIndex((entry) => isJsonObject(entry) && entry.name === PLUGIN_NAME);
+    if (existingIndex === -1) {
+        plugins.push(nextEntry);
+    }
+    else {
+        plugins.splice(existingIndex, 1, nextEntry);
+    }
+    return {
+        ...document,
+        interface: interfaceObject,
+        plugins,
+    };
+}
+export function buildCodexPluginManifest(version = getVersion()) {
+    return {
+        name: PLUGIN_NAME,
+        version,
+        description: "Bundle AgentPlane workflow guidance for the Codex plugins UI.",
+        homepage: "https://github.com/basilisk-labs/agentplane",
+        repository: "https://github.com/basilisk-labs/agentplane",
+        license: "MIT",
+        keywords: ["agentplane", "codex", "workflow", "tasks", "git"],
+        skills: "./skills/",
+        interface: {
+            displayName: "AgentPlane",
+            shortDescription: "Governed git-native workflow guidance for Codex",
+            longDescription: "Install AgentPlane into Codex through a local marketplace and give Codex explicit task, planning, verification, and branch_pr workflow guidance.",
+            developerName: "basilisk-labs",
+            category: "Productivity",
+            capabilities: ["Read", "Write"],
+            websiteURL: "https://github.com/basilisk-labs/agentplane",
+            defaultPrompt: [
+                "Use AgentPlane to initialize a governed workflow in this repository.",
+                "Use AgentPlane to create a task, approve the plan, and start work in branch_pr mode.",
+                "Use AgentPlane to verify the active task and record evidence before finish.",
+            ],
+            brandColor: "#111827",
+            composerIcon: "./assets/icon.svg",
+            logo: "./assets/logo.svg",
+            screenshots: ["./assets/header.png"],
+        },
+    };
+}
+export function resolveCodexInstallRoot(opts) {
+    if (opts.scope === "repo") {
+        const repoRoot = opts.repoRoot?.trim();
+        if (!repoRoot) {
+            throw new CliError({
+                exitCode: 2,
+                code: "E_USAGE",
+                message: "Repo scope requires a resolved repository root.",
+            });
+        }
+        return path.resolve(repoRoot);
+    }
+    const env = opts.env ?? process.env;
+    const overridden = env[AGENTPLANE_CODEX_HOME_ENV]?.trim();
+    if (overridden)
+        return path.resolve(overridden);
+    return os.homedir();
+}
+export function resolveCodexPluginRoot(installRoot) {
+    return path.join(installRoot, "plugins", PLUGIN_NAME);
+}
+export function resolveCodexMarketplacePath(installRoot) {
+    return path.join(installRoot, ".agents", "plugins", "marketplace.json");
+}
+export async function installBundledCodexPlugin(opts) {
+    const installRoot = path.resolve(opts.installRoot);
+    const pluginRoot = resolveCodexPluginRoot(installRoot);
+    const manifestPath = path.join(pluginRoot, ".codex-plugin", "plugin.json");
+    const marketplacePath = resolveCodexMarketplacePath(installRoot);
+    await mkdir(path.dirname(manifestPath), { recursive: true });
+    await mkdir(path.dirname(marketplacePath), { recursive: true });
+    await writeJsonStableIfChanged(manifestPath, buildCodexPluginManifest(opts.version ?? getVersion()));
+    const copiedAssets = [];
+    for (const asset of TEXT_ASSETS) {
+        const targetPath = path.join(pluginRoot, asset.relativePath);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        const contents = await readFile(asset.source, "utf8");
+        await writeTextIfChanged(targetPath, contents);
+        copiedAssets.push(targetPath);
+    }
+    for (const asset of BINARY_ASSETS) {
+        const targetPath = path.join(pluginRoot, asset.relativePath);
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await copyFile(fileURLToPath(asset.source), targetPath);
+        copiedAssets.push(targetPath);
+    }
+    const nextMarketplace = upsertMarketplaceDocument(await readTextIfExists(marketplacePath));
+    await writeJsonStableIfChanged(marketplacePath, nextMarketplace);
+    return {
+        scope: opts.scope,
+        installRoot,
+        pluginRoot,
+        manifestPath,
+        marketplacePath,
+        copiedAssets,
+    };
+}

package/dist/commands/commit.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commit.spec.d.ts","sourceRoot":"","sources":["../../src/commands/commit.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOvD,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAwLhD,CAAC"}
+{"version":3,"file":"commit.spec.d.ts","sourceRoot":"","sources":["../../src/commands/commit.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOvD,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CA0LhD,CAAC"}

package/dist/commands/commit.spec.js

@@ -104,6 +104,8 @@ export const commitSpec = {
         },
     ],
     notes: [
+        "Repository-managed task commits use the canonical subject format `<emoji> <suffix> <scope>: <summary>`; non-task commits use `<emoji> <scope>: <summary>`.",
+        "Repository-managed commit paths resolve author/committer identity from global git `user.name` and `user.email` before falling back to ambient git env.",
         "Protected path-scoped overrides can stand alone without a duplicate explicit prefix: `--allow-tasks`, `--allow-policy`, `--allow-config`, `--allow-hooks`, and `--allow-ci` each admit their own path family.",
         "Top-level `agentplane commit` can auto-stage those protected path scopes when the git index starts empty.",
         "`--allow-base` is different: it only overrides base-branch protection and never selects file paths by itself.",

package/dist/commands/doctor/branch-pr.d.ts

@@ -1,4 +1,4 @@
-import type { CommandContext } from "../shared/task-backend.js";
+import { type CommandContext } from "../shared/task-backend.js";
 export declare function checkBranchPrShippedTaskDrift(ctx?: CommandContext): Promise<string[]>;
 export declare function checkBranchPrDoneTaskOpenPrDrift(ctx?: CommandContext): Promise<string[]>;
 //# sourceMappingURL=branch-pr.d.ts.map

package/dist/commands/doctor/branch-pr.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch-pr.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/branch-pr.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAMhE,wBAAsB,6BAA6B,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuC3F;AAED,wBAAsB,gCAAgC,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkC9F"}
+{"version":3,"file":"branch-pr.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/branch-pr.ts"],"names":[],"mappings":"AAKA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAM3F,wBAAsB,6BAA6B,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyC3F;AAED,wBAAsB,gCAAgC,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAoC9F"}

package/dist/commands/doctor/branch-pr.js

@@ -1,10 +1,12 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { renderDiagnosticFinding } from "../../shared/diagnostics.js";
+import { backendUsesLocalTaskStore } from "../shared/task-backend.js";
 import { findDoneBranchPrTasksWithOpenPrArtifacts, findLocallyShippedBranchPrTasks, } from "../task/hosted-merge-sync.js";
 export async function checkBranchPrShippedTaskDrift(ctx) {
-    if (ctx?.backendId !== "local" || ctx.config.workflow_mode !== "branch_pr")
+    if (!ctx || !backendUsesLocalTaskStore(ctx) || ctx.config.workflow_mode !== "branch_pr") {
         return [];
+    }
     let tasks = [];
     try {
         tasks = await ctx.taskBackend.listTasks();
@@ -38,8 +40,9 @@ export async function checkBranchPrShippedTaskDrift(ctx) {
     ];
 }
 export async function checkBranchPrDoneTaskOpenPrDrift(ctx) {
-    if (ctx?.backendId !== "local" || ctx.config.workflow_mode !== "branch_pr")
+    if (!ctx || !backendUsesLocalTaskStore(ctx) || ctx.config.workflow_mode !== "branch_pr") {
         return [];
+    }
     const tasks = await readDoneTaskSnapshot(ctx);
     if (tasks.length === 0)
         return [];

package/dist/commands/guard/impl/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commands.ts"],"names":[],"mappings":"AAaA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAQvF,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA8SxE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9E;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CAsPlB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commands.ts"],"names":[],"mappings":"AAaA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAQvF,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA+SxE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9E;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;IACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CAwPlB"}

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

@@ -15,7 +15,7 @@ import { execFileAsync, gitEnv } from "../../shared/git.js";
 import { ensureReconciledBeforeMutation } from "../../shared/reconcile-check.js";
 import { stageAllowlist, suggestAllowPrefixes } from "./allow.js";
 import { buildCloseCommitMessage, taskReadmePathForTask } from "./close-message.js";
-import { buildGitCommitEnv } from "./env.js";
+import { buildGitCommitEnv, resolveCanonicalGitIdentity } from "./env.js";
 import { guardCommitCheck } from "./policy.js";
 const COMMIT_FAILURE_SIGNAL_PATTERNS = [
     /Code style issues found/i,
@@ -167,6 +167,7 @@ async function commitRefreshedTaskArtifacts(opts) {
         allowConfig: false,
         allowHooks: false,
         allowCI: false,
+        gitIdentity: await resolveCanonicalGitIdentity(),
     });
     await opts.ctx.git.commit({ message, env });
     return true;
@@ -442,6 +443,7 @@ export async function cmdCommit(opts) {
                 allowHooks: false,
                 allowCI: false,
                 allowStaleDist: true,
+                gitIdentity: await resolveCanonicalGitIdentity(),
             });
             await ctx.git.commit({ message: msg.subject, body: msg.body, env });
             if (!opts.quiet) {
@@ -512,6 +514,7 @@ export async function cmdCommit(opts) {
             allowConfig: opts.allowConfig,
             allowHooks: opts.allowHooks,
             allowCI: opts.allowCI,
+            gitIdentity: await resolveCanonicalGitIdentity(),
         });
         await ctx.git.commit({ message: opts.message, env });
         await refreshBranchPrArtifactsAfterTaskCommit({

package/dist/commands/guard/impl/comment-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment-commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/comment-commit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAQ/E,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAiEvF,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA2F/D"}
+{"version":3,"file":"comment-commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/comment-commit.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAQ/E,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAiEvF,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,gBAAgB,CAAC;CAC1B,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA4F/D"}

package/dist/commands/guard/impl/comment-commit.js

@@ -3,7 +3,7 @@ import { invalidValueMessage, successMessage } from "../../../cli/output.js";
 import { CliError } from "../../../shared/errors.js";
 import { formatCommentBodyForCommit, normalizeCommentBodyForCommit, } from "../../../shared/comment-format.js";
 import { loadCommandContext } from "../../shared/task-backend.js";
-import { buildGitCommitEnv } from "./env.js";
+import { buildGitCommitEnv, resolveCanonicalGitIdentity } from "./env.js";
 import { stageAllowlist } from "./allow.js";
 import { guardCommitCheck } from "./policy.js";
 function deriveCommitMessageFromComment(opts) {
@@ -116,6 +116,7 @@ export async function commitFromComment(opts) {
         allowConfig: false,
         allowHooks: false,
         allowCI: false,
+        gitIdentity: await resolveCanonicalGitIdentity(),
     });
     await ctx.git.commit({ message, body, env });
     const { hash, subject } = await ctx.git.headHashSubject();

package/dist/commands/guard/impl/env.d.ts

@@ -1,3 +1,8 @@
+export type CanonicalGitIdentity = {
+    name: string;
+    email: string;
+};
+export declare function resolveCanonicalGitIdentity(): Promise<CanonicalGitIdentity | null>;
 export declare function buildGitCommitEnv(opts: {
     taskId: string;
     agentId?: string;
@@ -9,5 +14,6 @@ export declare function buildGitCommitEnv(opts: {
     allowHooks: boolean;
     allowCI: boolean;
     allowStaleDist?: boolean;
+    gitIdentity?: CanonicalGitIdentity | null;
 }): NodeJS.ProcessEnv;
 //# sourceMappingURL=env.d.ts.map

package/dist/commands/guard/impl/env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/env.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,MAAM,CAAC,UAAU,CAcpB"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/env.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAiBF,wBAAsB,2BAA2B,IAAI,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAkBxF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,WAAW,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC3C,GAAG,MAAM,CAAC,UAAU,CAsBpB"}

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

@@ -1,6 +1,47 @@
+import { execFileAsync } from "../../shared/git.js";
+let canonicalGitIdentityPromise = null;
+async function readGitConfigValue(key) {
+    try {
+        const { stdout } = await execFileAsync("git", ["config", "--global", "--get", key], {
+            cwd: process.cwd(),
+            env: process.env,
+        });
+        const trimmed = stdout.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveCanonicalGitIdentity() {
+    canonicalGitIdentityPromise ??= (async () => {
+        const globalName = await readGitConfigValue("user.name");
+        const globalEmail = await readGitConfigValue("user.email");
+        const name = globalName ??
+            process.env.GIT_AUTHOR_NAME?.trim() ??
+            process.env.GIT_COMMITTER_NAME?.trim() ??
+            null;
+        const email = globalEmail ??
+            process.env.GIT_AUTHOR_EMAIL?.trim() ??
+            process.env.GIT_COMMITTER_EMAIL?.trim() ??
+            null;
+        if (!name || !email)
+            return null;
+        return { name, email };
+    })();
+    return await canonicalGitIdentityPromise;
+}
 export function buildGitCommitEnv(opts) {
     return {
         ...process.env,
+        ...(opts.gitIdentity
+            ? {
+                GIT_AUTHOR_NAME: opts.gitIdentity.name,
+                GIT_AUTHOR_EMAIL: opts.gitIdentity.email,
+                GIT_COMMITTER_NAME: opts.gitIdentity.name,
+                GIT_COMMITTER_EMAIL: opts.gitIdentity.email,
+            }
+            : null),
         AGENTPLANE_TASK_ID: opts.taskId,
         ...(opts.agentId ? { AGENTPLANE_AGENT_ID: opts.agentId } : null),
         ...(opts.statusTo ? { AGENTPLANE_STATUS_TO: opts.statusTo } : 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":"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"}
+{"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

@@ -2,11 +2,13 @@ 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";
@@ -14,6 +16,54 @@ import { maybeRunPostIntegrateBootstrap } from "./internal/post-integrate-bootst
 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;
@@ -41,14 +91,40 @@ export async function cmdIntegrate(opts) {
             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}`;
+            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_GIT"),
-                code: "E_GIT",
+                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({

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