agent-lyceum 0.31.1 → 0.33.0

package/README.md

@@ -79,6 +79,8 @@ Folder layout, every agent field and the rules `doctor` checks: [Configuration](
 
 Older versions refuse a `team.yaml` or `project.yaml` that contains `model_tiers` (a load error, "Unrecognized key"). Before using an older binary, remove `model_tiers` from every `project.yaml` and from `team.yaml`. Other mail and run state are unaffected: older versions ignore a `tier` line in mail. See [Model tiers](docs/configuration.md#model-tiers). (Spec 24.3.2, 24.13)
 
+Likewise, older versions refuse a `project.yaml` that contains `verify` ("Unrecognized key"). Remove the `verify` block before using an older binary. Run state is unaffected. See [Verify](docs/configuration.md#verify). (Spec 27.4)
+
 ## Topics
 
 | Topic | Read |

package/README.zh-TW.md

@@ -79,6 +79,8 @@ agents:
 
 舊版程式會拒絕載入含 `model_tiers` 的 `team.yaml` 或 `project.yaml`（載入錯誤，「Unrecognized key」）。改用舊版前，請先從每個 `project.yaml` 與 `team.yaml` 拿掉 `model_tiers`。其他信件與 run 狀態不受影響：舊版會忽略信件中的 `tier` 行。見[模型分級](docs/configuration.zh-TW.md#模型分級)。（spec 24.3.2、24.13）
 
+同樣地，舊版程式會拒絕載入含 `verify` 的 `project.yaml`（「Unrecognized key」）。改用舊版前，請先拿掉 `verify` 區塊。run 狀態不受影響。見[驗證](docs/configuration.zh-TW.md#驗證verify)。（spec 27.4）
+
 ## 主題
 
 | 主題 | 閱讀 |

package/dist/cli.js

@@ -14,7 +14,7 @@ import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
 import { acquireProjectLock, forceUnlock, inspectRunLock, listRunLocks, listUnreadableRunLocks, LOCK_FILE, lockHolderAlive } from "./project-lock.js";
 import { planWorkspace } from "./worktree.js";
 import { loadRunState, newRunId, outcomeOf, resolveRun, roundLimit, roundsLabel, runLabel, slugify, uniqueName } from "./run-store.js";
-import { failureGuide } from "./run-outcome.js";
+import { printRun } from "./run-print.js";
 import { exitCodeForOutcome, RUNTIMES } from "./schema.js";
 import { absPath, assertName, NAME_RE, projectPaths, resolveHome } from "./paths.js";
 import { addProject, initHome, removeProject } from "./scaffold.js";
@@ -192,30 +192,6 @@ function cancelOnSignals() {
         },
     };
 }
-function printRun(summary, runDir) {
-    console.log(`\nRun ${runLabel({ name: summary.name, run_id: summary.runId })} ended: ${summary.endReason}, outcome: ${summary.outcome}, after ${summary.rounds} round(s). Logs: ${path.join(runDir, "log.jsonl")}`);
-    if (summary.outcomeNote)
-        console.log(`Note: ${summary.outcomeNote}`);
-    if (summary.failure)
-        console.log(failureGuide(summary.project, summary.name ?? summary.runId, summary.failure, runDir));
-    if (summary.verification)
-        console.log(`Verification (as reported by the lead, not checked by agent-lyceum): ${summary.verification}`);
-    if (summary.resultBranch?.files) {
-        console.log(`\nThe work is on branch ${summary.resultBranch.branch} (${summary.resultBranch.files} file(s)); your working tree was not touched.\nBring it in with: git merge ${summary.resultBranch.branch}${summary.resultBranch.patch ? `\n(or apply the patch: git apply ${summary.resultBranch.patch})` : ""}`);
-    }
-    if (summary.pr) {
-        if (summary.pr.status === "opened")
-            console.log(`\nPull request ${summary.pr.updated ? "updated" : "opened"}: ${summary.pr.url}`);
-        else if (summary.pr.status === "skipped")
-            console.log(`\nA pull request was asked for but not opened: ${summary.pr.reason}`);
-        else
-            console.log(`\nThe pull request could not be opened (${summary.pr.step}: ${summary.pr.reason}).${summary.pr.manual.length ? ` To finish by hand:\n${summary.pr.manual.map((m) => `  ${m}`).join("\n")}` : ""}`);
-    }
-    if (summary.doneMessage) {
-        console.log(`\nLead's final message — ${summary.doneMessage.subject}\n\n${summary.doneMessage.body}`);
-        console.log(`\nResult saved to: ${path.join(runDir, RESULT_FILE)}`);
-    }
-}
 function reportRun(summary, runDir) {
     printRun(summary, runDir);
     process.exit(exitCodeForOutcome(summary.outcome));

package/dist/config.d.ts

@@ -1,6 +1,6 @@
 import { type ProjectPaths } from "./paths.js";
 import type { AgentWorkspace } from "./worktree.js";
-import { type DispatcherSettings, type Effort, type FallbackEntry, type SandboxPartialT, type Runtime, type WebLevel } from "./schema.js";
+import { type VerifySettings, type DispatcherSettings, type Effort, type FallbackEntry, type SandboxPartialT, type Runtime, type WebLevel } from "./schema.js";
 export declare class ConfigError extends Error {
 }
 export type Source = "global" | "project" | "default" | "model";
@@ -64,6 +64,8 @@ export interface ResolvedProject {
     agents: Record<string, ResolvedAgent>;
     /** Spec 24: non-empty model ladders per runtime, lowest first (project.yaml replaces team.yaml's per runtime). */
     modelTiers: Partial<Record<Runtime, string[]>>;
+    /** Spec 27: dispatcher-run verification commands from project.yaml; absent = off. Read once when the project is loaded. */
+    verify?: VerifySettings;
     /** Which file each ladder in `modelTiers` came from. */
     modelTiersFrom: Partial<Record<Runtime, "global" | "project">>;
     paths: ProjectPaths;
@@ -128,6 +130,14 @@ export declare function loadProjectRaw(home: string, name: string): {
         "claude-code"?: string[] | undefined;
         codex?: string[] | undefined;
     } | undefined;
+    verify?: {
+        max_rejections?: number | undefined;
+        commands: {
+            name: string;
+            run: string;
+            timeout_sec?: number | undefined;
+        }[];
+    } | undefined;
     dispatcher: {
         max_rounds?: number | undefined;
         max_parallel?: unknown;

package/dist/config.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import YAML from "yaml";
 import { absPath, canonicalPath, escapesParent, expandHome, homePaths, projectPaths, } from "./paths.js";
 import { availableTiers } from "./tiers.js";
-import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, RUNTIMES, } from "./schema.js";
+import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, VERIFY_DEFAULTS, inferRuntime, RUNTIMES, } from "./schema.js";
 export class ConfigError extends Error {
 }
 function readYaml(file, schema, label) {
@@ -71,6 +71,12 @@ export function resolveProjectFrom(home, name, g, p) {
             modelTiersFrom[rt] = fromProject ? "project" : "global";
         }
     }
+    const verify = p.verify?.commands.length
+        ? {
+            max_rejections: p.verify.max_rejections ?? VERIFY_DEFAULTS.max_rejections,
+            commands: p.verify.commands.map((c) => ({ name: c.name, run: c.run, timeout_sec: c.timeout_sec ?? VERIFY_DEFAULTS.timeout_sec })),
+        }
+        : undefined;
     const agents = {};
     for (const agentName of Object.keys(p.agents)) {
         const gl = resolveLayer(g.agents[agentName], home);
@@ -201,6 +207,7 @@ export function resolveProjectFrom(home, name, g, p) {
         agents,
         modelTiers,
         modelTiersFrom,
+        ...(verify ? { verify } : {}),
         paths,
         ignoredSettings: collectIgnored(hp.globalConfig, g, paths.config, p),
     };

package/dist/doctor.js

@@ -158,6 +158,14 @@ export async function diagnoseProject(project, opts = {}) {
             ? { level: "info", subject: "pr", message: `A run cannot open a pull request (a lead asks for one with \`open_pr: true\`): ${missing.join("; ")}.` }
             : { level: "ok", subject: "pr", message: "`gh` and `origin` found: a run can open a pull request when the lead asks for one." });
     }
+    if (project.verify) {
+        const cmds = project.verify.commands.map((c) => `${c.name}: ${c.run} (timeout ${c.timeout_sec}s)`).join("; ");
+        checks.push({
+            level: "warn",
+            subject: "verify",
+            message: `Before it accepts a lead's \`completed\` done, the dispatcher runs ${project.verify.commands.length} verify command(s), up to ${project.verify.max_rejections} rejection(s): ${cmds}. They run OUTSIDE the agents' sandbox with your permissions and execute code the agents wrote, in the lead's worktree, or directly in ${project.dir} when runs do not use worktrees. Only you can change them (project.yaml).`,
+        });
+    }
     for (const lock of listRunLocks(project.paths.root)) {
         const alive = lockHolderAlive(lock);
         checks.push({

package/dist/fs-util.d.ts

@@ -1,5 +1,5 @@
 /** Atomic write: temp file in the same dir, then rename. */
-export declare function atomicWrite(file: string, content: string): void;
+export declare function atomicWrite(file: string, content: string | Buffer): void;
 /** Is `cmd` an executable file in one of the PATH directories? (No `which`: it may be missing in slim containers.) */
 export declare function findOnPath(cmd: string, pathVar?: string): boolean;
 /**

package/dist/process-runner.d.ts

@@ -15,10 +15,15 @@ export interface RunnerOptions {
 }
 /** Pids below `root` (children, grandchildren, ...) by parent links; catches descendants that left the process group (setsid, daemons). */
 export declare function descendantsOf(root: number): number[];
+/** Make a child visible to `killAllRunning` (also used by verify commands, spec 27). */
+export declare function register(pid: number): void;
+export declare function unregister(pid: number): void;
 /** Sampling interval of the descendant timer (default 2000 ms); for tests. Takes effect for the next timer. */
 export declare function setSamplerIntervalMs(ms: number): void;
 /** Whether the descendant timer is running (for tests). */
 export declare function samplerActive(): boolean;
+/** Signal the runtime's group, the descendants recorded earlier that are still in the process table, and its current descendants. */
+export declare function killTree(pid: number, sig: NodeJS.Signals): void;
 /** How many runtimes are registered as running (for tests). */
 export declare function runningCount(): number;
 /** Synchronously SIGKILL every runtime still running, with the descendants seen when it was started or last checked. Used when agent-lyceum itself is going away. */

package/dist/process-runner.js

@@ -88,7 +88,8 @@ function sample() {
         for (const d of below(kids, pid))
             seen.add(d);
 }
-function register(pid) {
+/** Make a child visible to `killAllRunning` (also used by verify commands, spec 27). */
+export function register(pid) {
     live.set(pid, new Set());
     if (!exitHook) {
         exitHook = true;
@@ -99,7 +100,7 @@ function register(pid) {
         sampler.unref();
     }
 }
-function unregister(pid) {
+export function unregister(pid) {
     live.delete(pid);
     if (!live.size && sampler) {
         clearInterval(sampler);
@@ -123,7 +124,7 @@ function signalPid(pid, sig, group) {
     }
 }
 /** Signal the runtime's group, the descendants recorded earlier that are still in the process table, and its current descendants. */
-function killTree(pid, sig) {
+export function killTree(pid, sig) {
     const kids = processTable();
     const seen = live.get(pid) ?? new Set();
     const now = below(kids, pid);

package/dist/repeat-detect.d.ts

@@ -0,0 +1,40 @@
+import type { VerifyCommandRecord, VerifyRecord } from "./run-store.js";
+/** Spec 28: has the same verify failure come back on an unchanged workspace? Pure functions except `fingerprintPaths`. */
+/** How much of a command's raw output is looked at before it is cut into lines. */
+export declare const FINGERPRINT_WINDOW_BYTES: number;
+export declare const FINGERPRINT_LINES = 100;
+/** A literal path and what it is replaced with. */
+export type PathRule = [literal: string, replacement: string];
+/** The paths of this run that should not make two outputs differ: the working directory, the run directory and the temp directory. */
+export declare function fingerprintPaths(cwd: string, runDir: string): PathRule[];
+/** The last FINGERPRINT_LINES lines of `text` with ANSI codes, overwritten progress, clock times, durations and this run's paths removed. */
+export declare function normalizeOutput(text: string, paths: PathRule[]): string;
+/** 16 hex characters over the command name, how it failed, and the normalised tail of its output. */
+export declare function failureFingerprint(c: Pick<VerifyCommandRecord, "name" | "exit" | "timed_out" | "error">, tail: string, paths: PathRule[]): string;
+export type HashRelation = "same" | "changed" | "unknown" | "no-worktree";
+export type RepeatAction = "none" | "label" | "stop" | "limit";
+export interface RepeatComparison {
+    previous?: string;
+    sameFingerprint: boolean;
+    hash: HashRelation;
+}
+/** Compared with the newest record of the last rejected `done` of this segment, never with the current one (a replay adds a second record for the same source). */
+export declare function compareWithLastRejection(a: {
+    source: string;
+    fingerprint: string;
+    hash: string | undefined;
+    worktree: boolean;
+    records: VerifyRecord[] | undefined;
+    rejected: string[] | undefined;
+}): RepeatComparison;
+/** True when this `done` was already stopped as a repeat in this segment (`segment` is the number of reopens so far). */
+export declare function stoppedInSegment(records: VerifyRecord[] | undefined, source: string, segment: number): boolean;
+export declare function repeatAction(cmp: RepeatComparison, s: {
+    counted: boolean;
+    stoppedBefore: boolean;
+    left: number;
+}): RepeatAction;
+/** The label at the top of a rejection mail; the message itself is unchanged. */
+export declare function withRepeatLabel(action: RepeatAction, hash: HashRelation, message: string): string;
+/** The outcome note when a repeated failure on an unchanged workspace is accepted as partial; `failure` is `describeFailure`'s text. */
+export declare function repeatStopNote(name: string, run: string, failure: string, log: string, used: number, max: number): string;

package/dist/repeat-detect.js

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import { stripVTControlCharacters } from "node:util";
+/** Spec 28: has the same verify failure come back on an unchanged workspace? Pure functions except `fingerprintPaths`. */
+/** How much of a command's raw output is looked at before it is cut into lines. */
+export const FINGERPRINT_WINDOW_BYTES = 256 * 1024;
+export const FINGERPRINT_LINES = 100;
+const TMP = /(?<![\w./-])(?:\/private)?(?:\/tmp|\/var\/tmp|\/var\/folders\/[^\s/]+\/[^\s/]+\/T)(?:\/[^\s:'"`()[\]<>,;]*)?/g;
+const STAMP = /(?<![\w.:-])\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}(?::?\d{2})?)?(?![\w:])/g;
+const CLOCK = /(?<![\w.:-])\d{1,2}:\d{2}:\d{2}(?:[.,]\d+)?(?![\w:])/g;
+const DUR = /(?<![\w./-])(?:\d+h\s?)?(?:\d+m\s?)?\d+(?:\.\d+)?(?:ms|µs|ns|s|secs?|seconds?|mins?|minutes?)(?![\w/-]|\.\w)/g;
+/** The paths of this run that should not make two outputs differ: the working directory, the run directory and the temp directory. */
+export function fingerprintPaths(cwd, runDir) {
+    const rules = [];
+    const add = (p, to) => {
+        if (p && !rules.some(([l]) => l === p))
+            rules.push([p, to]);
+    };
+    const real = (p) => {
+        try {
+            return fs.realpathSync.native(p);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    for (const [p, to] of [[cwd, "<cwd>"], [runDir, "<run-dir>"], [os.tmpdir(), "/tmp"]]) {
+        add(p, to);
+        const r = real(p);
+        if (r)
+            add(r, to);
+    }
+    return rules;
+}
+const PATH_NEXT = /[\w.-]/;
+/** Replace each literal that is not directly followed by a name character (`/w/x` does not eat `/w/x2` or `/w/x.bak`). */
+function replacePaths(line, paths) {
+    let s = line;
+    for (const [literal, to] of [...paths].sort((a, b) => b[0].length - a[0].length)) {
+        if (!literal || literal === to)
+            continue;
+        let out = "";
+        let from = 0;
+        for (;;) {
+            const i = s.indexOf(literal, from);
+            if (i < 0)
+                break;
+            const next = s[i + literal.length];
+            out += s.slice(from, i);
+            if (next !== undefined && PATH_NEXT.test(next))
+                out += literal;
+            else
+                out += to;
+            from = i + literal.length;
+        }
+        s = out + s.slice(from);
+    }
+    return s;
+}
+/** The last FINGERPRINT_LINES lines of `text` with ANSI codes, overwritten progress, clock times, durations and this run's paths removed. */
+export function normalizeOutput(text, paths) {
+    const lines = stripVTControlCharacters(text)
+        .split("\n")
+        .map((l) => {
+        const noCr = l.replace(/\r+$/, "");
+        return noCr.slice(noCr.lastIndexOf("\r") + 1).trimEnd();
+    });
+    while (lines.length && lines[lines.length - 1] === "")
+        lines.pop();
+    return lines
+        .slice(-FINGERPRINT_LINES)
+        .map((l) => replacePaths(l, paths).replace(TMP, "<tmp>").replace(STAMP, "<time>").replace(CLOCK, "<time>").replace(DUR, "<duration>"))
+        .join("\n");
+}
+/** 16 hex characters over the command name, how it failed, and the normalised tail of its output. */
+export function failureFingerprint(c, tail, paths) {
+    const status = c.error ? `error:${normalizeOutput(c.error, paths)}` : c.timed_out ? "timeout" : c.exit === null ? "signal" : `exit:${c.exit}`;
+    return createHash("sha256").update(`${c.name}\0${status}\0${normalizeOutput(tail, paths)}`).digest("hex").slice(0, 16);
+}
+/** Compared with the newest record of the last rejected `done` of this segment, never with the current one (a replay adds a second record for the same source). */
+export function compareWithLastRejection(a) {
+    const records = a.records ?? [];
+    let last;
+    for (let i = records.length - 1; i >= 0; i--) {
+        const r = records[i];
+        if (r.source !== a.source && (a.rejected ?? []).includes(r.source)) {
+            last = r;
+            break;
+        }
+    }
+    const prev = last?.commands.find((c) => typeof c.fingerprint === "string")?.fingerprint;
+    const hash = !a.worktree ? "no-worktree" : a.hash === undefined || last?.diff_hash === undefined ? "unknown" : a.hash === last.diff_hash ? "same" : "changed";
+    return { ...(last ? { previous: last.source } : {}), sameFingerprint: prev !== undefined && prev === a.fingerprint, hash };
+}
+/** True when this `done` was already stopped as a repeat in this segment (`segment` is the number of reopens so far). */
+export function stoppedInSegment(records, source, segment) {
+    return (records ?? []).some((r) => r.source === source && r.repeat_stop_segment === segment);
+}
+export function repeatAction(cmp, s) {
+    if (s.counted)
+        return cmp.sameFingerprint ? "label" : "none";
+    if (s.stoppedBefore)
+        return "stop";
+    if (s.left <= 0)
+        return "limit";
+    if (!cmp.sameFingerprint)
+        return "none";
+    return cmp.hash === "same" ? "stop" : "label";
+}
+/** The label at the top of a rejection mail; the message itself is unchanged. */
+export function withRepeatLabel(action, hash, message) {
+    if (action !== "label")
+        return message;
+    const changed = hash === "changed" ? " The workspace changed since then, but this result did not." : "";
+    return `**Same failure as your last rejected \`done\`** (same command, same exit status, same last lines of output; times and paths ignored).${changed}\n\n${message}`;
+}
+/** The outcome note when a repeated failure on an unchanged workspace is accepted as partial; `failure` is `describeFailure`'s text. */
+export function repeatStopNote(name, run, failure, log, used, max) {
+    return `Verification stopped early: \`${name}\` (\`${run}\`) ${failure}; this is the same failure as the last rejected attempt and the workspace has not changed since, so no progress is likely and the \`done\` was not sent back again (${used} of ${max} rejection(s) used); see ${log}. Reported as partial; the lead's report is kept as written.`;
+}

package/dist/run-outcome.d.ts

@@ -7,7 +7,11 @@ export interface UnintegratedWork {
     report: string;
 }
 /** What a lead's `done` amounts to: its declared outcome, unless the contract is broken or member work never reached the repo. */
-export declare function resolveDoneOutcome(contract: DoneContract, rejections: number, unintegrated: UnintegratedWork[]): {
+export declare function resolveDoneOutcome(contract: DoneContract, rejections: number, unintegrated: UnintegratedWork[], 
+/** Spec 27/28: a verify command failed and no rejections were left, or the same failure repeated on an unchanged workspace; `note` says which and how. */
+verifyFailure?: {
+    note: string;
+}): {
     outcome: RunOutcome;
     note?: string;
     verification?: string;

package/dist/run-outcome.js

@@ -1,6 +1,8 @@
 import path from "node:path";
 /** What a lead's `done` amounts to: its declared outcome, unless the contract is broken or member work never reached the repo. */
-export function resolveDoneOutcome(contract, rejections, unintegrated) {
+export function resolveDoneOutcome(contract, rejections, unintegrated, 
+/** Spec 27/28: a verify command failed and no rejections were left, or the same failure repeated on an unchanged workspace; `note` says which and how. */
+verifyFailure) {
     const ok = contract.missing.length === 0;
     let outcome = ok ? (contract.outcome ?? "partial") : "partial";
     let note = ok ? undefined : `Completion contract not met after ${rejections} reminder(s): missing ${contract.missing.join("; ")}. Reported as partial; the lead's report is kept as written.`;
@@ -8,6 +10,12 @@ export function resolveDoneOutcome(contract, rejections, unintegrated) {
         outcome = "blocked";
         note = `Not completed: work of ${unintegrated.map((b) => `${b.agent} (branch ${b.branch})`).join(", ")} was never brought into the repo; see ${unintegrated.map((b) => b.report).join(", ")}.`;
     }
+    if (verifyFailure) {
+        // blocked (work never reached the repo) is the worse verdict and stays; the note names both
+        if (outcome === "completed")
+            outcome = "partial";
+        note = note ? `${note} ${verifyFailure.note}` : verifyFailure.note;
+    }
     return { outcome, note, verification: contract.verification };
 }
 /** How a run turned out, from why it stopped (`done` carries the lead's own verdict). */

package/dist/run-print.d.ts

@@ -0,0 +1,3 @@
+import { type RunSummary } from "./dispatcher.js";
+/** What a finished run prints on the terminal. */
+export declare function printRun(summary: RunSummary, runDir: string): void;

package/dist/run-print.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { RESULT_FILE } from "./dispatcher.js";
+import { failureGuide } from "./run-outcome.js";
+import { runLabel } from "./run-store.js";
+/** What a finished run prints on the terminal. */
+export function printRun(summary, runDir) {
+    console.log(`\nRun ${runLabel({ name: summary.name, run_id: summary.runId })} ended: ${summary.endReason}, outcome: ${summary.outcome}, after ${summary.rounds} round(s). Logs: ${path.join(runDir, "log.jsonl")}`);
+    if (summary.outcomeNote)
+        console.log(`Note: ${summary.outcomeNote}`);
+    if (summary.failure)
+        console.log(failureGuide(summary.project, summary.name ?? summary.runId, summary.failure, runDir));
+    if (summary.verification)
+        console.log(summary.dispatcherVerification ? `Verification (the lead's own report): ${summary.verification}` : `Verification (as reported by the lead, not checked by agent-lyceum): ${summary.verification}`);
+    if (summary.dispatcherVerification)
+        console.log(`Dispatcher verification (run by agent-lyceum): ${summary.dispatcherVerification.text}`);
+    if (summary.resultBranch?.files) {
+        console.log(`\nThe work is on branch ${summary.resultBranch.branch} (${summary.resultBranch.files} file(s)); your working tree was not touched.\nBring it in with: git merge ${summary.resultBranch.branch}${summary.resultBranch.patch ? `\n(or apply the patch: git apply ${summary.resultBranch.patch})` : ""}`);
+    }
+    if (summary.pr) {
+        if (summary.pr.status === "opened")
+            console.log(`\nPull request ${summary.pr.updated ? "updated" : "opened"}: ${summary.pr.url}`);
+        else if (summary.pr.status === "skipped")
+            console.log(`\nA pull request was asked for but not opened: ${summary.pr.reason}`);
+        else
+            console.log(`\nThe pull request could not be opened (${summary.pr.step}: ${summary.pr.reason}).${summary.pr.manual.length ? ` To finish by hand:\n${summary.pr.manual.map((m) => `  ${m}`).join("\n")}` : ""}`);
+    }
+    if (summary.doneMessage) {
+        console.log(`\nLead's final message — ${summary.doneMessage.subject}\n\n${summary.doneMessage.body}`);
+        console.log(`\nResult saved to: ${path.join(runDir, RESULT_FILE)}`);
+    }
+}

package/dist/run-session.d.ts

@@ -23,6 +23,11 @@ export interface RunSummary {
     outcome: RunOutcome;
     outcomeNote?: string;
     verification?: string;
+    /** Spec 27: the dispatcher's own verification of this done, when `verify` is configured and ran. */
+    dispatcherVerification?: {
+        passed: boolean;
+        text: string;
+    };
     doneMessage?: {
         subject: string;
         body: string;
@@ -68,6 +73,11 @@ export interface RunOptions {
      * shared memory), or undefined. Asked before activation, after an instance is created and when a run is resumed. Tests inject one.
      */
     instanceCheck?: (role: string, k: number) => string | undefined;
+    /** Spec 27: kill grace and pipe wait of verify commands (milliseconds); tests shorten them. */
+    verifyTiming?: {
+        killGraceMs?: number;
+        settleWaitMs?: number;
+    };
 }
 export declare class RunSession {
     private readonly opts;
@@ -107,6 +117,8 @@ export declare class RunSession {
     /** Models cooling down after a rate limit or quota error; one table for the run, shared by parallel wake-ups. */
     private readonly cooldowns;
     private doneVerification;
+    /** What the dispatcher's own verification of the accepted done came to (spec 27); set only when it ran. */
+    private dispatcherVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     private openPrRequested;
     private readonly prRunner;
@@ -162,6 +174,12 @@ export declare class RunSession {
     private refuseMember;
     /** After a batch (or, on resume, before the first one): revert guarded edits, route mail, detect done / lead failure. */
     private settle;
+    /**
+     * Run the project's verify commands on a completed `done` (spec 27). `passed`: accept; `exhausted`: accept as partial;
+     * `rejected`: sent back to the lead (the done file is set aside); `cancelled`: no verdict, the done file stays in the outbox.
+     * The commands are `project.verify` as loaded when this process started (project.yaml is not read again during a run).
+     */
+    private verifyDone;
     /** The user answered: send each asker its answers as a `reply`, then mark them delivered. Safe to repeat after a crash. */
     private deliverAnswers;
     /** Store the questions of this pass's valid `ask` mails; malformed ones go back to their sender. Returns true when the run should now wait. */