next-issue 1.0.0 → 1.0.1

package/README.md

@@ -7,13 +7,6 @@ the Claude Agent SDK. Run it inside a git repository.
 npx -y next-issue@latest
 ```
 
-Or install it once:
-
-```bash
-npm install -g next-issue@latest
-next-issue
-```
-
 ## What it does
 
 For each open issue, oldest first:
@@ -34,11 +27,16 @@ For each open issue, oldest first:
    writes a `base.behind` event. A new branch then starts from the remote base.
 4. Let the implementer agent do the work, then commit and push. When a git
    hook stops a commit, the agent that made the change gets the hook output,
-   fixes it, and the harness commits again. The budget is `maxCommitFixes`.
-5. Open a draft pull request that closes the issue.
+   fixes it, and the harness commits again. A `commit:` line in the reply of
+   the agent replaces the subject, so a hook that rejects the subject can pass.
+   The budget is `maxCommitFixes`.
+5. Open a draft pull request that closes the issue. Its title is the subject
+   of the commit that starts it, so a squash merge gives a conventional
+   commit.
 6. Wait for the checks, once the pull request shows the pushed commit. A
    pending state waits again, up to `checkTimeoutMinutes`. A read that fails
-   is tried three times before the run stops. A repository that reports no
+   is tried three times before the run stops. A watch that exits with an error
+   while no check failed counts as such a read, not as a red build. 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. The later
    gates of the same issue ask once.
@@ -61,16 +59,16 @@ For each open issue, oldest first:
 10. No open finding means approval: mark the pull request ready for review and
     set `status:done`. The merge stays with you, unless you pass `--merge`:
     then the harness squash-merges the pull request, deletes the remote
-    branch and waits for the checks that the merge commit starts on the base
-    branch. A cancelled run there is no failure. When those checks fail, the
-    fixer gets their logs on a branch reset to the base branch, from the check
-    budget, and the harness reopens the issue and opens a new pull request that
-    goes to step 6 again, with fresh review rounds. The next issue waits for
-    this, and a second ctrl-c stops only after it. The worktree, the local
-    branch and the state file go away. Without `--merge`, the remote branch
-    stays. A problem that the
-    reviewer leaves out of the findings thus gets an approval: only the findings
-    count.
+    branch, waits until the pull request is merged, for example through a
+    merge queue, and then waits for the checks that the merge commit starts on
+    the base branch. A cancelled run there is no failure. When those checks
+    fail, the fixer gets their logs on a branch reset to the base branch, from
+    the check budget, and the harness reopens the issue and opens a new pull
+    request that goes to step 6 again, with fresh review rounds. The next
+    issue waits for this, and a second ctrl-c stops only after it. The
+    worktree, the local branch and the state file go away. Without `--merge`,
+    the remote branch stays. A problem that the reviewer leaves out of the
+    findings thus gets an approval: only the findings count.
 11. With an open finding, run the fixer agent and go to step 6 again. The
     budget is `maxReviewRounds`. A fixer that holds every finding to be wrong
     changes nothing and gives its reason instead. The reason goes on the pull
@@ -102,6 +100,8 @@ when:
 - the reviewer gives no verdict, or the checks do not finish in time;
 - with `--merge`, the merge of an approved pull request fails, for example
    because branch protection asks for a human approval;
+- with `--merge`, a queued merge does not finish in `checkTimeoutMinutes`, or
+   the pull request closes without a merge;
 - with `--merge`, the checks on the base branch fail after the merge and the
    fixer cannot fix them, or they do not finish in time. The base branch is
    then broken, so the run stops after this issue;
@@ -151,8 +151,8 @@ and a `status:needs-human` pull request shows work that waits for a person.
 The harness runs all git and `gh` commands itself. The commit holds all the
 changes in the worktree, so a setup command that writes a file outside
 `.gitignore` puts that file in the commit. The reviewer is the one agent whose
-changes never get that far: the harness discards them before it reads the
-verdict.
+changes never get that far: the harness discards them, and undoes any commit
+that the reviewer made, before it reads the verdict.
 
 ## Safety
 
@@ -319,7 +319,8 @@ A `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.
+run stopped. A state file that is not valid JSON gives the issue an `error`
+outcome that names the file, rather than a silent skip.
 
 ## Retry an issue that waits for a person
 
