agentplane 0.3.11 → 0.3.13

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

@@ -4,6 +4,7 @@ import { resolveBaseBranch } from "@agentplaneorg/core";
 import { fileExists } from "../../../../cli/fs-utils.js";
 import { exitCodeForError } from "../../../../cli/exit-codes.js";
 import { unknownEntityMessage, workflowModeMessage } from "../../../../cli/output.js";
+import { withDiagnosticContext } from "../../../../shared/diagnostics.js";
 import { CliError } from "../../../../shared/errors.js";
 import { ensureGitClean } from "../../../guard/index.js";
 import { gitDiffNames } from "../../../shared/git-diff.js";
@@ -17,6 +18,7 @@ import { readAndValidatePrArtifacts, ensureCommittedPrArtifactsOnBranch } from "
 import { computeVerifyState } from "../verify.js";
 import { parsePrMetaForwardCompatible } from "../../../shared/pr-meta.js";
 import { assessPrArtifactFreshness } from "../../internal/freshness.js";
+import { requiresPullRequestMergePath } from "./github-protection.js";
 export async function prepareIntegrate(opts) {
     const ctx = opts.ctx ??
         (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
@@ -51,13 +53,6 @@ export async function prepareIntegrate(opts) {
         });
     }
     const currentBranch = await gitCurrentBranch(resolved.gitRoot);
-    if (currentBranch !== baseBranch) {
-        throw new CliError({
-            exitCode: exitCodeForError("E_GIT"),
-            code: "E_GIT",
-            message: `integrate must run on base branch ${baseBranch} (current: ${currentBranch})`,
-        });
-    }
     const { prDir, metaPath, diffstatPath, verifyLogPath } = await resolvePrPaths({
         ctx,
         cwd: opts.cwd,
@@ -91,6 +86,43 @@ export async function prepareIntegrate(opts) {
             message: unknownEntityMessage("branch", branch),
         });
     }
