next-issue 0.8.0 → 0.8.1

package/README.md

@@ -24,22 +24,27 @@ For each open issue, oldest first:
    the claim. An issue with saved state under `.next-issue/` resumes instead,
    whatever its labels, unless another person is now the assignee.
 2. Assign the issue to you and add `status:in-progress`.
-3. Fetch the default branch, fast-forward the local copy of it when that is
-   safe, then add a git worktree on a new `issue-<n>` branch from it.
+3. Fetch the remote, fast-forward the local copy of the default branch when
+   that is safe, then add a git worktree at `../<repo>-issue-<n>` on the
+   `issue-<n>` branch. A branch that exists on the remote is the start, and a
+   local branch that fell behind the remote is fast-forwarded.
 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 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.
+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
+   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.
 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, 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. A blocking finding always
-   stops the approval, even when the reviewer also says approve.
+   and set `status:done`. The merge stays with you. The worktree, the local
+   branch and the state file go away. The remote branch stays. 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`.
 
@@ -110,14 +115,14 @@ A short text summary of the same data goes to standard output. Use `--json` to
 get the full summary object there instead, so the harness fits in a pipe. All
 progress goes to standard error.
 
-Recorded for each step: `claim`, `comments`, `worktree`, `implement`, `push`,
-`pull-request`, `checks`, `review` and `fix`, each with a `.start`, `.end` or
-`.error` event and a duration in `ms`. Every `git` and `gh` command is recorded
-with its exit code and duration. A `tool` event holds the tool name, and for a
-`Bash` tool the command too. Each agent call adds a `usage` event with the
-tokens, the cost estimate in dollars, the turn count, the tool-call count, the
-model and the session id, so you can open the session again and read the full
-transcript.
+Recorded for each step: `claim`, `comments`, `worktree`, `setup`, `implement`,
+`push`, `pull-request`, `checks`, `review` and `fix`, each with a `.start`,
+`.end` or `.error` event and a duration in `ms`. Every `git` and `gh` command
+is recorded with its exit code and duration. A `tool` event holds the tool
+name, and for a `Bash` tool the command too. Each agent call adds a `usage`
+event with the tokens, the cost estimate in dollars, the turn count, the
+tool-call count, the model and the session id, so you can open the session
+again and read the full transcript.
 
 ```bash
 jq -r 'select(.kind=="usage") | [.issue,.role,.turns,.total] | @tsv' \
@@ -134,7 +139,7 @@ Three levels of console output:
 
 ## Requirements
 
-- Node 24 or later, because the command runs the TypeScript source directly
+- Node 24 or later
 - `gh`, authenticated with write access to the repository
 - Anthropic credentials for the Claude Agent SDK: `ANTHROPIC_API_KEY`, or a
   Claude subscription login
@@ -221,7 +226,8 @@ 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.
+step that the last run reached, so the work carries on where it stopped. A
+commit that you pushed to the pull request in the meantime is fetched first.
 
 ## Commands and options
 

package/dist/cli.mjs

@@ -6,6 +6,7 @@ import { loadConfig, writeDefaultConfig } from "./config.mjs";
 import { setCommandObserver, setDefaultTimeout } from "./exec.mjs";
 import { detectRepo, ensureIgnored, repoRoot } from "./git.mjs";
 import { currentLogin, defaultBranch, openIssues } from "./github.mjs";
+import { exitCode, runIssues } from "./loop.mjs";
 import { message, Recorder } from "./observe.mjs";
 import { PORTS, processIssue } from "./pipeline.mjs";
 import { resetState, STATE_DIR, takeStop } from "./state.mjs";
