agent-lyceum 0.25.1 → 0.27.0

package/dist/run-session.js

@@ -1,15 +1,18 @@
 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 { listRunLocks, lockHolderAlive } from "./project-lock.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";
@@ -18,6 +21,7 @@ import { bindRunProject, newRunId, newRunState, roundLimit, roundsLabel, saveRun
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
+import { modelForTier, wakeTier } from "./tiers.js";
 import { openPullRequest, prBody, prTitle, realRunner } from "./open-pr.js";
 export { newRunId };
 export const RESULT_FILE = "result.md";
@@ -35,6 +39,8 @@ function readIndex(file) {
 }
 /** The `state.sessions` key of the session an agent runs in on candidate `c`: a backup has a session of its own. */
 const sessionKeyOf = (agent, c) => (c.primary ? agent.name : `${agent.name}@${c.key}`);
+/** Why `key` is cooling down, for a message. */
+const cooldownKind = (cd, key) => cd.toJSON()[key]?.kind ?? "unknown";
 /** `runtime/model`, or the runtime alone for its default model. */
 const modelLabel = (c) => (c.model ? `${c.runtime}/${c.model}` : c.runtime);
 /** Each model given up on once, in order, with its last failure (retries on the same model are one entry). */
@@ -50,6 +56,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 +90,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 +134,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 +154,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;
@@ -197,7 +245,8 @@ export class RunSession {
         }
         const saveState = () => saveRunState(runDir, state);
         // Concurrent runs: the repo's instruction files the run can touch are the lead worktree's copies; your own tree is never watched (or restored).
-        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project);
+        const otherLiveRuns = () => listRunLocks(project.paths.root).filter((l) => l.run_id !== runId && lockHolderAlive(l)).map((l) => l.run_id);
+        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project, otherLiveRuns);
         if (resume) {
             log("resume", { rounds: state.rounds, interrupted: Object.keys(resume.active ?? {}) });
             if (opts.followup) {
@@ -237,7 +286,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 +325,216 @@ export class RunSession {
         log("note", { text });
         say(`  ${text}`);
     }
+    /** Spec 24.5.2: log every tier that was dropped; tell the sender once per reason (`no-tiers` is log-only). */
+    noteTierIgnored(route) {
+        for (const t of route.tierIgnored) {
+            this.log("tier_ignored", { from: t.from, id: t.id, to: t.to, reason: t.reason });
+            if (t.reason === "no-tiers")
+                continue;
+            const key = `tier\u0000${t.from}\u0000${t.reason}`;
+            if (this.ignoredNoted.has(key))
+                continue;
+            this.ignoredNoted.add(key);
+            this.note(t.reason === "not-lead"
+                ? `${t.from}'s mail ${t.id} has \`tier\`, but only the lead (${this.project.lead}) can choose a member's tier: it was delivered without one.`
+                : `${t.from}'s mail ${t.id} ("${t.subject}") has \`tier\` but is a ${t.type}: tiers apply to tasks only, so it was delivered without one.`);
+        }
+    }
+    /** 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)
@@ -312,11 +575,21 @@ export class RunSession {
             timeoutSec: cfg.wake_timeout_sec,
         };
         // Without a fallback chain (one candidate) the loop, its output and its records are exactly those of plain retries (spec 20.2 decision 11).
-        const all = candidatesFor(agent);
+        // A lead's `tier` (spec 24.5.3): only for an agent with a ladder, and only a valid value counts.
+        const tier = agent.tiers && agent.tiers.length >= 2 ? wakeTier(unread.map((m) => m.meta.tier)) : undefined;
+        const all = candidatesFor(agent, tier && agent.tiers ? modelForTier(agent.tiers, tier) : undefined);
         const chain = all.length > 1;
-        const candidates = chain ? planAttempts(agent, cooldowns, Date.now()) : all;
+        const candidates = chain ? planAttempts(all, cooldowns, Date.now()) : all;
+        const ceiling = must(all.find((c) => c.primary), "the agent's own model");
+        const tieredFirst = all[0]?.tiered ? all[0] : undefined;
         // The model a backup's calls stand in for: the one switched away from in this wake, or the cooling-down primary it started past.
-        let replaced = candidates[0]?.primary ? undefined : all[0];
+        // A tier's cheaper model is not a fallback (spec 24.7.3): only chain entries have one.
+        let replaced = candidates[0]?.primary || candidates[0]?.tiered ? undefined : ceiling;
+        if (tieredFirst && !candidates[0]?.tiered) {
+            const left = Math.ceil(cooldowns.active(tieredFirst.key, Date.now()) / 1000);
+            say(`  ${agent.name} tier ${tier} model ${modelLabel(tieredFirst)} is cooling down (${cooldownKind(cooldowns, tieredFirst.key)}, ${left}s left): starting on ${modelLabel(candidates[0])}`);
+            log("tier_step_up", { agent: agent.name, tier, from: modelLabel(tieredFirst), to: modelLabel(candidates[0]), reason: "cooldown" });
+        }
         let calls = 0;
         let stoppedByCancel = false;
         const outcome = await runWithFallback({
@@ -337,8 +610,19 @@ export class RunSession {
                 return state.max_rounds > 0 && state.rounds >= state.max_rounds ? "stop" : undefined;
             },
             onSwitch: (from, to, kind) => {
-                replaced = from;
+                if (!from.tiered)
+                    replaced = from;
                 this.syncCooldowns();
+                if (from.tiered) {
+                    log("tier_step_up", { agent: agent.name, tier, from: modelLabel(from), to: modelLabel(to), reason: kind ?? "unknown" });
+                    if (opts.signal?.aborted)
+                        return;
+                    say(`  ${agent.name} stepping up from tier ${tier} (${modelLabel(from)}) to ${modelLabel(to)} (${kind ?? "unknown error"})`);
+                    const resumesTo = agent.resume && !!state.sessions[sessionKeyOf(agent, to)];
+                    this.note(`${agent.name}'s tier ${tier} model ${modelLabel(from)} failed (${kind ?? "unknown error"}); it is woken again on ${modelLabel(to)}, which ${resumesTo ? "resumes its own earlier session" : "starts a fresh session"}, and redoes this wake-up. ` +
+                        `Anything the failed attempts already did outside the mailbox (file edits, commands) was not undone: side effects may have happened.`);
+                    return;
+                }
                 if (opts.signal?.aborted)
                     return;
                 say(`  ${agent.name} falling back to ${modelLabel(to)} (${kind ?? "unknown error"})`);
@@ -360,7 +644,7 @@ export class RunSession {
                 const redo = this.redoContext(agent.name, unread.map((m) => m.meta.id), att.id, attempt);
                 const userPrompt = redoUserPrompt(base.userPrompt, { attempt, error: ctx.previous?.error, prior: redo.prior, drafts: redo.drafts, taskMemory: agent.memory.task });
                 const retryN = chain ? ctx.candidateAttempt : attempt;
-                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime})${retryN ? ` — retry ${retryN}` : ""}`);
+                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime}${c.tiered ? `, tier ${tier}` : ""})${retryN ? ` — retry ${retryN}` : ""}`);
                 const sessionId = agent.resume ? state.sessions[sessionKey] : undefined;
                 const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
                 // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
@@ -389,7 +673,7 @@ export class RunSession {
                 state.cache_write_tokens += result.cacheWriteTokens ?? 0;
                 delete state.active[agent.name];
                 // With a chain only: which model ran, what it replaced, why it failed.
-                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || !replaced ? undefined : modelLabel(replaced), kind: result.kind } : {};
+                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || c.tiered ? undefined : modelLabel(replaced ?? ceiling), kind: result.kind } : {};
                 state.wakes.push({
                     round,
                     agent: agent.name,
@@ -402,8 +686,9 @@ export class RunSession {
                     handling,
                     error: result.error,
                     ...which,
+                    ...(tier ? { tier } : {}),
                 });
-                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}) };
+                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}), ...(tier ? { tier } : {}) };
                 log("wake", {
                     agent: agent.name,
                     runtime: c.runtime,
@@ -416,6 +701,7 @@ export class RunSession {
                     error: result.error,
                     ...(redo.prior.length ? { redo_of: redo.prior.map((a) => a.id) } : {}),
                     ...(chain ? { model: c.model, fallback_from: which.fallback_from, kind: result.kind } : {}),
+                    ...(tier ? { tier } : {}),
                 });
                 this.saveState();
                 if (result.ok) {
@@ -532,6 +818,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 +828,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 +844,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 +863,19 @@ 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.` : ""),
             });
         }
+        // Another run's lead edited a cross-run shared file: kept, not a violation of this batch, nobody is woken for it.
+        for (const u of guard.takeUnattributed()) {
+            say(`  shared file changed by another live run (${u.otherRuns.join(", ")}); kept: ${u.file}`);
+            log("protected-change-unattributed", { ...u });
+        }
+        // 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) {
@@ -603,6 +899,7 @@ export class RunSession {
                 contract = undefined;
             }
         }
+        this.noteTierIgnored(route);
         const askAccepted = this.handleAsks(route);
         for (const d of route.delivered)
             log("route", d);
@@ -846,7 +1143,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 +1153,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 +1169,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 +1206,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

@@ -1,9 +1,14 @@
 import type { ResolvedProject } from "./config.js";
 import type { DigestSection, Step } from "./format.js";
-import { type ErrorKind, type Runtime, type RunOutcome } from "./schema.js";
+import { type ErrorKind, type Runtime, type RunOutcome, type Tier } 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 {
@@ -46,6 +51,8 @@ export interface WakeRecord {
     fallback_from?: string;
     /** With a fallback chain only: why the call failed. */
     kind?: ErrorKind;
+    /** The tier this wake ran at (spec 24): set only when every mail it handled carried a valid one. */
+    tier?: Tier;
 }
 /** A model given up on during a wake with a fallback chain, for `failure.tried`. */
 export interface TriedModel {
@@ -118,6 +125,7 @@ export interface RunState {
         error?: string;
         runtime?: Runtime;
         model?: string;
+        tier?: Tier;
     }>;
     /** Process running this dispatcher, so a monitor can tell "running" from "interrupted". */
     pid: number;
@@ -146,6 +154,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 +174,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;