@webappwiz/arbor 0.0.7 → 0.0.9

package/README.md

@@ -131,6 +131,23 @@ prescribes (`# <task>`, `## Goal`, `## Next` with something unchecked in it, a
 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]`
+
+Blocks until a task stops moving, then prints where it stopped.
+
+Moving means `working` or `merging`. Everything else is somewhere it stays
+without a person: `escalated` (printed with its reason), `removed` (merged or
+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
+back, rather than a session that blocks all afternoon on a tree nobody is
+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.
+
 ### `arbor log [--count 20] [--json]`
 
 The last N things done here (`add`, `claim`, `merge`, `rm`, `escalate`,
@@ -221,6 +238,7 @@ The agent's control flow runs on these.
 | 11   | `orphaned`          | Record with no worktree. `arbor rm` it.                         |
 | 12   | `merge_failed`      | Trunk could not be fast-forwarded (usually a dirty main worktree). |
 | 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.        |
 
 Every failure prints a one-line JSON object on **stdout** (`{"reason": ...}`,
 plus fields like `paths` for conflicts) and the human explanation on **stderr**.

package/config.d.ts

@@ -1,49 +1,26 @@
-export interface Config {
-    /**
-     * The integration branch name. `merge` rebases a task onto this branch and
-     * then fast-forwards it to the result; new worktrees start from it.
-     */
+import { type InferConfig } from "webappwiz/config";
+/**
+ * The settings arbor runs a repo with. `loadConfig` builds one; everything a
+ * command needs comes off it with `get`.
+ */
+export declare const CONFIG_FACTORY: import("webappwiz/config").ConfigFactory<{
     trunk: string;
-    /** Directory holding one worktree per task, a sibling of the repo. */
     worktreeRoot: string;
-    /** Command run by `add` in the new worktree, via `sh -c`. */
     postCheckout: string | null;
-    /**
-     * Command run by `merge` after the rebase, before `preMerge`, via `sh -c`.
-     * A rebase can bring in a dependency the worktree has never installed, and
-     * whatever `preMerge` runs needs it.
-     */
     postRewrite: string | null;
-    /**
-     * Command run by `merge` after the rebase, via `sh -c`. The last gate before
-     * the branch lands: a nonzero exit rolls the branch back and leaves the base
-     * untouched. Tests are the obvious thing to put here, but arbor has no
-     * opinion; a repo with nothing to run leaves it null and merges on a green
-     * rebase alone.
-     */
     preMerge: string | null;
-    /**
-     * Command run by `merge` in the main tree after the base fast-forwards, via
-     * `sh -c`. The branch has already landed and the worktree is gone: a nonzero
-     * exit reports the failure but rolls nothing back.
-     */
     postMerge: string | null;
-    /** How long since its last heartbeat before a task's lease is up for grabs. */
     leaseStalenessMs: number;
-    /** Failed `merge` attempts a task gets before it must escalate or be removed. */
     mergeRetryCount: number;
-    /**
-     * How many removed task names to keep, so `rm` can say "already removed"
-     * rather than "never existed". A flat cap with no age policy: losing the
-     * oldest costs a nicer message and nothing else.
-     */
     removedCapacity: number;
-    /** How many entries `arbor log` keeps before the oldest fall off. */
     logCapacity: number;
-}
+}>;
+export type Config = InferConfig<typeof CONFIG_FACTORY>;
+/** The plain shape behind a `Config`: what a config file exports a part of. */
+export type ConfigRecord = ReturnType<Config["toRecord"]>;
 /**
  * Identity, for the types. `export default defineConfig({ ... })` in
  * `arbor.config.ts` gets the key names and their types checked, and completion
  * while writing it; a bare object literal gets neither.
  */
-export declare function defineConfig(config: Partial<Config>): Partial<Config>;
+export declare function defineConfig(config: Partial<ConfigRecord>): Partial<ConfigRecord>;

package/config.js

@@ -1,7 +1,8 @@
-// config.ts
-function defineConfig(config) {
-  return config;
-}
-export {
+import {
+  CONFIG_FACTORY,
   defineConfig
+} from "./index-84xjmns8.js";
+export {
+  defineConfig,
+  CONFIG_FACTORY
 };

package/dev.d.ts

@@ -1,10 +1,24 @@
 import type { HttpServer } from "webappwiz/http";
 import type { Logger } from "webappwiz/log";
-import type { Fs } from "webappwiz/system";
+import { type Fs, type PortProvider } from "webappwiz/system";
 import type { Assets } from "./dev/assets.js";
 import type { Journal } from "./journal.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;
+/** How far above the port asked for `dev` will look before giving up. */
+export declare const PORT_SPAN = 20;
+/**
+ * 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
+ * assertion `OpenPortProvider` would raise for a bug in here.
+ */
+export declare function devPorts(from: number): PortProvider;
+/** What `dev` lets a caller choose. */
+export interface DevOptions {
+    /** Where to listen; the port `--port` asked for, and the span above it. */
+    ports?: PortProvider;
+}
 /** A running server, and the one thing a caller ever wants to do with it. */
 export interface DevServer {
     port: number;
@@ -26,6 +40,4 @@ export declare function dev({ service, fs, journal, log, http, assets, }: {
     log: Logger;
     http: HttpServer;
     assets: Assets;
-}, { port }?: {
-    port?: number | undefined;
-}): Promise<DevServer>;
+}, { ports }?: DevOptions): Promise<DevServer>;

package/exit.d.ts

@@ -14,6 +14,7 @@ export declare const EXIT: {
     readonly orphaned: 11;
     readonly merge_failed: 12;
     readonly already_removed: 13;
+    readonly timeout: 14;
 };
 export type Reason = keyof typeof EXIT;
 /**

package/index-84xjmns8.js

@@ -0,0 +1,20 @@
+// config.ts
+import { Config as WizConfig } from "webappwiz/config";
+import { t } from "webappwiz/t";
+var CONFIG_FACTORY = WizConfig.factory({
+  trunk: t.string(),
+  worktreeRoot: t.string(),
+  postCheckout: t.nullable(t.string()),
+  postRewrite: t.nullable(t.string()),
+  preMerge: t.nullable(t.string()),
+  postMerge: t.nullable(t.string()),
+  leaseStalenessMs: t.number(),
+  mergeRetryCount: t.number(),
+  removedCapacity: t.number(),
+  logCapacity: t.number()
+});
+function defineConfig(config) {
+  return config;
+}
+
+export { CONFIG_FACTORY, defineConfig };

package/index.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
 // @bun
+import {
+  CONFIG_FACTORY
+} from "./index-84xjmns8.js";
 
 // index.ts
 import { BunHttpServer } from "webappwiz/http/bun";
@@ -8,6 +11,7 @@ import { NodeFs as NodeFs7 } from "webappwiz/system";
 // arbor.ts
 import { cli } from "webappwiz/cmd";
 import { t } from "webappwiz/t";
+import { Duration as Duration3 } from "webappwiz/time";
 
 // add.ts
 import { color } from "webappwiz/log";
@@ -27,7 +31,8 @@ var EXIT = {
   exists: 10,
   orphaned: 11,
   merge_failed: 12,
-  already_removed: 13
+  already_removed: 13,
+  timeout: 14
 };
 
 class Exit extends Error {
@@ -60,14 +65,14 @@ function exits() {
 // add.ts
 var NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var PLAN_FILE = "ARBOR.md";
-var PLAN = (task) => new MarkdownWriter().heading(1, task).heading(2, "Goal").heading(2, "Next").checklist("fill in Goal and list the steps here as `- [ ]` items").toString();
+var PLAN = (task) => new MarkdownWriter().heading(1, task).heading(2, "Goal").heading(2, "Files").heading(2, "Next").checklist("fill in Goal and list the steps here as `- [ ]` items").toString();
 async function add({
   service,
   shell,
   config,
   log,
   fs
-}, task, { base = config.trunk } = {}) {
+}, task, { base = config.get("trunk") } = {}) {
   if (!NAME.test(task)) {
     fail("usage", `invalid task name '${task}': use lowercase letters, digits and dashes`, { task });
   }
@@ -83,7 +88,7 @@ async function add({
   }
   const added = await service.add(task, { base });
   if (added.code !== 0) {
-    const missingTrunk = base === config.trunk && !await service.git.branchExists(base);
+    const missingTrunk = base === config.get("trunk") && !await service.git.branchExists(base);
     fail("usage", missingTrunk ? `trunk '${base}' is not a branch in this repo: set \`trunk\` in arbor.config.ts` : `git worktree add failed: ${added.stderr}`, { task });
   }
   const worktree = await (await service.find(task)).take({ base });
