@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -9,6 +9,8 @@ import { fileURLToPath } from 'node:url';
 // Type-only namespace import (erased before bundling; the smoke scanner exempts `import type`).
 import type * as spurApp from '@gobing-ai/spur-app';
 import { getEnvVar } from '../lib/env';
+import { loadInlineApp } from '../lib/inline-run-app';
+import { writeCloseSummary } from './run-summary';
 
 // EMBEDDED_SPUR_SCHEMAS: declared by the bundle twin, never exported by the barrel — optional
 // intersection member, exactly what the previous structural cast expressed.
@@ -18,9 +20,12 @@ 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 --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 --action --run-id <id> --node <state> --kind <kind> --status <done|failed> --ok <true|false> [--duration-ms <n>] [--estimated] [--project-root <path>] [--spur-bin <path>]',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --node-enter --run-id <id> --node <state> [--project-root <path>] [--spur-bin <path>]  (1136 R4: stamps the node enter time)',
+        '       bun plugins/sp/scripts/inline-run-setup.ts --actions-file <json-file> --run-id <id> [--project-root <path>] [--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>] [--no-summary] [--project-root <path>] [--spur-bin <path>]',
+        '       --project-root (1136 R1) names the tree that OWNS the run row; without it the run row is read from the cwd tree, and a miss exits 1 with RUN_NOT_FOUND',
+        '       --duration-ms is optional on --action (1136 R4): omitted, the duration is measured from the calling --node-enter; supplied, it records provenance host-reported',
         '       bun plugins/sp/scripts/inline-run-setup.ts --persist-out --from <worktree-path> [--task-file <path>]... [--spur-bin <path>]',
         '       terminal-reason is a closed enum (0937 R2): done, paused-operator, failed-check, failed-agent, failed-timeout, failed-guard, cancelled, interrupted, retry-exhausted',
         '       close defaults (1051 AC1): --status done → reason done, --status paused → reason paused-operator; --status failed requires an explicit --reason',
