@backburner/cli 0.1.0

package/dist/src/worktrees/workspace-ownership.js

@@ -0,0 +1,34 @@
+import * as path from "node:path";
+/**
+ * Validates that a candidate workspace path is owned by the orchestrator.
+ *
+ * Orchestrator-owned task workspaces are strictly located under:
+ * - <codeRoot>/_worktrees/
+ * - <codeRoot>/_merge-prep/
+ *
+ * This function performs a pure string-normalization check without I/O.
+ * It rejects the root directories themselves to ensure recovery targets
+ * individual task workspaces.
+ *
+ * @param workspacePath The candidate workspace path to validate.
+ * @param codeRoot The orchestrator's code root directory.
+ */
+export function validateWorkspaceOwnership(workspacePath, codeRoot) {
+    const resolvedCodeRoot = path.resolve(codeRoot);
+    const resolvedWorkspacePath = path.resolve(workspacePath);
+    const allowedRootSubdirs = ["_worktrees", "_merge-prep"];
+    for (const subdir of allowedRootSubdirs) {
+        const allowedRoot = path.join(resolvedCodeRoot, subdir);
+        const relative = path.relative(allowedRoot, resolvedWorkspacePath);
+        const isInside = relative !== "" &&
+            !relative.startsWith("..") &&
+            !path.isAbsolute(relative);
+        if (isInside) {
+            return { valid: true };
+        }
+    }
+    return {
+        valid: false,
+        reason: `Path "${resolvedWorkspacePath}" is not within an orchestrator-owned workspace root (_worktrees or _merge-prep) under "${resolvedCodeRoot}".`,
+    };
+}

package/dist/src/worktrees/workspace-recovery.js

