@openthink/stamp 1.3.1 → 1.4.0

package/dist/index.js

@@ -520,15 +520,34 @@ function validateConfig(input) {
       }
       enforce_reads_on_dotstamp = d.enforce_reads_on_dotstamp;
     }
+    const max_turns = parsePositiveInt(
+      d.max_turns,
+      `config.reviewers.${name}.max_turns`
+    );
+    const timeout_ms = parsePositiveInt(
+      d.timeout_ms,
+      `config.reviewers.${name}.timeout_ms`
+    );
     reviewers2[name] = {
       prompt: d.prompt,
       ...tools ? { tools } : {},
       ...mcp_servers ? { mcp_servers } : {},
-      ...enforce_reads_on_dotstamp !== void 0 ? { enforce_reads_on_dotstamp } : {}
+      ...enforce_reads_on_dotstamp !== void 0 ? { enforce_reads_on_dotstamp } : {},
+      ...max_turns !== void 0 ? { max_turns } : {},
+      ...timeout_ms !== void 0 ? { timeout_ms } : {}
     };
   }
   return { branches, reviewers: reviewers2 };
 }
+function parsePositiveInt(input, path2) {
+  if (input === void 0 || input === null) return void 0;
+  if (typeof input !== "number" || !Number.isFinite(input) || !Number.isInteger(input) || input <= 0) {
+    throw new Error(
+      `${path2} must be a positive integer (got ${JSON.stringify(input)})`
+    );
+  }
+  return input;
+}
 function parseChecks(input, branchName) {
   if (input === void 0 || input === null) return void 0;
   if (!Array.isArray(input)) {
@@ -2027,14 +2046,14 @@ async function invokeReviewer(params) {
     ...mcpServersResolved ?? {},
     "stamp-verdict": verdictServer
   };
-  const maxTurns = parseIntEnv("STAMP_REVIEWER_MAX_TURNS", 8);
-  const timeoutMs = parseIntEnv("STAMP_REVIEWER_TIMEOUT_MS", 5 * 60 * 1e3);
+  const maxTurns = def.max_turns ?? parseIntEnv("STAMP_REVIEWER_MAX_TURNS", 8);
+  const timeoutMs = def.timeout_ms ?? parseIntEnv("STAMP_REVIEWER_TIMEOUT_MS", 5 * 60 * 1e3);
   const modelOverride = resolveReviewerModel(params.reviewer);
   const abortController = new AbortController();
   const timeoutHandle = setTimeout(() => {
     abortController.abort(
       new Error(
-        `reviewer "${params.reviewer}" exceeded ${timeoutMs}ms wall-clock budget \u2014 raise STAMP_REVIEWER_TIMEOUT_MS to extend it`
+        `reviewer "${params.reviewer}" exceeded ${timeoutMs}ms wall-clock budget`
       )
     );
   }, timeoutMs);
@@ -2119,7 +2138,14 @@ async function invokeReviewer(params) {
         if (msg.subtype === "success") {
           finalText = msg.result;
         } else {
-          errorMessage = `reviewer "${params.reviewer}" run failed (subtype=${msg.subtype})`;
+          errorMessage = formatRunFailureMessage({
+            reviewer: params.reviewer,
+            subtype: msg.subtype,
+            repoRoot: params.repoRoot,
+            toolCalls,
+            maxTurns,
+            timeoutMs
+          });
         }
         break;
       }
@@ -2127,7 +2153,16 @@ async function invokeReviewer(params) {
   } catch (err) {
     if (abortController.signal.aborted) {
       const reason = abortController.signal.reason instanceof Error ? abortController.signal.reason.message : String(abortController.signal.reason ?? "aborted");
-      throw new Error(reason);
+      throw new Error(
+        formatAbortMessage({
+          reviewer: params.reviewer,
+          reason,
+          repoRoot: params.repoRoot,
+          toolCalls,
+          maxTurns,
+          timeoutMs
+        })
+      );
     }
     throw err;
   } finally {
@@ -2339,6 +2374,66 @@ function writeFailedParseSpool(repoRoot, reviewer, text) {
   const lineCount = text === "" ? 0 : text.split("\n").length;
   return { path: filepath, lineCount };
 }
+function writeFailedRunSpool(args) {
+  const dir = path.join(gitCommonDir(args.repoRoot), "stamp", "failed-runs");
+  mkdirSync2(dir, { recursive: true, mode: 448 });
+  chmodSync(dir, 448);
+  const slug = sanitizeReviewerSlug(args.reviewer);
+  const filename = `${Date.now()}-${slug}.log`;
+  const filepath = path.join(dir, filename);
+  const payload = {
+    reviewer: args.reviewer,
+    failure: args.failure,
+    max_turns: args.maxTurns,
+    timeout_ms: args.timeoutMs,
+    tool_call_count: args.toolCalls.length,
+    tool_calls: args.toolCalls,
+    captured_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  writeFileSync3(filepath, JSON.stringify(payload, null, 2) + "\n", {
+    flag: "wx",
+    mode: 384
+  });
+  chmodSync(filepath, 384);
+  return filepath;
+}
+function formatRunFailureMessage(args) {
+  const spool = trySpool({
+    repoRoot: args.repoRoot,
+    reviewer: args.reviewer,
+    failure: `subtype=${args.subtype}`,
+    toolCalls: args.toolCalls,
+    maxTurns: args.maxTurns,
+    timeoutMs: args.timeoutMs
+  });
+  const tracePart = formatTracePart(spool, args.toolCalls.length);
+  const hintPart = args.subtype === "error_max_turns" ? ` \u2014 raise STAMP_REVIEWER_MAX_TURNS (currently ${args.maxTurns}) or set reviewers.${args.reviewer}.max_turns in .stamp/config.yml to extend it` : "";
+  return `reviewer "${args.reviewer}" run failed (subtype=${args.subtype})${tracePart}${hintPart}`;
+}
+function formatAbortMessage(args) {
+  const spool = trySpool({
+    repoRoot: args.repoRoot,
+    reviewer: args.reviewer,
+    failure: `abort: ${args.reason}`,
+    toolCalls: args.toolCalls,
+    maxTurns: args.maxTurns,
+    timeoutMs: args.timeoutMs
+  });
+  const tracePart = formatTracePart(spool, args.toolCalls.length);
+  const hintPart = ` \u2014 raise STAMP_REVIEWER_TIMEOUT_MS (currently ${args.timeoutMs}ms) or set reviewers.${args.reviewer}.timeout_ms in .stamp/config.yml to extend it`;
+  return `${args.reason}${tracePart}${hintPart}`;
+}
+function trySpool(args) {
+  try {
+    return writeFailedRunSpool(args);
+  } catch {
+    return null;
+  }
+}
+function formatTracePart(spool, toolCallCount) {
+  if (spool === null) return "";
+  return ` \u2014 turn trace at ${spool} (${toolCallCount} tool call${toolCallCount === 1 ? "" : "s"} captured)`;
+}
 function parseIntEnv(name, fallback) {
   const raw = process.env[name];
   if (!raw) return fallback;
@@ -5091,11 +5186,12 @@ function runPrune(opts) {
   );
   const repoRoot = findRepoRoot();
   const dbPath = stampStateDbPath(repoRoot);
-  const spoolDir = join8(gitCommonDir(repoRoot), "stamp", "failed-parses");
+  const parsesDir = join8(gitCommonDir(repoRoot), "stamp", "failed-parses");
+  const runsDir = join8(gitCommonDir(repoRoot), "stamp", "failed-runs");
   const spoolCutoffMs = Date.now() - durationMs;
-  if (!existsSync14(dbPath) && !existsSync14(spoolDir)) {
+  if (!existsSync14(dbPath) && !existsSync14(parsesDir) && !existsSync14(runsDir)) {
     console.log(
-      `note: nothing to prune (neither ${dbPath} nor ${spoolDir} exists \u2014 both are created on first \`stamp review\`)`
+      `note: nothing to prune (none of ${dbPath}, ${parsesDir}, ${runsDir} exist \u2014 all are created on first \`stamp review\`)`
     );
     return;
   }
@@ -5113,14 +5209,19 @@ function runPrune(opts) {
           any2 = true;
         }
       }
-      const spoolPeek = peekFailedParseSpools(spoolDir, spoolCutoffMs);
-      if (spoolPeek.length > 0) {
-        if (any2) console.log("");
-        console.log(
-          `would prune ${spoolPeek.length} failed-parse spool file${spoolPeek.length === 1 ? "" : "s"} older than ${humanLabel}:`
-        );
-        for (const f of spoolPeek) console.log(`  ${f}`);
-        any2 = true;
+      for (const [label, dir] of [
+        ["failed-parse", parsesDir],
+        ["failed-run", runsDir]
+      ]) {
+        const peek = peekSpools(dir, spoolCutoffMs);
+        if (peek.length > 0) {
+          if (any2) console.log("");
+          console.log(
+            `would prune ${peek.length} ${label} spool file${peek.length === 1 ? "" : "s"} older than ${humanLabel}:`
+          );
+          for (const f of peek) console.log(`  ${f}`);
+          any2 = true;
+        }
       }
       if (!any2) {
         console.log(`note: nothing to prune (no rows or spools older than ${humanLabel})`);
@@ -5143,13 +5244,18 @@ function runPrune(opts) {
         any = true;
       }
     }
-    const spoolDeleted = pruneFailedParseSpools(spoolDir, spoolCutoffMs);
-    if (spoolDeleted > 0) {
-      if (any) console.log("");
-      console.log(
-        `${spoolDeleted} failed-parse spool file${spoolDeleted === 1 ? "" : "s"} pruned`
-      );
-      any = true;
+    for (const [label, dir] of [
+      ["failed-parse", parsesDir],
+      ["failed-run", runsDir]
+    ]) {
+      const deleted = pruneSpools(dir, spoolCutoffMs);
+      if (deleted > 0) {
+        if (any) console.log("");
+        console.log(
+          `${deleted} ${label} spool file${deleted === 1 ? "" : "s"} pruned`
+        );
+        any = true;
+      }
     }
     if (!any) {
       console.log(`note: nothing to prune (no rows or spools older than ${humanLabel})`);
@@ -5158,7 +5264,7 @@ function runPrune(opts) {
     db?.close();
   }
 }
-function peekFailedParseSpools(spoolDir, cutoffMs) {
+function peekSpools(spoolDir, cutoffMs) {
   if (!existsSync14(spoolDir)) return [];
   const out = [];
   for (const entry of readdirSync3(spoolDir)) {
@@ -5174,8 +5280,8 @@ function peekFailedParseSpools(spoolDir, cutoffMs) {
   }
   return out.sort();
 }
-function pruneFailedParseSpools(spoolDir, cutoffMs) {
-  const targets = peekFailedParseSpools(spoolDir, cutoffMs);
+function pruneSpools(spoolDir, cutoffMs) {
+  const targets = peekSpools(spoolDir, cutoffMs);
   let deleted = 0;
   for (const filepath of targets) {
     try {
@@ -6629,7 +6735,7 @@ serverRepo.command("restore <name>").description("restore the most recent soft-d
   }
 );
 program.command("review").description(
-  "run configured reviewer(s) against a diff. Reviewer config + prompts are sourced from the merge-base tree (security: prevents feature-branch self-review). For lock-file drift checks, use `stamp reviewers verify` (which exits 3 on drift). Reviewer execution budgets are env-tunable: STAMP_REVIEWER_MAX_TURNS (default 8) caps the model/tool round-trip count, STAMP_REVIEWER_TIMEOUT_MS (default 300000) bounds wall-clock time. Raise them when a reviewer with heavy lookup tools (Linear / GitHub MCP, multi-file Read) fails with subtype=error_max_turns or the abort message \u2014 see docs/troubleshooting.md."
+  "run configured reviewer(s) against a diff. Reviewer config + prompts are sourced from the merge-base tree (security: prevents feature-branch self-review). For lock-file drift checks, use `stamp reviewers verify` (which exits 3 on drift). Reviewer execution budgets resolve narrowest-wins: `.stamp/config.yml` per-reviewer fields (`reviewers.<name>.max_turns` / `timeout_ms`, committed, sourced from the merge-base tree), then env overrides (`STAMP_REVIEWER_MAX_TURNS` default 8, `STAMP_REVIEWER_TIMEOUT_MS` default 300000), then defaults. On failure a structured turn trace is written to `.git/stamp/failed-runs/` \u2014 see docs/troubleshooting.md."
 ).requiredOption("--diff <revspec>", "git revspec to review, e.g. main..HEAD").option("--only <reviewer>", "run a single reviewer by name").option(
   "--allow-large",
   "bypass the 200KB diff size cap (raise STAMP_REVIEW_DIFF_CAP_BYTES for a different threshold)"