@webappwiz/arbor 0.0.10 → 0.0.12

package/README.md

@@ -32,6 +32,11 @@ rebase, and that is what `rm` is for.
 Creates the task: branch `task/<task>`, a worktree at
 `../<repo>-arbor/<task>`, and a state record.
 
+`--base <branch>` starts the task from that branch and lands it back there
+instead of trunk. It takes another task's branch too: `--base task/<other>`
+stacks this task on that one, and the work lands in that task's worktree
+rather than on trunk.
+
 A fresh worktree shares no untracked files with the repo (no `node_modules`,
 no `.env`) which is what `postCheckout` is for.
 
@@ -53,10 +58,11 @@ holds the lease. A worktree with no record is rebuilt rather than rejected.
 
 ### `arbor merge`
 
-Lands the current worktree's branch on trunk. The core command.
+Lands the current worktree's branch on its base, trunk unless the task was
+created with `--base`. The core command.
 
-**Never a merge commit.** It rebases onto trunk, runs the `preMerge` gate
-there, and fast-forwards trunk with `git merge --ff-only`. History stays
+**Never a merge commit.** It rebases onto the base, runs the `preMerge` gate
+there, and fast-forwards the base with `git merge --ff-only`. History stays
 linear.
 
 1. Refuses if the worktree is dirty, out of retry budget, or leased elsewhere.
@@ -67,7 +73,11 @@ linear.
    passed before rebasing says nothing about whether it works against current
    trunk; this is the only defense against semantic conflicts, where both sides
    merge cleanly and the combination is broken.
-4. Re-checks the lease, then `git checkout <trunk> && git merge --ff-only`.
+4. Re-checks the lease, then fast-forwards the base **in the worktree that has
+   it checked out**: the main tree for trunk, or the other task's worktree for
+   a `--base task/<other>` task. Git allows one worktree per branch, and that
+   tree is the only place the branch can move: advancing the ref behind its
+   back would leave its index and files on the old commit.
 5. Discards the task (worktree, branch and record) exactly as `rm`
    would. The work is on trunk, so the tree has nothing left to hold, and
    `arbor ls` stays a list of live work rather than a graveyard of landed
@@ -236,7 +246,7 @@ The agent's control flow runs on these.
 | 9    | `hook_failed`       | `postCheckout` failed (worktree still exists; fix and re-run the hook), or `postMerge` failed (the branch already landed; nothing rolled back). |
 | 10   | `exists`            | Task already exists. `arbor claim` it, or `arbor rm` first.    |
 | 11   | `orphaned`          | Record with no worktree. `arbor rm` it.                         |
-| 12   | `merge_failed`      | Trunk could not be fast-forwarded (usually a dirty main worktree). |
+| 12   | `merge_failed`      | The base could not be fast-forwarded (usually uncommitted changes in the worktree holding it). |
 | 13   | `already_removed`    | This task was removed earlier; nothing left to remove.              |
 | 14   | `timeout`           | `arbor wait` gave up: the task is still working or merging.        |
 

package/git.d.ts

@@ -44,7 +44,13 @@ export declare class Git {
     rebase(cwd: string, onto: string): Promise<GitResult>;
     resetHard(cwd: string, commit: string): Promise<GitResult>;
     checkout(branch: string): Promise<GitResult>;
-    mergeFfOnly(branch: string): Promise<GitResult>;
+    mergeFfOnly(cwd: string, branch: string): Promise<GitResult>;
+    /**
+     * The worktree with `branch` checked out, or null when no worktree has it.
+     * Git allows one worktree per branch and that is the only place the branch
+     * can be advanced, so this is where a fast-forward has to happen.
+     */
+    worktreeFor(branch: string): Promise<string | null>;
     addWorktree(branch: string, path: string, from: string): Promise<GitResult>;
     removeWorktree(path: string): Promise<GitResult>;
     /** Drops metadata for worktrees whose directories are gone. */

package/index.js

@@ -630,14 +630,25 @@ ${gated.stderr}`)
     await lock.release();
     fail("lease_lost", `the lease on '${task}' was taken by pid ${current.lease?.pid} during the merge, stopping without landing. Do not retry; another agent owns this tree.`, { task, lease: current.lease });
   }
-  const checkout = await git.checkout(base);
-  const merged = checkout.code === 0 ? await git.mergeFfOnly(branch) : checkout;
+  const holder = await git.worktreeFor(base);
+  const landing = holder ?? git.root;
+  const checkout = holder ? null : await git.checkout(base);
+  const merged = checkout && checkout.code !== 0 ? checkout : await git.mergeFfOnly(landing, branch);
   if (merged.code !== 0) {
     await lock.release();
     await bump(worktree);
-    fail("merge_failed", `could not fast-forward ${base} in ${git.root}: ${merged.stderr || merged.stdout}`, { task });
+    fail("merge_failed", [
+      `could not fast-forward ${base} in ${landing}: ${merged.stderr || merged.stdout}`,
+      ...landing === git.root ? [] : [
+        "",
+        `${base} is checked out there, which is the only place it can move.`,
+        "Whoever is working in that tree has to commit or stash what collides,",
+        "then merge again."
+      ]
+    ].join(`
+`), { task, base, landing });
   }
-  const head = await git.shortHead(git.root);
+  const head = await git.shortHead(landing);
   service.ps.cd(git.root);
   const discarded = await current.discard();
   await lock.release();
@@ -647,7 +658,7 @@ Run \`arbor rm ${task}\` to clean up.`, { task });
   }
   if (config.postMerge) {
     const ran = await shell.run(config.postMerge, {
-      cwd: git.root,
+      cwd: landing,
       env: { ARBOR_TASK: task }
     });
     if (ran.exitCode !== 0) {
@@ -660,7 +671,8 @@ ${ran.stderr}`)
 `), { task, exitCode: ran.exitCode });
     }
   }
