passalong 0.13.0 → 0.14.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukman Isiaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,18 @@
 # passalong
 
-Hand finished work to another context.
+Hand work to your AI coding agents, and get back what they did and how they checked it.
 
-Solve something non-trivial in one agent session. Run one command. Open a session in another
-repo, on another machine, or with a teammate, and the agent there already knows the whole story:
-the problem, the decisions and why, the steps, how to verify, and what went wrong along the way.
+Write a task, a bug or a finished change once. The agent that takes it starts knowing what done
+looks like and what was already decided, reports as it goes, and hands back a write-up with the
+evidence for each thing you asked for, which you approve or send back. One agent per job, and
+everyone can see who has what. Works with Claude Code, Codex, ChatGPT, Claude, or anything that
+speaks MCP or HTTP. See [passalong.dev](https://passalong.dev).
 
 ```sh
 npm i -g passalong
 passalong setup      # installs the Claude Code capture skill + registers the MCP server
 passalong login      # optional: sync guides across machines and get share links
+codex mcp add passalong -- passalong mcp   # Codex: the same MCP server
 ```
 
 ## The loop

package/bin/passalong

@@ -13,7 +13,8 @@
 //   passalong approve <id>        the work in review is done
 //   passalong reject <id> <why>   not done: back to Ready, and the next agent reads why
 //   passalong release <id>        take work back from whoever holds it, of any kind
-//   passalong attach <image>      upload evidence and print the markdown that points at it
+//   passalong attach <file>       upload a picture or a file and print the markdown that points at it
+//   passalong reply <id> <text>   write to whoever holds it (--file PATH to attach); or leave a note
 //   passalong pull <id|link>      fetch a guide into ./.passalong/ and print it
 //   passalong start <id|link>     pull it and take it — one command for "I am doing this"
 //   passalong inbox               guides handed to you that you have not pulled yet
@@ -38,7 +39,7 @@
 //   passalong archive <id>        off your board and out of the free tier's count (was `done`)
 //   passalong rm <id>             delete a guide locally and from sync
 //   passalong export [dir]        dump every guide as plain markdown (default ./passalong-export)
-//   passalong login [token]       sign in with your email and password, or attach this machine with a token
+//   passalong login [token]       sign in from the browser, or attach this machine with a token
 //   passalong me [--handle H] [--name N] [--email E]   who you are to teammates
 //   passalong team                current team and its members
 //   passalong team create <name>  start a team (you become its owner)
@@ -50,7 +51,7 @@
 //   passalong mcp                 run the MCP server over stdio
 //   passalong version             print the installed version (also -v, --version)
 import { execFileSync, spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -69,8 +70,11 @@ function flags(argv) {
     const t = argv[i];
     if (t.startsWith("--")) {
       const next = argv[i + 1];
-      if (next === undefined || next.startsWith("-")) out[t.slice(2)] = true;
-      else out[t.slice(2)] = argv[++i];
+      const key = t.slice(2);
+      const value = next === undefined || next.startsWith("-") ? true : argv[++i];
+      // A flag given twice keeps both, so `--file a.pdf --file b.csv` is two files. Nothing else
+      // repeats a flag, so nothing else sees an array.
+      out[key] = key in out && value !== true ? [out[key], value].flat() : value;
     } else out._.push(t);
   }
   return out;
@@ -90,6 +94,86 @@ const tty = process.stdout.isTTY && process.stdin.isTTY;
  * Written against readline rather than a dependency because this package has none beyond the MCP
  * SDK and zod, and asking for a line of text is not where that changes.
  */
+/** Open a page in the default browser, and say nothing if there is none to open. */
+function openPage(url) {
+  const [cmd, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  try {
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).on("error", () => {}).unref();
+  } catch {}
+}
+
+/**
+ * Sign in by approving in the browser: show a code, wait, and be handed a token. No password is
+ * typed here and no token is pasted between windows. Needs no terminal to ask on, so an agent can
+ * run it and tell the person which page to open.
+ */
+async function browserLogin() {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("hex");
+  const start = await api.deviceStart(challenge, `${hostname()} cli`).catch((e) => die(e.message));
+  console.error(`Open ${start.url}`);
+  console.error(`and check the page shows the code ${start.code}, then press Approve.`);
+  if (tty) openPage(start.url);
+  console.error("Waiting for you to approve it here… (Ctrl-C to stop)");
+  const until = Date.now() + start.expires_in * 1000;
+  while (Date.now() < until) {
+    await new Promise((r) => setTimeout(r, start.interval * 1000));
+    const got = await api.devicePoll(start.id, verifier).catch((e) => die(e.message));
+    if (!got) continue;
+    store.writeConfig({ token: got.token, api: api.baseUrl() });
+    console.error(`signed in (account ${got.account}) on ${api.baseUrl()}. Sync is on.`);
+    console.error("Attach other machines with:");
+    console.error(`  passalong login ${got.token}`);
+    console.error("(keep it private — it is a credential, not a password)");
+    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+    return;
+  }
+  die("nobody approved it in time. Run `passalong login` again.");
+}
+
+/** The old way, kept for anyone who asks for it with `--email`: an email and a password, typed here. */
+async function passwordLogin(f) {
+// An account you cannot sign in to is one that dies with this file. This used to mint one
+  // silently and then suggest adding a password afterwards; it asks up front instead.
+  if (!tty)
+    die(
+      "no terminal to ask on. Sign in at " +
+        `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
+    );
+
+  const email = f.email || (await ask("Email: "));
+  if (!email) die("an email is needed to sign in");
+  const password = await ask("Password: ", { hidden: true });
+  if (!password) die("a password is needed to sign in");
+
+  const label = `${hostname()} cli`;
+  let who = await api.signIn(email, password, { label }).catch((e) => e);
+  if (who instanceof Error) {
+    // 401 is "no such account, or the wrong password", said the same way on purpose so the API
+    // does not confirm which addresses exist. The CLI has to ask rather than guess, because
+    // creating an account for a mistyped address is worse than being told to try again.
+    if (who.status !== 401) die(who.message);
+    const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
+    if (yes !== "y" && yes !== "yes")
+      die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
+    const again = await ask("Choose a password: ", { hidden: true });
+    if (again !== password) die("those did not match");
+    who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
+  }
+
+  store.writeConfig({ token: who.token, api: api.baseUrl() });
+  console.error(`signed in as ${email} (account ${who.account}) on ${api.baseUrl()}. Sync is on.`);
+  console.error("Attach other machines with:");
+  console.error(`  passalong login ${who.token}`);
+  console.error("(keep it private — it is a credential, not a password)");
+  console.error("Give teammates a name to address you by: passalong me --handle <you>");
+}
+
 async function ask(question, { hidden = false } = {}) {
   const { createInterface } = await import("node:readline");
   const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
@@ -386,12 +470,33 @@ const commands = {
    * a guide travels as markdown to whoever holds its link, so a file beside it does not travel.
    */
   async attach(f) {
-    const file = f._[0] || die("usage: passalong attach <image> [--name LABEL]");
-    const shot = await passalong.attach(file, { name: f.name || "" }).catch((e) => die(e.message));
+    const file = f._[0] || die("usage: passalong attach <file> [--name LABEL]");
+    // A picture is evidence a page draws; anything else is a file somebody downloads.
+    const isImage = Object.keys(passalong.SHOT_TYPES).some((x) => file.toLowerCase().endsWith(x));
+    const shot = await (isImage ? passalong.attach : passalong.attachFile)(file, {
+      name: f.name || "",
+    }).catch((e) => die(e.message));
     process.stdout.write(`${shot.markdown}\n`);
     console.error(`uploaded ${shot.bytes} bytes → ${shot.url}`);
   },
 
+  /**
+   * Write to whoever holds a guide, or leave a note on one nobody holds yet. The person's side of
+   * `ask`: an agent that stopped to wait hears this when it takes the guide again.
+   */
+  async reply(f) {
+    const id = f._[0] || die("usage: passalong reply <id> <message> [--file PATH ...]");
+    const files = [f.file].flat().filter((x) => typeof x === "string");
+    const said = f._.slice(1).join(" ");
+    if (!said && !files.length) die("say something, or attach a file: passalong reply <id> <message>");
+    const r = await passalong.reply(id, said, { files }).catch((e) => die(e.message));
+    console.error(
+      r?.noted
+        ? `${id} — nobody holds it yet, so this is a note: whoever takes it is handed it first`
+        : `${id} — sent. Whoever holds it reads it the next time it checks in`,
+    );
+  },
+
   async inbox() {
     const rows = await passalong.inbox().catch((e) => die(e.message));
     if (!rows.length) return console.error("inbox empty — nothing handed to you that you haven't pulled");
@@ -673,40 +778,11 @@ const commands = {
         return;
       }
     }
-    // An account you cannot sign in to is one that dies with this file. This used to mint one
-    // silently and then suggest adding a password afterwards; it asks up front instead.
-    if (!tty)
-      die(
-        "no terminal to ask on. Sign in at " +
-          `${api.baseUrl()}/hub, then attach this machine with \`passalong login <token>\``,
-      );
-
-    const email = f.email || (await ask("Email: "));
-    if (!email) die("an email is needed to sign in");
-    const password = await ask("Password: ", { hidden: true });
-    if (!password) die("a password is needed to sign in");
-
-    const label = `${hostname()} cli`;
-    let who = await api.signIn(email, password, { label }).catch((e) => e);
-    if (who instanceof Error) {
-      // 401 is "no such account, or the wrong password", said the same way on purpose so the API
-      // does not confirm which addresses exist. The CLI has to ask rather than guess, because
-      // creating an account for a mistyped address is worse than being told to try again.
-      if (who.status !== 401) die(who.message);
-      const yes = (await ask(`No account signed in as ${email}. Create one? [y/N] `)).toLowerCase();
-      if (yes !== "y" && yes !== "yes")
-        die("not signed in. If the password was wrong, try again, or reset it at " + `${api.baseUrl()}/hub`);
-      const again = await ask("Choose a password: ", { hidden: true });
-      if (again !== password) die("those did not match");
-      who = await api.signIn(email, password, { make: true, label }).catch((e) => die(e.message));
-    }
-
-    store.writeConfig({ token: who.token, api: api.baseUrl() });
-    console.error(`signed in as ${email} (account ${who.account}) on ${api.baseUrl()}. Sync is on.`);
-    console.error("Attach other machines with:");
-    console.error(`  passalong login ${who.token}`);
-    console.error("(keep it private — it is a credential, not a password)");
-    console.error("Give teammates a name to address you by: passalong me --handle <you>");
+    // Passwords are for someone who asks: `--email` keeps the prompts. Everyone else is sent to the
+    // browser, which works with no terminal at all — an agent can start it, and the person it is
+    // working for clicks once.
+    if (f.email || f.password) return passwordLogin(f);
+    return browserLogin();
   },
 
   async me(f) {
@@ -864,10 +940,16 @@ const commands = {
         input = JSON.parse(raw || "{}");
       }
       if (!api.loggedIn()) return;
+      // The timeout is cleared as soon as the answer is in. Left running it holds the process open
+      // for the full five seconds after the hook has printed, and a session start or a stop that
+      // waits five seconds for nothing is the hook getting in the way, which it must never do.
+      let timer;
       const r = await Promise.race([
         passalong.now(),
-        new Promise((_, no) => setTimeout(() => no(new Error("timeout")), 5000)),
-      ]);
+        new Promise((_, no) => {
+          timer = setTimeout(() => no(new Error("timeout")), 5000);
+        }),
+      ]).finally(() => clearTimeout(timer));
       if (f.hook === "session") {
         const text = nowText(r);
         if (text)

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "passalong",
-  "version": "0.13.0",
-  "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
+  "version": "0.14.0",
+  "description": "Hand tasks, bugs and finished work to AI coding agents, and get back a write-up with evidence.",
+  "mcpName": "io.github.codellyson/passalong",
   "keywords": [
     "mcp",
     "claude-code",
@@ -9,7 +10,11 @@
     "handoff",
     "knowledge-transfer",
     "cli",
-    "markdown"
+    "markdown",
+    "mcp-server",
+    "coding-agents",
+    "task-management",
+    "codex"
   ],
   "homepage": "https://passalong.dev",
   "repository": {

package/skill/SKILL.md

@@ -98,11 +98,24 @@ pulls a guide, and steps that reproduce a defect are the one list that must neve
 remedy — an agent that follows them reproduces the bug, checks the Verification, finds it false
 because the bug is real, and reports that the guide does not work.
 
+## Say it to a person
+
+Everything below is written for another agent: exact, dense, full of ids and paths. A person reading
+their hub wants two sentences. So every guide carries a `summary:` in its frontmatter — plain
+language, 400 characters at most, no ids, paths or jargon, saying what this is and whether anybody
+has to do anything. It is what they see first; your document is behind it. A guide with no summary is
+refused.
+
+Write it the way you would tell a colleague in the corridor: "Webhook signatures are now checked
+before anything is stored. Done and working; nothing to do." Not: "Implemented HMAC-SHA512 verify in
+billing.ts per the Paystack spec, see PR 412."
+
 ## Guide structure
 
 ```markdown
 ---
 title: <what this accomplishes, as a verb phrase: "Add Paystack webhook verification">
+summary: <one or two plain sentences for a PERSON, 400 characters at most, no ids or paths: what this is and whether anyone has to act>
 author: <git user.name, if known>
 source_context: <repo or product this came from>
 status: published
@@ -135,6 +148,7 @@ Commands to run and what they should print. Test cases. What "done" looks like.
 ```markdown
 ---
 title: <what is broken, in one line: "Undo leaves section drag handles dead">
+summary: <one or two plain sentences for a PERSON: what is broken and whether anyone has to act>
 kind: bug
 severity: <s1 blocker | s2 major | s3 minor | s4 cosmetic>
 area: <which surface it is on>

package/src/api.js

@@ -126,6 +126,32 @@ export async function signIn(email, password, { make = false, label = "" } = {})
  * 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
+ * approved. Nothing in the answer is a credential.
+ */
+export const deviceStart = (challenge, label) =>
+  call("/v1/device/start", { method: "POST", auth: false, body: { challenge, label } });
+
+/** `null` while nobody has said yes; the account and its token once somebody has. */
+export async function devicePoll(id, verifier) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}/v1/device/poll`, {
+      method: "POST",
+      headers: { ...CLIENT, "content-type": "application/json" },
+      body: JSON.stringify({ id, verifier }),
+    });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (res.status === 202) return null;
+  const said = await res.json().catch(() => ({}));
+  if (!res.ok) throw new ApiError(res.status, said.message || res.statusText);
+  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 });
@@ -216,6 +242,10 @@ export const progress = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/progress`, { method: "PUT", body });
 export const handIn = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/hand_in`, { method: "POST", body });
+export const ask = (id, body) =>
+  call(`/v1/guides/${encodeURIComponent(id)}/ask`, { method: "POST", body });
+export const reply = (id, body) =>
+  call(`/v1/guides/${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 = "") =>
@@ -228,6 +258,36 @@ export const ack = (id, taken, note = "") =>
  * 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.
  */
+/**
+ * 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
+ * percent-encoded because a header cannot hold what a filename can.
+ */
+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 = {
+    authorization: `Bearer ${t}`,
+    "content-type": type || "application/octet-stream",
+  };
+  if (name) headers["x-file-name"] = encodeURIComponent(String(name));
+  let res;
+  try {
+    res = await fetch(`${baseUrl()}/v1/attachments`, { method: "POST", headers, body: bytes });
+  } catch (err) {
+    throw new ApiError(0, `could not reach ${baseUrl()} (${err.message})`);
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    let message = body;
+    try {
+      message = JSON.parse(body).message || body;
+    } catch {}
+    throw new ApiError(res.status, message || res.statusText);
+  }
+  return (await res.json()).attachment;
+}
+
 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");

