@gobing-ai/spur 0.3.98 → 0.4.0

package/plugins/sp/scripts/persist-out-check.ts

@@ -0,0 +1,185 @@
+#!/usr/bin/env bun
+/**
+ * persist-out-check — WT-4 pre-removal assertion for E71 persist-out (task 1067 R1).
+ *
+ * Before `git worktree remove`, verify the worktree's durable evidence would not be
+ * abandoned: every file the worktree owns under `.spur/run/` (`<wbs>-*` per forwarded
+ * task file, `<runId>-*` per forwarded run id) and the whole `.spur/memory/evidence/`
+ * tree must exist in the invoking tree with identical bytes. Missing files BLOCK the
+ * removal (persist-out was skipped or stale); divergent files block too (persist-out
+ * never overwrites — reconcile by hand per execution-batch.md). No new public CLI verb:
+ * this is a driver-side assertion step, not a corpus tool.
+ *
+ * ponytail: file-level comparison only — DB run rows and nested-run deep walks stay
+ * persist-out's job (`inline-run-setup --persist-out`); this checks the planes E71
+ * names as files. Listing caps (64/prefix, 256 evidence) refuse runaways by name.
+ *
+ * Node-builtin imports only; pure helpers are exported for tests. Exit 0 ok, 1
+ * blocked/divergent, 2 usage error. Normal output is the finding lines themselves.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, relative } from 'node:path';
+
+const EVIDENCE_DIR = join('.spur', 'memory', 'evidence');
+const RUN_DIR = join('.spur', 'run');
+const NAMED_CAP = 32;
+const PREFIX_CAP = 64;
+const EVIDENCE_CAP = 256;
+
+/** Task files own their `<wbs>-*` evidence: leading digits before `_` in the basename. */
+export function wbsOfTaskFile(path: string): string | null {
+    const m = /^(\d+)_/.exec(basename(path));
+    return m?.[1] ?? null;
+}
+
+function listFilesUnder(root: string, rel: string, cap: number): string[] | null {
+    const dir = join(root, rel);
+    if (!existsSync(dir)) return [];
+    const out: string[] = [];
+    const walk = (cur: string): boolean => {
+        for (const entry of readdirSync(cur, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const p = join(cur, entry.name);
+            if (entry.isDirectory()) {
+                if (!walk(p)) return false;
+            } else {
+                out.push(relative(root, p));
+                if (out.length > cap) return false;
+            }
+        }
+        return true;
+    };
+    return walk(dir) ? out : null;
+}
+
+/**
+ * Evidence files the worktree owns: `.spur/memory/evidence/**` plus `.spur/run/<prefix>-*`
+ * direct children per task-file WBS / run id. Returns null on a cap overrun or a listing
+ * failure (not a directory, permission denied) — the caller refuses either way.
+ */
+export function listObligations(wtRoot: string, wbsList: string[], runIds: string[]): string[] | null {
+    const evidence = listFilesUnder(wtRoot, EVIDENCE_DIR, EVIDENCE_CAP);
+    if (evidence === null) return null;
+    const out = [...evidence];
+    const prefixes = [...wbsList, ...runIds];
+    for (const prefix of prefixes) {
+        const dir = join(wtRoot, RUN_DIR);
+        if (!existsSync(dir)) continue;
+        let entries: string[];
+        try {
+            entries = readdirSync(dir).sort();
+        } catch {
+            return null;
+        }
+        const owned = entries.filter((n) => n.startsWith(`${prefix}-`));
+        if (owned.length > PREFIX_CAP) return null;
+        out.push(...owned.map((n) => join(RUN_DIR, n)));
+    }
+    return [...new Set(out)].sort();
+}
+
+/** Classify obligations against the invoking tree: missing, divergent (byte-differs), or ok. */
+export function compareTrees(
+    wtRoot: string,
+    invokeRoot: string,
+    files: string[],
+): { missing: string[]; divergent: string[]; ok: number } {
+    const missing: string[] = [];
+    const divergent: string[] = [];
+    let ok = 0;
+    for (const rel of files) {
+        const wtPath = join(wtRoot, rel);
+        const invPath = join(invokeRoot, rel);
+        if (!existsSync(invPath)) {
+            missing.push(rel);
+            continue;
+        }
+        try {
+            const same = readFileSync(wtPath).equals(readFileSync(invPath));
+            if (same) ok++;
+            else divergent.push(rel);
+        } catch {
+            divergent.push(rel);
+        }
+    }
+    return { missing, divergent, ok };
+}
+
+export function persistOutCheckUsage(): string {
+    return 'usage: persist-out-check --from <worktree> [--task-file <path>]… [--run-id <id>]… [--root <invoke-tree>]';
+}
+
+/**
+ * The invoking tree is the MAIN repo root — never default to cwd: WT-4 runs from the
+ * worktree, and comparing the worktree against itself is a vacuous pass (caught live in
+ * task 1067 R4). `--git-common-dir` resolves to the shared `.git`, whose parent is the
+ * main tree; inside the main tree itself this falls back to cwd, which is correct there.
+ */
+export function defaultInvokeRoot(cwd: string): string {
+    try {
+        const run = spawnSync('git', ['-C', cwd, 'rev-parse', '--git-common-dir'], { encoding: 'utf8' });
+        const common = run.stdout.trim();
+        if (run.status === 0 && common) return dirname(isAbsolute(common) ? common : join(cwd, common));
+    } catch {
+        // git unavailable — fall through to cwd
+    }
+    return cwd;
+}
+
+export function main(argv: string[], invokeRoot = defaultInvokeRoot(process.cwd())): number {
+    let wtRoot = '';
+    const wbsList: string[] = [];
+    const runIds: string[] = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--spur-bin') {
+            i++;
+        } else if (arg === '--from') {
+            wtRoot = argv[++i] ?? '';
+        } else if (arg === '--root') {
+            invokeRoot = argv[++i] ?? invokeRoot;
+        } else if (arg === '--task-file') {
+            const wbs = wbsOfTaskFile(argv[++i] ?? '');
+            if (wbs) wbsList.push(wbs);
+        } else if (arg === '--run-id') {
+            const id = argv[++i] ?? '';
+            if (id) runIds.push(id);
+        } else {
+            process.stderr.write(`${persistOutCheckUsage()}\n`);
+            return 2;
+        }
+    }
+    if (!wtRoot || !existsSync(wtRoot) || !statSync(wtRoot).isDirectory()) {
+        process.stderr.write(
+            `${persistOutCheckUsage()}\npersist-out-check: --from must be an existing worktree directory\n`,
+        );
+        return 2;
+    }
+    const files = listObligations(wtRoot, wbsList, runIds);
+    if (files === null) {
+        process.stderr.write(
+            `persist-out-check: BLOCKED — worktree evidence listing failed or exceeded caps (64/prefix, ${EVIDENCE_CAP} evidence files) — inspect by hand\n`,
+        );
+        return 1;
+    }
+    const { missing, divergent, ok } = compareTrees(wtRoot, invokeRoot, files);
+    const findings = [
+        ...missing.map((f) => `MISSING ${f}`),
+        ...divergent.map((f) => `DIVERGENT ${f} — reconcile by hand (persist-out never overwrites)`),
+    ];
+    for (const line of findings.slice(0, NAMED_CAP)) process.stdout.write(`${line}\n`);
+    if (findings.length > NAMED_CAP) process.stdout.write(`… +${findings.length - NAMED_CAP} more\n`);
+    if (findings.length === 0) {
+        process.stdout.write(`persist-out-check: ok — ${ok} evidence file(s) persisted, nothing abandoned\n`);
+        return 0;
+    }
+    process.stderr.write(
+        `persist-out-check: BLOCKED ${missing.length} missing, ${divergent.length} divergent — run inline-run-setup --persist-out --from <worktree> before worktree removal\n`,
+    );
+    return 1;
+}
+
+if (import.meta.main) {
+    process.exit(main(process.argv.slice(2)));
+}