-  log2.info(`${color8.green("merged")} ${task} onto ${base} (${head})
+  log2.info(`${color8.green("merged")} ${task} onto ${base} (${head})${landing === git.root ? "" : `
+  landed in: ${landing}`}
   worktree removed, cd ${git.root}`);
 }
 async function bump(worktree) {
@@ -774,8 +786,21 @@ class Git {
   checkout(branch) {
     return this.run(this.root, "checkout", branch);
   }
-  mergeFfOnly(branch) {
-    return this.run(this.root, "merge", "--ff-only", branch);
+  mergeFfOnly(cwd, branch) {
+    return this.run(cwd, "merge", "--ff-only", branch);
+  }
+  async worktreeFor(branch) {
+    const listing2 = await this.out(this.root, "worktree", "list", "--porcelain");
+    let path2 = null;
+    for (const line of listing2.split(`
+`)) {
+      if (line.startsWith("worktree ")) {
+        path2 = line.slice("worktree ".length);
+      } else if (line === `branch refs/heads/${branch}`) {
+        return path2;
+      }
+    }
+    return null;
   }
   addWorktree(branch, path2, from) {
     return this.run(this.root, "worktree", "add", "-b", branch, path2, from);
@@ -1319,10 +1344,10 @@ var here = async ({
 var arbor = cli("arbor").use(exits()).use(repository());
 arbor.command("add").description("start a new task: create branch task/<task>, a worktree at ../<repo>-arbor/<task> and a state record").arg("task", t.string(), { description: "task name (lowercase-with-dashes)" }).option("base", t.string(), {
   default: "",
-  description: "branch this task starts from and merges onto (default: trunk)"
+  description: "branch this task starts from and merges onto (default: trunk); `task/<other>` stacks this task on that one and lands the work in its worktree"
 }).action((opts, ctx) => ctx.journal.record("add", opts.task, () => add(ctx, opts.task, { base: opts.base || undefined })));
 arbor.command("claim").description("resume an existing task: take ownership of its worktree and print its path, status and any half-finished rebase; refuses while another agent holds the lease, but takes a stale one silently, so `arbor show` first if the tree may not be abandoned").arg("task", t.string(), { description: "task name" }).action((opts, ctx) => ctx.journal.record("claim", opts.task, () => claim(ctx, opts.task)));
-arbor.command("merge").description("land this worktree's branch on its base (trunk unless created with --base): rebase onto it, run tests on the rebased code, fast-forward it, then discard the worktree, branch and record (linear history, never a merge commit, no flag to skip tests); requires committed work, refusing a dirty worktree").action(async (_opts, ctx) => ctx.journal.record("merge", await here(ctx), () => merge(ctx, ctx.ps.cwd())));
+arbor.command("merge").description("land this worktree's branch on its base (trunk unless created with --base): rebase onto it, run tests on the rebased code, fast-forward it in whichever worktree has it checked out, then discard the worktree, branch and record (linear history, never a merge commit, no flag to skip tests); requires committed work, refusing a dirty worktree").action(async (_opts, ctx) => ctx.journal.record("merge", await here(ctx), () => merge(ctx, ctx.ps.cwd())));
 arbor.command("rm").description("discard a task: worktree, branch and state file; cheap and encouraged, since redoing a task against current trunk often beats a hard rebase").arg("task", t.string(), { description: "task name" }).option("force", t.boolean(), {
   default: false,
   description: "discard even when another agent holds the lease"

package/merge.d.ts

@@ -8,7 +8,8 @@ import type { WorktreeService } from "./worktree-service.js";
  * Lands the current worktree's branch on its base branch, trunk unless the
  * task was created with `--base`. Never a merge commit: it rebases onto the
  * base, runs the gate there, and fast-forwards the base with
- * `git merge --ff-only`. History stays linear.
+ * `git merge --ff-only`, in whichever worktree has the base checked out.
+ * History stays linear.
  */
 export declare function merge({ service, git, lock, shell, config, log, }: {
     service: WorktreeService;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webappwiz/arbor",
-	"version": "0.0.10",
+	"version": "0.0.12",
 	"description": "Runs several AI coding agents on one repository at once, each in its own git worktree",
 	"license": "MIT",
 	"author": "Jared Johnson",
@@ -17,7 +17,7 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"webappwiz": "^0.0.10"
+		"webappwiz": "^0.0.12"
 	},
 	"main": "./index.js",
 	"types": "./index.d.ts",