@gobing-ai/spur 0.3.99 → 0.4.0

package/plugins/sp/lib/transcript.ts

@@ -0,0 +1,160 @@
+/**
+ * Host-transcript measurement primitives shared by session-timeline (session review) and
+ * run-summary (dev-run / dev-runall execution summary). Reads Claude Code JSONL rows read-only;
+ * tokens are counted once per message id (a response spans several records). Node builtins only.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export type Tokens = Record<'input' | 'cacheCreate' | 'cacheRead' | 'output', number>;
+
+export interface Span {
+    workMs: number;
+    waitMs: number;
+    toolCalls: number;
+    tokens: Tokens;
+}
+
+type Block = Partial<Record<'type' | 'id' | 'name' | 'text' | 'tool_use_id', string>>;
+
+export interface Row {
+    type?: string;
+    timestamp?: string;
+    isMeta?: boolean;
+    isCompactSummary?: boolean;
+    message?: { id?: string; content?: unknown; usage?: Record<string, number | undefined> };
+}
+
+/** Running measurement of one segment or window. */
+export interface Acc {
+    last: number;
+    askMs: number;
+    asks: Map<string, number>;
+    toolIds: Set<string>;
+    messages: Map<string, Tokens>;
+}
+
+const SESSION_ID = /^[A-Za-z0-9_-]+$/;
+/** Host tools whose call→result gap is the operator answering, not the agent working. */
+const OPERATOR_TOOLS = new Set(['AskUserQuestion']);
+
+export const zeroTokens = (): Tokens => ({ input: 0, cacheCreate: 0, cacheRead: 0, output: 0 });
+
+export function formatDuration(ms: number): string {
+    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}`;
+}
+
+/** Compact token units: `950`, `41k`, `28.4M`. */
+export function formatTokens(n: number): string {
+    if (n >= 999_500) return `${(n / 1e6).toFixed(1)}M`;
+    return n >= 1000 ? `${Math.round(n / 1000)}k` : String(n);
+}
+
+/**
+ * `<total> / <non-cached>`: total = every input class + output; non-cached drops cache reads, the
+ * share re-served from the prompt cache, leaving the fresh input, cache writes and output.
+ */
+export function formatTokenSplit(t: Tokens | null): string {
+    if (!t) return 'n/a';
+    const nonCached = t.input + t.cacheCreate + t.output;
+    return `${formatTokens(nonCached + t.cacheRead)} / ${formatTokens(nonCached)}`;
+}
+
+/** Operator prompt text, or undefined for tool results, meta rows and compaction summaries. */
+export function promptText(row: Row): string | undefined {
+    if (row.type !== 'user' || row.isMeta || row.isCompactSummary) return undefined;
+    const content = row.message?.content;
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content) || (content as Block[]).some((b) => b.type === 'tool_result')) return undefined;
+    return (content as Block[]).find((b) => b.type === 'text')?.text;
+}
+
+export function sumTokens(all: Tokens[]): Tokens {
+    const total = zeroTokens();
+    for (const t of all) for (const k of Object.keys(total) as (keyof Tokens)[]) total[k] += t[k];
+    return total;
+}
+
+export function sumSpans(spans: Span[]): Span {
+    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)),
+    };
+}
+
+export const newAcc = (ts: number): Acc => ({
+    last: ts,
+    askMs: 0,
+    asks: new Map(),
+    toolIds: new Set(),
+    messages: new Map(),
+});
+
+/** Fold one timestamped non-prompt record into a segment or window. */
+export function accumulate(acc: Acc, row: Row, ts: number): void {
+    acc.last = Math.max(acc.last, ts);
+    const blocks = Array.isArray(row.message?.content) ? (row.message.content as Block[]) : [];
+    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;
+    // Split records of one response repeat its usage: keyed by message id, overwrite, never add.
+    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,
+        });
+    }
+}
+
+/** Timestamped rows in file order; malformed lines counted, timestamp-less rows dropped. */
+export function parseRows(lines: string[]): { rows: [Row, number][]; skippedLines: number } {
+    const rows: [Row, number][] = [];
+    let skippedLines = 0;
+    for (const line of lines) {
+        if (!line.trim()) continue;
+        let row: Row;
+        try {
+            row = JSON.parse(line) as Row;
+        } catch {
+            skippedLines++;
+            continue;
+        }
+        const ts = row.timestamp ? Date.parse(row.timestamp) : Number.NaN;
+        if (!Number.isNaN(ts)) rows.push([row, ts]);
+    }
+    return { rows, skippedLines };
+}
+
+export type Resolved = { ok: true; path: string } | { ok: false; reason: string };
+
+export function resolveTranscript(
+    env: Record<string, string | undefined>,
+    projectsRoot = join(homedir(), '.claude', 'projects'),
+    override?: string,
+): Resolved {
+    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}` };
+}

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.99",
+    "version": "0.4.0",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/history-anatomy-cache.mjs

