agentplane 0.3.10 → 0.3.12

package/dist/commands/release/plan.command.js

@@ -18,6 +18,43 @@ function parseSemver(version) {
         return null;
     return { major, minor, patch };
 }
+function compareSemver(left, right) {
+    const leftParsed = parseSemver(left);
+    const rightParsed = parseSemver(right);
+    if (!leftParsed || !rightParsed) {
+        throw new CliError({
+            exitCode: exitCodeForError("E_VALIDATION"),
+            code: "E_VALIDATION",
+            message: `Invalid semver comparison: ${left} vs ${right}`,
+        });
+    }
+    if (leftParsed.major !== rightParsed.major)
+        return leftParsed.major - rightParsed.major;
+    if (leftParsed.minor !== rightParsed.minor)
+        return leftParsed.minor - rightParsed.minor;
+    return leftParsed.patch - rightParsed.patch;
+}
+function normalizeTagVersion(tag) {
+    if (!tag)
+        return null;
+    return tag.startsWith("v") ? tag.slice(1) : tag;
+}
+function listMissingPatchTags(fromVersion, toVersion) {
+    const fromParsed = parseSemver(fromVersion);
+    const toParsed = parseSemver(toVersion);
+    if (!fromParsed || !toParsed)
+        return [];
+    if (fromParsed.major !== toParsed.major ||
+        fromParsed.minor !== toParsed.minor ||
+        toParsed.patch <= fromParsed.patch) {
+        return [];
+    }
+    const out = [];
+    for (let patch = fromParsed.patch + 1; patch <= toParsed.patch; patch += 1) {
+        out.push(`v${fromParsed.major}.${fromParsed.minor}.${patch}`);
+    }
+    return out;
+}
 function bumpVersion(version, bump) {
     const parsed = parseSemver(version);
     if (!parsed) {
@@ -220,6 +257,17 @@ export const runReleasePlan = async (ctx, flags) => {
         });
     }
     const prevTag = flags.since ?? (await getLatestSemverTag(gitRoot));
+    const latestPublishedVersion = normalizeTagVersion(prevTag);
+    if (latestPublishedVersion && compareSemver(coreVersion, latestPublishedVersion) > 0) {
+        const missingTags = listMissingPatchTags(latestPublishedVersion, coreVersion);
+        const missingText = missingTags.length > 0 ? missingTags.join(", ") : coreVersion;
+        throw new CliError({
+            exitCode: exitCodeForError("E_VALIDATION"),
+            code: "E_VALIDATION",
+            message: `Release planning blocked: workspace version is already ${coreVersion} while the latest published/tagged release is ${prevTag}. ` +
+                `Publish or recover the missing release sequence first: ${missingText}.`,
+        });
+    }
     const nextVersion = bumpVersion(coreVersion, flags.bump);
     const nextTag = `v${nextVersion}`;
     const changes = await listChanges(gitRoot, prevTag);

package/dist/commands/shared/gh-transport.d.ts

@@ -0,0 +1,16 @@
+export declare const GH_LOOKUP_MAX_ATTEMPTS = 3;
+export declare const GH_LOOKUP_BASE_DELAY_MS = 250;
+export declare function normalizeGhTransportError(err: unknown): string;
+export declare function isTransientGhTransportError(err: unknown): boolean;
+export declare function withGhTransportRetry<T>(operation: () => Promise<T>, opts: {
+    label: string;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    onRetry?: (ctx: {
+        attempt: number;
+        maxAttempts: number;
+        error: unknown;
+        label: string;
+    }) => void;
+}): Promise<T>;
+//# sourceMappingURL=gh-transport.d.ts.map

package/dist/commands/shared/gh-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gh-transport.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/gh-transport.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,IAAI,CAAC;AACxC,eAAO,MAAM,uBAAuB,MAAM,CAAC;AA8B3C,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAU9D;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIjE;AAOD,wBAAsB,oBAAoB,CAAC,CAAC,EAC1C,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,IAAI,EAAE;IACJ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,EAAE,MAAM,CAAC;KACf,KAAK,IAAI,CAAC;CACZ,GACA,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/commands/shared/gh-transport.js

