passalong 0.5.0 → 0.8.0

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`);

package/src/hooks.js

@@ -25,14 +25,17 @@ const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
 export function nowText({ held, waiting = {} }) {
   if (held) {
     const lines = [
-      `Passalong: You hold ${held.id} (${held.kind || "task"}): ${held.title || held.id}.`,
+      // `kind` is required on what /v1/working sends. The `|| "task"` that used to be here was
+      // both dead and wrong — absent has meant transfer since kinds existed, never task.
+      `Passalong: You hold ${held.id} (${held.kind}): ${held.title || held.id}.`,
     ];
     if (held.note) lines.push(`Last note: "${held.note}".`);
     if (held.state === "stalled")
       lines.push("It is marked stalled: nobody has heard from its agent in 30 minutes.");
     lines.push(
       `To carry on, call take ${held.id} (it resumes what you hold), then progress at each ` +
-        "milestone. When it is done, hand_in; if it is not yours or you are stuck, pass with the reason.",
+        "milestone. When it is done, hand_in with evidence — what you ran and what came back — " +
+        "so keep it as you go; if it is not yours or you are stuck, pass with the reason.",
     );
     return lines.join("\n");
   }
@@ -57,9 +60,9 @@ export function stopVerdict({ held, input = {} }) {
     decision: "block",
     reason:
       `You still hold ${held.id}: ${held.title || held.id}. Before ending, do one of: ` +
-      `hand_in ${held.id} if it is done; pass ${held.id} with the reason if it is not yours or ` +
-      `you are stuck; or, if the user is stopping mid-way, progress ${held.id} with a note ` +
-      "saying what is left — then end.",
+      `hand_in ${held.id} with your evidence if it is done; pass ${held.id} with the reason if ` +
+      `it is not yours or you are stuck; or, if the user is stopping mid-way, progress ${held.id} ` +
+      "with a note saying what is left — then end.",
   };
 }
 
@@ -80,3 +83,47 @@ export function withHooks(settings = {}) {
   }
   return out;
 }
+
+// ---- the status line -------------------------------------------------------------------------------
+//
+// Claude Code draws a status line from a command's output, under the prompt, all session long. It is
+// the one place a person sees what their agent holds without asking. The command is
+// `passalong now --statusline`, which prints from a local cache and refreshes it in the background:
+// Claude Code cancels a status line that is still running when the next update arrives, so a
+// network call in the foreground would leave the line blank.
+
+/** The status line command, as written into settings. */
+export const STATUS_LINE = "passalong now --statusline";
+
+/** Keep a one-line note to what fits beside everything else in a terminal footer. */
+const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+
+/**
+ * One line: what this worktree's agent holds, then what needs you and what is ready here.
+ * `needs` counts everything waiting on the person: work handed in for review, agents stuck on
+ * them, and guides handed to them.
+ */
+export function statusText({ held, needs = 0, ready = 0 }) {
+  const parts = [];
+  if (held) {
+    const said = held.note ? ` "${clip(held.note, 32)}"` : "";
+    parts.push(`▸ ${held.id}${held.state === "stalled" ? " (stalled)" : ""}${said}`);
+  } else parts.push("passalong");
+  if (needs) parts.push(`${needs} need${needs === 1 ? "s" : ""} you`);
+  if (ready) parts.push(`${ready} ready`);
+  if (parts.length === 1 && !held) parts.push("clear");
+  return parts.join(" · ");
+}
+
+/**
+ * Settings with the status line added, when there is none. A status line someone already has is
+ * theirs — a script with their git branch or their context meter — and setup never replaces it.
+ * `refreshInterval` keeps it current while the session sits idle.
+ */
+export function withStatusLine(settings = {}) {
+  if (settings.statusLine) return settings;
+  return {
+    ...structuredClone(settings),
+    statusLine: { type: "command", command: STATUS_LINE, refreshInterval: 30 },
+  };
+}