@webappwiz/arbor 0.0.19 → 0.0.21

package/README.md

@@ -27,11 +27,15 @@ rebase, and that is what `remove` is for.
 
 ## Commands
 
-### `arbor add <task>`
+### `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.
+
 `--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
@@ -56,6 +60,11 @@ Prints the worktree path, status, uncommitted changes, and, loudly, any
 half-finished rebase or merge the tree is standing in. Refuses if another agent
 holds the lease. A worktree with no record is rebuilt rather than rejected.
 
+Claiming an `escalated` task puts it back to `working`: someone is on it
+again, and whatever it was waiting on is theirs to act on. Its merge budget
+stays as it was. Only `retry` refills that, and only from `escalated`, so a
+human granting a fresh budget does it before the agent claims.
+
 ### `arbor merge`
 
 Lands the current worktree's branch on its base, trunk unless the task was
@@ -65,7 +74,11 @@ created with `--base`. The core command.
 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.
+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.
 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.
@@ -91,6 +104,23 @@ 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
+took up with `--todo` leave the list, since that work is now done.
+
+```
+merged alpha onto main (1a2b3c4)
+  worktree removed, cd /src/repo
+
+next todo 7: retry the upload when the token expires
+  from alpha, waiting 2h
+  start it: arbor add <task> --todo 7
+
+stale todos, remove unless they still apply:
+  2: try the old parser again (41d)  arbor todo remove 2
+```
+
 ### `arbor remove <task>`
 
 Discards a task: `git worktree remove` plus the branch and the record.
@@ -100,17 +130,31 @@ 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.
 
+The todos it took up are open again, since the work they asked for was not
+done.
+
 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.
 
-### `arbor list [--json]`
+### `arbor list [--json] [--files]`
 
 Every task: name, status, lease (`held`/`stale`/`none`), commits ahead of
 trunk, age. A corrupt record shows as `unknown` instead of taking
 down the listing; a record whose worktree vanished shows as `orphaned`.
 
+`--files` adds, under each task, every path it has changed (committed or
+not) and every path its `ARBOR.md` plans under `## Files` that it has not
+touched yet. This is the overlap check an agent runs before starting: its own
+list of files against everyone else's.
+
+```
+alpha
+  changed  src/auth.ts
+  planned  src/session.ts
+```
+
 ### `arbor show <task> [--json]`
 
 One task in full: the row `list` would print for it, plus the `ARBOR.md`
@@ -137,11 +181,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` question once escalated), and anything off is printed under it.
+`## Blocked` with `- [ ] Q1.` 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 300]`
+### `arbor wait <task> [--timeout-secs 300] [--answered]`
 
 Blocks until a task stops moving, then prints where it stopped.
 
@@ -158,11 +203,109 @@ 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`),
-oldest first, each with the task and how it ended (`ok`, or the refusal reason).
+`retry`, `replies`, `todo add`, `todo update`, `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).
 
 ```
 WHEN  ACTION    TASK   RESULT
@@ -173,13 +316,71 @@ WHEN  ACTION    TASK   RESULT
 
 `list` is what still exists; this is what happened. Entries outlive their tasks:
 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
+the only thing that remembers a task landed at all. The last 1000 are kept
 (`logCapacity`) in `.git/arbor/log.jsonl`.
 
-### `arbor dev [--port 4269]`
+### `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.
+
+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.
+
+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,
+put a tunnel in front of it (Cloudflare Tunnel, Tailscale, ngrok) and name the
+tunnel's hostname in `--allow-hosts`:
 
-`list`, `show` and `log` in a browser, on `http://localhost:4269`, reloading
-themselves as tasks change. Read-only, and takes no lease.
+```bash
+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
+(Cloudflare Access, a Tailscale tailnet). Never expose it through a tunnel
+with no login in front.
 
 ### `arbor path [task]`
 
@@ -204,17 +405,47 @@ worktree it is already in.
 Refuses a task that does not exist, or one whose directory is gone, rather than
 printing a path you cannot `cd` into.
 
-### `arbor escalate <reason> [--task <name>]`
+### `arbor escalate <reason> [--task <name>] [--review]`
 
 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.
 
+`--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.
+
 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
 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>`
+
+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.
+
+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.
+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.
+
+`--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
+go when the todo does.
+
 ### `arbor retry <task>`
 
 Grants an escalated task another `mergeRetryCount` merge attempts and puts it
@@ -240,15 +471,17 @@ 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.                                |
+| 6    | `lease_held`        | Another agent is driving this tree. For a reply from the page: answer that agent in its chat. |
 | 7    | `dirty`             | Uncommitted changes. Commit before merging.                       |
-| 8    | `not_found`         | No such task, or not run from a task worktree.                     |
+| 8    | `not_found`         | No such task, or not run from a task worktree; for a reply from the page, no such open question. |
 | 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.        |
+| 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. |
+| 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": ...}`,
 plus fields like `paths` for conflicts) and the human explanation on **stderr**.
