@webappwiz/arbor 0.0.25 → 0.0.27

package/README.md

@@ -32,9 +32,9 @@ rebase, and that is what `remove` is for.
 Creates the task: branch `task/<task>`, a worktree at
 `../<repo>-arbor/<task>`, and a state record.
 
-`--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.
+`--todo 3,5` takes up todos (see `arbor todo`): each one's subject and detail
+become the plan's `## Goal`, 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>`
@@ -75,10 +75,9 @@ 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,
-   or while a person's reply waits unclaimed (`unread`: run `arbor replies`),
    or while a question under `## Blocked` is unchecked (`blocked`): whether
-   nobody has answered it yet, or the agent has yet to act on an answer or a
-   follow-up and check it off.
+   nobody has answered it yet, or the agent has yet to act on an answer and
+   check it off.
 2. Takes the merge lock, **blocking**, polling every 2s. Blocking is
    deliberate: telling an agent "busy, try later" invites it to go edit more
    code in a branch that is supposed to be frozen.
@@ -104,9 +103,10 @@ 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.
 
-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
+A merge onto trunk ends by recommending what to do next: the open todo highest
+on the list that came up in the task that landed, since its context is
+freshest, or failing that the open todo highest on the list, plus any todo older than `todoStalenessMs` (30 days) offered for
+removal instead. The todos the task
 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.
 
