passalong 1.2.0 → 1.3.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)
@@ -271,7 +271,7 @@ 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.",
         );
@@ -291,12 +291,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.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/passalong.js

@@ -776,8 +776,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 +797,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 +808,7 @@ export async function watch({
   onTask = () => {},
   onStep = () => {},
   onIdle = () => {},
-  onCapped = () => {},
+  onPaused = () => {},
   onFinished = () => {},
   onPassed = () => {},
   onWaiting = () => {},
@@ -850,7 +853,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,
       }),
@@ -937,7 +940,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 +961,21 @@ 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);
     const ran = await runAgent({
       ...agentRun,
-      prompt: resumed
-        ? runner.resumePrompt(t, branch, { forge: k.forge })
-        : runner.runnerPrompt(t, branch, { forge: k.forge }),
+      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,
@@ -988,6 +997,16 @@ 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.
+    // 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");
@@ -1025,16 +1044,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 +1091,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 +1111,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

@@ -23,8 +23,16 @@ import {
 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
@@ -174,13 +182,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 +264,42 @@ 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 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 {
@@ -257,7 +319,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({
@@ -276,7 +338,9 @@ export function runAgent({
     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`);
@@ -302,6 +366,7 @@ export function runAgent({
           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);
         }
@@ -406,12 +471,18 @@ export function describe(line, cwd = "") {
     e = JSON.parse(line);
   } catch {
     const text = hideSecrets(one(line, 300));
-    return { log: text, step: text };
+    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 ?? []) {
@@ -439,7 +510,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),
+    };
   }
   return { log: "", step: "" };
 }