@webappwiz/arbor 0.0.23 → 0.0.25

package/README.md

@@ -27,14 +27,14 @@ rebase, and that is what `remove` is for.
 
 ## Commands
 
-### `arbor add <task> [--base <branch>] [--todo <id>]`
+### `arbor add <task> [--base <branch>] [--todo <id,...>]`
 
 Creates the task: branch `task/<task>`, a worktree at
 `../<repo>-arbor/<task>`, and a state record.
 
-`--todo <id>` takes up a todo (see `arbor todo`): its text becomes the plan's
-`## Goal`, followed by the path of each file attached to it, and no other task
-can take it while this one lives.
+`--todo 3,5` takes up todos (see `arbor todo`): their text becomes the plan's
+`## Goal`, each followed by the path of every file attached to it, and no
+other task can take them while this one lives.
 
 `--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>`
@@ -107,11 +107,13 @@ configures none.
 A merge onto trunk ends by recommending what to do next: one todo, the task's
 own follow-ups first and then the longest waiting, plus any todo older than
 `todoStalenessMs` (30 days) offered for removal instead. The todos the task
-took up with `--todo` leave the list, since that work is now done.
+took up, with `--todo` or `todo take`, leave the list, since that work is now
+done; release one first to keep what is left of it.
 
 ```
 merged alpha onto main (1a2b3c4)
   worktree removed, cd /src/repo
+  done todo 5: show upload progress
 
 next todo 7: retry the upload when the token expires
   from alpha, waiting 2h
@@ -186,7 +188,7 @@ and anything off is printed under it.
 Warnings only, never a refusal: the agent that wrote the file is the one that
 runs `show` on it, and a rough plan still beats none.
 
-### `arbor wait <task> [--timeout-secs 300] [--answered]`
+### `arbor wait <task> [--timeout-secs 900] [--answered]`
 
 Blocks until a task stops moving, then prints where it stopped.
 
@@ -196,7 +198,7 @@ discarded, and `arbor log` says which), or one of the broken statuses.
 
 This is for the agent whose own work overlaps a task already in flight and
 would rather rebase onto its result than against it. The timeout is short by
-design: five minutes, and then a `timeout` refusal that hands the decision
+design: fifteen minutes, and then a `timeout` refusal that hands the decision
 back, rather than a session that blocks all afternoon on a tree nobody is
 driving. Wait again, work alongside it, or ask the human.
 
@@ -303,7 +305,8 @@ session: it is waiting in its chat, not reading its plan, so answer it there.
 ### `arbor log [--count 20] [--json]`
 
 The last N things done here (`add`, `claim`, `merge`, `remove`, `escalate`,
-`retry`, `replies`, `todo add`, `todo update`, `todo remove`, and from the
+`retry`, `replies`, `todo add`, `todo update`, `todo take`, `todo release`,
+`todo remove`, and from the
 page `reply`, `withdraw`, `defer`, `skip` and `approve`), oldest first, each with the task and how it ended (`ok`, or
 the refusal reason).
 
@@ -424,7 +427,7 @@ imports, a signature changed on one side and its callers on the other) and
 unreliable when both sides restructured the same logic, because then there is no
 correct merge, only a decision.
 
-### `arbor todo add <text> [--file <path>]`, `arbor todo list [--json]`, `arbor todo update <id> [text] [--file <path>] [--remove-file <name>]`, `arbor todo remove <id>`
+### `arbor todo add <text> [--file <path>]`, `arbor todo list [--json]`, `arbor todo update <id> [text] [--file <path>] [--remove-file <name>]`, `arbor todo take <id...>`, `arbor todo release <id...>`, `arbor todo remove <id>`
 
 Work deferred for later. When something outside the task comes up (a bug next
 door, a follow-up the reviewer asked for, a question that turns out to be its
@@ -437,9 +440,13 @@ one at once, with nothing to commit and no two agents rewriting the same file.
 Numbers are never reused. They are local to the clone: not in git history,
 not on a fresh checkout.
 
-`arbor add <task> --todo <id>` is how one gets picked up. `update` rewords
-one and keeps its number; `remove` drops one done some other way or no longer
-wanted.
+`arbor add <task> --todo <id,...>` picks todos up with a new task; `take`,
+run from a worktree, adds them to the task already under way, all or none.
+A task can hold any number. `release` puts them back on the list, from a
+worktree only its own task's: a task landing with one half done rewords it to
+what is left with `update`, then releases it, so the merge leaves it open.
+`update` rewords one and keeps its number; `remove` drops one done some other
+way or no longer wanted.
 
 `--file a.png,notes.md` attaches files of any kind, stored beside the todo in
 `.git/arbor/todos/<id>/` the way a reply's are. `update --remove-file` drops

package/add.d.ts

@@ -8,10 +8,10 @@ export interface AddOptions {
     /** Branch the task starts from and merges onto. Defaults to the trunk. */
     base?: string;
     /**
-     * The todo this task takes up: its text seeds the plan's Goal, and nobody
-     * else can take it while the task lives.
+     * The todos this task takes up: their text seeds the plan's Goal, and
+     * nobody else can take them while the task lives.
      */
-    todo?: number;
+    todos?: number[];
 }
 export declare function add({ service, shell, config, log, fs, todos, }: {
     service: WorktreeService;
@@ -20,4 +20,4 @@ export declare function add({ service, shell, config, log, fs, todos, }: {
     log: Logger;
     fs: Fs;
     todos: Todos;
-}, task: string, { base, todo: id }?: AddOptions): Promise<void>;
+}, task: string, { base, todos: ids }?: AddOptions): Promise<void>;

package/index.js

@@ -323,7 +323,7 @@ async function add({
   log,
   fs,
   todos
-}, task, { base = config.trunk, todo: id } = {}) {
+}, task, { base = config.trunk, todos: ids = [] } = {}) {
   if (!NAME.test(task)) {
     fail("usage", `invalid task name '${task}': use lowercase letters, digits and dashes`, { task });
   }
@@ -337,9 +337,13 @@ async function add({
   if (!found.gone) {
     fail("exists", `task '${task}' already exists: run \`arbor claim ${task}\``, { task, worktree: found.path });
   }