@@ -264,6 +264,7 @@ var FINDING_CATEGORIES = [
   "telemetry",
   "positive"
 ];
+var FINDING_CONFIDENCES = ["high", "medium", "low"];
 function checkReportStructure(reportMarkdown) {
   const problems = [];
   if (/TODO|PLACEHOLDER|FIXME|^\|\s*\|/im.test(reportMarkdown))
@@ -308,6 +309,10 @@ function checkReportStructure(reportMarkdown) {
       if (!/(^|[\s`])P[123]([\s`.]|$)/.test(block) && !block.includes("symbolic-severity")) {
         problems.push("finding-invalid-severity");
       }
+      const confValue = block.match(/`confidence`\s*[:=]\s*`?([^`\n]*?)`?\s*(?:\n|$)/)?.[1]?.trim();
+      if (confValue !== undefined && confValue !== "" && !FINDING_CONFIDENCES.includes(confValue.toLowerCase())) {
+        problems.push(`finding-invalid-confidence:${confValue}`);
+      }
       const catValue = block.match(/`category`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1];
       if (catValue && !FINDING_CATEGORIES.includes(catValue.trim())) {
         problems.push(`finding-invalid-category:${catValue.trim()}`);

package/plugins/sp/scripts/inline-run-setup.mjs

@@ -18,7 +18,7 @@ function usage() {
   const text = [
     "Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]",
     "       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]",
-    "       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]",
+    "       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--estimated] [--spur-bin <path>]",
     "       bun plugins/sp/scripts/inline-run-setup.ts --actions-file <json-file> --run-id <id> [--spur-bin <path>]  (1007 R5 batch trace emission)",
     "       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]",
     "       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]",
@@ -55,22 +55,6 @@ function resolveAppEntry(spurBin) {
   }
   return { entry, portable: true };
 }
-async function readInstalledInventory(file, spurBin) {
-  const localCli = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
-  const bundle = fileURLToPath(new URL("../lib/inline-run.generated.mjs", import.meta.url));
-  const { splitLaunchCommand } = await import(bundle);
-  const launch = spurBin ? splitLaunchCommand(spurBin, 'inline-run-setup "spurBin"') : existsSync(localCli) ? { command: "bun", leadingArgs: [localCli] } : { command: "spur", leadingArgs: [] };
-  if ("error" in launch)
-    throw new Error(launch.error);
-  const result = spawnSync(launch.command, [...launch.leadingArgs, "workflow", "show", file, "--format", "todo", "--json"], { cwd: process.cwd(), encoding: "utf8", timeout: 30000, maxBuffer: 4194304 });
-  if (result.status !== 0) {
-    throw new Error(`could not resolve the workflow definition with the installed CLI: ${result.error?.message ?? result.stderr}`);
-  }
-  const value = JSON.parse(result.stdout);
-  if (value && typeof value === "object" && "ok" in value && "data" in value && value.ok === true)
-    return value.data;
-  return value;
-}
 var TERMINAL_REASONS = new Set([
   "done",
   "paused-operator",
@@ -92,7 +76,7 @@ async function main() {
     process.exit(child.status ?? 1);
   }
   const flags = new Map;
-  let fingerprint = false, action = false, close = false, decide = false, persistOut = false;
+  let fingerprint = false, action = false, close = false, decide = false, persistOut = false, estimated = false;
   const taskFiles = [];
   let spurBin = getEnvVar("SPUR_BIN") ?? "";
   const argv = process.argv.slice(2);
@@ -108,6 +92,8 @@ async function main() {
       decide = true;
     else if (flag === "--persist-out")
       persistOut = true;
+    else if (flag === "--estimated")
+      estimated = true;
     else if (flag === "--task-file")
       taskFiles.push(argv[++i] ?? "");
     else if (flag === "--spur-bin")
@@ -127,6 +113,8 @@ async function main() {
   const okRaw = flags.get("--ok") ?? "";
   const durationRaw = flags.get("--duration-ms") ?? "";
   const actionsFile = flags.get("--actions-file") ?? "";
+  if (estimated && !action)
+    usage();
   if (fingerprint) {
     if (runId !== "" || file !== "" || taskFiles.length !== 1 || (taskFiles[0] ?? "").trim() === "")
       usage();
@@ -207,7 +195,16 @@ async function main() {
     const durationMs = Number(durationRaw);
     if (durationRaw.trim() === "" || !Number.isFinite(durationMs) || durationMs < 0)
       usage();
-    process.exit(await app2.runInlineRunTrace({ runId, close: false, node, kind, status, ok: okRaw === "true", durationMs }));
+    process.exit(await app2.runInlineRunTrace({
+      runId,
+      close: false,
+      node,
+      kind,
+      status,
+      ok: okRaw === "true",
+      durationMs,
+      ...estimated ? { estimated: true } : {}
+    }));
   }
   if (runId.trim() === "" || file.trim() === "")
     usage();
@@ -217,7 +214,11 @@ async function main() {
   const app = await import(entry);
   let inventory;
   try {
-    inventory = await readInstalledInventory(file, spurBin);
+    inventory = await app.readInstalledInventory({
+      file,
+      spurBin,
+      localCli: fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url))
+    });
   } catch (error) {
     const message = `could not resolve the workflow definition: ${error instanceof Error ? error.message : String(error)}`;
     app.writeInlineRunOutcome(runId, { ok: false, runId, error: message });

package/plugins/sp/scripts/inline-run-setup.ts

@@ -18,7 +18,7 @@ function usage(): never {
     const text = [
         'Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]',
         '       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]',
-        '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> --duration-ms <n> [--estimated] [--spur-bin <path>]',
         '       bun plugins/sp/scripts/inline-run-setup.ts --actions-file <json-file> --run-id <id> [--spur-bin <path>]  (1007 R5 batch trace emission)',
         '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--reason <terminal-reason>] [--spur-bin <path>]',
         '       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]',
@@ -61,33 +61,6 @@ function resolveAppEntry(spurBin: string): { entry: string; portable: boolean }
     return { entry, portable: true };
 }
 
-/** Let the selected CLI own config and layer resolution, then revalidate its snapshot in the app. */
-async function readInstalledInventory(file: string, spurBin: string): Promise<unknown> {
-    const localCli = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
-    const bundle = fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url));
-    const { splitLaunchCommand } = (await import(bundle)) as typeof import('../lib/inline-run.generated.mjs');
-    const launch = spurBin
-        ? splitLaunchCommand(spurBin, 'inline-run-setup "spurBin"')
-        : existsSync(localCli)
-          ? { command: 'bun', leadingArgs: [localCli] }
-          : { command: 'spur', leadingArgs: [] };
-    if ('error' in launch) throw new Error(launch.error);
-    const result = spawnSync(
-        launch.command,
-        [...launch.leadingArgs, 'workflow', 'show', file, '--format', 'todo', '--json'],
-        { cwd: process.cwd(), encoding: 'utf8', timeout: 30_000, maxBuffer: 4 * 1024 * 1024 },
-    );
-    if (result.status !== 0) {
-        throw new Error(
-            `could not resolve the workflow definition with the installed CLI: ${result.error?.message ?? result.stderr}`,
-        );
-    }
-    const value: unknown = JSON.parse(result.stdout);
-    // Honor the existing optional JSON envelope without inventing another projection format.
-    if (value && typeof value === 'object' && 'ok' in value && 'data' in value && value.ok === true) return value.data;
-    return value;
-}
-
 // 0937 R2 closed terminal-reason vocabulary for `--close`. COPIED from
 // packages/app/src/workflow/terminal-reason.ts (no value import); parity test asserts equality.
 const TERMINAL_REASONS = new Set([
@@ -116,7 +89,8 @@ async function main(): Promise<void> {
         action = false,
         close = false,
         decide = false,
-        persistOut = false;
+        persistOut = false,
+        estimated = false;
     const taskFiles: string[] = [];
     let spurBin = getEnvVar('SPUR_BIN') ?? '';
     const argv = process.argv.slice(2);
@@ -127,6 +101,7 @@ async function main(): Promise<void> {
         else if (flag === '--close') close = true;
         else if (flag === '--decide') decide = true;
         else if (flag === '--persist-out') persistOut = true;
+        else if (flag === '--estimated') estimated = true;
         else if (flag === '--task-file') taskFiles.push(argv[++i] ?? '');
         else if (flag === '--spur-bin') spurBin = argv[++i] ?? spurBin;
         else if (flag !== undefined) flags.set(flag, argv[++i] ?? '');
@@ -145,6 +120,10 @@ async function main(): Promise<void> {
     const durationRaw = flags.get('--duration-ms') ?? '';
     const actionsFile = flags.get('--actions-file') ?? '';
 
+    // `--estimated` labels a host-reported duration the driver did NOT time around the action
+    // (1070 R2). Only `--action` carries one: every other mode is refused here, before any write.
+    if (estimated && !action) usage();
+
     if (fingerprint) {
         if (runId !== '' || file !== '' || taskFiles.length !== 1 || (taskFiles[0] ?? '').trim() === '') usage();
         const app = (await import(resolveAppEntry(spurBin).entry)) as InlineApp;
@@ -218,7 +197,16 @@ async function main(): Promise<void> {
         const durationMs = Number(durationRaw);
         if (durationRaw.trim() === '' || !Number.isFinite(durationMs) || durationMs < 0) usage();
         process.exit(
-            await app.runInlineRunTrace({ runId, close: false, node, kind, status, ok: okRaw === 'true', durationMs }),
+            await app.runInlineRunTrace({
+                runId,
+                close: false,
+                node,
+                kind,
+                status,
+                ok: okRaw === 'true',
+                durationMs,
+                ...(estimated ? { estimated: true } : {}),
+            }),
         );
     }
 
@@ -228,7 +216,13 @@ async function main(): Promise<void> {
     const app = (await import(entry)) as InlineApp;
     let inventory: unknown;
     try {
-        inventory = await readInstalledInventory(file, spurBin);
+        // The CLI walk lives in the app service (ADR-130 glue budget): the script passes only the
+        // paths it derives from its own module URL.
+        inventory = await app.readInstalledInventory({
+            file,
+            spurBin,
+            localCli: fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url)),
+        });
     } catch (error) {
         const message = `could not resolve the workflow definition: ${error instanceof Error ? error.message : String(error)}`;
         app.writeInlineRunOutcome(runId, { ok: false, runId, error: message });

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

@@ -427,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 {
@@ -448,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(`
 `)}

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

@@ -170,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 {
@@ -191,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];