passalong 0.18.0 → 0.20.0

package/README.md

@@ -28,7 +28,7 @@ codex mcp add passalong -- passalong mcp   # Codex: the same MCP server
 ## Commands
 
 ```
-passalong share [file] [--to team[/handle]]  publish a guide as a draft → id + link; --to addresses it
+passalong share [file] [--to team[/handle]]  publish a guide → id + link, Ready; --to addresses it
 passalong pull <id|link>      print a guide; --save also writes ./.passalong/<id>.md (git-ignored)
 passalong inbox               guides handed to you that you have not pulled yet
 passalong board               waiting on you, in flight, landed, worth keeping
@@ -73,8 +73,8 @@ passalong inbox                         # on Ada's side: what was handed to you
 passalong activity                      # back on your side: it landed, and who pulled it
 ```
 
-Every guide, whatever its kind, moves the same way: it is a draft until a person marks it Ready
-(`passalong ready <id>`), then whoever takes it (`passalong take <id>`) holds it, hands it in with
+Every guide, whatever its kind, moves the same way: it is Ready when shared (or a draft, with
+`status: draft`, until a person runs `passalong ready <id>`), then whoever takes it (`passalong take <id>`) holds it, hands it in with
 the evidence, and a person approves it or sends it back with the reason (`passalong approve` /
 `passalong reject`).
 

package/bin/passalong

@@ -6,12 +6,11 @@
 //     handed to whoever pulls or starts that guide
 //     TARGET is a team, team/@handle for one person, or "team/#group" for the people who do a
 //     thing — quote that one, since a shell may read the # as a comment
-//   passalong task "<what needs doing>"  write a task for an agent; it waits in Draft
+//   passalong task "<what needs doing>"  write a task for an agent; Ready at once
 //   passalong ready <id...|--all> guides you have read are ready — whoever they are for may take them now
 //   passalong tasks               every task and where it is: draft, ready, claimed, stalled, review
 //   passalong work [--once] [--agent CMD]  run an agent on each ready task here, one after another
-//   passalong approve <id>        the work in review is done, of any kind
-//   passalong reject <id> <why>   not done: back to Ready, and whoever takes it next reads why
+//   passalong reopen <id> <why>   finished work isn't right: back to To do, and whoever takes it next reads why
 //   passalong release <id>        take work back from whoever holds it, of any kind
 //   passalong attach <file>       upload a picture or a file and print the markdown that points at it
 //   passalong reply <id> <text>   write to whoever holds it (--file PATH to attach); or leave a note
