passalong 1.3.0 → 1.5.0

package/README.md

@@ -51,10 +51,6 @@ 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, 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,6 @@
 //   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, 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)
@@ -251,68 +249,6 @@ async function statusLine() {
   }
 }
 
-/**
- * `passalong work --watch`: the runner (src/runner.js). Each piece of work marked safe to run alone
- * gets its own worktree, branch and Claude Code; what it does arrives as a pull request.
- */
-async function runner(f) {
-  const every = Number(f.every) || 60;
-  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,
-      // 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  ${repo}, on ${branch} in ${dir}`);
-      },
-      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;
-      },
-      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, { 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}`),
-    })
-    .catch((e) => die(e.message));
-}
-
 const commands = {
   /**
    * Write work down: a sentence becomes its title, summary and text, or a file is sent as it is. At
@@ -507,7 +443,14 @@ const commands = {
    * files without asking — which is yours to decide, not this command's.
    */
   async work(f) {
-    if (f.watch) return runner(f);
+    // The runner `--watch` started was removed (2026-11-07). Saying so beats running the queue
+    // instead, which is a different thing from what whoever typed `--watch` asked for.
+    if (f.watch) {
+      console.error(
+        "The runner has been removed from Passalong. Open a Claude Code session in your repo and ask it to take work from Passalong instead.",
+      );
+      process.exit(1);
+    }
     const run = await passalong
       .work({
         agent: typeof f.agent === "string" ? f.agent : undefined,
@@ -927,7 +870,22 @@ if (typeof argv.as === "string") {
 // both are caught here, with `version`, before dispatch. Only the number goes to stdout, so
 // `passalong -v` can be read by a script comparing it against the registry.
 if (cmd === "-v" || cmd === "version" || (cmd === "help" && argv.version === true)) {
-  console.log(JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version);
+  const mine = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+  console.log(mine);
+  // Another copy on PATH (npm's beside pnpm's) is the usual reason the version is not the one
+  // expected: updating one leaves the other answering. Said on stderr, so stdout stays the number.
+  try {
+    const { otherCopies } = await import("../src/update.js");
+    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.",
+      );
+  } catch {}
 } else if (cmd === "--help" || cmd === "-h" || cmd === "help") commands.help();
 // A command this build does not have used to print the help page and exit 0, which reads as "that
 // command exists and did nothing" — and the usual cause is an older passalong, where the command is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "1.3.0",
+  "version": "1.5.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

@@ -357,11 +357,6 @@ export const setStatus = (id, status) =>
 export const remove = (id) => call(`/v1/work/${id}`, { method: "DELETE" });
 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/checks.js

@@ -50,8 +50,8 @@ export const CHECK_TIMEOUT_MS = 10 * 60 * 1000;
 export const OUTPUT_MAX = 4000;
 
 /**
- * The tail of what a command printed, because that is where a runner puts what went wrong. A head
- * would hold the banner and the first hundred passing lines.
+ * The tail of what a command printed, because that is where a test runner puts what went wrong. A
+ * head would hold the banner and the first hundred passing lines.
  */
 function tail(out, max = OUTPUT_MAX) {
   const s = String(out ?? "").replace(/\s+$/, "");

package/src/passalong.js

@@ -8,7 +8,6 @@ import { basename, join } from "node:path";
 import * as api from "./api.js";
 import { context } from "./capture.js";
 import { refusal, runChecks } from "./checks.js";
-import * as runner from "./runner.js";
 import * as store from "./store.js";
 import { ID_RE, parse, STATUSES, serialize, stamp, unheldFields, validate } from "./work.js";
 
@@ -219,12 +218,11 @@ function needsSync(what) {
 
 /**
  * Take the next piece of work for this worktree's repo — always a new one, since an agent may hold
- * several. `null` when there is nothing to do. `alone` asks only for work a person marked safe to
- * run unattended (the runner).
+ * several. `null` when there is nothing to do.
  */
-export async function nextWork({ cwd = process.cwd(), any = false, alone = false } = {}) {
+export async function nextWork({ cwd = process.cwd(), any = false } = {}) {
   needsSync("taking work");
-  const { task } = await api.nextTask({ ...agent(cwd), any, ...(alone ? { alone: true } : {}) });
+  const { task } = await api.nextTask({ ...agent(cwd), any });
   return task || null;
 }
 
@@ -263,7 +261,7 @@ function rememberFence(id, fence, cwd) {
   writeFileSync(fenceFile(cwd), `${JSON.stringify(held, null, 2)}\n`);
 }
 
-/** A check a runner executed: the command it ran, and what the process returned. See checks.js. */
+/** A check that was actually run: the command, and what the process returned. See checks.js. */
 const verified = (c) => Boolean(c?.cmd) && (typeof c?.exit === "number" || c?.exit === null);
 
 /**
@@ -327,7 +325,7 @@ export async function handIn(
 ) {
   needsSync("handing work in");
   // A check that names a command is run here, before anything is sent. Checks that already carry
-  // an exit came from the MCP server's own runner and are left alone, so nothing runs twice.
+  // an exit were already run by the MCP server, and are not run again, so nothing runs twice.
   const pending = checks.filter((c) => c?.cmd && typeof c?.exit !== "number" && c?.exit !== null);
   if (pending.length) {
     const done = runChecks(pending, { cwd });
@@ -379,11 +377,9 @@ export async function assign(ref, to) {
 }
 
 /**
- * Not this agent's to do: what it held is open again, and `why` goes to whoever is next. `runner`
- * says the runner is giving it back, unfinished: the server then clears its Safe to run alone tick,
- * so it waits for a person rather than going straight back to an unattended agent.
+ * Not this agent's to do: what it held is open again, and `why` goes to whoever is next.
  */
-export async function pass(id, why, { cwd = process.cwd(), runner = false } = {}) {
+export async function pass(id, why, { cwd = process.cwd() } = {}) {
   needsSync("passing work");
   if (!String(why || "").trim())
     throw new PassalongError("say why you are passing it, so whoever is next knows");
@@ -392,7 +388,6 @@ export async function pass(id, why, { cwd = process.cwd(), runner = false } = {}
     agent: agent(cwd).agent,
     why,
     ...(fence === undefined ? {} : { fence }),
-    ...(runner ? { runner: true } : {}),
   });
 }
 
@@ -737,8 +732,6 @@ export function workPrompt(t) {
  *
  * An agent that exits without finishing stops the loop, rather than piling up half-done work. It
  * stays held here, for a person to see on the board and resume (take it) or release.
- *
- * The runner, which takes work marked safe to run alone with nobody watching, is watch() below.
  */
 export async function work({
   cwd = process.cwd(),
@@ -773,398 +766,6 @@ 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, 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
- * 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,
-  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 = () => {},
-  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 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",
-    );
-  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.
-  const onNow = new Map();
-  const say = (stopped = false) =>
-    Promise.resolve(
-      report({
-        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: 0,
-        at_once: atOnce,
-        stopped,
-      }),
-    ).catch(() => {});
-  // Ctrl-C: the hub hears it stopped. Agents running then stop with it, since they share the
-  // terminal; what they held stays held, and the sweep puts it back once it goes quiet.
-  if (signals)
-    process.once("SIGINT", async () => {
-      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 });
-
-  /** 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", k.root, "fetch", "--quiet", "origin"]);
-    } catch {}
-    let base = "HEAD";
-    try {
-      base = git(["-C", k.root, "rev-parse", "--verify", "--quiet", "origin/HEAD"])
-        ? "origin/HEAD"
-        : base;
-    } catch {}
-    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;
-    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 {
-        branch = `${branch}-${now().toString(36)}`;
-        git(["-C", dir, "switch", "--quiet", "-c", branch]);
-      }
-    } 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: 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, repo: k.repo });
-    say();
-    return {
-      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, 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 === "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", k.root, "worktree", "remove", "--force", dir]);
-      } catch {}
-      onFinished(t, { branch, log });
-      return;
-    }
-    // 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, k, dir, branch });
-      onWaiting(t, { question: held.claim.asking, dir });
-      return;
-    }
-    const why = runner.passBack({
-      minutes,
-      ...ran,
-      note: held?.claim?.note || "",
-      said: ran.said || runner.lastLine(log),
-      branch,
-      machine: name,
-    });
-    try {
-      await pass(t.id, why, { cwd: dir, runner: true });
-      onPassed(t, { why, dir, log });
-    } catch (err) {
-      onTrouble(err, t);
-    }
-  }
-
-  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, { afterPause = false } = {}) {
-    runner.countRun(countFile, runner.dayOf(now()));
-    onNow.set(t.id, t.title || t.id);
-    onResumed(t, { dir, branch, afterPause });
-    say();
-    const run = finish(t, k, dir, branch, { resumed: afterPause ? "usage" : true })
-      .catch((err) => onTrouble(err, t))
-      .finally(() => {
-        if (!paused.has(t.id)) onNow.delete(t.id);
-        running.delete(run);
-        say();
-      });
-    running.add(run);
-  }
-
-  /**
-   * Questions answered since the last look start their run again, while there is a slot and the
-   * day's allowance lasts. Work that was finished, taken back or given away meanwhile is let go.
-   */
-  async function resumeAnswered() {
-    if (!waiting.size) return;
-    let rows = [];
-    try {
-      rows = (await api.tasks()).tasks;
-    } catch (err) {
-      return onTrouble(err);
-    }
-    for (const [id, w] of [...waiting]) {
-      const row = rows.find((x) => x.id === id);
-      if (row?.state === "done") {
-        waiting.delete(id);
-        try {
-          git(["-C", w.k.root, "worktree", "remove", "--force", w.dir]);
-        } catch {}
-        onFinished(w.t, { branch: w.branch, log: join(w.k.runs, `${id}.log`) });
-        continue;
-      }
-      if (!row?.claim) {
-        waiting.delete(id);
-        onTrouble(new Error(`no longer held here; its worktree is kept in ${w.dir}`), w.t);
-        continue;
-      }
-      if (row.claim.asking) continue;
-      if (running.size >= atOnce || paused.size) return;
-      waiting.delete(id);
-      resume(w.t, w.k, w.dir, w.branch);
-    }
-  }
-
-  // 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 || "");
-      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 {}
-      (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;
-  for (;;) {
-    await carryOnPaused();
-    await resumeAnswered();
-    // 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);
-      } catch (err) {
-        onTrouble(err);
-        break;
-      }
-      if (!slot) {
-        if (!running.size) onIdle(repos);
-        break;
-      }
-      const run = slot.run.catch((err) => onTrouble(err)).finally(() => running.delete(run));
-      running.add(run);
-    }
-    // Wait for a run to end or for the next look, whichever is first.
-    await say();
-    await Promise.race([sleep(Math.max(10, every) * 1000), ...running]);
-  }
-}
-
 /**
  * Make every piece of work you wrote that is still in Draft ready, and return their ids. For the
  * moment a planner has written several and you have read them all. Only your own: sending work on

package/src/update.js

@@ -20,8 +20,15 @@
 // command started it, and config.json is read, patched and written whole: a refresh that read it
 // just before `logout` or `use` wrote it, and wrote it back after, put the old accounts and the old
 // default back. This file has one writer, so there is nothing to lose.
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { delimiter, dirname, join } from "node:path";
 import { HOME } from "./store.js";
 
 const FILE = join(HOME, "update.json");
@@ -138,3 +145,41 @@ export async function refresh({ now = Date.now(), fetchImpl = fetch, save = writ
   }
   return latest;
 }
+
+/**
+ * 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 the old one 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 };
+}

package/src/runner.js

@@ -1,591 +0,0 @@
-// The runner: `passalong work --watch` (docs/LOOP.md §1a). Left running with a repo checked out,
-// it takes work a person ticked Safe to run alone and starts Claude Code on each piece, with nobody
-// watching.
-//
-// 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).
-//
-// 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,
-  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, 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
- * nobody to ask: read and edit files in its worktree, use Passalong, run the usual build and test
- * tools, commit, push its own branch and open a pull request. Never push anywhere else, force a
- * push, or throw work away.
- */
-export const PERMISSIONS = {
-  allow: [
-    "Read",
-    "Edit",
-    "Write",
-    "Glob",
-    "Grep",
-    "mcp__passalong",
-    "Bash(git status*)",
-    "Bash(git diff*)",
-    "Bash(git log*)",
-    "Bash(git show*)",
-    "Bash(git add *)",
-    "Bash(git commit *)",
-    "Bash(git push -u origin passalong/*)",
-    "Bash(gh pr create *)",
-    "Bash(gh pr view *)",
-    "Bash(npm *)",
-    "Bash(pnpm *)",
-    "Bash(yarn *)",
-    "Bash(npx *)",
-    "Bash(node *)",
-    "Bash(make *)",
-    "Bash(python *)",
-    "Bash(python3 *)",
-    "Bash(pytest *)",
-    "Bash(go *)",
-    "Bash(cargo *)",
-  ],
-  deny: [
-    "Bash(git push --force*)",
-    "Bash(git push -f*)",
-    "Bash(git push * --force*)",
-    "Bash(git reset --hard*)",
-    "Bash(rm -rf *)",
-  ],
-};
-
-/** 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}`;
-
-/**
- * Claude Code, started for one piece of work: headless, refusing anything not allowed above, and
- * with Passalong's MCP server named here, because `passalong setup` registers it for one folder and
- * 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 } = {}) {
-  return {
-    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",
-      JSON.stringify({ permissions: PERMISSIONS }),
-      "--mcp-config",
-      JSON.stringify({ mcpServers: { passalong: { command: node, args: [cli, "mcp"] } } }),
-    ],
-    stdin: true,
-  };
-}
-
-/** 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), { 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:`,
-    "",
-    String(t.markdown || "").trim(),
-    "",
-    `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.",
-    "",
-    ...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.",
-    "",
-    "Nobody reads what you print: this session runs unattended, and anything not allowed is",
-    "refused rather than asked.",
-    "",
-    "When a decision is the person's to make (which of two layouts, which of three fixes), ask",
-    `them: call ask with id ${t.id}, one clear question, and \`choices\`: two to four options,`,
-    "each with a label and a line of detail. When an option is something to look at, take a",
-    "screenshot of it if you can, upload it with add_file, and give its link as that option's",
-    "`picture`. Then stop. They pick one with a tap in the hub, and you are started again here to",
-    "read their pick (take) and carry on.",
-    "",
-    "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");
-}
-
-/**
- * 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), 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, 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"),
-  ].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: shown, not a limit. */
-export function runsToday(file, day) {
-  try {
-    const s = JSON.parse(readFileSync(file, "utf8"));
-    return s.day === day ? Number(s.runs) || 0 : 0;
-  } catch {
-    return 0;
-  }
-}
-
-export function countRun(file, day) {
-  const runs = runsToday(file, day) + 1;
-  mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, `${JSON.stringify({ day, runs })}\n`);
-  return runs;
-}
-
-/** 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 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 it (${failed})`
-    : timedOut
-      ? `ran out of its ${minutes} minutes`
-      : 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}.`,
-    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 {
-    const lines = readFileSync(log, "utf8").trim().split("\n");
-    return (lines.at(-1) || "").trim().slice(0, 300);
-  } catch {
-    return "";
-  }
-}
-
-/** Run a git command, quietly; its output, trimmed. Throws when git fails. */
-export function git(args) {
-  return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
-}
-
-/**
- * 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,
-  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", "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;
-        child.kill("SIGTERM");
-      },
-      minutes * 60 * 1000,
-    );
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      write(`couldn't start: ${err.message}`);
-      done({ exit: err.message, timedOut });
-    });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      done({ exit: code, timedOut });
-    });
-    if (stdin) {
-      child.stdin.on("error", () => {});
-      child.stdin.end(prompt);
-    }
-  });
-}
-
-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();
-}