passalong 0.5.0 → 0.6.0

package/bin/passalong

@@ -41,7 +41,8 @@
 //   passalong now                 what this worktree holds and what is waiting (the hooks call --hook)
 //   passalong mcp                 run the MCP server over stdio
 //   passalong version             print the installed version (also -v, --version)
-import { execFileSync, spawnSync } from "node:child_process";
+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 { dirname, join, resolve } from "node:path";
@@ -130,6 +131,53 @@ const MONTHS = "January February March April May June July August September Octo
 /** "September 2026" from an ISO timestamp, without pulling in a date library for one heading. */
 const monthOf = (iso) => `${MONTHS[Number(iso.slice(5, 7)) - 1]} ${iso.slice(0, 4)}`;
 
+// ---- the status line cache --------------------------------------------------------------------------
+
+/** One small file per working directory, so two sessions in two repos each see their own. */
+const statusPath = (cwd) =>
+  join(store.HOME, "statusline", `${createHash("sha1").update(cwd).digest("hex").slice(0, 16)}.json`);
+
+function writeStatus(cwd, text) {
+  const p = statusPath(cwd);
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify({ at: Date.now(), text }));
+}
+
+/** How old a cached line may be before a refresh is started behind it. */
+const STATUS_TTL_MS = 30_000;
+
+/**
+ * Print the cached line for this directory at once, and when it is stale start a detached refresh
+ * that writes the next one. The first run in a directory prints a placeholder; the refresh lands
+ * within a second or two, and the next update shows it. Offline or signed out, it says nothing.
+ */
+async function statusLine() {
+  let input = {};
+  if (!process.stdin.isTTY) {
+    let raw = "";
+    for await (const chunk of process.stdin) raw += chunk;
+    try {
+      input = JSON.parse(raw || "{}");
+    } catch {}
+  }
+  if (!api.loggedIn()) return;
+  const cwd = input.workspace?.current_dir || input.cwd || process.cwd();
+  let cached = null;
+  try {
+    cached = JSON.parse(readFileSync(statusPath(cwd), "utf8"));
+  } catch {}
+  process.stdout.write(cached?.text ?? "passalong");
+  if (!cached || Date.now() - cached.at > STATUS_TTL_MS) {
+    // Marked fresh before the refresh starts, so a burst of updates starts one refresh, not ten.
+    writeStatus(cwd, cached?.text ?? "passalong");
+    spawn(process.execPath, [fileURLToPath(import.meta.url), "now", "--statusline-refresh", cwd], {
+      detached: true,
+      stdio: "ignore",
+      env: process.env,
+    }).unref();
+  }
+}
+
 const commands = {
   async share(f) {
     let path = f._[0];
@@ -598,14 +646,18 @@ const commands = {
     // over them, and a no-op when they are already there.
     const settingsPath = join(homedir(), ".claude", "settings.json");
     try {
-      const { withHooks } = await import("../src/hooks.js");
+      const { withHooks, withStatusLine } = await import("../src/hooks.js");
       const before = existsSync(settingsPath) ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};
-      const after = withHooks(before);
+      const after = withStatusLine(withHooks(before));
+      if (before.statusLine && before.statusLine.command !== "passalong now --statusline")
+        console.error(
+          "you already have a status line, so it was left alone. To show Passalong in it, call `passalong now --statusline` from your script",
+        );
       if (JSON.stringify(after) === JSON.stringify(before)) console.error("Claude Code hooks already installed");
       else {
         mkdirSync(dirname(settingsPath), { recursive: true });
         writeFileSync(settingsPath, `${JSON.stringify(after, null, 2)}\n`);
-        console.error(`installed Claude Code hooks (session start, stop) → ${settingsPath}`);
+        console.error(`installed Claude Code hooks (session start, stop) and status line → ${settingsPath}`);
       }
     } catch (err) {
       console.error(`could not install Claude Code hooks (${err.message}); ${settingsPath} left as it was`);
@@ -621,7 +673,18 @@ const commands = {
    * nothing at all when anything goes wrong — a hook must never get in the way of a session.
    */
   async now(f) {
-    const { nowText, stopVerdict } = await import("../src/hooks.js");
+    const { nowText, statusText, stopVerdict } = await import("../src/hooks.js");
+    // The status line: printed from a cache, refreshed behind it. Claude Code cancels a status
+    // line still running when the next update comes, so this never waits on the network.
+    if (f.statusline) return statusLine(f);
+    if (f["statusline-refresh"]) {
+      const cwd = typeof f["statusline-refresh"] === "string" ? f["statusline-refresh"] : process.cwd();
+      try {
+        const r = await passalong.now({ cwd });
+        writeStatus(cwd, statusText({ held: r.held, needs: r.needs, ready: r.waiting.ready }));
+      } catch {}
+      return;
+    }
     if (!f.hook) {
       const r = await passalong.now();
       console.log(nowText(r) || "Nothing held here, and nothing waiting.");

package/package.json

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

package/src/api.js

@@ -122,6 +122,7 @@ export const releaseTask = (id) =>
   call(`/v1/tasks/${encodeURIComponent(id)}/release`, { method: "POST", body: {} });
 /** 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 take = (body) => call("/v1/take", { method: "POST", body });
 export const progress = (id, body) =>
   call(`/v1/guides/${encodeURIComponent(id)}/progress`, { method: "PUT", body });

package/src/hooks.js

@@ -80,3 +80,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 },
+  };
+}

package/src/passalong.js

@@ -376,18 +376,31 @@ export async function now({ cwd = process.cwd() } = {}) {
   // Read, never minted: the hooks run in every repo a session opens, and a worktree that has never
   // taken anything has no agent — and should not be given a .passalong/ folder for asking.
   const who = knownAgent(cwd);
-  const { working } = await api.working();
-  const held = (who.agent && working.find((w) => w.agent === who.agent && w.by?.you)) || null;
-  const waiting = { ready: 0, inbox: 0 };
-  if (!held) {
-    const [t, i] = await Promise.allSettled([api.tasks(), api.inbox()]);
-    if (t.status === "fulfilled")
-      waiting.ready = t.value.tasks.filter(
-        (x) => x.state === "ready" && x.target === who.repo,
-      ).length;
-    if (i.status === "fulfilled") waiting.inbox = i.value.guides.length;
-  }
-  return { held, waiting, agent: who.agent };
+  const [w, t, i, h] = await Promise.allSettled([
+    api.working(),
+    api.tasks(),
+    api.inbox(),
+    api.handedIn(),
+  ]);
+  if (w.status === "rejected") throw w.reason;
+  const held =
+    (who.agent && w.value.working.find((x) => x.agent === who.agent && x.by?.you)) || null;
+  const tasks = t.status === "fulfilled" ? t.value.tasks : [];
+  const waiting = {
+    ready: tasks.filter((x) => x.state === "ready" && x.target === who.repo).length,
+    inbox: i.status === "fulfilled" ? i.value.guides.length : 0,
+  };
+  // Everything waiting on the person, the way the hub's Needs you counts it: their tasks handed in
+  // or stuck, handoffs of theirs handed in, and guides handed to them.
+  const review = tasks.filter(
+    (x) =>
+      x.mine &&
+      (x.state === "review" ||
+        x.state === "stalled" ||
+        (x.state === "claimed" && /^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 };
 }
 
 /**