package/plugins/sp/scripts/residual-scan.mjs

@@ -17,7 +17,8 @@ import { join } from "node:path";
 import { createHash } from "node:crypto";
 var MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
 var PRIORITY_PATTERN = /^P[1-4]/;
-var NONE_FINDING = /^(none( found)?|no (findings?|issues?)( found)?|—)\s*(\(.*\))?\.?$/i;
+var RANGE_PRIORITY = /^P[1-4]\s*[\u2013\u2014-]\s*P?[1-4]/;
+var NONE_FINDING = /^(none( found)?|no (findings?|issues?)( found)?|\u2014)\s*(\(.*\))?\.?$/i;
 var DISPOSITION_HEADER = /^(Disposition|Action|Status|Resolution|Fixed)$/i;
 var RESOLVED_DISPOSITION = /^(FIXED|RESOLVED|DONE)\b/i;
 var DEFERRED_DISPOSITION = /^DEFER(RED)?\b/i;
@@ -74,7 +75,7 @@ function parseReviewFindings(taskContent) {
       const priority = (cells[priorityCol] ?? "").trim();
       const finding = (cells[findingCol] ?? "").trim();
       const disposition = dispositionCol === -1 ? "" : (cells[dispositionCol] ?? "").trim();
-      if (PRIORITY_PATTERN.test(priority) && !NONE_FINDING.test(finding) && finding.length > 0 && !RESOLVED_DISPOSITION.test(disposition)) {
+      if (PRIORITY_PATTERN.test(priority) && !RANGE_PRIORITY.test(priority) && !NONE_FINDING.test(finding) && finding.length > 0 && !RESOLVED_DISPOSITION.test(disposition)) {
         const location = locationOf(cells[locationCol] ?? "", finding);
         out.push(DEFERRED_DISPOSITION.test(disposition) ? { priority, location, text: finding, deferral: disposition } : { priority, location, text: finding });
       }
@@ -84,7 +85,7 @@ function parseReviewFindings(taskContent) {
   return out;
 }
 function splitRow(line) {
-  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split(/(?<!\\)\|/).map((c) => c.trim());
 }
 function parseDiffMarkers(addedLines) {
   return addedLines.filter((l) => !EXCLUDED_PATHS.some((p) => l.file.startsWith(p))).filter((l) => !l.text.includes(ALLOW_PRAGMA)).filter((l) => MARKER_PATTERN.test(l.text)).map((l) => ({ location: `${l.file}:${l.line}`, text: l.text.trim() }));
@@ -212,7 +213,8 @@ function renderReport(wbs, items, attemptCount) {
 function recordedVerdictPath(runDir, wbs, fs) {
   const evidence = join(runDir, "..", "memory", "evidence");
   const durable = join(evidence, `${wbs}-verdict.json`);
-  for (const path of [join(runDir, ".."), join(evidence, ".."), evidence, durable]) {
+  const run = join(runDir, `${wbs}-verdict.json`);
+  for (const path of [join(runDir, ".."), join(evidence, ".."), evidence, durable, run]) {
     try {
       if (fs.lstatSync(path).isSymbolicLink())
         throw new Error(`residual-scan: symlink evidence path: ${path}`);
@@ -221,7 +223,44 @@ function recordedVerdictPath(runDir, wbs, fs) {
         throw error;
     }
   }
-  return fs.existsSync(durable) ? durable : join(runDir, `${wbs}-verdict.json`);
+  if (!fs.existsSync(durable))
+    return run;
+  if (!fs.existsSync(run))
+    return durable;
+  const newer = (a, b) => mtimeOf(fs, b) > mtimeOf(fs, a) ? b : a;
+  return newer(run, durable);
+}
+function mtimeOf(fs, path) {
+  try {
+    return fs.statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+function verdictDisagreementNote(runDir, wbs, fs) {
+  const run = join(runDir, `${wbs}-verdict.json`);
+  const durable = join(runDir, "..", "memory", "evidence", `${wbs}-verdict.json`);
+  if (!fs.existsSync(run) || !fs.existsSync(durable))
+    return null;
+  const bytes = (path) => {
+    try {
+      return fs.statSync(path).isFile() ? fs.readFileSync(path, "utf8") : null;
+    } catch {
+      return null;
+    }
+  };
+  const runBytes = bytes(run);
+  if (runBytes === null || runBytes === bytes(durable))
+    return null;
+  const value = (path) => {
+    try {
+      return JSON.parse(bytes(path) ?? "{}").verdict ?? "?";
+    } catch {
+      return "?";
+    }
+  };
+  const winner = mtimeOf(fs, durable) > mtimeOf(fs, run) ? "durable" : "run";
+  return `residual-fold: ${wbs} verdict copies disagree — run=${run} (${value(run)}) durable=${durable} (${value(durable)})` + ` → chose ${winner} (newer mtime)`;
 }
 
 // plugins/sp/lib/spur-bin.ts
@@ -337,9 +376,7 @@ function loadTask(env, spurBinFlag, wbs, root) {
   const featureId = [parsed.feature_id, parsed.frontmatter?.feature_id].find((v) => typeof v === "string") ?? "";
   return { content: typeof parsed.content === "string" ? parsed.content : "", featureId };
 }
-function loadVerdict(runDir, wbs) {
-  return JSON.parse(fs.readFileSync(recordedVerdictPath(runDir, wbs, fs), "utf8"));
-}
+var loadVerdict = (runDir, wbs) => JSON.parse(fs.readFileSync(recordedVerdictPath(runDir, wbs, fs), "utf8"));
 function scanMode(opts, env, io) {
   const runDir = join2(opts.root, ".spur", "run");
   fs.mkdirSync(runDir, { recursive: true });
@@ -355,6 +392,10 @@ function foldMode(opts, _env, io) {
   const runDir = join2(opts.root, ".spur", "run");
   const scan = JSON.parse(fs.readFileSync(join2(runDir, `${opts.wbs}-residuals.json`), "utf8"));
   const target = recordedVerdictPath(runDir, opts.wbs, fs);
+  const note = verdictDisagreementNote(runDir, opts.wbs, fs);
+  if (note !== null)
+    io.out(`${note}
+`);
   const verdict = loadVerdict(runDir, opts.wbs);
   const findingsPath = join2(runDir, `${opts.wbs}-test-gate.findings`);
   const fold = foldVerdict(verdict, scan, fs.existsSync(findingsPath) ? fs.readFileSync(findingsPath, "utf8") : "");
@@ -386,12 +427,7 @@ function settleMode(opts, env, io) {
     prior = JSON.parse(fs.readFileSync(residualsPath, "utf8"));
   const deferred = scan.items.filter((i) => i.class === "deferrable");
   if (deferred.length > 0 && prior.followUp === undefined) {
-    if (task.featureId === "") {
-      io.err(`residual-settle: ${wbs} deferrals pending but feature_id unknown; re-run: residual-scan settle ${wbs}
-`);
-      return 0;
-    }
-    const args = ["task", "create", `Residuals from ${wbs}`, "--feature", task.featureId, "--skip-ready", "--json"];
+    const args = ["task", "create", `Residuals from ${wbs}`, "--skip-ready", "--json"];
     const created = spur(env, opts.spurBin, args, opts.root);
     let wbsNew = "";
     try {
@@ -407,7 +443,7 @@ function settleMode(opts, env, io) {
       return 0;
     }
     const rows = deferred.map((i) => `- ${i.id} \u2014 ${i.location}: ${i.text}`);
-    const head = `Source task: ${wbs} (feature ${task.featureId}) \u2014 deferred residuals filed by residual-scan settle.`;
+    const head = `Source task: ${wbs}${task.featureId === "" ? "" : ` (feature ${task.featureId})`} \u2014 deferred residuals filed by residual-scan settle (unlinked: a deferral must not hold the completing feature open).`;
     const bgFile = join2(runDir, `${wbs}-residual-background.md`);
     fs.writeFileSync(bgFile, `${[head, "", ...rows].join(`
 `)}
@@ -469,6 +505,7 @@ function main(argv, env = getEnvVars(), options = {}) {
 }
 process.exit(main(process.argv.slice(2)));
 export {
+  verdictDisagreementNote,
   scanResiduals2 as scanResiduals,
   renderReport,
   recordedVerdictPath,

package/plugins/sp/scripts/residual-scan.ts

@@ -115,9 +115,8 @@ function loadTask(env: ScanEnv, spurBinFlag: string | undefined, wbs: string, ro
         [parsed.feature_id, parsed.frontmatter?.feature_id].find((v): v is string => typeof v === 'string') ?? '';
     return { content: typeof parsed.content === 'string' ? parsed.content : '', featureId };
 }
-function loadVerdict(runDir: string, wbs: string): VerdictFile {
-    return JSON.parse(fs.readFileSync(core.recordedVerdictPath(runDir, wbs, fs), 'utf8'));
-}
+const loadVerdict = (runDir: string, wbs: string): VerdictFile =>
+    JSON.parse(fs.readFileSync(core.recordedVerdictPath(runDir, wbs, fs), 'utf8'));
 function scanMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     const runDir = join(opts.root, '.spur', 'run');
     fs.mkdirSync(runDir, { recursive: true });
@@ -135,6 +134,8 @@ function foldMode(opts: ParsedArgs, _env: ScanEnv, io: ScanIo): number {
         fs.readFileSync(join(runDir, `${opts.wbs}-residuals.json`), 'utf8'),
     ) as core.ResidualArtifact;
     const target = core.recordedVerdictPath(runDir, opts.wbs, fs);
+    const note = core.verdictDisagreementNote(runDir, opts.wbs, fs);
+    if (note !== null) io.out(`${note}\n`);
     const verdict = loadVerdict(runDir, opts.wbs);
     const findingsPath = join(runDir, `${opts.wbs}-test-gate.findings`);
     const fold = core.foldVerdict(
@@ -169,13 +170,12 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
     if (fs.existsSync(residualsPath)) prior = JSON.parse(fs.readFileSync(residualsPath, 'utf8'));
     const deferred = scan.items.filter((i) => i.class === 'deferrable');
     if (deferred.length > 0 && prior.followUp === undefined) {
-        if (task.featureId === '') {
-            io.err(
-                `residual-settle: ${wbs} deferrals pending but feature_id unknown; re-run: residual-scan settle ${wbs}\n`,
-            );
-            return 0;
-        }
-        const args = ['task', 'create', `Residuals from ${wbs}`, '--feature', task.featureId, '--skip-ready', '--json'];
+        // The follow-up is filed UNLINKED: carrying a feature edge to the feature whose run produced
+        // it made that feature's done-gate fail with `L4.verifying-incomplete-tasks` the moment a
+        // residual was deferred (2026-10-04 session, E72/1086→1087), so a deferral must not be able
+        // to block the completing feature. The source task and its feature stay named in the
+        // Background, which keeps the traceability without the lifecycle coupling.
+        const args = ['task', 'create', `Residuals from ${wbs}`, '--skip-ready', '--json'];
         const created = spur(env, opts.spurBin, args, opts.root);
         let wbsNew = '';
         try {
@@ -190,7 +190,7 @@ function settleMode(opts: ParsedArgs, env: ScanEnv, io: ScanIo): number {
             return 0;
         }
         const rows = deferred.map((i) => `- ${i.id} — ${i.location}: ${i.text}`);
-        const head = `Source task: ${wbs} (feature ${task.featureId}) — deferred residuals filed by residual-scan settle.`;
+        const head = `Source task: ${wbs}${task.featureId === '' ? '' : ` (feature ${task.featureId})`} — deferred residuals filed by residual-scan settle (unlinked: a deferral must not hold the completing feature open).`;
         const bgFile = join(runDir, `${wbs}-residual-background.md`);
         fs.writeFileSync(bgFile, `${[head, '', ...rows].join('\n')}\n`);
         const updArgs = ['task', 'update', wbsNew, '--section', 'Background', '--from-file', bgFile];

package/plugins/sp/scripts/run-summary.mjs

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/run-summary.ts
+import { readFileSync } from "fs";
+
+// plugins/sp/lib/env.ts
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/lib/transcript.ts
+import { existsSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+var SESSION_ID = /^[A-Za-z0-9_-]+$/;
+var OPERATOR_TOOLS = new Set(["AskUserQuestion"]);
+var zeroTokens = () => ({ input: 0, cacheCreate: 0, cacheRead: 0, output: 0 });
+function formatDuration(ms) {
+  const s = Math.round(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor(s % 3600 / 60);
+  const ss = String(s % 60).padStart(2, "0");
+  return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${ss}` : `${m}:${ss}`;
+}
+function formatTokens(n) {
+  if (n >= 999500)
+    return `${(n / 1e6).toFixed(1)}M`;
+  return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
+}
+function formatTokenSplit(t) {
+  if (!t)
+    return "n/a";
+  const nonCached = t.input + t.cacheCreate + t.output;
+  return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
+}
+function promptText(row) {
+  if (row.type !== "user" || row.isMeta || row.isCompactSummary)
+    return;
+  const content = row.message?.content;
+  if (typeof content === "string")
+    return content;
+  if (!Array.isArray(content) || content.some((b) => b.type === "tool_result"))
+    return;
+  return content.find((b) => b.type === "text")?.text;
+}
+function sumTokens(all) {
+  const total = zeroTokens();
+  for (const t of all)
+    for (const k of Object.keys(total))
+      total[k] += t[k];
+  return total;
+}
+function sumSpans(spans) {
+  return {
+    workMs: spans.reduce((n, s) => n + s.workMs, 0),
+    waitMs: spans.reduce((n, s) => n + s.waitMs, 0),
+    toolCalls: spans.reduce((n, s) => n + s.toolCalls, 0),
+    tokens: sumTokens(spans.map((s) => s.tokens))
+  };
+}
+var newAcc = (ts) => ({
+  last: ts,
+  askMs: 0,
+  asks: new Map,
+  toolIds: new Set,
+  messages: new Map
+});
+function accumulate(acc, row, ts) {
+  acc.last = Math.max(acc.last, ts);
+  const blocks = Array.isArray(row.message?.content) ? row.message.content : [];
+  for (const b of blocks) {
+    if (b.type === "tool_use" && b.id) {
+      acc.toolIds.add(b.id);
+      if (b.name && OPERATOR_TOOLS.has(b.name))
+        acc.asks.set(b.id, ts);
+    } else if (b.type === "tool_result" && b.tool_use_id && acc.asks.has(b.tool_use_id)) {
+      acc.askMs += ts - (acc.asks.get(b.tool_use_id) ?? ts);
+    }
+  }
+  const u = row.message?.usage;
+  if (row.type === "assistant" && u && row.message?.id) {
+    acc.messages.set(row.message.id, {
+      input: u.input_tokens ?? 0,
+      cacheCreate: u.cache_creation_input_tokens ?? 0,
+      cacheRead: u.cache_read_input_tokens ?? 0,
+      output: u.output_tokens ?? 0
+    });
+  }
+}
+function parseRows(lines) {
+  const rows = [];
+  let skippedLines = 0;
+  for (const line of lines) {
+    if (!line.trim())
+      continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      skippedLines++;
+      continue;
+    }
+    const ts = row.timestamp ? Date.parse(row.timestamp) : Number.NaN;
+    if (!Number.isNaN(ts))
+      rows.push([row, ts]);
+  }
+  return { rows, skippedLines };
+}
+function resolveTranscript(env, projectsRoot = join(homedir(), ".claude", "projects"), override) {
+  if (override)
+    return existsSync(override) ? { ok: true, path: override } : { ok: false, reason: "no transcript" };
+  const id = env.CLAUDE_CODE_SESSION_ID;
+  if (!id)
+    return { ok: false, reason: "no host session id (CLAUDE_CODE_SESSION_ID); pass --transcript <path>" };
+  if (!SESSION_ID.test(id))
+    return { ok: false, reason: "refusing a session id with path characters" };
+  if (!existsSync(projectsRoot))
+    return { ok: false, reason: `no transcript root ${projectsRoot}` };
+  for (const dir of readdirSync(projectsRoot)) {
+    const path = join(projectsRoot, dir, `${id}.jsonl`);
+    if (existsSync(path))
+      return { ok: true, path };
+  }
+  return { ok: false, reason: `no transcript for session ${id}` };
+}
+
+// plugins/sp/scripts/run-summary.ts
+function attemptWindow(attempts) {
+  const starts = attempts.map((a) => Date.parse(a.startedAt ?? "")).filter((n) => !Number.isNaN(n));
+  const ends = attempts.map((a) => Date.parse(a.completedAt ?? "")).filter((n) => !Number.isNaN(n));
+  return starts.length && ends.length ? [Math.min(...starts), Math.max(...ends)] : undefined;
+}
+function summaryRow(stage, status, span, measured) {
+  return {
+    stage,
+    status,
+    workMs: span.workMs,
+    waitMs: span.waitMs,
+    toolCalls: measured ? span.toolCalls : null,
+    tokens: measured ? span.tokens : null,
+    time: formatDuration(span.workMs),
+    wait: formatDuration(span.waitMs),
+    token: formatTokenSplit(measured ? span.tokens : null)
+  };
+}
+function buildRunSummary(lines, inputs, since) {
+  const windows = [];
+  for (const { label, progress } of inputs) {
+    const states = (progress.states ?? []).flatMap((s) => {
+      const w = attemptWindow((s.actions ?? []).flatMap((a) => a.attempts ?? []));
+      return w ? [{ s, w }] : [];
+    });
+    if (!states.length)
+      throw new Error(`progress for run ${progress.runId} has no timed attempts`);
+    if (inputs.length === 1) {
+      for (const { s, w } of states) {
+        const stage = (s.visit ?? 1) > 1 ? `${s.state} (visit ${s.visit})` : s.state;
+        windows.push({ stage, status: s.status ?? "", start: w[0], end: w[1] });
+      }
+    } else {
+      const stage = label ?? `${progress.workflow ?? "run"} ${progress.runId.slice(0, 8)}`;
+      const start = Math.min(...states.map(({ w }) => w[0]));
+      windows.push({
+        stage,
+        status: progress.status ?? "",
+        start,
+        end: Math.max(...states.map(({ w }) => w[1]))
+      });
+    }
+  }
+  windows.sort((a, b) => a.start - b.start);
+  const { rows, skippedLines } = parseRows(lines);
+  const measure = (start, end) => {
+    const acc = newAcc(start);
+    for (const [row, ts] of rows)
+      if (ts >= start && ts <= end && promptText(row) === undefined)
+        accumulate(acc, row, ts);
+    const span = {
+      workMs: end - start - acc.askMs,
+      waitMs: acc.askMs,
+      toolCalls: acc.toolIds.size,
+      tokens: sumTokens([...acc.messages.values()])
+    };
+    return { span, measured: acc.toolIds.size > 0 || acc.messages.size > 0 };
+  };
+  const sinceMs = since ? Date.parse(since) : Number.NaN;
+  const totalStart = Number.isNaN(sinceMs) ? Math.min(...windows.map((w) => w.start)) : sinceMs;
+  let totalEnd = Math.max(...windows.map((w) => w.end));
+  if (!Number.isNaN(sinceMs)) {
+    for (const [, ts] of rows)
+      if (ts >= sinceMs)
+        totalEnd = Math.max(totalEnd, ts);
+  }
+  const stageRows = windows.map((w) => {
+    const { span, measured } = measure(w.start, w.end);
+    return summaryRow(w.stage, w.status, span, measured);
+  });
+  const totalMeasure = measure(totalStart, totalEnd);
+  const statuses = [...new Set(inputs.map((i) => i.progress.status ?? ""))].join("/");
+  const total = summaryRow("Total", statuses, totalMeasure.span, totalMeasure.measured);
+  const overlaps = windows.some((w, i) => i > 0 && w.start < (windows[i - 1]?.end ?? 0));
+  const sum = sumSpans(stageRows.map((r) => ({ ...r, toolCalls: r.toolCalls ?? 0, tokens: r.tokens ?? zeroTokens() })));
+  const overhead = {
+    workMs: total.workMs - sum.workMs,
+    waitMs: total.waitMs - sum.waitMs,
+    toolCalls: (total.toolCalls ?? 0) - sum.toolCalls,
+    tokens: Object.fromEntries(Object.keys(sum.tokens).map((k) => [k, (total.tokens?.[k] ?? 0) - sum.tokens[k]]))
+  };
+  if (!overlaps && overhead.workMs > 0)
+    stageRows.push(summaryRow("driver overhead", "", overhead, totalMeasure.measured));
+  return { available: true, rows: stageRows, total, skippedLines };
+}
+function renderSummaryMarkdown(summary) {
+  const line = (r, bold = false) => {
+    const stage = bold ? `**${r.stage}**` : r.stage;
+    return `| ${stage} | ${r.status} | ${r.time} | ${r.wait} | ${r.toolCalls ?? "n/a"} | ${r.token} |`;
+  };
+  return [
+    "| Stage | Status | Time | Wait | Tool calls | Token (total / non-cached) |",
+    "| --- | --- | ---: | ---: | ---: | ---: |",
+    ...summary.rows.map((r) => line(r)),
+    line(summary.total, true)
+  ].join(`
+`);
+}
+var RUN_SUMMARY_USAGE = "usage: run-summary --progress [<label>=]<file> [--progress ...] [--transcript <path>] [--since <iso>] [--markdown]";
+function main(argv, env = getEnvVars(), write = (s) => process.stdout.write(s), projectsRoot) {
+  let transcript;
+  let since;
+  let markdown = false;
+  const progressArgs = [];
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--transcript" && argv[i + 1])
+      transcript = argv[++i];
+    else if (arg === "--progress" && argv[i + 1])
+      progressArgs.push(argv[++i]);
+    else if (arg === "--since" && argv[i + 1])
+      since = argv[++i];
+    else if (arg === "--markdown")
+      markdown = true;
+    else if (arg === "--spur-bin" && argv[i + 1])
+      i++;
+    else {
+      process.stderr.write(`${RUN_SUMMARY_USAGE}
+`);
+      return 2;
+    }
+  }
+  if (!progressArgs.length) {
+    process.stderr.write(`${RUN_SUMMARY_USAGE}
+`);
+    return 2;
+  }
+  const resolved = resolveTranscript(env, projectsRoot, transcript);
+  if (!resolved.ok) {
+    const out = markdown ? `Execution summary: n/a (${resolved.reason})` : JSON.stringify({ available: false, reason: resolved.reason });
+    write(`${out}
+`);
+    return 0;
+  }
+  try {
+    const inputs = progressArgs.map((arg) => {
+      const eq = arg.indexOf("=");
+      const [label, file] = eq > 0 ? [arg.slice(0, eq), arg.slice(eq + 1)] : [undefined, arg];
+      return { label, progress: JSON.parse(readFileSync(file, "utf8")) };
+    });
+    const summary = buildRunSummary(readFileSync(resolved.path, "utf8").split(`
+`), inputs, since);
+    write(`${markdown ? renderSummaryMarkdown(summary) : JSON.stringify({ ...summary, transcript: resolved.path })}
+`);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`run-summary: ${error.message}
+`);
+    return 2;
+  }
+}
+process.exit(main(process.argv.slice(2)));
+export {
+  renderSummaryMarkdown,
+  main,
+  buildRunSummary,
+  RUN_SUMMARY_USAGE
+};