@webappwiz/arbor 0.0.11 → 0.0.13

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,10 +73,14 @@ 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
+   `arbor list` stays a list of live work rather than a graveyard of landed
    tasks. The agent's own directory goes with it, so the success message
    prints the main tree to `cd` back to.
 
@@ -95,7 +105,7 @@ Removal leaves a tombstone in `.git/arbor/removed/` so a second `rm` can say
 and drops the oldest as new ones arrive, so a long-forgotten task reports
 `not_found` again.
 
-### `arbor ls [--json]`
+### `arbor list [--json]`
 
 Every task: name, status, lease (`held`/`stale`/`none`), commits ahead of
 trunk, age. A corrupt record shows as `unknown` instead of taking
@@ -103,7 +113,7 @@ down the listing; a record whose worktree vanished shows as `orphaned`.
 
 ### `arbor show <task> [--json]`
 
-One task in full: the row `ls` would print for it, plus the `ARBOR.md`
+One task in full: the row `list` would print for it, plus the `ARBOR.md`
 its agent keeps at the worktree root and the reason behind an `escalated`
 status.
 
@@ -120,7 +130,7 @@ ARBOR.md
 ...
 ```
 
-`ls` says a task exists; this says what it is doing. Like `path`, it takes no
+`list` says a task exists; this says what it is doing. Like `path`, it takes no
 lease, so reading another agent's tree cannot knock it off its own work the way
 `claim` would. A task with no `ARBOR.md` is called out rather than passed over
 in silence: it is the one thing that makes the work resumable.
@@ -161,14 +171,14 @@ WHEN  ACTION    TASK   RESULT
 1h    merge     alpha  ok
 ```
 
-`ls` is what still exists; this is what happened. Entries outlive their tasks:
+`list` is what still exists; this is what happened. Entries outlive their tasks:
 a successful `merge` and a `rm` both take the record with them, so this is
 the only thing that remembers a task landed at all. The last 200 are kept
 (`logCapacity`) in `.git/arbor/log.jsonl`.
 
 ### `arbor dev [--port 4269]`
 
-`ls`, `show` and `log` in a browser, on `http://localhost:4269`, reloading
+`list`, `show` and `log` in a browser, on `http://localhost:4269`, reloading
 themselves as tasks change. Read-only, and takes no lease.
 
 ### `arbor path [task]`
@@ -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/arbor.d.ts

@@ -6,9 +6,9 @@ import { type Repository } from "./repository.js";
 /** Everything `arbor` is run with, before the repository middleware adds to it. */
 export interface ArborDeps extends Deps {
     fs: Fs;
-    /** Only `dev` listens, but the runtime is picked once, where arbor starts. */
+    /** HTTP server `dev` listens on to serve its preview. */
     http: HttpServer;
-    /** Likewise: only `dev` serves the page, and it is built before it ships. */
+    /** The built page `dev` serves as its preview. */
     assets: Assets;
 }
 export declare const arbor: import("webappwiz/cmd").Cli<ArborDeps, ArborDeps & Repository>;

package/dev/assets.d.ts

@@ -7,11 +7,5 @@ export interface Assets {
     /** The stylesheet, with Tailwind already compiled. */
     styles: string;
 }
-/**
- * The page this package ships, built by `build.ts` and imported here as text so
- * it travels inside the bundle a release publishes. Serving it costs a string
- * lookup, and nothing is read off disk: a published package has no `dev/`
- * directory to read from, and the CLI's own dependencies stay clear of React
- * and Tailwind because neither is needed once the page is built.
- */
+/** The page this package ships. Serve each field's contents as-is. */
 export declare const assets: Assets;

package/dev.d.ts

@@ -1,3 +1,4 @@
+import { type AsyncResource } from "webappwiz/disposable";
 import type { HttpServer } from "webappwiz/http";
 import type { Logger } from "webappwiz/log";
 import { type Fs, type PortProvider } from "webappwiz/system";
@@ -8,30 +9,19 @@ import type { WorktreeService } from "./worktree-service.js";
 export declare const DEFAULT_PORT = 4269;
 /** How far above the port asked for `dev` will look before giving up. */
 export declare const PORT_SPAN = 20;
