next-issue 0.6.0 → 0.8.0

package/README.md

@@ -29,15 +29,17 @@ For each open issue, oldest first:
 4. Let the implementer agent do the work, then commit and push.
 5. Open a draft pull request that closes the issue.
 6. Wait for the checks. A pending state waits again, up to
-   `checkTimeoutMinutes`. A repository without checks goes straight to the
-   review.
+   `checkTimeoutMinutes`. A repository that reports no check keeps asking for
+   `checkGraceSeconds`, because a new pull request often shows no check yet,
+   and only then goes straight to the review.
 7. On a red build, give the failed job logs to the fixer agent, then go to step
    6 again. The budget is `maxCiFixes`.
-8. Let the reviewer agent judge the diff. The reviewer returns a structured
-   verdict that rates each finding `blocking` or `minor`. The harness puts the
-   result on the pull request.
+8. Let the reviewer agent judge the diff, at most `diffMaxChars` of it. The
+   reviewer returns a structured verdict that rates each finding `blocking` or
+   `minor`. The harness puts the result on the pull request.
 9. No blocking finding means approval: mark the pull request ready for review
-   and set `status:done`. The merge stays with you.
+   and set `status:done`. The merge stays with you. A blocking finding always
+   stops the approval, even when the reviewer also says approve.
 10. With a blocking finding, run the fixer agent and go to step 6 again. The
     budget is `maxReviewRounds`.
 
@@ -48,9 +50,15 @@ when:
 
 - the check budget or the review budget runs out;
 - a fixer round adds no commit, so there is no progress;
+- the fixer reports that the checks fail for a reason the change did not cause,
+   such as a test already broken on the base branch or one that fails only under
+   load. It changes nothing and the reason reaches the pull request, rather than
+   the fixer spending its whole budget on a failure it cannot fix;
 - the reviewer repeats a finding set from an earlier round, which shows a
    ping-pong between the fixer and the reviewer;
 - the reviewer gives no verdict, or the checks do not finish in time;
+- an agent does not finish in `agentTimeoutMinutes`;
+- the setup command fails, or does not finish in `setupTimeoutMinutes`;
 - a step of the run fails with an error.
 
 The fixer sees the findings of all earlier rounds, not only the last one. From
@@ -78,8 +86,9 @@ command that writes a file outside `.gitignore` puts that file in the commit.
 
 ## Safety
 
-The implementer and the fixer run with the permission checks off. They can run
-any command in the worktree. The prompt holds the title, the body and the
+The implementer and the fixer run with the permission checks off. They start in
+the worktree, but nothing holds them there: they can run any command, with your
+rights, anywhere on the machine. The prompt holds the title, the body and the
 comments of the issue, which come from GitHub.
 
 Thus a person who can write an issue or a comment can try to give an
@@ -144,7 +153,8 @@ already; `--force` replaces it. The file holds no `setupCommand`, because that
 field has no default.
 
 A field that is not in the file keeps its default. A file that is not valid
