dunstan 0.1.10 → 0.1.11

package/README.md

@@ -29,7 +29,7 @@ report a pull request's handback before it says done ([`plugins/dunstan/`](plugi
 /plugin install dunstan@barglabs
 ```
 
-The plugin runs the MCP server with `npx -y dunstan@0.1.10 mcp`, the `dunstan` npm package at that
+The plugin runs the MCP server with `npx -y dunstan@0.1.11 mcp`, the `dunstan` npm package at that
 exact version: one self-contained file, no dependencies.
 
 **The token.** When you enable the plugin, Claude Code asks for an optional GitHub token and keeps it
@@ -76,7 +76,9 @@ dist/dunstan.mjs verify record.json   # offline: recompute claims, verdict and d
 dist/dunstan.mjs rerun record.json    # online: re-read the sources, report evidence_changed
 ```
 
-Exit codes: 0 pass, 1 fail, 2 unverifiable, 3 usage or internal error (`verify`: 0 verified, 1 not).
+Exit codes: 0 pass, 1 fail, 2 unverifiable, 3 no record: a usage error, a pull request that cannot
+be read or that moved while it was checked and again when checked once more (`pull_request_moved`),
+or an internal error (`verify`: 0 verified, 1 not).
 `--sign-key <path> --signer <principal>` writes the record as its JCS bytes with a detached SSH
 signature; `verify --sig <file> --allowed-signers <file>` checks it.
 
