@backburner/cli 0.1.7 → 0.1.9

package/README.md

@@ -4,6 +4,37 @@ Backburner turns GitHub issues into reviewable pull requests using coding agents
 
 Open an issue from your phone, get back to your day, and manage the work through GitHub comments, labels, and PR reviews. Your computer does the planning, coding, testing, committing, and pushing through the agent CLIs and credentials you already use. GitHub is the control plane; your computer is the worker.
 
+## From phone to pull request
+
+Follow work from the GitHub mobile app while Backburner runs the agent workflow on your machine:
+
+<table>
+  <tr>
+    <td align="center" width="50%">
+      <strong>1. Open an issue from your phone</strong>
+      <br />
+      <img src="docs/images/workflow-story/01-issue.jpg" alt="A GitHub issue describing OAuth support for hosted MCP" />
+    </td>
+    <td align="center" width="50%">
+      <strong>2. Review the product direction</strong>
+      <br />
+      <img src="docs/images/workflow-story/02-product-discovery.jpg" alt="An agent posts product discovery analysis on the GitHub issue" />
+    </td>
+  </tr>
+  <tr>
+    <td align="center" width="50%">
+      <strong>3. Approve the implementation plan</strong>
+      <br />
+      <img src="docs/images/workflow-story/03-plan-pr.jpg" alt="Backburner creates a planning pull request with product spec and plan documents" />
+    </td>
+    <td align="center" width="50%">
+      <strong>4. Review the completed work</strong>
+      <br />
+      <img src="docs/images/workflow-story/04-reviewed-change.jpg" alt="The implemented change is reviewed and ready for a human merge" />
+    </td>
+  </tr>
+</table>
+
 ## How it works
 
 1. You open an issue in a repository managed by Backburner.
@@ -250,7 +281,7 @@ The normal orchestrator starts its own broker on loopback. The standalone broker
 
 ## What a run does
 
-Each cycle loads configuration and state, syncs enabled repositories, scans GitHub through `gh`, derives eligible tasks, starts a local GitHub broker for provider access, dispatches work to provider CLIs, and writes state, journal events, and execution logs.
+Each cycle loads configuration and state, fetches and synchronizes enabled repositories, scans GitHub through `gh`, derives eligible tasks, starts a local GitHub broker for provider access, dispatches work to provider CLIs, and writes state, journal events, and execution logs. If a managed checkout has local changes, Backburner does not modify it; after a successful fetch, packet worktrees may still be created from the exact remote integration-branch ref.
 
 Backburner uses isolated git worktrees as implementation units. Generated control-plane state is readable JSON under `<outputs-dir>/state`; execution logs and artifacts are under `<outputs-dir>/logs`; journal events are under `<outputs-dir>/journal`.
 

package/dist/src/cli/commands/run.js

@@ -47,6 +47,26 @@ export function buildPacketWaveAdvancementEvaluationForRun(input) {
         waveAssessments: input.waveAssessments
     });
 }