-JSON stops the run.
+JSON, a field with a value of the wrong type and a field name that the harness
+does not know all stop the run, so a typo cannot pass without a word.
 
 ```json
 {
@@ -153,15 +163,15 @@ JSON stops the run.
   "maxCiFixes": 3,
   "maxReviewRounds": 3,
   "checkIntervalSeconds": 15,
+  "checkGraceSeconds": 60,
   "checkTimeoutMinutes": 60,
+  "agentTimeoutMinutes": 30,
+  "setupTimeoutMinutes": 15,
+  "commandTimeoutMinutes": 10,
   "logMaxChars": 20000,
+  "diffMaxChars": 60000,
   "draftPullRequest": true,
-  "setupCommand": "npm ci",
-  "models": {
-    "implementer": "claude-opus-5",
-    "reviewer": "claude-opus-5",
-    "fixer": "claude-opus-5"
-  },
+  "models": {},
   "labels": {
     "ready": "status:todo",
     "inProgress": "status:in-progress",
@@ -180,8 +190,13 @@ JSON stops the run.
 | `maxCiFixes` | `3` | The budget for check fixes per issue |
 | `maxReviewRounds` | `3` | The budget for review rounds per issue |
 | `checkIntervalSeconds` | `15` | The time between two check states |
+| `checkGraceSeconds` | `60` | The time to wait for the first check to show |
 | `checkTimeoutMinutes` | `60` | The limit for one check wait |
+| `agentTimeoutMinutes` | `30` | The limit for one agent call |
+| `setupTimeoutMinutes` | `15` | The limit for the setup command |
+| `commandTimeoutMinutes` | `10` | The limit for one `git` or `gh` command |
 | `logMaxChars` | `20000` | The maximum length of the failed job logs |
+| `diffMaxChars` | `60000` | The maximum length of the diff that the reviewer reads |
 | `draftPullRequest` | `true` | Open the pull request as a draft, until the review approves |
 | `setupCommand` | none | A shell command to run in a new worktree, before the implementer |
 | `models` | `{}` | The model per agent role |
@@ -191,12 +206,22 @@ An empty `labels.ready` turns the ready requirement off. The harness then
 claims every open issue that no other label and no assignee holds back.
 
 The log gives the reason for a skipped issue as `stop-label`, `not-ready`,
-`in-flight` or `assigned`. `--issue` obeys the same rules; it only makes the
-harness look at one issue.
+`in-flight` or `assigned`.
 
 A role without an entry in `models` uses the default model of the SDK. A
-`setupCommand` that fails hands the issue to a person. State per issue goes to
-`.next-issue/<issue>.json`, so a new run continues where the last run stopped.
+`setupCommand` that fails, or that does not finish in `setupTimeoutMinutes`,
+hands the issue to a person. The wait for the checks has its own limit, so
+`commandTimeoutMinutes` holds for every other `git` and `gh` command. State per
+issue goes to `.next-issue/<issue>.json`, so a new run continues where the last
+run stopped.
+
+## Retry an issue that waits for a person
+
+A hand-over leaves the state file with the used budgets in it, so the next run
+would hand the issue over again at once. To give the issue another try, take the
+`status:needs-human` label off and run with `--reset`. The flag puts the budgets
+and the findings back to zero and keeps the branch, the pull request and the
+step that the last run reached, so the work carries on where it stopped.
 
 ## Commands and options
 
@@ -204,10 +229,9 @@ A role without an entry in `models` uses the default model of the SDK. A
 | --- | --- |
 | `init` | Write the config file with the defaults |
 | `--force` | Replace an existing config file, with `init` |
-| `--issue <n>` | Handle one issue only |
 | `--once` | Stop after the first handled issue |
 | `--max <n>` | Handle at most n issues |
-| `--reset` | Drop the saved budgets and findings first |
+| `--reset` | Drop the saved budgets and findings, and keep the rest of the state |
 | `--json` | Print the machine summary instead of the text one |
 | `--verbose` | Show every command and all agent output |
 | `--quiet` | Show only the milestones and the summary |

package/dist/agents.mjs

@@ -22,73 +22,90 @@ export async function runAgent(recorder, request) {
     let sessionId;
     let structured;
     const started = Date.now();
-    log.event("agent.start", { model: request.model }, "normal");
-    const stream = query({
-        prompt: request.prompt,
-        options: {
-            cwd: request.cwd,
-            model: request.model,
-            tools: request.profile.tools,
-            allowedTools: request.profile.tools,
-            permissionMode: request.profile.permissionMode,
-            allowDangerouslySkipPermissions: request.profile.allowDangerouslySkipPermissions,
-            systemPrompt: { type: "preset", preset: "claude_code" },
-            outputFormat: request.outputSchema === undefined
-                ? undefined
-                : { type: "json_schema", schema: request.outputSchema },
-        },
-    });
-    for await (const message of stream) {
-        if (message.type === "assistant") {
-            for (const block of message.message.content) {
-                if (block.type === "tool_use") {
-                    toolCalls += 1;
-                    toolNames.set(block.id, block.name);
-                    log.event("tool", toolFields(block.name, block.input));
-                }
-                if (block.type === "text") {
-                    text += block.text;
-                    if (log.level === "verbose") {
-                        process.stderr.write(block.text);
+    log.event("agent.start", { model: request.model, timeoutMs: request.timeoutMs }, "normal");
+    const controller = new AbortController();
+    const timer = request.timeoutMs === undefined
+        ? undefined
+        : setTimeout(() => controller.abort(), request.timeoutMs);
+    const late = () => new Error(`The ${request.name} agent did not finish in ${request.timeoutMs} ms.`);
+    try {
+        const stream = query({
+            prompt: request.prompt,
+            options: {
+                cwd: request.cwd,
+                model: request.model,
+                tools: request.profile.tools,
+                allowedTools: request.profile.tools,
+                permissionMode: request.profile.permissionMode,
+                allowDangerouslySkipPermissions: request.profile.allowDangerouslySkipPermissions,
+                systemPrompt: { type: "preset", preset: "claude_code" },
+                abortController: controller,
+                outputFormat: request.outputSchema === undefined
+                    ? undefined
+                    : { type: "json_schema", schema: request.outputSchema },
+            },
+        });
+        for await (const message of stream) {
+            if (message.type === "assistant") {
+                for (const block of message.message.content) {
+                    if (block.type === "tool_use") {
+                        toolCalls += 1;
+                        toolNames.set(block.id, block.name);
+                        log.event("tool", toolFields(block.name, block.input));
+                    }
+                    if (block.type === "text") {
+                        text += block.text;
+                        if (log.level === "verbose") {
+                            process.stderr.write(block.text);
+                        }
                     }
                 }
             }
-        }
-        if (message.type === "user" && Array.isArray(message.message.content)) {
-            for (const block of message.message.content) {
-                if (block.type === "tool_result" && block.is_error === true) {
-                    log.event("tool.error", { tool: toolNames.get(block.tool_use_id) }, "quiet");
+            if (message.type === "user" && Array.isArray(message.message.content)) {
+                for (const block of message.message.content) {
+                    if (block.type === "tool_result" && block.is_error === true) {
+                        log.event("tool.error", { tool: toolNames.get(block.tool_use_id) }, "quiet");
+                    }
                 }
             }
-        }
-        if (message.type === "result") {
-            sessionId = message.session_id;
-            turns = message.num_turns;
-            costUsd = message.total_cost_usd;
-            model = main(message.modelUsage) ?? model;
-            for (const entry of Object.values(message.modelUsage)) {
-                usage.input += entry.inputTokens;
-                usage.output += entry.outputTokens;
-                usage.cacheRead += entry.cacheReadInputTokens;
-                usage.cacheWrite += entry.cacheCreationInputTokens;
-                usage.total +=
-                    entry.inputTokens +
-                        entry.outputTokens +
-                        entry.cacheReadInputTokens +
-                        entry.cacheCreationInputTokens;
-            }
-            if (message.subtype === "error_during_execution") {
-                throw new Error(`The ${request.name} agent failed: ${message.errors.join("; ")}`);
-            }
-            if (message.subtype === "success") {
-                text = message.result.length > 0 ? message.result : text;
-                structured = message.structured_output;
-            }
-            else {
-                log.event("agent.incomplete", { subtype: message.subtype }, "quiet");
+            if (message.type === "result") {
+                sessionId = message.session_id;
+                turns = message.num_turns;
+                costUsd = message.total_cost_usd;
+                model = main(message.modelUsage) ?? model;
+                for (const entry of Object.values(message.modelUsage)) {
+                    usage.input += entry.inputTokens;
+                    usage.output += entry.outputTokens;
+                    usage.cacheRead += entry.cacheReadInputTokens;
+                    usage.cacheWrite += entry.cacheCreationInputTokens;
+                    usage.total +=
+                        entry.inputTokens +
+                            entry.outputTokens +
+                            entry.cacheReadInputTokens +
+                            entry.cacheCreationInputTokens;
+                }
+                if (message.subtype === "error_during_execution") {
+                    throw new Error(`The ${request.name} agent failed: ${message.errors.join("; ")}`);
+                }
+                if (message.subtype === "success") {
+                    text = message.result.length > 0 ? message.result : text;
+                    structured = message.structured_output;
+                }
+                else {
+                    log.event("agent.incomplete", { subtype: message.subtype }, "quiet");
+                }
             }
         }
     }
+    catch (error) {
+        throw controller.signal.aborted ? late() : error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (controller.signal.aborted) {
+        throw late();
+    }
     const ms = Date.now() - started;
     recorder.usage(request.name, usage, ms, {
         turns,

package/dist/args.mjs

@@ -3,7 +3,6 @@ export const USAGE = `next-issue [command] [options]
 
   init         write ${CONFIG_FILE} with the defaults
 