@@ -337,9 +336,8 @@ const commands = {
     const id = guide.meta.id;
     console.log(id);
     const target = guide.meta.target_context;
-    console.error(`task "${guide.meta.title}" is in Draft${target ? ` for ${target}` : " (no repo)"}`);
+    console.error(`task "${guide.meta.title}" is Ready${target ? ` for ${target}` : " (no repo)"}`);
     if (guide.meta.team) console.error(`handed to ${guide.meta.team} (team inbox)`);
-    console.error(`when an agent may take it: passalong ready ${id}`);
   },
 
   async tasks() {
@@ -384,16 +382,25 @@ const commands = {
     if (n) console.error("review them with: passalong tasks");
   },
 
-  async approve(f) {
-    const id = f._[0] || die("usage: passalong approve <id>");
-    await passalong.approveTask(id).catch((e) => die(e.message));
-    console.error(`${id} is done`);
+  // Nothing waits for approval now (docs/REVIEW.md): finishing is final. Kept so a script that
+  // calls it is told, not refused.
+  async approve() {
+    console.error(
+      "nothing to approve: finished work is already Done. If it isn't right: passalong reopen <id> <why>",
+    );
+  },
+
+  /** Finished work back to To do, with why at its top; whoever finished it is told. */
+  async reopen(f) {
+    const id = f._[0] || die("usage: passalong reopen <id> <why>");
+    const why = f._.slice(1).join(" ");
+    if (!why) die("say why: passalong reopen <id> <what is wrong>");
+    await passalong.reopen(id, why).catch((e) => die(e.message));
+    console.error(`${id} is back in To do — whoever takes it next reads why`);
   },
 
   async reject(f) {
-    const id = f._[0] || die("usage: passalong reject <id> <why>");
-    await passalong.rejectTask(id, f._.slice(1).join(" ")).catch((e) => die(e.message));
-    console.error(`${id} is back in Ready — the next agent reads why`);
+    return commands.reopen(f);
   },
 
   async release(f) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
   "mcpName": "io.github.codellyson/passalong",
   "keywords": [

package/skill/SKILL.md

@@ -67,8 +67,7 @@ machine, another agent session, or a teammate without your branch.
    follow-up gets the guide it came out of, and where that guide has got to — so write it as a
    note on that work rather than as a standalone brief. What you did or found while working on a
    guide belongs in its `hand_in`, not a follow-up.
-6. **Report** the id (and link) and say it is a **draft**: it reaches nobody until the person reads
-   it and marks it Ready (`passalong ready <id>`, or Ready in the hub). Then one line on how to use
+6. **Report** the id (and link). It is Ready and has reached whoever it is for. Then one line on how to use
    it on the other side: `passalong take <id>` in the target repo, or "take passalong <id>" to an
    agent with the Passalong MCP server. `take` rather than `pull` on purpose: it holds the work as
    well as fetching it, and until somebody takes it the sender cannot tell a guide nobody noticed

package/src/api.js

@@ -429,6 +429,8 @@ export const approveTask = (id) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/approve`, { method: "POST", body: {} });
 export const rejectTask = (id, why) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/reject`, { method: "POST", body: { why } });
+export const reopen = (id, why) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/reopen`, { method: "POST", body: { why } });
 /** A handoff's or bug's approve and send-back. No `place` names the only hand-in there is. */
 export const closeGuide = (id) =>
   call(`/v1/guides/${encodeURIComponent(id)}/close`, { method: "POST", body: {} });

package/src/guide.js

@@ -497,7 +497,9 @@ export function stamp(guide, defaults = {}) {
   const meta = { ...guide.meta };
   if (!meta.id) meta.id = newId();
   if (!meta.created) meta.created = new Date().toISOString();
-  if (!meta.status) meta.status = "draft";
+  // Ready unless whoever wrote it said draft: a guide sent to someone is meant to reach them, and
+  // drafts were where addressed work sat forgotten (every draft in production on 2026-10-15).
+  if (!meta.status) meta.status = "published";
   for (const [k, v] of Object.entries(defaults))
     if (meta[k] === undefined || meta[k] === "") meta[k] = v;
   return { meta, body: guide.body };
@@ -525,8 +527,7 @@ export function bugGuide({
   area = "",
   report = "",
   environment = "",
-  // A draft like every new guide: it reaches people when a person marks it Ready.
-  status = "draft",
+  status = "published",
   evidence = [],
 } = {}) {
   /**
@@ -617,7 +618,7 @@ export function template(meta = {}) {
       summary: "",
       author: "",
       source_context: "",
-      status: "draft",
+      status: "published",
       stack_assumptions: [],
       tags: [],
       ...meta,
@@ -655,7 +656,7 @@ function bugTemplate(meta = {}) {
       kind: "bug",
       author: "",
       source_context: "",
-      status: "draft",
+      status: "published",
       severity: "s3",
       stack_assumptions: [],
       tags: ["bug"],
@@ -697,7 +698,7 @@ function taskTemplate(meta = {}) {
       author: "",
       source_context: "",
       target_context: "",
-      status: "draft",
+      status: "published",
       stack_assumptions: [],
       tags: [],
       ...meta,

package/src/hooks.js

@@ -21,28 +21,47 @@ const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
 /**
  * What this worktree's agent holds and what is waiting, as a few lines for an agent to read.
  * Empty when there is nothing to say, so a session in an unrelated repo is not told anything.
+ *
+ * `held` is a list: an agent may hold several things, and several sessions in one worktree are one
+ * agent to the queue. So a session is told what the worktree holds, and to carry on only with what
+ * was its own before a restart — never to resume another session's work.
  */
-export function nowText({ held, waiting = {} }) {
-  if (held) {
+export function nowText({ held = [], waiting = {} }) {
+  if (held.length === 1) {
+    const [h] = held;
     const lines = [
       // `kind` is required on what /v1/working sends. The `|| "task"` that used to be here was
       // both dead and wrong — absent has meant transfer since kinds existed, never task.
-      `Passalong: You hold ${held.id} (${held.kind}): ${held.title || held.id}.`,
+      `Passalong: This worktree holds ${h.id} (${h.kind}): ${h.title || h.id}.`,
     ];
-    if (held.note) lines.push(`Last note: "${held.note}".`);
+    if (h.note) lines.push(`Last note: "${h.note}".`);
     // The one thing here that is new information rather than a reminder: the person has written, and
     // nothing else in the session will say so until the agent next checks in.
-    if (held.replies)
+    if (h.replies)
       lines.push(
-        `${plural(held.replies, "message", "messages")} from the person ${held.replies === 1 ? "is" : "are"} ` +
-          `waiting for you: call take ${held.id} to read ${held.replies === 1 ? "it" : "them"} before anything else.`,
+        `${plural(h.replies, "message", "messages")} from the person ${h.replies === 1 ? "is" : "are"} ` +
+          `waiting: call take ${h.id} to read ${h.replies === 1 ? "it" : "them"} before anything else.`,
       );
-    if (held.state === "stalled")
+    if (h.state === "stalled")
       lines.push("It is marked stalled: nobody has heard from its agent in 30 minutes.");
     lines.push(
-      `To carry on, call take ${held.id} (it resumes what you hold), then progress at each ` +
-        "milestone. When it is done, hand_in with evidence — what you ran and what came back — " +
-        "so keep it as you go; if it is not yours or you are stuck, pass with the reason.",
+      `If it was yours before this session restarted, call take ${h.id} to carry on, then ` +
+        "progress at each milestone. When it is done, hand_in with evidence — what you ran and " +
+        "what came back — so keep it as you go; if it is not yours or you are stuck, pass with " +
+        "the reason. If another session here is on it, leave it to that session.",
+    );
+    return lines.join("\n");
+  }
+  if (held.length > 1) {
+    const lines = [`Passalong: This worktree holds ${held.length} things:`];
+    for (const h of held)
+      lines.push(
+        `- ${h.id} (${h.kind}): ${h.title || h.id}${h.state === "stalled" ? " — stalled" : ""}` +
+          `${h.replies ? ` — ${plural(h.replies, "message", "messages")} waiting` : ""}`,
+      );
+    lines.push(
+      "Several sessions may be working here. Carry on only with what was yours before this " +
+        "session restarted (take <id> resumes it) and leave the rest to the sessions on them.",
     );
     return lines.join("\n");
   }
@@ -59,19 +78,22 @@ export function nowText({ held, waiting = {} }) {
  * Whether a session may stop. `input` is what Claude Code sends the Stop hook on stdin. Null lets
  * it stop; an object is the hook's answer, blocking once with what to call. `stop_hook_active`
  * means this stop is already the session continuing because of this hook, and blocking again
- * would leave it no way to end.
+ * would leave it no way to end. The hook cannot tell which session took what, so it names
+ * everything still open here and lets the session settle its own.
  */
-export function stopVerdict({ held, input = {} }) {
+export function stopVerdict({ held = [], input = {} }) {
   // An agent that asked a question was told to stop and wait, so it must be let: blocking it would
   // make the instruction and the hook contradict each other, and the agent would pick one.
-  if (!held || held.asking || input.stop_hook_active) return null;
+  const open = held.filter((h) => !h.asking);
+  if (!open.length || input.stop_hook_active) return null;
+  const ids = open.map((h) => h.id).join(", ");
   return {
     decision: "block",
     reason:
-      `You still hold ${held.id}: ${held.title || held.id}. Before ending, do one of: ` +
-      `hand_in ${held.id} with your evidence if it is done; pass ${held.id} with the reason if ` +
-      `it is not yours or you are stuck; or, if the user is stopping mid-way, progress ${held.id} ` +
-      "with a note saying what is left — then end.",
+      `This worktree still holds ${ids}. For anything there you worked on in this session, do ` +
+      "one of before ending: hand_in it with your evidence if it is done; pass it with the reason " +
+      "if it is not yours or you are stuck; or, if the user is stopping mid-way, progress it with " +
+      "a note saying what is left. Leave what other sessions are on — then end.",
   };
 }
 
@@ -112,15 +134,19 @@ const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
  * `needs` counts everything waiting on the person: work handed in for review, agents stuck on
  * them, and guides handed to them.
  */
-export function statusText({ held, needs = 0, ready = 0 }) {
+export function statusText({ held = [], needs = 0, ready = 0 }) {
   const parts = [];
-  if (held) {
-    const said = held.note ? ` "${clip(held.note, 32)}"` : "";
-    parts.push(`▸ ${held.id}${held.state === "stalled" ? " (stalled)" : ""}${said}`);
+  if (held.length === 1) {
+    const [h] = held;
+    const said = h.note ? ` "${clip(h.note, 32)}"` : "";
+    parts.push(`▸ ${h.id}${h.state === "stalled" ? " (stalled)" : ""}${said}`);
+  } else if (held.length > 1) {
+    const stalled = held.filter((h) => h.state === "stalled").length;
+    parts.push(`▸ ${held.length} held${stalled ? ` (${stalled} stalled)` : ""}`);
   } else parts.push("passalong");
   if (needs) parts.push(`${needs} need${needs === 1 ? "s" : ""} you`);
   if (ready) parts.push(`${ready} ready`);
-  if (parts.length === 1 && !held) parts.push("clear");
+  if (parts.length === 1 && !held.length) parts.push("clear");
   return parts.join(" · ");
 }
 

package/src/mcp.js

@@ -297,15 +297,16 @@ export function buildServer() {
         "to act. It is what the person sees first in their hub; the document is behind it. A guide " +
         "with no summary is refused.\n" +
         "SAY WHICH KIND IT IS. There is no default: a guide with no `kind:` line is refused, and so " +
-        "is a spelling that is not one of the three. EVERY NEW GUIDE IS A DRAFT, whatever its kind: " +
-        "it reaches nobody until a person reads it and marks it Ready, and every kind then moves the " +
-        "same way — Ready, taken, handed in, approved. " +
+        "is a spelling that is not one of the three. A NEW GUIDE IS READY: it reaches whoever it is " +
+        "for at once. Say `status: draft` only when the person should read it first — something you " +
+        "are unsure of — and tell them; plan_tasks drafts for you. Every kind moves the same way — " +
+        "Ready, taken, handed in, approved. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
         "It has no Steps: work out how to reach Goal within Constraints, leave Out of scope " +
         "alone, and treat Acceptance as the definition of done. A proposal awaiting a team decision " +
-        "stays Draft until a person makes it Ready. hand_in with `markdown`: a " +
-        "transfer guide about what you did (guide_template kind transfer shows the shape) — its " +
-        "author reviews it against Acceptance.\n" +
+        "stays Draft until a person makes it Ready. hand_in when every Acceptance line holds: it is " +
+        "final — the task goes to Done with what you showed, and nobody reviews it after you — so " +
+        "show it, and say anything you had to adapt in `writeup` (500 characters).\n" +
         `kind: transfer (or no kind: line) is a finished implementation to repeat here. Sections: ${SECTIONS.join(", ")}. ` +
         "Follow its Steps, adapting anything marked ASSUMES to this codebase; run its " +
         "Verification, then hand_in with ok and, when it failed, a note saying what went wrong.\n" +
@@ -333,8 +334,8 @@ export function buildServer() {
         "session into a guide (guide_template kind transfer shows the shape) and call " +
         "publish_guide, with `to` as team, team/@handle for one teammate, or team/#group for the " +
         "people who do a thing. " +
-        "BEFORE PUBLISHING ANYTHING, CHECK WHAT IS ALREADY OPEN: call take with no id, or read the " +
-        "inbox, and see what you hold. If this session's work answers something you hold, hand_in " +
+        "BEFORE PUBLISHING ANYTHING, CHECK WHAT IS ALREADY OPEN: call board (it lists what this " +
+        "worktree holds) or read the inbox. If this session's work answers something you hold, hand_in " +
         "that — never publish a second guide about it. A transfer guide is for work that has to " +
         "cross a boundary: another repo, another machine, a teammate without your branch. Work you " +
         "committed and pushed where the team can already see it has crossed no boundary, and a " +
@@ -943,12 +944,17 @@ export function buildServer() {
         "The state of this user's transfers as queues: waiting on you (handed to you, not " +
         "pulled), not working (someone gave it a failing verdict — the most urgent), in flight " +
         "(handed over, nobody has taken it — `stale` means it has sat over a week), and landed " +
-        "(someone else has it). Use it to answer 'what is outstanding?'.",
+        "(someone else has it), and `held`: what this worktree's agents hold now. Use it to answer " +
+        "'what is outstanding?' and to see what you hold, without taking anything.",
       inputSchema: {},
     },
     async () => {
       try {
-        return json(await passalong.board());
+        const [board, now] = await Promise.all([
+          passalong.board(),
+          passalong.now().catch(() => ({ held: [] })),
+        ]);
+        return json({ ...board, held: now.held });
       } catch (err) {
         return fail(err);
       }
@@ -1084,7 +1090,7 @@ export function buildServer() {
         const ids = await passalong.planTasks(steps, { cwd: cwd || process.cwd() });
         return json({
           drafts: ids.map((id, i) => ({ id, title: steps[i].title, after: steps[i].after || [] })),
-          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
+          next: `all in Draft: ask the user to read them and mark them Ready on the board at ${api.baseUrl()}/hub/work, or run \`passalong ready --all\``,
         });
       } catch (err) {
         return fail(err);
@@ -1099,9 +1105,9 @@ export function buildServer() {
       annotations: ADDS,
       description:
         "Say you are doing it, and get it. With `id`, that guide — any kind: a task, a bug, a " +
-        "handoff. With no id, the next thing waiting for this worktree's agent. While you hold it " +
-        "no other agent can take it here, and its sender sees you are on it. One thing at a time: " +
-        "if you already hold something, finish or pass that first. If somebody else has it, the " +
+        "handoff. With no id, the next thing waiting — always something new, never what you hold. " +
+        "While you hold it no other agent can take it here, and its sender sees you are on it. You " +
+        "may hold several at once; the person watches them on the board. If somebody else has it, the " +
         "answer says who — tell the user rather than doing the work twice. Every answer ends with " +
         "what to call next.",
       inputSchema: {
@@ -1157,7 +1163,7 @@ export function buildServer() {
       outputSchema: handInOut,
       annotations: ADDS,
       description:
-        "Done here, with proof, sorted against the line it answers. Send `checks`: one entry per " +
+        "Finished here, with proof. IT IS FINAL: the work goes to Done with what you showed, and nobody reviews it after you (anyone can reopen it with a reason). So SHOW IT: a screenshot for anything with a screen — before and after, for a bug — or, for backend work, the one command and the line of its output that shows it works. Send `checks`: one entry per " +
         "line the guide asks for — `## Acceptance` on a task, `## Verification` on a handoff or a " +
         "bug — each with that line and the evidence for it. That is what its author reads, line " +
         "against line, instead of hunting through a wall of output for the part that answers each " +
@@ -1165,8 +1171,7 @@ export function buildServer() {
         "command proves it: the command is run here before the hand-in lands, a non-zero exit " +
         "refuses it, and what it printed is recorded instead of your account of it. Use `ran` for " +
         "a check no command can settle. `evidence` as one block is the older shape and still " +
-        "works. A task also takes `markdown`, a transfer guide about what you did and decided — " +
-        "this publishes it and attaches it. A handoff or a bug takes `ok`, whether its " +
+        "works. A task needs no write-up guide any more. A handoff or a bug takes `ok`, whether its " +
         "Verification held here, and `note` saying what went wrong when it did not. DO NOT " +
         "publish a guide to carry your evidence: it belongs on this call, and a second document " +
         'titled "Hand-in evidence" is the thing `checks` exists to replace. If it worked but you ' +
@@ -1242,10 +1247,10 @@ export function buildServer() {
           .string()
           .optional()
           .describe(
-            "handoff or bug: what you had to adapt to make it work here — a version, a name, a " +
-              "step that needed something the guide does not mention. Prose, and optional: leave " +
-              "it out when it worked as written. The next person to open the guide is shown it, " +
-              "which is why it does not need to be a guide of its own",
+            "what you had to adapt to make it work here — a version, a name, a step that needed " +
+              "something the guide does not mention. 500 characters at most; anything longer " +
+              "belongs in the change. Optional: leave it out when it worked as written. The next " +
+              "person to open the guide is shown it",
           ),
         risk: z
           .string()
@@ -1259,11 +1264,11 @@ export function buildServer() {
         markdown: z
           .string()
           .optional()
-          .describe("task: the write-up; start from guide_template kind transfer"),
+          .describe("older shape, not needed: say what you adapted in `writeup` instead"),
         report: z
           .string()
           .optional()
-          .describe("task, instead of markdown: id of a write-up already published"),
+          .describe("older shape, not needed: say what you adapted in `writeup` instead"),
         pr: z.string().optional().describe("task: PR or branch link, when there is one"),
         cwd: z
           .string()
@@ -1525,8 +1530,8 @@ export function buildServer() {
       title: "Publish guide",
       annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
       description:
-        "Publish a guide from markdown (frontmatter + sections). Check what you hold first (take " +
-        "with no id): if this session answers something you hold, hand_in that instead, and if the " +
+        "Publish a guide from markdown (frontmatter + sections). Check what you hold first " +
+        "(board): if this session answers something you hold, hand_in that instead, and if the " +
         "work never left a branch the team can see, publish what is still open as a bug or a task " +
         "rather than a write-up of the fix. A transfer guide by default, or " +
         "a single bug with `kind: bug`; use file_bugs for more than one; or a task for work nobody " +
@@ -1579,7 +1584,8 @@ export function buildServer() {
           ...(guide.meta.status === "draft"
             ? {
                 status: "draft",
-                next: `in Draft: ask the user to read it, then run \`passalong ready ${guide.meta.id}\``,
+                // The hub page, never the share link: the share page has no Ready button.
+                next: `in Draft: ask the user to read it and mark it Ready at ${api.baseUrl()}/hub/g/${guide.meta.id}, or run \`passalong ready ${guide.meta.id}\``,
               }
             : {}),
         });
@@ -1677,11 +1683,7 @@ export function buildServer() {
           { title: title || "", environment: environment || "", issues },
           { cwd: cwd || process.cwd(), to },
         );
-        return json({
-          ...filed,
-          // Filed is not sent: every bug is a draft until a person reads it.
-          next: "all in Draft: ask the user to read them, then run `passalong ready --all`",
-        });
+        return json(filed);
       } catch (err) {
         return fail(err);
       }

package/src/passalong.js

@@ -78,12 +78,6 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   ];
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
-  // Every guide is a draft when it is first shared, whatever its kind: Draft is where it waits
-  // until a person says it is ready — `ready()` — and an agent that writes one over MCP comes
-  // through here too, so publishing on share would let it reach people with nobody reading it.
-  // Sharing *is* putting it in Draft, so a new guide that names no status says so here; one already
-  // published keeps what its document says.
-  if (!guide.meta.status) guide = { ...guide, meta: { ...guide.meta, status: "draft" } };
 
   // The server is where a guide lives; nothing is kept on this machine.
   needsSync("sharing a guide");
@@ -270,7 +264,7 @@ export async function tasks() {
 }
 
 /**
- * Take the next task for this worktree's repo, or get back the one this worktree already holds.
+ * Take the next task for this worktree's repo — always a new one, since an agent may hold several.
  * `null` when there is nothing to do. Written to `.passalong/<id>.md` only when `save` asks.
  */
 export async function nextTask({ cwd = process.cwd(), any = false, save = false } = {}) {
@@ -548,7 +542,7 @@ export async function ask(id, question, { cwd = process.cwd() } = {}) {
 
 /**
  * What this worktree's agent holds right now, and what is waiting for it: what the session-start
- * and stop hooks read (src/hooks.js). `held` is null when it holds nothing. Counts are best effort
+ * and stop hooks read (src/hooks.js). `held` lists everything it holds, empty when nothing. Counts are best effort
  * — a hook must never fail a session over a count.
  */
 export async function now({ cwd = process.cwd() } = {}) {
@@ -563,8 +557,7 @@ export async function now({ cwd = process.cwd() } = {}) {
     api.handedIn(),
   ]);
   if (w.status === "rejected") throw w.reason;
-  const held =
-    (who.agent && w.value.working.find((x) => x.agent === who.agent && x.by?.you)) || null;
+  const held = who.agent ? w.value.working.filter((x) => x.agent === who.agent && x.by?.you) : [];
   const tasks = t.status === "fulfilled" ? t.value.tasks : [];
   const waiting = {
     ready: tasks.filter((x) => x.state === "ready" && x.target === who.repo).length,
@@ -583,6 +576,14 @@ export async function now({ cwd = process.cwd() } = {}) {
   return { held, waiting, needs: review + handed + waiting.inbox, agent: who.agent };
 }
 
+/** Finished work back to To do, with why (docs/REVIEW.md §4). */
+export async function reopen(id, why) {
+  needsSync("reopening work");
+  if (!String(why || "").trim())
+    throw new PassalongError("say why: whoever takes it next reads it");
+  return api.reopen(await resolveId(id), why);
+}
+
 /**
  * The gate, a person's three answers to a task. Approve: the work in review is done. Reject: it
  * goes back to Ready with `why` on it for the next agent. Release: a task an agent holds, live or
@@ -1046,10 +1047,13 @@ export async function planTasks(steps, { cwd = process.cwd() } = {}) {
     ].join("\n");
     // The summary is the step's own, said by whoever planned it: it is what a person reads about the
     // task, and this builds the document without guessing one (the server refuses a task without).
+    // A plan is the case Draft is for: several tasks at once, which a person reads before any of
+    // them runs. Stated here, by the code that knows it is building one.
     const meta = {
       title: step.title,
       summary: step.summary,
       kind: "task",
+      status: "draft",
       target_context: step.target_context ?? repo,
     };
     const after = (step.after || []).map((j) => ids[j]);
@@ -1094,9 +1098,8 @@ export function workPrompt(t) {
  * hand_in land on the claim this took. `agent` is a command the prompt is appended to;
  * `claude -p` by default, or whatever PASSALONG_AGENT says.
  *
- * An agent that exits without finishing stops the loop. Asking for the next task would hand the
- * same one back, since a worktree holds one task at a time, and the loop would run the agent on it
- * forever. The task stays claimed here, for the next run to resume or a person to release.
+ * An agent that exits without finishing stops the loop, rather than piling up half-done work. The
+ * task stays claimed here, for a person to see on the board and resume (take it) or release.
  */
 export async function work({
   cwd = process.cwd(),
@@ -1117,8 +1120,9 @@ export async function work({
       stdio: "inherit",
       env: { ...process.env, PASSALONG_TASK: t.id },
     });
+    // Finishing is final, so a finished task is Done; "review" is a server from before that.
     const state = (await tasks()).find((x) => x.id === t.id)?.state;
-    if (state !== "review")
+    if (state !== "done" && state !== "review")
       return {
         finished,
         stopped: "unfinished",

package/src/update.js

@@ -15,7 +15,31 @@
 // feature would have shipped dead while looking fine in review. So the line is read from a file and
 // the file is refreshed by a process nobody waits for. What a person sees is a day old at worst,
 // which is the right age for "there is a new version".
-import { readConfig, writeConfig } from "./store.js";
+//
+// The answer is kept in its own file, never in config.json. The refresh runs beside whatever
+// 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 { HOME } from "./store.js";
+
+const FILE = join(HOME, "update.json");
+
+function readUpdate() {
+  try {
+    return JSON.parse(readFileSync(FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeUpdate(held) {
+  if (!existsSync(HOME)) mkdirSync(HOME, { recursive: true, mode: 0o700 });
+  const tmp = `${FILE}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(held)}\n`, { mode: 0o600 });
+  renameSync(tmp, FILE);
+}
 
 /** How long a cached answer lasts before a refresh is worth starting. */
 export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
@@ -70,7 +94,7 @@ export function cachedNotice({
   current,
   now = Date.now(),
   env = process.env,
-  config = readConfig,
+  config = readUpdate,
 }) {
   if (env.PASSALONG_NO_UPDATE_CHECK === "1") return { notice: "", stale: false };
   const held = config();
@@ -90,7 +114,7 @@ export function cachedNotice({
  * trying again — `cachedNotice` reads an empty `update_latest` as a failure and uses the shorter
  * gap.
  */
-export async function refresh({ now = Date.now(), fetchImpl = fetch, save = writeConfig } = {}) {
+export async function refresh({ now = Date.now(), fetchImpl = fetch, save = writeUpdate } = {}) {
   let latest = "";
   try {
     const res = await fetchImpl(REGISTRY, {