@webappwiz/arbor 0.0.14 → 0.0.15

package/README.md

@@ -23,7 +23,7 @@ Two rules make that safe:
 
 Conflicts between agents are expected, not a process failure. Discarding a task
 and redoing it against current trunk is cheap and often better than a hard
-rebase, and that is what `rm` is for.
+rebase, and that is what `remove` is for.
 
 ## Commands
 
@@ -78,7 +78,7 @@ linear.
    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`
+5. Discards the task (worktree, branch and record) exactly as `remove`
    would. The work is on trunk, so the tree has nothing left to hold, and
    `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
@@ -91,7 +91,7 @@ fails the branch is reset to where it was and trunk is never touched.
 There is deliberately no flag to skip the gate: a repo that wants none
 configures none.
 
-### `arbor rm <task>`
+### `arbor remove <task>`
 
 Discards a task: `git worktree remove` plus the branch and the record.
 
@@ -100,7 +100,7 @@ discards its own tree. Use it freely. Warns about commits that never landed,
 but never blocks: throwing work away is the cheap escape hatch, not a last
 resort.
 
-Removal leaves a tombstone in `.git/arbor/removed/` so a second `rm` can say
+Removal leaves a tombstone in `.git/arbor/removed/` so a second `remove` can say
 `already_removed` rather than `not_found`. The ledger keeps the 50 most recent
 and drops the oldest as new ones arrive, so a long-forgotten task reports
 `not_found` again.
@@ -160,7 +160,7 @@ agent off it.
 
 ### `arbor log [--count 20] [--json]`
 
