passalong 0.12.0 → 0.13.0

package/README.md

@@ -33,7 +33,7 @@ passalong activity [--all]    what happened while you were away; clears unless -
 passalong list [query]        your guides and your teams', local and synced
 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 works <id> <shot>   you tried it and it holds up, with a screenshot of it working
 passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 passalong archive <id>        off your board and out of the free tier's count (was `done`)
 passalong promote <id>        deprecated: mark promoted
@@ -67,9 +67,11 @@ passalong inbox                         # on Ada's side: what was handed to you
 passalong activity                      # back on your side: it landed, and who pulled it
 ```
 
-A receiver who tries the work reports back with `passalong works <id>` or `passalong broken <id> <why>`.
-That is separate from `done`, which means *implemented*: a verdict means it actually runs, a failing
-one has to say why, and the author sees it on their board and in their inbox.
+A receiver who tries the work reports back with `passalong works <id> <screenshot.png>` or
+`passalong broken <id> <why>`. That is separate from `done`, which means *implemented*: a verdict
+means it actually runs. A passing one has to show it — at least one screenshot of it working, kept
+until 5 days after the guide is closed — a failing one has to say why, and the author sees it on
+their board and in their inbox.
 
 Sign in at [the hub](https://passalong.dev/hub) with an email and password, and mint
 an API token there for the CLI and MCP servers — named, revocable, and shown once. Your password

package/bin/passalong

@@ -33,7 +33,7 @@
 //                                 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 works <id> <shot.png...>  you tried it and it holds up — with a screenshot of it working
 //   passalong broken <id> <why>   you tried it and it does not — the author is told, with your reason
 //   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
@@ -603,9 +603,12 @@ const commands = {
   },
 
   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));
-    console.error(`${r.id} verified — the author has been told`);
+    const id = f._[0] || die("usage: passalong works <id> <screenshot.png...> [what you checked]");
+    const { images, note } = passalong.proofArgs(f._.slice(1));
+    const r = await passalong.verdict(id, true, note, { images }).catch((e) => die(e.message));
+    console.error(
+      `${r.id} verified with ${images.length || "your"} screenshot${images.length === 1 ? "" : "s"} — the author has been told`,
+    );
   },
 
   async broken(f) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "passalong",
-  "version": "0.12.0",
+  "version": "0.13.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

@@ -66,7 +66,7 @@ machine, another agent session, or a teammate without your branch.
    follow-up gets the guide it came out of, and where that guide has got to — so write it as a
    note on that work rather than as a standalone brief. 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
+   this way. Whether the guide worked is still its own answer: `passalong works <id> <screenshot>` or
    `passalong broken <id> <why>`.
 6. **Report** the id (and link if synced) and one line on how to use it on the other side:
    `passalong start <id>` in the target repo, or "start passalong <id>" to an agent with the

package/src/checks.js

@@ -22,6 +22,26 @@
  * exit code is the whole verdict here, which is also how a CI step decides.
  */
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+/**
+ * The shell a check runs in: bash with `pipefail` wherever there is one.
+ *
+ * A plain shell reports a pipeline's last command. `npx jest 2>&1 | grep Tests:` then passes when
+ * jest fails, because grep found the summary line, and `git log main..HEAD | head -60` passes when
+ * git dies with "fatal: ambiguous argument", because head exited 0 — which is exactly how a hand-in
+ * came back marked "ran, it worked here" with the fatal error sitting in its own output. With
+ * pipefail, any failing step fails the check.
+ */
+const BASH =
+  process.platform === "win32" ? "" : ["/bin/bash", "/usr/bin/bash"].find(existsSync) || "";
+
+/**
+ * 141 is 128 + SIGPIPE: the command was still writing when a later step stopped reading, which is
+ * what `| head` does on purpose. Under pipefail that is the pipeline's status, and it is not a
+ * failure — git printed what head wanted and was told to stop.
+ */
+const SIGPIPE = 141;
 
 /** 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;
@@ -58,13 +78,15 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
   const cmd = String(check?.cmd ?? "").trim();
   if (!cmd) return { check: check.check, ran: check.ran };
 
-  const r = spawnSync(cmd, {
-    shell: true,
+  const opts = {
     cwd,
     timeout: timeoutMs,
     encoding: "utf8",
     maxBuffer: 64 * 1024 * 1024,
-  });
+  };
+  const r = BASH
+    ? spawnSync(BASH, ["-o", "pipefail", "-c", cmd], opts)
+    : spawnSync(cmd, { ...opts, shell: true });
 
   const out = tail(`${r.stdout ?? ""}${r.stderr ?? ""}`);
   // `status` is null when the child was killed rather than exited: a timeout, or a signal.
@@ -84,15 +106,20 @@ export function runCheck(check, { cwd = process.cwd(), timeoutMs = CHECK_TIMEOUT
     };
   }
 
+  const cutShort = Boolean(BASH) && r.status === SIGPIPE;
   return {
     check: check.check,
     cmd,
     exit: r.status,
-    ok: r.status === 0,
+    ok: r.status === 0 || cutShort,
     // 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})`,
