agent-lyceum 0.25.0 → 0.26.0

package/dist/run-session.js

@@ -1,15 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
-import { agentForCandidate, candidatesFor, Cooldowns, planAttempts, runWithFallback } from "./fallback.js";
+import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, planAttempts, runWithFallback } from "./fallback.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
 import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, resolveOptionLetters, writeAskReply } from "./ask-reply.js";
-import { deliver, deliverOnce, ensureProjectDirs, finishDone, listUnread, rejectDone, routeOutboxes, unreadFiles } from "./mailbox.js";
-import { abandonClaim, attemptLogDir, sourceIdOf, beginAttempt, claimMessages, commitClaim, fault, finishAttempt, markOutputReady, parkOutbox, recoverRunMail, RouteJournal } from "./message-store.js";
+import { deliver, deliverOnce, ensureAgentDirs, ensureProjectDirs, finishDone, listUnread, PENDING_DIR, readMessageNoFollow, rejectDone, routeOutboxes, unreadFiles } from "./mailbox.js";
+import { instanceContainment } from "./instance-containment.js";
+import { DEFAULT_MAX_INSTANCES, assertInstancesResumable, heldStallKey, instanceCap, ownersOf, parseSlotName, planAssignments, roleOfName } from "./instances.js";
+import { abandonClaim, attemptLogDir, sourceIdOf, beginAttempt, claimMessages, commitClaim, fault, finishAttempt, loadClaim, markOutputReady, parkOutbox, recoverRunMail, RouteJournal } from "./message-store.js";
 import { createRunLog } from "./run-log.js";
 import { endOutcome, resolveDoneOutcome } from "./run-outcome.js";
-import { outboxDir, sharedIndex } from "./policy.js";
+import { inboxDir, outboxDir, sharedIndex } from "./policy.js";
 import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
 import { collectDrafts, priorFailedAttempts, redoUserPrompt } from "./redo.js";
 import { atomicWrite, readFileCapped } from "./fs-util.js";
@@ -50,6 +52,30 @@ function lastPerModel(tried) {
     }
     return out;
 }
