@backburner/cli 0.1.0

package/dist/src/workstreams/packet-projections.js

@@ -0,0 +1,190 @@
+/**
+ * Collects packet-scoped PR projections from a set of scanned entities.
+ * This is a pure and deterministic function.
+ */
+export function collectPacketPullRequestProjections(input) {
+    const { pullRequests, workstreams, worktrees } = input;
+    // 1. Build lookups
+    const worktreesByParentAndPacket = new Map();
+    for (const wt of worktrees) {
+        if (wt.packet) {
+            const key = `${wt.packet.parentWorkstreamId}\0${wt.packet.packetId}`;
+            const list = worktreesByParentAndPacket.get(key) || [];
+            list.push(wt);
+            worktreesByParentAndPacket.set(key, list);
+        }
+    }
+    const prsByRepoIdAndHeadBranch = new Map();
+    for (const pr of pullRequests) {
+        const key = `${pr.repoId}\0${pr.headBranch}`;
+        const list = prsByRepoIdAndHeadBranch.get(key) || [];
+        list.push(pr);
+        prsByRepoIdAndHeadBranch.set(key, list);
+    }
+    const prsByRepoIdAndNumber = new Map();
+    for (const pr of pullRequests) {
+        const key = `${pr.repoId}\0${pr.number}`;
+        prsByRepoIdAndNumber.set(key, pr);
+    }
+    const projections = [];
+    const seenProjections = new Set(); // repoSlug#prNumber#parentWorkstream.id#packet.id
+    // 2. Iterate parent workstreams deterministically
+    const sortedWorkstreams = [...workstreams].sort((a, b) => {
+        return a.repoKey.localeCompare(b.repoKey) || a.id.localeCompare(b.id);
+    });
+    for (const parentWorkstream of sortedWorkstreams) {
+        if (!parentWorkstream.packetPlan) {
+            continue;
+        }
+        const packetEntries = getPacketEntries(parentWorkstream);
+        for (const [packetId, packet] of packetEntries) {
+            let matchedInThisPacket = false;
+            // A. Worktree-backed matching (primary)
+            const key = `${parentWorkstream.id}\0${packetId}`;
+            const candidateWorktrees = worktreesByParentAndPacket.get(key) || [];
+            // Sort worktrees for determinism
+            candidateWorktrees.sort((a, b) => a.repoSlug.localeCompare(b.repoSlug) ||
+                a.branchName.localeCompare(b.branchName) ||
+                a.id.localeCompare(b.id));
+            for (const packetWorktree of candidateWorktrees) {
+                const parentIntegrationBranch = getParentIntegrationBranch(parentWorkstream, packetWorktree);
+                if (!parentIntegrationBranch) {
+                    continue;
+                }
+                const prs = prsByRepoIdAndHeadBranch.get(`${packetWorktree.repoId}\0${packetWorktree.branchName}`) || [];
+                // Sort PRs for determinism if multiple match the same branch (unlikely)
+                const sortedPrs = [...prs].sort((a, b) => a.number - b.number);
+                for (const pr of sortedPrs) {
+                    if (isEligiblePacketPr(pr, parentIntegrationBranch)) {
+                        const projectionKey = `${pr.repoSlug}#${pr.number}#${parentWorkstream.id}#${packetId}`;
+                        if (!seenProjections.has(projectionKey)) {
+                            projections.push({
+                                pullRequest: pr,
+                                parentWorkstream,
+                                packet,
+                                packetWorktree,
+                                parentIntegrationBranch,
+                                parentPullRequestNumber: parentWorkstream.integration?.prNumber
+                            });
+                            seenProjections.add(projectionKey);
+                            matchedInThisPacket = true;
+                        }
+                    }
+                }
+            }
+            // B. Fallback matching by packet.prNumber (only if no worktree match)
+            if (!matchedInThisPacket && packet.prNumber) {
+                const parentIntegrationBranch = getParentIntegrationBranch(parentWorkstream);
+                if (parentIntegrationBranch) {
+                    // Find repoId for fallback.
+                    // Try to find it from packet worktrees for this parent.
+                    let repoId = "";
+                    for (const wt of worktrees) {
+                        if (wt.packet?.parentWorkstreamId === parentWorkstream.id) {
+                            repoId = wt.repoId;
+                            break;
+                        }
+                    }
+                    let pr;
+                    if (repoId) {
+                        pr = prsByRepoIdAndNumber.get(`${repoId}\0${packet.prNumber}`);
+                    }
+                    else {
+                        // Fallback to repoSlug comparison since WorkstreamRecord doesn't have repoId
+                        for (const p of pullRequests) {
+                            if (p.repoSlug === parentWorkstream.repoKey &&
+                                p.number === packet.prNumber) {
+                                pr = p;
+                                break;
+                            }
+                        }
+                    }
+                    if (pr && isEligiblePacketPr(pr, parentIntegrationBranch)) {
+                        const projectionKey = `${pr.repoSlug}#${pr.number}#${parentWorkstream.id}#${packetId}`;
+                        if (!seenProjections.has(projectionKey)) {
+                            projections.push({
+                                pullRequest: pr,
+                                parentWorkstream,
+                                packet,
+                                parentIntegrationBranch,
+                                parentPullRequestNumber: parentWorkstream.integration?.prNumber
+                            });
+                            seenProjections.add(projectionKey);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return projections;
+}
+/**
+ * Collects packet-scoped PR comment projections.
+ */
+export function collectPacketPullRequestCommentProjections(input) {
+    const projections = [];
+    for (const comment of input.comments) {
+        if (comment.parentType !== "pull_request") {
+            continue;
+        }
+        for (const packetProjection of input.packetPullRequestProjections) {
+            if (comment.repoId === packetProjection.pullRequest.repoId &&
+                comment.parentNumber === packetProjection.pullRequest.number) {
+                projections.push({
+                    comment,
+                    packetProjection
+                });
+            }
+        }
+    }
+    // Sort deterministically
+    return projections.sort((a, b) => {
+        return (a.comment.repoSlug.localeCompare(b.comment.repoSlug) ||
+            a.comment.parentNumber - b.comment.parentNumber ||
+            a.comment.id.localeCompare(b.comment.id) ||
+            a.packetProjection.parentWorkstream.id.localeCompare(b.packetProjection.parentWorkstream.id) ||
+            a.packetProjection.packet.id.localeCompare(b.packetProjection.packet.id));
+    });
+}
+/**
+ * Resolves the parent integration branch for a packet.
+ */
+function getParentIntegrationBranch(parentWorkstream, packetWorktree) {
+    return (packetWorktree?.packet?.parentIntegrationBranch ||
+        parentWorkstream.integration?.branchName);
+}
+/**
+ * Returns packet entries sorted by wave order and then packet ID.
+ */
+function getPacketEntries(workstream) {
+    if (!workstream.packetPlan) {
+        return [];
+    }
+    const packets = workstream.packetPlan.packets;
+    const waves = workstream.packetPlan.waves || [];
+    const entries = [];
+    const wavedIds = new Set();
+    for (const wave of waves) {
+        const wavePackets = [];
+        for (const id of wave) {
+            if (packets[id]) {
+                wavePackets.push([id, packets[id]]);
+                wavedIds.add(id);
+            }
+        }
+        wavePackets.sort((a, b) => a[0].localeCompare(b[0]));
+        entries.push(...wavePackets);
+    }
+    const remainingEntries = Object.entries(packets)
+        .filter(([id]) => !wavedIds.has(id))
+        .sort((a, b) => a[0].localeCompare(b[0]));
+    entries.push(...remainingEntries);
+    return entries;
+}
+/**
+ * Checks if a PR is eligible to be a packet PR for a given parent integration branch.
+ */
+function isEligiblePacketPr(pr, parentIntegrationBranch) {
+    return (pr.baseBranch === parentIntegrationBranch &&
+        pr.baseClassification === "non_default_parent");
+}

package/dist/src/workstreams/parent-branch-sync-action.js

@@ -0,0 +1,312 @@
+import * as path from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+export async function executeParentBranchSyncActions(options) {
+    const now = options.now ?? (() => new Date().toISOString());
+    const tasks = [...options.tasks];
+    const executions = [...options.executions];
+    const attempts = [];
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        if (!task ||
+            task.kind !== "sync_parent_branch" ||
+            task.status !== "pending" ||
+            task.relevant === false) {
+            continue;
+        }
+        const preflight = task.context.preflight;
+        if (!preflight) {
+            const failedAt = now();
+            const execution = await buildActionFailureExecution(task, failedAt, options.logDir, "Missing preflight data in task context.");
+            tasks[i] = {
+                ...task,
+                status: "failed",
+                lastExecutionId: execution.id,
+                updatedAt: failedAt
+            };
+            executions.push(execution);
+            await options.stateStore.writeExecutionState(executions);
+            await options.stateStore.writeTaskState(tasks);
+            continue;
+        }
+        const localPath = task.context.localRepoPath;
+        if (!localPath) {
+            const failedAt = now();
+            const execution = await buildActionFailureExecution(task, failedAt, options.logDir, "Missing local repository path in task context.");
+            tasks[i] = {
+                ...task,
+                status: "failed",
+                lastExecutionId: execution.id,
+                updatedAt: failedAt
+            };
+            executions.push(execution);
+            await options.stateStore.writeExecutionState(executions);
+            await options.stateStore.writeTaskState(tasks);
+            const { parentPrNumber } = preflight;
+            if (parentPrNumber) {
+                try {
+                    const attempt = {
+                        taskId: task.id,
+                        status: "failed",
+                        attempted: false,
+                        parentBranch: preflight.parentIntegrationBranch,
+                        defaultBranch: preflight.defaultBranch,
+                        parentPrNumber,
+                        message: "Missing local repository path in task context."
+                    };
+                    const comment = formatParentBranchSyncComment(attempt);
+                    await options.gitHubGateway.postIssueComment({
+                        owner: task.repoSlug.split("/")[0] ?? "",
+                        name: task.repoSlug.split("/")[1] ?? "",
+                        issueNumber: parentPrNumber,
+                        body: comment
+                    });
+                }
+                catch (err) {
+                    options.logger?.warn(`Failed to post sync feedback to ${task.repoSlug}#${parentPrNumber}: ${err}`);
+                }
+            }
+            continue;
+        }
+        const { parentIntegrationBranch, defaultBranch, parentPrNumber } = preflight;
+        if (parentPrNumber === undefined) {
+            const failedAt = now();
+            const execution = await buildActionFailureExecution(task, failedAt, options.logDir, "Missing parent PR number in preflight data.");
+            tasks[i] = {
+                ...task,
+                status: "failed",
+                lastExecutionId: execution.id,
+                updatedAt: failedAt
+            };
+            executions.push(execution);
+            await options.stateStore.writeExecutionState(executions);
+            await options.stateStore.writeTaskState(tasks);
+            continue;
+        }
+        options.logger?.info(`Executing orchestrator sync for ${task.repoSlug} branch ${parentIntegrationBranch} (PR #${parentPrNumber})`);
+        let beforeComparison;
+        try {
+            beforeComparison = await options.gitGateway.compareBranchSyncStatus(localPath, parentIntegrationBranch, defaultBranch);
+        }
+        catch (err) {
+            options.logger?.warn(`Could not obtain before-comparison for sync action: ${err}`);
+        }
+        const startedAt = now();
+        let syncResult;
+        try {
+            syncResult = await options.parentBranchSyncService.syncParentBranch(localPath, parentIntegrationBranch, defaultBranch);
+        }
+        catch (err) {
+            syncResult = {
+                status: "failed",
+                message: "Parent branch sync service threw an unexpected error.",
+                error: err instanceof Error ? err.message : String(err)
+            };
+        }
+        let afterComparison;
+        try {
+            afterComparison = await options.gitGateway.compareBranchSyncStatus(localPath, parentIntegrationBranch, defaultBranch);
+        }
+        catch (err) {
+            options.logger?.warn(`Could not obtain after-comparison for sync action: ${err}`);
+        }
+        const endedAt = now();
+        const taskStatus = syncResult.status === "synced" || syncResult.status === "already_up_to_date"
+            ? "completed"
+            : "failed";
+        const attempt = {
+            taskId: task.id,
+            status: syncResult.status,
+            attempted: true,
+            parentBranch: parentIntegrationBranch,
+            defaultBranch,
+            message: syncResult.message,
+            ...(parentPrNumber !== undefined ? { parentPrNumber } : {}),
+            ...(beforeComparison !== undefined ? { beforeComparison } : {}),
+            ...(afterComparison !== undefined ? { afterComparison } : {}),
+            ...(syncResult.error !== undefined ? { error: syncResult.error } : {})
+        };
+        attempts.push(attempt);
+        const execution = await buildSyncExecutionRecord({
+            task,
+            attempt,
+            logDir: options.logDir,
+            startedAt,
+            endedAt
+        });
+        tasks[i] = {
+            ...task,
+            status: taskStatus,
+            lastExecutionId: execution.id,
+            updatedAt: endedAt
+        };
+        executions.push(execution);
+        // Persist incrementally
+        await options.stateStore.writeExecutionState(executions);
+        await options.stateStore.writeTaskState(tasks);
+        // Feedback
+        if (parentPrNumber) {
+            try {
+                const comment = formatParentBranchSyncComment(attempt);
+                await options.gitHubGateway.postIssueComment({
+                    owner: task.repoSlug.split("/")[0] ?? "",
+                    name: task.repoSlug.split("/")[1] ?? "",
+                    issueNumber: parentPrNumber,
+                    body: comment
+                });
+            }
+            catch (err) {
+                options.logger?.warn(`Failed to post sync feedback to ${task.repoSlug}#${parentPrNumber}: ${err}`);
+            }
+        }
+    }
+    return { tasks, executions, attempts };
+}
+async function buildActionFailureExecution(task, timestamp, logDir, message) {
+    const executionId = `exec-${task.id.replace(/[^a-zA-Z0-9_-]+/g, "_")}-action-failure-${timestamp.replace(/[:.]/g, "-")}`;
+    const artifactRoot = path.join(logDir, "artifacts", executionId);
+    await mkdir(artifactRoot, { recursive: true });
+    const promptPacketPath = path.join(artifactRoot, "prompt-packet.json");
+    const promptArtifactPath = path.join(artifactRoot, "prompt.md");
+    const stdoutArtifactPath = path.join(artifactRoot, "stdout.txt");
+    const stderrArtifactPath = path.join(artifactRoot, "stderr.txt");
+    await Promise.all([
+        writeFile(promptArtifactPath, `Task: ${task.id}\nPhase: parent branch sync action\n\n${message}\n`, "utf8"),
+        writeFile(stdoutArtifactPath, "", "utf8"),
+        writeFile(stderrArtifactPath, `${message}\n`, "utf8")
+    ]);
+    await writeFile(promptPacketPath, JSON.stringify({
+        taskId: task.id,
+        taskKind: task.kind,
+        status: "failed",
+        error: message
+    }, null, 2), "utf8");
+    return {
+        id: executionId,
+        taskId: task.id,
+        taskKind: task.kind,
+        taskStatus: "failed",
+        repoId: task.repoId,
+        repoSlug: task.repoSlug,
+        agentId: "orchestrator",
+        agentProvider: "unassigned",
+        command: {
+            executable: "orchestrator-action",
+            args: [],
+            cwd: task.context.localRepoPath ?? process.cwd(),
+            timeoutMs: 0
+        },
+        promptArtifactPath,
+        stdoutArtifactPath,
+        stderrArtifactPath,
+        promptPacketPath,
+        startedAt: timestamp,
+        endedAt: timestamp,
+        exitCode: 1,
+        errorMessage: message
+    };
+}
+async function buildSyncExecutionRecord(input) {
+    const { task, attempt, logDir, startedAt, endedAt } = input;
+    const executionId = `exec-${task.id.replace(/[^a-zA-Z0-9_-]+/g, "_")}-sync-action-${startedAt.replace(/[:.]/g, "-")}`;
+    const artifactRoot = path.join(logDir, "artifacts", executionId);
+    await mkdir(artifactRoot, { recursive: true });
+    const promptPacketPath = path.join(artifactRoot, "prompt-packet.json");
+    const promptArtifactPath = path.join(artifactRoot, "prompt.md");
+    const stdoutArtifactPath = path.join(artifactRoot, "stdout.txt");
+    const stderrArtifactPath = path.join(artifactRoot, "stderr.txt");
+    const resultPacket = {
+        taskId: task.id,
+        taskKind: task.kind,
+        parentBranchSync: {
+            status: attempt.status,
+            message: attempt.message,
+            parentBranch: attempt.parentBranch,
+            defaultBranch: attempt.defaultBranch,
+            parentPrNumber: attempt.parentPrNumber,
+            beforeComparison: attempt.beforeComparison,
+            afterComparison: attempt.afterComparison,
+            error: attempt.error
+        }
+    };
+    await Promise.all([
+        writeFile(promptPacketPath, JSON.stringify(resultPacket, null, 2), "utf8"),
+        writeFile(promptArtifactPath, `Task: ${task.id}\nPhase: parent branch sync action\n\n${attempt.message}\n`, "utf8"),
+        writeFile(stdoutArtifactPath, `${attempt.message}\n`, "utf8"),
+        writeFile(stderrArtifactPath, attempt.error ? `${attempt.error}\n` : "", "utf8")
+    ]);
+    return {
+        id: executionId,
+        taskId: task.id,
+        taskKind: task.kind,
+        taskStatus: attempt.status === "synced" || attempt.status === "already_up_to_date"
+            ? "completed"
+            : "failed",
+        repoId: task.repoId,
+        repoSlug: task.repoSlug,
+        agentId: "orchestrator",
+        agentProvider: "unassigned",
+        command: {
+            executable: "git-sync-service",
+            args: ["merge", attempt.defaultBranch, "into", attempt.parentBranch],
+            cwd: task.context.localRepoPath ?? process.cwd(),
+            timeoutMs: 0
+        },
+        promptArtifactPath,
+        stdoutArtifactPath,
+        stderrArtifactPath,
+        promptPacketPath,
+        startedAt,
+        endedAt,
+        exitCode: attempt.status === "synced" || attempt.status === "already_up_to_date" ? 0 : 1,
+        ...(attempt.error !== undefined ? { errorMessage: attempt.error } : {}),
+        result: {
+            parentBranchSync: {
+                status: attempt.status,
+                message: attempt.message,
+                parentBranch: attempt.parentBranch,
+                defaultBranch: attempt.defaultBranch,
+                ...(attempt.parentPrNumber !== undefined ? { parentPrNumber: attempt.parentPrNumber } : {}),
+                ...(attempt.beforeComparison !== undefined ? { beforeComparison: attempt.beforeComparison } : {}),
+                ...(attempt.afterComparison !== undefined ? { afterComparison: attempt.afterComparison } : {}),
+                ...(attempt.error !== undefined ? { error: attempt.error } : {})
+            }
+        }
+    };
+}
+export function formatParentBranchSyncComment(attempt) {
+    const lines = ["🤖 **Parent Branch Sync Attempt**", ""];
+    const actionText = attempt.attempted
+        ? `Attempted to merge the default branch (\`${attempt.defaultBranch}\`) into the parent branch (\`${attempt.parentBranch}\`) through the git sync service, with no rebase or force push.`
+        : "Could not attempt merge (precondition failed)";
+    lines.push(`- **Action**: ${actionText}`);
+    lines.push(`- **Parent Branch**: \`${attempt.parentBranch}\``);
+    lines.push(`- **Default Branch**: \`${attempt.defaultBranch}\``);
+    if (attempt.beforeComparison) {
+        const comp = attempt.beforeComparison;
+        lines.push(`- **Pre-attempt status**: \`${comp.status}\` (ahead: ${comp.parentAheadCount ?? "?"}, behind: ${comp.parentBehindCount ?? "?"})`);
+    }
+    lines.push(`- **Result**: \`${attempt.status}\``);
+    if (attempt.message) {
+        lines.push(`  > ${attempt.message}`);
+    }
+    if (attempt.error) {
+        lines.push(`  > **Error**: ${attempt.error}`);
+    }
+    if (attempt.afterComparison) {
+        const comp = attempt.afterComparison;
+        lines.push(`- **Post-attempt status**: \`${comp.status}\` (ahead: ${comp.parentAheadCount ?? "?"}, behind: ${comp.parentBehindCount ?? "?"})`);
+        lines.push("");
+        if (comp.status === "up_to_date") {
+            lines.push("Wave advancement is now eligible. It will be evaluated in the normal orchestration flow.");
+        }
+        else {
+            lines.push("Wave advancement remains blocked because the branch is not yet `up_to_date`.");
+        }
+    }
+    else {
+        lines.push("- **Post-attempt status**: `unknown` (comparison failed or unavailable)");
+        lines.push("");
+        lines.push("Wave advancement remains blocked because the branch status could not be verified after the attempt.");
+    }
+    return lines.join("\n");
+}

package/dist/src/workstreams/parent-branch-sync.js

@@ -0,0 +1,148 @@
+export class LocalParentBranchSyncService {
+    gitGateway;
+    constructor(gitGateway) {
+        this.gitGateway = gitGateway;
+    }
+    async syncParentBranch(localPath, parentBranch, defaultBranch) {
+        let initialComparison;
+        try {
+            await this.gitGateway.fetchRepository(localPath);
+            if (!(await this.gitGateway.isWorkingTreeClean(localPath))) {
+                return {
+                    status: "blocked",
+                    message: "Working tree is dirty; refusing to sync parent branch."
+                };
+            }
+            initialComparison = await this.gitGateway.compareBranchSyncStatus(localPath, parentBranch, defaultBranch);
+            if (initialComparison.status === "up_to_date") {
+                return {
+                    status: "already_up_to_date",
+                    message: "Parent branch is already up to date with the default branch.",
+                    comparison: initialComparison
+                };
+            }
+            if (initialComparison.status === "missing_parent_branch" ||
+                initialComparison.status === "missing_default_branch" ||
+                initialComparison.status === "unknown") {
+                return {
+                    status: "blocked",
+                    message: initialComparison.message,
+                    comparison: initialComparison
+                };
+            }
+            // If we are here, status is "behind_default" or "diverged"
+            const originalBranch = await this.gitGateway.getCurrentBranch(localPath);
+            // Check if parentBranch is already checked out in another worktree
+            const parentBranchWorktreePath = await this.gitGateway.getWorktreeForBranch(localPath, parentBranch);
+            const syncPath = parentBranchWorktreePath || localPath;
+            if (syncPath !== localPath && !(await this.gitGateway.isWorkingTreeClean(syncPath))) {
+                return {
+                    status: "blocked",
+                    message: `Parent branch is checked out in a dirty worktree at "${syncPath}"; refusing to sync parent branch.`
+                };
+            }
+            let syncResult;
+            try {
+                if (!parentBranchWorktreePath && originalBranch !== parentBranch) {
+                    await this.gitGateway.checkoutBranch(localPath, parentBranch);
+                }
+                // Ensure local parentBranch is up to date with its remote counterpart before merging
+                syncResult = await this.performMerge(syncPath, parentBranch, "pre-merging parent branch from remote", initialComparison);
+                if (!syncResult) {
+                    syncResult = await this.performMerge(syncPath, defaultBranch, "syncing parent branch with default branch", initialComparison);
+                }
+                if (!syncResult) {
+                    await this.gitGateway.pushBranch(syncPath, parentBranch);
+                    // Fetch again to ensure refreshed comparison uses the latest remote state
+                    await this.gitGateway.fetchRepository(localPath);
+                    const refreshedComparison = await this.gitGateway.compareBranchSyncStatus(localPath, parentBranch, defaultBranch);
+                    if (refreshedComparison.status === "up_to_date") {
+                        syncResult = {
+                            status: "synced",
+                            message: "Parent branch successfully synced with the default branch.",
+                            comparison: refreshedComparison
+                        };
+                    }
+                    else {
+                        syncResult = {
+                            status: "failed",
+                            message: `Refreshed comparison shows status "${refreshedComparison.status}" instead of "up_to_date": ${refreshedComparison.message}`,
+                            comparison: refreshedComparison
+                        };
+                    }
+                }
+            }
+            catch (error) {
+                syncResult = {
+                    status: "failed",
+                    message: "An unexpected error occurred while syncing parent branch.",
+                    comparison: initialComparison,
+                    error: error instanceof Error ? error.message : String(error)
+                };
+            }
+            // Cleanup phase: restore original branch and verify cleanliness
+            // Only if we were operating in the original localPath and we actually switched branches
+            if (!parentBranchWorktreePath && originalBranch && originalBranch !== parentBranch) {
+                try {
+                    await this.gitGateway.checkoutBranch(localPath, originalBranch);
+                }
+                catch (checkoutError) {
+                    return {
+                        status: "failed",
+                        message: `Sync status was ${syncResult?.status || "unknown"}; however, failed to return to original branch "${originalBranch}".`,
+                        comparison: syncResult?.comparison || initialComparison,
+                        error: checkoutError instanceof Error ? checkoutError.message : String(checkoutError)
+                    };
+                }
+            }
+            if (!(await this.gitGateway.isWorkingTreeClean(syncPath))) {
+                return {
+                    status: "failed",
+                    message: `Sync status was ${syncResult?.status || "unknown"}; however, the working tree at "${syncPath}" is dirty after cleanup.`,
+                    comparison: syncResult?.comparison || initialComparison
+                };
+            }
+            return syncResult || { status: "failed", message: "Sync process failed to produce a result." };
+        }
+        catch (outerError) {
+            return {
+                status: "failed",
+                message: "An unexpected error occurred in the sync service.",
+                ...(initialComparison ? { comparison: initialComparison } : {}),
+                error: outerError instanceof Error ? outerError.message : String(outerError)
+            };
+        }
+    }
+    async performMerge(localPath, branch, phaseName, initialComparison) {
+        try {
+            await this.gitGateway.mergeRemoteBranch(localPath, "origin", branch);
+            return undefined;
+        }
+        catch (mergeError) {
+            try {
+                await this.gitGateway.abortMerge(localPath);
+            }
+            catch (abortError) {
+                return {
+                    status: "failed",
+                    message: `An error occurred during ${phaseName} and aborting the merge failed.`,
+                    ...(initialComparison ? { comparison: initialComparison } : {}),
+                    error: `Merge error: ${mergeError instanceof Error ? mergeError.message : String(mergeError)}. Abort error: ${abortError instanceof Error ? abortError.message : String(abortError)}`
+                };
+            }
+            // If abort succeeded, it was likely a merge conflict, but we check if the error message suggests something else
+            const errorMessage = mergeError instanceof Error ? mergeError.message : String(mergeError);
+            const lowerMessage = errorMessage.toLowerCase();
+            const isConflict = lowerMessage.includes("conflict") ||
+                lowerMessage.includes("automatic merge failed");
+            return {
+                status: isConflict ? "conflict" : "failed",
+                message: isConflict
+                    ? `Merge conflict occurred while ${phaseName}; merge aborted.`
+                    : `Merge failed while ${phaseName}; merge aborted.`,
+                ...(initialComparison ? { comparison: initialComparison } : {}),
+                error: errorMessage
+            };
+        }
+    }
+}

package/dist/src/workstreams/phases.js

@@ -0,0 +1,4 @@
+import { evaluateWorkstreamMachine } from "../workflows/workstream-machine/evaluate.js";
+export function reduceWorkstreamPhase(input) {
+    return evaluateWorkstreamMachine(input);
+}

package/dist/src/workstreams/plan-breakdown-generator/export.js

@@ -0,0 +1,19 @@
+import { validateSession } from "./validate.js";
+export function exportSession(session) {
+    const issues = [...session.validationIssues, ...validateSession(session)];
+    const errors = issues.filter((i) => i.severity === "error");
+    if (errors.length > 0) {
+        throw new Error(`Cannot export invalid session: ${errors.map((e) => e.message).join("; ")}`);
+    }
+    return {
+        title: session.title,
+        summary: session.summary,
+        tasks: Object.values(session.tasks),
+        waves: session.waveOrder.map((id) => session.waves[id]),
+        recommendedFirstWaveId: session.recommendedFirstWaveId,
+        graphConcerns: session.graphConcerns,
+        humanDecisionsNeeded: session.humanDecisionsNeeded,
+        suggestedNextAction: session.suggestedNextAction,
+        validationIssues: issues.length > 0 ? issues : undefined
+    };
+}

package/dist/src/workstreams/plan-breakdown-generator/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./session.js";
+export * from "./patch.js";
+export * from "./inspect.js";
+export * from "./validate.js";
+export * from "./export.js";