passalong 0.6.0 → 0.8.0

package/README.md

@@ -35,11 +35,11 @@ passalong open <id> [--print] view a guide in the browser (or the terminal)
 passalong hub                 open your synced guides in the browser
 passalong works <id>          you tried it and it holds up
 passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
-passalong done <id>           deprecated: mark consumed
+passalong archive <id>        off your board and out of the free tier's count (was `done`)
 passalong promote <id>        deprecated: mark promoted
 passalong rm <id>             delete a guide locally and from sync
 passalong export [dir]        dump every guide as plain markdown
-passalong login [token]       create an account, or attach this machine with a token from your hub
+passalong login [token]       sign in with your email and password, 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)

package/bin/passalong

@@ -25,12 +25,20 @@
 //   passalong hub                 open your synced guides in the browser
 //   passalong take <id>           you are doing it — said before the work, so the sender stops guessing
 //   passalong pass <id> <why>     it is not yours — hands it back to its author with your reason
+//   passalong assign <id> <to>    give it to @handle, a #group, or "team" — yours, or assigned to you
+//   passalong admin create <email>   make an account that runs Passalong (owner only)
+//   passalong admin list          who runs it
+//   passalong admin grant|revoke <@handle>   make an existing account an admin, or stop it being one
+//   passalong gift <who> --until <date> [--why "..."] [--seats N]
+//                                 give Solo to @handle, or Team to team/slug, until a date (operator only)
+//   passalong gifts               what has been given away, and what is still running
+//   passalong ungift <gift id>    take one back now
 //   passalong works <id>          you tried it and it holds up
 //   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