@@ -0,0 +1,71 @@
+export const GH_LOOKUP_MAX_ATTEMPTS = 3;
+export const GH_LOOKUP_BASE_DELAY_MS = 250;
+const GH_TRANSIENT_ERROR_PATTERNS = [
+    /eof\b/i,
+    /tls handshake timeout/i,
+    /ssl_error_syscall/i,
+    /connection reset by peer/i,
+    /\beconnreset\b/i,
+    /\betimedout\b/i,
+    /socket hang up/i,
+    /temporary failure in name resolution/i,
+    /network is unreachable/i,
+    /server closed the connection/i,
+];
+const GH_PERMANENT_ERROR_PATTERNS = [
+    /authentication required/i,
+    /not logged into github/i,
+    /could not resolve to a pull request/i,
+    /graphql: field/i,
+    /bad credentials/i,
+    /permission denied/i,
+    /\b404\b/i,
+    /\b422\b/i,
+    /\b403\b/i,
+    /\b401\b/i,
+    /unknown command/i,
+    /usage:/i,
+];
+export function normalizeGhTransportError(err) {
+    if (err instanceof Error) {
+        const parts = [err.name, err.message];
+        const stderr = err.stderr;
+        const stdout = err.stdout;
+        if (typeof stderr === "string" && stderr.trim())
+            parts.push(stderr);
+        if (typeof stdout === "string" && stdout.trim())
+            parts.push(stdout);
+        return parts.filter((part) => part.trim().length > 0).join("\n");
+    }
+    return String(err);
+}
+export function isTransientGhTransportError(err) {
+    const text = normalizeGhTransportError(err);
+    if (GH_PERMANENT_ERROR_PATTERNS.some((pattern) => pattern.test(text)))
+        return false;
+    return GH_TRANSIENT_ERROR_PATTERNS.some((pattern) => pattern.test(text));
+}
+async function sleep(ms) {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+export async function withGhTransportRetry(operation, opts) {
+    const maxAttempts = opts.maxAttempts ?? GH_LOOKUP_MAX_ATTEMPTS;
+    const baseDelayMs = opts.baseDelayMs ?? GH_LOOKUP_BASE_DELAY_MS;
+    let lastError = null;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            lastError = error;
+            if (!isTransientGhTransportError(error) || attempt === maxAttempts) {
+                throw error;
+            }
+            opts.onRetry?.({ attempt, maxAttempts, error, label: opts.label });
+            await sleep(baseDelayMs * attempt);
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}

package/dist/commands/shared/git-diff.d.ts

@@ -1,7 +1,9 @@
 export declare function toGitPath(filePath: string): string;
 export declare function gitShowFile(cwd: string, ref: string, relPath: string): Promise<string>;
 export declare function gitDiffNames(cwd: string, base: string, branch: string): Promise<string[]>;
-export declare function gitDiffStat(cwd: string, base: string, branch: string): Promise<string>;
+export declare function gitDiffStat(cwd: string, base: string, branch: string, opts?: {
+    excludePaths?: string[];
+}): Promise<string>;
 export declare function gitAheadBehind(cwd: string, base: string, branch: string): Promise<{
     ahead: number;
     behind: number;

package/dist/commands/shared/git-diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-diff.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-diff.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5F;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAS/F;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5F;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAa5C"}
+{"version":3,"file":"git-diff.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-diff.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAM5F;AAED,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAS/F;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACjC,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAa5C"}

package/dist/commands/shared/git-diff.js

@@ -20,8 +20,16 @@ export async function gitDiffNames(cwd, base, branch) {
         .map((line) => line.trim())
         .filter((line) => line.length > 0);
 }
-export async function gitDiffStat(cwd, base, branch) {
-    const { stdout } = await execFileAsync("git", ["diff", "--stat", `${base}...${branch}`], {
+export async function gitDiffStat(cwd, base, branch, opts) {
+    const args = ["diff", "--stat", `${base}...${branch}`];
+    const excludePaths = (opts?.excludePaths ?? [])
+        .map((relPath) => relPath.trim())
+        .filter((relPath) => relPath.length > 0)
+        .map((relPath) => `:(exclude)${toGitPath(relPath)}`);
+    if (excludePaths.length > 0) {
+        args.push("--", ".", ...excludePaths);
+    }
+    const { stdout } = await execFileAsync("git", args, {
         cwd,
         env: gitEnv(),
     });

package/dist/commands/shared/git-ops.d.ts

@@ -1,6 +1,7 @@
 export declare function gitRevParse(cwd: string, args: string[]): Promise<string>;
 export declare function gitCurrentBranch(cwd: string): Promise<string>;
 export declare function gitBranchExists(cwd: string, branch: string): Promise<boolean>;
+export declare function gitIsAncestor(cwd: string, maybeAncestor: string, descendant: string): Promise<boolean>;
 export declare function gitBranchUpstream(cwd: string, branch: string): Promise<string | null>;
 export declare function gitListBranches(cwd: string): Promise<string[]>;
 export declare function gitStagedPaths(cwd: string): Promise<string[]>;

package/dist/commands/shared/git-ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-ops.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-ops.ts"],"names":[],"mappings":"AAMA,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9E;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBnE;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnF;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe3F;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASnE;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG7E;AAED,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACtD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAe9F;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDlB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB"}
+{"version":3,"file":"git-ops.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-ops.ts"],"names":[],"mappings":"AAMA,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9E;AAED,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBnE;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYnF;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAe3F;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASpE;AAED,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASnE;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAG7E;AAED,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GACtD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgB5E;AAED,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAe9F;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiDlB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB"}

package/dist/commands/shared/git-ops.js

@@ -52,6 +52,21 @@ export async function gitBranchExists(cwd, branch) {
         throw err;
     }
 }
+export async function gitIsAncestor(cwd, maybeAncestor, descendant) {
+    try {
+        await execFileAsync("git", ["merge-base", "--is-ancestor", maybeAncestor, descendant], {
+            cwd,
+            env: gitEnv(),
+        });
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 1)
+            return false;
+        throw err;
+    }
+}
 export async function gitBranchUpstream(cwd, branch) {
     try {
         const { stdout } = await execFileAsync("git", ["for-each-ref", "--format=%(upstream:short)", `refs/heads/${branch}`], {

package/dist/commands/shared/git-worktree.d.ts

@@ -4,5 +4,7 @@ export declare function listWorktrees(cwd: string): Promise<{
 }[]>;
 export declare function findWorktreeForBranch(cwd: string, branch: string): Promise<string | null>;
 export declare function parseTaskIdFromBranch(prefix: string, branch: string): string | null;
+export declare function parseTaskIdFromCloseBranch(branch: string): string | null;
+export declare function gitListBranchesByPrefixes(cwd: string, prefixes: string[]): Promise<string[]>;
 export declare function gitListTaskBranches(cwd: string, prefix: string): Promise<string[]>;
 //# sourceMappingURL=git-worktree.d.ts.map

package/dist/commands/shared/git-worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"git-worktree.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-worktree.ts"],"names":[],"mappings":"AAEA,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,CAAC,CAoBpD;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ/F;AAMD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMnF;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUxF"}
+{"version":3,"file":"git-worktree.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/git-worktree.ts"],"names":[],"mappings":"AAEA,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,CAAC,CAoBpD;AAED,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ/F;AAMD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMnF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAMxE;AAED,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAkBnB;AAED,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAExF"}

package/dist/commands/shared/git-worktree.js

@@ -39,10 +39,30 @@ export function parseTaskIdFromBranch(prefix, branch) {
     const taskId = rest.split("/", 1)[0];
     return taskId ? taskId.trim() : null;
 }
-export async function gitListTaskBranches(cwd, prefix) {
-    const { stdout } = await execFileAsync("git", ["for-each-ref", "--format=%(refname:short)", `refs/heads/${prefix}`], { cwd, env: gitEnv() });
+export function parseTaskIdFromCloseBranch(branch) {
+    const normalized = stripBranchRef(branch);
+    if (!normalized.startsWith("task-close/"))
+        return null;
+    const rest = normalized.slice("task-close/".length);
+    const taskId = rest.split("/", 1)[0];
+    return taskId ? taskId.trim() : null;
+}
+export async function gitListBranchesByPrefixes(cwd, prefixes) {
+    const patterns = prefixes
+        .map((prefix) => prefix.trim())
+        .filter((prefix) => prefix.length > 0)
+        .map((prefix) => `refs/heads/${prefix}`);
+    if (patterns.length === 0)
+        return [];
+    const { stdout } = await execFileAsync("git", ["for-each-ref", "--format=%(refname:short)", ...patterns], {
+        cwd,
+        env: gitEnv(),
+    });
     return stdout
         .split("\n")
         .map((line) => line.trim())
         .filter((line) => line.length > 0);
 }
+export async function gitListTaskBranches(cwd, prefix) {
+    return await gitListBranchesByPrefixes(cwd, [prefix]);
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"merged-branch-cleanup.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/merged-branch-cleanup.ts"],"names":[],"mappings":"AAKA,MAAM,MAAM,yBAAyB,GAAG;IACtC,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,wBAAwB,CAAC,IAAI,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA4CrC"}

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

@@ -0,0 +1,46 @@
+import { execFileAsync, gitEnv } from "./git.js";
+import { gitBranchExists } from "./git-ops.js";
+import { findWorktreeForBranch } from "./git-worktree.js";
+import { isPathWithin, resolvePathFallback } from "./path.js";
+export async function cleanupMergedLocalBranch(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,
+    };
+}

package/dist/commands/shared/post-commit-pr-artifacts.d.ts

@@ -0,0 +1,9 @@
+import type { CommandContext } from "../shared/task-backend.js";
+export declare function refreshBranchPrArtifactsAfterTaskCommit(opts: {
+    ctx: CommandContext;
+    cwd: string;
+    rootOverride?: string;
+    taskId: string;
+    quiet: boolean;
+}): Promise<void>;
+//# sourceMappingURL=post-commit-pr-artifacts.d.ts.map

package/dist/commands/shared/post-commit-pr-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-commit-pr-artifacts.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/post-commit-pr-artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AA2BhE,wBAAsB,uCAAuC,CAAC,IAAI,EAAE;IAClE,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB"}

package/dist/commands/shared/post-commit-pr-artifacts.js

@@ -0,0 +1,57 @@
+import { warnMessage } from "../../cli/output.js";
+import { normalizeGhTransportError } from "../shared/gh-transport.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+import { ensurePrArtifactsSynced } from "../pr/internal/sync.js";
+import { isTaskLocalOnlyAdvance } from "./task-local-freshness.js";
+function isUnknownRevisionError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return (/unknown revision or path not in the working tree/i.test(message) ||
+        /bad revision/i.test(message) ||
+        /ambiguous argument/i.test(message));
+}
+async function resolveHeadParent(gitRoot) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "HEAD^"], {
+            cwd: gitRoot,
+            env: gitEnv(),
+        });
+        const parent = stdout.trim();
+        return parent.length > 0 ? parent : null;
+    }
+    catch (err) {
+        if (!isUnknownRevisionError(err))
+            throw err;
+        return null;
+    }
+}
+export async function refreshBranchPrArtifactsAfterTaskCommit(opts) {
+    if (opts.ctx.config.workflow_mode !== "branch_pr")
+        return;
+    try {
+        const gitRoot = opts.ctx.resolvedProject.gitRoot;
+        const headParent = await resolveHeadParent(gitRoot);
+        if (await isTaskLocalOnlyAdvance({
+            gitRoot,
+            workflowDir: opts.ctx.config.paths.workflow_dir,
+            tasksPath: opts.ctx.config.paths.tasks_path,
+            taskId: opts.taskId,
+            fromRef: headParent,
+            toRef: "HEAD",
+        })) {
+            return;
+        }
+        await ensurePrArtifactsSynced({
+            ctx: opts.ctx,
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride,
+            taskId: opts.taskId,
+        });
+    }
+    catch (err) {
+        if (opts.quiet)
+            return;
+        const detail = normalizeGhTransportError(err).trim();
+        const suffix = detail ? ` (${detail})` : "";
+        process.stderr.write(`${warnMessage(`task commit succeeded but PR artifacts refresh failed for ${opts.taskId}; run \`agentplane pr update ${opts.taskId}\`${suffix}`)}\n`);
+    }
+}

package/dist/commands/shared/pr-meta.d.ts

@@ -1,5 +1,14 @@
 import { type TaskPrMeta } from "@agentplaneorg/core";
 export type PrMeta = TaskPrMeta;
+export type ObservedGithubPrState = {
+    prNumber: number;
+    prUrl: string | null;
+    status: "OPEN" | "CLOSED" | "MERGED";
+    mergedAt?: string | null;
+    mergeCommit?: string | null;
+    base?: string | null;
+    headSha?: string | null;
+};
 export type PrArtifactTextState = {
     diffstatText: string | null;
     verifyLogText: string | null;
@@ -23,6 +32,16 @@ export declare function buildUpdatedPrMeta(opts: {
     base?: string | null;
     headSha?: string | null;
 }): PrMeta;
+export declare function resolvePrArtifactHeadSha(opts: {
+    previousHeadSha?: string | null;
+    currentHeadSha?: string | null;
+    preservePrevious: boolean;
+}): string | undefined;
+export declare function buildObservedGithubPrMeta(opts: {
+    meta: PrMeta;
+    observed: ObservedGithubPrState;
+    at: string;
+}): PrMeta;
 export declare function buildVerifiedPrMeta(opts: {
     meta: PrMeta;
     at: string;
@@ -46,6 +65,7 @@ export type ShellInvocation = {
 };
 export declare function resolveShellInvocation(command: string): ShellInvocation;
 export declare function parsePrMeta(raw: string, taskId: string): PrMeta;
+export declare function parsePrMetaForwardCompatible(raw: string, taskId: string): PrMeta;
 export declare function extractLastVerifiedSha(logText: string): string | null;
 export declare function appendVerifyLog(logPath: string, header: string, content: string): Promise<void>;
 export declare function runShellCommand(command: string, cwd: string): Promise<{

package/dist/commands/shared/pr-meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-meta.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/pr-meta.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAI1E,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAChC,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAOF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,MAAM,CAoBT;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,GAAG,MAAM,CAgBT;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,GAAG,MAAM,CAST;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,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,EAAE,EAAE,MAAM,CAAC;IACX,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC,GAAG,MAAM,CAsBT;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAQvE;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAW/D;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQrE;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAMf;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAqBD"}
+{"version":3,"file":"pr-meta.d.ts","sourceRoot":"","sources":["../../../src/commands/shared/pr-meta.ts"],"names":[],"mappings":"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"}

package/dist/commands/shared/pr-meta.js

@@ -18,8 +18,14 @@ export function buildOpenedPrMeta(opts) {
         schema_version: 1,
         task_id: opts.taskId,
         branch: opts.branch,
+        pr_number: opts.previousMeta?.pr_number,
+        pr_url: opts.previousMeta?.pr_url,
         created_at: opts.previousMeta?.created_at ?? opts.at,
         updated_at: changed ? opts.at : (opts.previousMeta?.updated_at ?? opts.at),
+        status: opts.previousMeta?.status,
+        merge_strategy: opts.previousMeta?.merge_strategy,
+        merged_at: opts.previousMeta?.merged_at,
+        merge_commit: opts.previousMeta?.merge_commit,
         last_verified_sha: opts.previousMeta?.last_verified_sha ?? null,
         last_verified_at: opts.previousMeta?.last_verified_at ?? null,
         verify: opts.previousMeta?.verify ?? { status: "skipped" },
@@ -43,6 +49,46 @@ export function buildUpdatedPrMeta(opts) {
         last_verified_at: opts.meta.last_verified_at ?? null,
     };
 }
+export function resolvePrArtifactHeadSha(opts) {
+    const previousHeadSha = asNonEmptyString(opts.previousHeadSha);
+    const currentHeadSha = asNonEmptyString(opts.currentHeadSha);
+    if (opts.preservePrevious && previousHeadSha)
+        return previousHeadSha;
+    return currentHeadSha ?? previousHeadSha;
+}
+export function buildObservedGithubPrMeta(opts) {
+    const nextStatus = opts.observed.status;
+    const nextHeadSha = opts.meta.head_sha ?? opts.observed.headSha ?? undefined;
+    const nextMeta = {
+        ...opts.meta,
+        pr_number: opts.observed.prNumber,
+        pr_url: opts.observed.prUrl ?? opts.meta.pr_url,
+        status: nextStatus,
+        base: opts.observed.base ?? opts.meta.base,
+        head_sha: nextHeadSha,
+        updated_at: opts.meta.updated_at,
+    };
+    if (nextStatus === "MERGED") {
+        nextMeta.merged_at = opts.observed.mergedAt ?? opts.meta.merged_at;
+        nextMeta.merge_commit = opts.observed.mergeCommit ?? opts.meta.merge_commit;
+    }
+    else {
+        delete nextMeta.merged_at;
+        delete nextMeta.merge_commit;
+        delete nextMeta.merge_strategy;
+    }
+    const changed = nextMeta.pr_number !== opts.meta.pr_number ||
+        (nextMeta.pr_url ?? null) !== (opts.meta.pr_url ?? null) ||
+        nextMeta.status !== opts.meta.status ||
+        (nextMeta.base ?? null) !== (opts.meta.base ?? null) ||
+        (nextMeta.head_sha ?? null) !== (opts.meta.head_sha ?? null) ||
+        (nextMeta.merged_at ?? null) !== (opts.meta.merged_at ?? null) ||
+        (nextMeta.merge_commit ?? null) !== (opts.meta.merge_commit ?? null);
+    if (changed) {
+        nextMeta.updated_at = opts.at;
+    }
+    return nextMeta;
+}
 export function buildVerifiedPrMeta(opts) {
     const verifiedSha = opts.meta.head_sha ?? null;
     return {
@@ -96,6 +142,85 @@ export function parsePrMeta(raw, taskId) {
         throw new Error("pr/meta.json task_id mismatch");
     return meta;
 }
+function asNonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function asOptionalInteger(value) {
+    return Number.isInteger(value) && Number(value) > 0 ? Number(value) : undefined;
+}
+function asVerifyStatus(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const status = asNonEmptyString(value.status);
+    if (status !== "pass" && status !== "fail" && status !== "skipped")
+        return undefined;
+    const command = asNonEmptyString(value.command);
+    return command ? { status, command } : { status };
+}
+function asMergeStrategy(value) {
+    const strategy = asNonEmptyString(value);
+    return strategy === "squash" || strategy === "merge" || strategy === "rebase"
+        ? strategy
+        : undefined;
+}
+function buildForwardCompatiblePrMeta(parsed, taskId) {
+    if (parsed.schema_version !== 1)
+        return null;
+    if (asNonEmptyString(parsed.task_id) !== taskId)
+        return null;
+    const branch = asNonEmptyString(parsed.branch);
+    const createdAt = asNonEmptyString(parsed.created_at);
+    const updatedAt = asNonEmptyString(parsed.updated_at);
+    if (!branch || !createdAt || !updatedAt)
+        return null;
+    const statusCandidate = asNonEmptyString(parsed.status);
+    const status = statusCandidate === "OPEN" || statusCandidate === "CLOSED" || statusCandidate === "MERGED"
+        ? statusCandidate
+        : undefined;
+    return {
+        schema_version: 1,
+        task_id: taskId,
+        branch,
+        pr_number: asOptionalInteger(parsed.pr_number),
+        pr_url: asNonEmptyString(parsed.pr_url),
+        created_at: createdAt,
+        updated_at: updatedAt,
+        status,
+        merge_strategy: asMergeStrategy(parsed.merge_strategy),
+        merged_at: asNonEmptyString(parsed.merged_at),
+        merge_commit: asNonEmptyString(parsed.merge_commit),
+        last_verified_sha: asNonEmptyString(parsed.last_verified_sha),
+        last_verified_at: asNonEmptyString(parsed.last_verified_at),
+        verify: asVerifyStatus(parsed.verify) ?? { status: "skipped" },
+        base: asNonEmptyString(parsed.base),
+        head_sha: asNonEmptyString(parsed.head_sha),
+    };
+}
+export function parsePrMetaForwardCompatible(raw, taskId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`JSON Parse error: ${message}`);
+    }
+    try {
+        const meta = validateTaskPrMeta(parsed);
+        if (meta.task_id !== taskId)
+            throw new Error("pr/meta.json task_id mismatch");
+        return meta;
+    }
+    catch (err) {
+        const compat = buildForwardCompatiblePrMeta(parsed, taskId);
+        if (compat)
+            return compat;
+        throw err;
+    }
+}
 export function extractLastVerifiedSha(logText) {
     const regex = /verified_sha=([0-9a-f]{7,40})/gi;
     let match = null;

package/dist/commands/shared/task-backend.d.ts

@@ -29,11 +29,18 @@ export declare function loadCommandContext(opts: {
 export declare function loadTaskFromContext(opts: {
     ctx: CommandContext;
     taskId: string;
+    preferBranchSnapshot?: boolean;
+    branchSnapshotBranch?: string | null;
 }): Promise<TaskData>;
+export declare function resolveTaskBranchFromContext(opts: {
+    ctx: CommandContext;
+    taskId: string;
+}): Promise<string | null>;
 export declare function loadTaskFromBranchSnapshot(opts: {
     ctx: CommandContext;
     taskId: string;
     readmePath: string;
+    branch?: string | null;
 }): Promise<TaskData | null>;
 export declare function loadBackendTask(opts: {
     ctx?: CommandContext;