+    if (currentBranch !== baseBranch) {
+        if (currentBranch === branch) {
+            const baseWorktreePath = await findWorktreeForBranch(resolved.gitRoot, baseBranch);
+            const rerunCommand = baseWorktreePath && baseWorktreePath.trim().length > 0
+                ? `agentplane integrate ${opts.taskId} --branch ${branch} --root ${baseWorktreePath}`
+                : `git checkout ${baseBranch} && agentplane integrate ${opts.taskId} --branch ${branch}`;
+            throw new CliError({
+                exitCode: exitCodeForError("E_GIT"),
+                code: "E_GIT",
+                message: `integrate must run from the ${baseBranch} base checkout, not from task branch ${branch}. ` +
+                    `Rerun it against the base checkout after leaving this task worktree.`,
+                context: withDiagnosticContext({
+                    command: "integrate",
+                    task_id: opts.taskId,
+                    branch,
+                    base_branch: baseBranch,
+                    current_branch: currentBranch,
+                    ...(baseWorktreePath ? { base_worktree_path: baseWorktreePath } : {}),
+                    reason_code: "integrate_base_checkout_required",
+                }, {
+                    state: `integrate was invoked from task branch ${branch} instead of base branch ${baseBranch}`,
+                    likelyCause: "the operator is inside the task worktree, but branch_pr integrate is only valid from the registered base checkout",
+                    hint: "Use the base checkout/worktree for the resolved base branch, not the task branch worktree, when running integrate.",
+                    nextAction: {
+                        command: rerunCommand,
+                        reason: "rerun integrate against the base checkout route",
+                        reasonCode: "integrate_base_checkout_required",
+                    },
+                }),
+            });
+        }
+        throw new CliError({
+            exitCode: exitCodeForError("E_GIT"),
+            code: "E_GIT",
+            message: `integrate must run on base branch ${baseBranch} (current: ${currentBranch})`,
+        });
+    }
     await ensureCommittedPrArtifactsOnBranch({
         resolved,
         prDir,
@@ -132,6 +164,10 @@ export async function prepareIntegrate(opts) {
         preferBranchSnapshot: true,
         branchSnapshotBranch: branch,
     });
+    const protectedBaseRequiresPrMerge = await requiresPullRequestMergePath({
+        gitRoot: resolved.gitRoot,
+        baseBranch: base,
+    });
     const changedPaths = await gitDiffNames(resolved.gitRoot, base, branch);
     const tasksPath = loadedConfig.paths.tasks_path;
     if (changedPaths.includes(tasksPath)) {
@@ -145,6 +181,7 @@ export async function prepareIntegrate(opts) {
     let freshness = await assessPrArtifactFreshness({
         gitRoot: resolved.gitRoot,
         workflowDir: loadedConfig.paths.workflow_dir,
+        tasksPath: loadedConfig.paths.tasks_path,
         taskId: opts.taskId,
         branchHeadSha,
         metaHeadSha: metaSource.head_sha ?? null,
@@ -181,6 +218,7 @@ export async function prepareIntegrate(opts) {
             freshness = await assessPrArtifactFreshness({
                 gitRoot: resolved.gitRoot,
                 workflowDir: loadedConfig.paths.workflow_dir,
+                tasksPath: loadedConfig.paths.tasks_path,
                 taskId: opts.taskId,
                 branchHeadSha,
                 metaHeadSha: repairedMetaSource.head_sha ?? null,
@@ -218,6 +256,7 @@ export async function prepareIntegrate(opts) {
         task,
         baseBranch,
         currentBranch,
+        protectedBaseRequiresPrMerge,
         prDir,
         metaPath,
         diffstatPath,

package/dist/commands/pr/internal/auto-commit.d.ts

@@ -0,0 +1,7 @@
+import type { CommandContext } from "../../shared/task-backend.js";
+export declare function maybeAutoCommitTaskPrArtifacts(opts: {
+    ctx: CommandContext;
+    taskId: string;
+    branch: string;
+}): Promise<boolean>;
+//# sourceMappingURL=auto-commit.d.ts.map

package/dist/commands/pr/internal/auto-commit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-commit.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/auto-commit.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAiCnE,wBAAsB,8BAA8B,CAAC,IAAI,EAAE;IACzD,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CA8CnB"}

package/dist/commands/pr/internal/auto-commit.js

@@ -0,0 +1,69 @@
+import path from "node:path";
+import { extractTaskSuffix } from "@agentplaneorg/core";
+import { buildGitCommitEnv } from "../../guard/impl/env.js";
+import { toGitPath } from "../../shared/git-diff.js";
+import { execFileAsync, gitEnv } from "../../shared/git.js";
+import { gitCurrentBranch } from "../../shared/git-ops.js";
+function taskPrDirPrefix(workflowDir, taskId) {
+    return `${toGitPath(path.join(workflowDir, taskId, "pr"))}/`;
+}
+function taskReadmePath(workflowDir, taskId) {
+    return toGitPath(path.join(workflowDir, taskId, "README.md"));
+}
+function isTaskPacketPath(opts) {
+    const normalized = toGitPath(opts.relPath);
+    return (normalized === taskReadmePath(opts.workflowDir, opts.taskId) ||
+        normalized.startsWith(taskPrDirPrefix(opts.workflowDir, opts.taskId)));
+}
+async function readCachedPaths(gitRoot) {
+    const { stdout } = await execFileAsync("git", ["diff", "--cached", "--name-only", "--relative"], {
+        cwd: gitRoot,
+        env: gitEnv(),
+    });
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function taskPrArtifactRefreshMessage(taskId) {
+    return `📝 ${extractTaskSuffix(taskId)} task: refresh PR artifacts`;
+}
+export async function maybeAutoCommitTaskPrArtifacts(opts) {
+    if (opts.ctx.config.workflow_mode !== "branch_pr")
+        return false;
+    const branchText = await gitCurrentBranch(opts.ctx.resolvedProject.gitRoot);
+    const currentBranch = branchText.trim();
+    if (!currentBranch || currentBranch !== opts.branch.trim())
+        return false;
+    const changedPaths = await opts.ctx.git.statusChangedPaths();
+    const taskPacketPaths = changedPaths.filter((relPath) => isTaskPacketPath({
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        relPath,
+    }));
+    if (taskPacketPaths.length === 0)
+        return false;
+    const cachedPaths = await readCachedPaths(opts.ctx.resolvedProject.gitRoot);
+    if (cachedPaths.some((relPath) => !isTaskPacketPath({
+        workflowDir: opts.ctx.config.paths.workflow_dir,
+        taskId: opts.taskId,
+        relPath,
+    }))) {
+        return false;
+    }
+    await opts.ctx.git.stage(taskPacketPaths);
+    await opts.ctx.git.commit({
+        message: taskPrArtifactRefreshMessage(opts.taskId),
+        env: buildGitCommitEnv({
+            taskId: opts.taskId,
+            allowTasks: true,
+            allowBase: false,
+            allowPolicy: false,
+            allowConfig: false,
+            allowHooks: false,
+            allowCI: false,
+        }),
+    });
+    opts.ctx.git.invalidateStatus();
+    return true;
+}

package/dist/commands/pr/internal/freshness.d.ts

@@ -8,6 +8,7 @@ export type PrArtifactFreshness = {
 export declare function assessPrArtifactFreshness(opts: {
     gitRoot: string;
     workflowDir: string;
+    tasksPath?: string;
     taskId: string;
     branchHeadSha: string;
     metaHeadSha: unknown;

package/dist/commands/pr/internal/freshness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/freshness.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAgD/B"}
+{"version":3,"file":"freshness.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/freshness.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,mBAAmB,GAAG;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEF,wBAAsB,yBAAyB,CAAC,IAAI,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,qBAAqB,EAAE,OAAO,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAkD/B"}

package/dist/commands/pr/internal/freshness.js

@@ -15,6 +15,7 @@ export async function assessPrArtifactFreshness(opts) {
         (await isTaskLocalOnlyAdvance({
             gitRoot: opts.gitRoot,
             workflowDir: opts.workflowDir,
+            tasksPath: opts.tasksPath,
             taskId: opts.taskId,
             fromRef: metaHeadSha,
             toRef: opts.branchHeadSha,
@@ -33,6 +34,7 @@ export async function assessPrArtifactFreshness(opts) {
             (await isTaskLocalOnlyAdvance({
                 gitRoot: opts.gitRoot,
                 workflowDir: opts.workflowDir,
+                tasksPath: opts.tasksPath,
                 taskId: opts.taskId,
                 fromRef: metaLastVerifiedSha,
                 toRef: opts.branchHeadSha,

package/dist/commands/pr/internal/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAsFtC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAyOF,KAAK,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAmCpC,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,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,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B,GAAG,IAAI,CAAC,CAmDR;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B,GAAG,OAAO,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,CAAC,CA6SD"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../../src/commands/pr/internal/sync.ts"],"names":[],"mappings":"AAqBA,OAAO,EAML,KAAK,MAAM,EACZ,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,8BAA8B,CAAC;AAoFtC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,iBAAiB,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AA6SF,KAAK,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAmCpC,wBAAsB,uBAAuB,CAAC,IAAI,EAAE;IAClD,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,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/B,GAAG,IAAI,CAAC,CAmDR;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B,GAAG,OAAO,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B,CAAC,CA4TD"}

package/dist/commands/pr/internal/sync.js

@@ -1,6 +1,6 @@
 import { mkdir, readFile, rm } from "node:fs/promises";
 import path from "node:path";
-import { resolveBaseBranch } from "@agentplaneorg/core";
+import { extractTaskSuffix, resolveBaseBranch } from "@agentplaneorg/core";
 import { mapBackendError } from "../../../cli/error-map.js";
 import { exitCodeForError } from "../../../cli/exit-codes.js";
 import { fileExists } from "../../../cli/fs-utils.js";
@@ -9,13 +9,13 @@ import { CliError } from "../../../shared/errors.js";
 import { writeJsonStableIfChanged, writeTextIfChanged } from "../../../shared/write-if-changed.js";
 import { execFileAsync, gitEnv } from "../../shared/git.js";
 import { gitDiffStat } from "../../shared/git-diff.js";
-import { gitCurrentBranch } from "../../shared/git-ops.js";
+import { gitBranchUpstream, gitCurrentBranch } from "../../shared/git-ops.js";
 import { parseTaskIdFromBranch } from "../../shared/git-worktree.js";
 import { isTransientGhTransportError, normalizeGhTransportError, withGhTransportRetry, } from "../../shared/gh-transport.js";
 import { INCIDENTS_POLICY_PATH } from "../../incidents/shared.js";
-import { buildObservedGithubPrMeta, buildOpenedPrMeta, resolvePrArtifactHeadSha, buildUpdatedPrMeta, parsePrMeta, } from "../../shared/pr-meta.js";
-import { loadBackendTask, loadCommandContext, } from "../../shared/task-backend.js";
+import { buildObservedGithubPrMeta, buildOpenedPrMeta, buildUpdatedPrMeta, resolvePrArtifactHeadSha, parsePrMeta, } from "../../shared/pr-meta.js";
 import { isTaskLocalOnlyAdvance } from "../../shared/task-local-freshness.js";
+import { loadBackendTask, loadCommandContext, } from "../../shared/task-backend.js";
 import { resolvePrPaths } from "./pr-paths.js";
 import { readPrHandoffNotes } from "./note-store.js";
 import { ghEnv } from "./gh-api.js";
@@ -147,6 +147,36 @@ function formatGithubPrLink(prNumber, prUrl, verb) {
         ? `${verb} GitHub PR #${prNumber}: ${prUrl.trim()}`
         : `${verb} GitHub PR #${prNumber}`;
 }
+function shouldPersistObservedGithubPrMeta(observed) {
+    if (!observed)
+        return false;
+    return observed.status === "MERGED";
+}
+function taskPrArtifactRefreshMessage(taskId) {
+    return `📝 ${extractTaskSuffix(taskId)} task: refresh PR artifacts`;
+}
+async function resolveRenderableBranchHead(opts) {
+    const branchHeadSha = await resolveBranchHeadSha({
+        gitRoot: opts.gitRoot,
+        branch: opts.branch,
+    });
+    if (!branchHeadSha)
+        return { headSha: null, artifactRefresh: false };
+    try {
+        const { stdout: subjectStdout } = await execFileAsync("git", ["log", "-1", "--pretty=%s", branchHeadSha], {
+            cwd: opts.gitRoot,
+            env: gitEnv(),
+        });
+        const subject = subjectStdout.trim();
+        return {
+            headSha: branchHeadSha,
+            artifactRefresh: subject === taskPrArtifactRefreshMessage(opts.taskId),
+        };
+    }
+    catch {
+        return { headSha: branchHeadSha, artifactRefresh: false };
+    }
+}
 function formatUnpublishedRemoteHeadReason(branch) {
     return (`task branch ${branch} is not yet published on origin; push it with ` +
         `\`git push -u origin ${branch}\` and rerun \`agentplane pr open\``);
@@ -248,9 +278,17 @@ async function resolveBranchHeadSha(opts) {
     }
 }
 async function computePrDiffstat(opts) {
+    const diffBaseRef = await resolvePrDiffBaseRef({
+        gitRoot: opts.gitRoot,
+        baseBranch: opts.baseBranch,
+    });
+    const taskDir = path.dirname(opts.prDir);
     try {
-        return await gitDiffStat(opts.gitRoot, opts.baseBranch, opts.branch, {
-            excludePaths: [path.relative(opts.gitRoot, opts.prDir)],
+        return await gitDiffStat(opts.gitRoot, diffBaseRef, opts.branch, {
+            excludePaths: [
+                path.relative(opts.gitRoot, opts.prDir),
+                path.relative(opts.gitRoot, path.join(taskDir, "README.md")),
+            ],
         });
     }
     catch (err) {
@@ -259,6 +297,24 @@ async function computePrDiffstat(opts) {
         return "";
     }
 }
+async function resolvePrDiffBaseRef(opts) {
+    const upstreamRef = await gitBranchUpstream(opts.gitRoot, opts.baseBranch);
+    const candidate = upstreamRef?.trim() ?? "";
+    if (!candidate)
+        return opts.baseBranch;
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--verify", candidate], {
+            cwd: opts.gitRoot,
+            env: gitEnv(),
+        });
+        return stdout.trim() ? candidate : opts.baseBranch;
+    }
+    catch (err) {
+        if (!isUnknownRevisionError(err))
+            throw err;
+        return opts.baseBranch;
+    }
+}
 async function resolvePrSyncBranch(opts) {
     const explicitBranch = opts.branch?.trim() ?? "";
     if (explicitBranch) {
@@ -386,21 +442,28 @@ export async function syncPrArtifacts(opts) {
                 cliBaseOpt: null,
                 mode: config.workflow_mode,
             });
-            const headSha = await resolveBranchHeadSha({ gitRoot: resolved.gitRoot, branch });
+            const { headSha, artifactRefresh } = await resolveRenderableBranchHead({
+                gitRoot: resolved.gitRoot,
+                taskId: task.id,
+                branch,
+            });
             const preservePreviousHead = Boolean(existingMeta?.head_sha) &&
                 Boolean(headSha) &&
                 (await isTaskLocalOnlyAdvance({
                     gitRoot: resolved.gitRoot,
                     workflowDir: config.paths.workflow_dir,
+                    tasksPath: config.paths.tasks_path,
                     taskId: task.id,
                     fromRef: existingMeta?.head_sha ?? null,
                     toRef: headSha,
                 }));
-            const renderedHeadSha = resolvePrArtifactHeadSha({
-                previousHeadSha: existingMeta?.head_sha ?? null,
-                currentHeadSha: headSha,
-                preservePrevious: preservePreviousHead,
-            });
+            const renderedHeadSha = artifactRefresh
+                ? (existingMeta?.head_sha ?? undefined)
+                : resolvePrArtifactHeadSha({
+                    previousHeadSha: existingMeta?.head_sha ?? null,
+                    currentHeadSha: headSha,
+                    preservePrevious: preservePreviousHead,
+                });
             const preservedRenderUpdatedAt = existingMeta &&
                 (existingMeta.branch ?? null) === branch &&
                 (existingMeta.base ?? null) === (baseBranch ?? null) &&
@@ -418,7 +481,9 @@ export async function syncPrArtifacts(opts) {
                         prDir,
                     })
                     : "";
-                const renderedSummaryHeadSha = renderedHeadSha ?? headSha;
+                const renderedSummaryHeadSha = artifactRefresh
+                    ? renderedHeadSha
+                    : (renderedHeadSha ?? headSha);
                 let nextMeta = buildOpenedPrMeta({
                     taskId: task.id,
                     branch,
@@ -441,7 +506,7 @@ export async function syncPrArtifacts(opts) {
                     autoSummary: renderPrAutoSummary({
                         updatedAt: renderUpdatedAt,
                         branch,
-                        headSha: renderedSummaryHeadSha,
+                        headSha: renderedSummaryHeadSha ?? null,
                         diffstat,
                     }),
                 });
@@ -451,11 +516,13 @@ export async function syncPrArtifacts(opts) {
                     baseBranch,
                 });
                 if (observedGithubPr) {
-                    nextMeta = buildObservedGithubPrMeta({
-                        meta: nextMeta,
-                        observed: observedGithubPr,
-                        at: now,
-                    });
+                    if (shouldPersistObservedGithubPrMeta(observedGithubPr)) {
+                        nextMeta = buildObservedGithubPrMeta({
+                            meta: nextMeta,
+                            observed: observedGithubPr,
+                            at: now,
+                        });
+                    }
                     openOutcome = {
                         action: "linked-existing",
                         message: formatGithubPrLink(observedGithubPr.prNumber, observedGithubPr.prUrl, "linked to"),
@@ -476,11 +543,13 @@ export async function syncPrArtifacts(opts) {
                         body: githubBody,
                     });
                     if (createdGithubPr.observed) {
-                        nextMeta = buildObservedGithubPrMeta({
-                            meta: nextMeta,
-                            observed: createdGithubPr.observed,
-                            at: now,
-                        });
+                        if (shouldPersistObservedGithubPrMeta(createdGithubPr.observed)) {
+                            nextMeta = buildObservedGithubPrMeta({
+                                meta: nextMeta,
+                                observed: createdGithubPr.observed,
+                                at: now,
+                            });
+                        }
                         openOutcome = {
                             action: "created",
                             message: formatGithubPrLink(createdGithubPr.observed.prNumber, createdGithubPr.observed.prUrl, "created"),
@@ -496,7 +565,7 @@ export async function syncPrArtifacts(opts) {
                 const nextAutoSummary = renderPrAutoSummary({
                     updatedAt: renderUpdatedAt,
                     branch,
-                    headSha: renderedSummaryHeadSha,
+                    headSha: renderedSummaryHeadSha ?? null,
                     diffstat,
                 });
                 const nextReview = renderPrReviewDocument({
@@ -550,7 +619,7 @@ export async function syncPrArtifacts(opts) {
                 branch,
                 baseBranch,
             });
-            if (observedGithubPr) {
+            if (shouldPersistObservedGithubPrMeta(observedGithubPr)) {
                 nextMeta = buildObservedGithubPrMeta({
                     meta: nextMeta,
                     observed: observedGithubPr,
@@ -560,7 +629,9 @@ export async function syncPrArtifacts(opts) {
             const nextAutoSummary = renderPrAutoSummary({
                 updatedAt: nextMeta.updated_at,
                 branch,
-                headSha: nextMeta.head_sha ?? renderedHeadSha ?? headSha,
+                headSha: artifactRefresh
+                    ? (nextMeta.head_sha ?? renderedHeadSha ?? null)
+                    : (nextMeta.head_sha ?? renderedHeadSha ?? headSha ?? null),
                 diffstat,
             });
             const nextReview = renderPrReviewDocument({

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

@@ -1 +1 @@
-{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/open.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAiBhE,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiClB"}
+{"version":3,"file":"open.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/open.ts"],"names":[],"mappings":"AAQA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAuCpF,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgElB"}

package/dist/commands/pr/open.js

@@ -3,6 +3,10 @@ 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 { execFileAsync, gitEnv } from "../shared/git.js";
+import { gitBranchUpstream } from "../shared/git-ops.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { maybeAutoCommitTaskPrArtifacts } from "./internal/auto-commit.js";
 import { syncPrArtifacts } from "./internal/sync.js";
 function prOpenOutcomeDetails(meta, openOutcome) {
     if (openOutcome)
@@ -14,6 +18,24 @@ function prOpenOutcomeDetails(meta, openOutcome) {
     }
     return "local PR artifacts synced; remote PR creation staged";
 }
+async function pushTaskBranchUpstreamIfConfigured(opts) {
+    const upstream = await gitBranchUpstream(opts.gitRoot, opts.branch);
+    const trimmed = upstream?.trim() ?? "";
+    if (!trimmed)
+        return false;
+    const slashIndex = trimmed.indexOf("/");
+    if (slashIndex <= 0 || slashIndex === trimmed.length - 1)
+        return false;
+    const remote = trimmed.slice(0, slashIndex);
+    const upstreamBranch = trimmed.slice(slashIndex + 1);
+    if (!remote || !upstreamBranch)
+        return false;
+    await execFileAsync("git", ["push", "--no-verify", remote, `HEAD:${upstreamBranch}`], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+    });
+    return true;
+}
 export async function cmdPrOpen(opts) {
     try {
         const output = createCliEmitter();
@@ -25,16 +47,43 @@ export async function cmdPrOpen(opts) {
                 message: "Invalid value for --author.",
             });
         }
-        const { meta, prDir, resolved, openOutcome } = await syncPrArtifacts({
-            ctx: opts.ctx,
+        const commandCtx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const initialSync = await syncPrArtifacts({
+            ctx: commandCtx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             taskId: opts.taskId,
             mode: "open",
             author,
             branch: opts.branch,
-            remoteMode: opts.syncOnly ? "sync-only" : "auto",
+            remoteMode: "sync-only",
         });
+        const didAutoCommit = initialSync.meta.branch
+            ? await maybeAutoCommitTaskPrArtifacts({
+                ctx: commandCtx,
+                taskId: opts.taskId,
+                branch: initialSync.meta.branch,
+            })
+            : false;
+        if (didAutoCommit && !opts.syncOnly && initialSync.meta.branch) {
+            await pushTaskBranchUpstreamIfConfigured({
+                gitRoot: commandCtx.resolvedProject.gitRoot,
+                branch: initialSync.meta.branch,
+            });
+        }
+        const { meta, prDir, resolved, openOutcome } = opts.syncOnly
+            ? initialSync
+            : await syncPrArtifacts({
+                ctx: commandCtx,
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride,
+                taskId: opts.taskId,
+                mode: "open",
+                author,
+                branch: opts.branch,
+                remoteMode: "auto",
+            });
         output.success("pr open", path.relative(resolved.gitRoot, prDir), prOpenOutcomeDetails(meta, openOutcome ?? null));
         return 0;
     }

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

@@ -1 +1 @@
-{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/update.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAmEnC,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,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,CA4BlB"}
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../../src/commands/pr/update.ts"],"names":[],"mappings":"AAOA,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,2BAA2B,CAAC;AAqEnC,wBAAsB,WAAW,CAAC,IAAI,EAAE;IACtC,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,CAsClB"}

package/dist/commands/pr/update.js

@@ -5,6 +5,7 @@ import { createCliEmitter } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
 import { gitRevParse } from "../shared/git-ops.js";
 import { loadBackendTask, loadCommandContext, } from "../shared/task-backend.js";
+import { maybeAutoCommitTaskPrArtifacts } from "./internal/auto-commit.js";
 import { assessPrArtifactFreshness } from "./internal/freshness.js";
 import { syncPrArtifacts } from "./internal/sync.js";
 async function readTextIfExists(filePath) {
@@ -38,6 +39,7 @@ async function warnOnStaleVerifyAfterUpdate(opts) {
     const freshness = await assessPrArtifactFreshness({
         gitRoot: opts.resolved.gitRoot,
         workflowDir: path.join(opts.resolved.gitRoot, config.paths.workflow_dir),
+        tasksPath: config.paths.tasks_path,
         taskId: opts.taskId,
         branchHeadSha,
         metaHeadSha: opts.meta.head_sha ?? null,
@@ -54,16 +56,25 @@ async function warnOnStaleVerifyAfterUpdate(opts) {
 export async function cmdPrUpdate(opts) {
     try {
         const output = createCliEmitter();
+        const commandCtx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
         const { meta, prDir, resolved } = await syncPrArtifacts({
-            ctx: opts.ctx,
+            ctx: commandCtx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             taskId: opts.taskId,
             mode: "update",
         });
+        if (meta.branch) {
+            await maybeAutoCommitTaskPrArtifacts({
+                ctx: commandCtx,
+                taskId: opts.taskId,
+                branch: meta.branch,
+            });
+        }
         await warnOnStaleVerifyAfterUpdate({
             output,
-            ctx: opts.ctx,
+            ctx: commandCtx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             taskId: opts.taskId,

package/dist/commands/recipes/active.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesActiveParsed = {
+    full: boolean;
+};
+export declare const recipesActiveSpec: CommandSpec<RecipesActiveParsed>;
+export declare const runRecipesActive: CommandHandler<RecipesActiveParsed>;
+//# sourceMappingURL=active.command.d.ts.map

package/dist/commands/recipes/active.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/active.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAS9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAC2B,CAAC"}

package/dist/commands/recipes/active.command.js

@@ -0,0 +1,12 @@
+import { cmdRecipeActiveParsed } from "../recipes.js";
+export const recipesActiveSpec = {
+    id: ["recipes", "active"],
+    group: "Recipes",
+    summary: "List active project overlays.",
+    options: [
+        { kind: "boolean", name: "full", default: false, description: "Print full JSON payload." },
+    ],
+    examples: [{ cmd: "agentplane recipes active", why: "Show overlays active for the project." }],
+    parse: (raw) => ({ full: raw.opts.full === true }),
+};
+export const runRecipesActive = (ctx, parsed) => cmdRecipeActiveParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, full: parsed.full });

package/dist/commands/recipes/add.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesAddParsed = {
+    recipeRef: string;
+    mode?: "copy" | "link";
+};
+export declare const recipesAddSpec: CommandSpec<RecipesAddParsed>;
+export declare const runRecipesAdd: CommandHandler<RecipesAddParsed>;
+//# sourceMappingURL=add.command.d.ts.map

package/dist/commands/recipes/add.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/add.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAyBxD,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAMvD,CAAC"}