@@ -271,7 +504,8 @@ export default defineConfig({
 	leaseStalenessMs: 90_000,
 	mergeRetryCount: 2,
 	removedCapacity: 50,            // removed names kept, so remove can say "already removed"
-	logCapacity: 200,               // entries `arbor log` keeps before the oldest fall off
+	logCapacity: 1000,              // entries `arbor log` keeps before the oldest fall off
+	todoStalenessMs: 2_592_000_000, // 30 days: past this, merge offers a todo for removal
 });
 ```
 

package/add.d.ts

@@ -2,15 +2,22 @@ import { type Logger } from "webappwiz/log";
 import type { Fs } from "webappwiz/system";
 import type { Config } from "./config.js";
 import type { Shell } from "./shell.js";
+import type { Todos } from "./todo.js";
 import type { WorktreeService } from "./worktree-service.js";
 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.
+     */
+    todo?: number;
 }
-export declare function add({ service, shell, config, log, fs, }: {
+export declare function add({ service, shell, config, log, fs, todos, }: {
     service: WorktreeService;
     shell: Shell;
     config: Config;
     log: Logger;
     fs: Fs;
-}, task: string, { base }?: AddOptions): Promise<void>;
+    todos: Todos;
+}, task: string, { base, todo: id }?: AddOptions): Promise<void>;

package/attachments.d.ts

@@ -0,0 +1,36 @@
+import { type IdProvider } from "webappwiz/id";
+import type { Fs, Ps } from "webappwiz/system";
+/** A file handed over, as bytes so a pasted image needs no temp file. */
+export interface Attachment {
+    /** What it was called, kept in the stored name so the files stay apart. */
+    name: string;
+    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.
+ */
+export declare class Attachments {
+    readonly dir: string;
+    private readonly fs;
+    private readonly ids;
+    constructor(dir: string, fs: Fs, ids?: IdProvider);
+    /** Copies each file in, returning the absolute path each was stored at. */
+    store(files: Attachment[]): Promise<string[]>;
+    /** Whether `path` is one of this folder's files, and not a way out of it. */
+    owns(path: string): boolean;
+    /** Deletes the files given that are this folder's; others are left alone. */
+    remove(paths: string[]): Promise<void>;
+    /** Deletes the folder and everything in it. */
+    clear(): Promise<void>;
+}
+/**
+ * Reads files named on the command line, relative to the current directory or
+ * absolute, refusing the whole command over one that cannot be read.
+ */
+export declare function readFiles({ fs, ps }: {
+    fs: Fs;
+    ps: Ps;
+}, paths: string[]): Promise<Attachment[]>;

package/claim.d.ts

@@ -1,6 +1,10 @@
 import { type Logger } from "webappwiz/log";
 import type { WorktreeService } from "./worktree-service.js";
-/** The resume entry point: a fresh agent thread picking up existing work. */
+/**
+ * The resume entry point: a fresh agent thread picking up existing work. An
+ * escalated task goes back to `working`, since someone is on it again; its
+ * merge budget stays as it was, which only `retry` refills.
+ */
 export declare function claim({ service, log }: {
     service: WorktreeService;
     log: Logger;

package/config.d.ts

@@ -40,6 +40,12 @@ export interface Config {
     removedCapacity: number;
     /** How many entries `arbor log` keeps before the oldest fall off. */
     logCapacity: number;
+    /**
+     * How long a todo can wait before `merge` stops recommending it and offers
+     * it for removal instead: work deferred that long has usually been done
+     * some other way, or stopped mattering.
+     */
+    todoStalenessMs: number;
 }
 /**
  * Identity, for the types. `export default defineConfig({ ... })` in

package/dev.d.ts

@@ -3,6 +3,8 @@ 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. */
 export declare const DEFAULT_PORT = 4269;
@@ -12,23 +14,36 @@ export declare const PORT_SPAN = 20;
 export interface DevOptions {
     /** Where to listen; the port `--port` asked for, and the span above it. */
     ports?: PortProvider;
+    /**
+     * Host names besides this machine's own that the page may be reached by,
+     * like the hostname of a tunnel. Anything else is refused, which is what
+     * stops another site from reading the repo through a browser pointed at
+     * localhost. Who may use those names is the tunnel's business, not arbor's.
+     */
+    hosts?: string[];
 }
 /** A running server, and the one thing a caller ever wants to do with it. */
 export interface DevServer extends AsyncResource {
     port: number;
 }
 /**
- * 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.
+ * 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.
  */
-export declare function dev({ service, fs, journal, log, assets, }: {
+export declare function dev({ service, fs, journal, todos, replies, log, assets, }: {
     service: WorktreeService;
     fs: Fs;
     journal: Journal;
+    todos: Todos;
+    replies: Replies;
     log: Logger;
     assets: Assets;
-}, { ports }?: DevOptions): Promise<DevServer>;
+}, { ports, hosts }?: 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

package/escalate.d.ts

@@ -1,19 +1,28 @@
 import { type Logger } from "webappwiz/log";
-import type { Lock } from "webappwiz/system";
+import type { Fs, 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;
+    /**
+     * Ask a person to approve merging, rather than to answer questions: adds
+     * the question that asks it to the plan, with the reason as its detail.
+     * Refused while another question is unchecked.
+     */
+    review?: boolean;
 }
+/** The question a review asks. */
+export declare const REVIEW_SUBJECT = "\u2705 Ready to merge?";
 /**
  * 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
  * a decision, and that belongs to a human.
  */
-export declare function escalate({ service, git, lock, log, }: {
+export declare function escalate({ service, git, lock, log, fs, }: {
     service: WorktreeService;
     git: Git;
     lock: Lock;
     log: Logger;
-}, reason: string, cwd: string, { task }?: EscalateOptions): Promise<void>;
+    fs: Fs;
+}, reason: string, cwd: string, { task, review }?: EscalateOptions): Promise<void>;

package/exit.d.ts

@@ -15,6 +15,8 @@ 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;
 /**

package/git.d.ts

@@ -41,6 +41,18 @@ export declare class Git {
         added: number;
         removed: number;
     } | null>;
+    /**
+     * Every path `branch` touches since it left `trunk`, plus what is still
+     * uncommitted in `worktree` when there is one: an agent mid-task has usually
+     * committed nothing yet, and its edits are the overlap that matters most.
+     */
+    changedFiles(trunk: string, branch: string, worktree: string | null): Promise<string[] | null>;
+    /**
+     * Every path a person might point an agent at in the tree at `cwd`: the
+     * files git tracks, the new ones it does not ignore, and each directory
+     * above them, which ends in `/`. Sorted, relative to the tree's root.
+     */
+    paths(cwd: string): Promise<string[]>;
     rebase(cwd: string, onto: string): Promise<GitResult>;
     resetHard(cwd: string, commit: string): Promise<GitResult>;
     checkout(branch: string): Promise<GitResult>;

package/inbox.d.ts

@@ -0,0 +1,80 @@
+import { type Logger } from "webappwiz/log";
+import type { Fs } from "webappwiz/system";
+import { type Question } from "./plan.js";
+import { type Replies, type ReplyState } from "./replies.js";
+import type { WorktreeStatus } from "./worktree.js";
+import type { WorktreeService } from "./worktree-service.js";
+/** A question, with the task that asked it and where it stands. */
+export interface OpenQuestion extends Question {
+    task: string;
+    status: WorktreeStatus;
+    /**
+     * `held` means the asking agent is in a live session: answer it there,
+     * since `arbor reply` refuses a tree someone is driving.
+     */
+    lease: "held" | "stale" | "none";
+    /**
+     * A reply or follow-up given and waiting for the agent to claim it, or
+     * null.
+     */
+    pending: ReplyState | null;
+    /**
+     * Where it stands. `open` waits on a person. `waiting` has a reply its
+     * agent has yet to read, which can still be edited. `editing` is held by
+     * someone changing it. `read` has been claimed by its agent, which has yet
+     * to check it off. `done` is checked off. A follow-up takes a `read` or
+     * `done` question back to `waiting`.
+     */
+    state: QuestionState;
+}
+export type QuestionState = "open" | "waiting" | "editing" | "read" | "done";
+export interface Inbox {
+    /**
+     * Questions, by task name and then in the order each plan lists them.
+     * Only the unanswered ones unless the others were asked for too.
+     */
+    questions: OpenQuestion[];
+    /** How many unchecked questions have a reply their agent has yet to act on. */
+    replied: number;
+}
+export interface InboxOptions {
+    /**
+     * Keep the questions replied to but not yet checked off, to change or add
+     * to an answer. Without it, a question leaves the inbox once it is answered.
+     */
+    replied?: boolean;
+    /** Keep the questions checked off too, to follow one up. */
+    done?: boolean;
+}
+/**
+ * Every question still waiting on a person, across all tasks: the unchecked
+ * items under each worktree's `## Blocked` with no reply yet, and with
+ * `replied` also those answered but not yet checked off, whether their agent
+ * has read the reply or not.
+ *
+ * Returns data rather than printing it, so the CLI and the dev server show the
+ * same inbox.
+ */
+export declare function openQuestions({ service, fs, replies, }: {
+    service: WorktreeService;
+    fs: Fs;
+    replies: Replies;
+}, { replied, done }?: InboxOptions): Promise<Inbox>;
+export interface InboxPrintOptions extends InboxOptions {
+    /** Print the inbox as JSON instead of a listing. */
+    json?: boolean;
+}
+/** `arbor inbox`: the open questions, grouped by task. */
+export declare function inbox(deps: {
+    service: WorktreeService;
+    fs: Fs;
+    replies: Replies;
+    log: Logger;
+}, { json, replied }?: InboxPrintOptions): Promise<void>;
+/**
+ * One question as the inbox prints it: `Q9 subject`, its body and choices
+ * under it, then the reply the agent has yet to act on, if there is one.
+ */
+export declare function formatQuestion(question: Question & {
+    pending?: ReplyState | null;
+}): string[];