@webappwiz/arbor 0.0.25 → 0.0.27

package/merge.d.ts

@@ -2,7 +2,6 @@ import { type Logger } from "webappwiz/log";
 import type { Fs, Lock } from "webappwiz/system";
 import type { Config } from "./config.js";
 import type { Git } from "./git.js";
-import type { Replies } from "./replies.js";
 import type { Shell } from "./shell.js";
 import { type Todos } from "./todo.js";
 import type { WorktreeService } from "./worktree-service.js";
@@ -13,7 +12,7 @@ import type { WorktreeService } from "./worktree-service.js";
  * `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, todos, replies, fs, }: {
+export declare function merge({ service, git, lock, shell, config, log, todos, fs, }: {
     service: WorktreeService;
     git: Git;
     lock: Lock;
@@ -21,6 +20,5 @@ export declare function merge({ service, git, lock, shell, config, log, todos, r
     config: Config;
     log: Logger;
     todos: Todos;
-    replies: Replies;
     fs: Fs;
 }, cwd: string): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webappwiz/arbor",
-	"version": "0.0.25",
+	"version": "0.0.27",
 	"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.25",
+		"webappwiz": "^0.0.27",
 		"zod": "^4.4.3"
 	},
 	"main": "./index.js",

package/plan.d.ts

@@ -7,12 +7,12 @@ export declare const PLAN_FILE = "ARBOR.md";
  */
 export declare function plannedFiles(text: string): string[];
 /**
- * One `- [ ] Q9.` item under `## Blocked`: something only a person can do.
+ * One `- [ ] 9.` item under `## Blocked`: something only a person can do.
  * The item's line is its subject; lines indented under it are its body, and
  * `- (a) ...` or `- [a] ...` lines among them are the answers it offers.
  */
 export interface Question {
-    /** As the plan numbers it, `Q9`: the name a reply goes by. */
+    /** As the plan numbers it, `9`: the name a reply goes by. */
     number: string;
     /** Checked off, which the agent does once it has acted on the reply. */
     done: boolean;
@@ -41,10 +41,6 @@ export interface Question {
      * `- [a]` choices, where it picks all that apply. Null without choices.
      */
     pick: "one" | "any" | null;
-    /** The keys of the choices the reply picked, in the order offered. */
-    chosen: string[];
-    /** The absolute paths of the images its text and body show. */
-    images: string[];
 }
 /** One answer a question offers: `- (b) Migrate on next login`. */
 export interface Choice {
@@ -58,31 +54,6 @@ export interface Choice {
  * answer is one line, written by `arbor reply` or by hand after the arrow.
  */
 export declare function questions(text: string): Question[];
-/**
- * How a reply reads in the plan: each pick spelled out, so the agent needs
- * nothing but the line, then any words after it. `a (Email), c (Push): and
- * log it`.
- */
-export declare function replyLine(asked: Question, { choices, text }: {
-    choices?: string[];
-    text: string;
-}): string;
-/**
- * The plan with `reply` written onto that question's line, in place of any
- * earlier one, or with no reply there at all when it is null. The checkbox is left alone: checking it off is the agent's
- * word that it has acted on the answer. Null when the plan has no such
- * question.
- */
-export declare function withReply(text: string, number: string, 
-/** Null takes the reply off, leaving the question as it was asked. */
-reply: string | null): string | null;
-/**
- * The plan with `reply` added under a question already answered, as an
- * indented `→ ` line after everything else under it, and the question
- * unchecked: whatever the agent did about the answer, it has more to read.
- * Null when the plan has no such question.
- */
-export declare function withFollowUp(text: string, number: string, reply: string): string | null;
 /**
  * The plan with a new open question at the end of `## Blocked`, the section
  * made if missing, numbered after the highest there. Returns the plan and
@@ -93,8 +64,8 @@ export declare function withQuestion(text: string, subject: string, body?: strin
     number: string;
 };
 /**
- * A question's number however a person typed it: `Q9`, `q9`, `9` and `Q9.`
- * all mean `Q9`. Null for anything that is not a number at all.
+ * A question's number however a person typed it: `9`, `9.`, `Q9` and `q9:`
+ * all mean `9`. Null for anything that is not a number at all.
  */
 export declare function questionNumber(raw: string): string | null;
 export interface PlanOptions {

package/repository.d.ts

@@ -3,7 +3,6 @@ import { type Fs, type Lock } from "webappwiz/system";
 import type { Config } from "./config.js";
 import { Git } from "./git.js";
 import { Journal } from "./journal.js";
-import { Replies } from "./replies.js";
 import { Shell } from "./shell.js";
 import { Todos } from "./todo.js";
 import { WorktreeService } from "./worktree-service.js";
@@ -16,7 +15,6 @@ export interface Repository {
     shell: Shell;
     journal: Journal;
     todos: Todos;
-    replies: Replies;
 }
 /**
  * Runs the action against the repository `cwd` sits in, and refuses to run it

package/show.d.ts

@@ -15,7 +15,7 @@ export interface Details {
     age: string | null;
     escalation: string | null;
     /**
-     * While escalated to be approved, the question that asks for it, `Q4`;
+     * While escalated to be approved, the question that asks for it, `4`;
      * null otherwise.
      */
     review: string | null;

package/snapshot.d.ts

@@ -1,19 +1,16 @@
 import type { Fs } from "webappwiz/system";
-import { type Inbox } from "./inbox.js";
-import type { Replies } from "./replies.js";
 import { type Details } from "./show.js";
 import type { TodoState, Todos } from "./todo.js";
 import type { WorktreeService } from "./worktree-service.js";
 /**
- * Everything one page shows: `list` and `show` for each task, every question
- * each one asked however it stands, and `todo list`.
+ * Everything one page shows: `todo list`, and `list` and `show` for each
+ * task.
  */
 export interface Snapshot {
     /** The repository's directory name, so a page among many says whose it is. */
     repo: string;
     /** Past this age a todo is offered for removal rather than recommended. */
     todoStalenessMs: number;
-    inbox: Inbox;
     todos: TodoState[];
     tasks: Details[];
 }
@@ -21,10 +18,9 @@ export interface Snapshot {
  * Reads the whole repo the way the CLI's read commands do. Takes no lease, so
  * the page can sit open on a live tree without disturbing the agent in it.
  */
-export declare function snapshot({ service, todos, replies, fs, }: {
+export declare function snapshot({ service, todos, fs, }: {
     service: WorktreeService;
     todos: Todos;
-    replies: Replies;
     fs: Fs;
 }): Promise<Snapshot>;
 /**
@@ -32,4 +28,4 @@ export declare function snapshot({ service, todos, replies, fs, }: {
  * `age` ticks every minute, and hashing it would push to every open page for
  * nothing.
  */
-export declare function fingerprint({ inbox, todos, tasks }: Snapshot): string;
+export declare function fingerprint({ todos, tasks }: Snapshot): string;

package/todo.d.ts

@@ -5,7 +5,12 @@ import { type Attachment, Attachments } from "./attachments.js";
 /** What a todo is on disk: one file apiece, so two agents never rewrite one. */
 export interface TodoState {
     id: number;
+    /** What is left to do, in a line. */
+    subject: string;
+    /** Whatever more there is to say about it, or empty when the line is enough. */
     text: string;
+    /** Where it stands in the list, 1 at the top: the one to pick up first. */
+    position: number;
     /** The task it came up in, or null when a person added it from the main tree. */
     from: string | null;
     createdAt: string;
@@ -14,15 +19,27 @@ export interface TodoState {
     /** Absolute paths of the files attached, in `todos/<id>/`. */
     files: string[];
 }
-/** A todo's words and files changed: new ones added, some of the old kept. */
+/** A todo's words, place or files changed: new ones added, some of the old kept. */
 export interface TodoChange {
-    /** New words; the old ones stay when this is absent. */
+    /** A new line; the old one stays when this is absent. */
+    subject?: string;
+    /** New detail, empty for none; the old stays when this is absent. */
     text?: string;
+    /** Where to move it in the list; it stays put when this is absent. */
+    position?: number;
     /** Files to add. */
     files?: Attachment[];
     /** The paths of the files it has now to keep; absent keeps them all. */
     keep?: string[];
 }
+/** What a new todo has besides its subject, all of it optional. */
+export interface TodoNew {
+    /** Whatever more there is to say about it. */
+    text?: string;
+    files?: Attachment[];
+    /** Where it goes in the list, pushing those from there down; the bottom by default. */
+    position?: number;
+}
 /**
  * Work deferred for later: what an agent notes when something outside its
  * task comes up, so it can move on instead of growing the task. Kept under the
@@ -34,7 +51,9 @@ export declare class Todo {
     readonly state: TodoState;
     constructor(todos: Todos, state: TodoState);
     get id(): number;
+    get subject(): string;
     get text(): string;
+    get position(): number;
     get from(): string | null;
     get takenBy(): string | null;
     get createdAt(): Date;
@@ -47,10 +66,10 @@ export declare class Todo {
     get files(): string[];
     get attachments(): Attachments;
     /**
-     * Says what is left to do in other words, or with other files, keeping its
-     * id and history.
+     * Says what is left to do in other words, with other files, or higher or
+     * lower in the list, keeping its id and history.
      */
-    update({ text, files, keep }: TodoChange): Promise<Todo>;
+    update({ subject, text, position, files, keep, }: TodoChange): Promise<Todo>;
     remove(): Promise<void>;
 }
 /** What `Todos` is stored through; the real filesystem by default. */
@@ -62,27 +81,62 @@ export interface TodosOptions {
 /** Every todo in the repo, one JSON file each under `.git/arbor/todos`. */
 export declare class Todos {
     readonly dir: string;
-    /** Held while numbering a new todo, so two agents never share an id. */
+    /**
+     * Held while numbering a new todo, so two agents never share an id, and
+     * while writing one, so a move renumbering the rest never loses to a
+     * write of a position it just changed.
+     */
     private readonly lock;
     private readonly fs;
     private readonly ids;
     constructor(dir: string, 
-    /** Held while numbering a new todo, so two agents never share an id. */
+    /**
+     * Held while numbering a new todo, so two agents never share an id, and
+     * while writing one, so a move renumbering the rest never loses to a
+     * write of a position it just changed.
+     */
     lock: Lock, opts?: TodosOptions);
     /** Where a todo's files live, beside its record. */
     attachments(id: number): Attachments;
     /** Whether `path` is a file some todo holds, and not a way out of here. */
     owns(path: string): boolean;
-    add(text: string, from: string | null, files?: Attachment[]): Promise<Todo>;
-    /** Oldest first. A file that will not parse is skipped rather than fatal. */
+    add(subject: string, from: string | null, { text, files, position }?: TodoNew): Promise<Todo>;
+    /**
+     * Top of the list first. A file that will not parse is skipped rather than
+     * fatal, and positions are counted again from 1 as they are read, so a
+     * gap or a tie left by a crash, or a todo saved before they had any (it
+     * goes below those that do, oldest first), never shows.
+     */
     all(): Promise<Todo[]>;
     find(id: number): Promise<Todo>;
     /** The todos `task` has taken; what a merge or remove settles. */
     takenBy(task: string): Promise<Todo[]>;
+    /**
+     * Puts a todo at `position`, 1 at the top, past the bottom meaning the
+     * bottom, and numbers the rest around it.
+     */
+    move(id: number, position: number): Promise<Todo>;
+    /**
+     * @internal Rewrites one todo as it stands on disk now, under the lock, so
+     * a change to its words or who has it never undoes a move made meanwhile.
+     */
+    revise(id: number, change: (state: TodoState) => TodoState): Promise<Todo>;
     /** @internal Writes one todo. Rename makes the swap atomic for readers. */
     save(state: TodoState): Promise<Todo>;
-    /** @internal */
+    /** @internal Removes one, moving those below it up to close the gap. */
     delete(id: number): Promise<void>;
+    private locked;
+    /** One todo as it stands on disk; call it under the lock. */
+    private state;
+    /**
+     * Slots `state` in at `position` among the rest and saves whichever moved.
+     * Call it under the lock.
+     */
+    private place;
+    /** Every todo in list order, with the positions it has on disk. */
+    private stored;
+    /** Saves each todo in `order` whose position on disk is not its place there. */
+    private renumber;
     private path;
     private lastId;
     private read;
@@ -95,9 +149,10 @@ export interface Recommendation {
     stale: Todo[];
 }
 /**
- * Which todo to take up after `task`: its own first, since whoever just
- * finished it knows that context best, then the longest waiting. Todos past
- * `staleness` are never recommended, only offered for removal.
+ * Which todo to take up after `task`: one that came up in it first, since
+ * whoever just finished it knows that context best, then the open one highest
+ * on the list, which is how whoever keeps the list says what matters most.
+ * Todos past `staleness` are never recommended, only offered for removal.
  */
 export declare function recommend(todos: Todos, task: string | null, staleness: number): Promise<Recommendation>;
 /** The lines `merge` ends with, or none when there is nothing to say. */
@@ -110,19 +165,38 @@ export interface TodoFileOptions {
     /** Files to attach, relative to the current directory or absolute. */
     files?: string[];
 }
+export interface TodoAddOptions extends TodoFileOptions {
+    /** Whatever more there is to say than the subject. */
+    text?: string;
+    /** Where it goes in the list, 1 at the top; the bottom by default. */
+    position?: number;
+}
 export declare function todoAdd(deps: {
     todos: Todos;
     log: Logger;
     fs: Fs;
     ps: Ps;
-}, text: string, from: string | null, { files }?: TodoFileOptions): Promise<Todo>;
+}, subject: string, from: string | null, { text, files, position }?: TodoAddOptions): Promise<Todo>;
 export declare function todoList({ todos, log }: {
     todos: Todos;
     log: Logger;
 }, { json }?: TodoListOptions): Promise<void>;
+export interface TodoShowOptions {
+    /** Print the todo as JSON instead of prose. */
+    json?: boolean;
+}
+/** One todo in full: what `todo list` shows of it, its files, and its detail. */
+export declare function todoShow({ todos, log }: {
+    todos: Todos;
+    log: Logger;
+}, id: number, { json }?: TodoShowOptions): Promise<void>;
 export interface TodoUpdateOptions extends TodoFileOptions {
-    /** New words; the old ones stay when this is absent or empty. */
+    /** A new line; the old one stays when this is absent or empty. */
+    subject?: string;
+    /** New detail; the old stays when this is absent or empty. */
     text?: string;
+    /** Where to move it in the list, 1 at the top; it stays put when absent. */
+    position?: number;
     /** Attached files to drop, by path or by the name they were stored under. */
     removeFiles?: string[];
 }
@@ -131,7 +205,7 @@ export declare function todoUpdate(deps: {
     log: Logger;
     fs: Fs;
     ps: Ps;
-}, id: number, { text, files, removeFiles }?: TodoUpdateOptions): Promise<Todo>;
+}, id: number, { subject, text, position, 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

package/wait.d.ts

@@ -1,7 +1,5 @@
 import { type Logger } from "webappwiz/log";
-import type { Fs } from "webappwiz/system";
 import { Duration } from "webappwiz/time";
-import type { Replies } from "./replies.js";
 import type { WorktreeService } from "./worktree-service.js";
 /** How long `wait` gives a task before handing the wait back to its caller. */
 export declare const DEFAULT_TIMEOUT: Duration;
@@ -10,11 +8,6 @@ export interface WaitOptions {
     timeout?: Duration;
     /** How long between reads of the record; the default suits a human's patience. */
     poll?: Duration;
-    /**
-     * Wait for the task's open questions to be answered instead of for the task
-     * to stop moving: what an agent that escalated waits on.
-     */
-    answered?: boolean;
 }
 /**
  * Blocks until a task stops moving: merged or removed (both leave the name
@@ -22,15 +15,8 @@ export interface WaitOptions {
  * own work overlaps this one's and would rather rebase onto the result than
  * against it, which is why the timeout is short enough to come back and think
  * again rather than block a session for an afternoon.
- *
- * With `answered` it blocks instead until every open question under the
- * task's `## Blocked` has a reply nobody is still editing, then claims them,
- * which writes them into the plan, and prints them: the agent that escalated
- * waits for its human this way, rather than polling its own plan.
  */
-export declare function wait({ service, log, fs, replies, }: {
+export declare function wait({ service, log }: {
     service: WorktreeService;
     log: Logger;
-    fs: Fs;
-    replies: Replies;
-}, task: string, { timeout, poll, answered, }?: WaitOptions): Promise<void>;
+}, task: string, { timeout, poll }?: WaitOptions): Promise<void>;

package/worktree-service.d.ts

@@ -21,7 +21,6 @@ export declare class WorktreeService {
     readonly config: Config;
     private readonly tasksDir;
     private readonly removedDir;
-    private readonly repliesDir;
     private readonly fs;
     readonly ps: Ps;
     constructor(git: Git, config: Config, arborDir: string, opts?: WorktreeServiceOptions);
@@ -32,12 +31,6 @@ export declare class WorktreeService {
     branchFor(task: string): string;
     taskFor(branch: string): string | null;
     recordPath(task: string): string;
-    /**
-     * Where a task's replies wait to be read, and the files attached to them.
-     * Under `.git/arbor` rather than in the worktree, so they are never
-     * committed and every tree can open them, and gone with the task.
-     */
-    repliesPath(task: string): string;
     /** Always answers; the returned worktree's status says what was found. */
     find(task: string): Promise<Worktree>;
     list(): Promise<Worktree[]>;

package/worktree.d.ts

@@ -13,7 +13,7 @@ export interface Escalation {
     at: string;
     /**
      * For a task handed over to be approved rather than to answer questions,
-     * the question in its plan that asks for the approval, `Q4`.
+     * the question in its plan that asks for the approval, `4`.
      */
     review?: string;
 }

package/inbox.d.ts

@@ -1,80 +0,0 @@
-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[];

package/replies.d.ts

@@ -1,81 +0,0 @@
-import { type IdProvider } from "webappwiz/id";
-import type { Fs, Lock } from "webappwiz/system";
-import { Attachments } from "./attachments.js";
-import { type Question } from "./plan.js";
-/** How long a person opening a reply holds it before it lapses unsaved. */
-export declare const EDIT_MS: number;
-/**
- * A reply a person gave that its agent has not read yet. It waits here, out
- * of the plan, so the agent sees nothing half-written: the agent claims it to
- * read it, which writes it into the plan and ends any chance to edit it.
- */
-export interface ReplyState {
-    task: string;
-    /** `Q2`. */
-    question: string;
-    /** The keys of the choices picked. */
-    choices: string[];
-    /** Words, alongside the picks or instead of them. */
-    text: string;
-    /** Absolute paths of the files attached, in `replies/<task>/Q2/`. */
-    files: string[];
-    repliedAt: string;
-    /**
-     * While a person has it open to edit, when that hold lapses; null when
-     * nobody does. An agent reads nothing held, so it never sees a reply
-     * mid-change.
-     */
-    editingUntil: string | null;
-}
-/** One reply waiting to be read, with what can be done to it. */
-export declare class PendingReply {
-    private readonly replies;
-    readonly state: ReplyState;
-    constructor(replies: Replies, state: ReplyState);
-    /** Held by a person right now. */
-    get editing(): boolean;
-    get attachments(): Attachments;
-    /** Holds it for a person to edit, for `EDIT_MS` from now. */
-    hold(): Promise<PendingReply>;
-    release(): Promise<PendingReply>;
-    /** Drops the record. Its files go too unless `keepFiles`, as a claim wants. */
-    remove({ keepFiles }?: {
-        keepFiles?: boolean | undefined;
-    }): Promise<void>;
-}
-/**
- * Every reply waiting to be read, one JSON file each at
- * `.git/arbor/replies/<task>/<question>.json`, its files beside it. Removing a
- * task takes its folder with it.
- */
-export declare class Replies {
-    readonly dir: string;
-    /** Held across a read and the write it decides, so a claim and an edit never cross. */
-    private readonly lock;
-    private readonly fs;
-    private readonly ids;
-    constructor(dir: string, 
-    /** Held across a read and the write it decides, so a claim and an edit never cross. */
-    lock: Lock, fs: Fs, { ids }?: {
-        ids?: IdProvider;
-    });
-    /** Runs `work` holding the lock every write to a reply goes through. */
-    locked<T>(work: () => Promise<T>): Promise<T>;
-    find(task: string, question: string): Promise<PendingReply | null>;
-    /** A task's waiting replies, by question number. */
-    forTask(task: string): Promise<PendingReply[]>;
-    attachments(task: string, question: string): Attachments;
-    /** Whether `path` is a file some reply holds, and not a way out of here. */
-    owns(path: string): boolean;
-    /** @internal Writes one reply. Rename makes the swap atomic for readers. */
-    save(state: ReplyState): Promise<PendingReply>;
-    /** @internal */
-    delete(task: string, question: string): Promise<void>;
-    private path;
-    private read;
-}
-/**
- * A reply as its line in the plan reads once claimed: the picks spelled out,
- * the words, then each file's path, so the line alone is the whole answer.
- */
-export declare function replyText(asked: Question, reply: ReplyState): string;