@@ -61,46 +66,7 @@ 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([
-    'done',
-    'paused-operator',
-    'failed-check',
-    'failed-agent',
-    'failed-timeout',
-    'failed-guard',
-    'cancelled',
-    'interrupted',
-    'retry-exhausted',
-]);
+const SETUP_EXPORTS = ['readInstalledInventory', 'runInlineRunSetup', 'writeInlineRunOutcome'] as const;
 
 async function main(): Promise<void> {
     // The portable Node twin has no workspace imports; SQLite still uses Spur's existing Bun runtime.
@@ -116,7 +82,10 @@ async function main(): Promise<void> {
         action = false,
         close = false,
         decide = false,
-        persistOut = false;
+        persistOut = false,
+        nodeEnter = false,
+        estimated = false,
+        noSummary = false;
     const taskFiles: string[] = [];
     let spurBin = getEnvVar('SPUR_BIN') ?? '';
     const argv = process.argv.slice(2);
@@ -126,7 +95,10 @@ async function main(): Promise<void> {
         else if (flag === '--action') action = true;
         else if (flag === '--close') close = true;
         else if (flag === '--decide') decide = true;
+        else if (flag === '--node-enter') nodeEnter = true;
         else if (flag === '--persist-out') persistOut = true;
+        else if (flag === '--estimated') estimated = true;
+        else if (flag === '--no-summary') noSummary = 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] ?? '');
@@ -139,42 +111,43 @@ async function main(): Promise<void> {
     const optionsJson = flags.get('--options-json') ?? '';
     const node = flags.get('--node') ?? '';
     const kind = flags.get('--kind') ?? '';
+    const projectRoot = flags.get('--project-root') ?? '';
     const status = flags.get('--status') ?? '';
     const reason = flags.get('--reason') ?? '';
     const okRaw = flags.get('--ok') ?? '';
     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();
+    // 1146 AC3: `--no-summary` belongs to the close step; any other mode is a usage error.
+    if (noSummary && !close) usage();
+
     if (fingerprint) {
         if (runId !== '' || file !== '' || taskFiles.length !== 1 || (taskFiles[0] ?? '').trim() === '') usage();
-        const app = (await import(resolveAppEntry(spurBin).entry)) as InlineApp;
+        const { app } = await loadInlineApp<InlineApp>(spurBin, resolveAppEntry, ['runInlineRunFingerprint']);
         process.exit(await app.runInlineRunFingerprint({ taskFile: taskFiles[0] ?? '', featureFile }));
     }
 
-    if (actionsFile !== '') {
-        if (action || close || fingerprint || decide || persistOut || file !== '' || taskFiles.length > 0) usage();
-        if (runId.trim() === '' || status !== '' || node !== '' || kind !== '') usage();
-        if (okRaw !== '' || durationRaw !== '') usage();
-        if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
-        const app = (await import(resolveAppEntry(spurBin).entry)) as InlineApp;
-        process.exit(await app.runInlineRunTraceBatch({ runId, actionsFile }));
-    }
-
     if (decide) {
         if (action || close || fingerprint || file !== '' || taskFiles.length > 0) usage();
         if (runId.trim() === '' || node.trim() === '' || optionsJson.trim() === '') usage();
         if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
         try {
-            const { entry, portable } = resolveAppEntry(spurBin);
-            const app = (await import(entry)) as InlineApp;
-            const bundlePath = fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url));
-            const lib = (await import(bundlePath)) as typeof import('../lib/inline-run.generated.mjs');
-            // Decide-enabled switch resolved at the driver boundary (ADR-082), passed as a param.
-            const enabled = await lib.resolveDecideDecisionMakerEnabled(
-                process.cwd(),
-                portable ? { embeddedSchemas: lib.EMBEDDED_SPUR_SCHEMAS } : undefined,
+            const { app, portable } = await loadInlineApp<InlineApp>(spurBin, resolveAppEntry, ['runInlineRunDecide']);
+            // Decide switch + catalog config, resolved once (1094, ADR-082), behind the skew guard (1120 R2).
+            const { app: lib } = await loadInlineApp<typeof import('../lib/inline-run.generated.mjs')>(
+                spurBin,
+                () => ({ entry: fileURLToPath(new URL('../lib/inline-run.generated.mjs', import.meta.url)), portable }),
+                ['resolveDecideDecisionMakerEnabled', 'loadSpurConfig'],
             );
-            process.exit(await app.runInlineRunDecide({ runId, node, optionsFile: optionsJson, enabled }));
+            const loadOpts = portable ? { embeddedSchemas: lib.EMBEDDED_SPUR_SCHEMAS } : undefined;
+            const [enabled, spurConfig] = await Promise.all([
+                lib.resolveDecideDecisionMakerEnabled(process.cwd(), loadOpts),
+                lib.loadSpurConfig(process.cwd(), loadOpts),
+            ]);
+            process.exit(await app.runInlineRunDecide({ runId, node, optionsFile: optionsJson, enabled, spurConfig }));
         } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             process.stdout.write(`${JSON.stringify({ ok: false, runId, error: message })}\n`);
@@ -185,50 +158,45 @@ async function main(): Promise<void> {
     if (persistOut) {
         if (fingerprint || decide || action || close || runId !== '' || file !== '') usage();
         if (from.trim() === '' || taskFiles.some((taskFile) => taskFile.trim() === '')) usage();
-        const app = (await import(resolveAppEntry(spurBin).entry)) as InlineApp;
+        const { app } = await loadInlineApp<InlineApp>(spurBin, resolveAppEntry, ['runInlineRunPersistOut']);
         process.exit(await app.runInlineRunPersistOut({ from, taskFiles }));
     }
 
-    if (action || close) {
-        if (action && close) usage();
-        if (runId.trim() === '' || status.trim() === '') usage();
+    if (nodeEnter || actionsFile !== '' || action || close) {
         if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
-        const app = (await import(resolveAppEntry(spurBin).entry)) as InlineApp;
-        if (close) {
-            if (!app.isInlineRunCloseStatus(status)) usage();
-            // 0937 R2: failed close needs a declared closed-enum reason — before any write.
-            if (reason.trim() === '' ? status === 'failed' : !TERMINAL_REASONS.has(reason)) usage();
-            process.exit(
-                await app.runInlineRunTrace({
-                    runId,
-                    close: true,
-                    node: '',
-                    kind: '',
-                    status,
-                    ok: true,
-                    durationMs: 0,
-                    ...(reason.trim() === '' ? {} : { reason }),
-                }),
-            );
-        }
-        if (node.trim() === '' || kind.trim() === '') usage();
-        if (!app.isInlineRunActionStatus(status)) usage();
-        // `--ok` and `--duration-ms` are required and exact (0868 #2): no silent defaults.
-        if (okRaw !== 'true' && okRaw !== 'false') usage();
-        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 }),
-        );
+        const mode = nodeEnter ? 'node-enter' : actionsFile !== '' ? 'actions-file' : close ? 'close' : 'action';
+        const { app } = await loadInlineApp<InlineApp>(spurBin, resolveAppEntry, ['runInlineRunTraceMode']);
+        const code = await app.runInlineRunTraceMode({
+            mode,
+            runId,
+            node,
+            kind,
+            status,
+            reason,
+            ok: okRaw,
+            durationMs: durationRaw,
+            actionsFile,
+            projectRoot,
+            estimated,
+            noSummary,
+            ...(noSummary ? {} : { summarize: async (run) => writeCloseSummary(run) }),
+        });
+        if (code === 2) usage();
+        process.exit(code);
     }
 
     if (runId.trim() === '' || file.trim() === '') usage();
     if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
-    const { entry, portable } = resolveAppEntry(spurBin);
-    const app = (await import(entry)) as InlineApp;
+    const { app, portable } = await loadInlineApp<InlineApp>(spurBin, resolveAppEntry, SETUP_EXPORTS);
     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/persist-out-check.mjs

@@ -9,60 +9,64 @@ var EVIDENCE_DIR = join(".spur", "memory", "evidence");
 var RUN_DIR = join(".spur", "run");
 var NAMED_CAP = 32;
 var PREFIX_CAP = 64;
-var EVIDENCE_CAP = 256;
 function wbsOfTaskFile(path) {
   const m = /^(\d+)_/.exec(basename(path));
   return m?.[1] ?? null;
 }
-function listFilesUnder(root, rel, cap) {
-  const dir = join(root, rel);
+function walkFiles(dir, root) {
   if (!existsSync(dir))
     return [];
   const out = [];
   const walk = (cur) => {
-    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 {
+    for (const e of readdirSync(cur, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const p = join(cur, e.name);
+      if (e.isDirectory())
+        walk(p);
+      else if (e.isFile())
         out.push(relative(root, p));
-        if (out.length > cap)
-          return false;
-      }
     }
-    return true;
   };
-  return walk(dir) ? out : null;
+  walk(dir);
+  return out;
 }
-function listObligations(wtRoot, wbsList, runIds) {
-  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))
+function collectOwned(rels, prefixes, counts, out) {
+  for (const rel of rels) {
+    const prefix = prefixes.find((p) => basename(rel).startsWith(`${p}-`));
+    if (prefix === undefined)
       continue;
-    let entries;
-    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)));
+    const count = (counts.get(prefix) ?? 0) + 1;
+    if (count > PREFIX_CAP)
+      return false;
+    counts.set(prefix, count);
+    out.push(rel);
   }
