passalong 1.1.0 → 1.3.0

package/README.md

@@ -51,8 +51,10 @@ passalong archive <id>        off the board and out of the free tier's count
 passalong rm <id>             delete it
 passalong attach <file>       upload a picture or file and print the markdown that points at it
 passalong work [--once] [--agent CMD]  run an agent on each piece of ready work here, in turn
-passalong work --watch        the runner: work a person marked safe to run alone, up to 3 at once
-                              and 10 a day, each in its own worktree, finished as a pull request
+passalong work --watch        the runner, in a repo or a folder of repos: work a person marked safe
+                              to run alone, up to 3 at once, each in its own worktree, finished
+                              as a pull request; each agent's steps show in the hub. When Claude's
+                              usage runs out it pauses, and carries on once it is back
 passalong now                 what this worktree holds and what is waiting
 passalong hub                 open the hub in the browser
 passalong export [dir]        every piece of work as plain markdown

package/bin/passalong

@@ -22,8 +22,8 @@
 //   passalong rm <id>             delete it
 //   passalong attach <file>       upload a picture or a file and print the markdown that points at it
 //   passalong work [--once] [--agent CMD]  run an agent on each piece of ready work here, one after another
-//   passalong work --watch [--every SECS]  the runner: keep taking work marked safe to run alone,
-//     up to 3 at once and 10 a day, each in its own worktree and branch, finished as a pull request
+//   passalong work --watch [--every SECS]  the runner, in a repo or a folder of repos: keep taking work marked safe to run alone,
+//     up to 3 at once, each in its own worktree and branch, finished as a pull request
 //   passalong hub                 open the hub in the browser
 //   passalong export [dir]        dump every piece of work as plain markdown (default ./passalong-export)
 //   passalong admin create <email>   make an account that runs Passalong (owner only)
