@gevezex/gdt 0.5.0 → 0.5.3

package/README.md

@@ -486,7 +486,9 @@ to be told: it blocks until the workflow needs attention.
 
 The roles work in the checkout where you run `gdt start`: the developer checks
 out the feature branch there, and the tester and reviewer read that same working
-tree. `gdt start` needs a **clean working tree** and refuses to run otherwise
+tree. When the pull request head is checked out in another worktree (for example
+one the developer created) and not in that checkout, the tester and reviewer
+turns run in that worktree instead. `gdt start` needs a **clean working tree** and refuses to run otherwise
 ("Commit or stash before starting."), so commit or stash first. Do not edit that
 checkout while a workflow runs; if you want to keep working, use a separate
 clone for gdt.

package/dist/git.js

@@ -1,4 +1,5 @@
 import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
 function git(args, cwd, env) {
     return spawnSync("git", args, { cwd, env, encoding: "utf8" }).stdout ?? "";
 }
@@ -23,3 +24,31 @@ export function checkout(root, env) {
         branch: git(["symbolic-ref", "--quiet", "--short", "HEAD"], root, env).trim(),
     };
 }
+/**
+ * #76: the directory a tester or reviewer turn for `head` runs in. That is `root` when it has `head`
+ * checked out, otherwise the first other worktree at `head` whose directory exists, otherwise `root`.
+ */
+export function headWorktree(root, head, env) {
+    const real = (path) => {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return null;
+        }
+    };
+    const main = real(root) ?? root;
+    const atHead = [];
+    for (const entry of git(["worktree", "list", "--porcelain"], root, env).split("\n\n")) {
+        const fields = entry.split("\n");
+        const path = fields.find((f) => f.startsWith("worktree "))?.slice("worktree ".length);
+        if (path === undefined || !fields.includes(`HEAD ${head}`))
+            continue;
+        const dir = real(path);
+        if (dir !== null)
+            atHead.push(dir);
+    }
+    if (atHead.includes(main))
+        return root;
+    return atHead[0] ?? root;
+}

package/dist/github.js

@@ -89,10 +89,28 @@ export function detectedChecks(cwd, env) {
         return [];
     }
 }
