passalong 1.2.0 → 1.4.0

package/README.md

@@ -52,8 +52,9 @@ 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, in a repo or a folder of repos: 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; each agent's steps show in the hub
+                              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

@@ -23,7 +23,7 @@
 //   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, in a repo or a folder of repos: 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
+//     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)
@@ -61,6 +61,7 @@ import * as api from "../src/api.js";
 import { workScaffold } from "../src/capture.js";
 import { parse, serialize } from "../src/work.js";
 import * as passalong from "../src/passalong.js";
+import { otherCopies } from "../src/runner.js";
 import * as store from "../src/store.js";
 
 const PKG = resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -271,12 +272,23 @@ async function runner(f) {
       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 10 a day, and finishes each " +
+            "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)}`);
+        // Another copy on PATH (npm's beside pnpm's): updating one leaves the other running.
+        const mine = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+        const { others, shadowed } = otherCopies(fileURLToPath(import.meta.url));
+        for (const o of others)
+          console.error(
+            `! Another passalong${o.version ? ` (${o.version})` : ""} is installed at ${o.path}` +
+              (shadowed && o === others[0]
+                ? `, and it is the one \`passalong\` runs in a new terminal, not this ${mine}.`
+                : `, beside this ${mine}.`) +
+              " Keep one: `npm uninstall -g passalong` or `pnpm remove -g passalong`, whichever installed it.",
+          );
       },
       onTask: (t, { dir, branch, repo }) => {
         idle = false;
@@ -291,12 +303,21 @@ async function runner(f) {
           );
         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.2.0",
+  "version": "1.4.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/passalong.js

@@ -420,6 +420,7 @@ export function needsWhy(t) {
   if (!t.mine) return "";
   if (t.state === "draft") return "in Draft: read it and mark it Ready";
   if (t.state === "stalled") return "its agent went quiet";
+  if (t.state === "review") return "the runner finished it: ready for your review";
   if (t.claim?.asking) return `asking you: ${t.claim.asking}`;
   if (/^BLOCKED:/i.test(t.claim?.note || ""))
     return `stuck on you: ${t.claim.note.replace(/^BLOCKED:\s*/i, "")}`;
@@ -776,8 +777,12 @@ 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 its 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 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.
+ *
+ * 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
@@ -793,7 +798,6 @@ export async function watch({
   agent: command,
   every = 60,
   atOnce = runner.LIMITS.atOnce,
-  perDay = runner.LIMITS.perDay,
   minutes = runner.LIMITS.minutes,
   cli,
   git = runner.git,
@@ -805,7 +809,7 @@ export async function watch({
   onTask = () => {},
   onStep = () => {},
   onIdle = () => {},
-  onCapped = () => {},
+  onPaused = () => {},
   onFinished = () => {},
   onPassed = () => {},
   onWaiting = () => {},
@@ -850,7 +854,7 @@ export async function watch({
         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,
       }),
@@ -862,12 +866,24 @@ export async function watch({
       await Promise.race([say(true), new Promise((r) => setTimeout(r, 2000))]);
       process.exit(130);
     });
-  const agentRun = command
-    ? { command: command.trim().split(/\s+/)[0], args: command.trim().split(/\s+/).slice(1) }
-    : runner.claudeCommand({ cli });
+  /**
+   * The agent's command for one run: `--agent` as given, else Claude Code with what the server's
+   * brief allows it (runner-brief.ts on the server), or this package's own list without one.
+   */
+  const agentRun = (brief) =>
+    command
+      ? { command: command.trim().split(/\s+/)[0], args: command.trim().split(/\s+/).slice(1) }
+      : runner.claudeCommand({
+          cli,
+          ...(brief?.permissions?.allow ? { permissions: brief.permissions } : {}),
+        });
 
-  /** Make the worktree a taken piece of work runs in, as the agent whose id took it. */
-  function worktreeFor(k, dir, id) {
+  /**
+   * Make the worktree a taken piece of work runs in, as the agent whose id took it. Work sent back
+   * from review starts where its last run left off: on its pushed branch, not from scratch, which
+   * would also leave the agent unable to push over its own earlier commits.
+   */
+  function worktreeFor(k, dir, id, workId) {
     try {
       git(["-C", k.root, "fetch", "--quiet", "origin"]);
     } catch {}
@@ -877,6 +893,10 @@ export async function watch({
         ? "origin/HEAD"
         : base;
     } catch {}
+    try {
+      const earlier = `origin/${runner.branchOf(workId)}`;
+      if (git(["-C", k.root, "rev-parse", "--verify", "--quiet", earlier])) base = earlier;
+    } catch {}
     git(["-C", k.root, "worktree", "add", "--detach", "--quiet", dir, base]);
     writeFileSync(join(localDir(dir), "agent.json"), `${JSON.stringify({ id }, null, 2)}\n`);
   }
@@ -903,8 +923,11 @@ export async function watch({
           repo: k.repo,
           worktree: dir,
           alone: true,
+          // So the server's brief ends the run the way this checkout's host takes changes.
+          forge: k.forge,
         });
-        t = got?.task || null;
+        // The brief rides with the work: what to tell its agent, from the server (1.4.0's).
+        t = got?.task ? { ...got.task, brief: got.runner || null } : null;
       } catch (err) {
         onTrouble(err);
       }
@@ -915,7 +938,7 @@ export async function watch({
     // 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);
+      worktreeFor(k, dir, id, t.id);
       try {
         git(["-C", dir, "switch", "--quiet", "-C", branch]);
       } catch {
@@ -937,7 +960,8 @@ export async function watch({
     say();
     return {
       run: finish(t, k, dir, branch).finally(() => {
-        onNow.delete(t.id);
+        // 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();
       }),
     };
@@ -957,16 +981,25 @@ export async function watch({
       onStep(t, text);
     };
     step(
-      resumed
-        ? `Carrying on after your answer, on ${name}`
-        : `Started on ${name} in ${k.repo}, on branch ${branch}`,
+      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);
+    // The server's words when it sent them, with this run's branch filled in; else this package's.
+    const told = (said) => (typeof said === "string" ? said.replaceAll("{branch}", branch) : "");
+    const prompt =
+      resumed === "usage"
+        ? told(t.brief?.paused) || runner.pausedPrompt(t, branch, { forge: k.forge })
+        : resumed
+          ? told(t.brief?.resume) || runner.resumePrompt(t, branch, { forge: k.forge })
+          : told(t.brief?.start) || runner.runnerPrompt(t, branch, { forge: k.forge });
     const ran = await runAgent({
-      ...agentRun,
-      prompt: resumed
-        ? runner.resumePrompt(t, branch, { forge: k.forge })
-        : runner.runnerPrompt(t, branch, { forge: k.forge }),
+      ...agentRun(t.brief),
+      prompt,
+      ...(t.brief?.usage ? { usage: t.brief.usage } : {}),
       cwd: dir,
       log,
       minutes,
@@ -978,9 +1011,12 @@ export async function watch({
     try {
       held = (await api.tasks()).tasks.find((x) => x.id === t.id) || null;
     } catch {}
+    // Handed in: Done, or (from 1.4.0's server on) waiting for a person to approve it or send it
+    // back. Either way this run is over and its branch is pushed.
+    const handedIn = held?.state === "done" || held?.state === "review";
     // 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) {
+    if (!handedIn && !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);
@@ -988,11 +1024,25 @@ export async function watch({
     }
     // 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.
-    if (held.state !== "done" && !held.claim?.asking)
+    // 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 (!handedIn && !held.claim?.asking)
       step("Gave it back unfinished, with the reason on the work. Nothing it changed is lost.");
+    if (held.state === "review")
+      step(
+        "Handed in. It's ready for your review: approve it, or send it back with what to change",
+      );
     if (held.claim?.asking) step("Waiting for your answer, then it carries on");
     await flush();
-    if (held?.state === "done") {
+    if (handedIn) {
       try {
         git(["-C", k.root, "worktree", "remove", "--force", dir]);
       } catch {}
@@ -1025,16 +1075,19 @@ export async function watch({
   const running = new Set();
   /** 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, k, 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, k, 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();
       });
@@ -1069,15 +1122,15 @@ 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.k, w.dir, w.branch);
     }
   }
 
-  // A runner started again finds the questions its earlier runs left waiting: their worktrees are
-  // still beside their checkouts, 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 = basename(row.claim?.worktree || "");
@@ -1089,21 +1142,40 @@ export async function watch({
       try {
         branch = git(["-C", dir, "branch", "--show-current"]) || branch;
       } catch {}
-      waiting.set(row.id, { t: { id: row.id, title: row.title, markdown: "" }, k, 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);

package/src/runner.js

@@ -4,27 +4,39 @@
 //
 // Each piece gets its own git worktree, on a branch of its own, so up to three agents can work at
 // once without touching each other's files, and each one's change arrives as a pull request a
-// person reviews. At most ten runs start in a day. A run that ends without the work done (the agent
-// gave up, said it was blocked, or ran out of time) gives the work back to whoever wrote it, with
-// the agent's last note, and clears its Safe to run alone tick, so it is not tried again unwatched
-// until a person has looked (2026-11-06).
+// person reviews: what it hands in waits for them to approve it or send it back. A run that ends
+// without the work done (the agent gave up, said it was blocked, or ran out of time) gives the work
+// back to whoever wrote it, with the agent's last note, and clears its Safe to run alone tick, so
+// it is not tried again unwatched until a person has looked (2026-11-06). What the agent is told
+// and may run comes from the server with each piece of work (the brief); the copy here is for a
+// server that sends none.
 //
 // 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 {
   appendFileSync,
+  existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   statSync,
   writeFileSync,
 } from "node:fs";
 import { hostname, platform } from "node:os";
-import { basename, dirname, join, relative } from "node:path";
+import { basename, delimiter, 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
@@ -82,7 +94,7 @@ export const branchOf = (id) => `passalong/${id}`;
  * a fresh worktree is another. The server runs in the worktree, so it is that worktree's agent: the
  * one that took the work. The prompt goes in on stdin.
  */
-export function claudeCommand({ node = process.execPath, cli } = {}) {
+export function claudeCommand({ node = process.execPath, cli, permissions = PERMISSIONS } = {}) {
   return {
     command: "claude",
     args: [
@@ -95,7 +107,7 @@ export function claudeCommand({ node = process.execPath, cli } = {}) {
       "--permission-mode",
       "dontAsk",
       "--settings",
-      JSON.stringify({ permissions: PERMISSIONS }),
+      JSON.stringify({ permissions }),
       "--mcp-config",
       JSON.stringify({ mcpServers: { passalong: { command: node, args: [cli, "mcp"] } } }),
     ],
@@ -126,6 +138,10 @@ export function runnerPrompt(t, branch = branchOf(t.id), { forge = "github" } =
     "",
     String(t.markdown || "").trim(),
     "",
+    `First call the passalong MCP tool take with id ${t.id}: it hands you any notes a person left.`,
+    "If this branch already has commits, an earlier run was sent back from review, and those notes",
+    "say what to change: start from what is there and change that, rather than starting over.",
+    "",
     `Do it in this worktree, which is on its own branch, ${branch}. Read it, work out what done`,
     `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.",
@@ -174,13 +190,31 @@ export function resumePrompt(t, branch = branchOf(t.id), opts = {}) {
   ].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"),
+  ].join("\n");
+}
+
 /** Today, as the runner counts days: the machine's own date. */
 export const dayOf = (now) => {
   const d = new Date(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"));
@@ -238,6 +272,49 @@ export function sentences(text, max) {
   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 const USAGE_OUT =
+  "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";
+
+/** The server's pattern when it sent one (the brief), else this copy; a bad one falls back too. */
+function usagePattern(source) {
+  try {
+    return new RegExp(source || USAGE_OUT, "i");
+  } catch {
+    return new RegExp(USAGE_OUT, "i");
+  }
+}
+
+export function usageOut(text, now = Date.now(), pattern = USAGE_OUT) {
+  const s = String(text ?? "").trim();
+  if (!s || s.length > 400) return null;
+  if (!usagePattern(pattern).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 {
@@ -257,7 +334,7 @@ export function git(args) {
  * 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 }`, never rejects: an agent that would not start is a run that ended without
+ * `{ exit, timedOut, said, usage }`, never rejects: an agent that would not start is a run that ended without
  * the work done.
  */
 export function runAgent({
@@ -270,13 +347,16 @@ export function runAgent({
   minutes,
   env,
   onStep = () => {},
+  usage: usageSource = USAGE_OUT,
 }) {
   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 = "";
-    const done = (r) => resolve({ ...r, 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`);
@@ -300,8 +380,9 @@ export function runAgent({
         rest = lines.pop() ?? "";
         for (const line of lines) {
           if (!line.trim()) continue;
-          const d = describe(line, cwd);
+          const d = describe(line, cwd, usageSource);
           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);
         }
@@ -400,18 +481,24 @@ export function toolStep(name, input = {}, cwd = "") {
  * (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 = "") {
+export function describe(line, cwd = "", usage = USAGE_OUT) {
   let e;
   try {
     e = JSON.parse(line);
   } catch {
     const text = hideSecrets(one(line, 300));
-    return { log: text, step: text };
+    return { log: text, step: text, usage: usageOut(line, Date.now(), usage) };
   }
   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, Date.now(), usage) || { until: 0 } };
+    }
     const logs = [];
     const steps = [];
     for (const c of e.message?.content ?? []) {
@@ -439,7 +526,12 @@ export function describe(line, cwd = "") {
     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()) };
+    return {
+      log: text,
+      step: text,
+      said: hideSecrets(String(e.result || "").trim()),
+      usage: usageOut(e.result, Date.now(), usage),
+    };
   }
   return { log: "", step: "" };
 }
@@ -513,3 +605,41 @@ export function machineName() {
   }
   return hostname();
 }
+
+/**
+ * Other copies of passalong on PATH, besides the one at `cli`: their path and version, and whether
+ * one of them comes first, so `passalong` typed in a shell runs it rather than this. npm and pnpm
+ * each keep their own global copy, and updating one left an old runner running from the other
+ * (2026-11-06). Each version is read from the package.json beside the bin's real file.
+ */
+export function otherCopies(cli, { path = process.env.PATH || "" } = {}) {
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return "";
+    }
+  };
+  const versionAt = (file) => {
+    try {
+      return (
+        JSON.parse(readFileSync(join(dirname(file), "..", "package.json"), "utf8")).version || ""
+      );
+    } catch {
+      return "";
+    }
+  };
+  const mine = real(cli);
+  const seen = new Set();
+  const found = [];
+  for (const dir of path.split(delimiter).filter(Boolean)) {
+    const bin = join(dir, process.platform === "win32" ? "passalong.cmd" : "passalong");
+    if (!existsSync(bin)) continue;
+    const file = real(bin);
+    if (!file || seen.has(file)) continue;
+    seen.add(file);
+    found.push({ path: bin, version: versionAt(file), mine: file === mine });
+  }
+  const others = found.filter((f) => !f.mine);
+  return { others, shadowed: found.length > 0 && !found[0].mine };
+}