package/src/capture.js

@@ -65,6 +65,8 @@ export function taskScaffold(sentence, cwd = process.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,

package/src/checks.js

@@ -76,7 +76,10 @@ function tail(out, max = OUTPUT_MAX) {
  */
 export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT_MS } = {}) {
   const cmd = String(check?.cmd ?? "").trim();
-  if (!cmd) return { check: check.check, ran: check.ran };
+  // What the agent says happened, in plain words: the person's line of the table. It is the agent's
+  // account and a run never touches it, so it rides along on every shape this returns.
+  const says = check?.says ? { says: check.says } : {};
+  if (!cmd) return { check: check.check, ran: check.ran, ...says };
 
   const opts = {
     cwd,
@@ -99,6 +102,7 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
           : `could not run: ${r.error?.message ?? "unknown error"}`;
     return {
       check: check.check,
+      ...says,
       cmd,
       exit: null,
       ok: false,
@@ -109,6 +113,7 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
   const cutShort = Boolean(BASH) && r.status === SIGPIPE;
   return {
     check: check.check,
+    ...says,
     cmd,
     exit: r.status,
     ok: r.status === 0 || cutShort,

package/src/guide.js

@@ -50,6 +50,19 @@ export const SETTABLE = ["draft", "published", "consumed"];
  * exactly as ambiguous as it was and adds a second state — a guide that exists and cannot be
  * shared — where the point was to have fewer.
  */
+/**
+ * What a guide says to a person, in a sentence or two, and the longest that may be.
+ *
+ * Everything an agent writes is written for another agent: exact, dense, full of ids and paths. A
+ * person scanning their work wants "what is this, and do I need to do anything", so every guide
+ * carries both — the document is the agent's form, and `summary:` is the human one, shown by default
+ * in the hub with the document behind "Show details".
+ *
+ * Said by the author and refused when absent, like `kind`, for the same reason: a summary written
+ * afterwards by something that was not there is a second voice that can say what nobody claimed.
+ */
+export const SUMMARY_MAX = 400;
+
 export const KINDS = ["transfer", "bug", "task"];
 
 // Body sections in the order a guide should present them. The heading text is what the
@@ -330,6 +343,9 @@ function quote(v) {
 const META_ORDER = [
   "id",
   "title",
+  // Right under the title: it is what a person reads first about it, so it is what the document
+  // opens with.
+  "summary",
   "kind",
   "created",
   "author",
@@ -447,6 +463,14 @@ export function validate({ meta, body }) {
   // a kind — `parseFrontmatter` seeds it — so what reaches this without one was built field by
   // field in code, and code is exactly what should have to say what it is making.
   const kind = meta.kind;
+  const said = String(meta.summary ?? "").trim();
+  if (!said)
+    errors.push(
+      "say it to a person: add `summary:` — one or two plain sentences, no ids or paths, saying what " +
+        `this is and whether anybody needs to act (${SUMMARY_MAX} characters at most)`,
+    );
+  else if (said.length > SUMMARY_MAX)
+    errors.push(`summary is ${said.length} characters; ${SUMMARY_MAX} at most`);
   if (!kind) errors.push(`say what this is: kind must be one of ${KINDS.join(", ")}`);
   else if (!KINDS.includes(kind)) errors.push(`kind must be one of ${KINDS.join(", ")}`);
   const have = sections(body);
@@ -489,6 +513,10 @@ export function stamp(guide, defaults = {}) {
  */
 export function bugGuide({
   title = "",
+  // What a person reads about it. A bug's own title is that when nothing else was said, and it is
+  // the author's own words, stated here by the caller that knows it is building a bug — not a
+  // default for something an author left off.
+  summary = "",
   problem = "",
   reproduce = "",
   verification = "",
@@ -544,6 +572,7 @@ export function bugGuide({
 
   const meta = {
     title,
+    summary: String(summary || "").trim() || title,
     kind: "bug",
     status,
     tags: ["bug", environment, area].filter(Boolean),
@@ -584,6 +613,7 @@ export function template(meta = {}) {
   return serialize({
     meta: {
       title: "",
+      summary: "",
       author: "",
       source_context: "",
       status: "draft",
@@ -620,6 +650,7 @@ function bugTemplate(meta = {}) {
   return serialize({
     meta: {
       title: "",
+      summary: "",
       kind: "bug",
       author: "",
       source_context: "",
@@ -660,6 +691,7 @@ function taskTemplate(meta = {}) {
   return serialize({
     meta: {
       title: "",
+      summary: "",
       kind: "task",
       author: "",
       source_context: "",
@@ -677,3 +709,101 @@ function taskTemplate(meta = {}) {
 export function stripPlaceholders(body) {
   return body.replace(/^<!-- passalong:.*?-->\n?/gm, "").trim();
 }
+
+// ---- reading a guide in parts, and how big one may be -----------------------------------------
+// Mirrors apps/api/src/sections.ts — apps/api/test/sections.test.mjs holds the two to the same
+// answers. Most of what is stored is a few very large guides (six of 123 held 72% of the text), and
+// an agent that wants only the Acceptance of a long task should not read the rest first.
+
+/** Over this a guide is large: its readers are offered the outline first, and its author a warning. */
+export const GUIDE_WARN = 20_000;
+/** Over this a new guide is refused by the server. A guide stored before it existed may keep its size. */
+export const GUIDE_MAX = 60_000;
+
+/** Where each heading starts, outside the frontmatter and outside code fences. */
+function headingLines(markdown) {
+  const fm = /^---\r?\n[\s\S]*?\r?\n---\r?\n?/.exec(markdown);
+  const bodyStart = fm ? fm[0].length : 0;
+  const lines = [];
+  let fence = "";
+  let at = bodyStart;
+  for (const raw of markdown.slice(bodyStart).split("\n")) {
+    const mark = /^\s*(```|~~~)/.exec(raw)?.[1];
+    if (mark) fence = fence ? (fence === mark ? "" : fence) : mark;
+    const m = !fence && !mark ? /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(raw) : null;
+    if (m) lines.push({ heading: m[2].trim(), level: m[1].length, start: at });
+    at += raw.length + 1;
+  }
+  return lines;
+}
+
+/** The end of the section that begins at lines[i]: the next heading at its level or above. */
+function sectionEnd(lines, i, total) {
+  for (let j = i + 1; j < lines.length; j++)
+    if (lines[j].level <= lines[i].level) return lines[j].start;
+  return total;
+}
+
+/** Every heading, with the characters in its section (nested ones included). */
+export function outline(markdown) {
+  const lines = headingLines(markdown);
+  return lines.map((l, i) => ({
+    heading: l.heading,
+    level: l.level,
+    chars: sectionEnd(lines, i, markdown.length) - l.start,
+  }));
+}
+
+/** One section by its heading — exact, then by its start, then by what it contains. */
+export function section(markdown, name) {
+  const lines = headingLines(markdown);
+  const want = String(name ?? "")
+    .trim()
+    .toLowerCase();
+  if (!want) return null;
+  const at = (test) => lines.findIndex((l) => test(l.heading.toLowerCase()));
+  const i = [
+    at((h) => h === want),
+    at((h) => h.startsWith(want)),
+    at((h) => h.includes(want)),
+  ].find((n) => n >= 0);
+  if (i === undefined) return null;
+  return {
+    heading: lines[i].heading,
+    text: markdown.slice(lines[i].start, sectionEnd(lines, i, markdown.length)).trimEnd(),
+  };
+}
+
+/** What a guide's author is told when it is on the large side. */
+export function sizeWarning(chars) {
+  return chars > GUIDE_WARN
+    ? `this guide is ${chars.toLocaleString("en")} characters, and over ${GUIDE_WARN.toLocaleString("en")} ` +
+        "it is read by outline first. Put logs, dumps and long output in a file (attach_file) and " +
+        "link it; keep the guide to what the next agent has to act on."
+    : null;
+}
+
+/**
+ * What an agent is shown instead of a large guide: who it is, what it is, and where its parts are.
+ * `path` is where the whole of it was written, for a search rather than a read.
+ */
+export function outlineText(markdown, { id = "", path = "" } = {}) {
+  const { meta } = parse(markdown);
+  const rows = outline(markdown)
+    .filter((h) => h.level <= 3)
+    .map(
+      (h) => `${"  ".repeat(h.level - 1)}- ${h.heading} (${h.chars.toLocaleString("en")} chars)`,
+    );
+  return [
+    `${meta.title || id} — ${meta.kind || "guide"}, ${markdown.length.toLocaleString("en")} characters`,
+    meta.summary ? `Summary: ${meta.summary}` : "",
+    "",
+    "Sections:",
+    ...rows,
+    "",
+    `Read one with get_guide ref=${id} section="<heading>", or the whole thing with full=true.` +
+      (path ? ` The full text is also on disk at ${path}, if you only need to search it.` : ""),
+  ]
+    .filter((l, i, a) => l !== "" || a[i - 1] !== "")
+    .join("\n");
+}

package/src/hooks.js

@@ -30,6 +30,13 @@ export function nowText({ held, waiting = {} }) {
       `Passalong: You hold ${held.id} (${held.kind}): ${held.title || held.id}.`,
     ];
     if (held.note) lines.push(`Last note: "${held.note}".`);
+    // The one thing here that is new information rather than a reminder: the person has written, and
+    // nothing else in the session will say so until the agent next checks in.
+    if (held.replies)
+      lines.push(
+        `${plural(held.replies, "message", "messages")} from the person ${held.replies === 1 ? "is" : "are"} ` +
+          `waiting for you: call take ${held.id} to read ${held.replies === 1 ? "it" : "them"} before anything else.`,
+      );
     if (held.state === "stalled")
       lines.push("It is marked stalled: nobody has heard from its agent in 30 minutes.");
     lines.push(
@@ -55,7 +62,9 @@ export function nowText({ held, waiting = {} }) {
  * would leave it no way to end.
  */
 export function stopVerdict({ held, input = {} }) {
-  if (!held || input.stop_hook_active) return null;
+  // An agent that asked a question was told to stop and wait, so it must be let: blocking it would
+  // make the instruction and the hook contradict each other, and the agent would pick one.
+  if (!held || held.asking || input.stop_hook_active) return null;
   return {
     decision: "block",
     reason:

package/src/mcp.js

@@ -9,7 +9,18 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import * as api from "./api.js";
 import { refusal, runChecks } from "./checks.js";
-import { AREAS, BUG_SECTIONS, parse, SECTIONS, TASK_SECTIONS, template } from "./guide.js";
+import {
+  AREAS,
+  BUG_SECTIONS,
+  GUIDE_WARN,
+  outlineText,
+  parse,
+  SECTIONS,
+  section as sectionOf,
+  sizeWarning,
+  TASK_SECTIONS,
+  template,
+} from "./guide.js";
 import * as passalong from "./passalong.js";
 
 /**
@@ -226,6 +237,21 @@ export function nextNote({ next = [], say = "" } = {}, id = "") {
   return lines.length ? `<!-- passalong: next:\n${lines.join("\n")}\n-->` : "";
 }
 
+/**
+ * What the person said to this agent since it last heard, in front of everything else: a reply is
+ * the thing the agent stopped for, and burying it under the guide it already knows is how it gets
+ * missed. See claims.deliver() in apps/api/src/claims.ts.
+ */
+export function repliesNote(replies = []) {
+  if (!Array.isArray(replies) || !replies.length) return "";
+  const lines = replies.map((r) => `  - ${String(r.body).replace(/\n/g, "\n    ")}`);
+  const files = replies.some((r) => String(r.body).includes("/v1/attachments/"))
+    ? "\n  Attached files are private: fetch one with your passalong token, e.g. " +
+      'curl -H "authorization: Bearer $PASSALONG_TOKEN (or the token in ~/.passalong/config.json)" -o <name> <url>.'
+    : "";
+  return `<!-- passalong: the person replied:\n${lines.join("\n")}${files}\n-->`;
+}
+
 /** A refusal that carries the server's own next move, when it sent one. */
 const failWith = (err) => {
   const said = nextNote(err.body || {});
@@ -252,7 +278,9 @@ export function buildServer() {
         "returns it; nobody else can take it here while you hold it, and its sender sees you are " +
         "on it. progress, with a one-line note at each milestone — 30 minutes of silence marks it " +
         "stalled. hand_in when done here. pass, with the reason, when it is not yours or you are " +
-        "stuck. Every answer ends with `next`: what to call now. Follow it, and when it says to " +
+        "stuck. ask, with a question, when you need an answer from the person: you keep what you " +
+        "hold, stop and wait, and take it again once they have replied. Every answer ends with " +
+        "`next`: what to call now. Follow it, and when it says to " +
         "stop, stop. OPEN A GUIDE YOU MEAN TO ACT ON WITH take, NOT get_guide: get_guide only " +
         "reads, and the sender learns nothing. If take says somebody else has it, tell the user " +
         "instead of doing the work twice.\n" +
@@ -261,6 +289,11 @@ export function buildServer() {
         "Collect it as you work rather than writing it from memory at the end. hand_in without " +
         "it is refused, because the write-up and the verdict are both your word for your own " +
         "work and evidence is the part the person reviewing it can check.\n" +
+        "EVERY GUIDE SAYS WHAT IT IS TO A PERSON. The document is for agents: exact, dense, full of " +
+        "ids and paths. Put `summary:` in its frontmatter — one or two plain sentences, 400 " +
+        "characters at most, no ids, paths or jargon, saying what this is and whether anybody has " +
+        "to act. It is what the person sees first in their hub; the document is behind it. A guide " +
+        "with no summary is refused.\n" +
         "SAY WHICH KIND IT IS. There is no default: a guide with no `kind:` line is refused, and so " +
         "is a spelling that is not one of the three. " +
         `kind: task is work nobody has done yet. Sections: ${TASK_SECTIONS.join(", ")}. ` +
@@ -331,8 +364,13 @@ export function buildServer() {
     const note = nextNote({ next, say }, id);
     // The note is what the agent acts on and it is prose, so it stays in the text half only. The
     // structured half is the answer itself, which is what `outputSchema` below describes.
+    // A reply goes first, in prose: it is what the agent stopped for, and inside the JSON it reads
+    // as one more field.
+    const said = repliesNote(rest.replies);
     return {
-      ...text(`${JSON.stringify(rest, null, 2)}${note ? `\n${note}` : ""}`),
+      ...text(
+        `${said ? `${said}\n` : ""}${JSON.stringify(rest, null, 2)}${note ? `\n${note}` : ""}`,
+      ),
       structuredContent: rest,
     };
   };
@@ -359,8 +397,9 @@ export function buildServer() {
         `<!-- passalong: ${r.guide.id} is yours` +
         `${r.guide.resumed ? " (you already held it — carry on from where it was left)" : ""}; ` +
         `written to ${r.path}. -->`;
+      const said = repliesNote(r.replies);
       return text(
-        `${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
+        `${said ? `${said}\n\n` : ""}${from}${leadFor(meta)}${r.guide.markdown}${siblings}${context ? `\n\n${context}` : ""}` +
           `\n\n${held}\n${nextNote(r, r.guide.id)}\n${passalong.followUpNote(meta)}`,
       );
     } catch (err) {
@@ -368,7 +407,7 @@ export function buildServer() {
       if (h)
         return fail({
           message:
-            `${err.message}. Somebody else is on it here${h.note ? ` (last said: "${h.note}")` : ""}. ` +
+            `${err.message}. Somebody else is on it here${h.agent ? ` (agent ${h.agent}${h.host ? ` on ${h.host}` : ""})` : ""}${h.note ? ` (last said: "${h.note}")` : ""}. ` +
             "Tell the user before doing this work too; get_guide reads it without taking it.",
         });
       return failWith(err);
@@ -428,6 +467,14 @@ export function buildServer() {
     }
   }
 
+  async function doAsk({ id, question, cwd }) {
+    try {
+      return answer(await passalong.ask(id, question, { cwd: cwd || process.cwd() }), id);
+    } catch (err) {
+      return failWith(err);
+    }
+  }
+
   async function doPass({ id, why, cwd }) {
     try {
       return answer(await passalong.pass(id, why, { cwd: cwd || process.cwd() }), id);
@@ -623,6 +670,12 @@ export function buildServer() {
           .array(
             z.object({
               title: z.string(),
+              summary: z
+                .string()
+                .describe(
+                  "one or two plain sentences for a PERSON, no ids or paths: what this task is and " +
+                    "why it matters. The goal below is for the agent; this is what a person reads",
+                ),
               goal: z.string().describe("what is true when this step is done"),
               acceptance: z.string().describe("checks a person can run, one per line"),
               context: z.string().optional(),
@@ -694,7 +747,14 @@ export function buildServer() {
         "without one marks it stalled. If the answer says you no longer hold it, stop.",
       inputSchema: {
         id: z.string().describe("the id of what you hold"),
-        note: z.string().optional().describe('one line, e.g. "migrating schema, 2 of 5 steps"'),
+        note: z
+          .string()
+          .optional()
+          .describe(
+            'one plain sentence in the first person, as you would tell the person: "Reading ' +
+              'the settings page to find where the toggle goes." Start it with BLOCKED: when ' +
+              "you are stopped and need an answer",
+          ),
         cwd: z
           .string()
           .optional()
@@ -738,27 +798,44 @@ export function buildServer() {
           ),
         checks: z
           .array(
-            z.object({
-              check: z
-                .string()
-                .describe(
-                  "the line this answers, in the guide's own words: an Acceptance line on a task, " +
-                    "a Verification line on a handoff or a bug",
-                ),
-              ran: z
-                .string()
-                .optional()
-                .describe("what you ran for it, and what came back; not needed when `cmd` is set"),
-              cmd: z
-                .string()
-                .optional()
-                .describe(
-                  "the shell command that proves this line, run here before the hand-in lands — " +
-                    "its exit code decides the check and its output is recorded as the evidence. " +
-                    "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
-                    '"the badge reads 3" — then SHOW it with attach_screenshot and put the line it returns in `ran`; a check is run or shown, and describing what you saw is refused',
-                ),
-            }),
+            // A bare string is a check line with nothing behind it. Let it through to the server's
+            // refusal, which says what to send, rather than a schema error that says only "expected
+            // object".
+            z.preprocess(
+              (v) => (typeof v === "string" ? { check: v } : v),
+              z.object({
+                check: z
+                  .string()
+                  .describe(
+                    "the line this answers, in the guide's own words: an Acceptance line on a task, " +
+                      "a Verification line on a handoff or a bug",
+                  ),
+                says: z
+                  .string()
+                  .optional()
+                  .describe(
+                    'what happened, in one plain sentence for a PERSON: "Swagger lists all six ' +
+                      'endpoints, each with request and response schemas." It is the row they read ' +
+                      "in the review table; the evidence stays folded behind it. Strongly " +
+                      "recommended: a check without one shows only the line it answers",
+                  ),
+                ran: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "what you ran for it, and what came back; not needed when `cmd` is set",
+                  ),
+                cmd: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "the shell command that proves this line, run here before the hand-in lands — " +
+                      "its exit code decides the check and its output is recorded as the evidence. " +
+                      "Non-zero refuses the hand-in. Leave it out for a check nobody can run, like " +
+                      '"the badge reads 3" — then SHOW it with attach_screenshot and put the line it returns in `ran`; a check is run or shown, and describing what you saw is refused',
+                  ),
+              }),
+            ),
           )
           .optional()
           .describe(
@@ -768,7 +845,13 @@ export function buildServer() {
               "running it and is refused",
           ),
         ok: z.boolean().optional().describe("handoff or bug: did its Verification hold"),
-        note: z.string().optional().describe("one line; required when ok is false"),
+        note: z
+          .string()
+          .describe(
+            "one plain sentence, in the first person, saying what you did and how it went: " +
+              '"Added the toggle to Settings; it survives a reload." It is the first thing the ' +
+              "person reads, and the evidence is behind it. Say what went wrong when ok is false",
+          ),
         writeup: z
           .string()
           .optional()
@@ -805,6 +888,37 @@ export function buildServer() {
     async (args) => doHandIn(args),
   );
 
+  server.registerTool(
+    "ask",
+    {
+      title: "Ask the person",
+      outputSchema: openObject({ id: z.string(), lease_until: z.string() }),
+      annotations: ADDS,
+      description:
+        "You need the person's answer before you can go on. Ask one clear question, with the " +
+        "context it needs to be answered without opening your terminal. You keep what you hold " +
+        "and nobody else can take it. Then STOP and tell the user you are waiting: do not carry " +
+        "on guessing. When they have replied, call take with this id and their reply comes back " +
+        "with it. Use `pass` instead when the work is not yours; a progress note starting " +
+        "BLOCKED: is the older way of saying this, and is not heard as a question.",
+      inputSchema: {
+        id: z.string().describe("passalong id"),
+        question: z
+          .string()
+          .describe(
+            "one clear question in the first person, a few sentences at most, plain text: " +
+              '"Should the dark-mode toggle live in Settings or the header? The header is ' +
+              'crowded on mobile." What you were about to do, if they just say yes, helps',
+          ),
+        cwd: z
+          .string()
+          .optional()
+          .describe("the worktree you are working in; default is the server's cwd"),
+      },
+    },
+    async (args) => doAsk(args),
+  );
+
   server.registerTool(
     "pass",
     {
@@ -833,7 +947,9 @@ export function buildServer() {
       title: "Get guide",
       annotations: READS,
       description:
-        "READ a transfer guide by passalong id or share link and return its full markdown. Also " +
+        "READ a transfer guide by passalong id or share link and return its markdown. A guide over " +
+        "20,000 characters comes back as an outline (its headings and their sizes) unless you ask " +
+        "for `section`, for one part, or `full`, for all of it. Also " +
         "writes it to .passalong/<id>.md in the working directory so it survives the session. " +
         "Pulling a teammate's guide tells them the transfer landed. Use this to look at a guide " +
         "you have not committed to. If you are about to DO the work, call take instead: " +
@@ -845,12 +961,38 @@ export function buildServer() {
           .string()
           .optional()
           .describe("directory to write .passalong/<id>.md into; default is the server's cwd"),
+        section: z
+          .string()
+          .optional()
+          .describe("read only the part under this heading, e.g. Acceptance; see the outline"),
+        outline: z
+          .boolean()
+          .optional()
+          .describe("just the headings and their sizes, whatever the guide's length"),
+        full: z
+          .boolean()
+          .optional()
+          .describe("the whole document, even one over 20,000 characters"),
       },
     },
-    async ({ ref, cwd }) => {
+    async ({ ref, cwd, section, outline, full }) => {
       try {
         const { markdown, path, from } = await passalong.pull(ref, { cwd: cwd || process.cwd() });
         const meta = parse(markdown).meta;
+        if (section) {
+          const part = sectionOf(markdown, section);
+          if (!part)
+            return text(
+              `No heading matching "${section}".\n\n${outlineText(markdown, { id: meta.id || ref, path })}`,
+            );
+          return text(
+            `${part.text}\n\n<!-- passalong: ${meta.id || ref}, "${part.heading}" only; the whole guide is at ${path} -->`,
+          );
+        }
+        if (outline || (!full && markdown.length > GUIDE_WARN))
+          return text(
+            `${outlineText(markdown, { id: meta.id || ref, path })}\n\n<!-- passalong: ${from}; written to ${path} -->`,
+          );
         const lead = leadFor(meta);
         const siblings = await related(meta);
         // Follow-ups are more context for this guide, so they come with it — after the document,
@@ -930,6 +1072,72 @@ export function buildServer() {
     },
   );
 
+  server.registerTool(
+    "attach_file",
+    {
+      title: "Attach a file",
+      annotations: { ...ADDS, openWorldHint: true },
+      description:
+        "Upload a file that is not a picture — a log, a PDF, a CSV, a zip, up to 10MB — and get " +
+        "back the markdown line that points at it. For a guide body or a bug report: put the " +
+        "line there and publishing claims the file. It is private, so only people who can read " +
+        "that guide can download it; for something a reviewer must SEE, use attach_screenshot. " +
+        "Pictures belong to attach_screenshot, not here.",
+      inputSchema: {
+        file: z.string().describe("path to the file on this machine"),
+        name: z.string().default("").describe("label for the file; defaults to its filename"),
+      },
+    },
+    async ({ file, name }) => {
+      try {
+        const got = await passalong.attachFile(file, { name: name || "" });
+        return text(
+          `${JSON.stringify({ id: got.id, url: got.url, bytes: got.bytes }, null, 2)}\n\n` +
+            `Put this in the guide body:\n${got.markdown}`,
+        );
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "reply",
+    {
+      title: "Write to the agent",
+      annotations: ADDS,
+      description:
+        "A person's tool, for someone driving their work from an assistant: write to whoever " +
+        "holds a guide — an answer to a question it asked, or something you thought of since — " +
+        "or, when nobody holds it yet and it is yours, leave a note for whoever takes it. Plain " +
+        "text, 1000 characters. `files` are paths on this machine: a picture is drawn in the " +
+        "thread and anything else is a file to download. Only its author, whoever it is " +
+        "assigned to, or whoever holds it can write; the agent reads it the next time it " +
+        "checks in. Agents answering their own questions do not use this: they use ask and take.",
+      inputSchema: {
+        id: z.string().describe("passalong id"),
+        text: z.string().default("").describe("what to say; may be empty when attaching a file"),
+        files: z
+          .array(z.string())
+          .max(3)
+          .default([])
+          .describe("paths to up to three files or pictures to attach"),
+      },
+    },
+    async ({ id, text: said, files }) => {
+      try {
+        const r = await passalong.reply(id, said, { files });
+        return text(
+          r?.noted
+            ? `Nobody holds ${id} yet, so this is a note: whoever takes it is handed it first.`
+            : `Sent to whoever holds ${id}. It reads this the next time it checks in.`,
+        );
+      } catch (err) {
+        return failWith(err);
+      }
+    },
+  );
+
   server.registerTool(
     "publish_guide",
     {
@@ -983,6 +1191,7 @@ export function buildServer() {
           parent: guide.meta.parent || "",
           notified,
           path,
+          ...(sizeWarning(markdown.length) ? { warning: sizeWarning(markdown.length) } : {}),
           // A task does not go live on publish, and an agent that reports "queued it" has told
           // the user something untrue. Said in the result so it is said to them.
           ...(guide.meta.kind === "task" && guide.meta.status === "draft"
@@ -1036,6 +1245,13 @@ export function buildServer() {
                     "they go under Problem, where a reader looks first",
                 ),
               title: z.string().describe("what is broken, in one line"),
+              summary: z
+                .string()
+                .optional()
+                .describe(
+                  "one or two plain sentences for a PERSON, no ids or paths: what is broken and " +
+                    "whether anyone needs to act. Defaults to the title",
+                ),
               problem: z
                 .string()
                 .describe(

package/src/passalong.js

@@ -481,6 +481,9 @@ 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.
+            ...(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 } : {}),
           })),
@@ -524,6 +527,23 @@ export async function pass(id, why, { cwd = process.cwd() } = {}) {
   });
 }
 
+/**
+ * Ask the person a question and wait, keeping what you hold. Not `pass`, which gives the work back,
+ * and not `progress`, which says carry on: the answer to this one is "stop, and take it again when
+ * they have replied", and the reply comes back with that `take`.
+ */
+export async function ask(id, question, { cwd = process.cwd() } = {}) {
+  needsSync("asking");
+  if (!String(question || "").trim())
+    throw new PassalongError("say what you need to know, so the person can answer it");
+  const fence = fenceFor(id, cwd);
+  return api.ask(id, {
+    agent: agent(cwd).agent,
+    question,
+    ...(fence === undefined ? {} : { fence }),
+  });
+}
+
 /**
  * What this worktree's agent holds right now, and what is waiting for it: what the session-start
  * and stop hooks read (src/hooks.js). `held` is null when it holds nothing. Counts are best effort
@@ -555,7 +575,7 @@ export async function now({ cwd = process.cwd() } = {}) {
       x.mine &&
       (x.state === "review" ||
         x.state === "stalled" ||
-        (x.state === "claimed" && /^BLOCKED:/i.test(x.claim?.note || ""))),
+        (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 };
@@ -731,6 +751,64 @@ export async function attach(file, { name = "" } = {}) {
   return { ...shot, markdown: `![${name || basename(file)}](${shot.url})` };
 }
 
+/**
+ * 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.
+ */
+const FILE_HINTS = {
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".csv": "text/csv",
+  ".json": "application/json",
+  ".md": "text/markdown",
+};
+
+/** The most the server keeps of one file. Mirrors ATTACH_MAX in apps/api/src/attachments.ts. */
+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.
+ */
+export async function attachFile(file, { name = "" } = {}) {
+  if (!api.loggedIn())
+    throw new PassalongError("attaching a file needs sync — run `passalong login` first");
+  if (!existsSync(file)) throw new PassalongError(`no file at ${file}`);
+  const bytes = readFileSync(file);
+  if (!bytes.length) throw new PassalongError(`${file} is empty`);
+  if (bytes.length > FILE_MAX)
+    throw new PassalongError(
+      `${file} is ${Math.round(bytes.length / 1024 / 1024)}MB and the limit is 10MB — send a link instead`,
+    );
+  const ext = file.includes(".") ? file.slice(file.lastIndexOf(".")).toLowerCase() : "";
+  const label = (name || basename(file)).replace(/[[\]()]/g, "");
+  const attachment = await api.uploadFile(bytes, FILE_HINTS[ext] || "", name || basename(file));
+  return { ...attachment, markdown: `[${label}](${attachment.url})` };
+}
+
+/**
+ * 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.
+ */
+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);
+  }
+  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.
  *
@@ -1044,7 +1122,14 @@ export async function planTasks(steps, { cwd = process.cwd() } = {}) {
       ...section("Acceptance", step.acceptance),
       ...section("Out of scope", step.out_of_scope),
     ].join("\n");
-    const meta = { title: step.title, kind: "task", target_context: step.target_context ?? repo };
+    // 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).
+    const meta = {
+      title: step.title,
+      summary: step.summary,
+      kind: "task",
+      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);