@gevezex/gdt 0.2.0

package/dist/supervisor.js

@@ -0,0 +1,369 @@
+import { createHash } from "node:crypto";
+import { existsSync, rmSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+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 { comments, issueSnapshot, pullRequest, repository, viewer } from "./github.js";
+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";
+/** AC-4: the herdr agent state reported for each role pane state. */
+const ROLE_PANE_STATE = {
+    RUNNING: "working",
+    WAITING: "idle",
+    DONE: "idle",
+    FAILED: "blocked",
+};
+/** AC-5: the herdr agent state reported for the supervisor pane, by workflow status. */
+export function supervisorAgentState(status) {
+    if (status === "awaiting_human" || status === "blocked" || status === "failed")
+        return "blocked";
+    if (status === "ready_to_merge" || status === "stopped" || status === "paused")
+        return "idle";
+    return "working";
+}
+export function cliPath() {
+    return fileURLToPath(new URL("./cli.js", import.meta.url));
+}
+export function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+/** 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];
+    if (decision.question_id !== undefined)
+        parts.push(decision.question_id);
+    return parts.join(".");
+}
+function roleOf(record) {
+    switch (record.kind) {
+        case "handoff":
+            return "developer";
+        case "test":
+            return "tester";
+        case "review":
+            return "reviewer";
+        case "question":
+            return record.data.role;
+        default:
+            return null;
+    }
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+function log(line) {
+    process.stdout.write(`${logTimestamp()} ${line}\n`);
+}
+class Supervisor {
+    p;
+    issue;
+    config;
+    locale;
+    env;
+    state;
+    backend;
+    trusted = [];
+    reportWarned = false;
+    agents;
+    constructor(p, issue, config, locale, env, state, backend) {
+        this.p = p;
+        this.issue = issue;
+        this.config = config;
+        this.locale = locale;
+        this.env = env;
+        this.state = state;
+        this.backend = backend;
+        this.agents = Object.fromEntries(ROLES.map((role) => [role, config.roles[role].agent]));
+    }
+    save() {
+        writeState(this.p, this.state);
+    }
+    /** AC-5: the title of a role pane, for example `developer · opencode · RUNNING`. */
+    roleTitle(role, state) {
+        return `${role} · ${this.agents[role]} · ${state}`;
+    }
+    /**
+     * AC-4/AC-5: reports a pane's agent state to the backend. AC-6: a failing report never affects the
+     * workflow, and only the first failure is logged.
+     */
+    reportState(name, state) {
+        try {
+            this.backend.reportState(name, state);
+        }
+        catch (err) {
+            if (this.reportWarned)
+                return;
+            this.reportWarned = true;
+            log(`warning: herdr state report failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /** AC-4: sets a role pane's title and reports the matching herdr agent state. */
+    setRoleState(role, state) {
+        this.backend.setTitle(role, this.roleTitle(role, state));
+        this.reportState(role, ROLE_PANE_STATE[state]);
+    }
+    /** Records a status; notifies once when entering a notifying status. */
+    setStatus(status, reason, extra = {}) {
+        if (this.state.status !== status || this.state.reason !== reason)
+            log(`status ${status}${reason === "" ? "" : `: ${reason}`}`);
+        Object.assign(this.state, { status, reason }, extra);
+        this.backend.setTitle("supervisor", `supervisor · ${status}`);
+        this.reportState("supervisor", supervisorAgentState(status));
+        if (NOTIFY_STATUSES.includes(status)) {
+            if (this.state.notified_status !== status) {
+                const used = notify(`gdt #${this.issue}: ${status}`, reason === "" ? status : reason, this.env, log);
+                log(`notified via ${used}`);
+                this.state.notified_status = status;
+            }
+        }
+        else {
+            this.state.notified_status = null;
+        }
+        this.save();
+    }
+    startWorkers() {
+        this.backend.ensureWorkspace();
+        this.backend.setTitle("supervisor", "supervisor · starting");
+        this.reportState("supervisor", supervisorAgentState(this.state.status));
+        for (const role of ROLES) {
+            this.setRoleState(role, "WAITING");
+            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]);
+        }
+        this.save();
+    }
+    init() {
+        this.trusted = [viewer(this.p.root, this.env)];
+        this.state.repository = repository(this.p.root, this.env);
+    }
+    /** One poll. Returns "exit" when the supervisor must stop. */
+    tick(now) {
+        // `gdt pause` sets this file; `gdt resume` removes it. While it exists no turn is dispatched.
+        if (existsSync(this.p.pause)) {
+            this.setStatus("paused", "", { role: 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) ?? "";
+        const known = this.state.contract;
+        if (known !== null && known.sha256 !== bodySha) {
+            if (known.changelog === changelog) {
+                this.setStatus("blocked", "issue body changed without a Changelog update");
+                return "continue";
+            }
+            this.state.contract = { sha256: bodySha, changelog };
+            this.setStatus("contract_changed", "issue body and Changelog changed; evidence reset");
+            return "continue";
+        }
+        if (known === null)
+            this.state.contract = { sha256: bodySha, changelog };
+        const contract = validateContract(body, this.locale, { maxAcceptanceCriteria: this.config.contract.max_acceptance_criteria });
+        if (!contract.valid) {
+            this.setStatus("blocked", `issue contract invalid: ${contract.errors.join("; ")}`);
+            return "continue";
+        }
+        // A turn in flight: nothing to fetch until its worker has reported.
+        const running = this.state.inflight;
+        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.
+                this.setStatus("blocked", `${running.role} finished without a visible handoff`, { role: running.role, round: running.round });
+                return "continue";
+            }
+            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.
+            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];
+        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) {
+                this.state.head_transition_at = now.toISOString();
+                log(`head ${this.state.head} -> ${pr.head}`);
+            }
+            this.state.head = pr.head;
+        }
+        this.state.pr_number = pr?.number ?? null;
+        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 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`);
+                if (inflight.checks >= this.config.workflow.handoff_checks) {
+                    inflight.missing = true;
+                    this.setStatus("blocked", `${inflight.role} finished without a visible handoff`);
+                }
+                else {
+                    this.setStatus("running", `waiting for the ${inflight.role} handoff to become visible`, { role: inflight.role, round: inflight.round });
+                }
+                return "continue";
+            }
+            this.state.inflight = null;
+        }
+        const snapshot = {
+            repository: this.state.repository,
+            issue: this.issue,
+            records,
+            trusted_authors: this.trusted,
+            pr,
+            issue_body_sha256: bodySha,
+            acceptance_criteria: contract.acceptance_criteria,
+            head_transition_at: this.state.head_transition_at,
+            config: this.config.workflow,
+        };
+        this.state.open_findings = openFindings(snapshot);
+        const decision = decide(snapshot);
+        if (decision.action !== "dispatch") {
+            this.setStatus(decision.action, decision.reason, { role: null });
+            // AC-7: on completion the workers exit on their own when they see `ready_to_merge`; in herdr
+            // mode the supervisor exits too, after printing the completion line as its final output.
+            if (decision.action === "ready_to_merge" && this.config.workflow.terminal === "herdr")
+                return "exit";
+            return "continue";
+        }
+        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`, {
+                role: decision.role,
+                round: decision.round,
+                blocked_key: key,
+            });
+            return "continue";
+        }
+        const afterCommentId = Math.max(0, ...thread.map((c) => c.id));
+        const cursor = (this.state.directive_cursor ??= {});
+        const directives = pendingDirectives(records, this.trusted, decision.role, cursor[decision.role] ?? 0);
+        const dispatch = {
+            key,
+            issue: this.issue,
+            repository: this.state.repository,
+            role: decision.role,
+            round: decision.round,
+            pr_number: pr?.number ?? null,
+            head: pr?.head ?? null,
+            issue_body_sha256: bodySha,
+            acceptance_criteria: contract.acceptance_criteria,
+            language: this.config.language,
+            directives,
+            dispatched_at: now.toISOString(),
+        };
+        // 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.
+        writeJsonAtomic(this.p.dispatch(decision.role), dispatch);
+        this.state.dispatched.push(key);
+        cursor[decision.role] = afterCommentId;
+        this.state.inflight = {
+            key,
+            role: decision.role,
+            round: decision.round,
+            dispatched_at: dispatch.dispatched_at,
+            after_comment_id: afterCommentId,
+            checks: 0,
+            missing: false,
+        };
+        this.setRoleState(decision.role, "RUNNING");
+        this.setStatus("running", `dispatched ${decision.role}: ${decision.reason}`, { role: decision.role, round: decision.round, exit_code: null });
+        log(`dispatched ${key}`);
+        return "continue";
+    }
+}
+/** Runs the supervisor loop for `issue` until a failed turn or a signal. Returns the process exit code. */
+export async function supervise(root, issue, env) {
+    const p = paths(root, issue, env);
+    const holder = acquireLock(p);
+    if (holder !== null) {
+        log(`Supervisor for #${issue} is already running (pid ${holder})`);
+        return 1;
+    }
+    const release = () => rmSync(p.lock, { force: true });
+    process.on("SIGTERM", () => {
+        // AC-6: the pane's last output line explains how to resume.
+        process.stdout.write(`gdt stopped. Resume with: gdt start ${issue}\n`);
+        // The lock stays in place: `gdt stop`/`gdt retry` release it only after writing the final state.
+        // If this handler removed it first, a concurrent `gdt wait` could see the lock vanish while the
+        // state is still a waiting status and report a dead supervisor for a deliberate stop.
+        process.exit(143);
+    });
+    const { report } = loadConfig(root, env);
+    const state = readState(p);
+    if (!report.valid || state === null) {
+        log(report.valid ? "no state; run gdt start" : "invalid config; run gdt doctor");
+        release();
+        return 1;
+    }
+    state.pids.supervisor = process.pid;
+    writeState(p, state);
+    const backend = backendFor(report, root, issue, env, p);
+    const supervisor = new Supervisor(p, issue, report, loadLocale(report.language), env, state, backend);
+    log(`supervisor ${process.pid} for #${issue}, workflow ${state.workflow_id}`);
+    try {
+        supervisor.init();
+        supervisor.startWorkers();
+    }
+    catch (err) {
+        log(`startup failed: ${err instanceof Error ? err.message : String(err)}`);
+        release();
+        return 1;
+    }
+    for (;;) {
+        try {
+            if (supervisor.tick(new Date()) === "exit")
+                break;
+        }
+        catch (err) {
+            // GitHub or network trouble: log and try again on the next poll.
+            log(`poll failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        await sleep(report.workflow.poll_seconds * 1000);
+    }
+    // AC-7: the completion line is the pane's final output, so it is written after the last log line.
+    if (report.workflow.terminal === "herdr" && readState(p)?.status === "ready_to_merge") {
+        process.stdout.write(`Workflow complete: #${issue} is ready to merge. This pane can be closed.\n`);
+    }
+    else {
+        log("supervisor exiting");
+    }
+    release();
+    return 0;
+}

package/dist/worker.js

@@ -0,0 +1,232 @@
+import { spawn } from "node:child_process";
+import { closeSync, existsSync, mkdirSync, openSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { adapterFor } from "./agents/index.js";
+import { loadConfig, TEST_AGENT, testAgentsEnabled } from "./config.js";
+import { changedFiles, checkout } from "./git.js";
+import { buildPrompt } from "./prompts.js";
+import { alive, logTimestamp, paths, readJson, readOverrides, readState, writeJsonAtomic } from "./state.js";
+/** The clear-screen sequence: it erases the visible screen and keeps the scrollback (AC-1). */
+export const CLEAR_SCREEN = "\x1b[2J";
+/** Resets colours, so the agent's output follows in normal colours (AC-3). */
+export const RESET_COLOURS = "\x1b[0m";
+/** SGR 2, dim; the waiting line uses it (AC-2). */
+export const DIM = "\x1b[2m";
+/** AC-2: the one dim line a waiting role pane shows. */
+export function waitingLine(role, last) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const detail = last === undefined ? "no turn yet" : `last turn ${last.state} ${pad(last.at.getHours())}:${pad(last.at.getMinutes())}`;
+    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) {
+    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`);
+        return { argv: ["/bin/sh", resolve(root, role.script)], env: { GDT_PROMPT_FILE: promptFile }, stdin: null };
+    }
+    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);
+}
+function log(line) {
+    process.stdout.write(`${logTimestamp()} ${line}\n`);
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+/** The turn's agent process, so a stop can end it with the worker. */
+let activeAgent = null;
+/** AC-6: stops the running agent (and its own children) before the worker exits. */
+function killAgent() {
+    const child = activeAgent;
+    if (child === null || child.pid === undefined)
+        return;
+    try {
+        process.kill(-child.pid, "SIGTERM");
+    }
+    catch {
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Already gone.
+        }
+    }
+}
+export function stopLine(issue) {
+    return `gdt stopped. Resume with: gdt start ${issue}`;
+}
+export function completeLine(issue) {
+    return `Workflow complete: #${issue} is ready to merge. This pane can be closed.`;
+}
+/** A tester or reviewer must leave tracked files, the branch and HEAD as they were. */
+export function boundaryViolation(role, before, root, env) {
+    if (role === "developer")
+        return undefined;
+    const changed = changedFiles(root, env, false);
+    if (changed.length > 0)
+        return `${role} changed tracked files: ${changed.join(", ")}`;
+    const after = checkout(root, env);
+    const name = (branch) => (branch === "" ? "(detached)" : branch);
+    if (after.branch !== before.branch)
+        return `${role} switched branch from ${name(before.branch)} to ${name(after.branch)}`;
+    if (after.head !== before.head)
+        return `${role} moved HEAD from ${before.head} to ${after.head}`;
+    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) {
+    const [command, ...args] = inv.argv;
+    return new Promise((done) => {
+        let stdin = "ignore";
+        try {
+            if (inv.stdin !== null)
+                stdin = openSync(inv.stdin, "r");
+        }
+        catch (err) {
+            log(`cannot open prompt file: ${err instanceof Error ? err.message : String(err)}`);
+            done(66);
+            return;
+        }
+        // Its own process group, so a stop can end the agent and the children it started.
+        const child = spawn(command ?? "", args, {
+            cwd,
+            env: { ...env, ...inv.env },
+            stdio: [stdin, "inherit", "inherit"],
+            detached: true,
+        });
+        activeAgent = child;
+        const close = () => {
+            if (typeof stdin === "number")
+                closeSync(stdin);
+        };
+        child.on("error", (err) => {
+            activeAgent = null;
+            log(`agent could not start: ${err.message}`);
+            close();
+            done(127);
+        });
+        child.on("close", (code) => {
+            activeAgent = null;
+            close();
+            done(code);
+        });
+    });
+}
+async function turn(root, role, dispatch, env, p) {
+    let outcome = { state: "FAILED", at: new Date() };
+    const finish = (exit_code, violation) => {
+        const result = { key: dispatch.key, exit_code, finished_at: new Date().toISOString() };
+        if (violation !== undefined)
+            result.violation = violation;
+        writeJsonAtomic(p.result(dispatch.key), result);
+        outcome = { state: exit_code === 0 ? "DONE" : "FAILED", at: new Date() };
+        log(`turn ${dispatch.key} finished with exit code ${exit_code}`);
+        return outcome;
+    };
+    const started = p.started(dispatch.key);
+    mkdirSync(dirname(started), { recursive: true });
+    try {
+        // Exclusive create: at most one run per dispatch key, even across restarts.
+        writeFileSync(started, `${process.pid}\n`, { flag: "wx" });
+    }
+    catch {
+        // Started before but never finished: the earlier run was interrupted. Never run it again.
+        return finish(null);
+    }
+    const { report } = loadConfig(root, env);
+    if (!report.valid) {
+        log("invalid config; run gdt doctor");
+        return finish(78);
+    }
+    const promptFile = p.prompt(dispatch.key);
+    try {
+        writeFileSync(promptFile, buildPrompt(role, dispatch, { root, extraRules: report.contract.extra_rules }));
+    }
+    catch (err) {
+        log(`cannot build the prompt: ${err instanceof Error ? err.message : String(err)}`);
+        return finish(78);
+    }
+    // A `gdt set-agent` override wins over `.gdt/config.toml` for this role from this turn on.
+    const override = readOverrides(p)[role];
+    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);
+    }
+    catch (err) {
+        log(err instanceof Error ? err.message : String(err));
+        return finish(127);
+    }
+    log(`turn ${dispatch.key}: ${inv.argv.join(" ")}`);
+    const turnEnv = {
+        ...env,
+        GDT_ISSUE: String(dispatch.issue),
+        GDT_REPOSITORY: dispatch.repository,
+        GDT_ROLE: role,
+        GDT_ROUND: String(dispatch.round),
+        GDT_PR: dispatch.pr_number === null ? "" : String(dispatch.pr_number),
+        GDT_HEAD: dispatch.head ?? "",
+        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);
+    const violation = boundaryViolation(role, before, root, env);
+    if (violation !== undefined)
+        log(violation);
+    return finish(exitCode, violation);
+}
+/** Waits for dispatches for `role` without a model and runs one agent turn per dispatch key. */
+export async function work(root, issue, role, env) {
+    const p = paths(root, issue, env);
+    process.on("SIGTERM", () => {
+        killAgent();
+        process.stdout.write(`${stopLine(issue)}\n`);
+        process.exit(143);
+    });
+    log(`${role} worker ${process.pid} for #${issue} waiting`);
+    // In headless mode the workers keep waiting after ready_to_merge, as the supervisor does.
+    const { report } = loadConfig(root, env);
+    const herdr = report.valid && report.workflow.terminal === "herdr";
+    /** AC-1/AC-2: clears the pane and shows the dim waiting line; only herdr panes get escapes (AC-7). */
+    const showWaiting = (last) => {
+        if (herdr)
+            process.stdout.write(`${CLEAR_SCREEN}${waitingLine(role, last)}\n`);
+    };
+    /** The last turn of this role, so a restarted worker names it instead of claiming none ran. */
+    const finished = (dispatch) => {
+        const result = dispatch === null ? null : readJson(p.result(dispatch.key));
+        return result === null ? undefined : { state: result.exit_code === 0 ? "DONE" : "FAILED", at: new Date(result.finished_at) };
+    };
+    let last = finished(readJson(p.dispatch(role)));
+    showWaiting(last);
+    for (;;) {
+        const state = readState(p);
+        // AC-7: the workflow is done; the final line explains that this pane can be closed.
+        if (herdr && state !== null && state.status === "ready_to_merge") {
+            log(`${role} worker exiting (workflow ${state.status})`);
+            process.stdout.write(`${completeLine(issue)}\n`);
+            return 0;
+        }
+        if (state === null || state.status === "failed" || state.status === "stopped" || !alive(state.pids.supervisor)) {
+            log(`${role} worker exiting (workflow ${state?.status ?? "missing"})`);
+            // AC-6: a worker that is alive when its workflow stops (or its supervisor disappears)
+            // explains how to resume. A failed turn keeps its error and prints nothing extra.
+            if (state !== null && state.status !== "failed")
+                process.stdout.write(`${stopLine(issue)}\n`);
+            return 0;
+        }
+        const dispatch = readJson(p.dispatch(role));
+        if (dispatch !== null && !existsSync(p.result(dispatch.key))) {
+            // AC-3: a starting turn clears the pane and resets colours before the agent's output.
+            if (herdr)
+                process.stdout.write(`${CLEAR_SCREEN}${RESET_COLOURS}`);
+            last = await turn(root, role, dispatch, env, p);
+            showWaiting(last);
+        }
+        await sleep(250);
+    }
+}