passalong 1.3.0 → 1.4.0

package/bin/passalong

@@ -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)), "..");
@@ -277,6 +278,17 @@ async function runner(f) {
         );
         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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "1.3.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, "")}`;
@@ -865,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 {}
@@ -880,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`);
   }
@@ -906,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);
       }
@@ -918,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 {
@@ -968,14 +988,18 @@ export async function watch({
           : `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 === "usage"
-          ? runner.pausedPrompt(t, branch, { forge: k.forge })
-          : 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,
@@ -987,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);
@@ -1007,11 +1034,15 @@ export async function watch({
       onPaused(t, { until: ran.usage.until ? pauseUntil : 0 });
       return;
     }
-    if (held.state !== "done" && !held.claim?.asking)
+    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 {}

package/src/runner.js

@@ -4,24 +4,28 @@
 //
 // 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, and how long one run may take. There is no count of runs a day: it was
@@ -90,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: [
@@ -103,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"] } } }),
     ],
@@ -134,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.",
@@ -270,15 +278,22 @@ export function sentences(text, max) {
  * 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()) {
+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 (
-    !/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;
+  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 };
@@ -332,6 +347,7 @@ export function runAgent({
   minutes,
   env,
   onStep = () => {},
+  usage: usageSource = USAGE_OUT,
 }) {
   return new Promise((resolve) => {
     let timedOut = false;
@@ -364,7 +380,7 @@ 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);
@@ -465,13 +481,13 @@ 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, usage: usageOut(line) };
+    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")
@@ -481,7 +497,7 @@ export function describe(line, cwd = "") {
     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 } };
+      return { log: text, step: "", usage: usageOut(said, Date.now(), usage) || { until: 0 } };
     }
     const logs = [];
     const steps = [];
@@ -514,7 +530,7 @@ export function describe(line, cwd = "") {
       log: text,
       step: text,
       said: hideSecrets(String(e.result || "").trim()),
-      usage: usageOut(e.result),
+      usage: usageOut(e.result, Date.now(), usage),
     };
   }
   return { log: "", step: "" };
@@ -589,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 };
+}