-  --issue <n>  handle one issue only
   --once       stop after the first handled issue
   --max <n>    handle at most n issues
   --reset      drop the saved budgets and findings first
@@ -52,9 +51,6 @@ export function parseArgs(argv) {
         else if (arg === "--quiet") {
             args.level = "quiet";
         }
-        else if (arg === "--issue") {
-            args.issue = whole(argv[++index], arg);
-        }
         else if (arg === "--max") {
             args.max = whole(argv[++index], arg);
         }

package/dist/cli.mjs

@@ -3,12 +3,12 @@ import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parseArgs, USAGE } from "./args.mjs";
 import { loadConfig, writeDefaultConfig } from "./config.mjs";
-import { setCommandObserver } from "./exec.mjs";
+import { setCommandObserver, setDefaultTimeout } from "./exec.mjs";
 import { detectRepo, ensureIgnored, repoRoot } from "./git.mjs";
 import { currentLogin, defaultBranch, openIssues } from "./github.mjs";
 import { message, Recorder } from "./observe.mjs";
-import { processIssue } from "./pipeline.mjs";
-import { clearState, STATE_DIR, takeStop } from "./state.mjs";
+import { PORTS, processIssue } from "./pipeline.mjs";
+import { resetState, STATE_DIR, takeStop } from "./state.mjs";
 import { formatSummary } from "./summary.mjs";
 function write(stream, text) {
     return new Promise((resolve, reject) => {
@@ -26,6 +26,7 @@ async function main() {
         return init(root, args.force);
     }
     const config = await loadConfig(root);
+    setDefaultTimeout(config.commandTimeoutMinutes * 60_000);
     const repo = await detectRepo(root, config.remote);
     const recorder = await Recorder.create(repo.root, args.level);
     setCommandObserver((record) => {
@@ -34,6 +35,7 @@ async function main() {
             code: record.code,
             ms: record.ms,
             stderr: record.stderr.length > 0 ? record.stderr : undefined,
+            timedOut: record.timedOut ? true : undefined,
         }, record.code === 0 ? "verbose" : "quiet");
     });
     try {
@@ -53,9 +55,9 @@ async function init(root, force) {
 }
 async function handle(args, config, repo, recorder) {
     const [base, login] = await Promise.all([defaultBranch(repo), currentLogin(repo)]);
-    const context = { repo, config, base, login, recorder };
+    const context = { repo, config, base, login, recorder, ports: PORTS };
     recorder.event("run.start", { repo: `${repo.owner}/${repo.name}`, base, login, log: recorder.logFile }, "quiet");
-    const issues = (await openIssues(repo, config.issueLimit)).filter((issue) => args.issue === undefined || issue.number === args.issue);
+    const issues = await openIssues(repo, config.issueLimit);
     recorder.event("issues", { open: issues.length }, "quiet");
     await takeStop(repo);
     const reports = [];
@@ -65,7 +67,7 @@ async function handle(args, config, repo, recorder) {
             break;
         }
         if (args.reset) {
-            await clearState(repo, issue.number);
+            await resetState(repo, issue.number);
         }
         const report = await processIssue(context, issue);
         reports.push(report);

package/dist/config.mjs

@@ -7,8 +7,13 @@ const DEFAULTS = {
     maxCiFixes: 3,
     maxReviewRounds: 3,
     checkIntervalSeconds: 15,
+    checkGraceSeconds: 60,
     checkTimeoutMinutes: 60,
+    agentTimeoutMinutes: 30,
+    setupTimeoutMinutes: 15,
+    commandTimeoutMinutes: 10,
     logMaxChars: 20000,
+    diffMaxChars: 60000,
     draftPullRequest: true,
     models: {},
     labels: {
@@ -20,6 +25,22 @@ const DEFAULTS = {
         skip: "status:blocked",
     },
 };
+const FIELDS = [...Object.keys(DEFAULTS), "setupCommand"];
+const WHOLE_FIELDS = [
+    ["issueLimit", 1],
+    ["maxCiFixes", 0],
+    ["maxReviewRounds", 1],
+    ["checkIntervalSeconds", 1],
+    ["checkGraceSeconds", 0],
+    ["checkTimeoutMinutes", 1],
+    ["agentTimeoutMinutes", 1],
+    ["setupTimeoutMinutes", 1],
+    ["commandTimeoutMinutes", 1],
+    ["logMaxChars", 1],
+    ["diffMaxChars", 1],
+];
+const MODEL_ROLES = ["implementer", "reviewer", "fixer"];
+const LABEL_NAMES = ["ready", "inProgress", "inReview", "done", "needsHuman", "skip"];
 export const CONFIG_FILE = "next-issue.config.json";
 export async function writeDefaultConfig(root, force) {
     const path = join(root, CONFIG_FILE);
@@ -49,12 +70,82 @@ export async function loadConfig(root) {
     catch (error) {
         throw new Error(`${CONFIG_FILE} is not valid JSON: ${message(error)}`);
     }
-    return {
+    return parseConfig(parsed);
+}
+export function parseConfig(value) {
+    const file = record(value, "the file");
+    for (const key of Object.keys(file)) {
+        if (!FIELDS.includes(key)) {
+            throw new Error(`${CONFIG_FILE} holds an unknown field: ${key}`);
+        }
+    }
+    const config = {
         ...DEFAULTS,
-        ...parsed,
-        models: { ...DEFAULTS.models, ...parsed.models },
-        labels: { ...DEFAULTS.labels, ...parsed.labels },
+        models: { ...DEFAULTS.models },
+        labels: { ...DEFAULTS.labels },
     };
+    if (file.remote !== undefined) {
+        config.remote = text(file.remote, "remote", false);
+    }
+    for (const [field, least] of WHOLE_FIELDS) {
+        if (file[field] !== undefined) {
+            config[field] = whole(file[field], field, least);
+        }
+    }
+    if (file.draftPullRequest !== undefined) {
+        if (typeof file.draftPullRequest !== "boolean") {
+            throw new Error(`${CONFIG_FILE}: draftPullRequest must be true or false.`);
+        }
+        config.draftPullRequest = file.draftPullRequest;
+    }
+    if (file.setupCommand !== undefined) {
+        config.setupCommand = text(file.setupCommand, "setupCommand", false);
+    }
+    if (file.models !== undefined) {
+        const models = record(file.models, "models");
+        for (const key of Object.keys(models)) {
+            if (!MODEL_ROLES.includes(key)) {
+                throw new Error(`${CONFIG_FILE} holds an unknown model role: ${key}`);
+            }
+        }
+        for (const role of MODEL_ROLES) {
+            if (models[role] !== undefined) {
+                config.models[role] = text(models[role], `models.${role}`, false);
+            }
+        }
+    }
+    if (file.labels !== undefined) {
+        const labels = record(file.labels, "labels");
+        for (const key of Object.keys(labels)) {
+            if (!LABEL_NAMES.includes(key)) {
+                throw new Error(`${CONFIG_FILE} holds an unknown label name: ${key}`);
+            }
+        }
+        for (const name of LABEL_NAMES) {
+            if (labels[name] !== undefined) {
+                config.labels[name] = text(labels[name], `labels.${name}`, name === "ready");
+            }
+        }
+    }
+    return config;
+}
+function record(value, what) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${CONFIG_FILE}: ${what} must be an object.`);
+    }
+    return value;
+}
+function whole(value, field, least) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < least) {
+        throw new Error(`${CONFIG_FILE}: ${field} must be a whole number of ${least} or more.`);
+    }
+    return value;
+}
+function text(value, field, allowEmpty) {
+    if (typeof value !== "string" || (!allowEmpty && value.length === 0)) {
+        throw new Error(`${CONFIG_FILE}: ${field} must be ${allowEmpty ? "text" : "text that is not empty"}.`);
+    }
+    return value;
 }
 export function managedLabels(config) {
     return [

package/dist/exec.mjs

@@ -1,10 +1,15 @@
 import { spawn } from "node:child_process";
 let observer;
+let defaultTimeoutMs = 10 * 60_000;
 export function setCommandObserver(next) {
     observer = next;
 }
+export function setDefaultTimeout(ms) {
+    defaultTimeoutMs = ms;
+}
 export function run(command, args, options = {}) {
     const started = Date.now();
+    const limit = options.timeoutMs ?? defaultTimeoutMs;
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, {
             cwd: options.cwd,
@@ -21,22 +26,29 @@ export function run(command, args, options = {}) {
         child.stderr?.setEncoding("utf8");
         child.stdout?.on("data", (chunk) => {
             stdout += chunk;
+            if (options.tailChars !== undefined && stdout.length > options.tailChars) {
+                stdout = stdout.slice(-options.tailChars);
+            }
         });
         child.stderr?.on("data", (chunk) => {
             stderr += chunk;
         });
-        const timer = options.timeoutMs === undefined
-            ? undefined
-            : setTimeout(() => {
-                timedOut = true;
-                child.kill("SIGKILL");
-            }, options.timeoutMs);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, limit);
+        let done = false;
         child.on("error", (error) => {
             clearTimeout(timer);
+            done = true;
             reject(error);
         });
         child.on("close", (code) => {
             clearTimeout(timer);
+            if (done) {
+                return;
+            }
+            done = true;
             const result = { code: code ?? 1, stdout, stderr, timedOut };
             observer?.({
                 command,
@@ -45,6 +57,7 @@ export function run(command, args, options = {}) {
                 code: result.code,
                 ms: Date.now() - started,
                 stderr: result.code === 0 ? "" : stderr.trim(),
+                timedOut,
             });
             resolve(result);
         });
@@ -56,6 +69,9 @@ export function run(command, args, options = {}) {
 }
 export async function must(command, args, options = {}) {
     const result = await run(command, args, options);
+    if (result.timedOut) {
+        throw new Error(`${command} ${args.join(" ")} did not finish in time.`);
+    }
     if (result.code !== 0) {
         throw new Error(`${command} ${args.join(" ")} failed with code ${result.code}: ${result.stderr.trim()}`);
     }

package/dist/git.mjs

@@ -36,7 +36,9 @@ export async function addWorktree(repo, issue, base, remote) {
     if (await hasWorktree(repo, path)) {
         return path;
     }
-    const existing = await run("git", ["rev-parse", "--verify", branch], { cwd: repo.root });
+    const existing = await run("git", ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], {
+        cwd: repo.root,
+    });
     const args = existing.code === 0
         ? ["worktree", "add", path, branch]
         : ["worktree", "add", "-b", branch, path, `${remote}/${base}`];
@@ -45,12 +47,11 @@ export async function addWorktree(repo, issue, base, remote) {
 }
 export async function updateBase(repo, base, remote) {
     const head = await run("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: repo.root });
-    if (head.code === 0 && head.stdout.trim() === base) {
-        const merge = await run("git", ["merge", "--ff-only", `${remote}/${base}`], { cwd: repo.root });
-        return merge.code === 0;
-    }
-    const fetch = await run("git", ["fetch", remote, `${base}:${base}`], { cwd: repo.root });
-    return fetch.code === 0;
+    const args = head.code === 0 && head.stdout.trim() === base
+        ? ["merge", "--ff-only", `${remote}/${base}`]
+        : ["fetch", ".", `${remote}/${base}:${base}`];
+    const result = await run("git", args, { cwd: repo.root });
+    return result.code === 0;
 }
 export async function hasWorktree(repo, path) {
     const list = await must("git", ["worktree", "list", "--porcelain"], { cwd: repo.root });

package/dist/github.mjs

@@ -107,8 +107,8 @@ async function readChecks(repo, branch) {
     const checks = JSON.parse(output);
     return checks.length === 0 ? "none" : checks;
 }
-async function watchOnce(repo, branch, intervalSeconds, timeoutMs) {
-    const watch = await run("gh", ["pr", "checks", branch, "--watch", "--fail-fast", "--interval", String(intervalSeconds), "--repo", slug(repo)], { cwd: repo.root, inherit: true, timeoutMs });
+async function watchOnce(repo, branch, intervalSeconds, timeoutMs, inherit) {
+    const watch = await run("gh", ["pr", "checks", branch, "--watch", "--fail-fast", "--interval", String(intervalSeconds), "--repo", slug(repo)], { cwd: repo.root, inherit, timeoutMs });
     if (watch.timedOut) {
         return "timeout";
     }
@@ -120,22 +120,37 @@ async function watchOnce(repo, branch, intervalSeconds, timeoutMs) {
     }
     return "fail";
 }
-export async function waitForChecks(repo, branch, intervalSeconds, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
-        if ((await readChecks(repo, branch)) === "none") {
-            return "none";
+const REAL_CLOCK = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};
+export async function pollChecks(probe, options, clock = REAL_CLOCK) {
+    const started = clock.now();
+    const deadline = started + options.timeoutMs;
+    const rest = () => Math.max(0, deadline - clock.now());
+    for (;;) {
+        if (rest() === 0) {
+            return "timeout";
+        }
+        if ((await probe.list()) === "none") {
+            if (clock.now() - started >= options.graceMs) {
+                return "none";
+            }
         }
-        const state = await watchOnce(repo, branch, intervalSeconds, deadline - Date.now());
-        if (state !== "pending") {
-            return state;
+        else {
+            const state = await probe.watch(rest());
+            if (state !== "pending") {
+                return state;
+            }
         }
-        await delay(intervalSeconds * 1000);
+        await clock.sleep(Math.min(options.intervalSeconds * 1000, rest()));
     }
-    return "timeout";
 }
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+export function waitForChecks(repo, branch, options) {
+    return pollChecks({
+        list: async () => ((await readChecks(repo, branch)) === "none" ? "none" : "some"),
+        watch: (timeoutMs) => watchOnce(repo, branch, options.intervalSeconds, timeoutMs, options.inherit),
+    }, options);
 }
 export async function failedCheckLogs(repo, branch, maxChars) {
     const checks = await readChecks(repo, branch);
@@ -152,6 +167,7 @@ export async function failedCheckLogs(repo, branch, maxChars) {
         }
         const logs = await run("gh", ["run", "view", runId, "--log-failed", "--repo", slug(repo)], {
             cwd: repo.root,
+            tailChars: maxChars,
         });
         parts.push(logs.stdout.slice(-maxChars));
     }

package/dist/pipeline.mjs

@@ -4,9 +4,28 @@ import { run } from "./exec.mjs";
 import { addWorktree, branchName, commitAll, diff, hasWorktree, push, removeWorktree, worktreePath, } from "./git.mjs";
 import { assignIssue, commentOnPr, createPr, failedCheckLogs, findPr, issueComments, markPrReady, setLabel, waitForChecks, } from "./github.mjs";
 import { message } from "./observe.mjs";
-import { fixPrompt, implementPrompt, parseCommitSubject, reviewPrompt } from "./prompts.mjs";
+import { capDiff, fixPrompt, implementPrompt, parseCommitSubject, parseUnrelated, reviewPrompt, } from "./prompts.mjs";
 import { readState, writeState } from "./state.mjs";
 import { blockingFindings, fingerprint, formatFindings, formatVerdict, isApproved, readVerdict, VERDICT_SCHEMA, } from "./verdict.mjs";
+export const PORTS = {
+    addWorktree,
+    assignIssue,
+    commentOnPr,
+    commitAll,
+    createPr,
+    diff,
+    failedCheckLogs,
+    findPr,
+    hasWorktree,
+    issueComments,
+    markPrReady,
+    push,
+    removeWorktree,
+    runAgent,
+    runSetup: async (command, cwd, timeoutMs) => run("bash", ["-lc", command], { cwd, timeoutMs }),
+    setLabel,
+    waitForChecks,
+};
 export function skipReason(issue, config, login, resuming) {
     const labels = new Set(issue.labels);
     const names = config.labels;
@@ -69,15 +88,15 @@ export async function processIssue(context, issue) {
 }
 async function work(context, issue, log, state) {
     const started = Date.now();
-    const { repo, config } = context;
+    const { repo, config, ports } = context;
     const branch = state.branch;
     await log.step("claim", { label: config.labels.inProgress }, async () => {
-        await assignIssue(repo, issue.number, context.login);
+        await ports.assignIssue(repo, issue.number, context.login);
         await setStatus(context, issue.number, state.pr, config.labels.inProgress);
         await writeState(repo, state);
     });
-    const comments = await log.step("comments", {}, () => issueComments(repo, issue.number));
-    const worktree = await log.step("worktree", { branch }, () => addWorktree(repo, issue.number, context.base, config.remote));
+    const comments = await log.step("comments", {}, () => ports.issueComments(repo, issue.number));
+    const worktree = await log.step("worktree", { branch }, () => ports.addWorktree(repo, issue.number, context.base, config.remote));
     const job = { context, issue, log, state, branch, worktree, comments };
     const escalate = (reason) => handOver(context, log, issue.number, state, reason);
     const finish = async (outcome, reason) => {
@@ -93,23 +112,27 @@ async function work(context, issue, log, state) {
         };
     };
     if (config.setupCommand !== undefined) {
-        const setup = await log.step("setup", { cmd: config.setupCommand }, () => run("bash", ["-lc", config.setupCommand], { cwd: worktree }));
+        const setup = await log.step("setup", { cmd: config.setupCommand }, () => ports.runSetup(config.setupCommand, worktree, config.setupTimeoutMinutes * 60_000));
         if (setup.code !== 0) {
-            log.event("setup.fail", { code: setup.code, stderr: setup.stderr.trim().slice(-2000) }, "quiet");
-            await escalate("The setup command failed in the worktree.");
-            return finish("needs-human", "setup failed");
+            const late = setup.timedOut === true;
+            log.event("setup.fail", { code: setup.code, timedOut: late, stderr: setup.stderr.trim().slice(-2000) }, "quiet");
+            await escalate(late
+                ? `The setup command did not finish in ${config.setupTimeoutMinutes} minutes.`
+                : "The setup command failed in the worktree.");
+            return finish("needs-human", late ? "setup timeout" : "setup failed");
         }
     }
     if (state.phase === "claimed") {
-        const result = await log.step("implement", {}, () => runAgent(log, {
+        const result = await log.step("implement", {}, () => ports.runAgent(log, {
             name: "implementer",
             cwd: worktree,
             prompt: implementPrompt(issue, comments),
             profile: CODING,
             model: config.models.implementer,
+            timeoutMs: config.agentTimeoutMinutes * 60_000,
         }));
         const subject = parseCommitSubject(result.text, `fix: resolve issue #${issue.number}`);
-        if (!(await commitAll(worktree, `${subject}\n\nRefs #${issue.number}`))) {
+        if (!(await ports.commitAll(worktree, `${subject}\n\nRefs #${issue.number}`))) {
             await escalate("The implementer produced no change.");
             return finish("needs-human", "no implementation commit");
         }
@@ -117,36 +140,57 @@ async function work(context, issue, log, state) {
         state.phase = "implemented";
         await writeState(repo, state);
     }
-    await log.step("push", { branch }, () => push(worktree, config.remote, branch));
+    await log.step("push", { branch }, () => ports.push(worktree, config.remote, branch));
     state.pr = await log.step("pull-request", { branch }, async () => {
-        const existing = await findPr(repo, branch);
+        const existing = await ports.findPr(repo, branch);
         return (existing ??
-            createPr(repo, branch, context.base, issue.title, `Closes #${issue.number}\n\nOpened by next-issue.`, config.draftPullRequest));
+            ports.createPr(repo, branch, context.base, issue.title, `Closes #${issue.number}\n\nOpened by next-issue.`, config.draftPullRequest));
     });
     state.phase = "review";
     await writeState(repo, state);
     log.event("pull-request.ready", { pr: state.pr }, "quiet");
-    for (;;) {
-        const checks = await log.step("checks", { pr: state.pr }, () => waitForChecks(repo, branch, config.checkIntervalSeconds, config.checkTimeoutMinutes * 60_000));
+    const gate = async () => {
+        const checks = await log.step("checks", { pr: state.pr }, () => ports.waitForChecks(repo, branch, {
+            intervalSeconds: config.checkIntervalSeconds,
+            graceMs: config.checkGraceSeconds * 1000,
+            timeoutMs: config.checkTimeoutMinutes * 60_000,
+            inherit: log.level === "verbose",
+        }));
         log.event("checks.state", { state: checks });
         if (checks === "timeout") {
             await escalate("The checks did not finish in time.");
-            return finish("needs-human", "checks timeout");
+            return { done: true, report: await finish("needs-human", "checks timeout") };
         }
-        if (checks === "fail") {
-            if (state.ciFixes >= config.maxCiFixes) {
-                await escalate(`The limit of ${config.maxCiFixes} check fixes was reached.`);
-                return finish("needs-human", "check budget");
-            }
-            state.ciFixes += 1;
-            await writeState(repo, state);
-            const logs = await failedCheckLogs(repo, branch, config.logMaxChars);
-            log.event("checks.logs", { chars: logs.length });
-            const committed = await fixRound(job, "The continuous integration checks failed.", logs);
-            if (!committed) {
-                await escalate("The fixer added no commit for the failed checks.");
-                return finish("needs-human", "no fix commit");
-            }
+        if (checks !== "fail") {
+            return { done: false, fixed: false };
+        }
+        if (state.ciFixes >= config.maxCiFixes) {
+            await escalate(`The limit of ${config.maxCiFixes} check fixes was reached.`);
+            return { done: true, report: await finish("needs-human", "check budget") };
+        }
+        state.ciFixes += 1;
+        await writeState(repo, state);
+        const logs = await ports.failedCheckLogs(repo, branch, config.logMaxChars);
+        log.event("checks.logs", { chars: logs.length });
+        const fix = await fixRound(job, "The continuous integration checks failed.", logs, history(state.reviewLog), "checks");
+        if (!fix.committed) {
+            const note = fix.unrelated;
+            await escalate(note === undefined
+                ? "The fixer added no commit for the failed checks."
+                : `The checks fail for a reason this change did not cause: ${note}`);
+            return {
+                done: true,
+                report: await finish("needs-human", note === undefined ? "no fix commit" : "unrelated failure"),
+            };
+        }
+        return { done: false, fixed: true };
+    };
+    for (;;) {
+        const before = await gate();
+        if (before.done) {
+            return before.report;
+        }
+        if (before.fixed) {
             continue;
         }
         if (state.reviewRounds >= config.maxReviewRounds) {
@@ -156,13 +200,20 @@ async function work(context, issue, log, state) {
         state.reviewRounds += 1;
         await writeState(repo, state);
         await setStatus(context, issue.number, state.pr, config.labels.inReview);
-        const patch = await diff(worktree, context.base, config.remote);
-        const review = await log.step("review", { round: state.reviewRounds, diffChars: patch.length }, () => runAgent(log, {
+        const full = await ports.diff(worktree, context.base, config.remote);
+        const patch = capDiff(full, config.diffMaxChars);
+        const fields = {
+            round: state.reviewRounds,
+            diffChars: full.length,
+            cut: full.length > config.diffMaxChars,
+        };
+        const review = await log.step("review", fields, () => ports.runAgent(log, {
             name: "reviewer",
             cwd: worktree,
             prompt: reviewPrompt(issue, comments, patch, state.reviewRounds, history(state.reviewLog)),
             profile: READ_ONLY,
             model: config.models.reviewer,
+            timeoutMs: config.agentTimeoutMinutes * 60_000,
             outputSchema: VERDICT_SCHEMA,
         }));
         const verdict = readVerdict(review.structured);
@@ -178,9 +229,16 @@ async function work(context, issue, log, state) {
             minor: verdict.findings.length - blocking.length,
             summary: verdict.summary,
         }, "quiet");
-        await commentOnPr(repo, state.pr, formatVerdict(verdict));
+        await ports.commentOnPr(repo, state.pr, formatVerdict(verdict));
         if (isApproved(verdict)) {
-            if (config.draftPullRequest && !(await markPrReady(repo, state.pr))) {
+            const after = await gate();
+            if (after.done) {
+                return after.report;
+            }
+            if (after.fixed) {
+                continue;
+            }
+            if (config.draftPullRequest && !(await ports.markPrReady(repo, state.pr))) {
                 log.event("pull-request.undraft.fail", { pr: state.pr }, "quiet");
             }
             await setStatus(context, issue.number, state.pr, config.labels.done);
@@ -196,38 +254,45 @@ async function work(context, issue, log, state) {
         const earlier = history(state.reviewLog);
         state.reviewLog.push({ round: state.reviewRounds, fingerprint: mark, findings: formatFindings(blocking) });
         await writeState(repo, state);
-        const committed = await fixRound(job, "The reviewer requested changes.", formatFindings(blocking), earlier);
-        if (!committed) {
+        const fix = await fixRound(job, "The reviewer requested changes.", formatFindings(blocking), earlier, "review");
+        if (!fix.committed) {
             await escalate("The fixer added no commit for the review findings.");
             return finish("needs-human", "no fix commit");
         }
     }
 }
-async function fixRound(job, reason, detail, earlier = []) {
+async function fixRound(job, reason, detail, earlier, kind) {
     const { context, issue, log, worktree, branch } = job;
-    const result = await log.step("fix", { reason }, () => runAgent(log, {
+    const { ports } = context;
+    const result = await log.step("fix", { reason }, () => ports.runAgent(log, {
         name: "fixer",
         cwd: worktree,
-        prompt: fixPrompt(issue, reason, detail, earlier.length > 0 ? earlier : history(job.state.reviewLog)),
+        prompt: fixPrompt(issue, reason, detail, earlier, kind),
         profile: CODING,
         model: context.config.models.fixer,
+        timeoutMs: context.config.agentTimeoutMinutes * 60_000,
     }));
+    const unrelated = parseUnrelated(result.text);
+    if (unrelated !== undefined) {
+        log.event("fix.unrelated", { reason, note: unrelated }, "quiet");
+        return { committed: false, unrelated };
+    }
     const subject = parseCommitSubject(result.text, `fix: address feedback on issue #${issue.number}`);
-    if (!(await commitAll(worktree, `${subject}\n\nRefs #${issue.number}`))) {
+    if (!(await ports.commitAll(worktree, `${subject}\n\nRefs #${issue.number}`))) {
         log.event("commit.empty", { reason }, "quiet");
-        return false;
+        return { committed: false };
     }
     log.event("commit", { subject });
-    await push(worktree, context.config.remote, branch);
-    return true;
+    await ports.push(worktree, context.config.remote, branch);
+    return { committed: true };
 }
 async function cleanUp(context, log, issue) {
     const path = worktreePath(context.repo, issue);
     try {
-        if (!(await hasWorktree(context.repo, path))) {
+        if (!(await context.ports.hasWorktree(context.repo, path))) {
             return;
         }
-        if (!(await removeWorktree(context.repo, issue))) {
+        if (!(await context.ports.removeWorktree(context.repo, issue))) {
             log.event("worktree.kept", { path }, "quiet");
         }
     }
@@ -237,18 +302,18 @@ async function cleanUp(context, log, issue) {
 }
 async function handOver(context, log, issue, state, reason) {
     log.event("hand-over", { reason }, "quiet");
-    state.phase = "needs-human";
+    state.handedOver = true;
     await writeState(context.repo, state);
     await setStatus(context, issue, state.pr, context.config.labels.needsHuman);
     if (state.pr !== undefined) {
-        await commentOnPr(context.repo, state.pr, `next-issue needs help: ${reason}`);
+        await context.ports.commentOnPr(context.repo, state.pr, `next-issue needs help: ${reason}`);
     }
 }
 async function setStatus(context, issue, pr, label) {
     const managed = managedLabels(context.config);
-    await setLabel(context.repo, "issue", issue, label, managed);
+    await context.ports.setLabel(context.repo, "issue", issue, label, managed);
     if (pr !== undefined) {
-        await setLabel(context.repo, "pr", pr, label, managed);
+        await context.ports.setLabel(context.repo, "pr", pr, label, managed);
     }
 }
 function history(rounds) {

package/dist/prompts.mjs

@@ -21,6 +21,11 @@ export function implementPrompt(issue, comments) {
         COMMIT_RULES,
     ].join("\n\n");
 }
+export function capDiff(diff, maxChars) {
+    return diff.length <= maxChars
+        ? diff
+        : `${diff.slice(0, maxChars)}\n... The diff is cut here, after ${maxChars} characters.`;
+}
 export function reviewPrompt(issue, comments, diff, round, earlier) {
     const scope = round === 1
         ? "Check correctness, scope, repository conventions and test cover."
@@ -44,7 +49,12 @@ export function reviewPrompt(issue, comments, diff, round, earlier) {
         "Give the result as the structured output: the verdict, a short summary and one entry per finding.",
     ].join("\n\n");
 }
-export function fixPrompt(issue, reason, detail, earlier) {
+const UNRELATED_RULE = [
+    "The checks can fail for a reason this change did not cause: a test that is already broken on the base branch, one that exercises code the diff does not touch, or one that fails only under load.",
+    "Establish that before you fix anything. If the failure is not yours, change nothing and end your final message with one line in the form `unrelated: <one sentence on what fails and why it is not this change>`.",
+    "A person then reads it. Do not weaken, skip or re-record a test to make the checks pass.",
+].join("\n");
+export function fixPrompt(issue, reason, detail, earlier, kind) {
     return [
         `You are the fixer. Correct the work for issue #${issue.number}: ${issue.title}.`,
         `## Reason\n${reason}`,
@@ -58,11 +68,17 @@ export function fixPrompt(issue, reason, detail, earlier) {
             : "",
         "## Rules",
         "Fix the cause, not the symptom. Keep the change minimal.",
+        kind === "checks" ? UNRELATED_RULE : "",
         COMMIT_RULES,
     ]
         .filter((part) => part.length > 0)
         .join("\n\n");
 }
+export function parseUnrelated(text) {
+    const match = /^unrelated:\s*(.+)$/im.exec(text);
+    const note = match?.[1]?.trim();
+    return note !== undefined && note.length > 0 ? note : undefined;
+}
 export function parseCommitSubject(text, fallback) {
     const match = /^commit:\s*(.+)$/im.exec(text);
     const subject = match?.[1]?.trim();

package/dist/state.mjs

@@ -15,8 +15,15 @@ export async function readState(repo, issue) {
         return undefined;
     }
 }
-export async function clearState(repo, issue) {
-    await rm(file(repo, issue), { force: true });
+export async function resetState(repo, issue) {
+    const state = await readState(repo, issue);
+    if (state === undefined) {
+        return false;
+    }
+    const next = { ...state, ciFixes: 0, reviewRounds: 0, reviewLog: [] };
+    delete next.handedOver;
+    await writeState(repo, next);
+    return true;
 }
 export async function writeState(repo, state) {
     await mkdir(dir(repo), { recursive: true });

package/dist/verdict.mjs

@@ -26,18 +26,37 @@ export const VERDICT_SCHEMA = {
     },
     required: ["verdict", "summary", "findings"],
 };
+const SEVERITIES = ["blocking", "minor"];
+const VERDICTS = ["approve", "request_changes"];
 export function readVerdict(value) {
-    const verdict = value;
-    if (verdict === undefined || typeof verdict.summary !== "string" || !Array.isArray(verdict.findings)) {
+    if (typeof value !== "object" || value === null) {
         return undefined;
     }
-    return verdict;
+    const { verdict, summary, findings } = value;
+    if (typeof verdict !== "string" || !VERDICTS.includes(verdict)) {
+        return undefined;
+    }
+    if (typeof summary !== "string" || !Array.isArray(findings)) {
+        return undefined;
+    }
+    const checked = [];
+    for (const item of findings) {
+        if (typeof item !== "object" || item === null) {
+            return undefined;
+        }
+        const { severity, detail } = item;
+        if (typeof severity !== "string" || !SEVERITIES.includes(severity) || typeof detail !== "string") {
+            return undefined;
+        }
+        checked.push({ severity: severity, detail });
+    }
+    return { verdict: verdict, summary, findings: checked };
 }
 export function blockingFindings(verdict) {
     return verdict.findings.filter((finding) => finding.severity === "blocking");
 }
 export function isApproved(verdict) {
-    return verdict.verdict === "approve" || blockingFindings(verdict).length === 0;
+    return blockingFindings(verdict).length === 0;
 }
 export function formatVerdict(verdict) {
     const head = isApproved(verdict) ? "Review: approved" : "Review: changes requested";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-issue",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Autonomous issue harness driven by the Claude Agent SDK",
   "keywords": [
     "github",