@@ -59,25 +60,14 @@ async function handle(args, config, repo, recorder) {
     recorder.event("run.start", { repo: `${repo.owner}/${repo.name}`, base, login, log: recorder.logFile }, "quiet");
     const issues = await openIssues(repo, config.issueLimit);
     recorder.event("issues", { open: issues.length }, "quiet");
-    await takeStop(repo);
-    const reports = [];
-    for (const issue of issues) {
-        const handled = reports.filter((report) => report.outcome !== "skipped").length;
-        if (args.max !== undefined && handled >= args.max) {
-            break;
-        }
-        if (args.reset) {
-            await resetState(repo, issue.number);
-        }
-        const report = await processIssue(context, issue);
-        reports.push(report);
-        if (await takeStop(repo)) {
-            recorder.event("run.stop", { issue: issue.number }, "quiet");
-            break;
-        }
-        if (args.once && report.outcome !== "skipped") {
-            break;
-        }
+    const { reports, stoppedAt } = await runIssues(args, {
+        issues,
+        process: (issue) => processIssue(context, issue),
+        reset: (issue) => resetState(repo, issue),
+        stop: () => takeStop(repo),
+    });
+    if (stoppedAt !== undefined) {
+        recorder.event("run.stop", { issue: stoppedAt }, "quiet");
     }
     const summary = { ...recorder.summary(), issues: reports };
     recorder.event("run.end", {
@@ -90,7 +80,7 @@ async function handle(args, config, repo, recorder) {
     const summaryFile = join(repo.root, STATE_DIR, "runs", `${recorder.runId}.summary.json`);
     await writeFile(summaryFile, `${JSON.stringify(summary, null, 2)}\n`);
     await write(process.stdout, args.json ? `${JSON.stringify(summary, null, 2)}\n` : formatSummary(summary));
-    return count(reports, "needs-human") + count(reports, "error") > 0 ? 1 : 0;
+    return exitCode(reports);
 }
 function count(reports, outcome) {
     return reports.filter((report) => report.outcome === outcome).length;

package/dist/exec.mjs

@@ -15,7 +15,7 @@ export function run(command, args, options = {}) {
             cwd: options.cwd,
             stdio: [
                 options.input === undefined ? "ignore" : "pipe",
-                options.inherit === true ? "inherit" : "pipe",
+                options.show === true ? 2 : "pipe",
                 "pipe",
             ],
         });

package/dist/git.mjs

@@ -30,21 +30,26 @@ export function worktreePath(repo, issue) {
 export async function addWorktree(repo, issue, base, remote) {
     const path = worktreePath(repo, issue);
     const branch = branchName(issue);
-    await must("git", ["fetch", remote, base], { cwd: repo.root });
+    const upstream = `${remote}/${branch}`;
+    await must("git", ["fetch", remote], { cwd: repo.root });
     await updateBase(repo, base, remote);
     await must("git", ["worktree", "prune"], { cwd: repo.root });
-    if (await hasWorktree(repo, path)) {
-        return path;
+    const pushed = await hasBranch(repo, upstream, "--remotes");
+    if (!(await hasWorktree(repo, path))) {
+        const args = (await hasBranch(repo, branch))
+            ? ["worktree", "add", path, branch]
+            : ["worktree", "add", "-b", branch, path, pushed ? upstream : `${remote}/${base}`];
+        await must("git", args, { cwd: repo.root });
+    }
+    if (pushed) {
+        await run("git", ["merge", "--ff-only", upstream], { cwd: path });
     }
-    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}`];
-    await must("git", args, { cwd: repo.root });
     return path;
 }
+async function hasBranch(repo, name, ...flags) {
+    const list = await must("git", ["branch", "--list", ...flags, name], { cwd: repo.root });
+    return list.length > 0;
+}
 export async function updateBase(repo, base, remote) {
     const head = await run("git", ["symbolic-ref", "--quiet", "--short", "HEAD"], { cwd: repo.root });
     const args = head.code === 0 && head.stdout.trim() === base
@@ -98,3 +103,10 @@ export async function commitAll(cwd, message) {
 export async function push(cwd, remote, branch) {
     await must("git", ["push", "-u", remote, branch], { cwd });
 }
+export async function revision(cwd) {
+    return must("git", ["rev-parse", "HEAD"], { cwd });
+}
+export async function deleteBranch(repo, branch) {
+    const result = await run("git", ["branch", "-D", branch], { cwd: repo.root });
+    return result.code === 0;
+}

package/dist/github.mjs

@@ -1,5 +1,7 @@
 import { must, run } from "./exec.mjs";
 const CHECK_PENDING_CODE = 8;
+const READ_TRIES = 3;
+const KNOWN_LABELS = new Map();
 const NO_CHECKS = /no checks reported/i;
 function slug(repo) {
     return `${repo.owner}/${repo.name}`;
@@ -22,6 +24,8 @@ export async function openIssues(repo, limit) {
         "list",
         "--state",
         "open",
+        "--search",
+        "sort:created-asc",
         "--limit",
         String(limit),
         "--json",
@@ -65,7 +69,17 @@ export async function setLabel(repo, kind, number, add, remove) {
     await gh(repo, [kind, "edit", String(number), ...labelArgs(add, remove, current)]);
 }
 export async function ensureLabel(repo, label) {
+    let known = KNOWN_LABELS.get(slug(repo));
+    if (known === undefined) {
+        const raw = await gh(repo, ["label", "list", "--limit", "1000", "--json", "name"]);
+        known = new Set(JSON.parse(raw).map((item) => item.name));
+        KNOWN_LABELS.set(slug(repo), known);
+    }
+    if (known.has(label)) {
+        return;
+    }
     await run("gh", ["label", "create", label, "--repo", slug(repo)], { cwd: repo.root });
+    known.add(label);
 }
 export async function findPr(repo, branch) {
     const result = await run("gh", ["pr", "list", "--head", branch, "--state", "open", "--json", "number", "--repo", slug(repo)], { cwd: repo.root });
@@ -95,6 +109,9 @@ export async function createPr(repo, branch, base, title, body, draft) {
     }
     return number;
 }
+async function prHead(repo, branch) {
+    return gh(repo, ["pr", "view", branch, "--json", "headRefOid", "--jq", ".headRefOid"]);
+}
 async function readChecks(repo, branch) {
     const result = await run("gh", ["pr", "checks", branch, "--json", "name,bucket,link,description", "--repo", slug(repo)], { cwd: repo.root });
     const output = result.stdout.trim();
@@ -107,8 +124,8 @@ async function readChecks(repo, branch) {
     const checks = JSON.parse(output);
     return checks.length === 0 ? "none" : checks;
 }
-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 });
+async function watchOnce(repo, branch, intervalSeconds, timeoutMs, show) {
+    const watch = await run("gh", ["pr", "checks", branch, "--watch", "--fail-fast", "--interval", String(intervalSeconds), "--repo", slug(repo)], { cwd: repo.root, show, timeoutMs });
     if (watch.timedOut) {
         return "timeout";
     }
@@ -125,31 +142,53 @@ const REAL_CLOCK = {
     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 deadline = clock.now() + options.timeoutMs;
     const rest = () => Math.max(0, deadline - clock.now());
+    let shown;
+    let failures = 0;
     for (;;) {
         if (rest() === 0) {
             return "timeout";
         }
-        if ((await probe.list()) === "none") {
-            if (clock.now() - started >= options.graceMs) {
-                return "none";
+        const state = await read(probe, options.head, rest(), () => (shown ??= clock.now()));
+        if (state instanceof Error) {
+            failures += 1;
+            if (failures >= READ_TRIES) {
+                throw state;
             }
         }
         else {
-            const state = await probe.watch(rest());
-            if (state !== "pending") {
+            failures = 0;
+            if (state === "none" && clock.now() - (shown ?? 0) >= options.graceMs) {
+                return "none";
+            }
+            if (state !== "none" && state !== "behind" && state !== "pending") {
                 return state;
             }
         }
         await clock.sleep(Math.min(options.intervalSeconds * 1000, rest()));
     }
 }
+async function read(probe, head, timeoutMs, shown) {
+    try {
+        if (head !== undefined && (await probe.head()) !== head) {
+            return "behind";
+        }
+        shown();
+        if ((await probe.list()) === "none") {
+            return "none";
+        }
+    }
+    catch (error) {
+        return error instanceof Error ? error : new Error(String(error));
+    }
+    return probe.watch(timeoutMs);
+}
 export function waitForChecks(repo, branch, options) {
     return pollChecks({
+        head: () => prHead(repo, branch),
         list: async () => ((await readChecks(repo, branch)) === "none" ? "none" : "some"),
-        watch: (timeoutMs) => watchOnce(repo, branch, options.intervalSeconds, timeoutMs, options.inherit),
+        watch: (timeoutMs) => watchOnce(repo, branch, options.intervalSeconds, timeoutMs, options.show),
     }, options);
 }
 export async function failedCheckLogs(repo, branch, maxChars) {

package/dist/loop.mjs

@@ -0,0 +1,27 @@
+export async function runIssues(args, loop) {
+    await loop.stop();
+    const reports = [];
+    for (const issue of loop.issues) {
+        if (args.max !== undefined && handled(reports) >= args.max) {
+            break;
+        }
+        if (args.reset) {
+            await loop.reset(issue.number);
+        }
+        const report = await loop.process(issue);
+        reports.push(report);
+        if (await loop.stop()) {
+            return { reports, stoppedAt: issue.number };
+        }
+        if (args.once && report.outcome !== "skipped") {
+            break;
+        }
+    }
+    return { reports };
+}
+export function exitCode(reports) {
+    return reports.some((report) => report.outcome === "needs-human" || report.outcome === "error") ? 1 : 0;
+}
+function handled(reports) {
+    return reports.filter((report) => report.outcome !== "skipped").length;
+}

package/dist/pipeline.mjs

@@ -1,11 +1,11 @@
 import { CODING, READ_ONLY, runAgent } from "./agents.mjs";
 import { managedLabels } from "./config.mjs";
 import { run } from "./exec.mjs";
-import { addWorktree, branchName, commitAll, diff, hasWorktree, push, removeWorktree, worktreePath, } from "./git.mjs";
+import { addWorktree, branchName, commitAll, deleteBranch, diff, hasWorktree, push, removeWorktree, revision, worktreePath, } from "./git.mjs";
 import { assignIssue, commentOnPr, createPr, failedCheckLogs, findPr, issueComments, markPrReady, setLabel, waitForChecks, } from "./github.mjs";
 import { message } from "./observe.mjs";
 import { capDiff, fixPrompt, implementPrompt, parseCommitSubject, parseUnrelated, reviewPrompt, } from "./prompts.mjs";
-import { readState, writeState } from "./state.mjs";
+import { dropState, readState, writeState } from "./state.mjs";
 import { blockingFindings, fingerprint, formatFindings, formatVerdict, isApproved, readVerdict, VERDICT_SCHEMA, } from "./verdict.mjs";
 export const PORTS = {
     addWorktree,
@@ -13,6 +13,7 @@ export const PORTS = {
     commentOnPr,
     commitAll,
     createPr,
+    deleteBranch,
     diff,
     failedCheckLogs,
     findPr,
@@ -21,6 +22,7 @@ export const PORTS = {
     markPrReady,
     push,
     removeWorktree,
+    revision,
     runAgent,
     runSetup: async (command, cwd, timeoutMs) => run("bash", ["-lc", command], { cwd, timeoutMs }),
     setLabel,
@@ -101,6 +103,12 @@ async function work(context, issue, log, state) {
     const escalate = (reason) => handOver(context, log, issue.number, state, reason);
     const finish = async (outcome, reason) => {
         await cleanUp(context, log, issue.number);
+        if (outcome === "done") {
+            if (!(await ports.deleteBranch(repo, branch))) {
+                log.event("branch.kept", { branch }, "quiet");
+            }
+            await dropState(repo, issue.number);
+        }
         return {
             issue: issue.number,
             outcome,
@@ -123,6 +131,7 @@ async function work(context, issue, log, state) {
         }
     }
     if (state.phase === "claimed") {
+        const before = await ports.revision(worktree);
         const result = await log.step("implement", {}, () => ports.runAgent(log, {
             name: "implementer",
             cwd: worktree,
@@ -132,11 +141,10 @@ async function work(context, issue, log, state) {
             timeoutMs: config.agentTimeoutMinutes * 60_000,
         }));
         const subject = parseCommitSubject(result.text, `fix: resolve issue #${issue.number}`);
-        if (!(await ports.commitAll(worktree, `${subject}\n\nRefs #${issue.number}`))) {
+        if (!(await commitWork(job, before, subject))) {
             await escalate("The implementer produced no change.");
             return finish("needs-human", "no implementation commit");
         }
-        log.event("commit", { subject });
         state.phase = "implemented";
         await writeState(repo, state);
     }
@@ -149,14 +157,18 @@ async function work(context, issue, log, state) {
     state.phase = "review";
     await writeState(repo, state);
     log.event("pull-request.ready", { pr: state.pr }, "quiet");
+    let noChecks = false;
     const gate = async () => {
-        const checks = await log.step("checks", { pr: state.pr }, () => ports.waitForChecks(repo, branch, {
+        const head = await ports.revision(worktree);
+        const checks = await log.step("checks", { pr: state.pr, head }, () => ports.waitForChecks(repo, branch, {
+            head,
             intervalSeconds: config.checkIntervalSeconds,
-            graceMs: config.checkGraceSeconds * 1000,
+            graceMs: noChecks ? 0 : config.checkGraceSeconds * 1000,
             timeoutMs: config.checkTimeoutMinutes * 60_000,
-            inherit: log.level === "verbose",
+            show: log.level === "verbose",
         }));
         log.event("checks.state", { state: checks });
+        noChecks ||= checks === "none";
         if (checks === "timeout") {
             await escalate("The checks did not finish in time.");
             return { done: true, report: await finish("needs-human", "checks timeout") };
@@ -210,7 +222,7 @@ async function work(context, issue, log, state) {
         const review = await log.step("review", fields, () => ports.runAgent(log, {
             name: "reviewer",
             cwd: worktree,
-            prompt: reviewPrompt(issue, comments, patch, state.reviewRounds, history(state.reviewLog)),
+            prompt: reviewPrompt(issue, comments, patch, history(state.reviewLog)),
             profile: READ_ONLY,
             model: config.models.reviewer,
             timeoutMs: config.agentTimeoutMinutes * 60_000,
@@ -242,8 +254,6 @@ async function work(context, issue, log, state) {
                 log.event("pull-request.undraft.fail", { pr: state.pr }, "quiet");
             }
             await setStatus(context, issue.number, state.pr, config.labels.done);
-            state.phase = "done";
-            await writeState(repo, state);
             return finish("done");
         }
         const mark = fingerprint(blocking);
@@ -264,6 +274,7 @@ async function work(context, issue, log, state) {
 async function fixRound(job, reason, detail, earlier, kind) {
     const { context, issue, log, worktree, branch } = job;
     const { ports } = context;
+    const before = await ports.revision(worktree);
     const result = await log.step("fix", { reason }, () => ports.runAgent(log, {
         name: "fixer",
         cwd: worktree,
@@ -278,14 +289,20 @@ async function fixRound(job, reason, detail, earlier, kind) {
         return { committed: false, unrelated };
     }
     const subject = parseCommitSubject(result.text, `fix: address feedback on issue #${issue.number}`);
-    if (!(await ports.commitAll(worktree, `${subject}\n\nRefs #${issue.number}`))) {
+    if (!(await commitWork(job, before, subject))) {
         log.event("commit.empty", { reason }, "quiet");
         return { committed: false };
     }
-    log.event("commit", { subject });
     await ports.push(worktree, context.config.remote, branch);
     return { committed: true };
 }
+async function commitWork(job, before, subject) {
+    const { context, issue, log, worktree } = job;
+    if (await context.ports.commitAll(worktree, `${subject}\n\nRefs #${issue.number}`)) {
+        log.event("commit", { subject });
+    }
+    return (await context.ports.revision(worktree)) !== before;
+}
 async function cleanUp(context, log, issue) {
     const path = worktreePath(context.repo, issue);
     try {

package/dist/prompts.mjs

@@ -26,8 +26,8 @@ export function capDiff(diff, 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
+export function reviewPrompt(issue, comments, diff, earlier) {
+    const scope = earlier.length === 0
         ? "Check correctness, scope, repository conventions and test cover."
         : [
             "This is a later round. Judge two things only:",

package/dist/state.mjs

@@ -38,3 +38,6 @@ export async function takeStop(repo) {
         return false;
     }
 }
+export async function dropState(repo, issue) {
+    await rm(file(repo, issue), { force: true });
+}

package/package.json

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