+    ran:
+      (out ? `$ ${cmd}\n${out}` : `$ ${cmd}\n(no output; exited ${r.status})`) +
+      (cutShort
+        ? "\n(exit 141: a later step stopped reading early, as `head` does; not a failure)"
+        : ""),
   };
 }
 

package/src/guide.js

@@ -290,6 +290,37 @@ export function parseFrontmatter(text) {
   return meta;
 }
 
+/**
+ * Frontmatter fields holding more than this format can: a nested map, a block scalar (`|`), a
+ * sequence under a field that is not a list. `parseFrontmatter` keeps only the key's own line, so
+ * each of these would come back as `""` with its content gone — a design.md's `colors:` block did
+ * exactly that, and a publish would have stored the document with every token wiped. The format
+ * does not grow to hold them (strings and string lists only); the publish refuses them by name
+ * instead, so nothing is lost without its author being told. Mirrors `unheldFields` in
+ * apps/api/src/guide.ts, which is the refusal every client meets.
+ */
+export function unheldFields(markdown) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(markdown);
+  if (!m) return [];
+  const out = new Set();
+  let key = null;
+  let listKey = null;
+  for (const line of m[1].split(/\r?\n/)) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    if (listKey && /^\s*-\s*/.test(line)) continue;
+    const kv = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
+    if (kv) {
+      key = kv[1];
+      listKey = kv[2].trim() === "" && LIST_FIELDS.has(key) ? key : null;
+      continue;
+    }
+    // Anything else is a line the parser skips: an indented child, or an item under a field
+    // that is not a list. It belongs to the key above it, and that is the key to name.
+    out.add(key ?? line.trim());
+  }
+  return [...out];
+}
+
 function quote(v) {
   const s = String(v ?? "");
   // Quote anything YAML would misread: colons, leading symbols, or empty.

package/src/passalong.js

@@ -16,6 +16,7 @@ import {
   serialize,
   stamp,
   stripPlaceholders,
+  unheldFields,
   validate,
 } from "./guide.js";
 import * as store from "./store.js";
@@ -60,7 +61,13 @@ export async function share(markdown, { cwd = process.cwd(), to, follows } = {})
   if (follows) guide.meta.parent = await resolveId(String(follows).trim());
   if (guide.meta.to && !guide.meta.team)
     throw new PassalongError("`to:` needs a team — address a handoff as team/handle");
-  const errors = validate(guide);
+  const errors = [
+    ...unheldFields(markdown).map(
+      (k) =>
+        `frontmatter "${k}" holds more than a string or a list of strings, and it would be dropped — move it into the body (a fenced yaml block keeps it as written)`,
+    ),
+    ...validate(guide),
+  ];
   if (errors.length)
     throw new PassalongError(`guide is not ready to share:\n  - ${errors.join("\n  - ")}`);
   // A task stays a draft when it is shared. Draft is the column a task waits in until a person
@@ -908,13 +915,40 @@ export async function activity({ all = false, limit = 50 } = {}) {
  * "Correction: …" instead, because measurements, commands and commit ids do not fit in a tweet.
  * The first line is the summary a row shows; the whole thing is what the guide shows.
  */
-export async function verdict(id, ok, note = "") {
+export async function verdict(id, ok, note = "", { images = [] } = {}) {
   if (!api.loggedIn()) throw new PassalongError("verdicts need sync — run `passalong login` first");
   const said = note.trim();
   if (!ok && !said)
     throw new PassalongError("say what went wrong: passalong broken <id> <what happened>");
+  // "It works" is shown, not said: the server refuses one with no screenshot of it working, so
+  // the refusal is said here before anything is uploaded, in the words of the command that fixes it.
+  if (ok && !images.length && !/\/v1\/shots\/[a-z0-9]{6,16}/.test(said))
+    throw new PassalongError(
+      "show it working: passalong works <id> <screenshot.png> [what you checked]",
+    );
+  const guide = await resolveId(id);
+  const shots = [];
+  for (const file of images) shots.push((await attach(file)).markdown);
   const line = said.split("\n")[0].slice(0, 280);
-  return api.verdict(await resolveId(id), ok, line, said.length > line.length ? said : "");
+  const detail = [said.length > line.length || shots.length ? said : "", ...shots]
+    .filter(Boolean)
+    .join("\n");
+  return api.verdict(guide, ok, line, detail);
+}
+
+/**
+ * The words after `passalong works <id>`, split into the screenshots and the note: an argument is a
+ * screenshot when it names an image file that exists, and everything else is what was checked.
+ */
+export function proofArgs(args) {
+  const images = [];
+  const words = [];
+  for (const a of args) {
+    const ext = a.slice(a.lastIndexOf(".")).toLowerCase();
+    if (SHOT_TYPES[ext] && existsSync(a)) images.push(a);
+    else words.push(a);
+  }
+  return { images, note: words.join(" ") };
 }
 
 /**