+/**
+ * Whether same-role instances are possible in this run, decided once from configuration and paths (spec 23.11 preflight, reads only): when
+ * some member could run as several, the lead's prompt explains `parallel: true`. Writes nothing.
+ */
+function withCapability(project, mode, check, table) {
+    if (!project.run)
+        return project;
+    const possible = Object.keys(project.agents).some((role) => {
+        if (project.agents[role]?.instance && project.agents[role]?.instance?.k !== 1)
+            return false;
+        return instanceCap(project, mode, role, check, table?.roles[role] ?? []).n > 1;
+    });
+    return possible ? { ...project, run: { ...project.run, instances: { max: project.dispatcher.max_instances ?? DEFAULT_MAX_INSTANCES } } } : project;
+}
+const WAIT_TEXT = {
+    blocked: "its earlier work is blocked: reply to the failure about it to redo it",
+    refused: "its worktree was refused",
+    cap: "it is above the instance limit",
+    busy: "every instance is busy",
+    cooldown: "waiting for a rate-limited model to recover",
+    collision: "its name is already an agent of the project",
+    containment: "an instance there could write the role's shared memory",
+    "unknown-slot": "no such instance",
+};
 export class RunSession {
     opts;
     resume;
@@ -60,9 +86,21 @@ export class RunSession {
     cfg;
     runId;
     runDir;
-    /** The project bound to this run (own memory dirs and mailboxes). */
+    /** The project bound to this run (own memory dirs and mailboxes). Bound again when the run gets instances (spec 23.6). */
     project;
+    /** The project as configured (solo-narrowed), before it is bound to this run. */
+    base;
+    layout;
+    /** Roles that get no new instance in this process: a check after an instance was created found a conflict. */
+    noMoreInstances = new Set();
+    heldLogged = new Set();
+    ignoredNoted = new Set();
+    /** Held mail the assigner left in `pending/` this round (read by the stall check). */
+    waiting = [];
     wsMode;
+    /** D-17: the paths an instance would get against the shared memory of its role (writes nothing). */
+    containment;
+    instanceCheck;
     log;
     guard;
     state;
@@ -92,6 +130,12 @@ export class RunSession {
     attempts = new Map();
     constructor(opts) {
         const { task, resume, runDir } = opts;
+        // A run whose slot table no longer fits the configuration is refused before anything is written.
+        if (resume?.instances) {
+            const soloOf = resume.solo_agent;
+            const cfgBase = soloOf ? soloProject(opts.project, soloOf) : opts.project;
+            assertInstancesResumable(cfgBase, resume.instances, path.basename(runDir), cfgBase.name, opts.instanceCheck ?? instanceContainment(cfgBase, runDir, resume.mail_layout).check);
+        }
         if (resume?.end_reason === "waiting")
             RunSession.assertAnswered(runDir, resume.run_id);
         if (opts.followup && resume?.end_reason !== "done")
@@ -106,7 +150,7 @@ export class RunSession {
         const runId = path.basename(runDir);
         const layout = resume ? resume.mail_layout : "run";
         // Each run gets its own memory directory per agent and (new runs) its own mailboxes.
-        const project = bindRunProject(base, runDir, layout);
+        const project = bindRunProject(base, runDir, layout, resume?.instances);
         // Where agents work was decided before the lock was taken and is kept for the run's resumes. A resumed run that uses worktrees
         // is refused early (before anything is written) when its repo can no longer give them.
         const { plan } = opts;
@@ -237,7 +281,11 @@ export class RunSession {
         this.cfg = cfg;
         this.runId = runId;
         this.runDir = runDir;
-        this.project = project;
+        this.containment = instanceContainment(base, runDir, layout);
+        this.instanceCheck = opts.instanceCheck ?? this.containment.check;
+        this.project = withCapability(project, wsMode, opts.instanceCheck ?? this.containment.check, resume?.instances);
+        this.base = base;
+        this.layout = layout;
         this.wsMode = wsMode;
         this.log = log;
         this.guard = guard;
@@ -272,6 +320,201 @@ export class RunSession {
         log("note", { text });
         say(`  ${text}`);
     }
+    /** Bind the project to this run again, after its slot table changed. */
+    rebind() {
+        this.project = withCapability(bindRunProject(this.base, this.runDir, this.layout, this.state.instances), this.wsMode, this.instanceCheck, this.state.instances);
+    }
+    /** What the router needs to hold and place mail for roles with several instances (spec 23.7.1). */
+    routing() {
+        const { state, log } = this;
+        return {
+            cap: (role) => instanceCap(this.project, this.wsMode, role, this.instanceCheck, state.instances?.roles[role] ?? []),
+            held: (role) => !!state.instances?.roles[role],
+            enable: (role) => {
+                // Durable before any file of the mail that opens the role's instances exists; a crash after this replays into `pending/`.
+                state.schema_version = 3;
+                state.instances = { roles: { ...(state.instances?.roles ?? {}), [role]: [role] } };
+                this.saveState();
+                fault("instances:enabled");
+                this.rebind();
+                log("instances", { role, enabled: true });
+            },
+            ignored: (reason, m) => {
+                log("parallel_ignored", { from: m.from, id: m.id, to: m.to, reason });
+                const key = `${m.from}\u0000${reason}`;
+                if (this.ignoredNoted.has(key))
+                    return;
+                this.ignoredNoted.add(key);
+                this.note(reason === "not-lead"
+                    ? `${m.from}'s mail ${m.id} has \`parallel: true\`, but only the lead (${this.project.lead}) can start parallel instances: it was delivered as an ordinary task.`
+                    : `${m.from}'s mail ${m.id} ("${m.subject}") has \`parallel: true\` but was delivered as an ordinary mail: ${reason}`);
+            },
+        };
+    }
+    /** Make a new instance durable and give it its folders; false (and the role gets no more instances in this process) when a check refuses it. */
+    openInstance(role, slot) {
+        const { state, log } = this;
+        const table = must(state.instances?.roles[role], `slot table of ${role}`);
+        if (this.noMoreInstances.has(role))
+            return false;
+        table.push(slot);
+        this.saveState();
+        fault("instances:opened");
+        this.rebind();
+        ensureAgentDirs(this.project, slot);
+        const agent = must(this.project.agents[slot], `instance ${slot}`);
+        const refuse = (why) => {
+            this.noMoreInstances.add(role);
+            this.refused.add(slot); // listed in the slot table, but never given mail or woken
+            log("instances", { role, slot, refused: why });
+            this.note(`${slot} was opened but cannot be used: ${why}. ${role} gets no further instances in this run process.`);
+            return false;
+        };
+        for (const dir of [outboxDir(this.project, slot), agent.memory.task]) {
+            if (!dir)
+                continue;
+            const st = fs.lstatSync(dir, { throwIfNoEntry: false });
+            if (!st || st.isSymbolicLink() || !st.isDirectory())
+                return refuse(`${dir} is not a plain directory`);
+        }
+        const k = parseSlotName(slot)?.k ?? 2;
+        const conflict = this.instanceCheck?.(role, k);
+        if (conflict)
+            return refuse(conflict);
+        log("instances", { role, slot, opened: true });
+        return true;
+    }
+    /** The one round of placing held mail, at the top of the loop (spec 23.7.2). Leaves what it could not place in `this.waiting`. */
+    assignHeld() {
+        this.waiting = [];
+        for (const role of Object.keys(this.state.instances?.roles ?? {}).sort())
+            this.assignRole(role);
+    }
+    assignRole(role) {
+        const { state, log, runDir } = this;
+        const opened = [...must(state.instances?.roles[role], `slot table of ${role}`)];
+        const pendingDir = path.join(inboxDir(this.project, role), PENDING_DIR);
+        if (!fs.existsSync(pendingDir))
+            return;
+        const files = fs.readdirSync(pendingDir, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".md") && !e.name.startsWith(".")).map((e) => e.name).sort();
+        if (!files.length)
+            return;
+        const journal = this.journal();
+        const msgs = [];
+        const subjects = new Map();
+        for (const f of files) {
+            const entry = journal.byFile(f);
+            // Only the dispatcher's own held deliveries count: a file put here by anyone else is left alone.
+            if (!entry?.held) {
+                if (!this.heldLogged.has(`unknown:${f}`)) {
+                    this.heldLogged.add(`unknown:${f}`);
+                    log("held_unknown", { role, file: f });
+                }
+                continue;
+            }
+            let replyTo;
+            let thread;
+            try {
+                const m = readMessageNoFollow(path.join(pendingDir, f));
+                replyTo = m.meta.reply_to ? String(m.meta.reply_to) : undefined;
+                thread = m.meta.thread ? String(m.meta.thread) : undefined;
+                subjects.set(entry.msg_id, String(m.meta.subject ?? ""));
+            }
+            catch {
+                /* unreadable mail has no thread: it is placed as a new one */
+            }
+            msgs.push({ file: f, id: entry.msg_id, to: entry.to, replyTo, thread, parallel: entry.parallel === true });
+        }
+        if (!msgs.length)
+            return;
+        const mark = opened.map((n) => journal.firstHeld(n)).filter((x) => x !== undefined).reduce((a, b) => (a === undefined ? b : Math.min(a, b)), undefined);
+        const claimAgent = (id) => {
+            try {
+                return loadClaim(runDir, id).agent;
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const cap = instanceCap(this.project, this.wsMode, role, this.instanceCheck, opened);
+        const roleAgent = must(this.project.agents[role], `agent ${role}`);
+        const primary = must(candidatesFor(roleAgent)[0], `model of ${role}`);
+        const plan = planAssignments({
+            role,
+            held: msgs,
+            opened,
+            cap: cap.n,
+            owners: (id) => ownersOf(id, role, { opened, rec: (x) => journal.ownership(x), mark, claimAgent }),
+            recorded: (id) => journal.assigned(id)?.slot,
+            acceptsNew: (slot) => {
+                if (this.refused.has(slot))
+                    return "refused";
+                if (state.blocked_integrations?.some((b) => b.agent === slot))
+                    return "blocked";
+                return (parseSlotName(slot)?.k ?? 1) > cap.n ? "cap" : true;
+            },
+            busy: (slot) => unreadFiles(this.project, slot).length > 0,
+            coolingDown: this.cooldowns.active(primary.key, Date.now()) > 0,
+            mayOpen: (name) => (this.noMoreInstances.has(role) ? "containment" : name in this.base.agents ? "collision" : true),
+        });
+        const byFile = new Map(msgs.map((m) => [m.file, m]));
+        const wait = (m, reason) => {
+            this.waiting.push({ id: m.id, role, to: m.to, subject: subjects.get(m.id) ?? "", reason });
+            const key = `${m.id}:${reason}`;
+            if (!this.heldLogged.has(key)) {
+                this.heldLogged.add(key);
+                log("held", { id: m.id, role, reason });
+            }
+        };
+        // The plan is applied one mail at a time, in plan order: a slot that could not be opened takes nothing later in this plan either.
+        const unusable = new Set();
+        for (const a of plan.assign) {
+            const m = must(byFile.get(a.file), `held mail ${a.file}`);
+            if (unusable.has(a.slot) || (a.open && !this.openInstance(role, a.open))) {
+                unusable.add(a.slot);
+                wait(m, "containment");
+                continue;
+            }
+            if (a.rule !== "recorded")
+                journal.assign({ msg_id: m.id, file: a.file, role, slot: a.slot });
+            fault("assign:recorded");
+            fs.mkdirSync(inboxDir(this.project, a.slot), { recursive: true });
+            fs.renameSync(path.join(pendingDir, a.file), path.join(inboxDir(this.project, a.slot), a.file));
+            fault("assign:moved");
+            log("assign", { id: m.id, role, slot: a.slot, rule: a.rule, ...(a.addressed ? { addressed: a.addressed } : {}) });
+        }
+        for (const w of plan.waiting)
+            wait(must(byFile.get(w.file), `held mail ${w.file}`), w.reason);
+    }
+    /**
+     * The run is about to end idle but mail is still held (spec D-16). Only a cooldown in the way: wait for it (cut short by a cancel) and
+     * return true to go round again. Otherwise tell the lead once per set of waiting mails; true when that mail is new (the lead has work).
+     */
+    async stallHeld() {
+        const { log, project, opts } = this;
+        const held = this.waiting;
+        if (held.length === 0)
+            return "idle";
+        if (held.every((w) => w.reason === "cooldown")) {
+            const now = Date.now();
+            const ms = Math.min(...[...new Set(held.map((w) => w.role))].map((r) => this.cooldowns.active(must(candidatesFor(must(this.project.agents[r], `agent ${r}`))[0], "model").key, now)).filter((x) => x > 0));
+            if (Number.isFinite(ms)) {
+                log("held_wait", { until: new Date(now + ms).toISOString() });
+                await (opts.sleep ?? defaultSleep)(ms, opts.signal);
+                return "retry";
+            }
+            return "retry";
+        }
+        const list = held.map((w) => `${w.id} "${w.subject}" for ${w.to} (${WAIT_TEXT[w.reason] ?? w.reason})`).join(", ");
+        const { fresh } = deliverOnce(project, this.journal(), heldStallKey(held.map((w) => w.id)), {
+            from: "dispatcher",
+            to: project.lead,
+            type: "failure",
+            subject: "Tasks are waiting and nothing is running",
+            body: `${held.length} task(s) are waiting and nothing else is running: ${list}. They are assigned as soon as that work is in the repo.`,
+        });
+        return fresh ? "notified" : "idle";
+    }
     pendingAgents() {
         const { project } = this;
         const rows = Object.values(project.agents)
@@ -532,6 +775,8 @@ export class RunSession {
         }
         state.blocked_integrations = [...blocked, { agent: agent.name, branch: r.branch, reason: r.reason, report: r.report }];
         say(`  ${agent.name}: changes NOT brought into the repo (${r.reason.split("\n")[0]})`);
+        // A role with instances: the notice is about one of them, so the lead's reply to it goes back to that instance (spec 23.9).
+        const instanced = !!state.instances?.roles[roleOfName(project.agents, agent.name)];
         deliverOnce(project, this.journal(), `integration:${key}`, {
             from: "dispatcher",
             to: project.lead,
@@ -540,8 +785,9 @@ export class RunSession {
             body: `${agent.name} finished, but its changes could not be brought into the repo, and nothing was applied.\n\n${r.reason}\n\n` +
                 `Its work is kept: branch \`${r.branch}\`, worktree \`${r.workspace}\`, report \`${r.report}\`, patch \`${r.patch}\`.\n` +
                 `You can send ${agent.name} a task to redo or adjust it (it continues in the same worktree and the integration is retried after its next wake-up), or apply the patch yourself. ` +
+                (instanced ? `New tasks are not given to ${agent.name} while this work is not in the repo. To redo or adjust it, reply to this message (or to ${agent.name}'s last mail): only replies reach ${agent.name} now. ` : "") +
                 `Do not report the job \`completed\` while this work is missing from the repo.`,
-        });
+        }, instanced ? { about: agent.name } : {});
         this.saveState();
     }
     /** A member whose worktree was refused: it is not woken again in this run, and the lead is told so it can react. */
@@ -555,7 +801,7 @@ export class RunSession {
             type: "failure",
             subject: `${agent.name} cannot be woken: its worktree was refused`,
             body: `${agent.name} has unread mail, but its worktree cannot be used, so it is not woken again in this run and its unread mail stays unread.\n\n${reason}\n\nDo its work yourself or give it to another agent; do not wait for ${agent.name}.`,
-        });
+        }, this.state.instances?.roles[roleOfName(project.agents, agent.name)] ? { about: agent.name } : {});
         this.saveState();
     }
     /** After a batch (or, on resume, before the first one): revert guarded edits, route mail, detect done / lead failure. */
@@ -574,12 +820,14 @@ export class RunSession {
                     (v.saved ? `\n\nWhat was written is kept at \`${v.saved}\` (sha256 ${v.sha256}${v.truncated ? ", truncated to 1 MiB" : ""}). If it is worth keeping, have an agent that may edit this file redo it.` : ""),
             });
         }
