@openthink/stamp 1.2.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/hooks/post-receive.cjs

@@ -7497,6 +7497,58 @@ function buildMirrorPushInvocation(githubRepo, newSha, refname, token, parentEnv
   };
   return { args, env };
 }
+function buildMirrorPushInvocationSsh(githubRepo, newSha, refname, parentEnv = process.env, sshKeyPath) {
+  const remoteUrl = `git@github.com:${githubRepo}.git`;
+  const args = ["push", remoteUrl, `${newSha}:${refname}`];
+  const env = { ...parentEnv };
+  if (sshKeyPath) {
+    env["GIT_SSH_COMMAND"] = `ssh -F /dev/null -i ${sshKeyPath} -o IdentitiesOnly=yes -o UserKnownHostsFile=/etc/ssh/ssh_known_hosts -o StrictHostKeyChecking=yes`;
+  }
+  return { args, env };
+}
+
+// src/lib/perRepoKey.ts
+var VALID_OWNER = /^[A-Za-z0-9-]+$/;
+var VALID_REPO = /^[A-Za-z0-9._-]+$/;
+var SSH_CLIENT_KEY_DIR = "/srv/git/.ssh-client-keys";
+function computePerRepoKeyPath(githubRepo) {
+  if (typeof githubRepo !== "string" || githubRepo.length === 0) {
+    throw new Error("computePerRepoKeyPath: githubRepo must be a non-empty string");
+  }
+  if (githubRepo.startsWith("-")) {
+    throw new Error(
+      `computePerRepoKeyPath: githubRepo must not start with '-': ${githubRepo}`
+    );
+  }
+  if (githubRepo.includes("..")) {
+    throw new Error(
+      `computePerRepoKeyPath: githubRepo must not contain '..': ${githubRepo}`
+    );
+  }
+  const slashCount = (githubRepo.match(/\//g) ?? []).length;
+  if (slashCount !== 1) {
+    throw new Error(
+      `computePerRepoKeyPath: githubRepo must be exactly <owner>/<repo>: ${githubRepo}`
+    );
+  }
+  const [owner, repo] = githubRepo.split("/");
+  if (!owner || !repo) {
+    throw new Error(
+      `computePerRepoKeyPath: owner and repo halves must both be non-empty: ${githubRepo}`
+    );
+  }
+  if (!VALID_OWNER.test(owner)) {
+    throw new Error(
+      `computePerRepoKeyPath: owner must match [A-Za-z0-9-]+ (got "${owner}" in "${githubRepo}")`
+    );
+  }
+  if (!VALID_REPO.test(repo)) {
+    throw new Error(
+      `computePerRepoKeyPath: repo must match [A-Za-z0-9._-]+ (got "${repo}" in "${githubRepo}")`
+    );
+  }
+  return `${SSH_CLIENT_KEY_DIR}/${owner}_${repo}_ed25519`;
+}
 
 // src/lib/refPatterns.ts
 function globToRegex(pattern) {
@@ -7598,20 +7650,41 @@ function readMirrorConfigFromHeadBranch() {
   return readMirrorConfig(sha);
 }
 var ZERO_SHA = "0000000000000000000000000000000000000000";
+var SSH_DEPLOY_KEY_PATH = "/srv/git/.ssh-client-keys/github_ed25519";
 async function mirrorRef(label, refname, oldSha, newSha, githubRepo) {
   const token = process.env["GITHUB_BOT_TOKEN"];
-  if (!token) {
+  let perRepoKeyPath;
+  try {
+    perRepoKeyPath = computePerRepoKeyPath(githubRepo);
+  } catch (err) {
     warn(
-      `mirror: GITHUB_BOT_TOKEN not set in environment; skipping mirror of ${label} \u2192 ${githubRepo}`
+      `mirror: skipping per-repo SSH path \u2014 could not derive key path for ${githubRepo}: ${err instanceof Error ? err.message : String(err)}`
+    );
+    perRepoKeyPath = null;
+  }
+  const sshKeyPath = perRepoKeyPath && (0, import_node_fs3.existsSync)(perRepoKeyPath) ? perRepoKeyPath : (0, import_node_fs3.existsSync)(SSH_DEPLOY_KEY_PATH) ? null : void 0;
+  const useSsh = sshKeyPath !== void 0;
+  if (!useSsh && !token) {
+    warn(
+      `mirror: GITHUB_BOT_TOKEN not set in environment and no deploy key on disk (checked per-repo path ${perRepoKeyPath ?? "<derivation failed>"} and legacy ${SSH_DEPLOY_KEY_PATH}); skipping mirror of ${label} \u2192 ${githubRepo}`
     );
     return;
   }
-  const { args, env } = buildMirrorPushInvocation(
+  if (useSsh && !token) {
+    warn(
+      `mirror: GITHUB_BOT_TOKEN not set; SSH push to ${githubRepo} will proceed but stamp/verified statuses will be skipped`
+    );
+  }
+  const { args, env } = useSsh ? buildMirrorPushInvocationSsh(
     githubRepo,
     newSha,
     refname,
-    token
-  );
+    process.env,
+    // sshKeyPath is null for legacy (no override) or a string for
+    // per-repo (override via GIT_SSH_COMMAND). The builder ignores
+    // null/undefined and emits no override; passes through strings.
+    sshKeyPath ?? void 0
+  ) : buildMirrorPushInvocation(githubRepo, newSha, refname, token);
   const result = (0, import_node_child_process.spawnSync)("git", args, {
     encoding: "utf8",
     stdio: ["ignore", "pipe", "pipe"],
@@ -7621,16 +7694,25 @@ async function mirrorRef(label, refname, oldSha, newSha, githubRepo) {
     info(
       `mirror: pushed ${label} (${newSha.slice(0, 8)}) \u2192 github.com/${githubRepo}`
     );
-    await postStatuses(label, refname, oldSha, newSha, githubRepo, token);
+    if (token) {
+      await postStatuses(label, refname, oldSha, newSha, githubRepo, token);
+    }
   } else {
     const errOut = scrubTokenUrls((result.stderr ?? "").trim());
     warn(
       `mirror: push of ${label} to github.com/${githubRepo} failed (exit ${result.status})`
     );
     if (errOut) warn(`mirror: ${errOut.replace(/\n/g, "\nmirror: ")}`);
-    warn(
-      `mirror: stamp-server push already accepted; mirror out-of-sync. Retry manually with the bot token in env: GITHUB_BOT_TOKEN=<pat> GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: Basic $(printf '%s' "x-access-token:$GITHUB_BOT_TOKEN" | base64 | tr -d '\\n')" git push https://github.com/${githubRepo}.git ${refname}`
-    );
+    if (useSsh) {
+      const keyHint = sshKeyPath !== null && sshKeyPath !== void 0 ? `GIT_SSH_COMMAND="ssh -F /dev/null -i ${sshKeyPath} -o IdentitiesOnly=yes -o UserKnownHostsFile=/etc/ssh/ssh_known_hosts -o StrictHostKeyChecking=yes" ` : "";
+      warn(
+        `mirror: stamp-server push already accepted; mirror out-of-sync. Retry manually from a host with the deploy key: ${keyHint}git push git@github.com:${githubRepo}.git ${newSha}:${refname}`
+      );
+    } else {
+      warn(
+        `mirror: stamp-server push already accepted; mirror out-of-sync. Retry manually with the bot token in env: GITHUB_BOT_TOKEN=<pat> GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: Basic $(printf '%s' "x-access-token:$GITHUB_BOT_TOKEN" | base64 | tr -d '\\n')" git push https://github.com/${githubRepo}.git ${refname}`
+      );
+    }
   }
 }
 async function postStatuses(label, refname, oldSha, newSha, githubRepo, token) {