-  return [...new Set(out)].sort();
+  return true;
+}
+function listObligations(wtRoot, wbsList, runIds) {
+  const prefixes = [...new Set([...wbsList, ...runIds].filter(Boolean))];
+  if (prefixes.length === 0)
+    return null;
+  const evDir = join(wtRoot, EVIDENCE_DIR);
+  const runDir = join(wtRoot, RUN_DIR);
+  const evFiles = walkFiles(evDir, wtRoot);
+  const runFiles = existsSync(runDir) ? readdirSync(runDir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => join(RUN_DIR, e.name)).sort() : [];
+  const files = [];
+  const counts = new Map;
+  if (!collectOwned(evFiles, prefixes, counts, files))
+    return null;
+  if (!collectOwned(runFiles, prefixes, counts, files))
+    return null;
+  const unowned = evFiles.length - files.filter((f) => f.startsWith(EVIDENCE_DIR)).length;
+  return { files: [...new Set(files)].sort(), unowned };
 }
-function compareTrees(wtRoot, invokeRoot, files) {
+function compareTrees(wtRoot, invokeRoot, files, foreignDivergent = new Set) {
   const missing = [];
   const divergent = [];
   let ok = 0;
   for (const rel of files) {
+    if (foreignDivergent.has(rel) || foreignDivergent.has(basename(rel))) {
+      continue;
+    }
     const wtPath = join(wtRoot, rel);
     const invPath = join(invokeRoot, rel);
     if (!existsSync(invPath)) {
@@ -82,7 +86,7 @@ function compareTrees(wtRoot, invokeRoot, files) {
   return { missing, divergent, ok };
 }
 function persistOutCheckUsage() {
-  return "usage: persist-out-check --from <worktree> [--task-file <path>]\u2026 [--run-id <id>]\u2026 [--root <invoke-tree>]";
+  return "usage: persist-out-check --from <worktree> [--task-file <path>]\u2026 [--run-id <id>]\u2026 [--root <invoke-tree>] [--success-json <path>]";
 }
 function defaultInvokeRoot(cwd) {
   try {
@@ -95,6 +99,7 @@ function defaultInvokeRoot(cwd) {
 }
 function main(argv, invokeRoot = defaultInvokeRoot(process.cwd())) {
   let wtRoot = "";
+  let successJsonPath = "";
   const wbsList = [];
   const runIds = [];
   for (let i = 0;i < argv.length; i++) {
@@ -113,25 +118,64 @@ function main(argv, invokeRoot = defaultInvokeRoot(process.cwd())) {
       const id = argv[++i] ?? "";
       if (id)
         runIds.push(id);
+    } else if (arg === "--success-json") {
+      successJsonPath = argv[++i] ?? "";
     } else {
       process.stderr.write(`${persistOutCheckUsage()}
 `);
       return 2;
     }
   }
+  if (wbsList.length === 0 && runIds.length === 0) {
+    process.stderr.write(`${persistOutCheckUsage()}
+persist-out-check: at least one --task-file or --run-id prefix required
+`);
+    return 2;
+  }
   if (!wtRoot || !existsSync(wtRoot) || !statSync(wtRoot).isDirectory()) {
     process.stderr.write(`${persistOutCheckUsage()}
 persist-out-check: --from must be an existing worktree directory
 `);
     return 2;
   }
-  const files = listObligations(wtRoot, wbsList, runIds);
-  if (files === null) {
-    process.stderr.write(`persist-out-check: BLOCKED \u2014 worktree evidence listing failed or exceeded caps (64/prefix, ${EVIDENCE_CAP} evidence files) \u2014 inspect by hand
+  const foreignDivergent = new Set;
+  const skips = [];
+  const candidates = [
+    successJsonPath,
+    join(invokeRoot, ".spur", "run", "persist-out.json"),
+    join(wtRoot, ".spur", "run", "persist-out.json")
+  ].filter(Boolean);
+  for (const cand of candidates) {
+    if (existsSync(cand)) {
+      try {
+        const parsed = JSON.parse(readFileSync(cand, "utf8"));
+        if (Array.isArray(parsed.evidenceSkipped)) {
+          for (const item of parsed.evidenceSkipped) {
+            if (item.reason === "foreign-divergent" && typeof item.name === "string") {
+              foreignDivergent.add(item.name);
+              foreignDivergent.add(join(EVIDENCE_DIR, item.name));
+            }
+          }
+        }
+        if (Array.isArray(parsed.skipped)) {
+          for (const item of parsed.skipped) {
+            if (typeof item.id === "string" && typeof item.reason === "string") {
+              skips.push({ id: item.id, reason: item.reason });
+            }
+          }
+        }
+        break;
+      } catch {}
+    }
+  }
+  const obligations = listObligations(wtRoot, wbsList, runIds);
+  if (obligations === null) {
+    process.stderr.write(`persist-out-check: BLOCKED \u2014 worktree evidence listing failed or exceeded caps (${PREFIX_CAP}/prefix) \u2014 inspect by hand
 `);
     return 1;
   }
-  const { missing, divergent, ok } = compareTrees(wtRoot, invokeRoot, files);
+  const { files, unowned } = obligations;
+  const { missing, divergent, ok } = compareTrees(wtRoot, invokeRoot, files, foreignDivergent);
   const findings = [
     ...missing.map((f) => `MISSING ${f}`),
     ...divergent.map((f) => `DIVERGENT ${f} \u2014 reconcile by hand (persist-out never overwrites)`)
@@ -143,7 +187,12 @@ persist-out-check: --from must be an existing worktree directory
     process.stdout.write(`\u2026 +${findings.length - NAMED_CAP} more
 `);
   if (findings.length === 0) {
-    process.stdout.write(`persist-out-check: ok \u2014 ${ok} evidence file(s) persisted, nothing abandoned
+    for (const skip of skips) {
+      process.stdout.write(`SKIP ${skip.id}: ${skip.reason}
+`);
+    }
+    const abandonedMsg = skips.length > 0 ? `${skips.length} skipped` : "nothing abandoned";
+    process.stdout.write(`persist-out-check: ok \u2014 ${ok} evidence file(s) persisted, unowned: ${unowned}, ${abandonedMsg}
 `);
     return 0;
   }