agent-lyceum 0.31.1 → 0.32.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. */

package/dist/run-session.js

@@ -3,6 +3,8 @@ import path from "node:path";
 import { invokeWithSandboxChecks } from "./sandbox-invocation.js";
 import { realInvoker } from "./adapters/index.js";
 import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, deferredAttempts, planAttempts, runWithFallback } from "./fallback.js";
+import { compareWithLastRejection, repeatAction, repeatStopNote, stoppedInSegment, withRepeatLabel } from "./repeat-detect.js";
+import { commandPassed, describeFailure, rejectionMessage, runVerify, verificationSection } from "./verify.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
 import { listRunLocks, lockHolderAlive } from "./project-lock.js";
@@ -18,6 +20,7 @@ import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
 import { collectDrafts, priorFailedAttempts, redoUserPrompt } from "./redo.js";
 import { atomicWrite, readFileCapped } from "./fs-util.js";
 import { assertWorktreeRunnable, collectAgentChanges, dirtyPaths, existingAgentWorkspace, finishLeadBranch, integrateAgentChanges, prepareAgentWorkspace, recutLeadWorkspace, refusedIntegration, snapshotBase, snapshotHead, toplevel } from "./worktree.js";
+import { workingTreeHash } from "./worktree.js";
 import { bindRunProject, newRunId, newRunState, roundLimit, roundsLabel, saveRunState } from "./run-store.js";
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
@@ -119,6 +122,8 @@ export class RunSession {
     /** Models cooling down after a rate limit or quota error; one table for the run, shared by parallel wake-ups. */
     cooldowns;
     doneVerification;
+    /** What the dispatcher's own verification of the accepted done came to (spec 27); set only when it ran. */
+    dispatcherVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     openPrRequested = false;
     prRunner;
@@ -213,6 +218,8 @@ export class RunSession {
                 state.max_rounds = roundLimit(state, cfg.max_rounds);
                 state.result_branch = undefined;
                 state.done_rejections = 0;
+                state.verify_rejections = undefined;
+                state.verify_rejected = undefined;
                 // The progress so far stays shown: the follow-up's own steps are added after it.
                 state.step_base = resume.steps;
                 if (recut && resume.pr_url) {
@@ -862,7 +869,7 @@ export class RunSession {
         this.saveState();
     }
     /** After a batch (or, on resume, before the first one): revert guarded edits, route mail, detect done / lead failure. */
-    settle(batch, results) {
+    async settle(batch, results) {
         const { say, runDir, project, log, state, guard, claims, attempts } = this;
         const violations = guard.check(batch);
         for (const v of violations) {
@@ -913,6 +920,23 @@ export class RunSession {
                 contract = undefined;
             }
         }
+        // Spec 27: a completed done that met the contract is judged by the project's verify commands (the contract came first).
+        let verified;
+        if (route.done && contract && contract.missing.length === 0 && contract.outcome === "completed" && project.verify) {
+            const v = await this.verifyDone(route.done, project.verify);
+            if (v.kind === "cancelled") {
+                // No verdict: the done stays in the outbox (routed again on resume); the rest of this settle still runs.
+                route.done = undefined;
+                contract = undefined;
+                this.endReason = "cancelled";
+            }
+            else if (v.kind === "rejected") {
+                route.done = undefined;
+                contract = undefined;
+            }
+            else
+                verified = v;
+        }
         this.noteTierIgnored(route);
         const askAccepted = this.handleAsks(route);
         for (const d of route.delivered)
@@ -961,11 +985,16 @@ export class RunSession {
             }
             this.doneMessage = { subject: route.done.subject, body: route.done.body };
             this.openPrRequested = route.done.meta.open_pr === true;
-            const resolved = resolveDoneOutcome(must(contract, "completion contract of the done report"), state.done_rejections ?? 0, state.blocked_integrations ?? []);
+            const resolved = resolveDoneOutcome(must(contract, "completion contract of the done report"), state.done_rejections ?? 0, state.blocked_integrations ?? [], verified?.failure);
             this.doneOutcome = resolved.outcome;
             this.doneNote = resolved.note;
             this.doneVerification = resolved.verification;
-            const report = `# ${route.done.subject}\n\n**Outcome:** ${this.doneOutcome}${this.doneNote ? ` (${this.doneNote})` : ""}\n\n${route.done.body.trimEnd()}\n`;
+            if (verified) {
+                const bad = verified.record.commands.find((c) => !commandPassed(c));
+                const spec = bad ? project.verify?.commands.find((c) => c.name === bad.name) : undefined;
+                this.dispatcherVerification = bad ? { passed: false, text: `FAILED: ${bad.name} (${spec?.run ?? "?"}) ${describeFailure(bad, spec?.timeout_sec)}` } : { passed: true, text: `passed (${verified.record.commands.map((c) => c.name).join(", ")})` };
+            }
+            const report = `# ${route.done.subject}\n\n**Outcome:** ${this.doneOutcome}${this.doneNote ? ` (${this.doneNote})` : ""}\n\n${route.done.body.trimEnd()}\n${verified ? `\n${verificationSection(verified.record, must(project.verify, "verify settings"), verified.cwd)}` : ""}`;
             atomicWrite(path.join(runDir, RESULT_FILE), report);
             atomicWrite(path.join(runDir, `done-${(state.reopened?.length ?? 0) + 1}.md`), report);
             this.pendingDoneFile = route.done.file;
@@ -973,6 +1002,8 @@ export class RunSession {
             this.endReason = "done";
             return;
         }
+        if (this.endReason)
+            return; // cancelled while verifying: nothing later may change why the run ended
         if (askAccepted) {
             this.endReason = "waiting";
             return;
@@ -987,6 +1018,75 @@ export class RunSession {
             return;
         }
     }
+    /**
+     * 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).
+     */
+    async verifyDone(done, verify) {
+        const { say, runDir, project, log, state } = this;
+        const cwd = this.leadSpace?.dir ?? project.dir;
+        const source = sourceIdOf(done.from, done.file);
+        // The tree is hashed before any command runs; with the lead's worktree this uses the pinned git, never a bare one.
+        const diffHash = await workingTreeHash(project, this.leadSpace, { signal: this.opts.signal });
+        say(`  verifying ${project.lead}'s done: ${verify.commands.map((c) => c.name).join(", ")}`);
+        const out = await runVerify(verify, runDir, state.verify, { cwd, signal: this.opts.signal, ...this.opts.verifyTiming }, {
+            start: (name) => log("verify-start", { name }),
+            end: (c) => log("verify-end", { name: c.name, exit: c.exit, ms: c.ms, timed_out: c.timed_out, ...(c.error ? { error: c.error } : {}) }),
+        });
+        if (out.cancelled) {
+            say("  verification cancelled: no verdict; the done report stays for the next resume");
+            log("verify-cancelled", { source });
+            return { kind: "cancelled" };
+        }
+        const record = { at: new Date().toISOString(), passed: out.passed, source, ...(diffHash ? { diff_hash: diffHash } : {}), commands: out.commands };
+        state.verify = [...(state.verify ?? []), record];
+        if (out.passed)
+            return { kind: "passed", record, cwd };
+        const failed = must(out.failed, "failed verify command");
+        const spec = must(verify.commands.find((c) => c.name === failed.name), "verify command");
+        const counted = state.verify_rejected?.includes(source) ?? false;
+        const used = state.verify_rejections ?? 0;
+        const cmp = compareWithLastRejection({ source, fingerprint: must(failed.fingerprint, "failure fingerprint"), hash: diffHash, worktree: this.leadSpace !== undefined, records: state.verify, rejected: state.verify_rejected });
+        const segment = state.reopened?.length ?? 0;
+        const left = verify.max_rejections - used;
+        const action = repeatAction(cmp, { counted, stoppedBefore: stoppedInSegment(state.verify, source, segment), left });
+        log("verify-repeat", { source, name: failed.name, fingerprint: failed.fingerprint, previous: cmp.previous ?? null, same_fingerprint: cmp.sameFingerprint, hash: cmp.hash, action, rejections_left: left });
+        if (action === "limit") {
+            const note = `Verification failed after ${used} rejection(s): \`${failed.name}\` (\`${spec.run}\`) ${describeFailure(failed, spec.timeout_sec)}; see ${failed.log}. Reported as partial; the lead's report is kept as written.`;
+            log("verify-failed", { name: failed.name, exit: failed.exit });
+            return { kind: "exhausted", record, cwd, failure: { note } };
+        }
+        if (action === "stop") {
+            // The verdict is stored before anything else, so a replay after a crash keeps it even if the command's output differs this time.
+            record.repeat_stop_segment = segment;
+            const note = repeatStopNote(failed.name, spec.run, describeFailure(failed, spec.timeout_sec), failed.log, used, verify.max_rejections);
+            this.saveState();
+            fault("verify:stopped");
+            log("verify-failed", { name: failed.name, exit: failed.exit, repeat: true });
+            say(`  done report not sent back: ${failed.name} failed the same way as last time and the workspace has not changed; accepted as partial`);
+            return { kind: "exhausted", record, cwd, failure: { note } };
+        }
+        // Counted once per done file: the count and its source id are saved before the mail goes out, so a replay after a crash neither counts nor sends twice.
+        if (!counted) {
+            state.verify_rejections = used + 1;
+            state.verify_rejected = [...(state.verify_rejected ?? []), source];
+        }
+        this.saveState();
+        fault("verify:counted");
+        deliverOnce(project, this.journal(), `verify-reject:${source}`, {
+            from: "dispatcher",
+            to: project.lead,
+            type: "failure",
+            subject: "Your done report failed verification",
+            body: withRepeatLabel(action, cmp.hash, rejectionMessage(failed, spec.run, out.tails[failed.name] ?? "", spec.timeout_sec, state.verify_rejections ?? used, verify.max_rejections)),
+        });
+        fault("verify:sent");
+        rejectDone(done.file);
+        say(`  done report sent back to ${project.lead}: ${failed.name} ${describeFailure(failed, spec.timeout_sec)}`);
+        log("verify-rejected", { name: failed.name, exit: failed.exit, count: state.verify_rejections });
+        return { kind: "rejected" };
+    }
     /** The user answered: send each asker its answers as a `reply`, then mark them delivered. Safe to repeat after a crash. */
     deliverAnswers() {
         const { runDir, project, log } = this;
@@ -1126,7 +1226,7 @@ export class RunSession {
         return result;
     }
     /** On resume: sort out what the interrupted process left behind before anything is woken. */
-    recover() {
+    async recover() {
         const { say, runId, runDir, project, wsMode, log } = this;
         if (this.resume?.end_reason === "waiting")
             this.deliverAnswers();
@@ -1149,14 +1249,14 @@ export class RunSession {
         }
         for (const c of rec.abandoned)
             say(`  ${c.agent}'s unfinished wake-up is redone: its ${c.message_ids.length} message(s) stay unread`);
-        this.settle([], []);
+        await this.settle([], []);
         // Wake-ups that had finished before the crash: their output is routed now, so their input is consumed.
         for (const c of rec.ready)
             commitClaim(runDir, c.id);
     }
     async run() {
         if (this.resume)
-            this.recover();
+            await this.recover();
         const { say, runId, runDir, wsMode, log, state, opts } = this;
         let project = this.project;
         // When the lead was the last one woken and left every mailbox empty without a `done`, remind it once instead of ending silently.
@@ -1241,7 +1341,7 @@ export class RunSession {
             leadWasLast = awake.some((a) => a.name === project.lead);
             if (awake.some((a) => a.name !== project.lead))
                 nudged = false;
-            this.settle(awake, results);
+            await this.settle(awake, results);
             if (!this.endReason && opts.signal?.aborted)
                 this.endReason = "cancelled";
         }
@@ -1264,8 +1364,9 @@ export class RunSession {
         }
         log("end", { reason: endReason, outcome, rounds: state.rounds });
         this.saveState();
+        fault("run:ended");
         if (this.pendingDoneFile)
             finishDone(this.pendingDoneFile);
-        return { runId, name: state.name, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined, resultBranch, pr, project: project.name, failure: this.failure };
+        return { runId, name: state.name, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, ...(this.dispatcherVerification ? { dispatcherVerification: this.dispatcherVerification } : {}), doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined, resultBranch, pr, project: project.name, failure: this.failure };
     }
 }

package/dist/run-store.d.ts

@@ -68,6 +68,29 @@ export interface RunFailure {
     attempts: number;
     tried?: TriedModel[];
 }
+/** What one verify command did (spec 27.7). `log` is relative to the run dir. */
+export interface VerifyCommandRecord {
+    name: string;
+    exit: number | null;
+    ms: number;
+    timed_out: boolean;
+    log: string;
+    /** Set when the command could not be started (for example no shell). */
+    error?: string;
+    /** spec 28: hash of the failure (name, status, normalised last lines); only on a failed command. */
+    fingerprint?: string;
+}
+/** One verification of a lead's `done` (spec 27.7). `diff_hash` is the git tree of the lead's workspace when it started; absent outside a git repo. */
+export interface VerifyRecord {
+    at: string;
+    passed: boolean;
+    /** The `done` mail's source id. */
+    source: string;
+    diff_hash?: string;
+    /** spec 28: this done was stopped as a repeat, in this segment (state.reopened length). */
+    repeat_stop_segment?: number;
+    commands: VerifyCommandRecord[];
+}
 export interface RunState {
     /** 1 for runs written before versioning; 2 for runs with their own mailboxes. */
     schema_version: number;
@@ -90,6 +113,12 @@ export interface RunState {
     verification?: string;
     /** How many `done` mails were sent back because they broke the completion contract. */
     done_rejections?: number;
+    /** Spec 27: one record per verification the dispatcher ran, oldest first (kept across reopens). */
+    verify?: VerifyRecord[];
+    /** Spec 27: `done` reports sent back because a verify command failed, in the current segment (reset at reopen). */
+    verify_rejections?: number;
+    /** Spec 27: source ids of the `done` files already counted in `verify_rejections`, so a replay does not count twice. */
+    verify_rejected?: string[];
     /** How many malformed `ask` mails each agent had sent back (the limit is MAX_ASK_REJECTIONS). */
     ask_rejections?: Record<string, number>;
     /** Recovery remarks (interrupted attempts whose side effects may have happened). */

package/dist/run-store.js

@@ -52,6 +52,9 @@ const WireState = z
     outcome_note: z.string().optional(),
     verification: z.string().optional(),
     done_rejections: nonNeg.optional(),
+    verify: z.array(z.any()).optional(),
+    verify_rejections: nonNeg.optional(),
+    verify_rejected: z.array(z.string()).optional(),
     notes: z.array(z.string()).optional(),
     ask_rejections: z.record(z.string(), nonNeg).optional(),
     sessions: z.record(z.string(), z.string()).optional(),

package/dist/schema.d.ts

@@ -191,6 +191,32 @@ export declare const GlobalConfig: z.ZodObject<{
         owns: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
+/** Spec 27: commands the dispatcher runs before it accepts a lead's `completed` done. Only the user writes them (project.yaml). */
+export declare const VerifyCommandPartial: z.ZodObject<{
+    name: z.ZodString;
+    run: z.ZodString;
+    timeout_sec: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const VerifyPartial: z.ZodObject<{
+    max_rejections: z.ZodOptional<z.ZodNumber>;
+    commands: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        run: z.ZodString;
+        timeout_sec: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export interface VerifySettings {
+    max_rejections: number;
+    commands: {
+        name: string;
+        run: string;
+        timeout_sec: number;
+    }[];
+}
+export declare const VERIFY_DEFAULTS: {
+    readonly max_rejections: 2;
+    readonly timeout_sec: 600;
+};
 export declare const ProjectConfig: z.ZodObject<{
     dir: z.ZodString;
     team: z.ZodObject<{
@@ -200,6 +226,14 @@ export declare const ProjectConfig: z.ZodObject<{
         "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
         codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    verify: z.ZodOptional<z.ZodObject<{
+        max_rejections: z.ZodOptional<z.ZodNumber>;
+        commands: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            run: z.ZodString;
+            timeout_sec: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
     dispatcher: z.ZodDefault<z.ZodObject<{
         max_rounds: z.ZodOptional<z.ZodNumber>;
         max_parallel: z.ZodOptional<z.ZodUnknown>;

package/dist/schema.js

@@ -99,11 +99,35 @@ export const GlobalConfig = z
     agents: z.record(z.string(), AgentPartial).default({}),
 })
     .strict();
+/** Spec 27: commands the dispatcher runs before it accepts a lead's `completed` done. Only the user writes them (project.yaml). */
+export const VerifyCommandPartial = z
+    .object({
+    name: z.string().regex(/^[a-z0-9-]+$/, "must be lowercase letters, digits and '-'"),
+    run: z.string().min(1),
+    timeout_sec: z.number().int().min(1).max(7200).optional(),
+})
+    .strict();
+export const VerifyPartial = z
+    .object({
+    max_rejections: z.number().int().min(0).max(5).optional(),
+    commands: z.array(VerifyCommandPartial).default([]),
+})
+    .strict()
+    .superRefine((v, ctx) => {
+    const seen = new Set();
+    v.commands.forEach((c, i) => {
+        if (seen.has(c.name))
+            ctx.addIssue({ code: "custom", path: ["commands", i, "name"], message: `"${c.name}" is used twice; names must be unique` });
+        seen.add(c.name);
+    });
+});
+export const VERIFY_DEFAULTS = { max_rejections: 2, timeout_sec: 600 };
 export const ProjectConfig = z
     .object({
     dir: z.string(),
     team: z.object({ lead: z.string() }).strict(),
     model_tiers: ModelTiersPartial.optional(),
+    verify: VerifyPartial.optional(),
     dispatcher: DispatcherPartial.default({}),
     agents: z.record(z.string(), AgentPartial).default({}),
 })

package/dist/status.js

@@ -227,7 +227,7 @@ export function buildRunReport(run, project, opts = {}) {
             ask = { path: askReplyPath(run.dir), total: 0, unanswered: 0 };
         }
     }
-    return {
+    const report = {
         run_id: s.run_id,
         name: s.name,
         dir: run.dir,
@@ -265,7 +265,13 @@ export function buildRunReport(run, project, opts = {}) {
         ...(s.instances ? { instances: s.instances.roles } : {}),
         ...(ask ? { ask } : {}),
     };
+    const lastVerify = s.verify?.at(-1);
+    if (lastVerify)
+        lastVerifyOf.set(report, lastVerify); // human output only: `status --json` stays as it was
+    return report;
 }
+/** The latest dispatcher verification (spec 27), kept off the report so `status --json` is unchanged. */
+const lastVerifyOf = new WeakMap();
 /** A run that ended with a `completed` or `partial` outcome: the only kinds the monitor stops listing (blocked, failed and cancelled stay). */
 export const isFinishedRun = (r) => r.state === "ended" && (r.outcome === "completed" || r.outcome === "partial");
 const projectInfo = (p) => ({ name: p.name, dir: p.dir, lead: p.lead });
@@ -400,6 +406,9 @@ function summaryBlock(run, now, c) {
     if (s.end_reason === "done" && s.result_path && s.result_head.length) {
         lines.push(`${L("結果：")}${s.result_path}`, ...s.result_head.map((l) => c.dim("          " + clip(l, 80))));
     }
+    const dv = lastVerifyOf.get(s);
+    if (dv)
+        lines.push(`${L("dispatcher 驗證：")}${dv.passed ? c.green("通過") : c.red("未通過")}（${dv.commands.map((x) => `${x.name} ${x.timed_out ? "逾時" : x.error ? "無法執行" : `exit ${x.exit}`}`).join("、")}；${dv.at}）`);
     const lastWake = (s.wakes ?? []).at(-1);
     if (lastWake)
         lines.push(`${L("上一次：")}#${lastWake.round} ${c.cyan(lastWake.agent)} ${okText(c, lastWake.ok)} → ${sentText(lastWake.sent)}`);

package/dist/verify.d.ts

@@ -0,0 +1,67 @@
+import type { VerifyCommandRecord, VerifyRecord } from "./run-store.js";
+import type { VerifySettings } from "./schema.js";
+/** Most output kept in a verify log; a longer output keeps its end and says so at the top. */
+export declare const VERIFY_LOG_BYTES: number;
+/** Most output of one command put into the mail to the lead and into the report. */
+export declare const VERIFY_TAIL_BYTES = 4096;
+export declare const VERIFY_DIR = "verify";
+/** The last `max` bytes of `buf` as text, never starting in the middle of a UTF-8 character. */
+export declare function tailText(buf: Buffer, max: number): string;
+export interface RunCommandOptions {
+    cwd: string;
+    timeoutSec: number;
+    signal?: AbortSignal;
+    /** Called with each chunk of output as it arrives (a readiness barrier for tests). */
+    onOutput?: (chunk: Buffer) => void;
+    /** Between SIGTERM and SIGKILL. Default 5000. */
+    killGraceMs?: number;
+    /** How long to wait for the output pipes after the shell is gone. Default 1000. */
+    settleWaitMs?: number;
+}
+export type CommandResult = {
+    cancelled: true;
+} | {
+    cancelled: false;
+    exit: number | null;
+    ms: number;
+    timedOut: boolean;
+    error?: string;
+    output: Buffer;
+};
+/**
+ * Run one command with `sh -c` in its own process group: stdin closed, output (both streams, in arrival order) kept in memory up to
+ * 2 x VERIFY_LOG_BYTES. Timeout and cancel stop the whole tree (SIGTERM, SIGKILL after `killGraceMs`); this settles once, whatever
+ * still holds the pipes. The child is registered with the process runner, so `killAllRunning` takes it down when agent-lyceum exits.
+ */
+export declare function runCommand(run: string, opts: RunCommandOptions): Promise<CommandResult>;
+/** The output as it goes into the log file: at most VERIFY_LOG_BYTES, with a first line saying so when the start was cut. */
+export declare function logBody(output: Buffer): Buffer;
+/** The next free log number: above every record and every file already in `verify/`, so no attempt (also not an unrecorded one from a crash) is overwritten. */
+export declare function nextLogNumber(runDir: string, records: VerifyRecord[] | undefined): number;
+export type VerifyOutcome = {
+    cancelled: true;
+} | {
+    cancelled: false;
+    passed: boolean;
+    commands: VerifyCommandRecord[];
+    tails: Record<string, string>;
+    failed?: VerifyCommandRecord;
+};
+export interface VerifyHooks {
+    start?: (name: string) => void;
+    end?: (c: VerifyCommandRecord) => void;
+}
+/** Run the commands in order, stopping at the first failure (fail-fast). Cancelling gives no verdict. */
+export declare function runVerify(verify: VerifySettings, runDir: string, records: VerifyRecord[] | undefined, opts: {
+    cwd: string;
+    signal?: AbortSignal;
+    killGraceMs?: number;
+    settleWaitMs?: number;
+}, hooks?: VerifyHooks): Promise<VerifyOutcome>;
+export declare const commandPassed: (c: VerifyCommandRecord) => boolean;
+/** How a failed command reads: "exit 1", "timed out after 600s", ... */
+export declare function describeFailure(c: VerifyCommandRecord, timeoutSec?: number): string;
+/** `## Dispatcher verification`: appended by the dispatcher after the lead's own report. */
+export declare function verificationSection(rec: VerifyRecord, verify: VerifySettings, cwd: string): string;
+/** The mail that sends a failed `done` back to the lead. */
+export declare function rejectionMessage(failed: VerifyCommandRecord, run: string, tail: string, timeoutSec: number, count: number, max: number): string;

package/dist/verify.js

@@ -0,0 +1,184 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+import { killTree, register, unregister } from "./process-runner.js";
+import { FINGERPRINT_WINDOW_BYTES, failureFingerprint, fingerprintPaths } from "./repeat-detect.js";
+/** Most output kept in a verify log; a longer output keeps its end and says so at the top. */
+export const VERIFY_LOG_BYTES = 1024 * 1024;
+/** Most output of one command put into the mail to the lead and into the report. */
+export const VERIFY_TAIL_BYTES = 4096;
+export const VERIFY_DIR = "verify";
+/** The last `max` bytes of `buf` as text, never starting in the middle of a UTF-8 character. */
+export function tailText(buf, max) {
+    if (buf.length <= max)
+        return buf.toString("utf8");
+    let start = buf.length - max;
+    while (start < buf.length && (buf[start] & 0xc0) === 0x80)
+        start++;
+    return buf.subarray(start).toString("utf8");
+}
+/**
+ * Run one command with `sh -c` in its own process group: stdin closed, output (both streams, in arrival order) kept in memory up to
+ * 2 x VERIFY_LOG_BYTES. Timeout and cancel stop the whole tree (SIGTERM, SIGKILL after `killGraceMs`); this settles once, whatever
+ * still holds the pipes. The child is registered with the process runner, so `killAllRunning` takes it down when agent-lyceum exits.
+ */
+export function runCommand(run, opts) {
+    const grace = opts.killGraceMs ?? 5000;
+    const settleWait = opts.settleWaitMs ?? 1000;
+    if (opts.signal?.aborted)
+        return Promise.resolve({ cancelled: true });
+    return new Promise((resolve) => {
+        const started = Date.now();
+        let child;
+        try {
+            child = spawn("sh", ["-c", run], { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" });
+        }
+        catch (e) {
+            return resolve({ cancelled: false, exit: null, ms: 0, timedOut: false, error: e.message, output: Buffer.alloc(0) });
+        }
+        if (child.pid !== undefined)
+            register(child.pid);
+        let buf = Buffer.alloc(0);
+        let dropped = 0;
+        let exit = null;
+        let reason;
+        let spawnError;
+        let settled = false;
+        const timers = [];
+        const kill = (sig) => {
+            if (child.pid !== undefined)
+                killTree(child.pid, sig);
+        };
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            for (const t of timers)
+                clearTimeout(t);
+            opts.signal?.removeEventListener("abort", onAbort);
+            kill("SIGKILL"); // whatever of the tree is still around
+            if (child.pid !== undefined)
+                unregister(child.pid);
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            // An abort that came after the process was gone but before the result was judged also withholds the verdict.
+            if (reason === "cancel" || opts.signal?.aborted)
+                return resolve({ cancelled: true });
+            const out = dropped ? Buffer.concat([Buffer.from(`[agent-lyceum: ${dropped} byte(s) of earlier output dropped]\n`), buf]) : buf;
+            resolve({ cancelled: false, exit, ms: Date.now() - started, timedOut: reason === "timeout", ...(spawnError ? { error: spawnError } : {}), output: out });
+        };
+        const stop = (why) => {
+            if (settled)
+                return;
+            // Cancel outranks a timeout that is still cleaning up: the verdict is withheld either way, and the tree is already being stopped.
+            if (reason) {
+                if (why === "cancel")
+                    reason = "cancel";
+                return;
+            }
+            reason = why;
+            kill("SIGTERM");
+            timers.push(setTimeout(() => kill("SIGKILL"), grace));
+            timers.push(setTimeout(finish, grace + settleWait));
+        };
+        function onAbort() {
+            stop("cancel");
+        }
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+        timers.push(setTimeout(() => stop("timeout"), opts.timeoutSec * 1000));
+        const onData = (chunk) => {
+            opts.onOutput?.(chunk);
+            buf = Buffer.concat([buf, chunk]);
+            if (buf.length > VERIFY_LOG_BYTES * 2) {
+                let start = buf.length - VERIFY_LOG_BYTES;
+                while (start < buf.length && (buf[start] & 0xc0) === 0x80)
+                    start++;
+                dropped += start;
+                buf = buf.subarray(start);
+            }
+        };
+        child.stdout?.on("data", onData);
+        child.stderr?.on("data", onData);
+        child.on("error", (e) => {
+            spawnError = e.code === "ENOENT" ? `${e.message} (sh or the working directory ${opts.cwd} not found)` : e.message;
+            finish();
+        });
+        child.on("exit", (code) => {
+            exit = code;
+            timers.push(setTimeout(finish, settleWait)); // a descendant may still hold the pipes
+        });
+        child.on("close", finish);
+    });
+}
+/** The output as it goes into the log file: at most VERIFY_LOG_BYTES, with a first line saying so when the start was cut. */
+export function logBody(output) {
+    if (output.length <= VERIFY_LOG_BYTES)
+        return output;
+    let start = output.length - VERIFY_LOG_BYTES;
+    while (start < output.length && (output[start] & 0xc0) === 0x80)
+        start++;
+    return Buffer.concat([Buffer.from(`[agent-lyceum: output truncated; the first ${start} byte(s) are not kept, the last ${output.length - start} follow]\n`), output.subarray(start)]);
+}
+/** The next free log number: above every record and every file already in `verify/`, so no attempt (also not an unrecorded one from a crash) is overwritten. */
+export function nextLogNumber(runDir, records) {
+    let max = 0;
+    for (const r of records ?? [])
+        for (const c of r.commands)
+            max = Math.max(max, Number(/^verify\/(\d+)-/.exec(c.log)?.[1] ?? 0));
+    try {
+        for (const f of fs.readdirSync(path.join(runDir, VERIFY_DIR)))
+            max = Math.max(max, Number(/^(\d+)-/.exec(f)?.[1] ?? 0));
+    }
+    catch {
+        /* no verify dir yet */
+    }
+    return max + 1;
+}
+/** Run the commands in order, stopping at the first failure (fail-fast). Cancelling gives no verdict. */
+export async function runVerify(verify, runDir, records, opts, hooks = {}) {
+    const commands = [];
+    const tails = {};
+    let n = nextLogNumber(runDir, records);
+    for (const c of verify.commands) {
+        const rel = `${VERIFY_DIR}/${n++}-${c.name}.log`;
+        hooks.start?.(c.name);
+        const r = await runCommand(c.run, { cwd: opts.cwd, timeoutSec: c.timeout_sec, signal: opts.signal, killGraceMs: opts.killGraceMs, settleWaitMs: opts.settleWaitMs });
+        if (r.cancelled)
+            return { cancelled: true };
+        const body = logBody(r.output);
+        fs.mkdirSync(path.join(runDir, VERIFY_DIR), { recursive: true });
+        atomicWrite(path.join(runDir, rel), body);
+        const rec = { name: c.name, exit: r.exit, ms: r.ms, timed_out: r.timedOut, log: rel, ...(r.error ? { error: r.error } : {}) };
+        if (!commandPassed(rec))
+            rec.fingerprint = failureFingerprint(rec, tailText(r.output, FINGERPRINT_WINDOW_BYTES), fingerprintPaths(opts.cwd, runDir));
+        commands.push(rec);
+        tails[c.name] = tailText(r.output, VERIFY_TAIL_BYTES).replace(/\r\n/g, "\n");
+        hooks.end?.(rec);
+        if (!commandPassed(rec))
+            return { cancelled: false, passed: false, commands, tails, failed: rec };
+    }
+    if (opts.signal?.aborted)
+        return { cancelled: true };
+    return { cancelled: false, passed: true, commands, tails };
+}
+export const commandPassed = (c) => c.exit === 0 && !c.timed_out && !c.error;
+/** How a failed command reads: "exit 1", "timed out after 600s", ... */
+export function describeFailure(c, timeoutSec) {
+    if (c.error)
+        return `could not be run (${c.error})`;
+    if (c.timed_out)
+        return `timed out${timeoutSec ? ` after ${timeoutSec}s` : ""} and was killed`;
+    return c.exit === null ? "was killed by a signal" : `exited with code ${c.exit}`;
+}
+const secs = (ms) => `${(ms / 1000).toFixed(1)}s`;
+/** `## Dispatcher verification`: appended by the dispatcher after the lead's own report. */
+export function verificationSection(rec, verify, cwd) {
+    const lines = rec.commands.map((c) => `- \`${c.name}\`: ${commandPassed(c) ? "passed" : `FAILED, ${describeFailure(c, verify.commands.find((x) => x.name === c.name)?.timeout_sec)}`} (${secs(c.ms)}, log ${c.log})`);
+    const skipped = verify.commands.slice(rec.commands.length).map((c) => `- \`${c.name}\`: not run (an earlier command failed)`);
+    return `## Dispatcher verification\n\nRun by the dispatcher in ${cwd}, not by an agent: ${rec.passed ? "all commands passed" : "NOT all commands passed"}.\n\n${[...lines, ...skipped].join("\n")}\n`;
+}
+/** The mail that sends a failed `done` back to the lead. */
+export function rejectionMessage(failed, run, tail, timeoutSec, count, max) {
+    return `The run was not ended: before accepting your \`done\` (outcome completed) the dispatcher ran the project's verify commands, and one failed.\n\nCommand \`${failed.name}\` (\`${run}\`) ${describeFailure(failed, timeoutSec)}. Later commands were not run.\n\nLast output (at most ${VERIFY_TAIL_BYTES} bytes; the full log is ${failed.log} in the run directory):\n\n\`\`\`\n${tail.trimEnd()}\n\`\`\`\n\nFix the cause, then send \`done\` again. If the work cannot pass, report \`partial\` or \`blocked\` honestly (those are not verified). (Verification rejection ${count} of ${max}.)`;
+}

package/dist/worktree.d.ts

@@ -81,6 +81,15 @@ export declare function snapshotHead(project: ResolvedProject, runId: string): s
  * `from`: the checkout to snapshot — the lead's worktree in a concurrent run; by default your repo's working tree.
  */
 export declare function snapshotBase(project: ResolvedProject, runId: string, n: number, from?: AgentWorkspace): string;
+/**
+ * The git tree of the working tree as it is now (tracked changes and new, non-ignored files), through a throwaway index:
+ * nothing of the repo is touched. A worktree is read with the pinned git (no hooks, fsmonitor, filters from the worktree).
+ * Undefined when `dir` is not a git repository or the tree cannot be read (a nested repository in a worktree, ...).
+ */
+export declare function workingTreeHash(project: ResolvedProject, from?: AgentWorkspace, opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}): Promise<string | undefined>;
 export declare const workspaceRoot: (project: ResolvedProject, runId: string, agent: string) => string;
 /**
  * The agent's own checkout of the snapshot `baseRef`, at `<project home>/worktrees/<run>/<agent>`.

package/dist/worktree.js

@@ -1,10 +1,11 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { atomicWrite } from "./fs-util.js";
 import { escapesParent } from "./paths.js";
+import { killTree, register, unregister } from "./process-runner.js";
 const IDENTITY = {
     GIT_AUTHOR_NAME: "agent-lyceum",
     GIT_AUTHOR_EMAIL: "agent-lyceum@localhost",
@@ -291,6 +292,84 @@ export function snapshotBase(project, runId, n, from) {
         fs.rmSync(index, { force: true });
     }
 }
+/**
+ * The git tree of the working tree as it is now (tracked changes and new, non-ignored files), through a throwaway index:
+ * nothing of the repo is touched. A worktree is read with the pinned git (no hooks, fsmonitor, filters from the worktree).
+ * Undefined when `dir` is not a git repository or the tree cannot be read (a nested repository in a worktree, ...).
+ */
+export async function workingTreeHash(project, from, opts = {}) {
+    const index = path.join(os.tmpdir(), `agent-lyceum-index-${crypto.randomBytes(6).toString("hex")}`);
+    const deadline = Date.now() + (opts.timeoutMs ?? HASH_BUDGET_MS);
+    // No hooks (git runs post-index-change after writing an index, also a temporary one) and no fsmonitor, in both modes.
+    // Clean filters named in the repo's own config still run during `add -A` (as in snapshotBase); only the deadline bounds them.
+    const run = (cwd, args, env = {}) => boundedGit(cwd, from ? pinnedArgs(args) : ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args], from ? pinnedEnv(from, env) : env, deadline, opts.signal);
+    try {
+        let cwd;
+        if (from) {
+            assertWorkspaceIntact(from);
+            assertNoNestedRepos(from); // sync, no hooks, quick
+            cwd = from.root;
+        }
+        else
+            cwd = await run(project.dir, ["rev-parse", "--show-toplevel"]);
+        const env = { GIT_INDEX_FILE: index };
+        const head = await run(cwd, ["rev-parse", "--verify", "HEAD"]).catch(() => undefined);
+        if (head)
+            await run(cwd, ["read-tree", head], env);
+        await run(cwd, ["add", "-A"], env);
+        return await run(cwd, ["write-tree"], env);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        fs.rmSync(index, { force: true });
+        fs.rmSync(`${index}.lock`, { force: true }); // a git killed during `add` leaves its lock behind
+    }
+}
+/** The most the tree hash may take in total (spec 27.7 record, spec 28 comparison); then it is absent and verification goes on. */
+const HASH_BUDGET_MS = 30_000;
+/** git in its own process group, killed with SIGKILL (group and descendants) at `deadline` or on `signal`; the event loop stays free meanwhile. */
+function boundedGit(cwd, args, env, deadline, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(new Error("aborted"));
+        const child = spawn("git", args, { cwd, env: { ...process.env, ...env }, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32" });
+        if (child.pid !== undefined)
+            register(child.pid);
+        let out = "";
+        let err = "";
+        let done = false;
+        const end = (e) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            if (child.pid !== undefined) {
+                killTree(child.pid, "SIGKILL"); // also what a filter left behind
+                unregister(child.pid);
+            }
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            if (e)
+                reject(e);
+            else
+                resolve(out.replace(/\n$/, ""));
+        };
+        const onAbort = () => end(new Error("aborted"));
+        const timer = setTimeout(() => end(new Error("timed out")), Math.max(0, deadline - Date.now()));
+        signal?.addEventListener("abort", onAbort, { once: true });
+        child.stdout?.on("data", (c) => {
+            out += c.toString("utf8");
+        });
+        child.stderr?.on("data", (c) => {
+            err += c.toString("utf8").slice(0, 4096);
+        });
+        child.on("error", (e) => end(e));
+        child.on("close", (code) => end(code === 0 ? undefined : new Error(`git ${args.join(" ")} failed: ${err.trim()}`)));
+    });
+}
 export const workspaceRoot = (project, runId, agent) => path.join(project.paths.root, "worktrees", runId, agent);
 /** The user's repo's git common dir, as a real absolute path. Asked of the user's repo, never of a worktree. */
 const commonDirOf = (top) => fs.realpathSync(git(top, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",