@openthink/stamp 1.3.0 → 1.3.1

package/README.md

@@ -292,6 +292,33 @@ models pinned, each operator records their own verdict in their own
 state.db (same as today's reviewer-prompt model). Stamp does not assume
 verdicts are model-portable.
 
+### Reviewer execution budgets
+
+Each reviewer subprocess runs under two bounds, set on the operator's
+machine via env vars (they are operator infrastructure, not committed
+policy — different operators on the same repo can pick different values):
+
+| Env var | Default | What it caps |
+|---|---|---|
+| `STAMP_REVIEWER_MAX_TURNS` | `8` | Model/tool round-trips per reviewer call. Hitting it surfaces as `reviewer "<name>" run failed (subtype=error_max_turns)`. |
+| `STAMP_REVIEWER_TIMEOUT_MS` | `300000` (5 min) | Wall-clock budget per reviewer. Hitting it surfaces as `reviewer "<name>" exceeded <N>ms wall-clock budget — raise STAMP_REVIEWER_TIMEOUT_MS to extend it`. |
+
+The defaults are tight enough that a pathological reviewer gives up in
+single-digit minutes rather than racking up Anthropic spend silently.
+Raise them when a reviewer with legitimately heavy lookup tools (Linear
+MCP, multi-file `Read`, ticket reconciliation) repeatedly trips the cap
+on a non-trivial diff. Example:
+
+```sh
+STAMP_REVIEWER_MAX_TURNS=20 STAMP_REVIEWER_TIMEOUT_MS=600000 \
+  stamp review --diff main..HEAD
+```
+
+If a reviewer trips the cap consistently on small diffs too, the prompt
+is probably looping rather than working — diagnose before raising the
+budget. See [`docs/troubleshooting.md`](./docs/troubleshooting.md) for
+the runbook.
+
 ## Deployment shapes
 
 Three ways to run stamp-cli in a real setting, trading setup cost for

package/dist/index.js

@@ -6629,7 +6629,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)."
+  "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."
 ).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)"