@@ -87,6 +89,13 @@ agent calls with its block before it says done, beside `dunstan_suggest_declarat
 `checker.digest` in a record is the SHA-256 of `dist/dunstan.mjs`, the single-file bundle that ran:
 the checker code, its dependencies and both schemas from `spec/schema/`, inlined at build time.
 
+## What Dunstan does not check
+
+Dunstan checks the claims a handback declares against the record. It does not check that the
+handback covers what the issue asked for: an accurate report of the wrong work passes.
+
+What to declare: [`docs/agents.md`](docs/agents.md#the-instruction-block).
+
 ## Declare before done
 
 Checking a declared claim is exact. Finding the claims in prose is where readers fail: a hosted

package/dist/dunstan.mjs

@@ -8030,7 +8030,7 @@ import { readFileSync as readFileSync7 } from "node:fs";
 import { createHash } from "node:crypto";
 
 // src/spec/constants.ts
-var SPEC_VERSION = "0.1.6";
+var SPEC_VERSION = "0.1.7";
 var BLOCK_VERSION = "0.1";
 var SUPPORTED_BLOCK_VERSIONS = [BLOCK_VERSION];
 var BLOCK_INFO_STRING = "dunstan-handback";
@@ -8589,17 +8589,32 @@ function later(a, b) {
   if ((a.runAttempt ?? 0) !== (b.runAttempt ?? 0)) return (a.runAttempt ?? 0) > (b.runAttempt ?? 0);
   return a.id > b.id;
 }
+function identity(run) {
+  if (run.workflowPath !== void 0)
+    return JSON.stringify(["workflow", run.workflowPath, run.name]);
+  if (run.appSlug === "github-actions") return void 0;
+  if (run.appSlug !== void 0) return JSON.stringify(["app", run.appSlug, run.name]);
+  if (run.checkSuiteId === void 0) return JSON.stringify(["name", run.name]);
+  return void 0;
+}
 function countedCheckRuns(runs, excludedIds) {
   const excluded = new Set(excludedIds);
   const checker = /* @__PURE__ */ new Map();
   const latest = /* @__PURE__ */ new Map();
   for (const run of runs) {
-    if (excluded.has(run.id)) checker.set(run.name, Math.max(checker.get(run.name) ?? 0, run.id));
+    const id = identity(run);
+    if (excluded.has(run.id) && id !== void 0) {
+      checker.set(id, Math.max(checker.get(id) ?? 0, run.id));
+    }
     const key = checkKey(run);
     const seen = latest.get(key);
     if (seen === void 0 || later(run, seen)) latest.set(key, run);
   }
-  return [...latest.values()].filter((run) => !excluded.has(run.id) && run.id > (checker.get(run.name) ?? 0)).sort((a, b) => a.id - b.id);
+  const superseded = (run) => {
+    const id = identity(run);
+    return id !== void 0 && run.id < (checker.get(id) ?? 0);
+  };
+  return [...latest.values()].filter((run) => !excluded.has(run.id) && !superseded(run)).sort((a, b) => a.id - b.id);
 }
 var NOT_FAILED_CONCLUSIONS = ["success", "skipped", "neutral"];
 function booleanRow(field, declared, reason, runs, failed, mismatch, unsettled) {
@@ -8921,6 +8936,14 @@ var PullRequestUnreadable = class extends Error {
     this.name = "PullRequestUnreadable";
   }
 };
+var PullRequestMoved = class extends Error {
+  constructor(repository, number4, moves) {
+    super(
+      `pull request ${repository}#${number4} moved while it was checked, and again when it was checked once more (${moves.join(", ")}); no record is written (pull_request_moved)`
+    );
+    this.name = "PullRequestMoved";
+  }
+};
 var ShapeError = class extends Error {
 };
 function obj(value) {
@@ -8959,8 +8982,12 @@ function timestamp(value) {
 function second(t) {
   return t.slice(0, 19);
 }
-async function readPullRequest(client, repository, number4) {
-  const read = await client.read("pull_request", `/repos/${repository}/pulls/${number4}`);
+async function readPullRequest(client, repository, number4, options = {}) {
+  const read = await client.read(
+    "pull_request",
+    `/repos/${repository}/pulls/${number4}`,
+    options.record === false ? { record: false } : {}
+  );
   if (!read.ok) {
     throw new PullRequestUnreadable(
       `cannot read pull request ${repository}#${number4} (${read.error}); no record is written`
@@ -8972,6 +8999,7 @@ async function readPullRequest(client, repository, number4) {
     const state = str(pr.state);
     if (state !== "open" && state !== "closed") throw new ShapeError();
     const base = obj(obj(pr.base).repo);
+    const baseRef = str(obj(pr.base).ref);
     return {
       evidence: {
         status: "ok",
@@ -8985,6 +9013,7 @@ async function readPullRequest(client, repository, number4) {
         changedFiles: int(pr.changed_files)
       },
       repository: str(base.full_name),
+      baseRef,
       body: strOrNull(pr.body)
     };
   } catch (e) {
@@ -8996,6 +9025,20 @@ async function readPullRequest(client, repository, number4) {
     throw e;
   }
 }
+function pullRequestMoves(first, again) {
+  const state = (pr) => pr.evidence.merged ? "merged" : pr.evidence.state;
+  const pairs = [
+    ["head", first.evidence.headSha, again.evidence.headSha],
+    ["base", first.baseRef, again.baseRef],
+    ["state", state(first), state(again)],
+    ["repository", first.repository, again.repository],
+    ["mergedAt", first.evidence.mergedAt, again.evidence.mergedAt],
+    ["mergeSha", first.evidence.mergeSha, again.evidence.mergeSha],
+    ["changedFiles", first.evidence.changedFiles, again.evidence.changedFiles],
+    ["number", first.evidence.number, again.evidence.number]
+  ];
+  return pairs.filter(([, a, b]) => a !== b).map(([name, a, b]) => `${name} ${a} -> ${b}`);
+}
 async function readAllPages(client, kind, pathFor, itemsOf, map2, options = {}) {
   const out = [];
   for (let page = 1; page <= MAX_PAGES; page++) {
@@ -9775,7 +9818,7 @@ async function reportFromComment(client, repository, number4, login) {
 // src/record/checker.ts
 import { readFileSync } from "node:fs";
 var CHECKER_NAME = "dunstan";
-var CHECKER_VERSION = "0.1.10";
+var CHECKER_VERSION = "0.1.11";
 function checkerIdentity(artifact) {
   return {
     name: CHECKER_NAME,
@@ -10748,6 +10791,8 @@ import { parseArgs } from "node:util";
 
 // src/evidence/http.ts
 var DEFAULT_API = "https://api.github.com";
+var MAX_ARCHIVE_BYTES = MAX_ENTRY_BYTES + 8 * 1024 * 1024;
+var MAX_BODY_BYTES = 48 * 1024 * 1024;
 var EMPTY = new Uint8Array();
 var GitHubClient = class {
   sources = /* @__PURE__ */ new Map();
@@ -10784,10 +10829,19 @@ var GitHubClient = class {
   async read(kind, path, options = {}) {
     const method = options.method ?? "GET";
     const locator = options.locator ?? `${method} ${path}${options.locatorSuffix ?? ""}`;
-    const result = await this.#fetchWithRetry(method, path, options.requestBody, locator);
+    const budget = kind === "artifact" ? MAX_ARCHIVE_BYTES : MAX_BODY_BYTES;
+    const result = await this.#fetchWithRetry(method, path, options.requestBody, locator, budget);
     let read;
     if (result.kind === "network") {
       read = { ok: false, status: null, error: "network", body: EMPTY };
+    } else if (result.body === null) {
+      const failed = result.status < 200 || result.status > 299;
+      read = {
+        ok: false,
+        status: result.status,
+        error: failed ? `http_${result.status}` : "parse",
+        body: EMPTY
+      };
     } else if (result.status < 200 || result.status > 299) {
       read = {
         ok: false,
@@ -10824,7 +10878,7 @@ var GitHubClient = class {
     const source = this.sources.get(locator);
     if (source !== void 0) source.error = "parse";
   }
-  async #fetchWithRetry(method, path, body, locator) {
+  async #fetchWithRetry(method, path, body, locator, budget) {
     const headers = {
       accept: "application/vnd.github+json",
       "x-github-api-version": "2022-11-28",
@@ -10849,10 +10903,10 @@ var GitHubClient = class {
         this.#warn(`${locator}: network error after ${attempt} attempts (${e.message})`);
         return { kind: "network" };
       }
-      const bytes = new Uint8Array(await response.arrayBuffer());
       const status = response.status;
       const wait = retryWaitMs(response, status, this.#now(), attempt);
       if (wait !== void 0 && attempt < this.#maxAttempts && wait <= this.#maxWaitMs) {
+        await cancel(response.body);
         await this.#sleep(wait);
         continue;
       }
@@ -10860,10 +10914,48 @@ var GitHubClient = class {
         const why = wait > this.#maxWaitMs ? `rate limited for ${Math.ceil(wait / 1e3)}s` : `${attempt} attempts`;
         this.#warn(`${locator}: giving up with HTTP ${status} (${why}); recorded as unreadable`);
       }
+      const bytes = await readWithin(response, budget);
+      if (bytes === null) {
+        this.#warn(
+          `${locator}: answer over ${budget} bytes, not read in full; recorded as unreadable`
+        );
+      }
       return { kind: "response", status, body: bytes, etag: response.headers.get("etag") };
     }
   }
 };
+async function cancel(body) {
+  await body?.cancel().catch(() => {
+  });
+}
+async function readWithin(response, budget) {
+  const length = response.headers.get("content-length");
+  if (length !== null && /^[0-9]+$/.test(length) && Number(length) > budget) {
+    await cancel(response.body);
+    return null;
+  }
+  if (response.body === null) return EMPTY;
+  const reader = response.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+    size += chunk.value.length;
+    if (size > budget) {
+      await reader.cancel().catch(() => {
+      });
+      return null;
+    }
+    chunks.push(chunk.value);
+  }
+  if (chunks.length === 1) return chunks[0];
+  const bytes = new Uint8Array(size);
+  let at = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, at);
+    at += chunk.length;
+  }
+  return bytes;
+}
 function backoffMs(attempt) {
   return Math.min(1e3 * 2 ** (attempt - 1), 8e3);
 }
@@ -13094,13 +13186,34 @@ function serializeRecord(record2) {
 // src/pipeline/check-pull-request.ts
 function githubReaders(client) {
   return {
-    pullRequest: (repository, number4) => readPullRequest(client, repository, number4),
+    pullRequest: (repository, number4, options) => readPullRequest(client, repository, number4, options),
     evidence: (input2) => readEvidence(client, input2),
-    pathObjects: (input2) => readPathObjects(client, input2)
+    pathObjects: (input2) => readPathObjects(client, input2),
+    restart: () => client.sources.clear()
   };
 }
+async function atOnePullRequest(readers, repository, number4, first, collect) {
+  let pr = first ?? await readers.pullRequest(repository, number4);
+  for (let run = 1; ; run++) {
+    const collected = await collect(pr);
+    const again = await readers.pullRequest(repository, number4, { record: false });
+    const moves = pullRequestMoves(pr, again);
+    if (moves.length === 0) return collected;
+    if (run === 2) throw new PullRequestMoved(repository, number4, moves);
+    readers.restart?.();
+    pr = await readers.pullRequest(repository, number4);
+  }
+}
 async function checkPullRequest(input2) {
-  const pr = input2.pullRequest ?? await input2.readers.pullRequest(input2.repository, input2.number);
+  return atOnePullRequest(
+    input2.readers,
+    input2.repository,
+    input2.number,
+    input2.pullRequest,
+    (pr) => checkAt(input2, pr)
+  );
+}
+async function checkAt(input2, pr) {
   const repository = pr.repository;
   const ownRuns = await input2.afterPullRequest?.(pr) ?? [];
   const report = await input2.report(pr);
@@ -40734,7 +40847,7 @@ var Protocol = class {
           }
         };
       }
-      const cancel = (reason) => {
+      const cancel2 = (reason) => {
         this._responseHandlers.delete(messageId);
         this._progressHandlers.delete(messageId);
         this._cleanupTimeout(messageId);
@@ -40768,10 +40881,10 @@ var Protocol = class {
         }
       });
       options?.signal?.addEventListener("abort", () => {
-        cancel(options?.signal?.reason);
+        cancel2(options?.signal?.reason);
       });
       const timeout = options?.timeout ?? DEFAULT_REQUEST_TIMEOUT_MSEC;
-      const timeoutHandler = () => cancel(McpError.fromError(ErrorCode.RequestTimeout, "Request timed out", { timeout }));
+      const timeoutHandler = () => cancel2(McpError.fromError(ErrorCode.RequestTimeout, "Request timed out", { timeout }));
       this._setupTimeout(messageId, timeout, options?.maxTotalTimeout, timeoutHandler, options?.resetTimeoutOnProgress ?? false);
       const relatedTaskId = relatedTask?.taskId;
       if (relatedTaskId) {
@@ -42966,7 +43079,7 @@ function handbackResult(record2, outPath, notes) {
   };
 }
 function toolError(error62) {
-  const known = error62 instanceof InputError || error62 instanceof PullRequestUnreadable || error62 instanceof CanonicalizationError || typeof error62.code === "string";
+  const known = error62 instanceof InputError || error62 instanceof PullRequestUnreadable || error62 instanceof PullRequestMoved || error62 instanceof CanonicalizationError || typeof error62.code === "string";
   const message = error62.message ?? String(error62);
   return {
     isError: true,
@@ -43105,14 +43218,20 @@ async function rerun(args, io) {
     warn: (message) => io.err(`dunstan: ${message}
 `)
   });
-  const pr = await readPullRequest(client, old.subject.repository, old.subject.pullRequest);
   const oldExcluded = old.evidence.checkRuns?.status === "ok" ? old.evidence.checkRuns.excludedIds : [];
-  const evidence = await readEvidence(client, {
-    repository: old.subject.repository,
-    pullRequest: pr,
-    block: old.block.status === "found" ? old.block.value : null,
-    excludedCheckRunIds: [...oldExcluded, ...parseCheckRunIds(values["exclude-check-run"])]
-  });
+  const excluded = [...oldExcluded, ...parseCheckRunIds(values["exclude-check-run"])];
+  const evidence = await atOnePullRequest(
+    githubReaders(client),
+    old.subject.repository,
+    old.subject.pullRequest,
+    void 0,
+    (pr) => readEvidence(client, {
+      repository: old.subject.repository,
+      pullRequest: pr,
+      block: old.block.status === "found" ? old.block.value : null,
+      excludedCheckRunIds: excluded
+    })
+  );
   const record2 = buildRecord({
     checker: checkerIdentity(io.artifact),
     report: old.report,
@@ -43473,7 +43592,7 @@ async function main(argv, io) {
       io.err(`dunstan: ${e.message}
 
 ${USAGE}`);
-    } else if (e instanceof PullRequestUnreadable || e instanceof ReportUnavailable || e instanceof TemplateError) {
+    } else if (e instanceof PullRequestUnreadable || e instanceof PullRequestMoved || e instanceof ReportUnavailable || e instanceof TemplateError) {
       io.err(`dunstan: ${e.message}
 `);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dunstan",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "mcpName": "io.github.BargLabs/dunstan",
   "description": "Holds a coding agent's completion report to the record: deterministic checks of a declared handback block against the repository's own metadata.",
   "license": "AGPL-3.0-only",