@@ -0,0 +1,177 @@
+import { validateWorkspaceOwnership } from "./workspace-ownership.js";
+/**
+ * Service responsible for recovering agent workspaces after a failure.
+ *
+ * It ensures that a task-owned workspace is returned to a clean state
+ * (synced with its remote branch and free of untracked files) so that
+ * subsequent orchestrator turns can safely reuse or refresh it.
+ */
+export class WorkspaceRecoveryService {
+    now;
+    constructor(now = () => new Date().toISOString()) {
+        this.now = now;
+    }
+    /**
+     * Resolves the absolute path to the workspace owned by a task, if any.
+     *
+     * @param task The task record to inspect.
+     * @returns The absolute workspace path, or null if the task does not use a persistent local workspace.
+     */
+    resolveTaskWorkspacePath(task) {
+        switch (task.kind) {
+            case "implement_plan":
+            case "write_plan":
+            case "respond_pr_comment":
+                return task.context.localRepoPath ?? null;
+            case "prepare_pr_for_merge":
+                return task.context.prepareForMerge?.persistentWorktreePath ?? null;
+            default:
+                // Other task kinds (triage, review, breakdown, sync preflight) are either
+                // read-only or do not own a dedicated persistent worktree.
+                return null;
+        }
+    }
+    /**
+     * Resolves the branch name associated with a task for recovery purposes.
+     *
+     * @param task The task record to inspect.
+     * @returns The branch name, or null if none can be resolved.
+     */
+    resolveTaskBranch(task) {
+        if (task.kind === "prepare_pr_for_merge") {
+            return task.context.prepareForMerge?.headBranch ?? null;
+        }
+        return task.context.branchName ?? null;
+    }
+    /**
+     * Returns true if the task association requires workspace recovery.
+     *
+     * Triggers:
+     * 1. Task status is "failed" (traditional technical failure) AND it has a path.
+     * 2. Task context has "recoveryNeeded: true" (explicitly set during retry derivation).
+     *
+     * @param task The task record to inspect.
+     */
+    isRecoveryNeeded(task) {
+        const explicitRecovery = task.context.recoveryNeeded === true;
+        if (explicitRecovery) {
+            return true;
+        }
+        // Explicitly recovered in the current cycle or a previous turn.
+        if (task.context.recoveryNeeded === false) {
+            return false;
+        }
+        const hasPath = this.resolveTaskWorkspacePath(task) !== null;
+        const isFailed = task.status === "failed";
+        return isFailed && hasPath;
+    }
+    /**
+     * Performs the recovery of a task's workspace.
+     *
+     * 1. Validates that the workspace path is owned by the orchestrator.
+     * 2. Verifies it is a valid git working tree.
+     * 3. Aborts any in-progress merge.
+     * 4. Ensures the correct branch is checked out.
+     * 5. Performs a hard reset to origin/<branch> (branch may be derived from
+     *    the workspace's current branch if the task context has none; fails
+     *    explicitly if no branch can be determined).
+     * 6. Cleans untracked files and directories.
+     *
+     * @param opts Recovery options.
+     * @returns A record summarizing the recovery outcome.
+     */
+    async recoverWorkspace(opts) {
+        const { task, codeRoot, gitGateway } = opts;
+        const workspacePath = this.resolveTaskWorkspacePath(task);
+        if (!workspacePath) {
+            return {
+                taskId: task.id,
+                taskKind: task.kind,
+                outcome: "skipped",
+                reason: "Task has no associated workspace path.",
+                recoveredAt: this.now(),
+            };
+        }
+        const ownership = validateWorkspaceOwnership(workspacePath, codeRoot);
+        if (!ownership.valid) {
+            return {
+                taskId: task.id,
+                taskKind: task.kind,
+                workspacePath,
+                outcome: "rejected",
+                reason: ownership.reason,
+                recoveredAt: this.now(),
+            };
+        }
+        try {
+            const isGit = await gitGateway.isInsideWorkingTree(workspacePath);
+            if (!isGit) {
+                return {
+                    taskId: task.id,
+                    taskKind: task.kind,
+                    workspacePath,
+                    outcome: "failed",
+                    reason: `Path "${workspacePath}" is not a git working tree.`,
+                    recoveredAt: this.now(),
+                };
+            }
+            await gitGateway.fetchRepository(workspacePath);
+            // Abort any in-progress merge state before resetting.
+            const mergeState = await gitGateway.getActiveMergeState(workspacePath);
+            if (mergeState === "merging") {
+                await gitGateway.abortMerge(workspacePath);
+            }
+            else if (mergeState === "rebasing") {
+                await gitGateway.abortRebase(workspacePath);
+            }
+            else if (mergeState === "cherry-picking") {
+                await gitGateway.abortCherryPick(workspacePath);
+            }
+            else if (mergeState === "reverting") {
+                await gitGateway.abortRevert(workspacePath);
+            }
+            const currentBranch = await gitGateway.getCurrentBranch(workspacePath);
+            let branch = this.resolveTaskBranch(task);
+            if (!branch) {
+                // No branch in task context (e.g. write_plan/implement_plan tasks
+                // derived from a repoSyncRecord without an active worktree). Fall back
+                // to whatever branch the workspace is currently on so we can reset to
+                // its remote ref instead of leaving local-only commits ahead of origin.
+                branch = currentBranch;
+            }
+            if (!branch) {
+                return {
+                    taskId: task.id,
+                    taskKind: task.kind,
+                    workspacePath,
+                    outcome: "failed",
+                    reason: "Cannot recover: task has no associated branch name and the workspace is not currently on a branch (detached HEAD).",
+                    recoveredAt: this.now(),
+                };
+            }
+            if (currentBranch !== branch) {
+                await gitGateway.checkoutBranch(workspacePath, branch);
+            }
+            await gitGateway.resetHard(workspacePath, `origin/${branch}`);
+            await gitGateway.cleanUntrackedFiles(workspacePath);
+            return {
+                taskId: task.id,
+                taskKind: task.kind,
+                workspacePath,
+                outcome: "recovered",
+                reason: `Workspace at "${workspacePath}" reset and cleaned.`,
+                recoveredAt: this.now(),
+            };
+        }
+        catch (err) {
+            return {
+                taskId: task.id,
+                taskKind: task.kind,
+                workspacePath,
+                outcome: "failed",
+                reason: err instanceof Error ? err.message : String(err),
+                recoveredAt: this.now(),
+            };
+        }
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@backburner/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Local GitHub-based agent orchestration CLI",
+  "license": "MIT",
+  "author": "Elad Aviv",
+  "keywords": [
+    "cli",
+    "github",
+    "agents",
+    "orchestration",
+    "automation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eladav/backburner.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eladav/backburner/issues"
+  },
+  "homepage": "https://github.com/eladav/backburner#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "bin": {
+    "backburner": "dist/src/cli/run.js"
+  },
+  "scripts": {
+    "clean": "node scripts/clean-dist.mjs",
+    "build": "npm run clean && tsc -p tsconfig.json && node scripts/ensure-npm-bin.mjs",
+    "build:backburner": "npm run build",
+    "build:github-broker": "npm run build",
+    "prepack": "npm run build",
+    "link:local": "npm run build && npm link",
+    "install:local": "node scripts/install-local-package.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --import ./dist/test/setup.js --test --test-concurrency=1 dist/test/*.test.js",
+    "run:backburner": "node dist/src/cli/run.js run",
+    "run:github-broker": "node dist/src/cli/run.js broker",
+    "smoke:github-broker": "node dist/src/cli/run.js broker-smoke",
+    "init": "node dist/src/cli/run.js init"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@smithery/api": "^0.67.0",
+    "cross-spawn": "^7.0.6",
+    "xstate": "^5.31.0",
+    "zod": "^4.4.3"
+  }
+}