@gevezex/gdt 0.4.1 → 0.5.0

package/README.md

@@ -1,25 +1,37 @@
 # gdt
 
-**GitHub issues to merge-ready pull requests, with a developer, tester and reviewer agent.**
+**A deterministic supervisor that takes a GitHub issue through develop → test → review, with a different model in each role.**
 
-> Status: early development (0.x), used daily on this repository (see
-> [docs/dogfooding.md](docs/dogfooding.md)). Background:
-> [docs/design.md](docs/design.md).
+gdt (GitHub Development and Test) is a supervisor that makes every GitHub issue
+follow the same path: **develop → test → review**. Each step is done by a
+separate agent role, and you ideally give each role a different model, so one
+model's blind spots don't end up in your code unchecked.
 
-gdt takes one GitHub issue and runs it through three independent agent roles
-until a single draft pull request is ready to merge, or until it needs your
-decision:
+When the tester or reviewer finds problems, the issue goes back to the
+developer, but only a limited number of times: 2 correction rounds by default,
+shared between tester and reviewer. After that gdt stops and asks you, so an
+issue can never bounce between the roles forever.
+
+**Built to avoid burning tokens.** GitHub is the shared record: the roles don't
+talk to each other or to a long-running chat session, they each leave a
+structured comment on the pull request, and the supervisor reads those. The
+supervisor itself is plain code, not a model, so waiting, polling and deciding
+whose turn it is cost no tokens; a model only runs during a role's turn. It
+also means the workflow survives when your chat session ends.
+
+gdt currently supports **Claude Code, Codex, OpenCode, MCode, pi and omp**, both
+for the roles and for the agent you drive gdt from; more harnesses are on the
+way. You can watch the roles work in [herdr](https://herdr.dev). gdt stops at a
+draft pull request that is ready to merge; **you always merge yourself**.
+
+![gdt in herdr: the developer, tester and reviewer roles working on one issue](docs/assets/gdt-animation.gif)
 
 - the **developer** implements the issue and opens a draft pull request;
 - the **tester** checks every acceptance criterion against the running code;
 - the **reviewer** reads the diff against the issue.
 
-A deterministic **supervisor** (plain code, no model) decides whose turn it is.
-Waiting, polling and deciding cost no model tokens; a model only runs during a
-role's turn. You drive gdt by talking to any coding agent (Claude Code, Codex,
-OpenCode, MCode, pi or omp) and can watch the roles work in
-[herdr](https://herdr.dev). **You always merge yourself**: gdt never merges,
-deploys or closes issues.
+More background in [docs/design.md](docs/design.md); how we use gdt on this
+repository itself is in [docs/dogfooding.md](docs/dogfooding.md).
 
 ## How it works
 
@@ -28,8 +40,8 @@ deploys or closes issues.
 ```text
  ┌──────────┐  "pick up issue 251     ┌──────────────────────┐
  │   you    │ ──────────────────────► │  operator agent      │  Claude Code, Codex,
- └──────────┘   with gdt"             │  (your chat session) │  OpenCode, ...
-      ▲                               └──────────┬───────────┘
+ └──────────┘   with gdt"             │  (your chat session) │  OpenCode, MCode,
+      ▲                               └──────────┬───────────┘  pi or omp
       │                                          │ gdt start 251   (returns at once)
       │                                          │ gdt wait 251    (background, 0 tokens)
       │                                          ▼
@@ -447,6 +459,21 @@ Everything gdt keeps for an issue lives under `.git/gdt/issue-<n>/`: `state.json
 (the workflow state), `logs/` (one log per process) and `runs/` (the prompt and
 result of every turn). It is never committed.
 
+### What a role pane shows
+
+During a turn a role pane (herdr) or role log (headless, `logs/<role>.log`)
+shows what the agent CLI prints with the invocation in
+[docs/agents.md](docs/agents.md):
+
+| Agent | What the pane shows during a turn |
+|---|---|
+| `claude` | Live progress rendered by gdt from Claude Code's event stream: assistant text, tool calls (`→ Bash npm test`), tool results (`✓ ok` or `✗ error`) and the final result, while the turn runs |
+| `codex` | What `codex exec` prints: its progress (messages and the commands it runs) while the turn runs, then the final message |
+| `opencode` | What `opencode run` prints: messages and tool calls while the turn runs |
+| `mcode` | What `mcode exec` prints in its default text output |
+| `pi` | What `pi --print` prints: the final answer, when the turn ends |
+| `omp` | What `omp --print` prints: the final answer, when the turn ends |
+
 ### Notifications
 
 When a workflow needs you, gdt notifies you through the first of

package/dist/activity.js

@@ -0,0 +1,124 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+/** The CPU signal fires when the agent process group used at least this many more CPU seconds. */
+export const CPU_SIGNAL_SECONDS = 1;
+/** Parses a `ps` `time` value: `[dd-]hh:mm:ss` on Linux, `m:ss.cc` or `h:mm:ss.cc` on macOS. */
+export function parseCpuTime(value) {
+    const [days, rest] = value.includes("-") ? value.split("-", 2) : ["0", value];
+    const parts = (rest ?? "").split(":").map(Number);
+    let seconds = 0;
+    for (const part of parts)
+        seconds = seconds * 60 + (Number.isFinite(part) ? part : 0);
+    return Number(days) * 86_400 + seconds;
+}
+/**
+ * The summed CPU time and number of live (non-zombie) processes of process group `pgid`. The count is
+ * null when `ps` fails, so an unreadable process table never looks like an exited agent.
+ */
+export function groupUsage(pgid, env) {
+    if (pgid === null || pgid <= 0)
+        return { cpu: 0, processes: 0 };
+    const result = spawnSync("ps", ["-A", "-o", "pgid=", "-o", "stat=", "-o", "time="], { env, encoding: "utf8" });
+    if (result.status !== 0)
+        return { cpu: 0, processes: null };
+    let cpu = 0;
+    let processes = 0;
+    for (const line of result.stdout.split("\n")) {
+        const [group, stat, time] = line.trim().split(/\s+/);
+        if (Number(group) !== pgid || stat === undefined || time === undefined || stat.startsWith("Z"))
+            continue;
+        processes += 1;
+        cpu += parseCpuTime(time);
+    }
+    return { cpu, processes };
+}
+/** `HEAD`, `git status --porcelain` and the mtime of every listed file, hashed. */
+export function treeFingerprint(root, env) {
+    const git = (...args) => spawnSync("git", args, { cwd: root, env, encoding: "utf8" });
+    const head = git("rev-parse", "HEAD");
+    const status = git("status", "--porcelain", "-z");
+    if (status.status !== 0)
+        return null;
+    const hash = createHash("sha256").update(head.status === 0 ? head.stdout : "").update("\0").update(status.stdout);
+    const entries = status.stdout.split("\0").filter((entry) => entry !== "");
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i] ?? "";
+        const path = entry.slice(3);
+        // A rename or copy is followed by its original path, which no longer exists as listed.
+        if (entry[0] === "R" || entry[0] === "C")
+            i += 1;
+        hash.update(`\0${path}\0${mtimeOf(join(root, path)) ?? "-"}`);
+    }
+    return hash.digest("hex");
+}
+function mtimeOf(path) {
+    try {
+        return statSync(path).mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+function sizeOf(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return null;
+    }
+}
+/** The opencode session database: `$XDG_DATA_HOME/opencode/opencode.db`, by default under `~/.local/share`. */
+export function opencodeDatabase(env, home) {
+    const xdg = env.XDG_DATA_HOME;
+    const base = xdg !== undefined && isAbsolute(xdg) ? xdg : join(home, ".local", "share");
+    return join(base, "opencode", "opencode.db");
+}
+/** The mtime of `opencode.db-wal`, or of `opencode.db` when there is no write-ahead log. */
+export function opencodeMtime(database) {
+    return mtimeOf(`${database}-wal`) ?? mtimeOf(database);
+}
+/** Reads one activity sample with `ps`, `git` and file metadata only. */
+export function sample(input) {
+    const usage = groupUsage(input.pgid, input.env);
+    return {
+        cpu: usage.cpu,
+        processes: usage.processes,
+        tree: treeFingerprint(input.root, input.env),
+        log: input.logFile === null ? null : (sizeOf(input.logFile) ?? 0),
+        opencode: input.opencodeDb === null ? null : opencodeMtime(input.opencodeDb),
+    };
+}
+/**
+ * Compares a sample with the stored baseline. Without a baseline (the turn's first sample) no signal
+ * fires except CPU, which counts from zero: the agent process group started without CPU time.
+ */
+export function signals(current, baseline) {
+    const cpuBase = baseline?.cpu ?? 0;
+    const changed = (now, before) => baseline !== undefined && now !== null && before !== null && before !== undefined && now !== before;
+    return {
+        cpu: current.cpu - cpuBase >= CPU_SIGNAL_SECONDS,
+        tree: changed(current.tree, baseline?.tree),
+        log: baseline !== undefined && current.log !== null && current.log > (baseline.log ?? 0),
+        opencode: baseline !== undefined && current.opencode !== null && (baseline.opencode === null || current.opencode > baseline.opencode),
+    };
+}
+/**
+ * The baseline for the next poll. The CPU value only moves with recorded activity, or down when a
+ * process of the group exits and takes its CPU time with it.
+ */
+export function nextBaseline(current, previous, active) {
+    const cpuBase = previous?.cpu ?? 0;
+    return {
+        cpu: active || current.cpu < cpuBase ? current.cpu : cpuBase,
+        tree: current.tree,
+        log: current.log,
+        opencode: current.opencode,
+    };
+}
+/** The `supervisor.log` fragment naming every signal and whether it fired, for example `cpu=yes tree=no`. */
+export function formatSignals(fired) {
+    const yn = (value) => (value ? "yes" : "no");
+    return `cpu=${yn(fired.cpu)} tree=${yn(fired.tree)} log=${yn(fired.log)} opencode=${yn(fired.opencode)}`;
+}

package/dist/agents/claude-stream.js

@@ -0,0 +1,74 @@
+/**
+ * Renders Claude Code's stream-json output (`claude -p --output-format stream-json --verbose`) as
+ * readable lines while a turn runs (issue #62). A line it cannot read is passed through, never thrown.
+ */
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+/** The longest tool call summary, in characters. */
+const SUMMARY_MAX = 120;
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A passthrough line for a valid object: `[<type>]`, dimmed on a TTY. */
+function passthrough(type, tty) {
+    const line = `[${typeof type === "string" ? type : String(JSON.stringify(type))}]`;
+    return tty ? `${DIM}${line}${RESET}` : line;
+}
+/** `input.command`, else `input.file_path`, else `input.pattern`, else the compact JSON of `input`. */
+function summary(input) {
+    let text;
+    if (isObject(input) && typeof input.command === "string")
+        text = input.command;
+    else if (isObject(input) && typeof input.file_path === "string")
+        text = input.file_path;
+    else if (isObject(input) && typeof input.pattern === "string")
+        text = input.pattern;
+    else
+        text = JSON.stringify(input) ?? "";
+    return (text.split("\n")[0] ?? "").slice(0, SUMMARY_MAX);
+}
+function contentItems(event) {
+    const message = event.message;
+    return isObject(message) && Array.isArray(message.content) ? message.content : [];
+}
+function renderItem(item, eventType, tty) {
+    if (!isObject(item))
+        return [passthrough(typeof item, tty)];
+    if (eventType === "assistant" && item.type === "text" && typeof item.text === "string")
+        return item.text.split("\n");
+    if (eventType === "assistant" && item.type === "tool_use") {
+        const name = typeof item.name === "string" ? item.name : "";
+        return [`→ ${name} ${summary(item.input)}`];
+    }
+    if (eventType === "user" && item.type === "tool_result")
+        return [item.is_error === true ? "  ✗ error" : "  ✓ ok"];
+    return [passthrough(item.type, tty)];
+}
+/** The rendered lines for one line of stream-json output; an empty line gives none. */
+export function renderClaudeLine(line, tty) {
+    if (line.trim() === "")
+        return [];
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return [line];
+    }
+    if (!isObject(event))
+        return [line];
+    switch (event.type) {
+        case "assistant":
+        case "user": {
+            const type = event.type;
+            return contentItems(event).flatMap((item) => renderItem(item, type, tty));
+        }
+        case "result": {
+            const subtype = typeof event.subtype === "string" ? event.subtype : "";
+            const text = typeof event.result === "string" ? event.result.split("\n") : [];
+            return [`result: ${subtype}`, ...text];
+        }
+        default:
+            return [passthrough(event.type, tty)];
+    }
+}

