@gevezex/gdt 0.4.0 → 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)
       │                                          ▼
@@ -122,6 +134,7 @@ evidence too.
 | `git` | the shared checkout the roles work in |
 | `gh`, logged in (`gh auth login`) | issues, pull requests, comments, checks |
 | at least one agent CLI | `claude`, `codex`, `opencode`, `mcode`, `pi` or `omp` (see below) |
+| CI on pull requests | the target repository needs at least one CI check (for example a GitHub Actions job); `workflow.required_checks` lists its name as shown on the pull request and `gdt init` detects the names. Set `workflow.allow_no_required_checks = true` only as the explicit opt-out |
 | [herdr](https://herdr.dev) 0.9.1+ | the default way to watch the roles live, one tab per role; on machines without herdr set `workflow.terminal = "headless"` |
 
 ### Agent prerequisites
@@ -159,6 +172,12 @@ npm run build
 npm link          # puts `gdt` on your PATH
 ```
 
+A linked install runs `dist/` of that checkout, so gdt runs the code you built
+there. A workflow that runs gdt on that same checkout (for example on gdt's own
+repository) can rebuild `dist/` and change the running gdt mid-workflow. Use a
+linked install only to develop gdt; to run workflows, install the published
+package with `npm i -g @gevezex/gdt`.
+
 Then install the operator skill, so your coding agent knows how to drive gdt:
 
 ```bash
@@ -168,13 +187,34 @@ gdt install-skill
 It copies `skill/SKILL.md` into the skill directory of every agent CLI it finds
 (for example `~/.claude/skills/gdt`) and is safe to run again.
 
+## Security
+
+Before the first `gdt start`, know what a role turn can do:
+
+- Every role turn runs its agent CLI **without permission prompts** and with
+  shell access to the machine. The adapters pass, for example,
+  `--permission-mode bypassPermissions` for Claude Code and
+  `--dangerously-bypass-approvals-and-sandbox` for Codex, because nobody is
+  there to answer a prompt. Run gdt only where you accept that.
+- Issue and comment text is **task data** for the roles, never instructions to
+  the supervisor. Treat an issue body or a comment as untrusted input.
+- The tester and reviewer are **checked mechanically**: after their turn the
+  supervisor verifies that HEAD, branch and the tracked files are unchanged, and
+  blocks the workflow otherwise.
+- Roles act with **your own `gh` login**. An agent-written comment is
+  indistinguishable from one you wrote; gdt never merges, deploys or closes
+  issues.
+
+The full invocation for each agent is in [docs/agents.md](docs/agents.md); the
+trust boundaries are in
+[section 10 of docs/design.md](docs/design.md#10-security-and-trust-boundaries).
+
 ## Quick start
 
-### 1. Configure the target repository
+### 1. Set up the user config once per machine
 
-In the repository you want gdt to work on, create `.gdt/config.toml` with
-`gdt init` instead of writing TOML by hand. Ask your coding agent, or run it
-yourself:
+Roles belong to you, not to a repository, so they live in your user config. Ask
+your coding agent, or run `gdt init` yourself:
 
 ```bash
 gdt init --developer opencode/deepseek/deepseek-v4-flash \
@@ -182,27 +222,35 @@ gdt init --developer opencode/deepseek/deepseek-v4-flash \
          --reviewer codex/gpt-5.6-luna
 ```
 
-`gdt init` writes the roles to your user config (`~/.config/gdt/config.toml`,
-or `$XDG_CONFIG_HOME/gdt/config.toml`), writes the project settings to
-`.gdt/config.toml`, runs `gdt doctor` and installs the operator skill. Without the
-three role options, it reuses the roles from your user config when they are all
-there; otherwise it only reports what it found (agents on `PATH`, the terminal,
-the detected CI checks) so your agent can discuss the roles with you first. It
-never overwrites an existing config without `--force`, and it requires at least
-one required check unless you pass `--allow-no-required-checks`.
+`gdt init` writes the roles to the user config (`~/.config/gdt/config.toml`, or
+`$XDG_CONFIG_HOME/gdt/config.toml`) and installs the operator skill. Run it from
+one of your checkouts: it also creates that repository's `.gdt/config.toml`, so
+that first repository is configured too. Without the three role options, it
+reuses the roles from your user config when they are all there; otherwise it
+only reports what it found (agents on `PATH`, the terminal, the detected CI
+checks) so your agent can discuss the roles with you first. It never overwrites
+an existing config without `--force`.
+
+### 2. Configure each target repository
 
-Then check your setup:
+For every other repository you want gdt to work on, create `.gdt/config.toml`
+with `gdt init` (no role options: it reuses the roles from your user config), or
+commit a file based on [`examples/config.toml`](examples/config.toml). `gdt init`
+requires at least one required check unless you pass
+`--allow-no-required-checks`.
+
+Then check your setup in that repository:
 
 ```bash
 gdt doctor
 ```
 
-`doctor` checks `git`, `gh` and its login, the agent CLIs, herdr (when used)
-and the config, and prints a `fix:` line for every problem. It also warns when
-developer and tester use the same model vendor, because the tester is less
-independent then.
+`doctor` checks `git`, `gh` and its login, the agent CLIs, herdr (when used) and
+the user, repository and local config, and prints a `fix:` line for every
+problem. It also warns when developer and tester use the same model vendor,
+because the tester is less independent then.
 
-### 2. Write the issue as a contract
+### 3. Write the issue as a contract
 
 The issue body is the only specification. It needs fixed sections and numbered
 acceptance criteria, each with Given, When, Then and a concrete Example:
@@ -251,7 +299,7 @@ gdt check-issue --body-file body.md    # a draft, without calling GitHub
 Your agent can help write the body with the issue-writer instructions in
 [`roles/issue-writer.md`](roles/issue-writer.md).
 
-### 3. Start it from your agent
+### 4. Start it from your agent
 
 Just ask your coding agent, in your own language:
 
@@ -269,7 +317,7 @@ gdt wait 251      # blocks until the workflow needs attention
 gdt status 251    # one line plus the next step
 ```
 
-### 4. Answer, steer, merge
+### 5. Answer, steer, merge
 
 | Situation | What you (or your agent) run |
 |---|---|
@@ -295,7 +343,7 @@ changes product behaviour makes the role ask for the issue body to be updated.
 | `awaiting_human` | a role asked a question | `gdt answer <n> <question-id> "<text>"` |
 | `blocked` | a gate failed or a role reported blocked; the reason says why | follow the hint, e.g. `gdt allow-round <n>` |
 | `contract_changed` | the issue body changed; evidence is reset | wait |
-| `failed` | an agent turn exited non-zero | `gdt retry <n>` |
+| `failed` | an agent turn exited non-zero | `gdt retry <n>`, then `gdt start <n>` |
 | `paused` / `stopped` | you paused or stopped it | `gdt resume <n>` / `gdt start <n>` |
 | `ready_to_merge` | all gates passed | review and merge the PR |
 
@@ -306,7 +354,7 @@ Every command supports `--help`; `status` and `wait` also support `--json`.
 | Command | Effect |
 |---|---|
 | `gdt init` | Write the roles to the user config and `.gdt/config.toml`, install the operator skill |
-| `gdt doctor` | Check tools, GitHub login, agents, herdr and `.gdt/config.toml` |
+| `gdt doctor` | Check tools, GitHub login, agents, herdr and the user, repository and local config |
 | `gdt check-issue <n>` | Validate an issue body against the contract |
 | `gdt start <n>` | Preflight, start the supervisor and workers, return |
 | `gdt status <n>` | Status, role, round, open findings and next step |
@@ -374,6 +422,26 @@ the three files empty so you can see where your rules go; commit them like
 
 How each agent CLI is invoked is documented in [docs/agents.md](docs/agents.md).
 
+## Upgrading
+
+### From 0.3 to 0.4
+
+Since 0.4.0, `[roles.*]` in `.gdt/config.toml` is an error and `gdt start`
+refuses to run. Roles now live in the user config. To upgrade:
+
+1. Move the three `[roles.*]` tables from `.gdt/config.toml` to the user config
+   at `~/.config/gdt/config.toml`, or `$XDG_CONFIG_HOME/gdt/config.toml` when
+   `XDG_CONFIG_HOME` is set.
+2. Remove the `[roles.*]` tables from `.gdt/config.toml`, so only the repository
+   settings (`[workflow]`, `[contract]`) remain.
+3. Run `gdt doctor` to check that the configuration is valid again.
+
+Instead of steps 1 and 2 you can run `gdt init --force` with the three role
+options (see [Quick start](#quick-start)). It writes the roles to the user
+config, but it also replaces `.gdt/config.toml` in the current checkout with
+freshly detected defaults, so any custom repository settings there are lost.
+Use the manual move when you have changed `[workflow]` or `[contract]`.
+
 ## Watching it: herdr or headless
 
 ```text
@@ -391,6 +459,66 @@ 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
+`terminal-notifier`, `osascript` (macOS) or `notify-send` (Linux) that is on
+`PATH` and works. If none of them is available, the notification is only
+written to `.git/gdt/issue-<n>/logs/supervisor.log`, and `gdt wait` is the way
+to be told: it blocks until the workflow needs attention.
+
+## The checkout during and after a workflow
+
+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
+("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.
+
+After `ready_to_merge`, or after `gdt stop`, two things stay behind:
+
+- the herdr workspace `gdt-<n>`, which you can close yourself in herdr;
+- the state directory `.git/gdt/issue-<n>/`, which you may delete once the pull
+  request is merged and no gdt process for that issue is running.
+
+## Troubleshooting
+
+When a turn fails or a workflow stops unexpectedly, start with:
+
+```bash
+gdt status <n>
+gdt doctor
+```
+
+`gdt status <n>` shows the status, role, round and next step; `gdt doctor`
+reports a `fix:` line for every configuration or tool problem.
+
+Everything gdt keeps for an issue is under the state directory: one log per
+process in `.git/gdt/issue-<n>/logs/`, and the prompt and result of every turn
+in `.git/gdt/issue-<n>/runs/`.
+
+- **exit code 78** means the configuration was invalid or the turn's prompt
+  could not be built. Run `gdt doctor`, fix what it reports, then
+  `gdt retry <n>` and `gdt start <n>`.
+- **any other non-zero exit code** means the agent CLI itself failed; its log
+  under `.git/gdt/issue-<n>/logs/` shows why.
+
 ## Principles
 
 - **The issue body is the contract.** Work starts only when there are no open questions.
@@ -413,7 +541,7 @@ npm ci
 npm run build
 npm run lint
 npm test
-node dist/cli.js doctor   # run inside a repository with .gdt/config.toml
+node dist/cli.js doctor   # run in a repository configured for gdt (user + repository + local config)
 ```
 
 Rules for agents working on this repository: [AGENTS.md](AGENTS.md).

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({