@@ -183,12 +183,12 @@ in silence: it is the one thing that makes the work resumable.
 
 A `ARBOR.md` that is there gets checked against the shape the agent skill
 prescribes (`# <task>`, `## Goal`, `## Next` with something unchecked in it, a
-`## Blocked` with `- [ ] Q1.` items once escalated, and none left open after),
+`## Blocked` with `- [ ] 1.` items once escalated, and none left open after),
 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 900] [--answered]`
+### `arbor wait <task> [--timeout-secs 900]`
 
 Blocks until a task stops moving, then prints where it stopped.
 
@@ -205,109 +205,11 @@ driving. Wait again, work alongside it, or ask the human.
 Like `show` and `path`, it takes no lease, so watching a task cannot knock its
 agent off it.
 
-`--answered` waits for something else: until every open question under the
-task's `## Blocked` has a reply (or none is open), then claims everything new
-the way `arbor replies` does and prints it. This is how an agent that
-escalated waits for its human, with the same timeout and the same `timeout`
-refusal, which names the questions still unanswered. A reply someone has open
-to edit does not count yet. A task that is gone ends the wait too, since
-nothing is left to answer.
-
-```
-alpha has new
-  Q2 🎨 Does the header wrap to two lines?
-    → yes
-```
-
-### `arbor inbox [--replied] [--json]`
-
-Every question waiting on a person, across all tasks: each unchecked
-`- [ ] Q9.` item under a task's `## Blocked` with no reply yet, grouped by
-task. A question leaves the inbox once it is answered. `--replied` brings back
-the ones answered but not yet checked off by their agent, with the reply under
-each, follow-ups too: one still waiting for its agent says so, and can be
-changed on the page until the agent claims it. Takes no lease.
-
-```
-alpha
-  Q3 🧹 Keep or drop the old flag?
-      It has been off since March.
-
-beta (in a live session: answer it there)
-  Q1 🗄️ When should the migration run?
-      (a) Now
-      (b) After the backfill
-
-1 replied, not yet acted on: arbor inbox --replied
-```
-
-A question's line is its subject. Lines indented under it are its body,
-markdown with code blocks and images (`![shot](/abs/path.png)`, which the page
-shows inline). Choices come last in the body: `- (a) ...` lines take one or
-none, `- [a] ...` lines take any that apply.
-
-```markdown
-- [ ] Q3. 🔐 How should existing sessions move to the new tokens?
-  Sessions are keyed by the old cookie.
-  ![login screen](/abs/path/login.png)
-  - (a) Sign everyone out once
-  - (b) Migrate each session on its next request
-- [ ] Q4. 🔔 Where should failures notify?
-  - [a] Email
-  - [b] Slack
-  - [c] Push
-```
-
-### `arbor replies [task]`
-
-How an agent reads what its human answered, and the only way it does. A
-person answers from the page (`arbor dev`), never the CLI, so agents have no
-way to answer each other: every answer an agent reads through arbor came from
-a person. For anything no question asked, the person tells the agent in its
-chat.
-
-Claiming takes every reply waiting for the task, writes each into `ARBOR.md`,
-and prints them with the questions still unanswered. The first answer to a
-question goes on its line after ` → `, its picks spelled out so the line alone
-says what was picked: ` → b (Migrate each session on its next request)`, or
-` → a (Email), c (Push): and log it` with words after the picks. Once the
-agent has read an answer, the person can follow it up; a follow-up goes on a
-line of its own under the question, and unchecks it, whatever the agent did
-about the answer before:
-
-```markdown
-- [ ] Q3. 🔐 How should existing sessions move to the new tokens? → b (Migrate each session on its next request)
-  Sessions are keyed by the old cookie.
-  → Sign out the admins, though.
-```
-
-The box stays unchecked: checking it off is the agent's word that it has
-acted on everything under it. Once claimed, a reply can no longer change or be
-taken back, so the agent never acts on words that change under it. A reply the
-person has open to edit on the page is left for the next call. Run from a
-task worktree, the task is that one.
-
-```
-alpha replied
-  Q3 🧹 Keep or drop the old flag?
-    → drop
-  unanswered: Q4
-```
-
-Until claimed, a reply waits in `.git/arbor/replies/<task>/Q3.json`, its files
-beside it in `Q3/`, and the claimed line names each file by absolute path so
-the agent can open it from its own tree. They go when the task is merged or
-removed.
-
-A reply is refused (`lease_held`) while the task's agent is in a live
-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 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
+`retry`, `todo add`, `todo update`, `todo take`, `todo release` and
+`todo remove`), oldest first, each with the task and how it ended (`ok`, or
 the refusal reason).
 
 ```
@@ -324,52 +226,27 @@ the only thing that remembers a task landed at all. The last 1000 are kept
 
 ### `arbor dev [--port 4269] [--allow-hosts <names>]`
 
-The inbox, what you sent, the todos, and the tasks in a browser, on
-`http://localhost:4269`, reloading themselves as anything changes. Built for a
-phone first. The inbox holds only what waits on you: each unanswered question,
-grouped by task, a task only when it has one. A task whose agent is in a live
-session is left out, since that agent is answered in its chat. With a keyboard,
-J opens the next question, and a hint under the list says so when the page
-sees a mouse or trackpad.
-
-Tapping a question opens it with its body, images full size on a tap, its
-choices, a View button for its task, and a reply box that takes pasted or
-picked files. Beside the box, **Defer** makes the question a todo, its images
-carried along, and answers it "Deferred to todo 7: leave it out of this
-task."; **Skip** answers "Skip this: go ahead without it.". A task escalated
-with `arbor escalate --review` asks `✅ Ready to merge?` like any other
-question, with **Approve** ("Approved: merge it.") beside a box to request
-changes.
-
-Once answered, a question moves to Sent, one line each with where it stands
-in a word: Waiting (for its agent, still yours to change or withdraw),
-Editing, Read (by its agent), or Done (checked off). Opening one still
-waiting holds it, so its agent cannot claim it half-changed, and closing it
-lets go; the hold also lapses on its own after five minutes. One its agent
-has read shows what was said so far and a box to follow it up. Each stays
-until its task lands or goes.
-
-A line across the top always says something, so nothing under it moves: the
-question you last replied to while its agent has yet to read it, with
-Withdraw, or else how many questions need you and how many replies wait for
-their agents.
+The todos and the tasks in a browser, on `http://localhost:4269`, reloading
+themselves as anything changes. Built for a phone first.
+
+Todos are cards in list order: drag one to reorder the list (a short press
+on a phone, or Space on its grip and the arrow keys), or tap it to reword,
+attach files to, or remove. Typing `@` in a todo offers the files and
+directories in the main tree, tracked or new but not ignored, and writes the
+one picked as `@path/from/root`; picking a directory keeps the list open on
+what is inside.
 
 Tasks lists every task with its progress through its plan, flagging only an
 escalated or broken status; tapping one opens its details and whole plan.
 
-Todos open to reword, attach files to, or remove. Typing `@` in a reply or a
-todo offers the files and directories in the task's tree (the main tree's for
-a todo), tracked or new but not ignored, and writes the one picked as
-`@path/from/root`; picking a directory keeps the list open on what is inside.
 On a phone the tabs sit along the bottom, in reach of a thumb; on anything
 wider they run down a sidebar. If the server stops answering, the header says
 it is offline, since what the page shows may be stale.
 