+        // Crash seam: every wake of the batch is finished and marked output_ready; nothing of it is integrated or routed yet.
+        fault("wake:ready");
         batch.forEach((a, i) => {
             const ws = this.batchSpaces[a.name];
             if (ws && results[i]?.ok)
                 this.integrateMember(a, ws, claims.get(a.name)?.id ?? `${a.name}-${state.rounds}`);
         });
-        const route = routeOutboxes(project);
+        const route = routeOutboxes(project, this.routing());
         // A done that breaks the completion contract goes back to the lead (a limited number of times).
         let contract;
         if (route.done) {
@@ -846,7 +1094,8 @@ export class RunSession {
     async run() {
         if (this.resume)
             this.recover();
-        const { say, runId, runDir, project, wsMode, log, state, opts } = this;
+        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.
         let leadWasLast = false;
         let nudged = false;
@@ -855,6 +1104,8 @@ export class RunSession {
                 this.endReason = "cancelled";
                 break;
             }
+            this.assignHeld();
+            project = this.project;
             let pending = this.pendingAgents();
             if (pending.length === 0 && leadWasLast && !nudged) {
                 nudged = true;
@@ -869,6 +1120,17 @@ export class RunSession {
                 });
                 pending = this.pendingAgents();
             }
+            if (pending.length === 0) {
+                const stalled = await this.stallHeld();
+                if (opts.signal?.aborted) {
+                    this.endReason = "cancelled";
+                    break;
+                }
+                if (stalled === "retry")
+                    continue;
+                if (stalled === "notified")
+                    pending = this.pendingAgents();
+            }
             if (pending.length === 0) {
                 this.endReason = "idle";
                 break;
@@ -895,7 +1157,13 @@ export class RunSession {
                 }
                 for (const a of members) {
                     try {
-                        this.batchSpaces[a.name] = prepareAgentWorkspace(project, runId, a.name, ref);
+                        const ws = prepareAgentWorkspace(project, runId, a.name, ref);
+                        // An instance gets one more containment check with the worktree it really got (spec 23.11 point 3).
+                        const inst = a.instance;
+                        const conflict = inst ? (opts.instanceCheck ? opts.instanceCheck(inst.role, inst.k) : this.containment.checkWorkspace(inst.role, inst.k, ws)) : undefined;
+                        if (conflict)
+                            throw new Error(`${a.name} ${conflict}`);
+                        this.batchSpaces[a.name] = ws;
                     }
                     catch (e) {
                         this.refuseMember(a, e.message);

package/dist/run-store.d.ts

@@ -3,7 +3,12 @@ import type { DigestSection, Step } from "./format.js";
 import { type ErrorKind, type Runtime, type RunOutcome } from "./schema.js";
 import type { ResultBranch } from "./worktree.js";
 export declare const STATE_FILE = "state.json";
-export declare const STATE_SCHEMA_VERSION = 2;
+/** The newest state format this version reads. */
+export declare const STATE_SCHEMA_VERSION = 3;
+/** What a new run is written as: v3 only appears when the first parallel task opens instances (spec 23.6). */
+export declare const NEW_RUN_SCHEMA_VERSION = 2;
+/** Refuse a state newer than `supported`, before anything is written (the failure an older binary gives a v3 run). */
+export declare function assertSupportedVersion(version: number | undefined, supported: number, file: string): void;
 export type EndReason = "done" | "idle" | "max_rounds" | "lead_failed" | "agent_failed" | "cancelled" | "waiting";
 export type MailLayout = "run" | "legacy";
 export interface WakeTopic {
@@ -146,6 +151,12 @@ export interface RunState {
     }[];
     /** `rounds` at the last reopen; the round limit counts from here. */
     round_floor?: number;
+    /** Same-role instances opened in this run (spec 23.6); present only from the first parallel task on, together with `schema_version` 3. */
+    instances?: InstanceTable;
+}
+/** `roles[<role>]`: the role's open instances in number order, `[0]` is the role itself. Only grows. */
+export interface InstanceTable {
+    roles: Record<string, string[]>;
 }
 /** `20261006T010203456Z-<128 random bits>`: sorts by start time and cannot collide, even for two starts in one millisecond. */
 export declare function newRunId(d?: Date): string;
@@ -160,7 +171,7 @@ export declare function saveRunState(runDir: string, state: RunState): void;
  * The project as one run sees it. Per-task memory is always private to the run. With the "run" layout the
  * mailboxes live inside the run dir; with "legacy" they stay the shared project mailboxes older versions used.
  */
-export declare function bindRunProject(project: ResolvedProject, runDir: string, layout: MailLayout): ResolvedProject;
+export declare function bindRunProject(project: ResolvedProject, runDir: string, layout: MailLayout, instances?: InstanceTable): ResolvedProject;
 /**
  * How a finished run turned out. Runs that ended before outcomes existed have none recorded: they read as
  * partial (failed for a failed lead) and `verified: false`, never as a success nobody checked.

package/dist/run-store.js

@@ -2,10 +2,20 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
+import { synthesizeSlots } from "./instances.js";
 import { atomicWrite } from "./fs-util.js";
 import { ERROR_KINDS, RUNTIMES } from "./schema.js";
 export const STATE_FILE = "state.json";
-export const STATE_SCHEMA_VERSION = 2;
+/** The newest state format this version reads. */
+export const STATE_SCHEMA_VERSION = 3;
+/** What a new run is written as: v3 only appears when the first parallel task opens instances (spec 23.6). */
+export const NEW_RUN_SCHEMA_VERSION = 2;
+/** Refuse a state newer than `supported`, before anything is written (the failure an older binary gives a v3 run). */
+export function assertSupportedVersion(version, supported, file) {
+    if ((version ?? 1) > supported) {
+        throw new Error(`Run state ${file} uses schema_version ${version}, newer than this agent-lyceum understands (${supported}). Upgrade agent-lyceum.`);
+    }
+}
 /** `20261006T010203456Z-<128 random bits>`: sorts by start time and cannot collide, even for two starts in one millisecond. */
 export function newRunId(d = new Date()) {
     const t = d.toISOString().replace(/[-:]/g, "").replace(/\.(\d+)Z$/, "$1Z");
@@ -68,11 +78,12 @@ const WireState = z
     name: z.string().optional(),
     reopened: z.array(z.object({ at: z.string() })).optional(),
     round_floor: nonNeg.optional(),
+    instances: z.object({ roles: z.record(z.string(), z.array(z.string()).min(1)) }).optional(),
 })
     .passthrough();
 /** A fresh v2 state; every collection present. */
 export function newRunState(init) {
-    return normalize({ ...init, schema_version: STATE_SCHEMA_VERSION, mail_layout: init.mail_layout ?? "run" });
+    return normalize({ ...init, schema_version: NEW_RUN_SCHEMA_VERSION, mail_layout: init.mail_layout ?? "run" });
 }
 function normalize(w) {
     const version = w.schema_version ?? 1;
@@ -119,9 +130,7 @@ export function loadRunState(runDir) {
         const msg = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
         throw new Error(`Run state is invalid (${file}): ${msg}`);
     }
-    if ((parsed.data.schema_version ?? 1) > STATE_SCHEMA_VERSION) {
-        throw new Error(`Run state ${file} uses schema_version ${parsed.data.schema_version}, newer than this agent-lyceum understands (${STATE_SCHEMA_VERSION}). Upgrade agent-lyceum.`);
-    }
+    assertSupportedVersion(parsed.data.schema_version, STATE_SCHEMA_VERSION, file);
     return normalize(parsed.data);
 }
 export function saveRunState(runDir, state) {
@@ -131,9 +140,10 @@ export function saveRunState(runDir, state) {
  * The project as one run sees it. Per-task memory is always private to the run. With the "run" layout the
  * mailboxes live inside the run dir; with "legacy" they stay the shared project mailboxes older versions used.
  */
-export function bindRunProject(project, runDir, layout) {
+export function bindRunProject(project, runDir, layout, instances) {
     const runId = path.basename(runDir);
-    const agents = Object.fromEntries(Object.entries(project.agents).map(([n, a]) => [n, { ...a, memory: { ...a.memory, task: path.join(project.paths.taskMemory, runId, n) } }]));
+    const bound = Object.fromEntries(Object.entries(project.agents).map(([n, a]) => [n, { ...a, memory: { ...a.memory, task: path.join(project.paths.taskMemory, runId, n) } }]));
+    const agents = instances ? synthesizeSlots(bound, instances, (slot) => path.join(project.paths.taskMemory, runId, slot)) : bound;
     const paths = layout === "run"
         ? { ...project.paths, inboxRoot: path.join(runDir, "mail", "inbox"), outboxRoot: path.join(runDir, "mail", "outbox") }
         : project.paths;

package/dist/scaffold.d.ts

@@ -1,3 +1,5 @@
+/** The lead's guidance on `parallel: true` (spec 23.12 point 5). Only `init` writes it, into a new lead AGENT.md. */
+export declare const LEAD_PARALLEL_HINT = "Mark a task `parallel: true` only when it is independent and touches different files from the other open tasks; list each task's files in `## Scope` first; shared components, types, routes and tokens go first, alone.";
 export interface InitResult {
     home: string;
     created: string[];

package/dist/scaffold.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertName, homePaths, projectPaths } from "./paths.js";
+/** The lead's guidance on `parallel: true` (spec 23.12 point 5). Only `init` writes it, into a new lead AGENT.md. */
+export const LEAD_PARALLEL_HINT = "Mark a task `parallel: true` only when it is independent and touches different files from the other open tasks; list each task's files in `## Scope` first; shared components, types, routes and tokens go first, alone.";
 const PERSONAS = {
     lead: `# Lead
 
@@ -11,6 +13,7 @@ You coordinate the team. You receive the user's task, break it into concrete pie
 - Write every task with the standard task headings, and cite the mail it derives from under Upstream so teammates can trace it.
 - When a teammate reports back, decide the next step: assign follow-up work, ask another teammate to verify, or accept the result.
 - Teammates cannot message each other by default; route everything through yourself.
+- ${LEAD_PARALLEL_HINT}
 - When the whole job is verified and finished, send a \`done\` message summarising what was delivered.
 `,
     "fe-member": `# Frontend member

package/dist/schema.d.ts

@@ -108,6 +108,7 @@ export declare const DispatcherPartial: z.ZodObject<{
         }>>;
     }, z.core.$strict>>>;
     fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
+    max_instances: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
 export declare const REMOVED_DISPATCHER_KEYS: readonly ["max_parallel", "max_concurrent_runs", "workspace_mode"];
@@ -189,6 +190,7 @@ export declare const ProjectConfig: z.ZodObject<{
             }>>;
         }, z.core.$strict>>>;
         fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
+        max_instances: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
@@ -245,6 +247,8 @@ export interface DispatcherSettings {
     log_max_bytes: number;
     /** How long a primary that hit rate_limit/quota is skipped within a run, unless the CLI says when to come back. */
     fallback_cooldown_sec: number;
+    /** Most instances of one role at a time. Not in `DISPATCHER_DEFAULTS`, so `doctor --resolved` lists it only when written; the default lives in `instances.ts`. */
+    max_instances?: number;
 }
 export declare const DISPATCHER_DEFAULTS: DispatcherSettings;
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */

package/dist/schema.js

@@ -65,6 +65,8 @@ export const DispatcherPartial = z
     log_max_bytes: z.number().int().min(0).optional(),
     fallback: z.array(FallbackEntryPartial).optional(),
     fallback_cooldown_sec: z.number().int().min(0).optional(),
+    /** Most instances of one role at a time (spec 23); 1 turns parallel tasks off. Unset = `DEFAULT_MAX_INSTANCES`. */
+    max_instances: z.number().int().min(1).max(8).optional(),
 })
     .strict();
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */

package/dist/status.d.ts

@@ -48,6 +48,8 @@ export declare function cacheText(read: number | undefined, write: number | unde
 export declare function progressBar(done: number, total: number, width?: number, c?: Paint): string;
 export interface QueueItem {
     agent: string;
+    /** Mail waiting for a free instance of the role in `agent` (spec 23.7): not woken yet, placed by the dispatcher. Only for roles with instances. */
+    held?: true;
     from: string;
     type: string;
     subject: string;
@@ -105,6 +107,8 @@ export interface RunReport {
         ok: boolean;
         error?: string;
     }>;
+    /** Only when the run has same-role instances: each role's open instances, the role itself first. */
+    instances?: Record<string, string[]>;
     /** Present while the run waits for the user: the file to fill in and how many questions are still open. */
     ask?: {
         path: string;
@@ -116,6 +120,9 @@ export interface AgentReport {
     name: string;
     runtime?: string;
     lead: boolean;
+    /** Only for the rows of a role that has instances (the role itself is instance 1): the role and the instance number. */
+    role?: string;
+    instance?: number;
     unread: number;
     /** Who this agent may send mail to (`all` expanded, itself left out). */
     can_message: string[];