@@ -257,32 +257,55 @@ async function statusLine() {
  */
 async function runner(f) {
   const every = Number(f.every) || 60;
-  console.error(
-    "Runner: taking work marked safe to run alone, up to 3 at once and 10 a day, each finished as a " +
-      "pull request. The hub's Work board shows what it is on. Stop it with Ctrl-C: agents running " +
-      "then stop too, and what they held goes back to the queue once it goes quiet.",
-  );
   let idle = false;
+  /** "a, b and 4 more": the repos a runner serves, short enough for one line. */
+  const some = (repos) =>
+    repos.length <= 3 ? repos.join(", ") : `${repos.slice(0, 3).join(", ")} and ${repos.length - 3} more`;
   await passalong
     .watch({
       agent: typeof f.agent === "string" ? f.agent : undefined,
       every,
       cli: fileURLToPath(import.meta.url),
       signals: true,
-      onTask: (t, { dir, branch }) => {
+      // Said only once the folder checked out: a runner that cannot run says why, not what it will do.
+      onStart: ({ repos, skipped }) => {
+        console.error(
+          `Runner for ${repos.length === 1 ? repos[0] : `${repos.length} repos: ${some(repos)}`}.\n` +
+            "It takes work marked safe to run alone, up to 3 at once, and finishes each " +
+            "as a pull request. You can watch each agent here and on the work's page in the hub. " +
+            "Stop it with Ctrl-C: agents running then stop too.",
+        );
+        if (skipped.length)
+          console.error(`Skipped ${skipped.length} checkout${skipped.length === 1 ? "" : "s"} with no origin remote: ${some(skipped)}`);
+      },
+      onTask: (t, { dir, branch, repo }) => {
         idle = false;
-        console.error(`\n→ ${t.id}  ${t.title}\n  on ${branch} in ${dir}`);
+        console.error(`\n→ ${t.id}  ${t.title}\n  ${repo}, on ${branch} in ${dir}`);
       },
-      onIdle: (repo) => {
-        if (!idle) console.error(`waiting for work marked safe to run alone for ${repo || "this repo"}…`);
+      onStep: (t, text) => console.error(`  ${t.id} · ${text}`),
+      onIdle: (repos) => {
+        if (!idle)
+          console.error(
+            `waiting for work marked safe to run alone in ${some(repos)}. ` +
+              "Work with no repo needs one picked on its page in the hub.",
+          );
         idle = true;
       },
-      onCapped: (n) =>
-        console.error(`${n} runs today: that's the day's limit. Picking up again tomorrow.`),
+      onPaused: (t, { until }) =>
+        console.error(
+          `‖ ${t.id} paused: Claude's usage ran out. ` +
+            (until
+              ? `It carries on at ${new Date(until).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })}`
+              : "It tries again every 15 minutes") +
+            ", and takes nothing new until then.",
+        ),
       onFinished: (t, { branch, log }) => console.error(`✓ ${t.id} finished on ${branch} (log: ${log})`),
       onWaiting: (t, { question }) =>
         console.error(`? ${t.id} is waiting on you: "${question.split("\n")[0]}" (answer it in the hub)`),
-      onResumed: (t) => console.error(`\n→ ${t.id}  ${t.title}  (answered: carrying on)`),
+      onResumed: (t, { afterPause }) =>
+        console.error(
+          `\n→ ${t.id}  ${t.title}  (${afterPause ? "carrying on where it stopped" : "answered: carrying on"})`,
+        ),
       onPassed: (t, { dir, log }) =>
         console.error(`✗ ${t.id} went back to its author, unfinished. Its worktree: ${dir} (log: ${log})`),
       onTrouble: (err, t) => console.error(`! ${t ? `${t.id}: ` : ""}${err?.message || err}`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Work, projects, documents and files for a team and its agents: take work, hand it in with evidence, and keep what the team knows in its projects.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [

package/src/api.js

@@ -359,6 +359,9 @@ export const tasks = () => call("/v1/tasks");
 export const nextTask = (body) => call("/v1/tasks/next", { method: "POST", body });
 /** The runner saying how it is, for the hub: what it is on, today's count, or that it stopped. */
 export const runnerStatus = (body) => call("/v1/runner", { method: "PUT", body });
+/** What a runner's agent did since the last report, a line each, for the hub to show. */
+export const workSteps = (id, steps) =>
+  call(`/v1/work/${encodeURIComponent(id)}/steps`, { method: "POST", body: { steps } });
 export const reopen = (id, why) =>
   call(`/v1/work/${encodeURIComponent(id)}/reopen`, { method: "POST", body: { why } });
 /** Take work back from whoever holds it. */

package/src/passalong.js

@@ -775,51 +775,72 @@ export async function work({
 
 /**
  * The runner (src/runner.js, docs/LOOP.md §1a): work a person ticked Safe to run alone, each piece in
- * a git worktree of its own beside this checkout, on its own branch, by an agent that finishes with
- * a pull request. Up to `atOnce` at a time and `perDay` a day; a run that ends without the work done
- * passes it back to its author. Runs until stopped; `sleep` is how the tests stop it.
+ * a git worktree of its own beside its checkout, on its own branch, by an agent that finishes with
+ * a pull request. Up to `atOnce` at a time, with no count a day; a run that ends without the work
+ * done passes it back to its author. Runs until stopped; `sleep` is how the tests stop it.
  *
- * A worktree is made before asking the queue, because taking work is done by a worktree's agent and
- * the agent that takes it must be the one that does it. When the queue has nothing, the worktree
- * goes again.
+ * When the agent's usage runs out (runner.usageOut) its work is not given back: it stays held here
+ * with its worktree, the runner takes nothing new, and once the usage is back (when the agent said,
+ * or every `USAGE_RETRY_MS`) it carries on where it stopped.
+ *
+ * Started inside a checkout it serves that repo. Started in a folder of checkouts it serves every
+ * one with an `origin` remote, so one terminal does what six used to. The folder is checked before
+ * anything is said (`onStart`), so a runner that cannot run says why instead of what it will do.
+ *
+ * Work is asked for before a worktree is made: the agent's id is minted first and written into the
+ * worktree once there is work for it, so a runner serving many repos does not make and remove a
+ * worktree in each of them every minute. What the agent does is read as it goes (runner.describe)
+ * and sent to the hub every few seconds as steps, and to `onStep` for the terminal.
  */
 export async function watch({
   cwd = process.cwd(),
   agent: command,
   every = 60,
   atOnce = runner.LIMITS.atOnce,
-  perDay = runner.LIMITS.perDay,
   minutes = runner.LIMITS.minutes,
   cli,
   git = runner.git,
   runAgent = runner.runAgent,
   now = () => Date.now(),
   countFile = join(store.HOME, "runner.json"),
+  machine = runner.machineName,
+  onStart = () => {},
   onTask = () => {},
+  onStep = () => {},
   onIdle = () => {},
-  onCapped = () => {},
+  onPaused = () => {},
   onFinished = () => {},
   onPassed = () => {},
   onWaiting = () => {},
   onResumed = () => {},
   onTrouble = () => {},
   report = api.runnerStatus,
+  postSteps = api.workSteps,
+  stepEvery = 5,
   signals = false,
   sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
 } = {}) {
   needsSync("running work");
-  const { root, repo } = context(cwd);
-  if (!root) throw new PassalongError("run the runner inside a git checkout of the repo");
-  let remote = "";
-  try {
-    remote = git(["-C", root, "remote", "get-url", "origin"]);
-  } catch {}
-  if (!remote)
+  const inside = context(cwd).root;
+  const { found, skipped } = runner.checkoutsIn(cwd, { git });
+  if (inside && !found.length)
     throw new PassalongError(
       "this checkout has no `origin` remote: the runner pushes each change to a branch there",
     );
-  const runs = runner.runsDirOf(root);
-  mkdirSync(runs, { recursive: true });
+  if (!found.length)
+    throw new PassalongError(
+      `there's no git checkout in ${cwd} or the folders under it` +
+        (skipped.length ? ` with an \`origin\` remote (${skipped.length} without one)` : "") +
+        ". Start the runner inside a repo, or in the folder that holds your repos.",
+    );
+  const checkouts = found.map(({ root, remote }) => {
+    const runs = runner.runsDirOf(root);
+    mkdirSync(runs, { recursive: true });
+    return { root, runs, repo: context(root).repo || remote, forge: runner.forgeOf(remote) };
+  });
+  const repos = checkouts.map((k) => k.repo);
+  const name = machine();
+  onStart({ repos, skipped });
 
   // What it is on, said to the hub once a minute and whenever it changes (PUT /v1/runner), so
   // nobody has to look at this terminal to know. A failed report never stops a run.
@@ -827,11 +848,12 @@ export async function watch({
   const say = (stopped = false) =>
     Promise.resolve(
       report({
-        host: hostname(),
-        repo,
+        host: name,
+        repo: checkouts.length === 1 ? repos[0] : `${basename(cwd)}/`,
+        repos,
         running: [...onNow].map(([id, title]) => ({ id, title })),
         runs_today: runner.runsToday(countFile, runner.dayOf(now())),
-        per_day: perDay,
+        per_day: 0,
         at_once: atOnce,
         stopped,
       }),
@@ -847,36 +869,56 @@ export async function watch({
     ? { command: command.trim().split(/\s+/)[0], args: command.trim().split(/\s+/).slice(1) }
     : runner.claudeCommand({ cli });
 
-  /**
-   * One slot: a worktree and a piece of work taken for it, with its agent started. `null` when
-   * nothing waits. The run itself is handed back unawaited, so several go at once.
-   */
-  async function startOne(n) {
+  /** Make the worktree a taken piece of work runs in, as the agent whose id took it. */
+  function worktreeFor(k, dir, id) {
     try {
-      git(["-C", root, "fetch", "--quiet", "origin"]);
+      git(["-C", k.root, "fetch", "--quiet", "origin"]);
     } catch {}
     let base = "HEAD";
     try {
-      base = git(["-C", root, "rev-parse", "--verify", "--quiet", "origin/HEAD"])
+      base = git(["-C", k.root, "rev-parse", "--verify", "--quiet", "origin/HEAD"])
         ? "origin/HEAD"
         : base;
     } catch {}
-    const dir = join(runs, `run-${now()}-${n}`);
-    git(["-C", root, "worktree", "add", "--detach", "--quiet", dir, base]);
+    git(["-C", k.root, "worktree", "add", "--detach", "--quiet", dir, base]);
+    writeFileSync(join(localDir(dir), "agent.json"), `${JSON.stringify({ id }, null, 2)}\n`);
+  }
+
+  /**
+   * One slot: a piece of work taken for one of the repos, its worktree made and its agent started.
+   * `null` when nothing waits in any of them. The run itself is handed back unawaited, so several
+   * go at once. Repos are asked in turn, starting after the last one that had work.
+   */
+  let turn = 0;
+  async function startOne(n) {
     let t = null;
-    try {
-      t = await nextWork({ cwd: dir, alone: true });
-    } catch (err) {
-      onTrouble(err);
-    }
-    if (!t) {
-      git(["-C", root, "worktree", "remove", "--force", dir]);
-      return null;
+    let k = null;
+    let dir = "";
+    let id = "";
+    for (let i = 0; i < checkouts.length && !t; i++) {
+      k = checkouts[(turn + i) % checkouts.length];
+      dir = join(k.runs, `run-${now()}-${n}`);
+      id = randomBytes(12).toString("hex");
+      try {
+        const got = await api.nextTask({
+          agent: id,
+          host: hostname(),
+          repo: k.repo,
+          worktree: dir,
+          alone: true,
+        });
+        t = got?.task || null;
+      } catch (err) {
+        onTrouble(err);
+      }
+      if (t) turn = (turn + i + 1) % checkouts.length;
     }
+    if (!t || !k) return null;
     // Its branch, or a fresh one beside it when that one is still checked out in the worktree of
     // an earlier run that didn't finish (kept for its author), as when a person ticks it again.
     let branch = runner.branchOf(t.id);
     try {
+      worktreeFor(k, dir, id);
       try {
         git(["-C", dir, "switch", "--quiet", "-C", branch]);
       } catch {
@@ -886,39 +928,92 @@ export async function watch({
     } catch (err) {
       // Taken and then stuck before any agent started: never left held with nobody on it.
       const why = runner.passBack({ minutes, failed: err.message.split("\n")[0], dir, branch });
-      await pass(t.id, why, { cwd: dir, runner: true }).catch((e) => onTrouble(e, t));
+      await pass(t.id, why, { cwd: existsSync(dir) ? dir : k.root, runner: true }).catch((e) =>
+        onTrouble(e, t),
+      );
       onPassed(t, { why, dir, log: "" });
       return { run: Promise.resolve() };
     }
     runner.countRun(countFile, runner.dayOf(now()));
     onNow.set(t.id, t.title || t.id);
-    onTask(t, { dir, branch });
+    onTask(t, { dir, branch, repo: k.repo });
     say();
     return {
-      run: finish(t, dir, branch).finally(() => {
-        onNow.delete(t.id);
+      run: finish(t, k, dir, branch).finally(() => {
+        // A paused run is still on: the hub keeps showing it, with its last step saying why.
+        if (!paused.has(t.id)) onNow.delete(t.id);
         say();
       }),
     };
   }
 
-  async function finish(t, dir, branch, { resumed = false } = {}) {
-    const log = join(runs, `${t.id}.log`);
+  async function finish(t, k, dir, branch, { resumed = false } = {}) {
+    const log = join(k.runs, `${t.id}.log`);
+    // Steps go to the hub every few seconds rather than one request each: an agent can take a
+    // dozen in a second. Whatever is left goes when the run ends.
+    const pending = [];
+    const flush = async () => {
+      if (!pending.length) return;
+      await postSteps(t.id, pending.splice(0)).catch(() => {});
+    };
+    const step = (text) => {
+      pending.push({ at: new Date(now()).toISOString(), text });
+      onStep(t, text);
+    };
+    step(
+      resumed === "usage"
+        ? `Carrying on now that Claude's usage is back, on ${name}`
+        : resumed
+          ? `Carrying on after your answer, on ${name}`
+          : `Started on ${name} in ${k.repo}, on branch ${branch}`,
+    );
+    const timer = setInterval(flush, stepEvery * 1000);
     const ran = await runAgent({
       ...agentRun,
-      prompt: resumed ? runner.resumePrompt(t, branch) : runner.runnerPrompt(t, branch),
+      prompt:
+        resumed === "usage"
+          ? runner.pausedPrompt(t, branch, { forge: k.forge })
+          : resumed
+            ? runner.resumePrompt(t, branch, { forge: k.forge })
+            : runner.runnerPrompt(t, branch, { forge: k.forge }),
       cwd: dir,
       log,
       minutes,
       env: { ...process.env, PASSALONG_TASK: t.id },
-    });
+      onStep: step,
+    }).finally(() => clearInterval(timer));
+    if (ran.timedOut) step(`Stopped: it ran out of its ${minutes} minutes`);
     let held = null;
     try {
       held = (await api.tasks()).tasks.find((x) => x.id === t.id) || null;
     } catch {}
+    // Let go of already: its agent passed it, somebody pressed Stop, or it was taken back. Giving
+    // it back again would be refused, and it is no longer this runner's to describe.
+    if (held?.state !== "done" && !held?.claim) {
+      step("It was no longer held here when the agent stopped, so the runner left it as it is");
+      await flush();
+      onTrouble(new Error("no longer held here when its agent stopped; left as it is"), t);
+      return;
+    }
+    // The last step says how the run ended, while the work is still held here: once it is passed
+    // back, its steps are no longer this runner's to write.
+    // Its usage ran out: not given up. It stays held here, and carries on once the usage is back.
+    if (ran.usage && held.state !== "done" && !held.claim?.asking) {
+      pauseUntil = Math.max(pauseUntil, ran.usage.until || now() + runner.USAGE_RETRY_MS);
+      const when = ran.usage.until ? `at ${runner.clockOf(pauseUntil)}` : "when it's back";
+      step(`Paused: Claude's usage ran out. It carries on here ${when}, with nothing lost.`);
+      await flush();
+      paused.set(t.id, { t, k, dir, branch });
+      onPaused(t, { until: ran.usage.until ? pauseUntil : 0 });
+      return;
+    }
+    if (held.state !== "done" && !held.claim?.asking)
+      step("Gave it back unfinished, with the reason on the work. Nothing it changed is lost.");
+    if (held.claim?.asking) step("Waiting for your answer, then it carries on");
+    await flush();
     if (held?.state === "done") {
       try {
-        git(["-C", root, "worktree", "remove", "--force", dir]);
+        git(["-C", k.root, "worktree", "remove", "--force", dir]);
       } catch {}
       onFinished(t, { branch, log });
       return;
@@ -926,7 +1021,7 @@ export async function watch({
     // It stopped to ask, and the question is waiting on a person: not given up. The work stays held
     // here with its worktree, and the run picks up again once they answer (resumeAnswered).
     if (held?.claim?.asking) {
-      waiting.set(t.id, { t, dir, branch });
+      waiting.set(t.id, { t, k, dir, branch });
       onWaiting(t, { question: held.claim.asking, dir });
       return;
     }
@@ -934,9 +1029,9 @@ export async function watch({
       minutes,
       ...ran,
       note: held?.claim?.note || "",
-      said: runner.lastLine(log),
-      dir,
+      said: ran.said || runner.lastLine(log),
       branch,
+      machine: name,
     });
     try {
       await pass(t.id, why, { cwd: dir, runner: true });
@@ -947,18 +1042,21 @@ export async function watch({
   }
 
   const running = new Set();
-  /** Runs stopped on a question, by work id: their worktree and branch, kept to resume in. */
+  /** Runs stopped on a question, by work id: their checkout, worktree and branch, to resume in. */
   const waiting = new Map();
+  /** Runs stopped because the agent's usage ran out, the same way: they carry on at `pauseUntil`. */
+  const paused = new Map();
+  let pauseUntil = 0;
   /** Start an agent again where it stopped: the same worktree, branch and claim. */
-  function resume(t, dir, branch) {
+  function resume(t, k, dir, branch, { afterPause = false } = {}) {
     runner.countRun(countFile, runner.dayOf(now()));
     onNow.set(t.id, t.title || t.id);
-    onResumed(t, { dir, branch });
+    onResumed(t, { dir, branch, afterPause });
     say();
-    const run = finish(t, dir, branch, { resumed: true })
+    const run = finish(t, k, dir, branch, { resumed: afterPause ? "usage" : true })
       .catch((err) => onTrouble(err, t))
       .finally(() => {
-        onNow.delete(t.id);
+        if (!paused.has(t.id)) onNow.delete(t.id);
         running.delete(run);
         say();
       });
@@ -982,9 +1080,9 @@ export async function watch({
       if (row?.state === "done") {
         waiting.delete(id);
         try {
-          git(["-C", root, "worktree", "remove", "--force", w.dir]);
+          git(["-C", w.k.root, "worktree", "remove", "--force", w.dir]);
         } catch {}
-        onFinished(w.t, { branch: w.branch, log: join(runs, `${id}.log`) });
+        onFinished(w.t, { branch: w.branch, log: join(w.k.runs, `${id}.log`) });
         continue;
       }
       if (!row?.claim) {
@@ -993,39 +1091,60 @@ export async function watch({
         continue;
       }
       if (row.claim.asking) continue;
-      if (running.size >= atOnce) return;
-      if (runner.runsToday(countFile, runner.dayOf(now())) >= perDay) return;
+      if (running.size >= atOnce || paused.size) return;
       waiting.delete(id);
-      resume(w.t, w.dir, w.branch);
+      resume(w.t, w.k, w.dir, w.branch);
     }
   }
 
-  // A runner started again finds the questions its earlier runs left waiting: their worktrees are
-  // still beside the checkout, and the work is still held by them.
+  // A runner started again finds what its earlier runs left held: their worktrees are still beside
+  // their checkouts. One waiting on a question waits on; any other (paused when the usage ran out,
+  // or stopped with the runner) carries on straight away.
   try {
     for (const row of (await api.tasks()).tasks) {
-      const leaf = row.claim?.worktree || "";
-      const dir = leaf.startsWith("run-") ? join(runs, leaf) : "";
-      if (!dir || !existsSync(dir) || row.state === "done") continue;
+      const leaf = basename(row.claim?.worktree || "");
+      if (!leaf.startsWith("run-") || row.state === "done") continue;
+      const k = checkouts.find((x) => existsSync(join(x.runs, leaf)));
+      if (!k) continue;
+      const dir = join(k.runs, leaf);
       let branch = runner.branchOf(row.id);
       try {
         branch = git(["-C", dir, "branch", "--show-current"]) || branch;
       } catch {}
-      waiting.set(row.id, { t: { id: row.id, title: row.title, markdown: "" }, dir, branch });
+      (row.claim?.asking ? waiting : paused).set(row.id, {
+        t: { id: row.id, title: row.title, markdown: "" },
+        k,
+        dir,
+        branch,
+      });
     }
   } catch {}
 
+  /**
+   * While the agent's usage is out: keep each paused run's hold alive (an empty report of steps
+   * renews it, so the hub doesn't call it gone quiet), and once the time comes, carry them on. If
+   * the usage is still out they pause again at once, which costs nothing.
+   */
+  async function carryOnPaused() {
+    if (!paused.size) return;
+    if (now() < pauseUntil) {
+      for (const id of paused.keys()) await postSteps(id, []).catch(() => {});
+      return;
+    }
+    pauseUntil = 0;
+    for (const [id, p] of [...paused]) {
+      if (running.size >= atOnce) break;
+      paused.delete(id);
+      resume(p.t, p.k, p.dir, p.branch, { afterPause: true });
+    }
+  }
+
   let n = 0;
-  let cappedOn = "";
   for (;;) {
+    await carryOnPaused();
     await resumeAnswered();
-    while (running.size < atOnce) {
-      const day = runner.dayOf(now());
-      if (runner.runsToday(countFile, day) >= perDay) {
-        if (cappedOn !== day) onCapped(perDay);
-        cappedOn = day;
-        break;
-      }
+    // Nothing new while the usage is out: it would only start and stop at once.
+    while (running.size < atOnce && !paused.size && now() >= pauseUntil) {
       let slot;
       try {
         slot = await startOne(++n);
@@ -1034,7 +1153,7 @@ export async function watch({
         break;
       }
       if (!slot) {
-        if (!running.size) onIdle(repo);
+        if (!running.size) onIdle(repos);
         break;
       }
       const run = slot.run.catch((err) => onTrouble(err)).finally(() => running.delete(run));

package/src/runner.js

@@ -12,11 +12,27 @@
 // Everything that touches git, the clock or a process is passed in, so the tests can run it.
 
 import { execFileSync, spawn } from "node:child_process";
-import { mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import {
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname, platform } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
 
-/** How many agents at once, how many runs a day, and how long one run may take. */
-export const LIMITS = { atOnce: 3, perDay: 10, minutes: 60 };
+/**
+ * How many agents at once, and how long one run may take. There is no count of runs a day: it was
+ * ten, and a loop that gave the same work back over and over spent all ten on nothing, so the
+ * runner sat idle with work waiting (2026-11-06). What limits a runner now is the agent's own usage
+ * (`usageOut`: it pauses until that comes back) and the work the Passalong plan lets you keep.
+ */
+export const LIMITS = { atOnce: 3, minutes: 60 };
+
+/** How long a runner waits to try again when its agent's usage ran out and it didn't say until when. */
+export const USAGE_RETRY_MS = 15 * 60 * 1000;
 
 /**
  * What an unattended agent may do. `dontAsk` refuses anything not listed here, since there is
@@ -62,6 +78,9 @@ export const PERMISSIONS = {
   ],
 };
 
+/** Where a checkout's origin is hosted, for how a run ends: a pull request or a merge request. */
+export const forgeOf = (remote) => (/gitlab/i.test(String(remote || "")) ? "gitlab" : "github");
+
 /** The branch a piece of work's change goes on. */
 export const branchOf = (id) => `passalong/${id}`;
 
@@ -76,6 +95,11 @@ export function claudeCommand({ node = process.execPath, cli } = {}) {
     command: "claude",
     args: [
       "-p",
+      // One JSON event per line as it works, which the runner turns into the steps a person can
+      // watch from the hub (describe below). Plain -p prints only the final answer, at the end.
+      "--output-format",
+      "stream-json",
+      "--verbose",
       "--permission-mode",
       "dontAsk",
       "--settings",
@@ -88,7 +112,23 @@ export function claudeCommand({ node = process.execPath, cli } = {}) {
 }
 
 /** What the agent is told: the work itself, and how to finish it as a pull request. */
-export function runnerPrompt(t, branch = branchOf(t.id)) {
+export function runnerPrompt(t, branch = branchOf(t.id), { forge = "github" } = {}) {
+  // GitLab has no `gh`: a push option opens the merge request, and git prints its link.
+  const ship =
+    forge === "gitlab"
+      ? [
+          `When it is done, commit what you changed with a message starting "${t.id}: ", then run`,
+          `exactly \`git push -u origin ${branch} -o merge_request.create\`, which opens a merge`,
+          "request and prints its link. Then call hand_in with id " + t.id + ", `pr` set to that",
+          "link (or the commit hash if the push failed, and say why in the note), `note`: one plain",
+        ]
+      : [
+          `When it is done, commit what you changed with a message starting "${t.id}: ", then run`,
+          `exactly \`git push -u origin ${branch}\` and open a pull request with`,
+          `\`gh pr create --fill --head ${branch}\`. Then call hand_in with id ${t.id}, \`pr\` set to the`,
+          "pull request's URL (or the commit hash if the push or the pull request failed, and say why in",
+          "the note), `note`: one plain",
+        ];
   return [
     `You hold passalong work ${t.id}, and no other agent can take it while you do. Here it is:`,
     "",
@@ -98,11 +138,8 @@ export function runnerPrompt(t, branch = branchOf(t.id)) {
     `means, and get there. Call the passalong MCP tool progress with id ${t.id} and a one-line`,
     "status at each milestone; 30 minutes of silence stalls it.",
     "",
-    `When it is done, commit what you changed with a message starting "${t.id}: ", then run`,
-    `exactly \`git push -u origin ${branch}\` and open a pull request with`,
-    `\`gh pr create --fill --head ${branch}\`. Then call hand_in with id ${t.id}, \`pr\` set to the`,
-    "pull request's URL (or the commit hash if the push or the pull request failed, and say why in",
-    "the note), `note`: one plain sentence saying what you did, and `evidence`: what you ran and",
+    ...ship,
+    "sentence saying what you did, and `evidence`: what you ran and",
     "what came back, with the commands and the lines that decided it, the test summary, the commit.",
     "Keep that as you go. What you learned about the project goes into its documents",
     "(save_document). If a call says you no longer hold it, stop.",
@@ -120,6 +157,10 @@ export function runnerPrompt(t, branch = branchOf(t.id)) {
     "If something only a person can do stands between you and done (a permission, a secret), call",
     `progress with id ${t.id} and a note starting "BLOCKED: " that says exactly what you need,`,
     "and stop. The work goes back to the person who wrote it, with that note.",
+    "",
+    "Never call pass yourself. If you stop without hand_in, the runner gives the work back",
+    "unfinished and shows your last message as the reason, so end with what is done and what",
+    "isn't, in plain sentences.",
   ].join("\n");
 }
 
@@ -127,14 +168,32 @@ export function runnerPrompt(t, branch = branchOf(t.id)) {
  * What an agent is told when its run starts again after a person answered its question: read the
  * answer, then finish exactly as the first run was told to.
  */
-export function resumePrompt(t, branch = branchOf(t.id)) {
+export function resumePrompt(t, branch = branchOf(t.id), opts = {}) {
   return [
     `You hold passalong work ${t.id} (${t.title || t.id}), and you stopped earlier to ask the person`,
     `a question. They have answered. Call the passalong MCP tool take with id ${t.id} first: their`,
     "answer comes back with it. Then carry on in this worktree, where your earlier changes are, and",
     "finish as before:",
     "",
-    runnerPrompt({ ...t, markdown: "" }, branch)
+    runnerPrompt({ ...t, markdown: "" }, branch, opts)
+      .split("\n")
+      .slice(4)
+      .join("\n"),
+  ].join("\n");
+}
+
+/**
+ * What an agent is told when its run starts again after it stopped part-way, because Claude's usage
+ * ran out or the runner was stopped: the work is still held, its changes are in this worktree.
+ */
+export function pausedPrompt(t, branch = branchOf(t.id), opts = {}) {
+  return [
+    `You hold passalong work ${t.id} (${t.title || t.id}). An earlier run on it stopped before it`,
+    "finished, because Claude's usage ran out or the runner was stopped. Call the passalong MCP tool",
+    `take with id ${t.id} first to read the work again. Then look at what is already done in this`,
+    "worktree (git status, git log), carry on from there, and finish as before:",
+    "",
+    runnerPrompt({ ...t, markdown: "" }, branch, opts)
       .split("\n")
       .slice(4)
       .join("\n"),
@@ -147,7 +206,7 @@ export const dayOf = (now) => {
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
 };
 
-/** How many runs have started today, kept in `file` beside the rest of the CLI's state. */
+/** How many runs have started today, kept in `file` beside the rest of the CLI's state: shown, not a limit. */
 export function runsToday(file, day) {
   try {
     const s = JSON.parse(readFileSync(file, "utf8"));
@@ -167,25 +226,80 @@ export function countRun(file, day) {
 /** Where the runs' worktrees and logs live: beside the checkout, never inside it. */
 export const runsDirOf = (root) => join(dirname(root), `${basename(root)}.passalong-runs`);
 
-/** Why a run gave its work back, said to whoever wrote it. */
-export function passBack({ minutes, timedOut, exit, note, said, dir, branch, failed }) {
+/**
+ * Why a run gave its work back, said to whoever wrote it and to the team's channel. It leads with
+ * what the agent itself said at the end, which is nearly always the reason ("Not done: I couldn't
+ * start the app to take the screenshots"). It said "stopped without finishing (exit 0)", which
+ * means nothing to a person, and "the last thing it printed", cut mid-word (2026-11-06).
+ */
+export function passBack({ minutes, timedOut, exit, note, said, branch, failed, machine }) {
   const how = failed
-    ? `couldn't start (${failed})`
+    ? `couldn't start it (${failed})`
     : timedOut
       ? `ran out of its ${minutes} minutes`
-      : `stopped without finishing${exit === undefined || exit === null ? "" : ` (exit ${exit})`}`;
+      : exit === 0
+        ? "ended its run without handing it in"
+        : `stopped with an error${exit === undefined || exit === null || exit === "" ? "" : ` (${typeof exit === "number" ? `exit code ${exit}` : exit})`}`;
+  const words = sentences(note || said, 600);
   return [
-    `The runner's agent ${how}, so this is back with you and no longer marked safe to run alone.`,
-    note ? `Its last note: "${note}".` : "It left no note.",
-    said ? `The last thing it printed: "${said}".` : "",
-    failed
-      ? ""
-      : `What it changed is kept on branch ${branch}, in ${dir}, on the machine that ran it.`,
+    `The runner's agent ${how}.`,
+    words ? `It said: "${words}"` : "It didn't say why.",
+    "It's back in To do and no longer marked safe to run alone, so no runner takes it again until someone ticks it.",
+    failed ? "" : `What it changed is kept on branch ${branch}${machine ? ` on ${machine}` : ""}.`,
   ]
     .filter(Boolean)
     .join(" ");
 }
 
+/** At most `max` characters, ended at a sentence or a word rather than mid-word. */
+export function sentences(text, max) {
+  const one = String(text ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (one.length <= max) return one;
+  const cut = one.slice(0, max);
+  const stop = Math.max(cut.lastIndexOf(". "), cut.lastIndexOf("? "), cut.lastIndexOf("! "));
+  if (stop > max * 0.5) return cut.slice(0, stop + 1);
+  const space = cut.lastIndexOf(" ");
+  return `${(space > max * 0.6 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+/**
+ * Whether what an agent said means its usage ran out (Claude Code's plan limit, or the API refusing
+ * for rate or credit), and when it comes back: `{ until }` in ms, 0 when it didn't say. `null` when
+ * it means something else. Only Claude Code's own phrasings, in short messages: an agent that ran
+ * out says so in a line, and one that added "a daily limit" to someone's app must not pause.
+ */
+export function usageOut(text, now = Date.now()) {
+  const s = String(text ?? "").trim();
+  if (!s || s.length > 400) return null;
+  if (
+    !/usage limit reached|hit your (usage |session |weekly )?limit|(session|weekly|5-hour|five-hour|opus|sonnet) limit reached|out of (extra )?usage|rate_limit_error|credit balance is too low/i.test(
+      s,
+    )
+  )
+    return null;
+  // "Claude AI usage limit reached|1736789000": when it resets, in seconds.
+  const epoch = s.match(/\|(\d{10})\b/);
+  if (epoch) return { until: Number(epoch[1]) * 1000 };
+  // "resets 3pm", "resets at 5:30 pm": the next time the clock says that, on this machine.
+  const at = s.match(/resets?\s+(?:at\s+)?(\d{1,2})(?::(\d{2}))?\s*(am|pm)?/i);
+  if (at) {
+    let h = Number(at[1]) % 12;
+    if (!at[3]) h = Number(at[1]) % 24;
+    else if (at[3].toLowerCase() === "pm") h += 12;
+    const d = new Date(now);
+    d.setHours(h, Number(at[2] || 0), 0, 0);
+    if (d.getTime() <= now) d.setDate(d.getDate() + 1);
+    return { until: d.getTime() };
+  }
+  return { until: 0 };
+}
+
+/** "3:00 pm", for saying when a paused runner carries on. */
+export const clockOf = (ms) =>
+  new Date(ms).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+
 /** The last line an agent printed, from its log: often the reason it stopped. "" when none. */
 export function lastLine(log) {
   try {
@@ -202,24 +316,66 @@ export function git(args) {
 }
 
 /**
- * Start an agent and wait for it, writing what it prints to `log`. Killed after `minutes`.
- * Resolves `{ exit, timedOut }`, never rejects: an agent that would not start is a run that
- * ended without the work done.
+ * Start an agent and wait for it. What it prints is read a line at a time: each becomes a line of
+ * `log` a person can read (Claude Code's JSON events made into sentences, anything else as it came),
+ * and each thing it does is handed to `onStep`. Killed after `minutes`. Resolves
+ * `{ exit, timedOut, said, usage }`, never rejects: an agent that would not start is a run that ended without
+ * the work done.
  */
-export function runAgent({ command, args, stdin, prompt, cwd, log, minutes, env }) {
-  return new Promise((done) => {
-    const out = openSync(log, "a");
+export function runAgent({
+  command,
+  args,
+  stdin,
+  prompt,
+  cwd,
+  log,
+  minutes,
+  env,
+  onStep = () => {},
+}) {
+  return new Promise((resolve) => {
     let timedOut = false;
     let child;
+    /** What the agent said at the end (Claude Code's result), for why it gave the work back. */
+    let said = "";
+    /** Set when it said its usage ran out (usageOut): the run is paused, not given up. */
+    let usage = null;
+    const done = (r) => resolve({ ...r, said, usage });
+    const write = (text) => {
+      try {
+        appendFileSync(log, `${clock()} ${text}\n`);
+      } catch {}
+    };
     try {
       child = spawn(command, stdin ? args : [...args, prompt], {
         cwd,
         env,
-        stdio: [stdin ? "pipe" : "ignore", out, out],
+        stdio: [stdin ? "pipe" : "ignore", "pipe", "pipe"],
       });
     } catch (err) {
+      write(`couldn't start: ${err.message}`);
       return done({ exit: err.message, timedOut });
     }
+    const reader = () => {
+      let rest = "";
+      return (chunk) => {
+        rest += chunk;
+        const lines = rest.split("\n");
+        rest = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const d = describe(line, cwd);
+          if (d.said) said = d.said;
+          usage = d.usage || usage;
+          if (d.log) write(d.log);
+          for (const step of d.step ? d.step.split("\n") : []) onStep(step);
+        }
+      };
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", reader());
+    child.stderr?.on("data", reader());
     const timer = setTimeout(
       () => {
         timedOut = true;
@@ -229,6 +385,7 @@ export function runAgent({ command, args, stdin, prompt, cwd, log, minutes, env
     );
     child.on("error", (err) => {
       clearTimeout(timer);
+      write(`couldn't start: ${err.message}`);
       done({ exit: err.message, timedOut });
     });
     child.on("close", (code) => {
@@ -241,3 +398,194 @@ export function runAgent({ command, args, stdin, prompt, cwd, log, minutes, env
     }
   });
 }
+
+const clock = () => new Date().toTimeString().slice(0, 8);
+
+/**
+ * Take out what looks like a secret before a line leaves the machine: a long run of letters and
+ * digits (a token, a key) and the value after token=, secret=, password= or key=. Steps are read by
+ * the team in the hub, and an agent's commands can carry what its environment holds.
+ */
+export function hideSecrets(text) {
+  return String(text)
+    .replace(/\b((?:[a-z_]*_)?(?:token|secret|password|passwd|api_?key|key))=\S+/gi, "$1=[hidden]")
+    .replace(/\b(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{32,}\b/g, "[hidden]");
+}
+
+const one = (s, max = 140) => {
+  const line =
+    String(s ?? "")
+      .split("\n")
+      .map((l) => l.trim())
+      .find(Boolean) ?? "";
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+
+/** What one tool call does, in words: "Editing src/deals/form.tsx", "Running `npm test`". */
+export function toolStep(name, input = {}, cwd = "") {
+  const path = (p) => {
+    if (!p) return "a file";
+    const r = cwd ? relative(cwd, String(p)) : String(p);
+    return r && !r.startsWith("..") ? r : String(p);
+  };
+  const said = {
+    Read: () => `Reading ${path(input.file_path)}`,
+    Edit: () => `Editing ${path(input.file_path)}`,
+    MultiEdit: () => `Editing ${path(input.file_path)}`,
+    Write: () => `Writing ${path(input.file_path)}`,
+    NotebookEdit: () => `Editing ${path(input.notebook_path)}`,
+    Bash: () => `Running \`${one(input.command, 120)}\``,
+    Grep: () => `Searching for "${one(input.pattern, 80)}"`,
+    Glob: () => `Looking for files: ${one(input.pattern, 80)}`,
+    WebFetch: () => `Reading ${one(input.url, 120)}`,
+    WebSearch: () => `Searching the web for "${one(input.query, 80)}"`,
+    TodoWrite: () => {
+      const now = (input.todos || []).find((t) => t.status === "in_progress");
+      return now ? `Next: ${one(now.activeForm || now.content)}` : "Planning the steps";
+    },
+    Task: () => `Starting a helper: ${one(input.description, 80)}`,
+    Agent: () => `Starting a helper: ${one(input.description, 80)}`,
+    mcp__passalong__progress: () => `Progress: ${one(input.note)}`,
+    mcp__passalong__hand_in: () => `Handing it in${input.pr ? `: ${one(input.pr)}` : ""}`,
+    mcp__passalong__ask: () => `Asking you: ${one(input.question)}`,
+    mcp__passalong__take: () => "Reading the work again",
+    mcp__passalong__save_document: () =>
+      `Writing down what it learned: ${one(input.title || input.path)}`,
+  }[name];
+  if (said) return said();
+  const short = String(name).replace(/^mcp__([^_]+)__/, "$1: ");
+  return `Using ${short}`;
+}
+
+/**
+ * One line the agent printed, as a line of the log and, when it did something, a step.
+ *
+ * Claude Code's stream-json events become sentences: what it says (its first line), each tool it
+ * calls, a tool that failed, and the result at the end. Anything that is not one of those events
+ * (another agent, a crash) is kept as it came, and is a step too: it may be the only sign of why a
+ * run stopped.
+ */
+export function describe(line, cwd = "") {
+  let e;
+  try {
+    e = JSON.parse(line);
+  } catch {
+    const text = hideSecrets(one(line, 300));
+    return { log: text, step: text, usage: usageOut(line) };
+  }
+  if (!e || typeof e !== "object") return { log: hideSecrets(one(line, 300)), step: "" };
+  if (e.type === "system" && e.subtype === "init")
+    return { log: `started${e.model ? ` (${e.model})` : ""}`, step: "" };
+  if (e.type === "assistant") {
+    // Claude Code writes the refusal as a message of its own, marked with what went wrong.
+    if (["rate_limit", "billing_error"].includes(e.error)) {
+      const said = (e.message?.content ?? []).map((c) => c.text || "").join(" ");
+      const text = hideSecrets(one(said || "Claude's usage ran out", 200));
+      return { log: text, step: "", usage: usageOut(said) || { until: 0 } };
+    }
+    const logs = [];
+    const steps = [];
+    for (const c of e.message?.content ?? []) {
+      if (c.type === "text" && c.text?.trim()) {
+        logs.push(hideSecrets(c.text.trim()));
+        steps.push(hideSecrets(one(c.text)));
+      } else if (c.type === "tool_use") {
+        const s = hideSecrets(toolStep(c.name, c.input, cwd));
+        logs.push(s);
+        steps.push(s);
+      }
+    }
+    return { log: logs.join("\n"), step: steps.join("\n") };
+  }
+  if (e.type === "user") {
+    const failed = (e.message?.content ?? []).find((c) => c.type === "tool_result" && c.is_error);
+    if (!failed) return { log: "", step: "" };
+    const why = Array.isArray(failed.content)
+      ? failed.content.map((x) => x.text || "").join(" ")
+      : failed.content;
+    const text = hideSecrets(`That didn't work: ${one(why)}`);
+    return { log: text, step: text };
+  }
+  if (e.type === "result") {
+    const how = e.is_error ? "Stopped with an error" : "Finished";
+    const text = hideSecrets(`${how}${e.result ? `: ${one(e.result, 200)}` : ""}`);
+    // Its whole last message, too: when the work comes back unfinished, this is why.
+    return {
+      log: text,
+      step: text,
+      said: hideSecrets(String(e.result || "").trim()),
+      usage: usageOut(e.result),
+    };
+  }
+  return { log: "", step: "" };
+}
+
+/**
+ * The git checkouts a runner started in `cwd` serves: `cwd`'s own when it is inside one, else every
+ * checkout in the folders under it, three levels down at most. Worktrees, dependencies, hidden
+ * folders and the runner's own run folders are skipped. Those without an `origin` remote are listed
+ * apart, since a run ends by pushing its branch there.
+ */
+export function checkoutsIn(cwd, { git: run = git, depth = 3 } = {}) {
+  const top = (dir) => {
+    try {
+      return run(["-C", dir, "rev-parse", "--show-toplevel"]);
+    } catch {
+      return "";
+    }
+  };
+  const roots = [];
+  const own = top(cwd);
+  if (own) roots.push(own);
+  else {
+    const walk = (dir, left) => {
+      let names = [];
+      try {
+        names = readdirSync(dir);
+      } catch {
+        return;
+      }
+      if (names.includes(".git")) {
+        // A .git file is a worktree of a checkout found elsewhere, not a repo of its own.
+        try {
+          if (statSync(join(dir, ".git")).isDirectory()) roots.push(top(dir) || dir);
+        } catch {}
+        return;
+      }
+      if (!left) return;
+      for (const n of names.sort()) {
+        if (n.startsWith(".") || n === "node_modules" || n.endsWith(".passalong-runs")) continue;
+        const p = join(dir, n);
+        try {
+          if (statSync(p).isDirectory()) walk(p, left - 1);
+        } catch {}
+      }
+    };
+    walk(cwd, depth);
+  }
+  const found = [];
+  const skipped = [];
+  for (const root of roots) {
+    let remote = "";
+    try {
+      remote = run(["-C", root, "remote", "get-url", "origin"]);
+    } catch {}
+    if (remote) found.push({ root, remote });
+    else skipped.push(root);
+  }
+  return { found, skipped };
+}
+
+/** This computer as a person knows it: "Lukman's MacBook Pro" on a Mac, its host name elsewhere. */
+export function machineName() {
+  if (platform() === "darwin") {
+    try {
+      const name = execFileSync("scutil", ["--get", "ComputerName"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+      if (name) return name;
+    } catch {}
+  }
+  return hostname();
+}