passalong 0.20.0 → 1.0.0

package/src/passalong.js

@@ -8,28 +8,17 @@ import { basename, join } from "node:path";
 import * as api from "./api.js";
 import { context } from "./capture.js";
 import { refusal, runChecks } from "./checks.js";
-import {
-  bugGuide,
-  ID_RE,
-  parse,
-  STATUSES,
-  serialize,
-  stamp,
-  stripPlaceholders,
-  unheldFields,
-  validate,
-} from "./guide.js";
 import * as store from "./store.js";
+import { ID_RE, parse, STATUSES, serialize, stamp, unheldFields, validate } from "./work.js";
 
 export class PassalongError extends Error {}
 
-/** "team" or "team/handle" → { team, to }. */
 /**
  * Split `--to` into a team and who inside it: "team", "team/@handle", or "team/#group".
  *
  * Only the `@` is stripped. The `#` is load-bearing and travels into the frontmatter as written —
  * it is the sigil the server reads to tell a person from a group, and dropping it here would turn
- * a handoff to six people into a lookup for a teammate who does not exist.
+ * work for six people into a lookup for a teammate who does not exist.
  */
 export function parseTarget(to) {
   if (!to) return {};
@@ -38,142 +27,124 @@ export function parseTarget(to) {
 }
 
 /**
- * Publish a guide from markdown: fill in defaults, validate, store locally, and sync when
- * logged in. `to` addresses it: "team", "team/@handle", or "team/#group". Returns
- * { guide, path, url, synced }.
+ * Store a piece of work from its markdown: fill in what is missing, validate, and send it. `to`
+ * addresses it: "team", "team/@handle", or "team/#group"; with no team it goes to the account's
+ * current one. `parent` names the work it came out of. Returns { work, url, notified }.
  */
-export async function share(markdown, { cwd = process.cwd(), to, follows } = {}) {
+export async function publish(markdown, { cwd = process.cwd(), to, parent } = {}) {
   const c = context(cwd);
-  const raw = parse(markdown);
-  let guide = stamp(
-    { meta: raw.meta, body: stripPlaceholders(raw.body) },
-    {
-      author: c.author,
-      source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
-    },
-  );
+  let work = stamp(parse(markdown), {
+    author: c.author,
+    source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
+  });
   const target = parseTarget(to);
-  if (target.team) guide.meta.team = target.team;
-  if (target.to) guide.meta.to = target.to;
-  if (
-    !guide.meta.team &&
-    (guide.meta.kind === "bug" || guide.meta.kind === "task") &&
-    api.loggedIn()
-  ) {
+  if (target.team) work.meta.team = target.team;
+  if (target.to) work.meta.to = target.to;
+  if (!work.meta.team && api.loggedIn()) {
     const team = api.currentTeam();
-    if (team) guide.meta.team = team;
+    if (team) work.meta.team = team;
   }
-  // `follows` names the guide this one came out of: an id, a share link, or a pulled .md file. An id
-  // is used as it is; a link or a file is read for the id in its own frontmatter. `validate()` below
-  // is what refuses a guide that names itself.
-  if (follows) guide.meta.parent = await resolveId(String(follows).trim());
-  if (guide.meta.to && !guide.meta.team)
-    throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
+  // An id is used as it is; a link or a file is read for the id in its own frontmatter. `validate()`
+  // below is what refuses work that names itself.
+  if (parent) work.meta.parent = await resolveId(String(parent).trim());
+  if (work.meta.to && !work.meta.team)
+    throw new PassalongError("`to:` needs a team — address it as team/@handle");
   const errors = [
     ...unheldFields(markdown).map(
       (k) =>
         `frontmatter "${k}" holds more than a string or a list of strings, and it would be dropped — move it into the body (a fenced yaml block keeps it as written)`,
     ),
-    ...validate(guide),
+    ...validate(work),
   ];
   if (errors.length)
-    throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
+    throw new PassalongError(`this is not ready to send:\n  - ${errors.join("\n  - ")}`);
 
-  // The server is where a guide lives; nothing is kept on this machine.
-  needsSync("sharing a guide");
-  const res = await api.publish(guide.meta.id, serialize(guide));
-  const url = res.url;
-  guide = { ...guide, meta: { ...guide.meta, url } };
-  return { guide, url, synced: true, notified: Boolean(res.notified) };
+  needsSync("sending work");
+  const res = await api.publish(work.meta.id, serialize(work));
+  work = { ...work, meta: { ...work.meta, url: res.url } };
+  return { work, url: res.url, notified: Boolean(res.notified) };
 }
 
 /**
- * File a set of bugs as one report.
- *
- * The report is opened first because each issue's frontmatter names it, and the issues go up one
- * at a time — a partial failure that has filed three of five should say which three, since the
- * three that landed are real guides someone can already act on.
+ * One piece of work or several, written from fields rather than markdown: what an agent hands over
+ * when it writes work down. Each may name the earlier ones it needs by position (`after: [0, 1]`),
+ * and those become its `blocked_by`, so they are handed out in an order that works and the
+ * independent ones run side by side.
  *
- * Unlike `share()`, this needs sync: a report is a server-side parent, and there is nothing local
- * for a set to belong to. One bug on its own does not — that is just `share()` with a bug
- * document, and it works offline like any other guide.
+ * Only earlier ones: work that waits on itself or on a later one never finishes, and it is refused
+ * before anything is written rather than discovered as a queue that never moves. `draft` holds them
+ * all in Draft, for a plan a person should read before any of it runs.
  */
-export async function fileBugs(
-  { title = "", environment = "", issues = [] },
-  { cwd = process.cwd(), to } = {},
-) {
-  if (!issues.length) throw new PassalongError("a report needs at least one issue");
-  if (!api.loggedIn())
-    throw new PassalongError("filing a report needs sync — run `passalong login` first");
-  const target = parseTarget(to);
-  const team = target.team || api.currentTeam();
-  const { report } = await api.createReport({
-    title,
-    environment,
-    team,
-    to: target.to || "",
+export async function createWork(items, { draft = false, to, cwd = process.cwd() } = {}) {
+  if (!Array.isArray(items) || !items.length)
+    throw new PassalongError("say what the work is: at least one item");
+  items.forEach((item, i) => {
+    for (const j of item.after || [])
+      if (!Number.isInteger(j) || j < 0 || j >= i)
+        throw new PassalongError(
+          `item ${i} ("${item.title}") can only wait on an earlier one, not ${j}`,
+        );
   });
-
-  const filed = [];
-  try {
-    for (const issue of issues) {
-      const markdown = bugGuide({ ...issue, report: report.id, environment });
-      const { guide, url } = await share(markdown, { cwd, to });
-      filed.push({
-        id: guide.meta.id,
-        title: guide.meta.title,
-        area: guide.meta.area || "",
-        severity: guide.meta.severity || "",
-        url,
-      });
-    }
-  } catch (err) {
-    if (!filed.length) throw err;
-    throw new PassalongError(
-      `filed ${filed.length} of ${issues.length} issues (${filed
-        .map((f) => f.id)
-        .join(", ")}) before failing: ${err.message}`,
-    );
+  const repo = context(cwd).repo;
+  const made = [];
+  for (const item of items) {
+    const meta = {
+      title: item.title,
+      summary: item.summary,
+      ...(draft ? { status: "draft" } : {}),
+      target_context: item.repo ?? repo,
+      ...(item.tags?.length ? { tags: item.tags } : {}),
+    };
+    const after = (item.after || []).map((j) => made[j].id);
+    if (after.length) meta.blocked_by = after;
+    const { work, url } = await publish(serialize({ meta, body: item.body || "" }), {
+      cwd,
+      to: item.to || to,
+      parent: item.parent,
+    });
+    made.push({ id: work.meta.id, title: work.meta.title, status: work.meta.status, url });
   }
-  return { report: { id: report.id, title, environment, team }, issues: filed };
+  return made;
 }
 
 /**
- * Resolve a reference (id, share URL, or local file path) to a guide. An id is the server's to
- * answer: nothing keeps a copy on this machine. `peek` reads without recording a pull.
+ * Replace a piece of work's text, by its id: the whole document, frontmatter first, as `find_work`
+ * handed it over. What it is called and what it says are both in there.
+ */
+export async function updateText(id, markdown, { cwd = process.cwd() } = {}) {
+  const g = parse(markdown);
+  if (g.meta.id && g.meta.id !== id)
+    throw new PassalongError(`the document says it is ${g.meta.id}, not ${id}`);
+  return publish(serialize({ meta: { ...g.meta, id }, body: g.body }), { cwd });
+}
+
+/**
+ * Resolve a reference (id, share URL, or local file path) to a piece of work. An id is the server's
+ * to answer: nothing keeps a copy on this machine. `peek` reads without recording a pull.
  */
 export async function resolve(ref, { peek = false } = {}) {
   if (/^https?:\/\//.test(ref)) {
     const md = await api.fetchShared(ref);
-    return { guide: parse(md), from: "link" };
+    return { work: parse(md), from: "link" };
   }
   if (ref.endsWith(".md") && existsSync(ref)) {
-    return { guide: parse(readFileSync(ref, "utf8")), from: "file" };
+    return { work: parse(readFileSync(ref, "utf8")), from: "file" };
   }
   if (!ID_RE.test(ref))
     throw new PassalongError(`"${ref}" is not a passalong id, share link, or .md file`);
-  needsSync("reading a guide by id");
+  needsSync("reading work by id");
   try {
-    return { guide: parse(await api.get(ref, { peek })), from: "sync" };
+    return { work: parse(await api.get(ref, { peek })), from: "sync" };
   } catch (err) {
-    if (err.status === 404) throw new PassalongError(`no guide "${ref}"`);
+    if (err.status === 404) throw new PassalongError(`no work "${ref}"`);
     throw err;
   }
 }
 
 /**
- * Resolve a reference to its id alone, without fetching the guide.
- *
- * The reader's two answers — an ack and a verdict — are writes that take an id and nothing else,
- * so the guide body they used to fetch on the way was never read. That fetch was not free:
- * `GET /v1/guides/:id` records a pull, which is how somebody saying "not me" on a handoff
- * registered as taking delivery of it — inflating the guide's pull count and moving it into the
- * sender's "landed" queue. An id needs no lookup at all, and a link or a file carries the id in
- * its own frontmatter.
- *
- * Unlike `resolve()`, a bare id is not checked for existence here. The server answers that when
- * the write lands, and "no such guide" from the route the write went to is the same news one
- * round trip earlier.
+ * Resolve a reference to its id alone, without fetching it. A write needs an id and nothing else,
+ * and `GET /v1/work/:id` records a pull; a link or a file carries the id in its own frontmatter.
+ * A bare id is not checked here: the route the write goes to answers that.
  */
 export async function resolveId(ref) {
   if (/^https?:\/\//.test(ref)) return parse(await api.fetchShared(ref)).meta.id;
@@ -182,18 +153,7 @@ export async function resolveId(ref) {
   throw new PassalongError(`"${ref}" is not a passalong id, share link, or .md file`);
 }
 
-/**
- * Pull a guide and return it, so the caller can put the text straight into an agent's context. A
- * pull of someone else's guide is recorded server-side, which is how the sender sees the transfer
- * landed. Nothing is written unless `save` asks: then it lands in `.passalong/<id>.md` here.
- */
-export async function pull(ref, { cwd = process.cwd(), save = false } = {}) {
-  const { guide, from } = await resolve(ref);
-  const markdown = serialize(guide);
-  return { guide, from, path: save ? saveTo(cwd, guide.meta.id, markdown) : null, markdown };
-}
-
-/** Write a guide into `.passalong/<id>.md` under `cwd`, when somebody asked for a file. */
+/** Write a piece of work into `.passalong/<id>.md` under `cwd`, when somebody asked for a file. */
 function saveTo(cwd, id, markdown) {
   const path = join(localDir(cwd), `${id}.md`);
   writeFileSync(path, markdown);
@@ -203,9 +163,9 @@ function saveTo(cwd, id, markdown) {
 /**
  * `.passalong/` in a working directory, made if it is missing.
  *
- * A pulled guide carries its own share URL in the frontmatter, and that URL needs no account to
- * read. Committing this directory would publish the guide to anyone who can see the repo, so the
- * directory ignores itself. Delete its .gitignore if you do want guides in the repo.
+ * Work saved there carries its own share URL in the frontmatter, and that URL needs no account to
+ * read. Committing this directory would publish it to anyone who can see the repo, so the directory
+ * ignores itself. Delete its .gitignore if you do want it in the repo.
  */
 function localDir(cwd) {
   const dir = join(cwd, ".passalong");
@@ -216,13 +176,12 @@ function localDir(cwd) {
 }
 
 /**
- * Who this worktree is to the task queue, minted the first time it asks.
+ * Who this worktree is to the queue, minted the first time it asks.
  *
  * A claim belongs to an agent, not an account: one person runs several, and "no two agents on one
- * task" means nothing if the server cannot tell them apart. The id lives in the worktree's own
- * `.passalong/agent.json`, so a restarted session in the same worktree is the same agent and gets
- * its task back, and a second worktree of the same repo is a different agent. Per machine would
- * let two worktrees on one laptop share a lock; per session would lose the task on every restart.
+ * piece of work" means nothing if the server cannot tell them apart. The id lives in the worktree's
+ * own `.passalong/agent.json`, so a restarted session in the same worktree is the same agent and
+ * gets its work back, and a second worktree of the same repo is a different agent.
  */
 export function agent(cwd = process.cwd()) {
   const c = context(cwd);
@@ -253,44 +212,24 @@ function knownAgent(cwd = process.cwd()) {
 function needsSync(what) {
   if (!api.loggedIn())
     throw new PassalongError(
-      `${what} needs sync — the queue lives on the server (run \`passalong login\`)`,
+      `${what} needs sync — work lives on the server (run \`passalong login\`)`,
     );
 }
 
-/** Every task you can see, with where it is and who has it. */
-export async function tasks() {
-  needsSync("the task queue");
-  return (await api.tasks()).tasks;
-}
-
 /**
- * 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.
+ * 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).
  */
-export async function nextTask({ cwd = process.cwd(), any = false, save = false } = {}) {
-  needsSync("taking a task");
-  const { task } = await api.nextTask({ ...agent(cwd), any });
-  if (!task) return null;
-  return { ...task, path: save ? saveTo(agent(cwd).worktree, task.id, task.markdown) : null };
-}
-
-/** Word from the agent holding a task: renews its lease, and `note` becomes the board's line. */
-export async function taskProgress(id, note, { cwd = process.cwd() } = {}) {
-  needsSync("reporting progress");
-  const { agent: a } = agent(cwd);
-  return api.taskProgress(id, note ? { agent: a, note } : { agent: a });
+export async function nextWork({ cwd = process.cwd(), any = false, alone = false } = {}) {
+  needsSync("taking work");
+  const { task } = await api.nextTask({ ...agent(cwd), any, ...(alone ? { alone: true } : {}) });
+  return task || null;
 }
 
 /**
- * What a hand-in has to carry, checked before anything is published.
- *
- * The server refuses the call without it anyway; the reason to check first is that publishing the
- * write-up and then being refused leaves a guide nobody asked for behind every refused hand-in.
- * The rule and the wording are the server's — see evidenceProblem() in apps/api/src/claims.ts.
- */
-/**
- * The claim generation this worktree was given when it took a guide, kept in `.passalong/held.json`
- * beside `agent.json`. See apps/api/migrations/0029_claim_fence.sql.
+ * The claim generation this worktree was given when it took a piece of work, kept in
+ * `.passalong/held.json` beside `agent.json`. See apps/api/migrations/0029_claim_fence.sql.
  *
  * The agent never sees this number and is never asked for it — a model echoing an integer back
  * three calls later is not a lock. `take` writes it, and every call that writes to the claim sends
@@ -310,7 +249,7 @@ function heldFences(cwd) {
   }
 }
 
-/** The number this worktree holds for a guide, or undefined when it has none to send. */
+/** The number this worktree holds for a piece of work, or undefined when it has none to send. */
 function fenceFor(id, cwd) {
   const n = heldFences(cwd)[id];
   return Number.isInteger(n) ? n : undefined;
@@ -326,6 +265,10 @@ function rememberFence(id, fence, cwd) {
 /** A check a runner executed: the command it ran, and what the process returned. See checks.js. */
 const verified = (c) => Boolean(c?.cmd) && (typeof c?.exit === "number" || c?.exit === null);
 
+/**
+ * What a hand-in has to carry, checked before it is sent. The rule and the wording are the
+ * server's — see evidenceProblem() in apps/api/src/claims.ts.
+ */
 function requireEvidence(evidence) {
   const said = String(evidence || "").trim();
   if (said.length >= 16) return;
@@ -337,52 +280,20 @@ function requireEvidence(evidence) {
 }
 
 /**
- * The work is done: the task moves to review with a transfer guide about it attached.
- *
- * Pass `markdown` and this writes that guide too, with `parent:` naming the task, so the write-up
- * and the finish are one step and neither can be skipped or pointed at the wrong guide. Pass
- * `report` instead when the guide is already published.
- */
-export async function finishTask(
-  id,
-  { report, markdown, evidence = "", pr = "", note = "", cwd = process.cwd() } = {},
-) {
-  needsSync("finishing a task");
-  requireEvidence(evidence);
-  if (!report && markdown) {
-    const g = parse(markdown);
-    // A task's report is a transfer guide, and this code is what is making one — so it says so
-    // rather than hoping the agent's frontmatter did. Absent is refused now, and refusing an
-    // agent's hand-in because its write-up left a line off would be this function's omission
-    // charged to the agent. Stated, not defaulted: `kind` is the one field here that is not the
-    // author's to leave open, because the caller already knows the answer.
-    report = (
-      await share(serialize({ meta: { ...g.meta, kind: "transfer", parent: id }, body: g.body }), {
-        cwd,
-      })
-    ).guide.meta.id;
-  }
-  if (!report)
-    throw new PassalongError(
-      "finishing needs the write-up: `markdown` for a transfer guide about the work, or `report` with the id of one",
-    );
-  return api.finishTask(id, { agent: agent(cwd).agent, report, evidence, pr, note });
-}
-
-/**
- * The four verbs every guide answers to, whatever its kind (docs/V2.md §11). Each answer carries
- * `next`, the calls that make sense from here, and `say` when the move is to stop.
+ * The calls every piece of work answers to. Each answer carries `next`, the calls that make sense
+ * from here, and `say` when the move is to stop.
  *
- * take: this worktree's agent takes guide `id`, or with no id the next one waiting for it. The
- * document comes back in the answer, and is written to `.passalong/<id>.md` only when `save` asks.
+ * take: this worktree's agent takes work `id` (an id, a share link or a saved .md), or with no id
+ * the next one waiting for it. The document comes back in the answer, and is written to
+ * `.passalong/<id>.md` only when `save` asks.
  */
 export async function take(id, { cwd = process.cwd(), any = false, save = false } = {}) {
   needsSync("taking work");
   const who = agent(cwd);
   const r = await api.take({ ...who, ...(id ? { id: await resolveId(id) } : {}), any });
-  if (!r.guide?.markdown) return r;
-  rememberFence(r.guide.id, r.guide.fence, cwd);
-  return { ...r, path: save ? saveTo(who.worktree, r.guide.id, r.guide.markdown) : null };
+  if (!r.work?.markdown) return r;
+  rememberFence(r.work.id, r.work.fence, cwd);
+  return { ...r, path: save ? saveTo(who.worktree, r.work.id, r.work.markdown) : null };
 }
 
 /** Word from the agent that holds it: the lease starts again, and `note` is what the hub shows. */
@@ -397,35 +308,25 @@ export async function progress(id, note, { cwd = process.cwd() } = {}) {
 }
 
 /**
- * Done here. A task hands in a write-up — `markdown`, published with `parent:` naming the task, or
- * `report`, the id of one already published — for its author to review against Acceptance. Any
- * other guide hands in whether its Verification held: `ok`, and a `note` when it did not.
- *
- * Every hand-in carries `evidence`: what was run and what came back. The write-up and the `ok` are
- * both the agent's word for its own work; evidence is the part the reviewer can check.
+ * Finished here: the work goes to Done with what was shown. Every hand-in carries `evidence` or
+ * `checks` — what was run and what came back — because the note is the agent's word for its own
+ * work and evidence is the part a person can check. `writeup` is what had to be adapted.
  */
 export async function handIn(
   id,
   {
-    ok,
     note = "",
     evidence = "",
     checks = [],
     writeup = "",
     risk = "",
-    markdown,
-    report,
     pr = "",
     cwd = process.cwd(),
   } = {},
 ) {
   needsSync("handing work in");
-  // A check that names a command is run here, before anything is sent.
-  //
-  // The MCP server did this and this function did not, so "put the command in `cmd` and it is
-  // executed here" was true over one transport and a quiet lie over the other: a `cmd` handed to
-  // this function was passed along as a string nothing had executed. Checks that already carry an
-  // exit came from the server's own runner and are left alone, so nothing runs twice.
+  // 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.
   const pending = checks.filter((c) => c?.cmd && typeof c?.exit !== "number" && c?.exit !== null);
   if (pending.length) {
     const done = runChecks(pending, { cwd });
@@ -435,24 +336,10 @@ export async function handIn(
       throw new Error(refusal(done.failed, { ran: done.ran, total: checks.length }));
     }
   }
-  // Checks are evidence, sorted against the lines they answer: bringing them is bringing it. A
-  // check whose command was actually run is exempt from the length rule — its exit code is the
-  // evidence, and `test -f dist/app.js` exiting 0 says more than any sentence about it would.
+  // Checks are evidence, sorted against what they answer: bringing them is bringing it. A check
+  // whose command was actually run is exempt from the length rule — its exit code is the evidence.
   if (checks.length) checks.forEach((c) => (verified(c) ? null : requireEvidence(c?.ran)));
   else requireEvidence(evidence);
-  if (!report && markdown) {
-    const g = parse(markdown);
-    // A task's report is a transfer guide, and this code is what is making one — so it says so
-    // rather than hoping the agent's frontmatter did. Absent is refused now, and refusing an
-    // agent's hand-in because its write-up left a line off would be this function's omission
-    // charged to the agent. Stated, not defaulted: `kind` is the one field here that is not the
-    // author's to leave open, because the caller already knows the answer.
-    report = (
-      await share(serialize({ meta: { ...g.meta, kind: "transfer", parent: id }, body: g.body }), {
-        cwd,
-      })
-    ).guide.meta.id;
-  }
   const fence = fenceFor(id, cwd);
   return api.handIn(id, {
     agent: agent(cwd).agent,
@@ -464,50 +351,30 @@ export async function handIn(
           checks: checks.map((c) => ({
             check: c.check,
             ran: c.ran,
-            // What the agent says happened, in plain words, for the person's table. Left out when
-            // not said: the row then shows the line that was asked and keeps its run folded.
+            // What the agent says happened, in plain words, for the person's table.
             ...(c.says ? { says: c.says } : {}),
             // Only present on a check that was run. The server keeps them apart the same way.
             ...(verified(c) ? { cmd: c.cmd, exit: c.exit, ok: c.ok } : {}),
           })),
         }
       : {}),
-    ...(report ? { report, pr } : {}),
-    // Left out when there is nothing to say, rather than sent as "": most hand-ins have nothing
-    // to adapt, and the field is for the ones that do.
+    // Each left out when there is nothing to say, rather than sent as "".
     ...(writeup ? { writeup } : {}),
-    // What it could break, for the reviewer. Left out when empty, like the write-up.
     ...(risk ? { risk } : {}),
-    ...(typeof ok === "boolean" ? { ok } : {}),
+    ...(pr ? { pr } : {}),
   });
 }
 
 /**
- * Give a guide or task you wrote to someone else in its team: `@handle` for one person, `#group`
- * for the people who do a thing, or "team" (or empty) for everyone. Whoever held it and is left out
- * has it taken back and is told; a task then only goes to the new assignee's agents. The local copy
- * is dropped so the next read shows the new `to:`.
+ * Give work to someone else in its team: `@handle` for one person, `#group` for the people who do
+ * a thing, or "team" (or empty) for everyone. Whoever held it and is left out has it taken back and
+ * is told.
  */
 export async function assign(ref, to) {
-  needsSync("reassigning");
+  needsSync("giving work to someone");
   const id = await resolveId(ref);
   const target = !to || to === "team" || to === "everyone" ? "" : String(to).trim();
-  const r = await api.assign(id, target);
-  store.remove(id);
-  return r;
-}
-
-/**
- * Take back something you sent: it is private again and gone from every inbox it was in. Refused
- * while somebody is on it. Whoever already opened it keeps what they pulled. The local copy is
- * dropped so the next read shows it without the address.
- */
-export async function recall(ref) {
-  needsSync("taking a guide back");
-  const id = await resolveId(ref);
-  const r = await api.recall(id);
-  store.remove(id);
-  return r;
+  return api.assign(id, target);
 }
 
 /** Not this agent's to do: what it held is open again, and `why` goes to whoever is next. */
@@ -540,43 +407,81 @@ export async function ask(id, question, { cwd = process.cwd() } = {}) {
   });
 }
 
+/** Why a piece of work needs its author, or "" when it does not. Mirrors needsWhy() in mcp-http.ts. */
+export function needsWhy(t) {
+  if (!t.mine) return "";
+  if (t.state === "draft") return "in Draft: read it and mark it Ready";
+  if (t.state === "stalled") return "its agent went quiet";
+  if (t.claim?.asking) return `asking you: ${t.claim.asking}`;
+  if (/^BLOCKED:/i.test(t.claim?.note || ""))
+    return `stuck on you: ${t.claim.note.replace(/^BLOCKED:\s*/i, "")}`;
+  return "";
+}
+
+/**
+ * The work board, the way `find_work` with nothing hands it over and `passalong board` prints it:
+ * what needs you, who is on what, and what is ready to take. Built from `/v1/tasks` (every piece of
+ * work you can see, with its state) and `/v1/working` (everything someone holds).
+ */
+export async function board() {
+  needsSync("the board");
+  const [{ tasks }, { working }] = await Promise.all([api.tasks(), api.working()]);
+  const hub = `${api.baseUrl()}/hub`;
+  const who = (b = {}) => (b.you ? "You" : b.name || (b.handle ? `@${b.handle}` : "A teammate"));
+  const needs = tasks
+    .map((t) => ({ id: t.id, title: t.title, why: needsWhy(t), url: `${hub}/w/${t.id}` }))
+    .filter((t) => t.why);
+  return {
+    hub,
+    counts: {
+      needs: needs.length,
+      working: working.length,
+      open: tasks.filter((t) => ["ready", "blocked", "draft"].includes(t.state)).length,
+      done: tasks.filter((t) => t.state === "done").length,
+    },
+    needs,
+    working: working.map((w) => ({
+      id: w.id,
+      title: w.title,
+      who: who(w.by),
+      note: w.note,
+      stalled: w.state === "stalled",
+      url: w.url,
+    })),
+    ready: tasks
+      .filter((t) => t.state === "ready")
+      .map((t) => ({
+        id: t.id,
+        title: t.title,
+        target: t.target || "",
+        to: t.to || "",
+        url: t.url,
+      })),
+  };
+}
+
 /**
- * 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` lists everything it holds, empty when nothing. Counts are best effort
- * — a hook must never fail a session over a count.
+ * What this worktree's agent holds right now, and what is waiting: what the session-start and stop
+ * hooks read (src/hooks.js). Counts are best effort — a hook must never fail a session over one.
  */
 export async function now({ cwd = process.cwd() } = {}) {
   needsSync("seeing what you hold");
   // Read, never minted: the hooks run in every repo a session opens, and a worktree that has never
-  // taken anything has no agent — and should not be given a .passalong/ folder for asking.
+  // taken anything has no agent — and should not be given a .passalong/ project for asking.
   const who = knownAgent(cwd);
-  const [w, t, i, h] = await Promise.allSettled([
-    api.working(),
-    api.tasks(),
-    api.inbox(),
-    api.handedIn(),
-  ]);
+  const [w, t] = await Promise.allSettled([api.working(), api.tasks()]);
   if (w.status === "rejected") throw w.reason;
   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 = {
+  return {
+    held,
     ready: tasks.filter((x) => x.state === "ready" && x.target === who.repo).length,
-    inbox: i.status === "fulfilled" ? i.value.guides.length : 0,
+    needs: tasks.filter((x) => needsWhy(x)).length,
+    agent: who.agent,
   };
-  // Everything waiting on the person, the way the hub's Needs you counts it: their tasks handed in
-  // or stuck, handoffs of theirs handed in, and guides handed to them.
-  const review = tasks.filter(
-    (x) =>
-      x.mine &&
-      (x.state === "review" ||
-        x.state === "stalled" ||
-        (x.state === "claimed" && (x.claim?.asking || /^BLOCKED:/i.test(x.claim?.note || "")))),
-  ).length;
-  const handed = h.status === "fulfilled" ? h.value.handed_in.length : 0;
-  return { held, waiting, needs: review + handed + waiting.inbox, agent: who.agent };
 }
 
-/** Finished work back to To do, with why (docs/REVIEW.md §4). */
+/** Finished work back to To do, with why. */
 export async function reopen(id, why) {
   needsSync("reopening work");
   if (!String(why || "").trim())
@@ -584,98 +489,16 @@ export async function reopen(id, why) {
   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
- * stalled, goes back to Ready with a note saying where that agent left it.
- *
- * The local copy is dropped after each, so the next read of the task fetches what the server made
- * of it — a reject or a release rewrites the document, and a stale copy would hide exactly the
- * line the next reader needs.
- */
-export async function approveTask(id) {
-  needsSync("approving work");
-  const { guide } = await resolve(id, { peek: true });
-  const r = await (guide.meta.kind === "task" ? api.approveTask(id) : api.closeGuide(id));
-  store.remove(id);
-  return r;
-}
-
-export async function rejectTask(id, why) {
-  needsSync("sending work back");
-  if (!String(why || "").trim())
-    throw new PassalongError("say why: whoever takes it next reads it");
-  const { guide } = await resolve(id, { peek: true });
-  const r = await (guide.meta.kind === "task" ? api.rejectTask(id, why) : api.sendBack(id, why));
-  store.remove(id);
-  return r;
-}
-
-/**
- * Take it back from whoever is holding it — a task, a handoff or a bug, and from all of them at
- * once when several people hold the same handoff in different repos.
- *
- * It was tasks only, which left an asymmetry nobody chose: the author of a handoff could mark it
- * done or give it to somebody else, and had no way to simply have it back.
- */
+/** Take it back from whoever is holding it. */
 export async function release(id) {
   needsSync("taking work back");
-  const r = await api.release(id);
-  store.remove(id);
-  return r;
-}
-
-/**
- * Pull a guide *and* take the handoff: the two halves of starting work, in one call.
- *
- * `pull` says the guide arrived. `ack` says somebody is doing it, which is the thing the sender
- * cannot find out any other way — and the two are deliberately separate, because reading a guide
- * to decide it is not yours is exactly what `pass` is for. Fetching is not committing.
- *
- * For an agent the distinction is real but the ordering never varies: it reads a guide because it
- * is about to follow it. So this is the path an agent takes when it means to do the work, and it
- * is one call rather than two — the mandated thing has to be the cheap thing or it gets skipped.
- * `pull` alone remains the way to read one without answering for it.
- *
- * The ack is best-effort and never costs the caller the markdown, which is what they came for:
- *
- *   - the author's own guide is a 403 (`ack` is the reader's answer and an author is not a party
- *     to it), and that is a no-op, not a failure — an agent working in its own user's repo hits
- *     this constantly;
- *   - logged out, there is nobody to tell;
- *   - anything else is reported in `ack_error` rather than swallowed, because an ack that quietly
- *     did not land leaves the sender in the silence the whole feature exists to end.
- */
-export async function start(ref, { cwd = process.cwd(), save = false } = {}) {
-  const r = await take(await resolveId(ref), { cwd, save });
-  if (!r.guide?.markdown) return r;
-  return { ...r, markdown: r.guide.markdown };
-}
-
-/**
- * The one line `get_guide` adds to a guide it is handing an agent, or "" when there is nothing to
- * say. Separate from the tool so it can be tested without a server.
- *
- * Only a guide that was addressed to somebody can be taken — one nobody was handed has no handoff
- * to answer for, and nudging about it is noise that teaches an agent to ignore the nudge.
- *
- * It goes after the document, not in front of it. Anything before the opening `---` stops the
- * frontmatter being frontmatter, and an agent that writes what it was handed back out to a file
- * would lose the id along with it.
- */
-export function handoffNudge(meta = {}) {
-  if (!meta.to && !meta.team) return "";
-  return (
-    "<!-- passalong: this guide was handed to someone. If you are about to do the work, call " +
-    "take instead of get_guide — it takes the handoff so the sender stops guessing. " +
-    "If you are only reading, or it turns out not to be yours, answer with pass with a reason. -->"
-  );
+  return api.release(await resolveId(id));
 }
 
 /**
- * The image types a guide can carry as evidence. Mirrors SHOT_TYPES in apps/api/src/shots.ts —
- * the server is the authority and refuses anything else; this is what lets a local caller find
- * out before spending an upload on it.
+ * The image types work can carry. Mirrors SHOT_TYPES in apps/api/src/shots.ts — the server is the
+ * authority and refuses anything else; this is what lets a local caller find out before spending an
+ * upload on it.
  */
 export const SHOT_TYPES = {
   ".png": "image/png",
@@ -686,65 +509,42 @@ export const SHOT_TYPES = {
 };
 
 /**
- * Attach a screenshot from disk, and return the markdown that points at it.
- *
- * Evidence belongs *in* the document: a guide travels as markdown to anyone holding its link, so
- * an image beside it would not travel at all. `claimShots` binds the upload to whichever guide's
- * markdown names it at publish, which is why this returns a line to paste rather than taking a
- * guide id — there is nothing to attach it to until the document says so.
- *
- * Local because it reads a path. An agent in a terminal has one; a hosted assistant does not, and
- * reaches the same route through `attach_screenshot` on the HTTP server instead.
- */
-/**
- * The same upload, for an agent that has the image and not a path to it.
- *
- * `attach()` takes a path because a screenshot usually lands on disk. An agent driving a browser
- * often has the opposite: the pane hands back an image as a tool result and never writes a file, so
- * the only door into evidence was one it could not open. It did what anyone would — swapped to
- * `grep` and `tsc` checks and put what it saw in `writeup` — and said so itself: "a grep proves the
- * code changed, not that the screen renders right."
- *
- * Base64 in a tool call, which the HTTP server's instructions rightly warn against, because there
- * the alternative is `create_upload` and a curl. Here there is no alternative for bytes held in
- * memory, and this server is a local process talking to the same upload the file path uses.
+ * The same upload as `attach()`, for an agent that has the image and not a path to it: a browser
+ * pane hands an image back as a tool result and never writes a file. Base64 in a tool call is fine
+ * here, where this server is a local process talking to the same upload the file path uses.
  */
 export async function attachBytes(data, { name = "", type = "image/png" } = {}) {
-  if (!api.loggedIn())
-    throw new PassalongError("attaching evidence needs sync — run `passalong login` first");
+  needsSync("adding a file");
   const allowed = new Set(Object.values(SHOT_TYPES));
   if (!allowed.has(type))
-    throw new PassalongError(`screenshots must be ${[...allowed].join(", ")} — ${type} is not one`);
-  let bytes;
-  try {
-    // A data: URL is what several browser tools hand back, so it is accepted rather than made the
-    // caller's problem to strip.
-    bytes = Buffer.from(String(data).replace(/^data:[^,]*,/, ""), "base64");
-  } catch {
-    throw new PassalongError("`data` is not base64");
-  }
+    throw new PassalongError(`pictures must be ${[...allowed].join(", ")} — ${type} is not one`);
+  // A data: URL is what several browser tools hand back, so it is accepted rather than made the
+  // caller's problem to strip.
+  const bytes = Buffer.from(String(data).replace(/^data:[^,]*,/, ""), "base64");
   if (!bytes.length) throw new PassalongError("`data` decoded to nothing");
-  // The server's own ceiling, checked here so a large paste fails before it is sent rather than
-  // after. Anything bigger belongs in create_upload, which streams from a file.
+  // The server's own ceiling, checked here so a large paste fails before it is sent.
   if (bytes.length > 5 * 1024 * 1024)
     throw new PassalongError(
-      `that image is ${Math.round(bytes.length / 1024 / 1024)}MB and the limit is 5MB — ` +
-        "write it to a file and use create_upload, which streams",
+      `that image is ${Math.round(bytes.length / 1024 / 1024)}MB and the limit is 5MB — write it to a file and pass its path`,
     );
   const label = name || "screenshot";
   const shot = await api.uploadShot(bytes, type, label);
   return { ...shot, markdown: `![${label}](${shot.url})` };
 }
 
+/**
+ * Upload a picture from disk, and return the markdown that points at it. It belongs *in* the work's
+ * text or a hand-in check: `claimShots` binds the upload to whichever document names it, which is
+ * why this returns a line to paste rather than taking an id.
+ */
 export async function attach(file, { name = "" } = {}) {
-  if (!api.loggedIn())
-    throw new PassalongError("attaching evidence needs sync — run `passalong login` first");
+  needsSync("adding a file");
   if (!existsSync(file)) throw new PassalongError(`no file at ${file}`);
   const ext = file.slice(file.lastIndexOf(".")).toLowerCase();
   const type = SHOT_TYPES[ext];
   if (!type)
     throw new PassalongError(
-      `screenshots must be ${[...new Set(Object.values(SHOT_TYPES))].join(", ")} — ${ext || file} is not one`,
+      `pictures must be ${[...new Set(Object.values(SHOT_TYPES))].join(", ")} — ${ext || file} is not one`,
     );
   const shot = await api.uploadShot(readFileSync(file), type, name || basename(file));
   return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
@@ -752,7 +552,7 @@ export async function attach(file, { name = "" } = {}) {
 
 /**
  * What a file's extension suggests it is. A hint only: the server reads the bytes and decides, and
- * refuses what it does not keep. It exists so a `.csv` is filed as CSV and not as generic text.
+ * refuses what it does not keep.
  */
 const FILE_HINTS = {
   ".pdf": "application/pdf",
@@ -768,14 +568,11 @@ const FILE_HINTS = {
 const FILE_MAX = 10 * 1024 * 1024;
 
 /**
- * Attach a file that is not a picture — a log, a PDF, a CSV, a zip — and return the markdown line that
- * points at it. For a guide body or a bug report, where an agent has the file and nothing else to
- * show it with. It is private: whoever can read the guide can download it, and nobody else can, so
- * it is not evidence on a page that travels by link.
+ * Upload a file that is not a picture — a log, a PDF, a CSV, a zip — and return the markdown line
+ * that points at it. It is private: whoever can read the work can download it, and nobody else.
  */
 export async function attachFile(file, { name = "" } = {}) {
-  if (!api.loggedIn())
-    throw new PassalongError("attaching a file needs sync — run `passalong login` first");
+  needsSync("adding a file");
   if (!existsSync(file)) throw new PassalongError(`no file at ${file}`);
   const bytes = readFileSync(file);
   if (!bytes.length) throw new PassalongError(`${file} is empty`);
@@ -789,330 +586,149 @@ export async function attachFile(file, { name = "" } = {}) {
   return { ...attachment, markdown: `[${label}](${attachment.url})` };
 }
 
+/** A picture or any other file from disk, whichever it is, as the line that points at it. */
+export function attachAny(file, opts = {}) {
+  const isImage = Object.keys(SHOT_TYPES).some((x) => file.toLowerCase().endsWith(x));
+  return (isImage ? attach : attachFile)(file, opts);
+}
+
 /**
- * Write to whoever holds a guide, or leave a note on one nobody holds yet: an answer to a question,
- * or something thought of since. `files` are paths — a picture is uploaded as one and drawn in the
- * thread, anything else as a file to download — and each becomes a line of the message. The server
- * decides who may write and whether anyone is listening, and says so in words.
+ * Write to whoever holds a piece of work, or leave a note on one nobody holds yet. `files` are
+ * paths, each uploaded and added as a line of the message. The server decides who may write and
+ * whether anyone is listening, and says so in words.
  */
 export async function reply(ref, text, { files = [] } = {}) {
   needsSync("replying");
   const lines = [];
-  for (const file of files) {
-    const ext = file.includes(".") ? file.slice(file.lastIndexOf(".")).toLowerCase() : "";
-    const got = SHOT_TYPES[ext] ? await attach(file) : await attachFile(file);
-    lines.push(got.markdown);
-  }
+  for (const file of files) lines.push((await attachAny(file)).markdown);
   const body = [String(text || "").trim(), ...lines].filter(Boolean).join("\n");
   if (!body) throw new PassalongError("say something, or attach a file");
   return api.reply(await resolveId(ref), body);
 }
 
 /**
- * The line a guide arrives with, saying what a follow-up is and how to write one.
- *
- * A follow-up is more context for a guide, written as its own guide with `parent` naming the
- * original — a missing detail, a step that needed explaining, what changed since, what someone
- * found doing it. Whoever opens the original, person or agent, gets its follow-ups with it, which
- * is why context belongs there rather than in a one-line verdict note.
- *
- * What an agent did and found working on the guide is not context for it: that is the hand-in,
- * and the note says so. It used to list "what you found doing it" among the things to publish, on
- * every `take`, while hand_in said a follow-up was not for answering — the agent followed the one
- * it read last, and the author got a second guide to review with the evidence inside it.
- *
- * Trailing, like the handoff nudge, so it never sits in front of the frontmatter. It is here and
- * not only in the server's instructions because an agent reads the payload it is working from and
- * skims everything else — the same reason the bug lead is inside the document. For a bug, the
- * context worth adding is usually the fix, when it is worth repeating somewhere else: that is a
- * transfer guide, and the bug is what it adds context to.
+ * What an agent is told after the work it opened: where what it learns goes. Knowledge belongs in
+ * the project's documents, where the next person finds it; work somebody else should now do is new
+ * work. Neither is a second document handed to one person. Mirrors AFTER in apps/api/src/mcp-http.ts.
  */
-export function followUpNote(meta = {}) {
-  if (!meta.id) return "";
-  if (meta.kind === "bug")
-    return (
-      "<!-- passalong: once this is fixed, if the fix is worth repeating somewhere else, that is " +
-      "more context for this bug: publish it as a transfer guide with publish_guide " +
-      `parent=${meta.id}, and whoever opens this bug gets it too. -->`
-    );
-  return (
-    "<!-- passalong: a follow-up is more context for this guide, written as its own guide. If " +
-    "this guide needs more — a missing detail, a step that needed explaining, what changed since " +
-    `— publish that with publish_guide parent=${meta.id}, and whoever opens this guide gets it ` +
-    "too. What you did and found working on it is not a follow-up: it goes on hand_in, in " +
-    "`checks` and `writeup`. -->"
-  );
-}
-
-/** What heads a guide's follow-ups when they are handed to an agent. Same words on both servers. */
-export const FOLLOW_UPS_LEAD =
-  "FOLLOW-UPS — more context added to this guide, oldest first. Read them before acting; where " +
-  "one contradicts the original, the follow-up is newer.";
-
-/**
- * A guide's follow-ups as the server lists them, oldest first, or [] when there are none, when
- * sync is off, or when anything goes wrong. Context is never worth failing a pull over: the guide
- * itself is what was asked for, and it is already in hand.
- *
- * Only with sync, because follow-ups live on the server and are scoped to what this account can
- * read — the same condition `resolve()` uses to look a guide up there. Fetching them records no
- * pull on them: reading context for a guide is not opening those guides.
- *
- * `markdown` asks for each one's content too (capped server-side). The api calls are injectable
- * so this can be tested without a network.
- */
-export async function followUpGuides(
-  meta = {},
-  { markdown = false, children = api.children, loggedIn = api.loggedIn } = {},
-) {
-  if (!meta.id || !loggedIn()) return [];
-  try {
-    const { guides = [] } = await children(meta.id, { markdown });
-    const listed = (Array.isArray(guides) ? guides : []).filter((g) => g?.id);
-    // With content the server already sends oldest first; the plain listing is newest first.
-    return markdown ? listed : listed.reverse();
-  } catch {
-    return [];
-  }
-}
-
-/**
- * A guide's follow-ups with their content, formatted to go after the document for an agent — the
- * same shape the remote server's get_guide returns — or "" when there are none.
- */
-export async function followUps(meta = {}, deps = {}) {
-  const guides = (await followUpGuides(meta, { ...deps, markdown: true })).filter(
-    (g) => typeof g.markdown === "string",
-  );
-  if (!guides.length) return "";
-  return [
-    FOLLOW_UPS_LEAD,
-    ...guides.map(
-      (g) => `--- follow-up ${g.id}: ${g.title || "untitled"} ---\n${g.markdown.trimEnd()}`,
-    ),
-  ].join("\n\n");
-}
+export const AFTER =
+  "<!-- passalong: what you learn doing this — how something works, a decision and why — goes " +
+  "into the project's documents (find_projects, read_document, save_document), not into a new " +
+  "piece of work. Work somebody else should now do is create_work with `parent` set to this id. " +
+  "What you did and how you checked it goes on hand_in. -->";
 
 /**
- * The guide a follow-up came out of, formatted to go in front of it — or "" when there is none.
+ * The work this one came out of, formatted to go in front of it — or "" when there is none.
  *
- * Follow-ups travelled one way: opening a guide handed over what was written under it, and opening
- * one of those handed over nothing. An agent given a follow-up on its own reads a document that
- * assumes a piece of work it has never seen, and either goes looking for it or treats the note as
- * the whole job. Where the parent has got to is part of the context, not a separate question.
- *
- * The same shape the hosted server's parentOf() returns. Injectable for testing, and never worth
- * failing the call over: the guide itself is what was asked for.
+ * A piece of work read on its own can look like the whole job when it is one part of a bigger one,
+ * and where the bigger one has got to is part of the context. Injectable for testing, and never
+ * worth failing the call over: the work itself is what was asked for. Mirrors parentOf() in
+ * apps/api/src/mcp-http.ts.
  */
-export async function parentGuide(
-  meta = {},
-  { parent = api.parent, loggedIn = api.loggedIn } = {},
-) {
+export async function parentWork(meta = {}, { parent = api.parent, loggedIn = api.loggedIn } = {}) {
   if (!meta.id || !meta.parent || !loggedIn()) return "";
   try {
-    const { guide } = await parent(meta.id, { markdown: true });
-    if (!guide?.id) return "";
-    const who = guide.by?.name || (guide.by?.handle ? `@${guide.by.handle}` : "");
-    const state = guide.state === "held" && who ? `held by ${who}` : guide.state || "open";
+    const { work } = await parent(meta.id, { markdown: true });
+    if (!work?.id) return "";
+    const who = work.by?.name || (work.by?.handle ? `@${work.by.handle}` : "");
+    const state = work.state === "held" && who ? `held by ${who}` : work.state || "open";
     return (
-      `THIS IS A FOLLOW-UP TO ${guide.id}: ${guide.title || "untitled"} — ${state}. It is more ` +
-      "context for that guide, not a piece of work on its own. Read the guide it follows first; " +
-      "it is below, and where the two disagree this follow-up is newer. If what it asks for " +
-      `depends on ${guide.id} being done and it is not, say so rather than starting.\n\n` +
-      `--- the guide it follows: ${guide.id} ---\n${String(guide.markdown ?? "").trimEnd()}\n\n`
+      `THIS CAME OUT OF ${work.id}: ${work.title || "untitled"} — ${state}. It is part of that ` +
+      "work, which is below; read it first. If this depends on " +
+      `${work.id} being done and it is not, say so rather than starting.\n\n` +
+      `--- the work it came out of: ${work.id} ---\n${String(work.markdown ?? "").trimEnd()}\n\n`
     );
   } catch {
     return "";
   }
 }
 
-/** Guides on the server this account can see, newest first, optionally filtered. */
+/** Work on the server this account can see, newest first, optionally filtered. */
 export async function list(query = "", { scope = "" } = {}) {
-  needsSync("listing guides");
-  const res = await api.list(query, scope);
-  return res.guides.map((r) => ({ ...r, where: "synced" }));
-}
-
-/** Guides handed to you (or your teams) that you have not pulled yet. Needs sync. */
-export async function inbox() {
-  const res = await api.inbox();
-  return res.guides;
-}
-
-/**
- * The state of your transfers as four queues: waiting on you, in flight (handed over, untouched),
- * and landed (someone else has it). Needs sync.
- */
-export const board = () => api.board();
-
-/**
- * What you did, newest first: what you published, what you took delivery of, and every verdict and
- * ack you gave. The other half of `activity` — that one is what other people did to your guides and
- * it clears when you read it; this is your own record and it never clears.
- *
- * It is a record of what you passed along, not of what you worked on. Work that never became a
- * guide has no row, so anything printing this has to say so. Needs sync.
- */
-export async function log({ repo = "", since = "" } = {}) {
-  const res = await api.log({ repo, since });
-  return res.log;
-}
-
-/**
- * What happened while you were away: your guides being pulled and shipped, guides handed to you,
- * invites taken up. Each item carries a rendered `text` line so every surface says the same thing.
- */
-export async function activity({ all = false, limit = 50 } = {}) {
-  return api.notifications({ unread: !all, limit });
+  needsSync("finding work");
+  return (await api.list(query, scope)).work;
 }
 
-/**
- * Report whether a guide actually works. This is the reader's answer, not the author's status:
- * `done` says "I implemented it", a verdict says "I tried it and it holds up" — or does not.
- * A failing verdict needs a note; "it doesn't work" without a reason helps nobody.
- */
-/** Mark notifications seen. No ids means everything unread. */
-export const seen = (ids = []) => api.markRead(ids);
-
-export function summary(g) {
-  return {
-    id: g.meta.id,
-    title: g.meta.title,
-    status: g.meta.status,
-    created: g.meta.created,
-    source_context: g.meta.source_context,
-    tags: g.meta.tags || [],
-    stack_assumptions: g.meta.stack_assumptions || [],
-    url: g.meta.url || null,
-    team: g.meta.team || "",
-    to: g.meta.to || "",
-    mine: true,
-  };
-}
-
-/** Archive a guide (`consumed`) or put it back (`published`). The server refuses `promoted`. */
+/** Archive a piece of work (`done`), make it Ready, or put it in Draft. */
 export async function setStatus(id, status) {
   if (!STATUSES.includes(status))
     throw new PassalongError(`status must be one of ${STATUSES.join(", ")}`);
-  const { guide } = await resolve(id, { peek: true });
-  const next = { ...guide, meta: { ...guide.meta, status } };
-  // The server first. Saved the other way round, a refusal left the local copy saying what the
-  // server had just refused — a teammate's `ready` on someone else's task read as done here.
-  await api.setStatus(id, status);
-  return next;
+  needsSync("changing work");
+  return api.setStatus(await resolveId(id), status);
 }
 
-/**
- * Move a guide from Draft to Ready: a person has read it, and whoever it is for may take it now.
- * Every kind: a handoff or bug is a draft until somebody says so, as a task always was.
- */
+/** Move work from Draft to Ready: a person has read it, and whoever it is for may take it now. */
 export async function ready(id) {
-  const { guide } = await resolve(id, { peek: true });
-  if (guide.meta.status !== "draft")
-    throw new PassalongError(`${guide.meta.id} is not in Draft (status: ${guide.meta.status})`);
-  return setStatus(guide.meta.id, "published");
+  const { work } = await resolve(id, { peek: true });
+  if (work.meta.status !== "draft")
+    throw new PassalongError(`${work.meta.id} is not in Draft (status: ${work.meta.status})`);
+  await setStatus(work.meta.id, "ready");
+  return work.meta.id;
 }
 
-/**
- * One goal as several tasks, written as drafts in order. Each step may name the earlier steps it
- * needs by position (`after: [0, 1]`), and those become its `blocked_by`, so the queue hands them
- * out in an order that works and runs the independent ones side by side.
- *
- * Only earlier steps: a step that waits on itself or on a later one is a plan that never finishes,
- * and it is refused before anything is written rather than discovered as a queue that never moves.
- * Every step lands in Draft — a wrong decomposition is several agents building the wrong thing at
- * once, so a person reads the plan before any of it runs.
- */
-export async function planTasks(steps, { cwd = process.cwd() } = {}) {
-  if (!Array.isArray(steps) || !steps.length)
-    throw new PassalongError("a plan needs at least one step");
-  steps.forEach((step, i) => {
-    for (const j of step.after || [])
-      if (!Number.isInteger(j) || j < 0 || j >= i)
-        throw new PassalongError(
-          `step ${i} ("${step.title}") can only wait on an earlier step, not ${j}`,
-        );
-  });
-  const repo = context(cwd).repo;
-  const ids = [];
-  for (const step of steps) {
-    const section = (name, text) =>
-      String(text || "").trim() ? [`## ${name}`, String(text).trim(), ""] : [];
-    const body = [
-      ...section("Goal", step.goal),
-      ...section("Context", step.context),
-      ...section("Constraints", step.constraints),
-      ...section("Acceptance", step.acceptance),
-      ...section("Out of scope", step.out_of_scope),
-    ].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]);
-    if (after.length) meta.blocked_by = after;
-    ids.push((await share(serialize({ meta, body }), { cwd })).guide.meta.id);
-  }
-  return ids;
-}
-
-/** What an agent started by `work()` is told. The task itself goes in too, so it cannot start blind. */
+/** What an agent started by `work()` is told. The work itself goes in too, so it cannot start blind. */
 export function workPrompt(t) {
   return [
-    `You hold passalong task ${t.id}, and no other agent can take it while you do. Here it is:`,
+    `You hold passalong work ${t.id}, and no other agent can take it while you do. Here it is:`,
     "",
     t.markdown.trim(),
     "",
-    "Do it in this repo. There are no Steps: work out how to reach Goal within Constraints, and",
-    "leave Out of scope alone. Call the passalong MCP tool progress with id",
-    `${t.id} and a one-line status at each milestone — 30 minutes of silence stalls the task.`,
-    "When every Acceptance check holds, commit what you changed as one commit whose message",
-    `starts with "${t.id}: " — several tasks share this worktree, and a reviewer reads each one's`,
-    "change on its own. Then call hand_in with id",
-    `${t.id}, \`pr\` set to that commit's hash, \`markdown\`: a transfer guide saying what you`,
-    "did, what you decided and why, and how you checked each Acceptance line, and `evidence`:",
-    "what you ran and what came back — the commands and the lines that decided it, the test",
-    "summary, the commit. Keep that as you go; at the end you would be writing it from memory,",
-    "and it is the one part of the hand-in a reviewer can check. If either call says you no",
-    "longer hold the task, stop.",
+    "Do it in this repo: 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. When it is done, commit what you changed as one commit whose message",
+    `starts with "${t.id}: " — several pieces of work share this worktree, and a person reads each`,
+    `one's change on its own. Then call hand_in with id ${t.id}, \`pr\` set to that commit's hash,`,
+    "`note`: one plain sentence saying what you did, and `evidence`: what you ran and what came",
+    "back — the commands and the lines that decided it, the test summary, the commit. Keep that",
+    "as you go; at the end you would be writing it from memory. 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. If something only a person can",
-    "do stands between you and an Acceptance line — a permission, a secret, a decision — call",
+    "do stands between you and done — a permission, a secret, a decision — call",
     `progress with id ${t.id} and a note starting "BLOCKED: " that says exactly what you`,
-    "need, leave the task unfinished and uncommitted, and stop. The board shows that note.",
+    "need, leave it unfinished and uncommitted, and stop. The board shows that note.",
   ].join("\n");
 }
 
 /**
- * Work the queue from this worktree: take the next task, hand it to an agent, and when the agent
- * has finished it take the next, until there is nothing left.
+ * Work the queue from this worktree: take the next piece of work, hand it to an agent, and when the
+ * agent has finished it take the next, until there is nothing left.
  *
  * The agent runs in this worktree, so it is the same agent to the queue — its progress and
  * 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, 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.
+ * 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.
+ *
+ * `watch` is the runner (docs/LOOP.md §1a): left running on an always-on machine with the repo
+ * checked out, it takes only work a person marked safe to run alone, waits `every` seconds when
+ * there is none, and keeps going past work its agent did not finish — that stays held here, the
+ * sweep puts it back in the queue once it goes quiet, and a second time a person is told it is
+ * stuck. Nobody is watching, so nothing stops for a person.
  */
 export async function work({
   cwd = process.cwd(),
   agent = process.env.PASSALONG_AGENT || "claude -p",
   any = false,
   once = false,
+  watch = false,
+  every = 60,
   onTask = () => {},
+  onIdle = () => {},
+  onUnfinished = () => {},
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
 } = {}) {
   needsSync("working the queue");
   const [command, ...args] = agent.trim().split(/\s+/);
   const finished = [];
   for (;;) {
-    const t = await nextTask({ cwd, any });
+    const t = await nextWork({ cwd, any, alone: watch });
+    if (!t && watch) {
+      onIdle();
+      await sleep(Math.max(10, every) * 1000);
+      continue;
+    }
     if (!t) return { finished, stopped: "empty" };
     onTask(t);
     const run = spawnSync(command, [...args, workPrompt(t)], {
@@ -1120,9 +736,12 @@ 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 !== "done" && state !== "review")
+    const state = (await api.tasks()).tasks.find((x) => x.id === t.id)?.state;
+    if (state !== "done" && watch) {
+      onUnfinished(t, state, run.status ?? run.error?.message);
+      continue;
+    }
+    if (state !== "done")
       return {
         finished,
         stopped: "unfinished",
@@ -1136,13 +755,13 @@ export async function work({
 }
 
 /**
- * Make every guide 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 a guide on is its
- * author's call.
+ * 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
+ * is its author's call.
  */
 export async function readyDrafts() {
   const drafts = (await list("", { scope: "mine" })).filter((g) => g.status === "draft");
-  for (const g of drafts) await ready(g.id);
+  for (const g of drafts) await setStatus(g.id, "ready");
   return drafts.map((g) => g.id);
 }
 
@@ -1159,8 +778,8 @@ export async function remove(id) {
 }
 
 /**
- * Write every guide to a directory as plain markdown: signed in, every one the server lets this
- * account read, and the local store's own besides. Returns the paths written.
+ * Write every piece of work to a directory as plain markdown: signed in, every one the server lets
+ * this account read, and the local store's own besides. Returns the paths written.
  */
 export async function exportAll(dir) {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
@@ -1169,7 +788,7 @@ export async function exportAll(dir) {
     let after = "";
     do {
       const page = await api.exportPage(after);
-      for (const g of page.guides) paths.set(g.id, g.markdown);
+      for (const g of page.work) paths.set(g.id, g.markdown);
       after = page.next;
     } while (after);
   }
@@ -1181,26 +800,70 @@ export async function exportAll(dir) {
   });
 }
 
+// The host this product answered on before passalong.dev. It serves the same data, so a copy
+// whose url names it belongs to the default API.
+const OLD_HOST = "passalong.kreativekorna.com";
+const hostOf = (url) => {
+  try {
+    const { host, hostname } = new URL(url);
+    if (["localhost", "127.0.0.1", "[::1]"].includes(hostname)) return "";
+    return host === OLD_HOST ? new URL(api.DEFAULT_API).host : host;
+  } catch {
+    return "";
+  }
+};
+// Raised whenever tidy learns to remove something it used to keep, so machines that tidied run it once more.
+const TIDIED = 2;
+
 /**
  * Once per machine, signed in: drop the local copies the server says it holds. They were written
- * by every share, pull and take before `keep()`, and nothing ever removed one. What the server
- * does not return — shared while signed out, or from another account — is left where it is.
+ * by every share, pull and take before `keep()`, and nothing ever removed one. Every login on the
+ * machine is asked, since a copy may be any of theirs. A copy whose `url:` is on a login's own host
+ * and that the server answers 404 for was since deleted, and goes too. Anything else — no url,
+ * localhost, another host, or an answer that was neither 200 nor 404 — is left where it is, and an
+ * export that failed leaves the flag unset so the next start tries again.
  */
 export async function tidy() {
-  if (!api.loggedIn() || store.readConfig().tidied) return 0;
-  const local = new Set(store.list().map((g) => g.meta.id));
+  const logins = api.logins();
+  if (!logins.length || store.readConfig().tidied === TIDIED) return 0;
+  const local = new Map(store.list().map((g) => [g.meta.id, hostOf(g.meta.url)]));
   let removed = 0;
-  let after = "";
-  while (local.size) {
-    const page = await api.exportPage(after);
-    for (const g of page.guides)
-      if (local.delete(g.id)) {
-        store.remove(g.id);
-        removed++;
-      }
-    after = page.next;
-    if (!after) break;
+  let sure = true;
+  const drop = (id) => {
+    if (!local.delete(id)) return;
+    store.remove(id);
+    removed++;
+  };
+  for (const as of logins) {
+    try {
+      let after = "";
+      do {
+        const page = await api.exportPage(after, as);
+        for (const g of page.work) drop(g.id);
+        after = page.next;
+      } while (after && local.size);
+    } catch {
+      sure = false;
+    }
+  }
+  const said = new Map();
+  for (const as of logins) {
+    const host = hostOf(as.api);
+    const ids = [...local].filter(([, h]) => h && h === host).map(([id]) => id);
+    // Eight at a time: a few hundred copies is a few seconds, not a few hundred open requests.
+    for (let i = 0; i < ids.length; i += 8)
+      await Promise.all(
+        ids.slice(i, i + 8).map(async (id) => {
+          const status = await api.get(id, { peek: true, as }).then(
+            () => 200,
+            (err) => err.status ?? 0,
+          );
+          said.set(id, [...(said.get(id) ?? []), status]);
+        }),
+      );
   }
-  store.writeConfig({ tidied: true });
+  for (const [id, statuses] of said)
+    if (statuses.includes(200) || statuses.every((s) => s === 404)) drop(id);
+  if (sure) store.writeConfig({ tidied: TIDIED });
   return removed;
 }