agent-lyceum 0.31.0 → 0.32.0

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/summarize.d.ts

@@ -0,0 +1,2 @@
+/** One local CLI call. The prompt already says what to write; this only runs it. */
+export declare function summarizeProgress(runtime: "claude" | "codex", prompt: string): Promise<string>;

package/dist/summarize.js

@@ -0,0 +1,85 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const TIMEOUT_MS = 90_000;
+const CAP = 200_000;
+/** One local CLI call. The prompt already says what to write; this only runs it. */
+export async function summarizeProgress(runtime, prompt) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "lyceum-summary-"));
+    try {
+        const text = runtime === "claude" ? await claude(dir, prompt) : await codex(dir, prompt);
+        const trimmed = text.trim();
+        if (!trimmed)
+            throw new Error("沒有寫出摘要。");
+        return trimmed;
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+async function claude(dir, prompt) {
+    const settings = path.join(dir, "settings.json");
+    fs.writeFileSync(settings, JSON.stringify({
+        disableAllHooks: true,
+        permissions: { deny: ["Bash", "Edit", "Write", "NotebookEdit", "WebSearch", "WebFetch", "Agent", "Read", "Glob", "Grep"] },
+    }));
+    const result = await run("claude", ["-p", "--no-session-persistence", "--output-format", "text", "--permission-mode", "dontAsk", "--settings", settings], prompt, dir);
+    if (!result.stdout.trim())
+        throw new Error(first(result.stderr) || "claude 沒有寫出摘要。");
+    return result.stdout;
+}
+async function codex(dir, prompt) {
+    const last = path.join(dir, "last.txt");
+    const result = await run("codex", ["exec", "-C", dir, "-s", "read-only", "--skip-git-repo-check", "-c", 'approval_policy="never"', "-o", last, "-"], prompt, dir);
+    let text = "";
+    try {
+        text = fs.readFileSync(last, "utf8");
+    }
+    catch {
+        text = "";
+    }
+    if (!text.trim())
+        text = result.stdout;
+    if (!text.trim())
+        throw new Error(first(result.stderr) || "codex 沒有寫出摘要。");
+    return text;
+}
+function first(text) {
+    return text.split("\n").map((line) => line.trim()).find(Boolean) ?? "";
+}
+function run(cmd, args, stdin, cwd) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve({ stdout, stderr });
+        };
+        const timer = setTimeout(() => {
+            child.kill();
+            finish(new Error(`${cmd} 超過 ${Math.round(TIMEOUT_MS / 1000)} 秒沒有回應。`));
+        }, TIMEOUT_MS);
+        child.stdout.on("data", (chunk) => {
+            stdout = (stdout + String(chunk)).slice(0, CAP);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr = (stderr + String(chunk)).slice(0, CAP);
+        });
+        child.on("error", (error) => {
+            const code = error.code;
+            finish(code === "ENOENT" ? new Error(`找不到 ${cmd}。`) : error);
+        });
+        child.on("close", () => finish());
+        child.stdin.write(stdin);
+        child.stdin.end();
+    });
+}

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;