-  const todo = id === undefined ? null : await todos.find(id);
-  if (todo?.takenBy) {
-    await todo.take(task);
+  const taken = [];
+  for (const id of new Set(ids)) {
+    const todo = await todos.find(id);
+    if (todo.takenBy) {
+      await todo.take(task);
+    }
+    taken.push(todo);
   }
   const added = await service.add(task, { base });
   if (added.code !== 0) {
@@ -356,8 +360,10 @@ async function add({
 ${PLAN_FILE}
 `.trimStart());
   }
-  await fs.write(`${worktree.path}/${PLAN_FILE}`, PLAN(task, todo === null ? null : goal(todo.text, todo.files)));
-  await todo?.take(task);
+  await fs.write(`${worktree.path}/${PLAN_FILE}`, PLAN(task, taken.length === 0 ? null : goal(taken)));
+  for (const todo of taken) {
+    await todo.take(task);
+  }
   if (config.postCheckout) {
     const { exitCode } = await shell.stream(config.postCheckout, worktree.path, {
       env: {
@@ -375,8 +381,13 @@ ${PLAN_FILE}
   branch:   ${worktree.branch}
   base:     ${base}`);
 }
-function goal(text, files) {
-  return files.length === 0 ? text : [text, "", ...files.map((path) => `Attached: \`${path}\``)].join(`
+function goal(todos) {
+  return todos.map((todo) => {
+    const text = todos.length === 1 ? todo.text : `Todo ${todo.id}: ${todo.text}`;
+    return todo.files.length === 0 ? text : [text, "", ...todo.files.map((path) => `Attached: \`${path}\``)].join(`
+`);
+  }).join(`
+
 `);
 }
 function PLAN(task, goal2) {
@@ -1661,6 +1672,41 @@ async function todoUpdate(deps, id, { text, files: files2 = [], removeFiles = []
 `));
   return updated;
 }
+async function todoTake({ todos, log: log2 }, ids, task) {
+  if (task === null) {
+    fail("usage", "take todos from the worktree of the task they belong to, or start one with `arbor add <task> --todo <id>`", { todos: ids });
+  }
+  const found = await findAll(todos, ids);
+  for (const todo of found) {
+    if (todo.takenBy !== null && todo.takenBy !== task) {
+      await todo.take(task);
+    }
+  }
+  const taken = await Promise.all(found.map((todo) => todo.take(task)));
+  log2.info([
+    ...taken.map((todo) => `${color10.green("took")} todo ${todo.id}: ${todo.text}`),
+    `  add ${taken.length === 1 ? "it" : "them"} to the Goal in ARBOR.md; merging removes ${taken.length === 1 ? "it" : "them"}`
+  ].join(`
+`));
+  return taken;
+}
+async function todoRelease({ todos, log: log2 }, ids, task) {
+  const found = await findAll(todos, ids);
+  const other = found.find((todo) => task !== null && todo.takenBy !== null && todo.takenBy !== task);
+  if (other) {
+    fail("exists", `todo ${other.id} is taken by '${other.takenBy}', not '${task}': nothing was released`, { todo: other.id, takenBy: other.takenBy });
+  }
+  const released = await Promise.all(found.map((todo) => todo.release()));
+  log2.info(released.map((todo) => `${color10.green("released")} todo ${todo.id}: ${todo.text}`).join(`
+`));
+  return released;
+}
+async function findAll(todos, ids) {
+  if (ids.length === 0) {
+    fail("usage", "name at least one todo id: run `arbor todo list`", {});
+  }
+  return Promise.all([...new Set(ids)].map((id) => todos.find(id)));
+}
 async function todoRemove({ todos, log: log2 }, id) {
   const todo = await todos.find(id);
   await todo.remove();
@@ -1794,13 +1840,15 @@ ${ran.stderr}`)
 `), { task, exitCode: ran.exitCode });
     }
   }
-  for (const todo of await todos.takenBy(task)) {
+  const done = await todos.takenBy(task);
+  for (const todo of done) {
     await todo.remove();
   }
   const lines = [
     `${color11.green("merged")} ${task} onto ${base} (${head})${landing === git.root ? "" : `
   landed in: ${landing}`}
-  worktree removed, cd ${git.root}`
+  worktree removed, cd ${git.root}`,
+    ...done.map((todo) => `  done todo ${todo.id}: ${todo.text}`)
   ];
   if (landing === git.root) {
     lines.push(...recommendation(await recommend(todos, task, config.todoStalenessMs)));
@@ -2494,7 +2542,7 @@ async function retry({
 // wait.ts
 import { color as color14 } from "webappwiz/log";
 import { Duration, sleep } from "webappwiz/time";
-var DEFAULT_TIMEOUT = Duration.mins(5);
+var DEFAULT_TIMEOUT = Duration.mins(15);
 var POLL = Duration.secs(2);
 var RUNNING = ["working", "merging"];
 async function wait({
@@ -2556,12 +2604,12 @@ 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", z.string(), { description: "task name (lowercase-with-dashes)" }).option("base", z.string(), {
   default: "",
   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"
-}).option("todo", z.coerce.number().int().nonnegative(), {
-  default: 0,
-  description: "take up this todo: its text becomes the plan's Goal, merging removes it, and removing the task puts it back"
+}).option("todo", z.string(), {
+  default: "",
+  description: "take up these todos, comma separated: their text becomes the plan's Goal, merging removes them, and removing the task puts them back"
 }).action((opts, ctx) => ctx.journal.record("add", opts.task, () => add(ctx, opts.task, {
   base: opts.base || undefined,
-  todo: opts.todo || undefined
+  todos: todoIds(opts.todo)
 })));
 arbor.command("claim").description("resume an existing task: take ownership of its worktree and print its path, status and any half-finished rebase; an escalated task goes back to working; 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", z.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())));
@@ -2652,7 +2700,28 @@ todo.command("update").description("say what a todo is in other words, or attach
   files: commaList(opts.file),
   removeFiles: commaList(opts["remove-file"])
 })));