-Answering is done here and nowhere else, so an agent with a shell cannot
-answer another: see `arbor replies`. Todos are the CLI's too, through the same
-functions (`arbor todo add`, `update` and `remove`). Merging, removing tasks
-and claiming stay in the CLI, so a page that should not have been reachable
-can at worst leave a reply and change todos. It takes no lease.
+Todo writes are the same functions as `arbor todo add`, `update` and
+`remove`. Questions are answered in the agent's chat, not here. Merging,
+removing tasks and claiming stay in the CLI, so a page that should not have
+been reachable can at worst change todos. It takes no lease.
 
 It listens on 127.0.0.1 only and refuses a request whose `Host` is not this
 machine, and any write from another origin. To use it from another device,
@@ -381,7 +258,7 @@ arbor dev --allow-hosts myrepo-arbor.example.dev
 ```
 
 arbor has no login of its own. Whoever can reach an allowed host can read the
-repo's plans and reply, so the tunnel has to be the one asking who you are
+repo's plans and change its todos, so the tunnel has to be the one asking who you are
 (Cloudflare Access, a Tailscale tailnet). Never expose it through a tunnel
 with no login in front.
 
@@ -413,13 +290,37 @@ printing a path you cannot `cd` into.
 The explicit "this needs a human" exit. Records the reason, drops the lease, and
 leaves the worktree **exactly** as it is so the human sees what the agent saw.
 
+Questions go under `## Blocked` in the task's `ARBOR.md`, numbered `1.`,
+`2.`, … (a plan numbered the old way, `Q1.`, still reads). A question's line
+is its subject. Lines indented under it are its body, markdown with code
+blocks and images (`![shot](/abs/path.png)`). Choices come last in the body:
+`- (a) ...` lines take one or none, `- [a] ...` lines take any that apply.
+
+```markdown
+- [ ] 3. 🔐 How should existing sessions move to the new tokens?
+  Sessions are keyed by the old cookie.
+  ![login screen](/abs/path/login.png)
+  - (a) Sign everyone out once
+  - (b) Migrate each session on its next request
+- [ ] 4. 🔔 Where should failures notify?
+  - [a] Email
+  - [b] Slack
+  - [c] Push
+```
+
+The person answers in the agent's chat, and the agent writes each answer on
+its question's line after ` → `, then checks it off once it has acted on it:
+
+```markdown
+- [x] 3. 🔐 How should existing sessions move to the new tokens? → b (Migrate each session on its next request)
+```
+
 `--review` asks for approval to merge rather than for answers: it adds
-`- [ ] Q5. ✅ Ready to merge?` under `## Blocked`, the reason indented under
-it as what to look at, and the page shows the task as one card with Approve
-and Request changes. Refused (`blocked`) while another question is unchecked,
-so a review is the last thing standing between the task and trunk. The agent
-waits with `arbor wait --answered`, then merges on "Approved: merge it." or
-acts on the changes asked for.
+`- [ ] 5. ✅ Ready to merge?` under `## Blocked`, the reason indented under
+it as what to look at. Refused (`blocked`) while another question is
+unchecked, so a review is the last thing standing between the task and trunk.
+The agent merges once the person approves in chat, or acts on the changes
+asked for.
 
 This exists so an agent has a way out that is not "resolve the conflict badly to
 finish the task". Agents are reliable at mechanical conflicts (both sides added
@@ -427,13 +328,23 @@ 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 take <id...>`, `arbor todo release <id...>`, `arbor todo remove <id>`
+### `arbor todo add <subject> [text] [--position <n>] [--file <path>]`, `arbor todo list [--json]`, `arbor todo show <id> [--json]`, `arbor todo update <id> [text] [--subject <subject>] [--position <n>] [--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
 own project), the agent notes it with `arbor todo add` and carries on instead
 of growing the task. Run from a worktree, `add` records the task it came up
-in, which is what lets `merge` recommend a task's own follow-ups first.
+in. A todo is a subject, one line that `list` and `merge` show, and an optional
+detail below it that `show` prints in full. Agents lead a subject with one
+emoji for what it is about (`🐛 Upload retries forever on a 413`), as they do a
+question, so the list reads at a glance.
+
+The list is in order: position 1 is the top, and after a task's own todos,
+the open todo highest on it is the one `merge` recommends next. A new one goes to the bottom, or with
+`--position 2` in at 2, pushing those from there down. `update --position`
+moves one, and removing one closes the gap, so positions always run 1, 2, 3.
+Whoever keeps the list, a person on the page or an agent, decides what
+matters most by moving it up.
 
 Todos live in `.git/arbor/todos/`, one file each, so every worktree sees a new
 one at once, with nothing to commit and no two agents rewriting the same file.