@@ -374,6 +375,7 @@ The workflow then bumps the version and publishes the package to npm with a
 [trusted publish](https://docs.npmjs.com/trusted-publishers), so no token is
 stored. Only after the publish does it push the tag and make the GitHub release,
 so a failed publish leaves no half-release behind. A manual run of the workflow
-publishes the version in `package.json` and changes nothing else, which repairs
-a release that reached GitHub but not npm. The release job stays on a
-GitHub runner, because npm takes provenance only from a GitHub runner.
+checks out the last tag and publishes that commit under the tag version, and
+changes nothing else. This repairs a release that reached GitHub but not npm.
+The release job stays on a GitHub runner, because npm takes provenance only
+from a GitHub runner.

package/dist/agents.mjs

@@ -1,5 +1,7 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { setTimeout as delay } from "node:timers/promises";
 import { track } from "./exec.mjs";
 import { emptyUsage } from "./observe.mjs";
 const REVIEWING = {
@@ -12,6 +14,8 @@ const CODING = {
     allowDangerouslySkipPermissions: true,
 };
 export { CODING, REVIEWING };
+const STDERR_TAIL = 2000;
+const STDERR_GRACE_MS = 500;
 export async function runAgent(recorder, request) {
     const log = recorder.scope({ role: request.name });
     const usage = emptyUsage();
@@ -23,6 +27,8 @@ export async function runAgent(recorder, request) {
     let model = request.model;
     let sessionId;
     let structured;
+    let stderr = "";
+    let stderrClosed = Promise.resolve();
     const started = Date.now();
     log.event("agent.start", { model: request.model, timeoutMs: request.timeoutMs }, "normal");
     const controller = new AbortController();
@@ -42,7 +48,14 @@ export async function runAgent(recorder, request) {
                 allowDangerouslySkipPermissions: request.profile.allowDangerouslySkipPermissions,
                 systemPrompt: { type: "preset", preset: "claude_code" },
                 abortController: controller,
-                spawnClaudeCodeProcess: spawnClaude,
+                pathToClaudeCodeExecutable: request.executable,
+                spawnClaudeCodeProcess: (options) => {
+                    const child = spawnClaude(options, (chunk) => {
+                        stderr = (stderr + chunk).slice(-STDERR_TAIL);
+                    });
+                    stderrClosed = once(child.stderr, "close").catch(() => undefined);
+                    return child;
+                },
                 outputFormat: request.outputSchema === undefined
                     ? undefined
                     : { type: "json_schema", schema: request.outputSchema },
@@ -101,7 +114,11 @@ export async function runAgent(recorder, request) {
         }
     }
     catch (error) {
-        throw controller.signal.aborted ? late() : error;
+        if (controller.signal.aborted) {
+            throw late();
+        }
+        await Promise.race([stderrClosed, delay(STDERR_GRACE_MS, undefined, { ref: false })]);
+        throw withStderr(error, stderr);
     }
     finally {
         clearTimeout(timer);
@@ -147,14 +164,23 @@ export function toolFields(name, input) {
     const { command } = input;
     return typeof command === "string" ? { tool: name, command } : { tool: name };
 }
-export function spawnClaude(options) {
+export function withStderr(error, stderr) {
+    const tail = stderr.trim();
+    if (tail.length === 0 || !(error instanceof Error)) {
+        return error;
+    }
+    return new Error(`${error.message}\nClaude CLI stderr:\n${tail}`, { cause: error });
+}
+export function spawnClaude(options, onStderr = () => undefined) {
     const child = spawn(options.command, options.args, {
         cwd: options.cwd,
         env: options.env,
         signal: options.signal,
         detached: true,
-        stdio: ["pipe", "pipe", "ignore"],
+        stdio: ["pipe", "pipe", "pipe"],
     });
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", onStderr);
     track(child);
     return child;
 }

package/dist/git.mjs

@@ -100,11 +100,11 @@ export async function commitAll(cwd, message) {
     await must("git", ["commit", "-m", message], { cwd });
     return true;
 }
-export async function discardChanges(cwd) {
-    if (!(await isDirty(cwd))) {
+export async function discardChanges(cwd, target) {
+    if (!(await isDirty(cwd)) && (await revision(cwd)) === target) {
         return false;
     }
-    await must("git", ["reset", "--hard", "HEAD"], { cwd });
+    await must("git", ["reset", "--hard", target], { cwd });
     await must("git", ["clean", "-fd"], { cwd });
     return true;
 }

package/dist/github.mjs

@@ -168,7 +168,11 @@ async function watchOnce(repo, branch, intervalSeconds, timeoutMs, show) {
     if (watch.code === CHECK_PENDING_CODE) {
         return "pending";
     }
-    return "fail";
+    const checks = await readChecks(repo, branch);
+    if (checks !== "none" && checks.some((check) => check.bucket === "fail")) {
+        return "fail";
+    }
+    throw new Error(`gh pr checks ${branch} --watch failed with code ${watch.code} and no check failed: ${watch.stderr.trim()}`);
 }
 const REAL_CLOCK = {
     now: () => Date.now(),
@@ -293,8 +297,20 @@ export async function mergePr(repo, pr) {
     const result = await run("gh", ["pr", "merge", String(pr), "--squash", "--delete-branch", "--repo", slug(repo)], { cwd: repo.root });
     return result.code === 0;
 }
-export async function mergeCommit(repo, pr) {
-    return gh(repo, ["pr", "view", String(pr), "--json", "mergeCommit", "--jq", ".mergeCommit.oid"]);
+export async function mergeCommit(repo, pr, options, clock = REAL_CLOCK) {
+    const deadline = clock.now() + options.timeoutMs;
+    for (;;) {
+        const raw = await gh(repo, ["pr", "view", String(pr), "--json", "state,mergeCommit"]);
+        const view = JSON.parse(raw);
+        if (view.state === "MERGED" && view.mergeCommit?.oid) {
+            return view.mergeCommit.oid;
+        }
+        const rest = deadline - clock.now();
+        if (view.state === "CLOSED" || rest <= 0) {
+            return undefined;
+        }
+        await clock.sleep(Math.min(options.intervalSeconds * 1000, rest));
+    }
 }
 export async function reopenIssue(repo, issue) {
     await gh(repo, ["issue", "reopen", String(issue)]);

package/dist/pipeline.mjs

@@ -58,7 +58,14 @@ export function skipReason(issue, config, resuming) {
 export async function processIssue(context, issue) {
     const started = Date.now();
     const log = context.recorder.scope({ issue: issue.number });
-    const saved = await readState(context.repo, issue.number);
+    let saved;
+    try {
+        saved = await readState(context.repo, issue.number);
+    }
+    catch (error) {
+        log.event("issue.error", { error: message(error), ms: Date.now() - started }, "quiet");
+        return { ...skipped(issue), outcome: "error", reason: message(error), ms: Date.now() - started };
+    }
     const skip = skipReason(issue, context.config, saved !== undefined);
     if (skip !== undefined) {
         log.event("issue.skip", { title: issue.title, reason: skip });
@@ -204,7 +211,7 @@ async function openPr(job) {
     const pr = await log.step("pull-request", { branch }, async () => {
         const existing = await ports.findPr(repo, branch);
         return (existing ??
-            ports.createPr(repo, branch, context.base, issue.title, `Closes #${issue.number}\n\nOpened by next-issue.`, config.draftPullRequest));
+            ports.createPr(repo, branch, context.base, state.title ?? `fix: resolve issue #${issue.number}`, `Closes #${issue.number}\n\nOpened by next-issue.`, config.draftPullRequest));
     });
     state.pr = pr;
     await writeState(repo, state);
@@ -269,6 +276,7 @@ async function reviewRound(job) {
         diffChars: full.length,
         cut: full.length > config.diffMaxChars,
     };
+    const before = await ports.revision(worktree);
     const review = await log.step("review", fields, () => ports.runAgent(log, {
         name: "reviewer",
         cwd: worktree,
@@ -278,7 +286,7 @@ async function reviewRound(job) {
         timeoutMs: config.agentTimeoutMinutes * 60_000,
         outputSchema: VERDICT_SCHEMA,
     }));
-    if (await ports.discardChanges(worktree)) {
+    if (await ports.discardChanges(worktree, before)) {
         log.event("review.discard", { round: state.reviewRounds }, "quiet");
     }
     const verdict = readVerdict(review.structured);
@@ -351,7 +359,14 @@ async function reviewRound(job) {
 async function watchBase(job) {
     const { context, issue, log, state, worktree } = job;
     const { repo, config, ports } = context;
-    const sha = await ports.mergeCommit(repo, state.pr);
+    const sha = await ports.mergeCommit(repo, state.pr, {
+        intervalSeconds: config.checkIntervalSeconds,
+        timeoutMs: config.checkTimeoutMinutes * 60_000,
+    });
+    if (sha === undefined) {
+        await escalate(job, "The pull request did not merge in time, or it closed without a merge.");
+        return { done: true, report: await finish(job, "needs-human", "not merged") };
+    }
     const checks = await log.step("main-checks", { pr: state.pr, sha }, () => ports.waitForBaseChecks(repo, sha, {
         intervalSeconds: config.checkIntervalSeconds,
         graceMs: config.checkGraceSeconds * 1000,
@@ -462,7 +477,11 @@ async function commitWork(job, before, subject, role) {
             if (await ports.commitAll(worktree, `${subject}\n\nRefs #${issue.number}`)) {
                 log.event("commit", { subject });
             }
-            return (await ports.revision(worktree)) !== before;
+            if ((await ports.revision(worktree)) === before) {
+                return false;
+            }
+            state.title = subject;
+            return true;
         }
         catch (error) {
             const used = state.commitFixes ?? 0;
@@ -473,7 +492,7 @@ async function commitWork(job, before, subject, role) {
             await writeState(repo, state);
             const output = message(error).slice(-config.logMaxChars);
             log.event("commit.fail", { role, output }, "quiet");
-            await log.step("commit-fix", { role }, () => ports.runAgent(log, {
+            const fix = await log.step("commit-fix", { role }, () => ports.runAgent(log, {
                 name: role,
                 cwd: worktree,
                 prompt: hookPrompt(issue, comments, role, output),
@@ -481,6 +500,7 @@ async function commitWork(job, before, subject, role) {
                 model: config.models[role],
                 timeoutMs: config.agentTimeoutMinutes * 60_000,
             }));
+            subject = parseCommitSubject(fix.text, subject);
         }
     }
 }

package/dist/prompts.mjs

@@ -95,12 +95,12 @@ export function fixPrompt(issue, reason, detail, earlier, kind) {
         .join("\n\n");
 }
 export function parseUnrelated(text) {
-    const match = /^unrelated:\s*(.+)$/im.exec(text);
+    const match = [...text.matchAll(/^unrelated:\s*(.+)$/gim)].at(-1);
     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 match = [...text.matchAll(/^commit:\s*(.+)$/gim)].at(-1);
     const subject = match?.[1]
         ?.trim()
         .replace(/^`+|`+$/g, "")

package/dist/state.mjs

@@ -8,11 +8,22 @@ function file(repo, issue) {
     return join(dir(repo), `${issue}.json`);
 }
 export async function readState(repo, issue) {
+    const path = file(repo, issue);
+    let text;
     try {
-        return JSON.parse(await readFile(file(repo, issue), "utf8"));
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        return JSON.parse(text);
     }
     catch {
-        return undefined;
+        throw new Error(`the state file ${path} is not valid JSON`);
     }
 }
 export function resetState(state) {

package/package.json

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