-//   passalong done <id>           archive it: off your board and out of the free tier's count
+//   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]       create an account, or attach this machine with a token from your hub
+//   passalong login [token]       sign in with your email and password, 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)
@@ -44,7 +52,7 @@
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, hostname } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import * as api from "../src/api.js";
@@ -75,6 +83,38 @@ function die(msg) {
 
 const tty = process.stdout.isTTY && process.stdin.isTTY;
 
+/**
+ * One line typed at the terminal. `hidden` turns the echo off, so a password does not end up in a
+ * screen share, a scrollback or somebody's terminal recording.
+ *
+ * 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.
+ */
+async function ask(question, { hidden = false } = {}) {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+  if (hidden) {
+    // readline still writes the prompt itself; everything after it is swallowed. The newline the
+    // user's Return would have echoed is put back by hand, or the next line starts mid-prompt.
+    rl.output.write(question);
+    rl._writeToOutput = () => {};
+  }
+  try {
+    // `close` as well as an answer: stdin reaching EOF part-way through — a pipe, a closed pty, a
+    // ^D — never calls the question's callback, and without this the promise is simply never
+    // settled and the process exits on a warning about it rather than saying what happened.
+    const answer = await new Promise((done) => {
+      rl.on("close", () => done(null));
+      rl.question(hidden ? "" : question, done);
+    });
+    if (hidden) process.stdout.write("\n");
+    if (answer === null) die("nothing to read from — sign in at the terminal, or pass a token");
+    return answer.trim();
+  } finally {
+    rl.close();
+  }
+}
+
 function edit(path) {
   const editor = process.env.VISUAL || process.env.EDITOR || "vi";
   const r = spawnSync(editor, [path], { stdio: "inherit", shell: true });
@@ -478,6 +518,86 @@ const commands = {
     console.error(`${r.id} handed back — the author has been told: "${r.note}"`);
   },
 
+  async assign(f) {
+    const id = f._[0] || die('usage: passalong assign <id> <@handle | #group | team>');
+    const to = f._[1] || die('say who: @handle for one person, #group, or "team" for everyone');
+    const r = await passalong.assign(id, to).catch((e) => die(e.message));
+    const back = r.taken_back ? ` — taken back from ${r.taken_back} who had it, and they were told` : "";
+    console.error(`${r.id} is now for ${r.to || "everyone in the team"}${back}`);
+  },
+
+  // ---- who runs the product ---------------------------------------------------------------
+  // `passalong admin <create|list|grant|revoke>`. An admin signs in like anybody else: the role is
+  // a column, so there is no admin password and no admin token — only an account that has it.
+  // "admin" is the word everywhere a person reads; `super` stays the stored value.
+
+  async admin(f) {
+    const what = f._[0] || "list";
+    if (what === "create") {
+      const email = f._[1] || die("usage: passalong admin create <email>");
+      const r = await api.makeAdmin(email).catch((e) => die(e.message));
+      // Shown once, and only here. The link is a day long because it is handed to somebody
+      // rather than clicked on the spot.
+      // Three labelled values on stdout, so one can be cut out with awk. "password link", not
+      // "password": the value is a URL, and somebody will try to paste it into a password field.
+      console.log(`account        ${r.account}`);
+      console.log(`token          ${r.token}`);
+      console.log(`password link  ${r.password_url}`);
+      console.error(
+        `\n${r.email} is an admin. The token is for \`passalong login\`, the link sets their ` +
+          `password for the hub, and it expires ${r.expires.slice(0, 10)}. Neither is shown again.`,
+      );
+      return;
+    }
+    if (what === "grant" || what === "revoke") {
+      const who = f._[1] || die(`usage: passalong admin ${what} <@handle | account id>`);
+      const call = what === "grant" ? api.grantAdmin : api.revokeAdmin;
+      const r = await call(who).catch((e) => die(e.message));
+      console.error(
+        what === "grant" ? `${r.name} is now an admin` : `${r.name} is no longer an admin`,
+      );
+      return;
+    }
+    if (what !== "list") die("usage: passalong admin <create <email> | list | grant | revoke>");
+    const { supers = [] } = await api.listAdmins().catch((e) => die(e.message));
+    if (!supers.length) return console.error("nobody is an admin yet");
+    for (const s of supers)
+      console.log(`${s.id}  ${s.name}${s.email ? `  ${s.email}` : ""}  since ${s.since.slice(0, 10)}`);
+  },
+
+  // ---- giving a plan away -----------------------------------------------------------------
+  // Only for whoever the deployment names in ADMIN_ACCOUNTS; for everybody else the routes behind
+  // these are 404, and the message says so rather than pretending the command does not exist.
+
+  async gift(f) {
+    const to = f._[0] || die('usage: passalong gift <@handle | team/slug> --until 2027-09-23 [--why "..."]');
+    const until = f.until || die("say when it ends: --until 2027-09-23. A gift with no end is a price change");
+    const r = await api
+      .giveGift({ to, until, why: f.why || "", seats: Number(f.seats || 0) })
+      .catch((e) => die(e.message));
+    // The seat count is said back whether or not it was asked for: left off, it is the number of
+    // members the team has today, and an operator should read which number that turned out to be.
+    const seats = r.kind === "team" ? ` for ${r.seats} seat${r.seats === 1 ? "" : "s"}` : "";
+    console.error(`${r.to} is on ${r.plan}${seats} until ${r.until.slice(0, 10)} — gift ${r.id}`);
+  },
+
+  async gifts() {
+    const { gifts = [] } = await api.listGifts().catch((e) => die(e.message));
+    if (!gifts.length) return console.error("no plans given away yet");
+    for (const g of gifts) {
+      const state = g.live ? `until ${g.until.slice(0, 10)}` : "over";
+      console.log(
+        `${g.id}  ${g.plan.padEnd(5)} ${state.padEnd(16)} ${g.to}${g.why ? ` — ${g.why}` : ""}`,
+      );
+    }
+  },
+
+  async ungift(f) {
+    const id = f._[0] || die("usage: passalong ungift <gift id>  (passalong gifts lists them)");
+    await api.takeGiftBack(id).catch((e) => die(e.message));
+    console.error(`${id} taken back — that plan is lapsed as of now`);
+  },
+
   async works(f) {
     const id = f._[0] || die("usage: passalong works <id>");
     const r = await passalong.verdict(id, true, f._.slice(1).join(" ")).catch((e) => die(e.message));
@@ -495,16 +615,29 @@ const commands = {
   /**
    * Archive a guide: off your board, and out of what the free tier counts.
    *
-   * It was deprecated for meaning "I implemented it", which is the reader's judgement and belongs
-   * to the verdict. As shelf space it has a job nothing else does — it is the only way under the
-   * sync limit that does not delete the work, and the 402 says so by name.
+   * The command was `done`, and the status it sets is still `consumed`, because both once meant "I
+   * implemented it". That meaning went to the verdict, where it belongs — it is the reader's
+   * judgement, not the author's — and what was left is shelf space, which has a job nothing else
+   * does: the only way under the sync limit that does not delete the work, and the 402 says so by
+   * name. So the command says what it does now.
+   *
+   * `consumed` stays on disk. It is a status inside markdown files in other people's
+   * repositories, and `validate()` refuses a status it does not know, so renaming the value would
+   * make a guide shared a month ago fail to re-share today. The word people read and the token the
+   * format stores are allowed to differ; what is not allowed is two words for people.
    */
-  async done(f) {
-    const id = f._[0] || die("usage: passalong done <id>");
+  async archive(f) {
+    const id = f._[0] || die("usage: passalong archive <id>");
     const g = await passalong.setStatus(id, "consumed").catch((e) => die(e.message));
     console.error(`${g.meta.id} archived — off your board, and it no longer counts against sync`);
   },
 
+  /** What `archive` was called. Kept so a script written against it still runs, and says so. */
+  async done(f) {
+    console.error("`passalong done` is now `passalong archive` — it archives, it does not mark work done.");
+    return commands.archive(f);
+  },
+
   async rm(f) {
     const id = f._[0] || die("usage: passalong rm <id>");
     await passalong.remove(id).catch((e) => die(e.message));
@@ -533,14 +666,40 @@ const commands = {
         return;
       }
     }
-    const { token, account } = await api.createAccount().catch((e) => die(e.message));
-    store.writeConfig({ token, api: api.baseUrl() });
-    console.error(`account ${account} created on ${api.baseUrl()}. Sync is on.`);
+    // 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 ${token}`);
+    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>");
-    console.error(`Add an email and password so you can sign in and recover it: ${api.baseUrl()}/hub`);
   },
 
   async me(f) {
@@ -722,6 +881,15 @@ const commands = {
     await serve();
   },
 
+  /**
+   * Ask the registry what the latest version is and write it down. Not in the help, because it is
+   * not for a person: `passalong` spawns it, detached, when the answer on file is a day old.
+   */
+  async ["refresh-update"]() {
+    const { refresh } = await import("../src/update.js");
+    await refresh();
+  },
+
   async help() {
     const src = readFileSync(fileURLToPath(import.meta.url), "utf8");
     const lines = src.split("\n").filter((l) => l.startsWith("//   passalong "));
@@ -738,5 +906,42 @@ const cmd = argv._.shift() || "help";
 // `passalong -v` can be read by a script comparing it against the registry.
 if (cmd === "-v" || cmd === "version" || (cmd === "help" && argv.version === true)) {
   console.log(JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version);
-} else if (cmd === "--help" || cmd === "-h" || !commands[cmd]) commands.help();
-else await commands[cmd](argv).catch((e) => die(e.message));
+} else if (cmd === "--help" || cmd === "-h" || cmd === "help") commands.help();
+// A command this build does not have used to print the help page and exit 0, which reads as "that
+// command exists and did nothing" — and the usual cause is an older passalong, where the command is
+// in the docs and not in the binary. So it fails, names what it does not know, and says the version
+// it is, which is the fact that explains it.
+else if (!commands[cmd])
+  die(
+    `unknown command "${cmd}" — run \`passalong help\` for the list. ` +
+      `This is passalong ${JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version}; ` +
+      "if you expected this command, `npm i -g passalong` for the newest one.",
+  );
+else {
+  await commands[cmd](argv).catch((e) => die(e.message));
+  // After the command, never before it: a version check is not worth a millisecond of somebody's
+  // first impression, and it must never be the reason a command felt slow. `mcp` is a server that
+  // does not return, and the hooks are read by an agent rather than a person — a line neither of
+  // them asked for is noise in a transcript.
+  if (!["mcp", "now", "refresh-update"].includes(cmd)) {
+    try {
+      const { cachedNotice } = await import("../src/update.js");
+      const current = JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+      const { notice, stale } = cachedNotice({ current });
+      if (notice) console.error(notice);
+      // The refresh is a process this one does not wait for: detached, output thrown away,
+      // unref'd so the exit is not held open by it. Measuring the alternative is what settled it —
+      // the registry took six to ten seconds to answer, so awaiting it meant every command paid
+      // that or the check silently never worked.
+      if (stale) {
+        const child = spawn(process.execPath, [fileURLToPath(import.meta.url), "refresh-update"], {
+          detached: true,
+          stdio: "ignore",
+        });
+        child.unref();
+      }
+    } catch {
+      // Nothing about being out of date is worth failing a command that already worked.
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Hand a finished implementation from one context to another, in a form an AI agent can act on.",
   "keywords": [
     "mcp",

package/skill/SKILL.md

@@ -9,6 +9,31 @@ You are turning this session into a **transfer guide**: executable context for a
 different place. The reader is an AI agent (with a developer watching) that has none of this
 session's history. Write for execution, not for permanence.
 
+## Before you write anything
+
+**Check what is already open, and whether a guide is wanted at all.** Run `passalong now` (or
+`take` with no id over MCP) to see what this worktree holds and what was handed to you.
+
+- **The session answers something you hold** — hand it in (`passalong hand_in <id> …`) instead.
+  Publishing a second guide about it leaves two records of one piece of work. Every hand-in carries
+  what you ran and what came back — the command and the lines that decided it, a test summary, a
+  link to the change, or a screenshot url. Copy each one out of the session as you go; at the end
+  you would be writing from memory, which is what evidence exists to replace. On a **task**, send
+  it as `checks`: one entry per Acceptance line, each with that line and the evidence for it. Its
+  author reads them line against line, and evidence filed under the check it answers is worth more
+  than the same output in one block. On a handoff or a bug, which have no Acceptance lines, send
+  `evidence` as one block.
+- **The work never left this repo** — committed and pushed on a branch the team can already see,
+  with a pull request to review — then it has crossed no boundary, and a transfer guide is one more
+  thing for somebody to read. What is worth publishing from a session like that is what is *still
+  open*: file it as a bug (`kind: bug`) or a task, not as a write-up of the fix.
+- **The ask is vague** — "update the passalong", "add this to passalong", "log this" — it may mean
+  hand in what you hold, add a follow-up to a guide, or publish something new. Ask which, in one
+  line. Publishing the wrong thing costs somebody a review, and the author a guide to delete.
+
+A transfer guide earns its place when the work has to cross a boundary: another repo, another
+machine, another agent session, or a teammate without your branch.
+
 ## Procedure
 
 1. **Pick the one thing to transfer.** If the user named it (`/passalong-capture <what>` or
@@ -37,7 +62,9 @@ session's history. Write for execution, not for permanence.
    **If what you are capturing is more context for an existing guide** — a missing detail, a step
    that needed explaining, what changed since, what you found doing it — add `--follows <that id>`.
    That publishes it as a follow-up: its own guide, listed under the original, and handed to
-   whoever opens the original, person or agent. A session that started from a passalong guide
+   whoever opens the original, person or agent. It travels the other way too — whoever opens the
+   follow-up gets the guide it came out of, and where that guide has got to — so write it as a
+   note on that work rather than as a standalone brief. A session that started from a passalong guide
    (`passalong start` or `pull` on an id, or an agent opened one) usually has context worth adding
    this way. Whether the guide worked is still its own answer: `passalong works <id>` or
    `passalong broken <id> <why>`.

package/src/api.js

@@ -63,7 +63,58 @@ const q = (params) => {
   return s ? `?${s}` : "";
 };
 
-/** Mint a fresh account and return its token. No email, no password: the token is the account. */
+/**
+ * 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.
+ */
 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 });
@@ -101,6 +152,26 @@ export const get = (id) => call(`/v1/guides/${id}`, { raw: true });
  */
 export const children = (id, { markdown = false } = {}) =>
   call(`/v1/guides/${encodeURIComponent(id)}/children${q({ markdown: markdown ? "1" : "" })}`);
+/**
+ * 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.
+ */
+export const parent = (id, { markdown = false } = {}) =>
+  call(`/v1/guides/${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.
+ */
+export const makeAdmin = (email) => call("/v1/admin/accounts", { method: "POST", body: { email } });
+export const listAdmins = () => call("/v1/admin/accounts");
+export const grantAdmin = (who) =>
+  call(`/v1/admin/accounts/${encodeURIComponent(who)}`, { method: "PUT", body: {} });
+export const revokeAdmin = (who) =>
+  call(`/v1/admin/accounts/${encodeURIComponent(who)}`, { method: "DELETE" });
+export const giveGift = (body) => call("/v1/admin/gifts", { method: "POST", body });
+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" });
@@ -123,6 +194,8 @@ export const releaseTask = (id) =>
 /** The four verbs every guide answers to. See docs/V2.md §11. */
 export const working = () => call("/v1/working");
 export const handedIn = () => call("/v1/handed_in");
+export const assign = (id, to) =>
+  call(`/v1/guides/${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 });

package/src/checks.js

@@ -0,0 +1,127 @@
+/**
+ * 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
+ * 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
+ * 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.
+ *
+ * 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
+ * keeps the prose gate that `evidenceProblem()` applies.
+ *
+ * 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.
+ */
+import { spawnSync } from "node:child_process";
+
+/** How long a check may run before it is killed. Long enough for a real suite, short of a lease. */
+export const CHECK_TIMEOUT_MS = 10 * 60 * 1000;
+
+/** The most captured output kept per check. Matches EVIDENCE_MAX in apps/api/src/claims.ts. */
+export const OUTPUT_MAX = 4000;
+
+/**
+ * The tail of what a command printed, because that is where a runner puts what went wrong. A head
+ * would hold the banner and the first hundred passing lines.
+ */
+function tail(out, max = OUTPUT_MAX) {
+  const s = String(out ?? "").replace(/\s+$/, "");
+  if (s.length <= max) return s;
+  return `… ${s.length - max} earlier characters cut …\n${s.slice(-max)}`;
+}
+
+/**
+ * One check, run if it names a command.
+ *
+ * Returns the check with three things added: `cmd` as it was run, `exit` — what the process
+ * returned — and `ok`, whether the check is met. They are two fields on purpose. SARIF keeps
+ * `exitCode` beside `executionSuccessful` "because not all programs exit with an exit code of 0 on
+ * success and non-0 on failure", and GitHub Actions keeps `outcome` beside `conclusion` so a
+ * policy that forgives a failure never overwrites what happened. Today `ok` is `exit === 0` and
+ * nothing else; keeping the pair means a check that needs a different rule later does not have to
+ * rewrite what was already recorded.
+ *
+ * A command that never ran — no such file, a shell that died, a timeout — is not a failing check.
+ * It is an unknown, and it is recorded as one so that "it did not run" cannot read as "it ran and
+ * found nothing wrong".
+ */
+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 };
+
+  const r = spawnSync(cmd, {
+    shell: true,
+    cwd,
+    timeout: timeoutMs,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+
+  const out = tail(`${r.stdout ?? ""}${r.stderr ?? ""}`);
+  // `status` is null when the child was killed rather than exited: a timeout, or a signal.
+  if (r.error || r.status === null) {
+    const why =
+      r.signal === "SIGTERM" && r.error?.code === "ETIMEDOUT"
+        ? `did not finish within ${Math.round(timeoutMs / 1000)}s`
+        : r.signal
+          ? `was killed by ${r.signal}`
+          : `could not run: ${r.error?.message ?? "unknown error"}`;
+    return {
+      check: check.check,
+      cmd,
+      exit: null,
+      ok: false,
+      ran: `$ ${cmd}\nthe command ${why}${out ? `\n${out}` : ""}`,
+    };
+  }
+
+  return {
+    check: check.check,
+    cmd,
+    exit: r.status,
+    ok: r.status === 0,
+    // The recorded evidence is what the process printed, not what the agent said about it. An
+    // empty run is written out rather than left blank: the exit code is what decided it, and a
+    // blank `ran` reads like evidence nobody supplied.
+    ran: out ? `$ ${cmd}\n${out}` : `$ ${cmd}\n(no output; exited ${r.status})`,
+  };
+}
+
+/**
+ * Every check, in the order the agent worked them, with the ones naming a command actually run.
+ *
+ * Stops at the first failure. A suite that fails at step two tells the agent what to fix, and
+ * running the remaining eight minutes of checks against a tree that is already wrong buys nothing.
+ */
+export function runChecks(checks = [], opts = {}) {
+  const done = [];
+  for (const c of checks) {
+    const r = runCheck(c, opts);
+    done.push(r);
+    if (r.ok === false) return { checks: done, failed: r, ran: done.filter((d) => d.cmd).length };
+  }
+  return { checks: done, failed: null, ran: done.filter((d) => d.cmd).length };
+}
+
+/** What the agent is told when a check it named did not hold. Its own output is the reason. */
+export function refusal(failed, { ran, total }) {
+  const what =
+    failed.exit === null
+      ? "did not run"
+      : `exited ${failed.exit}${failed.exit === 0 ? "" : ", so the check does not hold"}`;
+  return (
+    `not handed in: \`${failed.cmd}\` ${what}.\n\n` +
+    `${failed.ran}\n\n` +
+    `This was check ${ran} of ${total}, "${failed.check}". Fix what it found and hand in again. ` +
+    "Nothing was recorded, and you still hold this."
+  );
+}

package/src/guide.js

@@ -37,8 +37,18 @@ export const SETTABLE = ["draft", "published", "consumed"];
  *   bug       something broken there — do NOT follow anything; fix it
  *   task      work nobody has done yet — do what Goal asks, done when Acceptance holds
  *
- * A guide with no `kind` is a transfer guide: every guide written before this existed is one,
- * and defaulting the other way would turn them all into bug reports.
+ * A guide with no `kind` is a transfer guide: every guide written before this existed is one, and
+ * defaulting the other way would turn them all into bug reports.
+ *
+ * That default is applied once, on read, and written back — `parseFrontmatter` seeds it the way it
+ * seeds `tags`, so nothing downstream has to decide what an empty kind means. It was decided in six
+ * places, each with its own `|| "transfer"`, and one of them said `|| "task"`. A guide either says
+ * what it is or is read as a transfer guide and then says so; there is no third state for anything
+ * to disagree about.
+ *
+ * Which is also why publishing an untyped guide is not refused. Refusing it leaves the document
+ * 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.
  */
 export const KINDS = ["transfer", "bug", "task"];
 
@@ -245,6 +255,10 @@ export function parseFrontmatter(text) {
   // Only the lists every guide has. `blocked_by` is a task's, and defaulting it would write an
   // empty one into every guide anybody re-shares.
   for (const k of ["stack_assumptions", "tags"]) if (meta[k] === undefined) meta[k] = [];
+  // What it is, said rather than inferred. An unknown spelling is left alone for `validate()` to
+  // refuse by name: quietly turning `kind: buggy` into a transfer guide is the same guess this is
+  // here to remove.
+  if (!String(meta.kind ?? "").trim()) meta.kind = "transfer";
   // Both ends of this module: what it reads and what it writes are in one style, so a guide
   // written before there was a rule comes back normalised and goes out normalised.
   meta.tags = tagList(meta.tags);
@@ -320,7 +334,11 @@ export function sections(body) {
     const h = /^##\s+(.+?)\s*$/.exec(line);
     if (h) {
       current = h[1];
-      out[current] = "";
+      // A heading written twice adds to its section rather than replacing it. Resetting here lost
+      // the first block outright, so a guide with two `## Verification` headings was validated
+      // against only the second — and `splitSections()` in apps/api/src/guide.ts, which the web
+      // view reads, kept both. The corpus in fixtures/guides is where the two stopped agreeing.
+      if (!(current in out)) out[current] = "";
       continue;
     }
     if (current) out[current] += `${line}\n`;
@@ -365,8 +383,12 @@ export function validate({ meta, body }) {
   if (meta.status && !STATUSES.includes(meta.status)) {
     errors.push(`status must be one of ${STATUSES.join(", ")}`);
   }
-  const kind = meta.kind || "transfer";
-  if (!KINDS.includes(kind)) errors.push(`kind must be one of ${KINDS.join(", ")}`);
+  // Absent is refused here, and this is the one place it can be. Anything read from a document has
+  // 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;
+  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);
   for (const s of REQUIRED[kind] || REQUIRED.transfer) {
     if (!have[s]) errors.push(`missing "## ${s}" section`);