passalong 0.20.0 → 1.0.0

package/src/api.js

@@ -1,5 +1,5 @@
-// Client for the hosted sync API (apps/api). Everything here is optional: with no token the
-// CLI is a purely local tool, and every function throws an ApiError the CLI turns into a hint.
+// Client for the hosted API (apps/api). Work lives there, so nearly every call needs a login, and
+// every function throws an ApiError the CLI turns into a hint.
 import { readFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { basename } from "node:path";
@@ -27,7 +27,7 @@ export class ApiError extends Error {
 // ---- which account -----------------------------------------------------------------------------
 //
 // A machine may be signed in to several (store.js). Who a call is made as comes from, in order:
-// PASSALONG_TOKEN, an account named by PASSALONG_ACCOUNT, `--as` or `use_account` (this process
+// PASSALONG_TOKEN, an account named by PASSALONG_ACCOUNT, `--as` or `accounts` `use` (this process
 // only), then the machine's default. With two or more logins and nobody having said which, a
 // person at a terminal gets the default and an agent — a process with no terminal to ask on — is
 // refused with the names, so it asks the person rather than choosing. That refusal is the prompt:
@@ -102,7 +102,7 @@ export function choiceMessage() {
     .join(", ");
   return (
     `More than one Passalong account is signed in on this machine (${list}) and nothing says which ` +
-    "this session is for. Ask the person which one to use, then call use_account with its name " +
+    "this session is for. Ask the person which one to use, then call accounts with `use` set to its name " +
     "(or run the command with --as <name>). Do not choose one yourself."
   );
 }
@@ -120,6 +120,19 @@ export function loggedIn() {
   return Boolean(token());
 }
 
+/**
+ * Every login this machine holds, as `{ token, api }` for a call's `as`: each kept account and the
+ * one in use, once each. For work that belongs to all of them, like `tidy`, rather than to one.
+ */
+export function logins() {
+  const all = Object.values(readAccounts())
+    .filter((a) => a.token)
+    .map((a) => ({ token: a.token, api: a.api || readConfig().api || DEFAULT_API }));
+  if (token()) all.push({ token: token(), api: baseUrl() });
+  const seen = new Set();
+  return all.filter((a) => !seen.has(`${a.token} ${a.api}`) && seen.add(`${a.token} ${a.api}`));
+}
+
 /** The team this account works in. It belongs to the account, not the machine. */
 export function currentTeam() {
   const p = picked();
@@ -149,12 +162,12 @@ export { nameFor };
 
 async function call(
   path,
-  { method = "GET", body, auth = true, raw = false, uploadName = "" } = {},
+  { method = "GET", body, auth = true, raw = false, uploadName = "", as = null } = {},
 ) {
   const headers = { ...CLIENT };
   if (auth) {
-    if (needsChoice()) throw new ApiError(409, choiceMessage());
-    const t = token();
+    if (!as && needsChoice()) throw new ApiError(409, choiceMessage());
+    const t = as ? as.token : token();
     if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
     headers.authorization = `Bearer ${t}`;
   }
@@ -166,9 +179,10 @@ async function call(
         : "application/json";
   }
   if (uploadName) headers["x-file-name"] = uploadName.replace(/[^\x20-\x7e]/g, "").slice(0, 120);
+  const base = as ? as.api.replace(/\/$/, "") : baseUrl();
   let res;
   try {
-    res = await fetch(`${baseUrl()}${path}`, {
+    res = await fetch(`${base}${path}`, {
       method,
       headers,
       body:
@@ -179,7 +193,7 @@ async function call(
             : JSON.stringify(body),
     });
   } catch (err) {
-    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+    throw new ApiError(0, `could not reach ${base} (${err.message})`);
   }
   if (!res.ok) {
     const text = await res.text();
@@ -201,58 +215,6 @@ const q = (params) => {
   return s ? `?${s}` : "";
 };
 
-/**
- * Sign in, or make the account, and come back with a token for this machine.
- *
- * Three calls, because the API answers a browser and this is not one: signing in sets a session
- * cookie, and the CLI carries a bearer token instead — one that shows up in the hub's token list
- * with a name on it, and can be revoked there without changing the password. So the cookie is used
- * once, to mint the token, and then dropped.
- *
- * `make` is signup rather than sign-in. It is the caller's decision and not a fallback here: an
- * account created because an address was mistyped is worse than being told there is no such
- * account.
- */
-export async function signIn(email, password, { make = false, label = "" } = {}) {
-  const res = await fetch(`${baseUrl()}${make ? "/v1/auth/signup" : "/v1/auth/login"}`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ email, password }),
-  }).catch((err) => {
-    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
-  });
-  if (!res.ok) {
-    const said = await res.json().catch(() => ({}));
-    throw new ApiError(res.status, said.message || res.statusText);
-  }
-  const { account } = await res.json();
-  // `getSetCookie` keeps the cookies apart; a joined `set-cookie` header cannot be split safely,
-  // because an Expires date has a comma in it.
-  const cookie = (res.headers.getSetCookie?.() ?? []).map((c) => c.split(";")[0]).join("; ");
-  if (!cookie) throw new ApiError(500, "signed in, but no session came back");
-
-  const minted = await fetch(`${baseUrl()}/v1/tokens`, {
-    method: "POST",
-    headers: { "content-type": "application/json", cookie },
-    body: JSON.stringify({ name: label || "cli" }),
-  });
-  if (!minted.ok) {
-    const said = await minted.json().catch(() => ({}));
-    throw new ApiError(minted.status, said.message || "could not make a token for this machine");
-  }
-  const { token: made } = await minted.json();
-  return { account, token: made };
-}
-
-/**
- * Mint an account with no email and no password.
- *
- * Nothing in this package calls it any more — `passalong login` asks for an email and a password,
- * because an account nobody can sign in to is one that dies with the file it is stored in, and the
- * CLI used to make one without ever saying so. It stays exported because the route it calls is
- * still live and still right for the invite page, which mints before it claims, and because
- * removing a published export is a breaking change for anyone who imported it.
- */
 /**
  * Sign this machine in from the browser. `challenge` is the sha256, in hex, of a secret kept here;
  * what comes back is a short code to show, the page to open, and how often to ask whether it was
@@ -279,7 +241,6 @@ export async function devicePoll(id, verifier) {
   return said;
 }
 
-export const createAccount = () => call("/v1/accounts", { method: "POST", auth: false });
 export const me = () => call("/v1/me");
 export const updateMe = (patch) => call("/v1/me", { method: "PATCH", body: patch });
 
@@ -300,101 +261,83 @@ export const removeMember = (slug, who) =>
 export const join = (code) =>
   call(`/v1/invites/${encodeURIComponent(code)}/accept`, { method: "POST" });
 
-export const board = () => call("/v1/board");
-export const folders = (scope = "all", { query = "", guide = "" } = {}) =>
-  call(`/v1/folders${q({ scope, q: query, guide })}`);
-export const createFolder = (title, description = "", team = "", parent = "", color = "") =>
-  call("/v1/folders", { method: "POST", body: { title, description, team, parent, color } });
-export const folder = (id) => call(`/v1/folders/${encodeURIComponent(id)}`);
-export const updateFolder = (id, changes) =>
-  call(`/v1/folders/${encodeURIComponent(id)}`, { method: "PATCH", body: changes });
-export const folderDocument = (folderId, documentId) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`);
-export const folderAsset = (folderId, assetId) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/assets/${encodeURIComponent(assetId)}/agent`);
-export async function addFolderAsset(folderId, path, name = "") {
+export const projects = (scope = "all", query = "") =>
+  call(`/v1/projects${q({ scope, q: query })}`);
+export const createProject = (
+  title,
+  description = "",
+  team = "",
+  parent = "",
+  color = "",
+  repo = "",
+) =>
+  call("/v1/projects", { method: "POST", body: { title, description, team, parent, color, repo } });
+export const project = (id) => call(`/v1/projects/${encodeURIComponent(id)}`);
+export const updateProject = (id, changes) =>
+  call(`/v1/projects/${encodeURIComponent(id)}`, { method: "PATCH", body: changes });
+export const projectDocument = (projectId, documentId) =>
+  call(`/v1/projects/${encodeURIComponent(projectId)}/documents/${encodeURIComponent(documentId)}`);
+export const projectFile = (projectId, fileId) =>
+  call(`/v1/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(fileId)}/agent`);
+export async function addProjectFile(projectId, path, name = "") {
   const file = await stat(path);
-  if (!file.isFile()) throw new ApiError(400, "Choose a file to add to the folder.");
+  if (!file.isFile()) throw new ApiError(400, "Choose a file to add to the project.");
   if (file.size > 10 * 1024 * 1024) throw new ApiError(413, "That file is over 10 MB.");
-  return call(`/v1/folders/${encodeURIComponent(folderId)}/assets`, {
+  return call(`/v1/projects/${encodeURIComponent(projectId)}/files`, {
     method: "POST",
     body: new Uint8Array(await readFile(path)),
     uploadName: name || basename(path),
   });
 }
-export const createFolderDocument = (folderId, name, body) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/documents`, {
+export const createProjectDocument = (projectId, name, body) =>
+  call(`/v1/projects/${encodeURIComponent(projectId)}/documents`, {
     method: "POST",
     body: { name, body },
   });
-export const saveFolderDocument = (folderId, documentId, version, body) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
-    method: "PUT",
-    body: { version, body },
-  });
-export const renameFolderDocument = (folderId, documentId, name) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
-    method: "PATCH",
-    body: { name },
-  });
-export const moveFolderDocument = (folderId, documentId, to, name = "") =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
-    method: "PATCH",
-    body: name ? { folder: to, name } : { folder: to },
-  });
-export const folderDocumentHistory = (folderId, documentId, version = 0) =>
+export const saveProjectDocument = (projectId, documentId, version, body) =>
   call(
-    `/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}/revisions${version ? `/${version}` : ""}`,
+    `/v1/projects/${encodeURIComponent(projectId)}/documents/${encodeURIComponent(documentId)}`,
+    {
+      method: "PUT",
+      body: { version, body },
+    },
   );
-export const shareFolder = (folderId) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/share`, { method: "POST" });
-export const linkFolderGuide = (folderId, guide) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/guides`, { method: "POST", body: { guide } });
-export const unlinkFolderGuide = (folderId, guide) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/guides/${encodeURIComponent(guide)}`, {
-    method: "DELETE",
-  });
-export const deleteFolderDocument = (folderId, documentId) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/documents/${encodeURIComponent(documentId)}`, {
-    method: "DELETE",
-  });
-export const deleteFolderAsset = (folderId, assetId) =>
-  call(`/v1/folders/${encodeURIComponent(folderId)}/assets/${encodeURIComponent(assetId)}`, {
+/** Rename a document, move it to another project (`project`), or both. Its id and history stay. */
+export const patchProjectDocument = (projectId, documentId, changes) =>
+  call(
+    `/v1/projects/${encodeURIComponent(projectId)}/documents/${encodeURIComponent(documentId)}`,
+    {
+      method: "PATCH",
+      body: changes,
+    },
+  );
+export const projectDocumentHistory = (projectId, documentId, version = 0) =>
+  call(
+    `/v1/projects/${encodeURIComponent(projectId)}/documents/${encodeURIComponent(documentId)}/revisions${version ? `/${version}` : ""}`,
+  );
+export const deleteProjectDocument = (projectId, documentId) =>
+  call(
+    `/v1/projects/${encodeURIComponent(projectId)}/documents/${encodeURIComponent(documentId)}`,
+    {
+      method: "DELETE",
+    },
+  );
+export const deleteProjectFile = (projectId, fileId) =>
+  call(`/v1/projects/${encodeURIComponent(projectId)}/files/${encodeURIComponent(fileId)}`, {
     method: "DELETE",
   });
-/** What you did, newest first. `since` is a date prefix: 2026, 2026-09, 2026-09-11. */
-export const log = ({ repo = "", since = "", limit = 0 } = {}) =>
-  call(`/v1/log${q({ repo, since, limit: limit || "" })}`);
-export const notifications = ({ unread = true, limit = 0 } = {}) =>
-  call(`/v1/notifications${q({ unread: unread ? "1" : "", limit: limit || "" })}`);
-/** No ids means "everything unread". */
-export const markRead = (ids = []) =>
-  call("/v1/notifications/read", { method: "POST", body: { ids } });
-
-export const publish = (id, markdown) =>
-  call(`/v1/guides/${id}`, { method: "PUT", body: markdown });
-export const list = (query = "", scope = "") => call(`/v1/guides${q({ q: query, scope })}`);
-export const inbox = () => call("/v1/inbox");
-/** Open a report for a set of issues to be filed under. */
-export const createReport = (body) => call("/v1/reports", { method: "POST", body });
-/** One report and the issues filed under it, grouped by product area. */
-export const report = (id) => call(`/v1/reports/${encodeURIComponent(id)}`);
-export const get = (id, { peek = false } = {}) =>
-  call(`/v1/guides/${id}${q({ peek: peek ? "1" : "" })}`, { raw: true });
-/** One page of every guide this account can read, for `export`. Records no pull. */
-export const exportPage = (after = "") => call(`/v1/export${q({ after })}`);
-/**
- * A guide's follow-ups, one level down. `markdown` adds each one's content, oldest first and
- * capped server-side; neither form counts as opening them.
- */
-export const children = (id, { markdown = false } = {}) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/children${q({ markdown: markdown ? "1" : "" })}`);
+export const publish = (id, markdown) => call(`/v1/work/${id}`, { method: "PUT", body: markdown });
+export const list = (query = "", scope = "") => call(`/v1/work${q({ q: query, scope })}`);
+export const get = (id, { peek = false, as = null } = {}) =>
+  call(`/v1/work/${id}${q({ peek: peek ? "1" : "" })}`, { raw: true, as });
+/** One page of every piece of work this account can read, for `export`. Records no pull. */
+export const exportPage = (after = "", as = null) => call(`/v1/export${q({ after })}`, { as });
 /**
- * The guide this one came out of, with where it has got to. `markdown` adds its content. Like the
- * follow-ups, reading it is not opening it: no pull is recorded on the parent.
+ * The work this one came out of, with where it has got to. `markdown` adds its content. Reading it
+ * is not opening it: no pull is recorded on the parent.
  */
 export const parent = (id, { markdown = false } = {}) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/parent${q({ markdown: markdown ? "1" : "" })}`);
+  call(`/v1/work/${encodeURIComponent(id)}/parent${q({ markdown: markdown ? "1" : "" })}`);
 /**
  * Giving a plan away, for whoever the deployment names in `ADMIN_ACCOUNTS`. Every other account
  * gets a 404 from these, so the CLI does not have to know who the operator is either.
@@ -410,63 +353,29 @@ export const listGifts = () => call("/v1/admin/gifts");
 export const takeGiftBack = (id) =>
   call(`/v1/admin/gifts/${encodeURIComponent(id)}`, { method: "DELETE" });
 export const setStatus = (id, status) =>
-  call(`/v1/guides/${id}/status`, { method: "PATCH", body: { status } });
-export const remove = (id) => call(`/v1/guides/${id}`, { method: "DELETE" });
-/** Does it actually work? `note` is required when it does not. */
-export const verdict = (id, ok, note = "", detail = "") =>
-  call(`/v1/guides/${id}/verdict`, {
-    method: "PUT",
-    body: { ok, note, ...(detail ? { detail } : {}) },
-  });
-
+  call(`/v1/work/${id}/status`, { method: "PATCH", body: { status } });
+export const remove = (id) => call(`/v1/work/${id}`, { method: "DELETE" });
 export const tasks = () => call("/v1/tasks");
 export const nextTask = (body) => call("/v1/tasks/next", { method: "POST", body });
-export const taskProgress = (id, body) =>
-  call(`/v1/tasks/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
-export const finishTask = (id, body) =>
-  call(`/v1/tasks/${encodeURIComponent(id)}/finish`, { method: "POST", body });
-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: {} });
-export const sendBack = (id, why) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/send_back`, { method: "POST", body: { why } });
-/** Take work back from whoever holds it, of any kind. `/v1/tasks/…/release` is the old path. */
+  call(`/v1/work/${encodeURIComponent(id)}/reopen`, { method: "POST", body: { why } });
+/** Take work back from whoever holds it. */
 export const release = (id) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
-/** The four verbs every guide answers to. See docs/V2.md §11. */
+  call(`/v1/work/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
 export const working = () => call("/v1/working");
-export const handedIn = () => call("/v1/handed_in");
-export const recall = (id) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/recall`, { method: "POST", body: {} });
 export const assign = (id, to) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/assign`, { method: "POST", body: { to } });
+  call(`/v1/work/${encodeURIComponent(id)}/assign`, { method: "POST", body: { to } });
 export const take = (body) => call("/v1/take", { method: "POST", body });
 export const progress = (id, body) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
+  call(`/v1/work/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
 export const handIn = (id, body) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/hand_in`, { method: "POST", body });
+  call(`/v1/work/${encodeURIComponent(id)}/hand_in`, { method: "POST", body });
 export const ask = (id, body) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/ask`, { method: "POST", body });
+  call(`/v1/work/${encodeURIComponent(id)}/ask`, { method: "POST", body });
 export const reply = (id, body) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/reply`, { method: "POST", body: { body } });
+  call(`/v1/work/${encodeURIComponent(id)}/reply`, { method: "POST", body: { body } });
 export const pass = (id, body) =>
-  call(`/v1/guides/${encodeURIComponent(id)}/pass`, { method: "POST", body });
-export const ack = (id, taken, note = "") =>
-  call(`/v1/guides/${id}/ack`, { method: "PUT", body: { taken, note } });
-
-/**
- * Upload an image as evidence, and get back the URL a guide points at.
- *
- * Not `call()`: that serialises a body as JSON or markdown, and this route reads bytes and takes
- * the content type as the declaration of what they are. `name` is the label, and it travels in a
- * header rather than the body for the same reason.
- */
+  call(`/v1/work/${encodeURIComponent(id)}/pass`, { method: "POST", body });
 /**
  * Upload a file that is not a picture, and get back what the server made of it. The server decides
  * what the bytes are and refuses what it does not keep; `type` and `name` are hints. The name travels
@@ -477,6 +386,7 @@ export async function uploadFile(bytes, type, name = "") {
   const t = token();
   if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
   const headers = {
+    ...CLIENT,
     authorization: `Bearer ${t}`,
     "content-type": type || "application/octet-stream",
   };
@@ -498,6 +408,10 @@ export async function uploadFile(bytes, type, name = "") {
   return (await res.json()).attachment;
 }
 
+/**
+ * Upload a picture, and get back the URL work points at. Not `call()`: that serialises a body as
+ * JSON or markdown, and this route reads bytes and takes the content type as what they are.
+ */
 export async function uploadShot(bytes, type, name = "") {
   const t = token();
   if (!t) throw new ApiError(401, "not logged in — run `passalong login` to enable sync");
@@ -522,7 +436,7 @@ export async function uploadShot(bytes, type, name = "") {
   return (await res.json()).shot;
 }
 
-/** Fetch a guide by its share link (no account needed). Accepts the web URL or the .md URL. */
+/** Fetch work by its share link (no account needed). Accepts the web URL or the .md URL. */
 export async function fetchShared(url) {
   const u = new URL(url);
   if (!u.pathname.endsWith(".md")) u.pathname = `${u.pathname.replace(/\/$/, "")}.md`;
@@ -531,7 +445,3 @@ export async function fetchShared(url) {
     throw new ApiError(res.status, `could not fetch ${url}: ${res.status} ${res.statusText}`);
   return res.text();
 }
-
-export function shareUrl(id, key) {
-  return `${baseUrl()}/g/${id}/${key}`;
-}

package/src/capture.js

@@ -1,9 +1,8 @@
-// Fallback capture when no agent wrote a draft: scaffold one from the working directory so the
-// developer starts from "what changed" instead of a blank page. The Claude Code skill in
-// skills/passalong-capture does the real distillation from a session transcript.
+// What can be learned about where a command runs, without reading any session: the repo, its
+// branch, who is committing. Work written from inside a repo is for that repo.
 import { execFileSync } from "node:child_process";
 import { basename } from "node:path";
-import { template } from "./guide.js";
+import { serialize } from "./work.js";
 
 function git(cwd, ...args) {
   try {
@@ -40,59 +39,24 @@ export function context(cwd = process.cwd()) {
   const name = basename(root || cwd);
   const branch = root ? git(cwd, "rev-parse", "--abbrev-ref", "HEAD") : "";
   const author = git(cwd, "config", "user.name");
-  const commits = root ? git(cwd, "log", "--oneline", "-8").split("\n").filter(Boolean) : [];
-  const changed = root
-    ? git(cwd, "diff", "--stat", "HEAD~5..HEAD").split("\n").filter(Boolean).slice(-1)[0] || ""
-    : "";
-  const files = root
-    ? git(cwd, "diff", "--name-only", "HEAD~5..HEAD").split("\n").filter(Boolean)
-    : [];
   // The repo as the task queue names it: its remote when it has one, because two worktrees of one
-  // repo have two folder names and one remote. The folder name when there is no remote.
+  // repo have two project names and one remote. The project name when there is no remote.
   const repo = root ? repoKey(git(cwd, "remote", "get-url", "origin") || name) : "";
-  return { root, name, repo, branch, author, commits, changed, files };
+  return { root, name, repo, branch, author };
 }
 
 /**
- * A task draft from one sentence: the sentence as the title and the Goal, the rest left to fill.
+ * A piece of work from one sentence: the sentence is its title, what it says to a person, and its
+ * text, for whoever wrote it to add to before it goes.
  *
- * `target_context` defaults to the repo this runs in, because that is the likeliest repo a task
- * written from inside one is for — and it is in the editor, in the frontmatter, for the author
- * to change before it goes anywhere. Outside a repo it stays empty, which is a task for no repo.
+ * `target_context` is the repo this runs in, because that is the likeliest repo work written from
+ * inside one is for — and it is in the frontmatter, for the author to change before it goes
+ * anywhere. Outside a repo it stays empty, which is work for no repo.
  */
-export function taskScaffold(sentence, cwd = process.cwd()) {
-  const c = context(cwd);
-  const md = template({
-    kind: "task",
-    title: sentence,
-    // The person typed this sentence, so it is theirs to say to a person as well as to name the task.
-    summary: String(sentence).slice(0, 400),
-    author: c.author,
-    source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
-    target_context: c.repo,
+export function workScaffold(sentence, cwd = process.cwd()) {
+  const said = String(sentence).trim();
+  return serialize({
+    meta: { title: said, summary: said.slice(0, 400), target_context: context(cwd).repo },
+    body: `${said}\n`,
   });
-  return md.replace(/^## Goal\n/m, `## Goal\n${sentence}\n`);
-}
-
-/** A draft pre-filled with repo facts. Recent activity is appended as a comment for reference. */
-export function scaffold(cwd = process.cwd()) {
-  const c = context(cwd);
-  let md = template({
-    kind: "transfer",
-    title: "",
-    author: c.author,
-    source_context: c.branch && c.branch !== "HEAD" ? `${c.name}@${c.branch}` : c.name,
-  });
-  if (c.commits.length) {
-    md += [
-      "",
-      "<!-- passalong: recent activity in this repo, for reference while you write. Delete when done.",
-      ...c.commits.map((l) => `  ${l}`),
-      c.changed ? `  ${c.changed}` : "",
-      ...c.files.slice(0, 30).map((f) => `  ${f}`),
-      "-->",
-      "",
-    ].join("\n");
-  }
-  return md;
 }

package/src/checks.js

@@ -2,15 +2,15 @@
  * Running an Acceptance check, rather than reading the agent's account of running it.
  *
  * A hand-in used to be the agent's word about its own work: `ran` was a string, and the only rule
- * was that it was longer than a verdict. "ran the tests, all green" passed. This module is the
+ * was that it was longer than a yes. "ran the tests, all green" passed. This module is the
  * other half — when a check names the command that proves it, the command is run here and the exit
  * code is recorded from the process, so the agent reports what it did and the machine reports how
  * it went.
  *
- * **The command comes from the agent's own hand_in call, never from a guide.** A guide is written
+ * **The command comes from the agent's own hand_in call, never from work.** Work is written
  * somewhere else and pulled from a stranger's account; lifting a command out of its Acceptance
- * section and running it would turn every pulled guide into remote code execution. Nothing here
- * parses guide markdown, and nothing should.
+ * section and running it would turn every pulled work into remote code execution. Nothing here
+ * parses work markdown, and nothing should.
  *
  * This runs only where there is a shell. `src/mcp.js` is a local stdio server on the agent's own
  * machine, so it can; `apps/api/src/mcp-http.ts` is a Worker, so it cannot, and a hand-in over HTTP
@@ -19,7 +19,7 @@
  * What this deliberately does NOT do is parse test output. SWE-bench needs 57 per-framework log
  * parsers to tell a skipped test from a passing one, and a half-parser that guesses is worse than
  * none: it would refuse honest runs in shapes nobody thought of, and pass the ones it misread. The
- * exit code is the whole verdict here, which is also how a CI step decides.
+ * exit code is the whole answer here, which is also how a CI step decides.
  */
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";

package/src/hooks.js

@@ -1,4 +1,4 @@
-// The Claude Code hooks `passalong setup` installs. See docs/V2.md §11.
+// The Claude Code hooks `passalong setup` installs.
 //
 // Two moments an agent forgets what it holds: when a session starts (a restart, a /clear, a
 // compaction), and when it decides it is done. SessionStart runs `passalong now --hook session`
@@ -26,14 +26,10 @@ const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
  * 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 = {} }) {
+export function nowText({ held = [], ready = 0 }) {
   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: This worktree holds ${h.id} (${h.kind}): ${h.title || h.id}.`,
-    ];
+    const lines = [`Passalong: This worktree holds ${h.id}: ${h.title || h.id}.`];
     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.
@@ -56,7 +52,7 @@ export function nowText({ held = [], waiting = {} }) {
     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.id}: ${h.title || h.id}${h.state === "stalled" ? " — stalled" : ""}` +
           `${h.replies ? ` — ${plural(h.replies, "message", "messages")} waiting` : ""}`,
       );
     lines.push(
@@ -65,13 +61,8 @@ export function nowText({ held = [], waiting = {} }) {
     );
     return lines.join("\n");
   }
-  const parts = [];
-  if (waiting.ready)
-    parts.push(plural(waiting.ready, "ready task for this repo", "ready tasks for this repo"));
-  if (waiting.inbox)
-    parts.push(plural(waiting.inbox, "guide handed to you", "guides handed to you"));
-  if (!parts.length) return "";
-  return `Passalong: ${parts.join(" and ")}. Call take with no id to start the next one, when the user wants that.`;
+  if (!ready) return "";
+  return `Passalong: ${plural(ready, "piece of work is", "pieces of work are")} ready for this repo. Call take with no id to start the next one, when the user wants that.`;
 }
 
 /**
@@ -81,7 +72,7 @@ export function nowText({ held = [], waiting = {} }) {
  * 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 stopDecision({ 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.
   const open = held.filter((h) => !h.asking);
@@ -131,8 +122,8 @@ const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
 
 /**
  * One line: what this worktree's agent holds, then what needs you and what is ready here.
- * `needs` counts everything waiting on the person: work handed in for review, agents stuck on
- * them, and guides handed to them.
+ * `needs` counts everything waiting on the person: drafts to read, agents asking or stuck on them,
+ * and agents gone quiet.
  */
 export function statusText({ held = [], needs = 0, ready = 0 }) {
   const parts = [];