+/**
+ * Returns local repositories that can safely provide packet worktrees.
+ *
+ * Packet worktrees start at an exact `origin/<integration-branch>` ref, so a
+ * successfully fetched repository remains usable only when its primary
+ * checkout was explicitly blocked for local changes. Other failed sync states
+ * remain excluded because their remote refs may be stale or unavailable.
+ */
+export function buildPacketProvisioningRepoPathMap(repoResults) {
+    return new Map(repoResults
+        .filter(isPacketProvisioningRepo)
+        .map((result) => [result.repoId, result.localPath]));
+}
+function isPacketProvisioningRepo(result) {
+    if (result.status === "synced") {
+        return true;
+    }
+    return (result.fetched &&
+        result.defaultBranchSyncStatus === "blocked_dirty");
+}
 export async function processProviderLimitResumption(input) {
     const providerLimits = [...(input.previousState.providerLimits ?? [])];
     const currentTime = Date.parse(input.now);
@@ -726,6 +746,9 @@ export async function runCli(argv, options = {}) {
             if (retrospectiveDerivation.tasks.length > 0 || finalSkipContextHydration.changed) {
                 await stateStore.writeTaskState(finalTasksToDispatch);
             }
+            // Workspace recovery already ran before the initial dispatch. Deferring
+            // further recovery until the next outer run preserves completed task
+            // handoffs produced earlier in this run.
             dispatchResult = await runDispatchWithMergePrepLifecycle({
                 tasks: finalTasksToDispatch,
                 worktrees: projectionAwareTriageWorktrees,
@@ -759,6 +782,7 @@ export async function runCli(argv, options = {}) {
                 commandRunner,
                 gitGateway,
                 workspaceRecoveryService,
+                skipWorkspaceRecovery: true,
                 agentPool
             });
             // Journal new executions (dedup via executionIdsBeforeCycle)
@@ -871,9 +895,7 @@ export async function runCli(argv, options = {}) {
                     .filter((assessment) => assessment !== undefined)
             });
             // Packet planning artifact creation
-            const repoPathMap = new Map(scanResult.repoResults
-                .filter((result) => result.status === "synced")
-                .map((result) => [result.repoId, result.localPath]));
+            const repoPathMap = buildPacketProvisioningRepoPathMap(scanResult.repoResults);
             let currentWorktrees = finalWorktrees;
             let currentWorkstreams = enrichedWorkstreams;
             // Preserve new packet plans before provisioning external packet artifacts.
@@ -887,13 +909,38 @@ export async function runCli(argv, options = {}) {
                 if (!repo || !repoPath) {
                     continue;
                 }
-                const packetWorktreeResults = await implementationWorkflowService.ensurePacketPlanningWorktreesForCurrentWave({
-                    repo,
-                    repoPath,
-                    codeRoot,
-                    parentWorkstream: workstream,
-                    existingWorktrees: currentWorktrees
-                });
+                const parentIntegrationBranch = workstream.integration?.branchName;
+                if (!parentIntegrationBranch) {
+                    continue;
+                }
+                try {
+                    const comparison = await gitGateway.compareBranchSyncStatus(repoPath, parentIntegrationBranch, repo.defaultBranch ?? "main");
+                    if (comparison.status === "missing_parent_branch" || comparison.status === "unknown") {
+                        logger.warn(`Packet worktree start point origin/${parentIntegrationBranch} is unavailable for ${workstream.id}; will retry next cycle.`);
+                        continue;
+                    }
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    logger.warn(`Could not verify packet worktree start point for ${workstream.id}; will retry next cycle: ${message}`);
+                    continue;
+                }
+                let packetWorktreeResults;
+                try {
+                    packetWorktreeResults =
+                        await implementationWorkflowService.ensurePacketPlanningWorktreesForCurrentWave({
+                            repo,
+                            repoPath,
+                            codeRoot,
+                            parentWorkstream: workstream,
+                            existingWorktrees: currentWorktrees
+                        });
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    logger.warn(`Failed to provision packet worktrees for ${workstream.id}; will retry next cycle: ${message}`);
+                    continue;
+                }
                 if (packetWorktreeResults.length > 0) {
                     for (const result of packetWorktreeResults) {
                         const existingIndex = currentWorktrees.findIndex((wt) => wt.id === result.worktree.id);

package/dist/src/cli/run.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-export { runCli, buildPacketWaveAdvancementEvaluationForRun } from "./commands/run.js";
+export { runCli, buildPacketProvisioningRepoPathMap, buildPacketWaveAdvancementEvaluationForRun } from "./commands/run.js";
 export { buildEffectiveProviderBrokerToolAllowLists } from "./runtime/provider-tools.js";
 export { runDispatchWithMergePrepLifecycle } from "./runtime/dispatch-lifecycle.js";
 export { runLoopCli, SerializedCycleRunner } from "./commands/run-loop.js";

package/dist/src/cli/runtime/dispatch-lifecycle.js

@@ -298,7 +298,10 @@ export async function runDispatchWithMergePrepLifecycle(input) {
         await stateStore.writeTaskState(hydratedInputTasks);
     }
     // ── Phase 0: Recover workspaces of failed workspace-write tasks ─────────────
+    // This phase is intentionally skipped for follow-up dispatches in the same
+    // outer run so a failed sibling cannot erase a completed task's handoff.
     const seenRecoveryPaths = new Set();
+    const recoveryResultByPath = new Map();
     const existingRecoveryRecords = await stateStore.loadWorkspaceRecoveryState();
     const recoveryRecords = [...existingRecoveryRecords];
     let recoveryStateChanged = false;
@@ -311,11 +314,20 @@ export async function runDispatchWithMergePrepLifecycle(input) {
     };
     const recoveryResultByTaskId = new Map();
     for (const task of hydratedInputTasks) {
-        if (!workspaceRecoveryService.isRecoveryNeeded(task)) {
+        if (input.skipWorkspaceRecovery || !workspaceRecoveryService.isRecoveryNeeded(task)) {
             continue;
         }
         const localPath = workspaceRecoveryService.resolveTaskWorkspacePath(task);
         if (localPath && seenRecoveryPaths.has(localPath)) {
+            const sharedRecoveryResult = recoveryResultByPath.get(localPath);
+            if (sharedRecoveryResult) {
+                recoveryResultByTaskId.set(task.id, sharedRecoveryResult);
+                if (sharedRecoveryResult.outcome === "recovered" ||
+                    sharedRecoveryResult.outcome === "skipped") {
+                    task.context.recoveryNeeded = false;
+                    taskStateChangedByRecovery = true;
+                }
+            }
             continue;
         }
         if (localPath) {
@@ -329,6 +341,9 @@ export async function runDispatchWithMergePrepLifecycle(input) {
         counts[recoveryResult.outcome]++;
         recoveryRecords.push(recoveryResult);
         recoveryResultByTaskId.set(task.id, recoveryResult);
+        if (localPath) {
+            recoveryResultByPath.set(localPath, recoveryResult);
+        }
         recoveryStateChanged = true;
         if (recoveryResult.outcome === "recovered" || recoveryResult.outcome === "skipped") {
             task.context.recoveryNeeded = false;

package/dist/src/git/types.js

@@ -74,18 +74,18 @@ export class GitCliGateway {
             defaultRef
         };
         try {
-            if (!(await this.hasRef(localPath, defaultRef))) {
+            if (!(await this.hasRef(localPath, parentRef))) {
                 return {
                     ...baseComparison,
-                    status: "missing_default_branch",
-                    message: "Default branch ref was not found locally."
+                    status: "missing_parent_branch",
+                    message: "Parent branch ref was not found locally."
                 };
             }
-            if (!(await this.hasRef(localPath, parentRef))) {
+            if (!(await this.hasRef(localPath, defaultRef))) {
                 return {
                     ...baseComparison,
-                    status: "missing_parent_branch",
-                    message: "Parent branch ref was not found locally."
+                    status: "missing_default_branch",
+                    message: "Default branch ref was not found locally."
                 };
             }
             const result = await this.commandRunner.run("git", ["rev-list", "--left-right", "--count", `${defaultRef}...${parentRef}`], { cwd: localPath });
@@ -382,6 +382,8 @@ export class LocalRepoSyncService {
         const existedBeforeSync = await pathExists(localPath);
         let currentBranchBefore = null;
         let currentBranchAfter = null;
+        let fetched = false;
+        let defaultBranchSyncStatus = "not_attempted";
         let defaultBranch = repo.defaultBranch ?? null;
         let defaultBranchSource = repo.defaultBranch ? "config" : "unknown";
         try {
@@ -389,6 +391,7 @@ export class LocalRepoSyncService {
                 await this.gitGateway.cloneRepository(repo, localPath);
             }
             await this.gitGateway.fetchRepository(localPath);
+            fetched = true;
             currentBranchBefore = await this.gitGateway.getCurrentBranch(localPath);
             if (!defaultBranch) {
                 try {
@@ -402,10 +405,12 @@ export class LocalRepoSyncService {
             }
             const clean = await this.gitGateway.isWorkingTreeClean(localPath);
             if (!clean) {
+                defaultBranchSyncStatus = "blocked_dirty";
                 throw new Error("working tree is dirty; refusing to switch or fast-forward the default branch");
             }
             await this.gitGateway.ensureDefaultBranchCheckedOut(localPath, defaultBranch);
             await this.gitGateway.fastForwardDefaultBranch(localPath, defaultBranch);
+            defaultBranchSyncStatus = "synced";
             currentBranchAfter = await this.gitGateway.getCurrentBranch(localPath);
             return {
                 repoId: repo.id,
@@ -416,7 +421,8 @@ export class LocalRepoSyncService {
                 status: "synced",
                 existedBeforeSync,
                 cloned: !existedBeforeSync,
-                fetched: true,
+                fetched,
+                defaultBranchSyncStatus,
                 defaultBranch,
                 defaultBranchSource,
                 currentBranchBefore,
@@ -438,7 +444,8 @@ export class LocalRepoSyncService {
                 status: "failed",
                 existedBeforeSync,
                 cloned: !existedBeforeSync && currentBranchAfter !== null,
-                fetched: existedBeforeSync,
+                fetched,
+                defaultBranchSyncStatus: defaultBranchSyncStatus === "blocked_dirty" ? "blocked_dirty" : "failed",
                 defaultBranch,
                 defaultBranchSource,
                 currentBranchBefore,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backburner/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "description": "Local GitHub-based agent orchestration CLI",
   "license": "MIT",