package/dist/agents/claude.js

@@ -6,9 +6,21 @@ export const claude = {
     modelFormat: "<model>",
     modelExample: "claude-sonnet-5",
     buildInvocation: (_role, model, promptFile) => ({
-        argv: ["claude", "-p", "--model", model, "--permission-mode", "bypassPermissions", "--no-session-persistence"],
+        argv: [
+            "claude",
+            "-p",
+            "--model",
+            model,
+            "--permission-mode",
+            "bypassPermissions",
+            "--no-session-persistence",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+        ],
         env: {},
         stdin: promptFile,
+        output: "claude-stream-json",
     }),
     vendorOf: () => "anthropic",
     skillDir: () => "~/.claude/skills/gdt",

package/dist/cli.js

@@ -11,7 +11,7 @@ import { loadLocale, shippedLanguages } from "./locale.js";
 import { allowRound, answer, installSkill, pause, resume, setAgent, steer } from "./steering.js";
 import { supervise } from "./supervisor.js";
 import { work } from "./worker.js";
-import { retry, start, status, stop, wait } from "./workflow.js";
+import { extend, retry, start, status, stop, wait } from "./workflow.js";
 /** Exit codes: 0 success, 1 a check failed, 2 usage error. */
 export const EXIT_OK = 0;
 export const EXIT_FAILED = 1;
@@ -30,6 +30,7 @@ Commands:
   wait          Wait until the workflow needs attention
   stop          Stop the workflow for an issue; start resumes it
   retry         Prepare a controlled retry of the failed turn
+  extend        Give a turn that is still active at its hard limit more time
   answer        Answer an open question
   steer         Send a directive to one role
   pause         Stop dispatching new turns
@@ -108,6 +109,12 @@ Stops the supervisor, the role workers and any running agent turn.
 
 Stops the failed or interrupted workflow and clears that turn so
 "gdt start <issue>" runs it again.
+`,
+    extend: `Usage: gdt extend <issue>
+
+Gives a turn that is still active at its hard limit (workflow.turn_max_minutes)
+that many more minutes, counted from now. Only valid while the workflow is
+blocked at a turn's hard limit.
 `,
     pause: `Usage: gdt pause <issue>
 
@@ -445,19 +452,17 @@ function workflowCommand(command, args, io) {
     if (typeof parsed === "number")
         return parsed;
     const { issue, json } = parsed;
-    const result = command === "start"
-        ? start(issue, io.cwd, io.env)
-        : command === "stop"
-            ? stop(issue, io.cwd, io.env)
-            : command === "retry"
-                ? retry(issue, io.cwd, io.env)
-                : command === "pause"
-                    ? pause(issue, io.cwd, io.env)
-                    : command === "resume"
-                        ? resume(issue, io.cwd, io.env)
-                        : command === "allow-round"
-                            ? allowRound(issue, io.cwd, io.env)
-                            : status(issue, io.cwd, io.env, json);
+    const commands = {
+        start: () => start(issue, io.cwd, io.env),
+        status: () => status(issue, io.cwd, io.env, json),
+        stop: () => stop(issue, io.cwd, io.env),
+        retry: () => retry(issue, io.cwd, io.env),
+        extend: () => extend(issue, io.cwd, io.env),
+        pause: () => pause(issue, io.cwd, io.env),
+        resume: () => resume(issue, io.cwd, io.env),
+        "allow-round": () => allowRound(issue, io.cwd, io.env),
+    };
+    const result = commands[command]();
     return emit(result, io);
 }
 /** `gdt wait <issue> [--timeout <seconds>] [--json]`: blocks until the workflow needs attention. */
@@ -597,6 +602,7 @@ export function run(argv, io) {
         case "status":
         case "stop":
         case "retry":
+        case "extend":
         case "pause":
         case "resume":
         case "allow-round":

package/dist/config.js

@@ -15,6 +15,12 @@ export const LOCAL_CONFIG_PATH = ".gdt/config.local.toml";
 export const USER_CONFIG_DIR = "gdt";
 export const DEFAULT_LANGUAGE = "en";
 export const DEFAULT_MAX_ACCEPTANCE_CRITERIA = 8;
+/** AC-4: the turn time limit in minutes when `workflow.turn_timeout_minutes` is absent. */
+export const DEFAULT_TURN_TIMEOUT_MINUTES = 60;
+/** The inactivity window in minutes when `workflow.turn_idle_minutes` is absent. */
+export const DEFAULT_TURN_IDLE_MINUTES = 10;
+/** The hard limit in minutes when `workflow.turn_max_minutes` is absent. */
+export const DEFAULT_TURN_MAX_MINUTES = 120;
 /** The test agent: runs `script` instead of a coding agent. Only accepted when GDT_TEST_AGENTS=1. */
 export const TEST_AGENT = "fake";
 /** The OS home directory, or `env.HOME` when it names one (AC-1 of issue #51). */
@@ -58,7 +64,8 @@ function configSchemaFor(testAgents) {
         roles: z
             .strictObject({ developer: role.optional(), tester: role.optional(), reviewer: role.optional() })
             .optional(),
-        workflow: z.strictObject({
+        workflow: z
+            .strictObject({
             max_correction_rounds: z.int().min(0).default(2),
             // Deliberately without a default: an empty gate must be an explicit choice.
             required_checks: z.array(z.string().min(1)),
@@ -69,6 +76,21 @@ function configSchemaFor(testAgents) {
             herdr_layout: z.enum(HERDR_LAYOUTS).default("tabs"),
             poll_seconds: z.number().positive().default(30),
             handoff_checks: z.int().min(1).default(5),
+            // AC-4: a positive number of minutes per turn, 60 by default; zero or negative is invalid.
+            turn_timeout_minutes: z.number().positive().default(DEFAULT_TURN_TIMEOUT_MINUTES),
+            // A turn past its deadline keeps running while it was active within this many minutes.
+            turn_idle_minutes: z.number().positive().default(DEFAULT_TURN_IDLE_MINUTES),
+            // A turn still active this long after its dispatch asks the user (`gdt extend` or `gdt retry`).
+            turn_max_minutes: z.number().positive().default(DEFAULT_TURN_MAX_MINUTES),
+        })
+            .superRefine((workflow, ctx) => {
+            if (workflow.turn_max_minutes < workflow.turn_timeout_minutes) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["turn_max_minutes"],
+                    message: `must be at least workflow.turn_timeout_minutes (${workflow.turn_timeout_minutes})`,
+                });
+            }
         }),
         contract: z
             .strictObject({

package/dist/prompts.js

@@ -37,6 +37,16 @@ export function pendingDirectives(records, trustedAuthors, role, afterCommentId)
         .filter((r) => trustedAuthors.includes(r.author) && r.data.role === role && r.comment_id > afterCommentId)
         .map((r) => ({ comment_id: r.comment_id, directive: r.data.directive }));
 }
+/**
+ * The record schema as embedded in a prompt. `z.toJSONSchema` starts with a `"$schema"` key and
+ * agents copy it into their record, where the strict schema rejects it; the key is dropped from the
+ * prompt (AC-3).
+ */
+function recordSchema(kind) {
+    const schema = { ...z.toJSONSchema(schemas[kind]) };
+    delete schema["$schema"];
+    return JSON.stringify(schema, null, 2);
+}
 function schemaSection(kind) {
     return [
         `## Protocol: ${marker(kind)}`,
@@ -44,8 +54,10 @@ function schemaSection(kind) {
         `Close the record with ${marker(kind, true)}. The JSON object must match this JSON Schema:`,
         "",
         "```json",
-        JSON.stringify(z.toJSONSchema(schemas[kind]), null, 2),
+        recordSchema(kind),
         "```",
+        "",
+        `The record must not contain a \`"$schema"\` key.`,
     ].join("\n");
 }
 /** The prompt for one turn: role file, dispatch facts, language, protocol, directives and project rules. */
@@ -77,6 +89,16 @@ export function buildPrompt(role, dispatch, project) {
         `Acceptance-criterion fields: ${f.given}, ${f.when}, ${f.then}, ${f.example}`,
         `"None" marker: ${locale.markers.none}`,
     ].join("\n"));
+    // AC-2: the retried turn is told which record was rejected and why, so it can post a fixed one.
+    if (dispatch.invalid_record !== undefined) {
+        const rejected = dispatch.invalid_record;
+        parts.push([
+            `## Invalid record in comment ${rejected.comment_id}`,
+            "",
+            `Your previous ${marker(rejected.kind)} record in comment ${rejected.comment_id} was rejected: ${rejected.reason}`,
+            `Post a new, complete record ${marker(rejected.kind)} that matches the schema exactly.`,
+        ].join("\n"));
+    }
     parts.push(schemaSection(RECORD_OF[role]), schemaSection("question"));
     if (dispatch.directives.length > 0) {
         parts.push([

package/dist/protocol.js

@@ -63,6 +63,14 @@ export const schemas = {
 export function marker(kind, closing = false) {
     return `[${closing ? "/" : ""}gdt-${kind}:v1]`;
 }
+/** AC-1: the blocked reason for a turn whose role posted only an invalid record. */
+export function invalidRecordReason(role, diagnostic) {
+    return `${role} posted an invalid record ${marker(diagnostic.kind)} in comment ${diagnostic.comment_id}: ${diagnostic.reason}`;
+}
+/** True when a blocked reason reports an invalid record, so `gdt retry` can lift it (AC-1). */
+export function isInvalidRecordReason(reason) {
+    return reason.includes(" posted an invalid record ");
+}
 /** The comment body carrying one record: opening marker, JSON object and closing marker. */
 export function formatRecord(kind, data) {
     return `${marker(kind)}\n${JSON.stringify(data, null, 2)}\n${marker(kind, true)}\n`;
@@ -93,12 +101,12 @@ export function parseRecords(comments) {
                 json = JSON.parse(unfence(match[2] ?? ""));
             }
             catch {
-                diagnostics.push({ comment_id: comment.id, kind, reason: "invalid JSON" });
+                diagnostics.push({ comment_id: comment.id, author: comment.author, kind, reason: "invalid JSON" });
                 continue;
             }
             const parsed = schemas[kind].safeParse(json);
             if (!parsed.success) {
-                diagnostics.push({ comment_id: comment.id, kind, reason: schemaReason(parsed.error) });
+                diagnostics.push({ comment_id: comment.id, author: comment.author, kind, reason: schemaReason(parsed.error) });
                 continue;
             }
             records.push({

package/dist/state.js

@@ -31,6 +31,7 @@ export function paths(root, issue, env) {
         lock: join(dir, "supervisor.lock"),
         pause: join(dir, "paused"),
         stopping: join(dir, "stopping"),
+        extend: join(dir, "extend.json"),
         overrides: join(dir, "overrides.json"),
         logs: join(dir, "logs"),
         panes: join(dir, "panes.json"),
@@ -39,6 +40,7 @@ export function paths(root, issue, env) {
         started: (key) => join(dir, "runs", `${key}.started`),
         result: (key) => join(dir, "runs", `${key}.result.json`),
         prompt: (key) => join(dir, "runs", `${key}.prompt.md`),
+        agent: (key) => join(dir, "runs", `${key}.agent`),
     };
 }
 /** A log line timestamp in local time, `YYYY-MM-DD hh:mm:ss`. */

package/dist/supervisor.js

@@ -1,6 +1,9 @@
 import { createHash } from "node:crypto";
-import { existsSync, rmSync } from "node:fs";
+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 { backendFor } from "./backends/index.js";
 import { loadConfig, ROLES } from "./config.js";
 import { sectionText, validateContract } from "./contract.js";
@@ -9,8 +12,8 @@ import { comments, issueSnapshot, pullRequest, repository, viewer } from "./gith
 import { loadLocale } from "./locale.js";
 import { notify } from "./notify.js";
 import { pendingDirectives } from "./prompts.js";
-import { parseRecords } from "./protocol.js";
-import { acquireLock, logTimestamp, NOTIFY_STATUSES, paths, readJson, readState, writeJsonAtomic, writeState, } from "./state.js";
+import { invalidRecordReason, parseRecords } from "./protocol.js";
+import { acquireLock, logTimestamp, NOTIFY_STATUSES, paths, readJson, readOverrides, readState, writeJsonAtomic, writeState, } from "./state.js";
 /** AC-4: the herdr agent state reported for each role pane state. */
 const ROLE_PANE_STATE = {
     RUNNING: "working",
@@ -32,6 +35,43 @@ export function cliPath() {
 export function sha256(text) {
     return createHash("sha256").update(text).digest("hex");
 }
+/** AC-1: the running reason of a turn past its deadline that is still active. */
+export function activeReason(role, limit) {
+    return `${role} turn past the ${limit}-minute limit, still active`;
+}
+/** AC-2: the blocked reason of a turn stopped because it was inactive after its deadline. */
+export function inactiveReason(role, idle, limit) {
+    return `${role} turn inactive for ${idle} minutes after the ${limit}-minute limit`;
+}
+/** AC-4: the blocked reason of a turn that is still active at its hard limit. */
+export function hardLimitReason(role, minutes) {
+    return `${role} turn still active after ${minutes} minutes`;
+}
+/** 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`;
+}
+/** The deadline of a turn dispatched at `dispatchedAt`, with `minutes` as the configured limit. */
+export function turnDeadline(dispatchedAt, minutes) {
+    return new Date(new Date(dispatchedAt).getTime() + minutes * 60_000);
+}
+/** AC-8: the turn's last activity: `dispatched_at` until an activity signal fires. */
+export function turnLastActivity(inflight) {
+    return inflight.last_activity ?? inflight.dispatched_at;
+}
+/** AC-8: the turn's hard limit: `dispatched_at + turn_max_minutes` until `gdt extend` moves it. */
+export function turnHardLimit(inflight, maxMinutes) {
+    return inflight.hard_limit === undefined ? turnDeadline(inflight.dispatched_at, maxMinutes) : new Date(inflight.hard_limit);
+}
+/** 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);
+}
+/** AC-4: true when a blocked reason is a turn still active at its hard limit. */
+export function isHardLimitReason(reason) {
+    return /^\w+ turn still active after [\d.]+ minutes$/.test(reason);
+}
+const NO_SIGNALS = { cpu: false, tree: false, log: false, opencode: false };
 /** One key per role, round, head and contract; a resumed question makes the resumed turn distinct. */
 export function dispatchKey(decision, head, bodySha) {
     const parts = [decision.role, `r${decision.round}`, head ?? "no-pr", bodySha];
@@ -53,6 +93,18 @@ function roleOf(record) {
             return null;
     }
 }
+/** 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`. */
+function invalidRecordFor(inflight, diagnostics, trusted) {
+    return diagnostics
+        .filter((d) => ROLE_OF_KIND[d.kind] === inflight.role && trusted.includes(d.author) && d.comment_id > inflight.after_comment_id)
+        // Newest comment wins when the role posted several invalid records.
+        .sort((a, b) => b.comment_id - a.comment_id)[0];
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function sleep(ms) {
     return new Promise((done) => setTimeout(done, ms));
 }
@@ -107,6 +159,16 @@ class Supervisor {
         this.backend.setTitle(role, this.roleTitle(role, state));
         this.reportState(role, ROLE_PANE_STATE[state]);
     }
+    /**
+     * AC-1: ends a role's worker, which stops its agent process group on SIGTERM. Its pid is dropped so
+     * a later `gdt retry` does not try to stop an already-dead process.
+     */
+    stopRole(role) {
+        const pid = this.state.pids.workers[role];
+        if (pid !== undefined && this.backend.alive(pid))
+            this.backend.close(pid);
+        this.state.pids.workers = Object.fromEntries(Object.entries(this.state.pids.workers).filter(([name]) => name !== role));
+    }
     /** AC-1: sets the display-only agent label, for example `developer · opencode` or `gdt · supervisor`. */
     setDisplay(name, label) {
         try {
@@ -119,6 +181,21 @@ class Supervisor {
             log(`warning: herdr display label failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /** The agent of a role's next turn: its `gdt set-agent` override, otherwise the config agent. */
+    effectiveAgent(role) {
+        return readOverrides(this.p)[role]?.agent ?? this.agents[role];
+    }
+    /**
+     * #68 AC-1/AC-2: sets a role label naming the effective agent. A `gdt set-agent` that writes its
+     * override and label between our read and our write would be overwritten, so the label is written
+     * again until the override read after writing it matches.
+     */
+    setRoleDisplay(role) {
+        for (let agent = this.effectiveAgent(role), written = ""; agent !== written; agent = this.effectiveAgent(role)) {
+            this.setDisplay(role, `${role} · ${agent}`);
+            written = agent;
+        }
+    }
     /** Records a status; notifies once when entering a notifying status. */
     setStatus(status, reason, extra = {}) {
         if (this.state.status !== status || this.state.reason !== reason)
@@ -138,15 +215,169 @@ class Supervisor {
         }
         this.save();
     }
+    /** The agent process group id the worker recorded for the turn, or null before the agent started. */
+    agentGroup(key) {
+        try {
+            const pid = Number(readFileSync(this.p.agent(key), "utf8").trim());
+            return Number.isInteger(pid) && pid > 0 ? pid : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** AC-2: ends what is left of the agent process group once its worker is stopped. */
+    stopGroup(pgid) {
+        if (pgid === null)
+            return;
+        for (const signal of ["SIGTERM", "SIGKILL"]) {
+            if (groupUsage(pgid, this.env).processes === 0)
+                return;
+            try {
+                process.kill(-pgid, signal);
+            }
+            catch {
+                return;
+            }
+            for (let waited = 0; waited < 2000 && groupUsage(pgid, this.env).processes !== 0; waited += 100)
+                sleepSync(100);
+        }
+    }
+    /** 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,
+        });
+    }
+    /**
+     * 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
+     * turn blocked again in between.
+     */
+    applyExtension(running) {
+        const extension = readJson(this.p.extend);
+        if (extension === null)
+            return false;
+        if (extension.key === running.key) {
+            running.hard_limit = extension.hard_limit;
+            running.at_hard_limit = false;
+            log(`${running.role} turn hard limit extended to ${extension.hard_limit}`);
+        }
+        return true;
+    }
+    /** Blocks the workflow on a stopped or exited turn; the block stays until `gdt retry`. */
+    blockStopped(running) {
+        this.setRoleState(running.role, "FAILED");
+        this.setStatus("blocked", running.stop_reason ?? exitedReason(running.role), { role: running.role, round: running.round });
+        return "continue";
+    }
+    /**
+     * Checks a result-less in-flight turn on every poll, before any GitHub fetch, so a failing `gh`
+     * call never postpones it. It samples the turn's activity and moves its last activity when a
+     * signal fires. AC-6: a turn whose worker and agent are gone on two consecutive polls blocks at
+     * once. Past the deadline, AC-1: an active turn keeps running; AC-2: an inactive one is stopped
+     * and blocked; AC-4: an active one at its hard limit blocks without being stopped. A result file
+     * ends the turn, also at the hard limit; a stopped turn stays blocked even if a result appears.
+     * With `startup`, the worker was not started yet, so a missing worker is not an exited agent.
+     * Returns "continue" when the poll ends here, or null to let `tick` go on.
+     */
+    settleTurn(now, startup = false) {
+        const running = this.state.inflight;
+        if (running === null || running.violation !== undefined || running.missing)
+            return null;
+        if (running.stop_reason !== undefined)
+            return this.blockStopped(running);
+        if (readJson(this.p.result(running.key)) !== null)
+            return null;
+        const extended = this.applyExtension(running);
+        const outcome = this.checkActivity(running, now, startup);
+        if (extended) {
+            this.save();
+            rmSync(this.p.extend, { force: true });
+        }
+        return outcome;
+    }
+    /** The activity part of `settleTurn` for a result-less in-flight turn. */
+    checkActivity(running, now, startup) {
+        const workflow = this.config.workflow;
+        const pgid = this.agentGroup(running.key);
+        const current = this.sampleTurn(running, pgid);
+        // On startup the agent of the previous run is gone and gdt's own stop line grew the log, so the
+        // sample only becomes the new baseline: the kept last activity gets no fresh window.
+        const fired = startup ? NO_SIGNALS : signals(current, running.activity);
+        const active = fired.cpu || fired.tree || fired.log || fired.opencode;
+        running.activity = nextBaseline(current, startup ? undefined : running.activity, startup || active);
+        if (active)
+            running.last_activity = now.toISOString();
+        // AC-6: an exited agent needs two consecutive polls, so a single unlucky sample never blocks a turn.
+        const workerAlive = this.backend.alive(this.state.pids.workers[running.role] ?? -1);
+        running.exited_polls = !startup && !workerAlive && current.processes === 0 ? (running.exited_polls ?? 0) + 1 : 0;
+        if (running.exited_polls >= 2) {
+            running.stop_reason = exitedReason(running.role);
+            this.stopRole(running.role);
+            log(`${running.role} agent exited without a result`);
+            return this.blockStopped(running);
+        }
+        const limit = workflow.turn_timeout_minutes;
+        if (now.getTime() < turnDeadline(running.dispatched_at, limit).getTime())
+            return null;
+        const lastActivity = turnLastActivity(running);
+        // AC-1/AC-3: one line per poll past the deadline, naming every signal and whether it fired.
+        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;
+        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);
+            return "continue";
+        }
+        if (now.getTime() - Date.parse(lastActivity) >= workflow.turn_idle_minutes * 60_000) {
+            running.timed_out = true;
+            running.stop_reason = inactiveReason(running.role, workflow.turn_idle_minutes, limit);
+            this.stopRole(running.role);
+            this.stopGroup(pgid);
+            log(`${running.stop_reason}; worker and agent stopped`);
+            return this.blockStopped(running);
+        }
+        if (now.getTime() >= hardLimit.getTime()) {
+            running.at_hard_limit = true;
+            this.setStatus("blocked", hardLimitReason(running.role, hardMinutes), context);
+            return "continue";
+        }
+        this.setStatus("running", activeReason(running.role, limit), context);
+        return "continue";
+    }
+    /**
+     * Settles an in-flight turn before replacement workers start. A replacement worker that finds the
+     * turn's `started` marker writes an interruption result (exit code null), which would otherwise
+     * turn an inactive overdue turn into `failed` instead of the retryable `blocked`. Returns the
+     * stopped role, so `startWorkers` keeps its FAILED pane and starts no worker for it.
+     */
+    settleOverdueTurn(now) {
+        this.settleTurn(now, true);
+        const running = this.state.inflight;
+        return running?.stop_reason === undefined ? null : running.role;
+    }
     startWorkers() {
         this.backend.ensureWorkspace();
         // AC-1: the agents overview shows the role next to the agent name, once per `gdt start`.
         this.setDisplay("supervisor", "gdt · supervisor");
         this.backend.setTitle("supervisor", "supervisor · starting");
         this.reportState("supervisor", supervisorAgentState(this.state.status));
+        // AC-1: settle an overdue in-flight turn before its replacement worker can write a result.
+        const settled = this.settleOverdueTurn(new Date());
         for (const role of ROLES) {
+            // A settled role keeps its FAILED pane and gets no worker until `gdt retry` and `gdt start`.
+            if (role === settled)
+                continue;
             this.setRoleState(role, "WAITING");
-            this.setDisplay(role, `${role} · ${this.agents[role]}`);
+            this.setRoleDisplay(role);
             if (this.backend.alive(this.state.pids.workers[role] ?? -1))
                 continue;
             this.state.pids.workers[role] = this.backend.spawnPane(role, [process.execPath, cliPath(), "_worker", String(this.issue), role]);
@@ -164,6 +395,10 @@ class Supervisor {
             this.setStatus("paused", "", { role: null });
             return "continue";
         }
+        // The turn check runs before any GitHub fetch, so a failing `gh` call cannot postpone it and
+        // 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 bodySha = sha256(body);
         const changelog = sectionText(body, this.locale.sections.changelog) ?? "";
@@ -193,10 +428,13 @@ class Supervisor {
                 return "continue";
             }
             if (running.missing) {
-                // Also restores the status after a stop and start.
-                this.setStatus("blocked", `${running.role} finished without a visible handoff`, { role: running.role, round: running.round });
+                // 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 });
@@ -237,17 +475,30 @@ class Supervisor {
         const thread = [...comments(this.state.repository, this.issue, this.p.root, this.env)];
         if (pr !== null)
             thread.push(...comments(this.state.repository, pr.number, this.p.root, this.env));
-        const { records } = parseRecords(thread);
+        const { records, diagnostics } = parseRecords(thread);
         const trusted = records.filter((r) => this.trusted.includes(r.author));
         const inflight = this.state.inflight;
         if (inflight !== null) {
             const visible = trusted.some((r) => roleOf(r) === inflight.role && r.comment_id > inflight.after_comment_id);
             if (!visible) {
                 inflight.checks += 1;
-                log(`handoff check ${inflight.checks}/${this.config.workflow.handoff_checks} for ${inflight.key}: not visible`);
+                // 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));
                 if (inflight.checks >= this.config.workflow.handoff_checks) {
                     inflight.missing = true;
-                    this.setStatus("blocked", `${inflight.role} finished without a visible handoff`);
+                    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);
                 }
                 else {
                     this.setStatus("running", `waiting for the ${inflight.role} handoff to become visible`, { role: inflight.role, round: inflight.round });
@@ -255,6 +506,9 @@ class Supervisor {
                 return "continue";
             }
             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)
+                this.state.retry_record = null;
         }
         const snapshot = {
             repository: this.state.repository,

package/dist/worker.js

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { closeSync, existsSync, mkdirSync, openSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { renderClaudeLine } from "./agents/claude-stream.js";
 import { adapterFor } from "./agents/index.js";
 import { loadConfig, TEST_AGENT, testAgentsEnabled } from "./config.js";
 import { changedFiles, checkout } from "./git.js";
@@ -77,7 +79,7 @@ export function boundaryViolation(role, before, root, env) {
     return undefined;
 }
 /** Runs one invocation and passes the agent's exit code through unchanged (null when killed by a signal). */
-export function runInvocation(inv, cwd, env) {
+export function runInvocation(inv, cwd, env, onSpawn) {
     const [command, ...args] = inv.argv;
     return new Promise((done) => {
         let stdin = "ignore";
@@ -90,18 +92,39 @@ export function runInvocation(inv, cwd, env) {
             done(66);
             return;
         }
-        // Its own process group, so a stop can end the agent and the children it started.
+        const rendered = inv.output === "claude-stream-json";
+        // Its own process group, so a stop can end the agent and the children it started. A rendered
+        // stream is read in this process, so the renderer adds no process that could outlive the agent.
         const child = spawn(command ?? "", args, {
             cwd,
             env: { ...env, ...inv.env },
-            stdio: [stdin, "inherit", "inherit"],
+            stdio: [stdin, rendered ? "pipe" : "inherit", "inherit"],
             detached: true,
         });
         activeAgent = child;
+        // The agent's pid is its process group id; the supervisor samples that group's activity.
+        if (child.pid !== undefined)
+            onSpawn?.(child.pid);
         const close = () => {
             if (typeof stdin === "number")
                 closeSync(stdin);
         };
+        // With a rendered stream the turn ends once the agent has exited and its last line is written.
+        let pending = rendered && child.stdout !== null ? 2 : 1;
+        let exitCode = null;
+        const settle = () => {
+            if (--pending === 0)
+                done(exitCode);
+        };
+        if (rendered && child.stdout !== null) {
+            const tty = process.stdout.isTTY === true;
+            const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+            lines.on("line", (line) => {
+                for (const out of renderClaudeLine(line, tty))
+                    process.stdout.write(`${out}\n`);
+            });
+            lines.on("close", settle);
+        }
         child.on("error", (err) => {
             activeAgent = null;
             log(`agent could not start: ${err.message}`);
@@ -111,7 +134,8 @@ export function runInvocation(inv, cwd, env) {
         child.on("close", (code) => {
             activeAgent = null;
             close();
-            done(code);
+            exitCode = code;
+            settle();
         });
     });
 }
@@ -142,8 +166,12 @@ async function turn(root, role, dispatch, env, p) {
         return finish(78);
     }
     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.
+    const rejected = readState(p)?.retry_record;
+    const promptDispatch = rejected != null && rejected.role === role ? { ...dispatch, invalid_record: rejected } : dispatch;
     try {
-        writeFileSync(promptFile, buildPrompt(role, dispatch, { root, extraRules: report.contract.extra_rules }));
+        writeFileSync(promptFile, buildPrompt(role, promptDispatch, { root, extraRules: report.contract.extra_rules }));
     }
     catch (err) {
         log(`cannot build the prompt: ${err instanceof Error ? err.message : String(err)}`);
@@ -173,7 +201,7 @@ async function turn(root, role, dispatch, env, p) {
         GDT_DISPATCH_KEY: dispatch.key,
     };
     const before = checkout(root, env);
-    const exitCode = await runInvocation(inv, root, turnEnv);
+    const exitCode = await runInvocation(inv, root, turnEnv, (pid) => writeFileSync(p.agent(dispatch.key), `${pid}\n`));
     const violation = boundaryViolation(role, before, root, env);
     if (violation !== undefined)
         log(violation);

package/dist/workflow.js

@@ -3,14 +3,15 @@ import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node
 import { relative } from "node:path";
 import { headless } from "./backends/headless.js";
 import { backendFor } from "./backends/index.js";
-import { loadConfig, ROLES, userConfigPath } from "./config.js";
+import { DEFAULT_TURN_MAX_MINUTES, DEFAULT_TURN_TIMEOUT_MINUTES, loadConfig, ROLES, userConfigPath, } from "./config.js";
 import { validateContract } from "./contract.js";
 import { findRepository, herdrPreflight, unsupportedAgentFindings } from "./doctor.js";
 import { changedFiles } from "./git.js";
 import { issueBody, repository } from "./github.js";
 import { loadLocale } from "./locale.js";
-import { alive, lockHolder, paths, readOverrides, readState, writeState } from "./state.js";
-import { cliPath } from "./supervisor.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";
 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. */
@@ -200,7 +201,12 @@ export function stop(issue, cwd, env) {
 function retryable(state) {
     if (state.status === "failed")
         return true;
-    return state.status === "blocked" && (state.reason.includes("without a visible handoff") || state.reason.includes("already ran"));
+    return (state.status === "blocked" &&
+        (state.reason.includes("without a visible handoff") ||
+            state.reason.includes("already ran") ||
+            isTimeoutReason(state.reason) ||
+            isHardLimitReason(state.reason) ||
+            isInvalidRecordReason(state.reason)));
 }
 /** `gdt retry <n>`: stops the workflow and clears the interrupted turn so `gdt start` runs it again. */
 export function retry(issue, cwd, env) {
@@ -217,6 +223,7 @@ export function retry(issue, cwd, env) {
     if (key !== undefined) {
         rmSync(p.started(key), { force: true });
         rmSync(p.result(key), { force: true });
+        rmSync(p.agent(key), { force: true });
         state.dispatched = state.dispatched.filter((known) => known !== key);
     }
     Object.assign(state, {
@@ -228,6 +235,7 @@ export function retry(issue, cwd, env) {
         pids: { supervisor: null, workers: {} },
     });
     writeState(p, state);
+    rmSync(p.extend, { force: true });
     // Release the lock only now: `gdt wait` must return on the final status, never on the vanished lock.
     releaseAfterStop(p);
     return ok(`Retry prepared for #${issue}. Next: ${describe(state, false).next}\n`);
@@ -235,8 +243,15 @@ export function retry(issue, cwd, env) {
 function blockedHint(issue, reason) {
     if (reason.startsWith("round budget exhausted"))
         return `gdt allow-round ${issue}`;
-    if (reason.includes("without a visible handoff") || reason.includes("already ran"))
+    // AC-4: a turn still active at its hard limit gets more time or is stopped and run again.
+    if (isHardLimitReason(reason))
+        return `gdt extend ${issue} or gdt retry ${issue}`;
+    if (reason.includes("without a visible handoff") ||
+        reason.includes("already ran") ||
+        isTimeoutReason(reason) ||
+        isInvalidRecordReason(reason)) {
         return `gdt retry ${issue}`;
+    }
     if (reason.includes("without a Changelog update"))
         return `add a Changelog entry to issue #${issue}, or revert the body change`;
     return "resolve the cause; the supervisor checks again on every poll";
@@ -268,10 +283,54 @@ export function describe(state, supervisorAlive) {
             return { line: withReason, next: "wait" };
     }
 }
-/** The state as status and wait see it: the pause file reports `paused` until the workflow ends. */
-function effectiveState(p, state) {
+/** A `gdt extend` request for the state's in-flight turn that the supervisor has not applied yet. */
+function pendingExtension(p, state) {
+    const extension = readJson(p.extend);
+    return extension !== null && extension.key === state.inflight?.key ? extension : null;
+}
+/**
+ * The state as status and wait see it: the pause file reports `paused` until the workflow ends, and
+ * AC-5: a pending `gdt extend` reports the turn `running` with its new hard limit before the
+ * supervisor's next poll applies it.
+ */
+function effectiveState(p, state, turnTimeoutMinutes = DEFAULT_TURN_TIMEOUT_MINUTES) {
     const paused = existsSync(p.pause) && state.status !== "stopped" && state.status !== "failed";
-    return paused ? { ...state, status: "paused", reason: "" } : state;
+    if (paused)
+        return { ...state, status: "paused", reason: "" };
+    const extension = pendingExtension(p, state);
+    if (extension === null || state.inflight === null || state.status !== "blocked" || !isHardLimitReason(state.reason))
+        return state;
+    const inflight = { ...state.inflight, hard_limit: extension.hard_limit, at_hard_limit: false };
+    return { ...state, status: "running", reason: activeReason(inflight.role, turnTimeoutMinutes), inflight };
+}
+/** The workflow's turn limits, or the defaults when the config is unreadable. */
+function turnLimits(report) {
+    return report.valid
+        ? { timeout: report.workflow.turn_timeout_minutes, max: report.workflow.turn_max_minutes }
+        : { timeout: DEFAULT_TURN_TIMEOUT_MINUTES, max: DEFAULT_TURN_MAX_MINUTES };
+}
+/** `gdt extend <n>`: grants a turn blocked at its hard limit `turn_max_minutes` more from now (AC-5). */
+export function extend(issue, cwd, env) {
+    const root = findRepository(cwd) ?? cwd;
+    const p = paths(root, issue, env);
+    const state = readState(p);
+    if (state === null)
+        return fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+    const limits = turnLimits(loadConfig(root, env).report);
+    const effective = effectiveState(p, state, limits.timeout);
+    const inflight = state.inflight;
+    if (effective.status !== "blocked" ||
+        !isHardLimitReason(effective.reason) ||
+        inflight === null ||
+        readJson(p.result(inflight.key)) !== null) {
+        const { line, next } = describe(effective, lockHolder(p) !== null);
+        return fail(`Workflow for #${issue} is not waiting at a turn's hard limit (${line}). Next: ${next}\n`);
+    }
+    const hardLimit = new Date(Date.now() + limits.max * 60_000).toISOString();
+    // The supervisor applies the request on its next poll; status and wait report it at once.
+    writeJsonAtomic(p.extend, { key: inflight.key, hard_limit: hardLimit });
+    const { next } = describe(effectiveState(p, state, limits.timeout), lockHolder(p) !== null);
+    return ok(`Extended the ${inflight.role} turn of #${issue}; new hard limit ${hardLimit}. Next: ${next}\n`);
 }
 /** `gdt status <n>`. The pause file reports `paused` even before the supervisor notices it. */
 export function status(issue, cwd, env, json) {
@@ -279,18 +338,29 @@ export function status(issue, cwd, env, json) {
     const p = paths(root, issue, env);
     const state = readState(p);
     if (state === null) {
-        return json
-            ? { code: 1, stdout: `${JSON.stringify({ issue, status: null, next_step: `gdt start ${issue}` }, null, 2)}\n`, stderr: "" }
-            : fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
+        // AC-5: the same keys, null without a dispatched turn.
+        const empty = {
+            issue,
+            status: null,
+            turn_started_at: null,
+            turn_deadline: null,
+            turn_last_activity: null,
+            turn_hard_limit: null,
+            next_step: `gdt start ${issue}`,
+        };
+        return json ? { code: 1, stdout: `${JSON.stringify(empty, null, 2)}\n`, stderr: "" } : fail(`No workflow for #${issue}. Next: gdt start ${issue}\n`);
     }
-    const effective = effectiveState(p, state);
+    const { report } = loadConfig(root, env);
+    const limits = turnLimits(report);
+    const effective = effectiveState(p, state, limits.timeout);
     const { line, next } = describe(effective, lockHolder(p) !== null);
     if (!json)
         return ok(`${line}. Next: ${next}\n`);
-    let maxRounds = null;
-    const { report } = loadConfig(root, env);
-    if (report.valid)
-        maxRounds = report.workflow.max_correction_rounds;
+    const maxRounds = report.valid ? report.workflow.max_correction_rounds : null;
+    // The in-flight turn's start, deadline, last activity and hard limit. A result file ends the turn,
+    // so a turn that has finished but still awaits its handoff check reports null for all four.
+    const inflight = effective.inflight !== null && readJson(p.result(effective.inflight.key)) === null ? effective.inflight : null;
+    const turnStart = inflight?.dispatched_at ?? null;
     const out = {
         issue,
         workflow_id: state.workflow_id,
@@ -302,6 +372,11 @@ export function status(issue, cwd, env, json) {
         exit_code: state.exit_code,
         pr_number: state.pr_number,
         open_findings: state.open_findings ?? [],
+        turn_started_at: turnStart,
+        turn_deadline: turnStart === null ? null : turnDeadline(turnStart, limits.timeout).toISOString(),
+        // AC-8: null without a result-less in-flight turn.
+        turn_last_activity: inflight === null ? null : turnLastActivity(inflight),
+        turn_hard_limit: inflight === null ? null : turnHardLimit(inflight, limits.max).toISOString(),
         overrides: readOverrides(p),
         next_step: next,
     };
@@ -316,12 +391,13 @@ export function wait(issue, cwd, env, options) {
     const root = findRepository(cwd) ?? cwd;
     const p = paths(root, issue, env);
     const deadline = options.timeoutSeconds === null ? null : Date.now() + options.timeoutSeconds * 1000;
+    const turnTimeout = turnLimits(loadConfig(root, env).report).timeout;
     for (;;) {
         const state = readState(p);
         // No workflow is status's error path (AC-6); an action status returns at once (AC-1, AC-2).
         if (state === null)
             return status(issue, cwd, env, options.json);
-        const effective = effectiveState(p, state);
+        const effective = effectiveState(p, state, turnTimeout);
         if (ACTION_STATUSES.includes(effective.status))
             return status(issue, cwd, env, options.json);
         // A dead supervisor ends the wait, except while the operator paused it deliberately (AC-4).

package/package.json

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