@@ -445,12 +356,13 @@ 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.
+`update` rewords one, its detail as the argument and its subject with
+`--subject`, 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
-one, named by path or by its stored file name (`todo list` shows them). They
+`.git/arbor/todos/<id>/`. `update --remove-file` drops
+one, named by path or by its stored file name (`todo show` lists them). They
 go when the todo does.
 
 ### `arbor retry <task>`
@@ -478,16 +390,15 @@ The agent's control flow runs on these.
 | 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 remove` and redo against current trunk. |
-| 6    | `lease_held`        | Another agent is driving this tree. For a reply from the page: answer that agent in its chat. |
+| 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; for a reply from the page, no such open question. |
+| 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 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, or with `--answered`, a question is still unanswered. |
-| 15   | `unread`            | `arbor merge` refused: a person's reply waits unclaimed. `arbor replies`, act on it, check it off, merge again. |
+| 14   | `timeout`           | `arbor wait` gave up: the task is still working or merging. |
 | 16   | `blocked`           | `arbor merge` refused: a question under `## Blocked` is unchecked, unanswered or not yet acted on. Also `escalate --review` while one is. |
 
 Every failure prints a one-line JSON object on **stdout** (`{"reason": ...}`,

package/add.d.ts

@@ -8,7 +8,7 @@ export interface AddOptions {
     /** Branch the task starts from and merges onto. Defaults to the trunk. */
     base?: string;
     /**
-     * The todos this task takes up: their text seeds the plan's Goal, and
+     * The todos this task takes up: their words seed the plan's Goal, and
      * nobody else can take them while the task lives.
      */
     todos?: number[];

package/attachments.d.ts

@@ -7,10 +7,10 @@ export interface Attachment {
     bytes: Uint8Array;
 }
 /**
- * The folder of files that belong to one record, a reply's or a todo's, kept
- * beside it: `replies/<task>/Q2.json` has `replies/<task>/Q2/`, and
- * `todos/7.json` has `todos/7/`. Under `.git/arbor`, so nothing here is ever
- * committed and every tree can open what it holds.
+ * The folder of files that belong to a todo: todo 7's beside its record, in
+ * `todos/7/`.
+ * Under `.git/arbor`, so nothing here is ever committed and every tree can
+ * open what it holds.
  */
 export declare class Attachments {
     readonly dir: string;

package/dev.d.ts

@@ -3,7 +3,6 @@ import type { Logger } from "webappwiz/log";
 import { type Fs, type PortProvider } from "webappwiz/system";
 import type { Assets } from "./dev/assets.js";
 import type { Journal } from "./journal.js";
-import type { Replies } from "./replies.js";
 import type { Todos } from "./todo.js";
 import type { WorktreeService } from "./worktree-service.js";
 /** Preferred, not required: `dev` moves up from here when it is taken. */
@@ -27,20 +26,16 @@ export interface DevServer extends AsyncResource {
     port: number;
 }
 /**
- * Serves what `list`, `show`, `inbox` and `todo list` print, as one page that
- * refetches when the repo changes. It is the only place a person answers a
- * question: follows one up, defers or skips it, or approves a merge. The CLI
- * has no command for any of them, so no agent is tempted to answer another.
- * Anything that moves a task (merge, remove, claim) stays in the CLI, so a
- * page that should not have been reachable can at worst leave a reply or
- * change a todo.
+ * Serves what `todo list`, `list` and `show` print as one page that refetches
+ * when the repo changes, where a person adds, edits, reorders and removes
+ * todos. Anything that moves a task (merge, remove, claim) stays in the CLI,
+ * so a page that should not have been reachable can at worst change a todo.
  */
-export declare function dev({ service, fs, journal, todos, replies, log, assets, }: {
+export declare function dev({ service, fs, journal, todos, log, assets, }: {
     service: WorktreeService;
     fs: Fs;
     journal: Journal;
     todos: Todos;
-    replies: Replies;
     log: Logger;
     assets: Assets;
 }, { ports, hosts }?: DevOptions): Promise<DevServer>;

package/exit.d.ts

@@ -15,7 +15,6 @@ export declare const EXIT: {
     readonly merge_failed: 12;
     readonly already_removed: 13;
     readonly timeout: 14;
-    readonly unread: 15;
     readonly blocked: 16;
 };
 export type Reason = keyof typeof EXIT;