passalong 1.1.0 → 1.2.0

package/README.md

@@ -51,8 +51,9 @@ passalong archive <id>        off the board and out of the free tier's count
 passalong rm <id>             delete it
 passalong attach <file>       upload a picture or file and print the markdown that points at it
 passalong work [--once] [--agent CMD]  run an agent on each piece of ready work here, in turn
-passalong work --watch        the runner: work a person marked safe to run alone, up to 3 at once
-                              and 10 a day, each in its own worktree, finished as a pull request
+passalong work --watch        the runner, in a repo or a folder of repos: work a person marked safe
+                              to run alone, up to 3 at once and 10 a day, each in its own worktree,
+                              finished as a pull request; each agent's steps show in the hub
 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,7 +22,7 @@
 //   passalong rm <id>             delete it
 //   passalong attach <file>       upload a picture or a file and print the markdown that points at it
 //   passalong work [--once] [--agent CMD]  run an agent on each piece of ready work here, one after another
-//   passalong work --watch [--every SECS]  the runner: keep taking work marked safe to run alone,
+//   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
 //   passalong hub                 open the hub in the browser
 //   passalong export [dir]        dump every piece of work as plain markdown (default ./passalong-export)
@@ -257,24 +257,38 @@ async function statusLine() {
  */
 async function runner(f) {
   const every = Number(f.every) || 60;
-  console.error(
-    "Runner: taking work marked safe to run alone, up to 3 at once and 10 a day, each finished as a " +
-      "pull request. The hub's Work board shows what it is on. Stop it with Ctrl-C: agents running " +
-      "then stop too, and what they held goes back to the queue once it goes quiet.",
-  );
   let idle = false;
+  /** "a, b and 4 more": the repos a runner serves, short enough for one line. */
+  const some = (repos) =>
+    repos.length <= 3 ? repos.join(", ") : `${repos.slice(0, 3).join(", ")} and ${repos.length - 3} more`;
   await passalong
     .watch({
       agent: typeof f.agent === "string" ? f.agent : undefined,
       every,
       cli: fileURLToPath(import.meta.url),
       signals: true,
-      onTask: (t, { dir, branch }) => {
+      // Said only once the folder checked out: a runner that cannot run says why, not what it will do.
+      onStart: ({ repos, skipped }) => {
+        console.error(
+          `Runner for ${repos.length === 1 ? repos[0] : `${repos.length} repos: ${some(repos)}`}.\n` +
+            "It takes work marked safe to run alone, up to 3 at once and 10 a day, and finishes each " +
+            "as a pull request. You can watch each agent here and on the work's page in the hub. " +
+            "Stop it with Ctrl-C: agents running then stop too.",
+        );
+        if (skipped.length)
+          console.error(`Skipped ${skipped.length} checkout${skipped.length === 1 ? "" : "s"} with no origin remote: ${some(skipped)}`);
+      },
+      onTask: (t, { dir, branch, repo }) => {
         idle = false;
-        console.error(`\n→ ${t.id}  ${t.title}\n  on ${branch} in ${dir}`);
+        console.error(`\n→ ${t.id}  ${t.title}\n  ${repo}, on ${branch} in ${dir}`);
       },
-      onIdle: (repo) => {
-        if (!idle) console.error(`waiting for work marked safe to run alone for ${repo || "this repo"}…`);
+      onStep: (t, text) => console.error(`  ${t.id} · ${text}`),
+      onIdle: (repos) => {
+        if (!idle)
+          console.error(
+            `waiting for work marked safe to run alone in ${some(repos)}. ` +
+              "Work with no repo needs one picked on its page in the hub.",
+          );
         idle = true;
       },
       onCapped: (n) =>

package/package.json

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

package/src/api.js

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

package/src/passalong.js

@@ -775,13 +775,18 @@ export async function work({
 
 /**
  * The runner (src/runner.js, docs/LOOP.md §1a): work a person ticked Safe to run alone, each piece in
- * a git worktree of its own beside this checkout, on its own branch, by an agent that finishes with
+ * a 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 worktree is made before asking the queue, because taking work is done by a worktree's agent and
- * the agent that takes it must be the one that does it. When the queue has nothing, the worktree
- * goes again.
+ * 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(),
@@ -795,7 +800,10 @@ export async function watch({
   runAgent = runner.runAgent,
   now = () => Date.now(),
   countFile = join(store.HOME, "runner.json"),
+  machine = runner.machineName,
+  onStart = () => {},
   onTask = () => {},
+  onStep = () => {},
   onIdle = () => {},
   onCapped = () => {},
   onFinished = () => {},
@@ -804,22 +812,32 @@ export async function watch({
   onResumed = () => {},
   onTrouble = () => {},
   report = api.runnerStatus,
+  postSteps = api.workSteps,
+  stepEvery = 5,
   signals = false,
   sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
 } = {}) {
   needsSync("running work");
-  const { root, repo } = context(cwd);
-  if (!root) throw new PassalongError("run the runner inside a git checkout of the repo");
-  let remote = "";
-  try {
-    remote = git(["-C", root, "remote", "get-url", "origin"]);
-  } catch {}
-  if (!remote)
+  const inside = context(cwd).root;
+  const { found, skipped } = runner.checkoutsIn(cwd, { git });
+  if (inside && !found.length)
     throw new PassalongError(
       "this checkout has no `origin` remote: the runner pushes each change to a branch there",
     );
-  const runs = runner.runsDirOf(root);
-  mkdirSync(runs, { recursive: true });
+  if (!found.length)
+    throw new PassalongError(
+      `there's no git checkout in ${cwd} or the folders under it` +
+        (skipped.length ? ` with an \`origin\` remote (${skipped.length} without one)` : "") +
+        ". Start the runner inside a repo, or in the folder that holds your repos.",
+    );
+  const checkouts = found.map(({ root, remote }) => {
+    const runs = runner.runsDirOf(root);
+    mkdirSync(runs, { recursive: true });
+    return { root, runs, repo: context(root).repo || remote, forge: runner.forgeOf(remote) };
+  });
+  const repos = checkouts.map((k) => k.repo);
+  const name = machine();
+  onStart({ repos, skipped });
 
   // What it is on, said to the hub once a minute and whenever it changes (PUT /v1/runner), so
   // nobody has to look at this terminal to know. A failed report never stops a run.
@@ -827,8 +845,9 @@ export async function watch({
   const say = (stopped = false) =>
     Promise.resolve(
       report({
-        host: hostname(),
-        repo,
+        host: name,
+        repo: checkouts.length === 1 ? repos[0] : `${basename(cwd)}/`,
+        repos,
         running: [...onNow].map(([id, title]) => ({ id, title })),
         runs_today: runner.runsToday(countFile, runner.dayOf(now())),
         per_day: perDay,
@@ -847,36 +866,56 @@ export async function watch({
     ? { command: command.trim().split(/\s+/)[0], args: command.trim().split(/\s+/).slice(1) }
     : runner.claudeCommand({ cli });
 
-  /**
-   * One slot: a worktree and a piece of work taken for it, with its agent started. `null` when
-   * nothing waits. The run itself is handed back unawaited, so several go at once.
-   */
-  async function startOne(n) {
+  /** Make the worktree a taken piece of work runs in, as the agent whose id took it. */
+  function worktreeFor(k, dir, id) {
     try {
-      git(["-C", root, "fetch", "--quiet", "origin"]);
+      git(["-C", k.root, "fetch", "--quiet", "origin"]);
     } catch {}
     let base = "HEAD";
     try {
-      base = git(["-C", root, "rev-parse", "--verify", "--quiet", "origin/HEAD"])
+      base = git(["-C", k.root, "rev-parse", "--verify", "--quiet", "origin/HEAD"])
         ? "origin/HEAD"
         : base;
     } catch {}
-    const dir = join(runs, `run-${now()}-${n}`);
-    git(["-C", root, "worktree", "add", "--detach", "--quiet", dir, base]);
+    git(["-C", k.root, "worktree", "add", "--detach", "--quiet", dir, base]);
+    writeFileSync(join(localDir(dir), "agent.json"), `${JSON.stringify({ id }, null, 2)}\n`);
+  }
+
+  /**
+   * One slot: a piece of work taken for one of the repos, its worktree made and its agent started.
+   * `null` when nothing waits in any of them. The run itself is handed back unawaited, so several
+   * go at once. Repos are asked in turn, starting after the last one that had work.
+   */
+  let turn = 0;
+  async function startOne(n) {
     let t = null;
-    try {
-      t = await nextWork({ cwd: dir, alone: true });
-    } catch (err) {
-      onTrouble(err);
-    }
-    if (!t) {
-      git(["-C", root, "worktree", "remove", "--force", dir]);
-      return null;
+    let k = null;
+    let dir = "";
+    let id = "";
+    for (let i = 0; i < checkouts.length && !t; i++) {
+      k = checkouts[(turn + i) % checkouts.length];
+      dir = join(k.runs, `run-${now()}-${n}`);
+      id = randomBytes(12).toString("hex");
+      try {
+        const got = await api.nextTask({
+          agent: id,
+          host: hostname(),
+          repo: k.repo,
+          worktree: dir,
+          alone: true,
+        });
+        t = got?.task || null;
+      } catch (err) {
+        onTrouble(err);
+      }
+      if (t) turn = (turn + i + 1) % checkouts.length;
     }
+    if (!t || !k) return null;
     // Its branch, or a fresh one beside it when that one is still checked out in the worktree of
     // an earlier run that didn't finish (kept for its author), as when a person ticks it again.
     let branch = runner.branchOf(t.id);
     try {
+      worktreeFor(k, dir, id);
       try {
         git(["-C", dir, "switch", "--quiet", "-C", branch]);
       } catch {
@@ -886,39 +925,76 @@ export async function watch({
     } catch (err) {
       // Taken and then stuck before any agent started: never left held with nobody on it.
       const why = runner.passBack({ minutes, failed: err.message.split("\n")[0], dir, branch });
-      await pass(t.id, why, { cwd: dir, runner: true }).catch((e) => onTrouble(e, t));
+      await pass(t.id, why, { cwd: existsSync(dir) ? dir : k.root, runner: true }).catch((e) =>
+        onTrouble(e, t),
+      );
       onPassed(t, { why, dir, log: "" });
       return { run: Promise.resolve() };
     }
     runner.countRun(countFile, runner.dayOf(now()));
     onNow.set(t.id, t.title || t.id);
-    onTask(t, { dir, branch });
+    onTask(t, { dir, branch, repo: k.repo });
     say();
     return {
-      run: finish(t, dir, branch).finally(() => {
+      run: finish(t, k, dir, branch).finally(() => {
         onNow.delete(t.id);
         say();
       }),
     };
   }
 
-  async function finish(t, dir, branch, { resumed = false } = {}) {
-    const log = join(runs, `${t.id}.log`);
+  async function finish(t, k, dir, branch, { resumed = false } = {}) {
+    const log = join(k.runs, `${t.id}.log`);
+    // Steps go to the hub every few seconds rather than one request each: an agent can take a
+    // dozen in a second. Whatever is left goes when the run ends.
+    const pending = [];
+    const flush = async () => {
+      if (!pending.length) return;
+      await postSteps(t.id, pending.splice(0)).catch(() => {});
+    };
+    const step = (text) => {
+      pending.push({ at: new Date(now()).toISOString(), text });
+      onStep(t, text);
+    };
+    step(
+      resumed
+        ? `Carrying on after your answer, on ${name}`
+        : `Started on ${name} in ${k.repo}, on branch ${branch}`,
+    );
+    const timer = setInterval(flush, stepEvery * 1000);
     const ran = await runAgent({
       ...agentRun,
-      prompt: resumed ? runner.resumePrompt(t, branch) : runner.runnerPrompt(t, branch),
+      prompt: resumed
+        ? 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.
+    if (held.state !== "done" && !held.claim?.asking)
+      step("Gave it back unfinished, with the reason on the work. Nothing it changed is lost.");
+    if (held.claim?.asking) step("Waiting for your answer, then it carries on");
+    await flush();
     if (held?.state === "done") {
       try {
-        git(["-C", root, "worktree", "remove", "--force", dir]);
+        git(["-C", k.root, "worktree", "remove", "--force", dir]);
       } catch {}
       onFinished(t, { branch, log });
       return;
@@ -926,7 +1002,7 @@ export async function watch({
     // It stopped to ask, and the question is waiting on a person: not given up. The work stays held
     // here with its worktree, and the run picks up again once they answer (resumeAnswered).
     if (held?.claim?.asking) {
-      waiting.set(t.id, { t, dir, branch });
+      waiting.set(t.id, { t, k, dir, branch });
       onWaiting(t, { question: held.claim.asking, dir });
       return;
     }
@@ -934,9 +1010,9 @@ export async function watch({
       minutes,
       ...ran,
       note: held?.claim?.note || "",
-      said: runner.lastLine(log),
-      dir,
+      said: ran.said || runner.lastLine(log),
       branch,
+      machine: name,
     });
     try {
       await pass(t.id, why, { cwd: dir, runner: true });
@@ -947,15 +1023,15 @@ export async function watch({
   }
 
   const running = new Set();
-  /** Runs stopped on a question, by work id: their worktree and branch, kept to resume in. */
+  /** Runs stopped on a question, by work id: their checkout, worktree and branch, to resume in. */
   const waiting = new Map();
   /** Start an agent again where it stopped: the same worktree, branch and claim. */
-  function resume(t, dir, branch) {
+  function resume(t, k, dir, branch) {
     runner.countRun(countFile, runner.dayOf(now()));
     onNow.set(t.id, t.title || t.id);
     onResumed(t, { dir, branch });
     say();
-    const run = finish(t, dir, branch, { resumed: true })
+    const run = finish(t, k, dir, branch, { resumed: true })
       .catch((err) => onTrouble(err, t))
       .finally(() => {
         onNow.delete(t.id);
@@ -982,9 +1058,9 @@ export async function watch({
       if (row?.state === "done") {
         waiting.delete(id);
         try {
-          git(["-C", root, "worktree", "remove", "--force", w.dir]);
+          git(["-C", w.k.root, "worktree", "remove", "--force", w.dir]);
         } catch {}
-        onFinished(w.t, { branch: w.branch, log: join(runs, `${id}.log`) });
+        onFinished(w.t, { branch: w.branch, log: join(w.k.runs, `${id}.log`) });
         continue;
       }
       if (!row?.claim) {
@@ -996,22 +1072,24 @@ export async function watch({
       if (running.size >= atOnce) return;
       if (runner.runsToday(countFile, runner.dayOf(now())) >= perDay) return;
       waiting.delete(id);
-      resume(w.t, w.dir, w.branch);
+      resume(w.t, w.k, w.dir, w.branch);
     }
   }
 
   // A runner started again finds the questions its earlier runs left waiting: their worktrees are
-  // still beside the checkout, and the work is still held by them.
+  // still beside their checkouts, and the work is still held by them.
   try {
     for (const row of (await api.tasks()).tasks) {
-      const leaf = row.claim?.worktree || "";
-      const dir = leaf.startsWith("run-") ? join(runs, leaf) : "";
-      if (!dir || !existsSync(dir) || row.state === "done") continue;
+      const leaf = basename(row.claim?.worktree || "");
+      if (!leaf.startsWith("run-") || row.state === "done") continue;
+      const k = checkouts.find((x) => existsSync(join(x.runs, leaf)));
+      if (!k) continue;
+      const dir = join(k.runs, leaf);
       let branch = runner.branchOf(row.id);
       try {
         branch = git(["-C", dir, "branch", "--show-current"]) || branch;
       } catch {}
-      waiting.set(row.id, { t: { id: row.id, title: row.title, markdown: "" }, dir, branch });
+      waiting.set(row.id, { t: { id: row.id, title: row.title, markdown: "" }, k, dir, branch });
     }
   } catch {}
 
@@ -1034,7 +1112,7 @@ export async function watch({
         break;
       }
       if (!slot) {
-        if (!running.size) onIdle(repo);
+        if (!running.size) onIdle(repos);
         break;
       }
       const run = slot.run.catch((err) => onTrouble(err)).finally(() => running.delete(run));

package/src/runner.js

@@ -12,8 +12,16 @@
 // Everything that touches git, the clock or a process is passed in, so the tests can run it.
 
 import { execFileSync, spawn } from "node:child_process";
-import { mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import {
+  appendFileSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname, platform } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
 
 /** How many agents at once, how many runs a day, and how long one run may take. */
 export const LIMITS = { atOnce: 3, perDay: 10, minutes: 60 };
@@ -62,6 +70,9 @@ export const PERMISSIONS = {
   ],
 };
 
+/** Where a checkout's origin is hosted, for how a run ends: a pull request or a merge request. */
+export const forgeOf = (remote) => (/gitlab/i.test(String(remote || "")) ? "gitlab" : "github");
+
 /** The branch a piece of work's change goes on. */
 export const branchOf = (id) => `passalong/${id}`;
 
@@ -76,6 +87,11 @@ export function claudeCommand({ node = process.execPath, cli } = {}) {
     command: "claude",
     args: [
       "-p",
+      // One JSON event per line as it works, which the runner turns into the steps a person can
+      // watch from the hub (describe below). Plain -p prints only the final answer, at the end.
+      "--output-format",
+      "stream-json",
+      "--verbose",
       "--permission-mode",
       "dontAsk",
       "--settings",
@@ -88,7 +104,23 @@ export function claudeCommand({ node = process.execPath, cli } = {}) {
 }
 
 /** What the agent is told: the work itself, and how to finish it as a pull request. */
-export function runnerPrompt(t, branch = branchOf(t.id)) {
+export function runnerPrompt(t, branch = branchOf(t.id), { forge = "github" } = {}) {
+  // GitLab has no `gh`: a push option opens the merge request, and git prints its link.
+  const ship =
+    forge === "gitlab"
+      ? [
+          `When it is done, commit what you changed with a message starting "${t.id}: ", then run`,
+          `exactly \`git push -u origin ${branch} -o merge_request.create\`, which opens a merge`,
+          "request and prints its link. Then call hand_in with id " + t.id + ", `pr` set to that",
+          "link (or the commit hash if the push failed, and say why in the note), `note`: one plain",
+        ]
+      : [
+          `When it is done, commit what you changed with a message starting "${t.id}: ", then run`,
+          `exactly \`git push -u origin ${branch}\` and open a pull request with`,
+          `\`gh pr create --fill --head ${branch}\`. Then call hand_in with id ${t.id}, \`pr\` set to the`,
+          "pull request's URL (or the commit hash if the push or the pull request failed, and say why in",
+          "the note), `note`: one plain",
+        ];
   return [
     `You hold passalong work ${t.id}, and no other agent can take it while you do. Here it is:`,
     "",
@@ -98,11 +130,8 @@ export function runnerPrompt(t, branch = branchOf(t.id)) {
     `means, and get there. Call the passalong MCP tool progress with id ${t.id} and a one-line`,
     "status at each milestone; 30 minutes of silence stalls it.",
     "",
-    `When it is done, commit what you changed with a message starting "${t.id}: ", then run`,
-    `exactly \`git push -u origin ${branch}\` and open a pull request with`,
-    `\`gh pr create --fill --head ${branch}\`. Then call hand_in with id ${t.id}, \`pr\` set to the`,
-    "pull request's URL (or the commit hash if the push or the pull request failed, and say why in",
-    "the note), `note`: one plain sentence saying what you did, and `evidence`: what you ran and",
+    ...ship,
+    "sentence saying what you did, and `evidence`: what you ran and",
     "what came back, with the commands and the lines that decided it, the test summary, the commit.",
     "Keep that as you go. What you learned about the project goes into its documents",
     "(save_document). If a call says you no longer hold it, stop.",
@@ -120,6 +149,10 @@ export function runnerPrompt(t, branch = branchOf(t.id)) {
     "If something only a person can do stands between you and done (a permission, a secret), call",
     `progress with id ${t.id} and a note starting "BLOCKED: " that says exactly what you need,`,
     "and stop. The work goes back to the person who wrote it, with that note.",
+    "",
+    "Never call pass yourself. If you stop without hand_in, the runner gives the work back",
+    "unfinished and shows your last message as the reason, so end with what is done and what",
+    "isn't, in plain sentences.",
   ].join("\n");
 }
 
@@ -127,14 +160,14 @@ export function runnerPrompt(t, branch = branchOf(t.id)) {
  * What an agent is told when its run starts again after a person answered its question: read the
  * answer, then finish exactly as the first run was told to.
  */
-export function resumePrompt(t, branch = branchOf(t.id)) {
+export function resumePrompt(t, branch = branchOf(t.id), opts = {}) {
   return [
     `You hold passalong work ${t.id} (${t.title || t.id}), and you stopped earlier to ask the person`,
     `a question. They have answered. Call the passalong MCP tool take with id ${t.id} first: their`,
     "answer comes back with it. Then carry on in this worktree, where your earlier changes are, and",
     "finish as before:",
     "",
-    runnerPrompt({ ...t, markdown: "" }, branch)
+    runnerPrompt({ ...t, markdown: "" }, branch, opts)
       .split("\n")
       .slice(4)
       .join("\n"),
@@ -167,25 +200,44 @@ export function countRun(file, day) {
 /** Where the runs' worktrees and logs live: beside the checkout, never inside it. */
 export const runsDirOf = (root) => join(dirname(root), `${basename(root)}.passalong-runs`);
 
-/** Why a run gave its work back, said to whoever wrote it. */
-export function passBack({ minutes, timedOut, exit, note, said, dir, branch, failed }) {
+/**
+ * Why a run gave its work back, said to whoever wrote it and to the team's channel. It leads with
+ * what the agent itself said at the end, which is nearly always the reason ("Not done: I couldn't
+ * start the app to take the screenshots"). It said "stopped without finishing (exit 0)", which
+ * means nothing to a person, and "the last thing it printed", cut mid-word (2026-11-06).
+ */
+export function passBack({ minutes, timedOut, exit, note, said, branch, failed, machine }) {
   const how = failed
-    ? `couldn't start (${failed})`
+    ? `couldn't start it (${failed})`
     : timedOut
       ? `ran out of its ${minutes} minutes`
-      : `stopped without finishing${exit === undefined || exit === null ? "" : ` (exit ${exit})`}`;
+      : exit === 0
+        ? "ended its run without handing it in"
+        : `stopped with an error${exit === undefined || exit === null || exit === "" ? "" : ` (${typeof exit === "number" ? `exit code ${exit}` : exit})`}`;
+  const words = sentences(note || said, 600);
   return [
-    `The runner's agent ${how}, so this is back with you and no longer marked safe to run alone.`,
-    note ? `Its last note: "${note}".` : "It left no note.",
-    said ? `The last thing it printed: "${said}".` : "",
-    failed
-      ? ""
-      : `What it changed is kept on branch ${branch}, in ${dir}, on the machine that ran it.`,
+    `The runner's agent ${how}.`,
+    words ? `It said: "${words}"` : "It didn't say why.",
+    "It's back in To do and no longer marked safe to run alone, so no runner takes it again until someone ticks it.",
+    failed ? "" : `What it changed is kept on branch ${branch}${machine ? ` on ${machine}` : ""}.`,
   ]
     .filter(Boolean)
     .join(" ");
 }
 
+/** At most `max` characters, ended at a sentence or a word rather than mid-word. */
+export function sentences(text, max) {
+  const one = String(text ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (one.length <= max) return one;
+  const cut = one.slice(0, max);
+  const stop = Math.max(cut.lastIndexOf(". "), cut.lastIndexOf("? "), cut.lastIndexOf("! "));
+  if (stop > max * 0.5) return cut.slice(0, stop + 1);
+  const space = cut.lastIndexOf(" ");
+  return `${(space > max * 0.6 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
 /** The last line an agent printed, from its log: often the reason it stopped. "" when none. */
 export function lastLine(log) {
   try {
@@ -202,24 +254,63 @@ export function git(args) {
 }
 
 /**
- * Start an agent and wait for it, writing what it prints to `log`. Killed after `minutes`.
- * Resolves `{ exit, timedOut }`, never rejects: an agent that would not start is a run that
- * ended without the work done.
+ * Start an agent and wait for it. What it prints is read a line at a time: each becomes a line of
+ * `log` a person can read (Claude Code's JSON events made into sentences, anything else as it came),
+ * and each thing it does is handed to `onStep`. Killed after `minutes`. Resolves
+ * `{ exit, timedOut }`, never rejects: an agent that would not start is a run that ended without
+ * the work done.
  */
-export function runAgent({ command, args, stdin, prompt, cwd, log, minutes, env }) {
-  return new Promise((done) => {
-    const out = openSync(log, "a");
+export function runAgent({
+  command,
+  args,
+  stdin,
+  prompt,
+  cwd,
+  log,
+  minutes,
+  env,
+  onStep = () => {},
+}) {
+  return new Promise((resolve) => {
     let timedOut = false;
     let child;
+    /** What the agent said at the end (Claude Code's result), for why it gave the work back. */
+    let said = "";
+    const done = (r) => resolve({ ...r, said });
+    const write = (text) => {
+      try {
+        appendFileSync(log, `${clock()} ${text}\n`);
+      } catch {}
+    };
     try {
       child = spawn(command, stdin ? args : [...args, prompt], {
         cwd,
         env,
-        stdio: [stdin ? "pipe" : "ignore", out, out],
+        stdio: [stdin ? "pipe" : "ignore", "pipe", "pipe"],
       });
     } catch (err) {
+      write(`couldn't start: ${err.message}`);
       return done({ exit: err.message, timedOut });
     }
+    const reader = () => {
+      let rest = "";
+      return (chunk) => {
+        rest += chunk;
+        const lines = rest.split("\n");
+        rest = lines.pop() ?? "";
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          const d = describe(line, cwd);
+          if (d.said) said = d.said;
+          if (d.log) write(d.log);
+          for (const step of d.step ? d.step.split("\n") : []) onStep(step);
+        }
+      };
+    };
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", reader());
+    child.stderr?.on("data", reader());
     const timer = setTimeout(
       () => {
         timedOut = true;
@@ -229,6 +320,7 @@ export function runAgent({ command, args, stdin, prompt, cwd, log, minutes, env
     );
     child.on("error", (err) => {
       clearTimeout(timer);
+      write(`couldn't start: ${err.message}`);
       done({ exit: err.message, timedOut });
     });
     child.on("close", (code) => {
@@ -241,3 +333,183 @@ export function runAgent({ command, args, stdin, prompt, cwd, log, minutes, env
     }
   });
 }
+
+const clock = () => new Date().toTimeString().slice(0, 8);
+
+/**
+ * Take out what looks like a secret before a line leaves the machine: a long run of letters and
+ * digits (a token, a key) and the value after token=, secret=, password= or key=. Steps are read by
+ * the team in the hub, and an agent's commands can carry what its environment holds.
+ */
+export function hideSecrets(text) {
+  return String(text)
+    .replace(/\b((?:[a-z_]*_)?(?:token|secret|password|passwd|api_?key|key))=\S+/gi, "$1=[hidden]")
+    .replace(/\b(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{32,}\b/g, "[hidden]");
+}
+
+const one = (s, max = 140) => {
+  const line =
+    String(s ?? "")
+      .split("\n")
+      .map((l) => l.trim())
+      .find(Boolean) ?? "";
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+
+/** What one tool call does, in words: "Editing src/deals/form.tsx", "Running `npm test`". */
+export function toolStep(name, input = {}, cwd = "") {
+  const path = (p) => {
+    if (!p) return "a file";
+    const r = cwd ? relative(cwd, String(p)) : String(p);
+    return r && !r.startsWith("..") ? r : String(p);
+  };
+  const said = {
+    Read: () => `Reading ${path(input.file_path)}`,
+    Edit: () => `Editing ${path(input.file_path)}`,
+    MultiEdit: () => `Editing ${path(input.file_path)}`,
+    Write: () => `Writing ${path(input.file_path)}`,
+    NotebookEdit: () => `Editing ${path(input.notebook_path)}`,
+    Bash: () => `Running \`${one(input.command, 120)}\``,
+    Grep: () => `Searching for "${one(input.pattern, 80)}"`,
+    Glob: () => `Looking for files: ${one(input.pattern, 80)}`,
+    WebFetch: () => `Reading ${one(input.url, 120)}`,
+    WebSearch: () => `Searching the web for "${one(input.query, 80)}"`,
+    TodoWrite: () => {
+      const now = (input.todos || []).find((t) => t.status === "in_progress");
+      return now ? `Next: ${one(now.activeForm || now.content)}` : "Planning the steps";
+    },
+    Task: () => `Starting a helper: ${one(input.description, 80)}`,
+    Agent: () => `Starting a helper: ${one(input.description, 80)}`,
+    mcp__passalong__progress: () => `Progress: ${one(input.note)}`,
+    mcp__passalong__hand_in: () => `Handing it in${input.pr ? `: ${one(input.pr)}` : ""}`,
+    mcp__passalong__ask: () => `Asking you: ${one(input.question)}`,
+    mcp__passalong__take: () => "Reading the work again",
+    mcp__passalong__save_document: () =>
+      `Writing down what it learned: ${one(input.title || input.path)}`,
+  }[name];
+  if (said) return said();
+  const short = String(name).replace(/^mcp__([^_]+)__/, "$1: ");
+  return `Using ${short}`;
+}
+
+/**
+ * One line the agent printed, as a line of the log and, when it did something, a step.
+ *
+ * Claude Code's stream-json events become sentences: what it says (its first line), each tool it
+ * calls, a tool that failed, and the result at the end. Anything that is not one of those events
+ * (another agent, a crash) is kept as it came, and is a step too: it may be the only sign of why a
+ * run stopped.
+ */
+export function describe(line, cwd = "") {
+  let e;
+  try {
+    e = JSON.parse(line);
+  } catch {
+    const text = hideSecrets(one(line, 300));
+    return { log: text, step: text };
+  }
+  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") {
+    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()) };
+  }
+  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();
+}