-/** The issue body and the open pull requests that close the issue ("Closes #n"). */
+/** True when `body` contains a closing keyword ("Closes #n", "fixes #n", ...) for exactly issue `issue`. */
+export function closesIssue(body, issue) {
+    return new RegExp(`(?<![\\w])(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\\s+#${issue}(?!\\d)`, "i").test(body);
+}
+/**
+ * The issue body and the workflow's pull requests: the open pull requests GitHub links as closing the
+ * issue, or, when there are none, the open pull requests whose body closes the issue without GitHub
+ * having linked them (`unlinked` is then true). The fallback costs one `gh api --paginate` call that
+ * reads every open pull request, so an older pull request is never cut off by a list limit.
+ */
 export function issueSnapshot(issue, cwd, env) {
     const data = ghJson(["issue", "view", String(issue), "--json", "body,closedByPullRequestsReferences"], cwd, env);
-    return { body: data.body, pullRequests: (data.closedByPullRequestsReferences ?? []).map((pr) => pr.number) };
+    const linked = (data.closedByPullRequestsReferences ?? []).map((pr) => pr.number);
+    if (linked.length > 0)
+        return { body: data.body, pullRequests: linked, unlinked: false };
+    const pages = ghJson(["api", "--paginate", "--slurp", "repos/{owner}/{repo}/pulls?state=open&per_page=100"], cwd, env);
+    const unlinked = pages
+        .flat()
+        .filter((pr) => closesIssue(pr.body ?? "", issue))
+        .map((pr) => pr.number)
+        .sort((x, y) => x - y);
+    return { body: data.body, pullRequests: unlinked, unlinked: unlinked.length > 0 };
 }
 /** All comments on an issue or pull request conversation, oldest first. */
 export function comments(repo, number, cwd, env) {

package/dist/prompts.js

@@ -72,6 +72,7 @@ export function buildPrompt(role, dispatch, project) {
         `Round: ${dispatch.round}`,
         `Pull request: ${dispatch.pr_number === null ? "none yet" : `#${dispatch.pr_number}`}`,
         `Head: ${dispatch.head ?? "none yet"}`,
+        ...(dispatch.workdir === undefined ? [] : [`Working directory: ${dispatch.workdir}`]),
         `issue_body_sha256: ${dispatch.issue_body_sha256}`,
         `Acceptance criteria: ${dispatch.acceptance_criteria.join(", ")}`,
         `Language: ${locale.name}`,

package/dist/supervisor.js

@@ -3,11 +3,12 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { formatSignals, groupUsage, nextBaseline, opencodeDatabase, sample, signals } from "./activity.js";
+import { formatSignals, groupUsage, nextBaseline, opencodeDatabase, opencodeMtime, sample, signals, } from "./activity.js";
 import { backendFor } from "./backends/index.js";
 import { loadConfig, ROLES } from "./config.js";
 import { sectionText, validateContract } from "./contract.js";
 import { decide, openFindings } from "./decision.js";
+import { headWorktree } from "./git.js";
 import { comments, issueSnapshot, pullRequest, repository, viewer } from "./github.js";
 import { loadLocale } from "./locale.js";
 import { notify } from "./notify.js";
@@ -47,6 +48,10 @@ export function inactiveReason(role, idle, limit) {
 export function hardLimitReason(role, minutes) {
     return `${role} turn still active after ${minutes} minutes`;
 }
+/** #71 AC-4: the blocked reason of a turn whose agent exited and stayed active until its hard limit. */
+export function exitedActiveReason(role, minutes) {
+    return `${role} exited without a visible handoff and stayed active until the ${minutes}-minute hard limit`;
+}
 /** AC-6: the blocked reason of a turn whose agent and worker are gone without a result. */
 export function exitedReason(role) {
     return `${role} agent exited without a result`;
@@ -63,6 +68,10 @@ export function turnLastActivity(inflight) {
 export function turnHardLimit(inflight, maxMinutes) {
     return inflight.hard_limit === undefined ? turnDeadline(inflight.dispatched_at, maxMinutes) : new Date(inflight.hard_limit);
 }
+/** The turn's hard limit in minutes after dispatch, rounded to two decimals for a reason text. */
+function hardLimitMinutes(inflight, hardLimit) {
+    return Math.round(((hardLimit.getTime() - Date.parse(inflight.dispatched_at)) / 60_000) * 100) / 100;
+}
 /** AC-2/AC-6: true when a blocked reason is a stopped or exited turn, so `gdt retry` can lift it. */
 export function isTimeoutReason(reason) {
     return /^\w+ turn inactive for [\d.]+ minutes after the [\d.]+-minute limit$/.test(reason) || / agent exited without a result$/.test(reason);
@@ -93,6 +102,24 @@ function roleOf(record) {
             return null;
     }
 }
+/**
+ * #76 AC-5/AC-6: why a dispatch that already ran is blocked. A tester or reviewer record for another
+ * head, posted after the role's dispatch `key`, is named with both heads and the turn's working directory.
+ */
+export function alreadyRanReason(role, key, dispatch, trusted, root) {
+    if (dispatch?.key === key && dispatch.head !== null) {
+        const since = Date.parse(dispatch.dispatched_at);
+        const heads = trusted.flatMap((r) => (r.kind === "test" || r.kind === "review") && r.data.role === role && Date.parse(r.created_at) >= since ? [r.data.head] : []);
+        const other = heads.filter((head) => head !== dispatch.head).at(-1);
+        if (other !== undefined)
+            return `${role} record is for head ${other}, not the dispatch head ${dispatch.head}; the turn ran in ${dispatch.workdir ?? root}`;
+    }
+    return `${role} already ran for this dispatch without a usable record`;
+}
+/** Whether `reason` is an already-ran block (#76: also when it names a record for another head); `gdt retry` lifts it. */
+export function isAlreadyRanReason(reason) {
+    return reason.includes(" already ran for this dispatch ") || reason.includes(", not the dispatch head ");
+}
 /** The record kind each workflow role writes; a diagnostic of another kind is never that role's. */
 const ROLE_OF_KIND = { handoff: "developer", test: "tester", review: "reviewer" };
 /** AC-1: the newest invalid role record the role posted after the turn's `after_comment_id`. */
@@ -121,6 +148,8 @@ class Supervisor {
     backend;
     trusted = [];
     reportWarned = false;
+    /** Unlinked pull requests already logged, so the fallback line appears once per pull request. */
+    unlinkedLogged = new Set();
     agents;
     constructor(p, issue, config, locale, env, state, backend) {
         this.p = p;
@@ -242,18 +271,37 @@ class Supervisor {
                 sleepSync(100);
         }
     }
+    /** The opencode session database when the role's agent is opencode, otherwise null. */
+    opencodeDb(role) {
+        if (this.effectiveAgent(role) !== "opencode")
+            return null;
+        const home = this.env.HOME === undefined || this.env.HOME === "" ? homedir() : this.env.HOME;
+        return opencodeDatabase(this.env, home);
+    }
     /** The activity sample of an in-flight turn (issue Definitions). */
     sampleTurn(running, pgid) {
-        const agent = this.effectiveAgent(running.role);
-        const home = this.env.HOME === undefined || this.env.HOME === "" ? homedir() : this.env.HOME;
         return sample({
             root: this.p.root,
             env: this.env,
             pgid,
             logFile: this.config.workflow.terminal === "headless" ? join(this.p.logs, `${running.role}.log`) : null,
-            opencodeDb: agent === "opencode" ? opencodeDatabase(this.env, home) : null,
+            opencodeDb: this.opencodeDb(running.role),
         });
     }
+    /**
+     * #71 post-exit activity: true when the opencode database changed since the previous handoff check,
+     * or since the agent exited on the first check. Never fires for other agents or a stopped turn.
+     */
+    postExitActivity(inflight, finishedAt) {
+        const database = inflight.stopped === true ? null : this.opencodeDb(inflight.role);
+        if (database === null)
+            return false;
+        const current = opencodeMtime(database);
+        const previous = inflight.handoff_opencode ?? (finishedAt === undefined ? undefined : Date.parse(finishedAt));
+        if (current !== null)
+            inflight.handoff_opencode = current;
+        return current !== null && previous !== undefined && current > previous;
+    }
     /**
      * AC-5: applies a hard limit granted by `gdt extend` for this turn. Returns true when a request was
      * read; the caller removes it only after saving the poll's status, so `gdt status` never sees the
@@ -331,7 +379,7 @@ class Supervisor {
         log(`activity check for ${running.key}: ${formatSignals(fired)}; last activity ${lastActivity}`);
         const context = { role: running.role, round: running.round };
         const hardLimit = turnHardLimit(running, workflow.turn_max_minutes);
-        const hardMinutes = Math.round(((hardLimit.getTime() - Date.parse(running.dispatched_at)) / 60_000) * 100) / 100;
+        const hardMinutes = hardLimitMinutes(running, hardLimit);
         if (running.at_hard_limit === true) {
             // AC-4: the turn keeps running until `gdt extend`, `gdt retry` or its result.
             this.setStatus("blocked", hardLimitReason(running.role, hardMinutes), context);
@@ -399,7 +447,7 @@ class Supervisor {
         // leave a hung turn `running` forever.
         if (this.settleTurn(now) !== null)
             return "continue";
-        const { body, pullRequests } = issueSnapshot(this.issue, this.p.root, this.env);
+        const { body, pullRequests, unlinked } = issueSnapshot(this.issue, this.p.root, this.env);
         const bodySha = sha256(body);
         const changelog = sectionText(body, this.locale.sections.changelog) ?? "";
         const known = this.state.contract;
@@ -421,48 +469,56 @@ class Supervisor {
         }
         // A turn in flight: nothing to fetch until its worker has reported.
         const running = this.state.inflight;
+        let finishedAt;
         if (running !== null) {
             if (running.violation !== undefined) {
                 this.setRoleState(running.role, "FAILED");
                 this.setStatus("blocked", running.violation, { role: running.role, round: running.round });
                 return "continue";
             }
-            if (running.missing) {
-                // Also restores the status after a stop and start. AC-1: an invalid record keeps its reason.
-                const reason = running.missing_reason ?? `${running.role} finished without a visible handoff`;
-                this.setStatus("blocked", reason, { role: running.role, round: running.round });
-                return "continue";
-            }
-            // A turn past its deadline was already settled at the top of this tick, before the GitHub
-            // fetch. A result-less turn that reaches this point is still before its deadline.
-            const result = readJson(this.p.result(running.key));
-            if (result === null) {
-                this.setStatus("running", `${running.role} turn in progress`, { role: running.role, round: running.round });
-                return "continue";
-            }
-            if (result.violation !== undefined) {
-                // A broken role boundary outranks the exit code: the checkout can no longer be trusted.
-                running.violation = result.violation;
-                this.setRoleState(running.role, "FAILED");
-                this.setStatus("blocked", result.violation, { role: running.role, round: running.round, exit_code: result.exit_code });
+            if (running.missing && running.stopped === true) {
+                // #71 Out of scope: a stopped turn stays blocked until a retry, whatever record arrives later.
+                this.setStatus("blocked", running.missing_reason ?? `${running.role} finished without a visible handoff`, { role: running.role, round: running.round });
                 return "continue";
             }
-            if (result.exit_code !== 0) {
-                const reason = result.exit_code === null
-                    ? `${running.role} turn was interrupted`
-                    : `${running.role} turn failed (exit code ${result.exit_code})`;
-                this.setRoleState(running.role, "FAILED");
-                this.setStatus("failed", reason, { role: running.role, round: running.round, exit_code: result.exit_code });
-                return "exit";
+            // #71 AC-5: a turn blocked on a missing handoff goes on to the fetch, so a late record lifts the block.
+            if (!running.missing) {
+                // A turn past its deadline was already settled at the top of this tick, before the GitHub
+                // fetch. A result-less turn that reaches this point is still before its deadline.
+                const result = readJson(this.p.result(running.key));
+                if (result === null) {
+                    this.setStatus("running", `${running.role} turn in progress`, { role: running.role, round: running.round });
+                    return "continue";
+                }
+                if (result.violation !== undefined) {
+                    // A broken role boundary outranks the exit code: the checkout can no longer be trusted.
+                    running.violation = result.violation;
+                    this.setRoleState(running.role, "FAILED");
+                    this.setStatus("blocked", result.violation, { role: running.role, round: running.round, exit_code: result.exit_code });
+                    return "continue";
+                }
+                if (result.exit_code !== 0) {
+                    const reason = result.exit_code === null
+                        ? `${running.role} turn was interrupted`
+                        : `${running.role} turn failed (exit code ${result.exit_code})`;
+                    this.setRoleState(running.role, "FAILED");
+                    this.setStatus("failed", reason, { role: running.role, round: running.round, exit_code: result.exit_code });
+                    return "exit";
+                }
+                // AC-5: the turn finished successfully.
+                finishedAt = result.finished_at;
+                this.setRoleState(running.role, "DONE");
             }
-            // AC-5: the turn finished successfully.
-            this.setRoleState(running.role, "DONE");
         }
         if (pullRequests.length > 1) {
             this.setStatus("blocked", `more than one open pull request closes #${this.issue}: ${pullRequests.map((n) => `#${n}`).join(", ")}`);
             return "continue";
         }
         const prNumber = pullRequests[0];
+        if (unlinked && prNumber !== undefined && !this.unlinkedLogged.has(prNumber)) {
+            this.unlinkedLogged.add(prNumber);
+            log(`pull request #${prNumber} closes #${this.issue} in its body but GitHub has not linked it; using it`);
+        }
         const pr = prNumber === undefined ? null : pullRequest(prNumber, this.p.root, this.env);
         if (pr !== null) {
             if (this.state.head !== null && this.state.head !== pr.head) {
@@ -480,31 +536,52 @@ class Supervisor {
         const inflight = this.state.inflight;
         if (inflight !== null) {
             const visible = trusted.some((r) => roleOf(r) === inflight.role && r.comment_id > inflight.after_comment_id);
+            const context = { role: inflight.role, round: inflight.round };
+            if (!visible && inflight.missing) {
+                // AC-1: an invalid record keeps its reason.
+                this.setStatus("blocked", inflight.missing_reason ?? `${inflight.role} finished without a visible handoff`, context);
+                return "continue";
+            }
             if (!visible) {
-                inflight.checks += 1;
                 // AC-1: an invalid record is named with its validation error instead of `not visible`;
                 // AC-4: without any role record the message and log line stay as before.
                 const invalid = invalidRecordFor(inflight, diagnostics, this.trusted);
-                log(`handoff check ${inflight.checks}/${this.config.workflow.handoff_checks} for ${inflight.key}: ` +
-                    (invalid === undefined ? "not visible" : invalid.reason));
+                const seen = invalid === undefined ? "not visible" : invalid.reason;
+                const retryRecord = (extra) => 
+                // AC-2: `gdt retry` keeps this record; the role's next turn reads it into its prompt.
+                invalid === undefined
+                    ? extra
+                    : { ...extra, retry_record: { role: inflight.role, kind: invalid.kind, comment_id: invalid.comment_id, reason: invalid.reason } };
+                // #71 AC-2: a check with post-exit activity is not a missed check.
+                if (this.postExitActivity(inflight, finishedAt)) {
+                    log(`handoff check for ${inflight.key}: ${seen}, agent still active (opencode=yes)`);
+                    const hardLimit = turnHardLimit(inflight, this.config.workflow.turn_max_minutes);
+                    if (now.getTime() >= hardLimit.getTime()) {
+                        // #71 AC-4: the hard limit bounds the wait, also when unrelated opencode use keeps it active.
+                        inflight.missing = true;
+                        inflight.missing_reason = exitedActiveReason(inflight.role, hardLimitMinutes(inflight, hardLimit));
+                        this.setStatus("blocked", inflight.missing_reason, retryRecord(context));
+                    }
+                    else {
+                        this.setStatus("running", `waiting for the ${inflight.role} handoff; agent exited but is still active`, context);
+                    }
+                    return "continue";
+                }
+                inflight.checks += 1;
+                log(`handoff check ${inflight.checks}/${this.config.workflow.handoff_checks} for ${inflight.key}: ${seen}`);
                 if (inflight.checks >= this.config.workflow.handoff_checks) {
                     inflight.missing = true;
-                    const reason = invalid === undefined
-                        ? `${inflight.role} finished without a visible handoff`
-                        : invalidRecordReason(inflight.role, invalid);
-                    inflight.missing_reason = reason;
-                    const extra = { role: inflight.role, round: inflight.round };
-                    // AC-2: `gdt retry` keeps this record; the role's next turn reads it into its prompt.
-                    if (invalid !== undefined) {
-                        extra.retry_record = { role: inflight.role, kind: invalid.kind, comment_id: invalid.comment_id, reason: invalid.reason };
-                    }
-                    this.setStatus("blocked", reason, extra);
+                    inflight.missing_reason = invalid === undefined ? `${inflight.role} finished without a visible handoff` : invalidRecordReason(inflight.role, invalid);
+                    this.setStatus("blocked", inflight.missing_reason, retryRecord(context));
                 }
                 else {
-                    this.setStatus("running", `waiting for the ${inflight.role} handoff to become visible`, { role: inflight.role, round: inflight.round });
+                    this.setStatus("running", `waiting for the ${inflight.role} handoff to become visible`, context);
                 }
                 return "continue";
             }
+            // #71 AC-5: a late record lifts the block as if it had arrived in time.
+            if (inflight.missing)
+                log(`late handoff for ${inflight.key} accepted`);
             this.state.inflight = null;
             // AC-2: the role's rejection explanation is spent once a valid record is visible.
             if (this.state.retry_record?.role === inflight.role)
@@ -533,7 +610,7 @@ class Supervisor {
         }
         const key = dispatchKey(decision, pr?.head ?? null, bodySha);
         if (this.state.dispatched.includes(key)) {
-            this.setStatus("blocked", `${decision.role} already ran for this dispatch without a usable record`, {
+            this.setStatus("blocked", alreadyRanReason(decision.role, key, readJson(this.p.dispatch(decision.role)), trusted, this.p.root), {
                 role: decision.role,
                 round: decision.round,
                 blocked_key: key,
@@ -556,6 +633,8 @@ class Supervisor {
             language: this.config.language,
             directives,
             dispatched_at: now.toISOString(),
+            // #76 AC-1/AC-3: a verifier runs where the pull request head is checked out.
+            workdir: pr !== null && decision.role !== "developer" ? headWorktree(this.p.root, pr.head, this.env) : this.p.root,
         };
         // Dispatch file first: if gdt stop lands in between, the restarted supervisor dispatches the same key
         // again, and the worker's exclusive "started" marker still runs it at most once.

package/dist/worker.js

@@ -21,7 +21,7 @@ export function waitingLine(role, last) {
     return `${DIM}${role} waiting · ${detail}${RESET_COLOURS}`;
 }
 /** The command for one unattended turn: the role's agent adapter, or the test agent's script. */
-export function invocation(roleName, role, root, promptFile, env) {
+export function invocation(roleName, role, root, promptFile, env, cwd = root) {
     if (role.agent === TEST_AGENT) {
         if (role.script === undefined || !testAgentsEnabled(env))
             throw new Error(`agent "${TEST_AGENT}" requires GDT_TEST_AGENTS=1 and a script`);
@@ -30,7 +30,7 @@ export function invocation(roleName, role, root, promptFile, env) {
     const adapter = adapterFor(role.agent);
     if (adapter === undefined)
         throw new Error(`no adapter for agent "${role.agent}" yet`);
-    return adapter.buildInvocation(roleName, role.model, promptFile, root);
+    return adapter.buildInvocation(roleName, role.model, promptFile, cwd);
 }
 function log(line) {
     process.stdout.write(`${logTimestamp()} ${line}\n`);
@@ -165,6 +165,8 @@ async function turn(root, role, dispatch, env, p) {
         log("invalid config; run gdt doctor");
         return finish(78);
     }
+    // #76 AC-1/AC-2: the turn and its boundary check run where the supervisor found the head.
+    const workdir = dispatch.workdir ?? root;
     const promptFile = p.prompt(dispatch.key);
     // AC-2: a retried turn is told how its previous record was rejected. Reading the state (rather than
     // the dispatch file) avoids a race with the worker that started before `gdt retry` finished.
@@ -182,7 +184,7 @@ async function turn(root, role, dispatch, env, p) {
     const roleConfig = override === undefined ? report.roles[role] : { ...report.roles[role], agent: override.agent, model: override.model };
     let inv;
     try {
-        inv = invocation(role, roleConfig, root, promptFile, env);
+        inv = invocation(role, roleConfig, root, promptFile, env, workdir);
     }
     catch (err) {
         log(err instanceof Error ? err.message : String(err));
@@ -200,9 +202,9 @@ async function turn(root, role, dispatch, env, p) {
         GDT_ISSUE_BODY_SHA256: dispatch.issue_body_sha256,
         GDT_DISPATCH_KEY: dispatch.key,
     };
-    const before = checkout(root, env);
-    const exitCode = await runInvocation(inv, root, turnEnv, (pid) => writeFileSync(p.agent(dispatch.key), `${pid}\n`));
-    const violation = boundaryViolation(role, before, root, env);
+    const before = checkout(workdir, env);
+    const exitCode = await runInvocation(inv, workdir, turnEnv, (pid) => writeFileSync(p.agent(dispatch.key), `${pid}\n`));
+    const violation = boundaryViolation(role, before, workdir, env);
     if (violation !== undefined)
         log(violation);
     return finish(exitCode, violation);

package/dist/workflow.js

@@ -11,7 +11,7 @@ import { issueBody, repository } from "./github.js";
 import { loadLocale } from "./locale.js";
 import { isInvalidRecordReason } from "./protocol.js";
 import { alive, lockHolder, paths, readJson, readOverrides, readState, writeJsonAtomic, writeState, } from "./state.js";
-import { activeReason, cliPath, isHardLimitReason, isTimeoutReason, turnDeadline, turnHardLimit, turnLastActivity, } from "./supervisor.js";
+import { activeReason, cliPath, isAlreadyRanReason, isHardLimitReason, isTimeoutReason, turnDeadline, turnHardLimit, turnLastActivity, } from "./supervisor.js";
 export const ok = (stdout) => ({ code: 0, stdout, stderr: "" });
 export const fail = (stderr) => ({ code: 1, stdout: "", stderr });
 /** Statuses that need a person or end the workflow: `gdt wait` returns when it reaches one. */
@@ -185,6 +185,9 @@ export function stop(issue, cwd, env) {
     stopProcesses(p, before, env);
     // Re-read: the supervisor may have written state until it was stopped.
     const state = readState(p) ?? before;
+    // #71 Out of scope: a late record for a stopped turn is never accepted.
+    if (state.inflight !== null)
+        state.inflight.stopped = true;
     // A failed turn keeps its status and reason; only the recovery step (gdt retry) clears it.
     if (state.status === "failed")
         Object.assign(state, { pids: { supervisor: null, workers: {} } });
@@ -203,7 +206,7 @@ function retryable(state) {
         return true;
     return (state.status === "blocked" &&
         (state.reason.includes("without a visible handoff") ||
-            state.reason.includes("already ran") ||
+            isAlreadyRanReason(state.reason) ||
             isTimeoutReason(state.reason) ||
             isHardLimitReason(state.reason) ||
             isInvalidRecordReason(state.reason)));
@@ -247,7 +250,7 @@ function blockedHint(issue, reason) {
     if (isHardLimitReason(reason))
         return `gdt extend ${issue} or gdt retry ${issue}`;
     if (reason.includes("without a visible handoff") ||
-        reason.includes("already ran") ||
+        isAlreadyRanReason(reason) ||
         isTimeoutReason(reason) ||
         isInvalidRecordReason(reason)) {
         return `gdt retry ${issue}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gevezex/gdt",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.",
   "keywords": [
     "github",

package/roles/reviewer.md

@@ -7,8 +7,8 @@ quality to be merged?
 ## Your job this turn
 
 1. Read the issue body with `gh issue view <issue>`. The current body is the only specification.
-2. Read the pull request and its diff with `gh pr view <pr>` and `gh pr diff <pr>`. All roles share one
-   checkout, and it is already at the pull request head: confirm that `git rev-parse HEAD` equals the
+2. Read the pull request and its diff with `gh pr view <pr>` and `gh pr diff <pr>`. Your turn runs in a
+   checkout at the pull request head (the working directory in this prompt): confirm that `git rev-parse HEAD` equals the
    head in this prompt (otherwise post `blocked`), read the code in context, and run the build and
    tests if that helps. Never check out another commit.
 3. Check, in this order:

package/roles/tester.md

@@ -7,8 +7,8 @@ check behaviour yourself.
 ## Your job this turn
 
 1. Read the issue body with `gh issue view <issue>`. The current body is the only specification.
-2. All roles share one checkout, and it is already at the pull request head. Confirm that
-   `git rev-parse HEAD` equals the head in this prompt. If it does not, post `blocked` and say so;
+2. Your turn runs in a checkout at the pull request head: the working directory in this prompt.
+   Confirm that `git rev-parse HEAD` equals the head in this prompt. If it does not, post `blocked` and say so;
    never check out another commit.
 3. For every AC: turn Given, When, Then and Example into a concrete check. Run the project's tests,
    run the program, and try the example and its edge cases. Record what you did and what you saw.