-The last N things done here (`add`, `claim`, `merge`, `rm`, `escalate`,
+The last N things done here (`add`, `claim`, `merge`, `remove`, `escalate`,
 `retry`),
 oldest first, each with the task and how it ended (`ok`, or the refusal reason).
 
@@ -172,7 +172,7 @@ WHEN  ACTION    TASK   RESULT
 ```
 
 `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
+a successful `merge` and a `remove` 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`.
 
@@ -218,7 +218,7 @@ correct merge, only a decision.
 ### `arbor retry <task>`
 
 Grants an escalated task another `mergeRetryCount` merge attempts and puts it
-back to `working`. The way out of `budget_exhausted` that is not `rm` and redo,
+back to `working`. The way out of `budget_exhausted` that is not `remove` and redo,
 for the case where the task was one fix away rather than genuinely lost.
 
 Only from `escalated`, and that is the whole design. The budget exists to make
@@ -239,13 +239,13 @@ The agent's control flow runs on these.
 | 2    | `conflict`          | Rebase conflicted. **Rebase is still in progress.** Resolve, `git add`, `git rebase --continue`, merge again. |
 | 3    | `tests_failed`      | The gate (`postRewrite`, `preMerge`) failed after the rebase. Branch rolled back, trunk untouched. Fix and merge again. |
 | 4    | `lease_lost`        | Another agent took the tree mid-merge. **Stop. Do not retry.**     |
-| 5    | `budget_exhausted`  | Out of merge attempts. `arbor escalate`, and a human can grant another budget with `arbor retry`; or `arbor rm` and redo against current trunk. |
+| 5    | `budget_exhausted`  | Out of merge attempts. `arbor escalate`, and a human can grant another budget with `arbor retry`; or `arbor remove` and redo against current trunk. |
 | 6    | `lease_held`        | Another agent is driving this tree.                                |
 | 7    | `dirty`             | Uncommitted changes. Commit before merging.                       |
 | 8    | `not_found`         | No such task, or not run from a task worktree.                     |
 | 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.                         |
+| 10   | `exists`            | Task already exists. `arbor claim` it, or `arbor remove` first. |
+| 11   | `orphaned`          | Record with no worktree. `arbor remove` it.                     |
 | 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.        |
@@ -270,7 +270,7 @@ export default defineConfig({
 	postMerge: "bun install",       // in the main tree, after the branch lands
 	leaseStalenessMs: 90_000,
 	mergeRetryCount: 2,
-	removedCapacity: 50,            // removed names kept, so rm can say "already removed"
+	removedCapacity: 50,            // removed names kept, so remove can say "already removed"
 	logCapacity: 200,               // entries `arbor log` keeps before the oldest fall off
 });
 ```
@@ -330,5 +330,5 @@ other. Git still leaves the file staged as `UU`, so the agent must confirm with
 exists because of a real livelock: an agent rebases onto trunk, another agent
 lands during its test run, and it is stale again before it finishes. Under load
 an unlucky agent can chase a moving trunk indefinitely. When the budget is gone,
-escalate or `arbor rm`: redoing the task against current trunk usually beats
+escalate or `arbor remove`: redoing the task against current trunk usually beats
 retrofitting a rebase.

package/config.d.ts

@@ -33,7 +33,7 @@ export interface Config {
     /** Failed `merge` attempts a task gets before it must escalate or be removed. */
     mergeRetryCount: number;
     /**
-     * How many removed task names to keep, so `rm` can say "already removed"
+     * How many removed task names to keep, so `remove` can say "already removed"
      * rather than "never existed". A flat cap with no age policy: losing the
      * oldest costs a nicer message and nothing else.
      */

package/index.js

@@ -77,7 +77,7 @@ async function add({
   }
   const found = await service.find(task);
   if (found.status === "stray") {
-    fail("exists", `branch ${found.branch} exists without a worktree: run \`arbor rm ${task}\` first`, { task, branch: found.branch });
+    fail("exists", `branch ${found.branch} exists without a worktree: run \`arbor remove ${task}\` first`, { task, branch: found.branch });
   }
   if (!found.gone) {
     fail("exists", `task '${task}' already exists: run \`arbor claim ${task}\``, { task, worktree: found.path });
@@ -129,10 +129,10 @@ async function claim({ service, log }, task) {
     });
   }
   if (found.status === "orphaned") {
-    fail("orphaned", `state file for '${task}' has no worktree at ${found.path}: run \`arbor rm ${task}\``, { task, worktree: found.path });
+    fail("orphaned", `state file for '${task}' has no worktree at ${found.path}: run \`arbor remove ${task}\``, { task, worktree: found.path });
   }
   if (found.status === "stray") {
-    fail("orphaned", `branch ${found.branch} exists but has no worktree: run \`arbor rm ${task}\` and start over`, { task, branch: found.branch });
+    fail("orphaned", `branch ${found.branch} exists but has no worktree: run \`arbor remove ${task}\` and start over`, { task, branch: found.branch });
   }
   if (found.leaseHeldByOther) {
     fail("lease_held", `'${task}' is held by pid ${found.lease?.pid} on ${found.lease?.hostname} (heartbeat ${found.lease?.heartbeatAt}): another agent is driving this tree`, { task, lease: found.lease });
@@ -555,7 +555,7 @@ function listing(rows) {
   ];
   const orphaned = rows.filter((row3) => row3.status === "orphaned");
   if (orphaned.length > 0) {
-    out.push("", color7.yellow(`${orphaned.length} orphaned record(s): run \`arbor rm ${orphaned[0]?.task}\``));
+    out.push("", color7.yellow(`${orphaned.length} orphaned record(s): run \`arbor remove ${orphaned[0]?.task}\``));
   }
   return out.join(`
 `);
@@ -587,7 +587,7 @@ async function merge({
     fail("dirty", `'${task}' has uncommitted changes: commit them before merging`, { task, paths: dirty });
   }
   if (worktree.mergeAttempts >= config.mergeRetryCount) {
-    fail("budget_exhausted", `'${task}' has used its ${config.mergeRetryCount} merge attempts: run \`arbor escalate <reason>\`, and a human can grant another ${config.mergeRetryCount} with \`arbor retry ${task}\`; or \`arbor rm ${task}\` and start over against current ${base}`, { task, mergeAttempts: worktree.mergeAttempts });
+    fail("budget_exhausted", `'${task}' has used its ${config.mergeRetryCount} merge attempts: run \`arbor escalate <reason>\`, and a human can grant another ${config.mergeRetryCount} with \`arbor retry ${task}\`; or \`arbor remove ${task}\` and start over against current ${base}`, { task, mergeAttempts: worktree.mergeAttempts });
   }
   if (worktree.leaseHeldByOther) {
     fail("lease_held", `'${task}' is held by pid ${worktree.lease?.pid} on ${worktree.lease?.hostname}: another agent is driving this tree`, { task, lease: worktree.lease });
@@ -608,7 +608,7 @@ async function merge({
       "The rebase is still in progress. Resolve the conflicts, `git add` them,",
       "`git rebase --continue`, then run `arbor merge` again.",
       "If both sides restructured the same logic, prefer `arbor escalate <reason>`",
-      `or \`arbor rm ${task}\` and redo the task against current ${base}.`
+      `or \`arbor remove ${task}\` and redo the task against current ${base}.`
     ].join(`
 `), { task, paths });
   }
@@ -661,7 +661,7 @@ ${gated.stderr}`)
   await lock.release();
   if (discarded.code !== 0) {
     fail("usage", `landed '${task}' on ${base} (${head}) but could not discard its worktree: ${discarded.stderr || discarded.stdout}
-Run \`arbor rm ${task}\` to clean up.`, { task });
+Run \`arbor remove ${task}\` to clean up.`, { task });
   }
   if (config.postMerge) {
     const ran = await shell.run(config.postMerge, landing, {
@@ -712,6 +712,40 @@ async function path({ service, log: log2 }, task) {
   log2.info(worktree.path);
 }
 
+// remove.ts
+import { color as color9 } from "webappwiz/log";
+async function remove({ service, log: log2 }, task, { force = false } = {}) {
+  const worktree = await service.find(task);
+  if (worktree.gone) {
+    const removed = worktree.status === "removed";
+    fail(removed ? "already_removed" : "not_found", removed ? `'${task}' was already removed (${worktree.removedAt}), nothing left to remove` : `no worktree, branch or state file named '${task}', so it never existed here`, { task });
+  }
+  if (worktree.leaseHeldByOther) {
+    if (!force) {
+      fail("lease_held", `'${task}' is held by pid ${worktree.lease?.pid} on ${worktree.lease?.hostname}: pass --force to discard it anyway`, { task, lease: worktree.lease });
+    }
+    log2.error(color9.yellow(`arbor: --force discarding a tree held by pid ${worktree.lease?.pid}`));
+  }
+  const unlanded = worktree.hasBranch ? await worktree.commitsAhead() : 0;
+  const discarded = await worktree.discard();
+  if (discarded.code !== 0) {
+    fail("usage", `discarding '${task}' failed: ${discarded.stderr}`, {
+      task
+    });
+  }
+  const lines = [
+    `${color9.green("removed")} ${task}`,
+    `  worktree: ${worktree.exists ? worktree.path : "already gone"}`,
+    `  branch:   ${worktree.hasBranch ? worktree.branch : "already gone"}`,
+    `  state:    ${worktree.state ? "removed" : "already gone"}`
+  ];
+  if (unlanded) {
+    lines.push(color9.yellow(`  discarded ${unlanded} commit(s) that were never on ${worktree.base}`));
+  }
+  log2.info(lines.join(`
+`));
+}
+
 // repository.ts
 import { dirname } from "node:path";
 import { FileLock } from "webappwiz/system";
@@ -1246,7 +1280,7 @@ function repository(at) {
 }
 
 // retry.ts
-import { color as color9 } from "webappwiz/log";
+import { color as color10 } from "webappwiz/log";
 async function retry({
   service,
   config,
@@ -1261,7 +1295,7 @@ async function retry({
   }
   const worktree = await found.save({ status: "working", mergeAttempts: 0 });
   log2.info([
-    `${color9.green("retry")} ${worktree.task}`,
+    `${color10.green("retry")} ${worktree.task}`,
     `  attempts: 0 of ${config.mergeRetryCount}`,
     `  status:   working`,
     "",
@@ -1270,40 +1304,6 @@ async function retry({
 `));
 }
 
-// rm.ts
-import { color as color10 } from "webappwiz/log";
-async function rm({ service, log: log2 }, task, { force = false } = {}) {
-  const worktree = await service.find(task);
-  if (worktree.gone) {
-    const removed = worktree.status === "removed";
-    fail(removed ? "already_removed" : "not_found", removed ? `'${task}' was already removed (${worktree.removedAt}), nothing left to remove` : `no worktree, branch or state file named '${task}', so it never existed here`, { task });
-  }
-  if (worktree.leaseHeldByOther) {
-    if (!force) {
-      fail("lease_held", `'${task}' is held by pid ${worktree.lease?.pid} on ${worktree.lease?.hostname}: pass --force to discard it anyway`, { task, lease: worktree.lease });
-    }
-    log2.error(color10.yellow(`arbor: --force discarding a tree held by pid ${worktree.lease?.pid}`));
-  }
-  const unlanded = worktree.hasBranch ? await worktree.commitsAhead() : 0;
-  const discarded = await worktree.discard();
-  if (discarded.code !== 0) {
-    fail("usage", `discarding '${task}' failed: ${discarded.stderr}`, {
-      task
-    });
-  }
-  const lines2 = [
-    `${color10.green("removed")} ${task}`,
-    `  worktree: ${worktree.exists ? worktree.path : "already gone"}`,
-    `  branch:   ${worktree.hasBranch ? worktree.branch : "already gone"}`,
-    `  state:    ${worktree.state ? "removed" : "already gone"}`
-  ];
-  if (unlanded) {
-    lines2.push(color10.yellow(`  discarded ${unlanded} commit(s) that were never on ${worktree.base}`));
-  }
-  log2.info(lines2.join(`
-`));
-}
-
 // wait.ts
 import { color as color11 } from "webappwiz/log";
 import { Duration as Duration2, sleep } from "webappwiz/time";
@@ -1349,10 +1349,10 @@ arbor.command("add").description("start a new task: create branch task/<task>, a
 }).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 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(), {
+arbor.command("remove").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 })));
+}).action((opts, ctx) => ctx.journal.record("remove", opts.task, () => remove(ctx, opts.task, { force: opts.force })));
 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(), {
@@ -1361,7 +1361,7 @@ arbor.command("wait").description("block until a task stops moving: escalated, o
 }).action((opts, ctx) => wait(ctx, opts.task, {
   timeout: Duration3.secs(opts["timeout-secs"])
 }));
-arbor.command("log").description("show what has been done here recently: one line per add, claim, merge, rm, escalate and retry, with how it ended; outlives the tasks themselves").option("count", t.number(), {
+arbor.command("log").description("show what has been done here recently: one line per add, claim, merge, remove, escalate and retry, with how it ended; outlives the tasks themselves").option("count", t.number(), {
   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 }));
@@ -1379,7 +1379,7 @@ arbor.command("escalate").description("hand this task to a human and stop: recor
 }).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)));
+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 remove 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,

package/journal.d.ts

@@ -10,7 +10,7 @@ export interface Entry {
 }
 /**
  * What has been done in this repo, oldest first. Entries outlive their tasks:
- * `merge` and `rm` take the record with them, so this is the only thing that
+ * `merge` and `remove` take the record with them, so this is the only thing that
  * remembers a task existed at all.
  */
 /** What a `Journal` is stored through; the real filesystem by default. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webappwiz/arbor",
-	"version": "0.0.14",
+	"version": "0.0.15",
 	"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.14"
+		"webappwiz": "^0.0.15"
 	},
 	"main": "./index.js",
 	"types": "./index.d.ts",

package/{rm.d.ts → remove.d.ts}

@@ -1,6 +1,6 @@
 import { type Logger } from "webappwiz/log";
 import type { WorktreeService } from "./worktree-service.js";
-export interface RmOptions {
+export interface RemoveOptions {
     /** Discard the tree even when another agent holds its lease. */
     force?: boolean;
 }
@@ -11,7 +11,7 @@ export interface RmOptions {
  * Throwing a task away and redoing it against current trunk is usually cheaper
  * than a hard rebase, so this is meant to be used freely.
  */
-export declare function rm({ service, log }: {
+export declare function remove({ service, log }: {
     service: WorktreeService;
     log: Logger;
-}, task: string, { force }?: RmOptions): Promise<void>;
+}, task: string, { force }?: RemoveOptions): Promise<void>;

package/retry.d.ts

@@ -3,7 +3,7 @@ import type { Config } from "./config.js";
 import type { WorktreeService } from "./worktree-service.js";
 /**
  * The way back from `budget_exhausted`. A task that has spent its merge
- * attempts gets another `mergeRetryCount` of them, instead of `rm` and redo.
+ * attempts gets another `mergeRetryCount` of them, instead of `remove` and redo.
  *
  * Only from `escalated`, and deliberately: the budget's whole job is to make an
  * agent stop and hand the task over. An agent that could grant itself more

package/worktree-service.d.ts

@@ -43,7 +43,7 @@ export declare class WorktreeService {
     private removedPath;
     private removedAt;
     /**
-     * Remembers a removed name so a second `rm` can say "already removed"
+     * Remembers a removed name so a second `remove` can say "already removed"
      * instead of "never existed", then drops the oldest so the list of
      * remembered names cannot grow without bound.
      */