+todo.command("take").description("take up todos for the task whose worktree you are in, as when they turn out to be part of its work: merging removes them, removing the task puts them back").rest("ids", z.coerce.number().int().positive(), {
+  description: "todo ids"
+}).action(async (opts, ctx) => {
+  const task = await here(ctx);
+  await ctx.journal.record("todo take", task, () => todoTake(ctx, opts.ids, task));
+});
+todo.command("release").description("put taken todos back on the list, as when a task lands without finishing them: `arbor todo update` the leftover first; from a worktree, only its own task's").rest("ids", z.coerce.number().int().positive(), {
+  description: "todo ids"
+}).action(async (opts, ctx) => {
+  const task = await here(ctx);
+  await ctx.journal.record("todo release", task, () => todoRelease(ctx, opts.ids, task));
+});
 todo.command("remove").description("drop a todo that was done some other way or no longer applies").arg("id", z.coerce.number().int().positive(), { description: "todo id" }).action((opts, ctx) => ctx.journal.record("todo remove", null, () => todoRemove(ctx, opts.id)));
+function todoIds(raw) {
+  return commaList(raw).map((value) => {
+    const id = Number(value);
+    if (!Number.isInteger(id) || id <= 0) {
+      fail("usage", `'${value}' is not a todo id`, { todo: value });
+    }
+    return id;
+  });
+}
 function commaList(raw) {
   return raw.split(",").map((value) => value.trim()).filter(Boolean);
 }

package/package.json

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

package/todo.d.ts

@@ -132,6 +132,24 @@ export declare function todoUpdate(deps: {
     fs: Fs;
     ps: Ps;
 }, id: number, { text, files, removeFiles }?: TodoUpdateOptions): Promise<Todo>;
+/**
+ * Takes up todos for `task` after it started, as when one turns out to be
+ * part of the work. Every id is checked before any is taken, so one that is
+ * gone or another task's refuses them all.
+ */
+export declare function todoTake({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, ids: number[], task: string | null): Promise<Todo[]>;
+/**
+ * Puts todos back on the list, as when a task is landing without finishing
+ * them: say what is left with `arbor todo update` first. From a worktree it
+ * gives back only its own task's todos.
+ */
+export declare function todoRelease({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, ids: number[], task: string | null): Promise<Todo[]>;
 export declare function todoRemove({ todos, log }: {
     todos: Todos;
     log: Logger;