@@ -97,13 +102,14 @@ ${PLAN_FILE}
 `.trimStart());
   }
   await fs.write(`${worktree.path}/${PLAN_FILE}`, PLAN(task));
-  if (config.postCheckout) {
-    const { exitCode } = await shell.stream(config.postCheckout, {
+  const postCheckout = config.get("postCheckout");
+  if (postCheckout) {
+    const { exitCode } = await shell.stream(postCheckout, {
       cwd: worktree.path,
       env: {
         ARBOR_TASK: task,
         ARBOR_WORKTREE: worktree.path,
-        ARBOR_TRUNK: config.trunk
+        ARBOR_TRUNK: config.get("trunk")
       }
     });
     if (exitCode !== 0) {
@@ -159,6 +165,10 @@ ${changes.map((change) => `    ${change}`).join(`
 }
 
 // dev.ts
+import {
+  MAX_PORT,
+  OpenPortProvider
+} from "webappwiz/system";
 import { Duration } from "webappwiz/time";
 
 // snapshot.ts
@@ -219,7 +229,7 @@ import { NodeFs } from "webappwiz/system";
 // plan.ts
 import { Markdown } from "webappwiz/md";
 var SECTIONS = ["Goal", "Files", "Done", "Next", "Notes", "Blocked"];
-var REQUIRED = ["Goal", "Next"];
+var REQUIRED = ["Goal", "Files", "Next"];
 var UNCHECKED = /^[ \t]*- \[ \]/m;
 function checkPlan(text, { task, escalated = false }) {
   const md = Markdown.parse(text);
@@ -236,6 +246,9 @@ function checkPlan(text, { task, escalated = false }) {
   if (section("Goal") === "") {
     problems.push("## Goal is empty: say in a line or two what done means");
   }
+  if (section("Files") === "") {
+    problems.push("## Files is empty: list the file paths you plan to touch");
+  }
   const next = section("Next");
   if (next !== null && !UNCHECKED.test(next)) {
     problems.push("## Next has no `- [ ]` item: say what the next step is");
@@ -358,6 +371,15 @@ function fingerprint({ tasks, entries }) {
 
 // dev.ts
 var DEFAULT_PORT = 4269;
+var PORT_SPAN = 20;
+function devPorts(from) {
+  if (!Number.isInteger(from) || from < 0 || from > MAX_PORT) {
+    fail("usage", `invalid port '${from}': use a whole number 0 to ${MAX_PORT}`, {
+      port: from
+    });
+  }
+  return OpenPortProvider.span({ from, span: PORT_SPAN });
+}
 var POLL_MS = 2000;
 async function dev({
   service,
@@ -366,7 +388,7 @@ async function dev({
   log: log2,
   http,
   assets
-}, { port = DEFAULT_PORT } = {}) {
+}, { ports = devPorts(DEFAULT_PORT) } = {}) {
   const open = new Set;
   const encoder = new TextEncoder;
   let last = fingerprint(await snapshot(service, journal, { fs }));
@@ -428,7 +450,7 @@ async function dev({
       default:
         return new Response("not found", { status: 404 });
     }
-  }, { port, idleTimeout: Duration.zero() });
+  }, { port: await ports.get(), idleTimeout: Duration.zero() });
   log2.info(`arbor dev on http://localhost:${listening.port}`);
   return {
     port: listening.port,
@@ -560,8 +582,8 @@ async function merge({
   if (dirty.length > 0) {
     fail("dirty", `'${task}' has uncommitted changes: commit them before merging`, { task, paths: dirty });
   }
-  if (worktree.mergeAttempts >= config.mergeRetryCount) {
-    fail("budget_exhausted", `'${task}' has used its ${config.mergeRetryCount} merge attempts: run \`arbor escalate <reason>\`, and a human can grant another ${config.mergeRetryCount} with \`arbor retry ${task}\`; or \`arbor rm ${task}\` and start over against current ${base}`, { task, mergeAttempts: worktree.mergeAttempts });
+  if (worktree.mergeAttempts >= config.get("mergeRetryCount")) {
+    fail("budget_exhausted", `'${task}' has used its ${config.get("mergeRetryCount")} merge attempts: run \`arbor escalate <reason>\`, and a human can grant another ${config.get("mergeRetryCount")} with \`arbor retry ${task}\`; or \`arbor rm ${task}\` and start over against current ${base}`, { task, mergeAttempts: worktree.mergeAttempts });
   }
   if (worktree.leaseHeldByOther) {
     fail("lease_held", `'${task}' is held by pid ${worktree.lease?.pid} on ${worktree.lease?.hostname}: another agent is driving this tree`, { task, lease: worktree.lease });
@@ -586,7 +608,7 @@ async function merge({
     ].join(`
 `), { task, paths });
   }
-  const gate = [config.postRewrite, config.preMerge].filter(Boolean).join(" && ");
+  const gate = [config.get("postRewrite"), config.get("preMerge")].filter(Boolean).join(" && ");
   const gated = gate ? await shell.run(gate, {
     cwd: worktree.path,
     env: {
@@ -627,8 +649,9 @@ ${gated.stderr}`)
     fail("usage", `landed '${task}' on ${base} (${head}) but could not discard its worktree: ${discarded.stderr || discarded.stdout}
 Run \`arbor rm ${task}\` to clean up.`, { task });
   }
-  if (config.postMerge) {
-    const ran = await shell.run(config.postMerge, {
+  const postMerge = config.get("postMerge");
+  if (postMerge) {
+    const ran = await shell.run(postMerge, {
       cwd: git.root,
       env: { ARBOR_TASK: task }
     });
@@ -852,7 +875,7 @@ import { NodeFs as NodeFs5 } from "webappwiz/system";
 async function loadConfig(root, opts = {}) {
   const found = await file(opts.fs ?? new NodeFs5, root);
   const trunk = found.trunk ?? await (opts.git ?? new Git(root)).defaultBranch() ?? "main";
-  return { ...defaults(root, trunk), ...found };
+  return CONFIG_FACTORY.create({ ...defaults(root, trunk), ...found });
 }
 function defaults(root, trunk) {
   return {
@@ -933,7 +956,7 @@ class Worktree {
     if (!lease) {
       return false;
     }
-    if (Date.now() - Date.parse(lease.heartbeatAt) >= config.leaseStalenessMs) {
+    if (Date.now() - Date.parse(lease.heartbeatAt) >= config.get("leaseStalenessMs")) {
       return false;
     }
     return lease.hostname === ps.hostname ? ps.alive(lease.pid) : true;
@@ -1054,10 +1077,10 @@ class WorktreeService {
     await this.fs.mkdir(this.removedDir);
   }
   get trunk() {
-    return this.config.trunk;
+    return this.config.get("trunk");
   }
   pathFor(task) {
-    return resolve2(this.config.worktreeRoot, task);
+    return resolve2(this.config.get("worktreeRoot"), task);
   }
   branchFor(task) {
     return `${BRANCH_PREFIX}${task}`;
@@ -1099,8 +1122,8 @@ class WorktreeService {
     }
     return found;
   }
-  async add(task, { base = this.config.trunk } = {}) {
-    await this.fs.mkdir(this.config.worktreeRoot);
+  async add(task, { base = this.config.get("trunk") } = {}) {
+    await this.fs.mkdir(this.config.get("worktreeRoot"));
     return this.git.addWorktree(this.branchFor(task), this.pathFor(task), base);
   }
   async discard(worktree) {
@@ -1137,7 +1160,7 @@ class WorktreeService {
     return raw?.trim() ?? null;
   }
   async rememberRemoved(task, at = new Date().toISOString()) {
-    const { removedCapacity } = this.config;
+    const removedCapacity = this.config.get("removedCapacity");
     await this.fs.write(this.removedPath(task), `${at}
 `);
     const names = await this.fs.readdir(this.removedDir).catch(() => []);
@@ -1186,10 +1209,10 @@ function repository(at) {
         fs,
         ps,
         log: log2,
-        stalenessMs: config.leaseStalenessMs
+        stalenessMs: config.get("leaseStalenessMs")
       }),
       shell: new Shell({ ps }),
-      journal: new Journal(`${arborDir}/log.jsonl`, config.logCapacity, {
+      journal: new Journal(`${arborDir}/log.jsonl`, config.get("logCapacity"), {
         fs
       })
     });
@@ -1213,7 +1236,7 @@ async function retry({
   const worktree = await found.save({ status: "working", mergeAttempts: 0 });
   log2.info([
     `${color9.green("retry")} ${worktree.task}`,
-    `  attempts: 0 of ${config.mergeRetryCount}`,
+    `  attempts: 0 of ${config.get("mergeRetryCount")}`,
     `  status:   working`,
     "",
     `Run \`arbor claim ${worktree.task}\` to pick it up.`
@@ -1255,6 +1278,43 @@ async function rm({ service, log: log2 }, task, { force = false } = {}) {
 `));
 }
 
+// wait.ts
+import { color as color11 } from "webappwiz/log";
+import { Duration as Duration2, sleep } from "webappwiz/time";
+var DEFAULT_TIMEOUT = Duration2.mins(5);
+var POLL = Duration2.secs(2);
+var RUNNING = ["working", "merging"];
+async function wait({ service, log: log2 }, task, { timeout = DEFAULT_TIMEOUT, poll = POLL } = {}) {
+  const deadline = Date.now() + timeout.ms;
+  for (;; ) {
+    const worktree = await service.find(task);
+    if (worktree.status === "absent") {
+      fail("not_found", `no task '${task}': run \`arbor ls\` to see what there is`, { task });
+    }
+    if (!RUNNING.includes(worktree.status)) {
+      log2.info(report2(worktree));
+      return;
+    }
+    const left = deadline - Date.now();
+    if (left <= 0) {
+      fail("timeout", `'${task}' is still ${worktree.status} after ${timeout.secs}s: wait again, work alongside it and accept the rebase, or ask the human`, { task, status: worktree.status });
+    }
+    await sleep(Duration2.min(poll, Duration2.ms(left)));
+  }
+}
+function report2(worktree) {
+  const lines2 = [`${color11.bold(worktree.task)} ${worktree.status}`];
+  const escalation = worktree.state?.escalations?.at(-1)?.reason;
+  if (escalation) {
+    lines2.push(`  ${color11.yellow(`escalated: ${escalation}`)}`);
+  }
+  if (worktree.status === "removed") {
+    lines2.push("", `Nothing left of it here: \`arbor log\` says whether it landed.`);
+  }
+  return lines2.join(`
+`);
+}
+
 // arbor.ts
 var here = async ({
   service,
@@ -1274,14 +1334,20 @@ arbor.command("rm").description("discard a task: worktree, branch and state file
 }).action((opts, ctx) => ctx.journal.record("rm", opts.task, () => rm(ctx, opts.task, { force: opts.force })));
 arbor.command("ls").description("list every task: name, status, lease (held: an agent is on it now; stale: gone quiet, normal for a task mid-edit; none), commits ahead of trunk, age").option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => ls(ctx, { json: opts.json }));
 arbor.command("show").description("read one task without touching it: everything `ls` lists for it, plus the ARBOR.md its agent left at the worktree root; takes no lease, so it cannot knock that agent off its own tree").arg("task", t.string(), { description: "task name" }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => show(ctx, opts.task, { json: opts.json }));
+arbor.command("wait").description("block until a task stops moving: escalated, or gone (merged or removed), or broken; takes no lease, and gives up with `timeout` rather than waiting forever").arg("task", t.string(), { description: "task name" }).option("timeout-secs", t.number(), {
+  default: DEFAULT_TIMEOUT.secs,
+  description: "how long to wait before giving up"
+}).action((opts, ctx) => wait(ctx, opts.task, {
+  timeout: Duration3.secs(opts["timeout-secs"])
+}));
 arbor.command("log").description("show what has been done here recently: one line per add, claim, merge, rm, escalate and retry, with how it ended; outlives the tasks themselves").option("count", t.number(), {
   default: DEFAULT_COUNT,
   description: "how many entries to show"
 }).option("json", t.boolean(), { default: false, description: "emit JSON" }).action((opts, ctx) => log(ctx, { count: opts.count, json: opts.json }));
 arbor.command("dev").description("serve `ls`, `show` and `log` as a web page; read-only").option("port", t.number(), {
   default: DEFAULT_PORT,
-  description: "port to listen on"
-}).action((opts, ctx) => dev(ctx, { port: opts.port }));
+  description: "port to listen on, or the next open one above it"
+}).action((opts, ctx) => dev(ctx, { ports: devPorts(opts.port) }));
 arbor.command("path").description("print a task's worktree path, or the main tree with no task; names another agent's tree without taking its lease").arg("task", t.string(), {
   default: "",
   description: "task name; omit for the main tree"

package/load-config.d.ts

@@ -1,5 +1,5 @@
 import { type Fs } from "webappwiz/system";
-import type { Config } from "./config.js";
+import { type Config } from "./config.js";
 import { Git } from "./git.js";
 export interface LoadConfigOptions {
     /** What `arbor.config.ts` is looked for through; the real one by default. */

package/package.json

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

package/wait.d.ts

@@ -0,0 +1,22 @@
+import { type Logger } from "webappwiz/log";
+import { Duration } from "webappwiz/time";
+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;
+export interface WaitOptions {
+    /** How long to wait before giving up. */
+    timeout?: Duration;
+    /** How long between reads of the record; the default suits a human's patience. */
+    poll?: Duration;
+}
+/**
+ * Blocks until a task stops moving: merged or removed (both leave the name
+ * `removed`), escalated to a human, or broken. Waiting is for the agent whose
+ * 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.
+ */
+export declare function wait({ service, log }: {
+    service: WorktreeService;
+    log: Logger;
+}, task: string, { timeout, poll }?: WaitOptions): Promise<void>;