-/**
- * Where `dev` will listen, given the port asked for. A flag is outside input,
- * so a port that cannot exist is a refusal with an exit code rather than the
- * assertion `OpenPortProvider` would raise for a bug in here.
- */
-export declare function devPorts(from: number): PortProvider;
 /** What `dev` lets a caller choose. */
 export interface DevOptions {
     /** Where to listen; the port `--port` asked for, and the span above it. */
     ports?: PortProvider;
 }
 /** A running server, and the one thing a caller ever wants to do with it. */
-export interface DevServer {
+export interface DevServer extends AsyncResource {
     port: number;
-    stop(): Promise<void>;
 }
 /**
- * Serves what `ls`, `show` and `log` print, as one page that refetches when the
+ * Serves what `list`, `show` and `log` print, as one page that refetches when the
  * repo changes. Read-only on purpose: driving arbor is what the CLI is for, and
  * a button that took a lease would fight the agent holding it.
- *
- * The page itself is a React app under `dev/`, built before publishing and
- * carried in the bundle, so nothing here builds markup and nothing reads it
- * off disk.
  */
 export declare function dev({ service, fs, journal, log, http, assets, }: {
     service: WorktreeService;
@@ -41,3 +31,9 @@ export declare function dev({ service, fs, journal, log, http, assets, }: {
     http: HttpServer;
     assets: Assets;
 }, { ports }?: DevOptions): Promise<DevServer>;
+/**
+ * Where `dev` will listen, given the port asked for. A flag is outside input,
+ * so a port that cannot exist is a refusal with an exit code rather than the
+ * assertion `OpenPortProvider` would raise for a bug in here.
+ */
+export declare function devPorts(from: number): PortProvider;

package/escalate.d.ts

@@ -2,6 +2,10 @@ import { type Logger } from "webappwiz/log";
 import type { Lock } from "webappwiz/system";
 import type { Git } from "./git.js";
 import type { WorktreeService } from "./worktree-service.js";
+export interface EscalateOptions {
+    /** Task to escalate. Defaults to the one `cwd` is a worktree for. */
+    task?: string;
+}
 /**
  * The way out that is not "resolve the conflict badly to finish the task".
  * When both sides restructured the same logic there is no correct merge, only
@@ -12,4 +16,4 @@ export declare function escalate({ service, git, lock, log, }: {
     git: Git;
     lock: Lock;
     log: Logger;
-}, reason: string, cwd: string, task?: string): Promise<void>;
+}, reason: string, cwd: string, { task }?: EscalateOptions): Promise<void>;

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

@@ -62,7 +62,6 @@ function exits() {
 // add.ts
 var NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var PLAN_FILE = "ARBOR.md";
-var PLAN = (task) => new MarkdownWriter().heading(1, task).heading(2, "Goal").heading(2, "Files").heading(2, "Next").checklist("fill in Goal and list the steps here as `- [ ]` items").toString();
 async function add({
   service,
   shell,
@@ -100,8 +99,7 @@ ${PLAN_FILE}
   }
   await fs.write(`${worktree.path}/${PLAN_FILE}`, PLAN(task));
   if (config.postCheckout) {
-    const { exitCode } = await shell.stream(config.postCheckout, {
-      cwd: worktree.path,
+    const { exitCode } = await shell.stream(config.postCheckout, worktree.path, {
       env: {
         ARBOR_TASK: task,
         ARBOR_WORKTREE: worktree.path,
@@ -117,6 +115,9 @@ ${PLAN_FILE}
   branch:   ${worktree.branch}
   base:     ${base}`);
 }
+function PLAN(task) {
+  return new MarkdownWriter().heading(1, task).heading(2, "Goal").heading(2, "Files").heading(2, "Next").checklist("fill in Goal and list the steps here as `- [ ]` items").toString();
+}
 
 // claim.ts
 import { color as color2 } from "webappwiz/log";
@@ -161,6 +162,7 @@ ${changes.map((change) => `    ${change}`).join(`
 }
 
 // dev.ts
+import { AsyncDisposer } from "webappwiz/disposable";
 import {
   MAX_PORT,
   OpenPortProvider
@@ -271,41 +273,47 @@ function checkPlan(text, { task, escalated = false }) {
 
 // show.ts
 var FILE = "ARBOR.md";
-async function show({ service, fs, log: log2 }, task, { json = false } = {}) {
+async function show({ service, fs, log: log2 }, task, opts = {}) {
   const worktree = await service.find(task);
   if (worktree.gone) {
-    fail("not_found", `no task '${task}': run \`arbor ls\` to see what there is`, { task });
+    fail("not_found", `no task '${task}': run \`arbor list\` to see what there is`, { task });
   }
-  const details = await taskDetails(worktree, { fs });
-  if (json) {
+  const details = await new TaskDetails({ fs }).get(worktree);
+  if (opts.json ?? false) {
     log2.info(JSON.stringify(details, null, "\t"));
     return;
   }
   log2.info(report(details));
 }
-async function taskDetails(worktree, opts = {}) {
-  const files = opts.fs ?? new NodeFs;
-  const { state } = worktree;
-  const stat = worktree.hasBranch ? await worktree.diffStat() : null;
-  const plan = worktree.exists ? await files.read(`${worktree.path}/${FILE}`).catch(() => null) : null;
-  return {
-    task: worktree.task,
-    status: worktree.status,
-    branch: worktree.branch,
-    base: worktree.base,
-    worktree: worktree.path,
-    lease: worktree.leaseStatus,
-    ahead: worktree.hasBranch ? await worktree.commitsAhead() : null,
-    added: stat?.added ?? null,
-    removed: stat?.removed ?? null,
-    age: state ? age(state.createdAt) : null,
-    escalation: state?.escalations?.at(-1)?.reason ?? null,
-    plan,
-    planProblems: plan === null ? [] : checkPlan(plan, {
+
+class TaskDetails {
+  fs;
+  constructor(opts = {}) {
+    this.fs = opts.fs ?? new NodeFs;
+  }
+  async get(worktree) {
+    const { state } = worktree;
+    const stat = worktree.hasBranch ? await worktree.diffStat() : null;
+    const plan = worktree.exists ? await this.fs.read(`${worktree.path}/${FILE}`).catch(() => null) : null;
+    return {
       task: worktree.task,
-      escalated: worktree.status === "escalated"
-    })
-  };
+      status: worktree.status,
+      branch: worktree.branch,
+      base: worktree.base,
+      worktree: worktree.path,
+      lease: worktree.leaseStatus,
+      ahead: worktree.hasBranch ? await worktree.commitsAhead() : null,
+      added: stat?.added ?? null,
+      removed: stat?.removed ?? null,
+      age: state ? age(state.createdAt) : null,
+      escalation: state?.escalations?.at(-1)?.reason ?? null,
+      plan,
+      planProblems: plan === null ? [] : checkPlan(plan, {
+        task: worktree.task,
+        escalated: worktree.status === "escalated"
+      })
+    };
+  }
 }
 function report(details) {
   const lines = [
@@ -340,10 +348,10 @@ function diff(details) {
 
 // snapshot.ts
 async function snapshot(service, journal, opts = {}) {
-  const fs = opts.fs ?? new NodeFs2;
+  const details = new TaskDetails({ fs: opts.fs ?? new NodeFs2 });
   const tasks = [];
   for (const worktree of await service.list()) {
-    tasks.push(await taskDetails(worktree, { fs }));
+    tasks.push(await details.get(worktree));
   }
   return { tasks, entries: await journal.tail(DEFAULT_COUNT) };
 }
@@ -368,14 +376,6 @@ function fingerprint({ tasks, entries }) {
 // dev.ts
 var DEFAULT_PORT = 4269;
 var PORT_SPAN = 20;
-function devPorts(from) {
-  if (!Number.isInteger(from) || from < 0 || from > MAX_PORT) {
-    fail("usage", `invalid port '${from}': use a whole number 0 to ${MAX_PORT}`, {
-      port: from
-    });
-  }
-  return OpenPortProvider.span({ from, span: PORT_SPAN });
-}
 var POLL_MS = 2000;
 async function dev({
   service,
@@ -448,14 +448,22 @@ async function dev({
     }
   }, { port: await ports.get(), idleTimeout: Duration.zero() });
   log2.info(`arbor dev on http://localhost:${listening.port}`);
+  const disposer = new AsyncDisposer;
+  disposer.defer(() => listening.stop());
+  disposer.defer(async () => clearInterval(poll));
   return {
     port: listening.port,
-    stop: async () => {
-      clearInterval(poll);
-      await listening.stop();
-    }
+    disposeAsync: disposer.disposeAsync
   };
 }
+function devPorts(from) {
+  if (!Number.isInteger(from) || from < 0 || from > MAX_PORT) {
+    fail("usage", `invalid port '${from}': use a whole number 0 to ${MAX_PORT}`, {
+      port: from
+    });
+  }
+  return OpenPortProvider.span({ from, span: PORT_SPAN });
+}
 
 // escalate.ts
 import { color as color6 } from "webappwiz/log";
@@ -464,7 +472,7 @@ async function escalate({
   git,
   lock,
   log: log2
-}, reason, cwd, task) {
+}, reason, cwd, { task } = {}) {
   const branch = await git.currentBranch(cwd).catch(() => "");
   const name = task || service.taskFor(branch);
   if (!name) {
@@ -496,9 +504,9 @@ async function escalate({
 `));
 }
 
-// ls.ts
+// list.ts
 import { color as color7 } from "webappwiz/log";
-async function ls({ service, log: log2 }, { json = false } = {}) {
+async function list({ service, log: log2 }, { json = false } = {}) {
   const rows = [];
   for (const worktree of await service.list()) {
     rows.push(await row2(worktree));
@@ -605,8 +613,7 @@ async function merge({
 `), { task, paths });
   }
   const gate = [config.postRewrite, config.preMerge].filter(Boolean).join(" && ");
-  const gated = gate ? await shell.run(gate, {
-    cwd: worktree.path,
+  const gated = gate ? await shell.run(gate, worktree.path, {
     env: {
       ARBOR_TASK: task,
       ARBOR_WORKTREE: worktree.path
@@ -630,14 +637,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();
@@ -646,8 +664,7 @@ ${gated.stderr}`)
 Run \`arbor rm ${task}\` to clean up.`, { task });
   }
   if (config.postMerge) {
-    const ran = await shell.run(config.postMerge, {
-      cwd: git.root,
+    const ran = await shell.run(config.postMerge, landing, {
       env: { ARBOR_TASK: task }
     });
     if (ran.exitCode !== 0) {
@@ -660,7 +677,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) {
@@ -683,7 +701,7 @@ async function path({ service, log: log2 }, task) {
   }
   const worktree = await service.find(task);
   if (worktree.gone) {
-    fail("not_found", `no task '${task}': run \`arbor ls\` to see what there is`, { task });
+    fail("not_found", `no task '${task}': run \`arbor list\` to see what there is`, { task });
   }
   if (!worktree.exists) {
     fail("orphaned", `'${task}' has no worktree at ${worktree.path}`, {
@@ -774,8 +792,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);
@@ -907,11 +938,11 @@ class Shell {
   constructor(opts = {}) {
     this.ps = opts.ps ?? new NodePs2;
   }
-  run(command, opts) {
-    return this.ps.spawnCapture(["sh", "-c", command], opts);
+  run(command, cwd, opts = {}) {
+    return this.ps.spawnCapture(["sh", "-c", command], { ...opts, cwd });
   }
-  stream(command, opts) {
-    return this.ps.spawn(["sh", "-c", command], opts);
+  stream(command, cwd, opts = {}) {
+    return this.ps.spawn(["sh", "-c", command], { ...opts, cwd });
   }
 }
 
@@ -1284,7 +1315,7 @@ async function wait({ service, log: log2 }, task, { timeout = DEFAULT_TIMEOUT, p
   for (;; ) {
     const worktree = await service.find(task);
     if (worktree.status === "absent") {
-      fail("not_found", `no task '${task}': run \`arbor ls\` to see what there is`, { task });
+      fail("not_found", `no task '${task}': run \`arbor list\` to see what there is`, { task });
     }
     if (!RUNNING.includes(worktree.status)) {
       log2.info(report2(worktree));
@@ -1311,24 +1342,19 @@ function report2(worktree) {
 }
 
 // arbor.ts
-var here = async ({
-  service,
-  git,
-  ps
-}) => service.taskFor(await git.currentBranch(ps.cwd()).catch(() => ""));
 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"
 }).action((opts, ctx) => ctx.journal.record("rm", opts.task, () => rm(ctx, opts.task, { force: opts.force })));
-arbor.command("ls").description("list every task: name, status, lease (held: an agent is on it now; stale: gone quiet, normal for a task mid-edit; none), commits ahead of trunk, age").option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => ls(ctx, { json: opts.json }));
-arbor.command("show").description("read one task without touching it: everything `ls` lists for it, plus the ARBOR.md its agent left at the worktree root; takes no lease, so it cannot knock that agent off its own tree").arg("task", t.string(), { description: "task name" }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => show(ctx, opts.task, { json: opts.json }));
+arbor.command("list").description("list every task: name, status, lease (held: an agent is on it now; stale: gone quiet, normal for a task mid-edit; none), commits ahead of trunk, age").option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => list(ctx, { json: opts.json }));
+arbor.command("show").description("read one task without touching it: everything `list` shows for it, plus the ARBOR.md its agent left at the worktree root; takes no lease, so it cannot knock that agent off its own tree").arg("task", t.string(), { description: "task name" }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => show(ctx, opts.task, { json: opts.json }));
 arbor.command("wait").description("block until a task stops moving: escalated, or gone (merged or removed), or broken; takes no lease, and gives up with `timeout` rather than waiting forever").arg("task", t.string(), { description: "task name" }).option("timeout-secs", t.number(), {
   default: DEFAULT_TIMEOUT.secs,
   description: "how long to wait before giving up"
@@ -1339,7 +1365,7 @@ arbor.command("log").description("show what has been done here recently: one lin
   default: DEFAULT_COUNT,
   description: "how many entries to show"
 }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => log(ctx, { count: opts.count, json: opts.json }));
-arbor.command("dev").description("serve `ls`, `show` and `log` as a web page; read-only").option("port", t.number(), {
+arbor.command("dev").description("serve `list`, `show` and `log` as a web page; read-only").option("port", t.number(), {
   default: DEFAULT_PORT,
   description: "port to listen on, or the next open one above it"
 }).action((opts, ctx) => dev(ctx, { ports: devPorts(opts.port) }));
@@ -1350,8 +1376,17 @@ arbor.command("path").description("print a task's worktree path, or the main tre
 arbor.command("escalate").description("hand this task to a human and stop: records the reason, drops the lease and leaves the worktree exactly as it is; use instead of resolving a genuine conflict badly just to finish").arg("reason", t.string(), { description: "why this needs a human" }).option("task", t.string(), {
   default: "",
   description: "task name, when run outside its worktree"
-}).action(async (opts, ctx) => ctx.journal.record("escalate", opts.task || await here(ctx), () => escalate(ctx, opts.reason, ctx.ps.cwd(), opts.task || undefined)));
+}).action(async (opts, ctx) => ctx.journal.record("escalate", opts.task || await here(ctx), () => escalate(ctx, opts.reason, ctx.ps.cwd(), {
+  task: opts.task || undefined
+})));
 arbor.command("retry").description("give an escalated task another mergeRetryCount merge attempts and put it back to working; the way out of `budget_exhausted` that is not rm and redo, and only from escalated, so a human has seen the tree first").arg("task", t.string(), { description: "task name" }).action((opts, ctx) => ctx.journal.record("retry", opts.task, () => retry(ctx, opts.task)));
+async function here({
+  service,
+  git,
+  ps
+}) {
+  return service.taskFor(await git.currentBranch(ps.cwd()).catch(() => ""));
+}
 
 // dev/build/main.txt
 var main_default = `var __create = Object.create;
@@ -18889,7 +18924,7 @@ class Feed {
     stream.onerror = () => this.set({ offline: true });
     this.load();
   }
-  stop() {
+  dispose() {
     this.stream?.close();
     this.stream = null;
   }
@@ -19106,7 +19141,7 @@ function App() {
   const [feed] = import_react6.useState(() => new Feed);
   useDisposerEffect((disposer) => {
     feed.start();
-    disposer.defer(() => feed.stop());
+    disposer.use(feed);
   }, [feed]);
   const { snapshot, offline } = useReactive(feed, (feed2) => ({ snapshot: feed2.snapshot, offline: feed2.offline }), ["changed"]);
   const [tab, setTab] = import_react6.useState("tasks");

package/{ls.d.ts → list.d.ts}

@@ -1,10 +1,10 @@
 import { type Logger } from "webappwiz/log";
 import type { WorktreeService } from "./worktree-service.js";
-export interface LsOptions {
+export interface ListOptions {
     /** Print the rows as JSON instead of a table. */
     json?: boolean;
 }
-export declare function ls({ service, log }: {
+export declare function list({ service, log }: {
     service: WorktreeService;
     log: Logger;
-}, { json }?: LsOptions): Promise<void>;
+}, { json }?: ListOptions): Promise<void>;

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.11",
+	"version": "0.0.13",
 	"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.11"
+		"webappwiz": "^0.0.13"
 	},
 	"main": "./index.js",
 	"types": "./index.d.ts",

package/shell.d.ts

@@ -1,8 +1,4 @@
 import { type Ps, type SpawnCaptureResult, type SpawnOptions, type SpawnResult } from "webappwiz/system";
-/** Spawn options for a shell command. `cwd` is the worktree it runs against. */
-export type ShellRunOptions = SpawnOptions & {
-    cwd: string;
-};
 /** What a `Shell` spawns through; the real process by default. */
 export interface ShellOptions {
     ps?: Ps;
@@ -15,7 +11,7 @@ export declare class Shell {
     private readonly ps;
     constructor(opts?: ShellOptions);
     /** Captures output, for commands whose failure has to be reported back. */
-    run(command: string, opts: ShellRunOptions): Promise<SpawnCaptureResult>;
+    run(command: string, cwd: string, opts?: SpawnOptions): Promise<SpawnCaptureResult>;
     /** Inherits stdio, for commands the agent should watch as they run. */
-    stream(command: string, opts: ShellRunOptions): Promise<SpawnResult>;
+    stream(command: string, cwd: string, opts?: SpawnOptions): Promise<SpawnResult>;
 }

package/show.d.ts

@@ -23,7 +23,7 @@ export interface ShowOptions {
     json?: boolean;
 }
 /**
- * One task in full: what `ls` shows for it, plus the `ARBOR.md` its agent
+ * One task in full: what `list` shows for it, plus the `ARBOR.md` its agent
  * left at the worktree root. Reading a tree this way takes no lease, so it
  * cannot knock the agent driving it off its own work.
  */
@@ -31,13 +31,18 @@ export declare function show({ service, fs, log }: {
     service: WorktreeService;
     fs: Fs;
     log: Logger;
-}, task: string, { json }?: ShowOptions): Promise<void>;
+}, task: string, opts?: ShowOptions): Promise<void>;
+/** Configures how {@link TaskDetails} gathers a task's info. */
+export interface TaskDetailsOptions {
+    /** What the worktree is read through; the real filesystem by default. */
+    fs?: Fs;
+}
 /**
  * Everything there is to say about one task. Split out so `dev` can render the
  * same fields this prints, rather than assembling its own and drifting.
  */
-export interface TaskDetailsOptions {
-    /** What the worktree is read through; the real filesystem by default. */
-    fs?: Fs;
+export declare class TaskDetails {
+    private readonly fs;
+    constructor(opts?: TaskDetailsOptions);
+    get(worktree: Worktree): Promise<Details>;
 }
-export declare function taskDetails(worktree: Worktree, opts?: TaskDetailsOptions): Promise<Details>;

package/snapshot.d.ts

@@ -2,13 +2,13 @@ import { type Fs } from "webappwiz/system";
 import type { Entry, Journal } from "./journal.js";
 import { type Details } from "./show.js";
 import type { WorktreeService } from "./worktree-service.js";
-/** Everything one page shows: `ls` and `show` for each task, plus `log`. */
+/** Everything one page shows: `list` and `show` for each task, plus `log`. */
 export interface Snapshot {
     tasks: Details[];
     entries: Entry[];
 }
 /**
- * Reads the whole repo the way `ls`, `show` and `log` do. Takes no lease, so
+ * Reads the whole repo the way `list`, `show` and `log` do. Takes no lease, so
  * serving a page cannot knock an agent off the tree it is driving.
  */
 export interface SnapshotOptions {