agent-lyceum 0.25.1 → 0.26.0

package/dist/instances.js

@@ -0,0 +1,268 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { NAME_RE, isInside } from "./paths.js";
+// Same-role dynamic instances (docs/specs/23-dynamic-instances.md). Pure functions only: the caller injects every file read.
+/** Instances one role may have at the same time when `dispatcher.max_instances` is not written. */
+export const DEFAULT_MAX_INSTANCES = 4;
+/** Instance 1 is the role itself; the others are `<role>--<k>`. */
+export const slotName = (role, k) => (k === 1 ? role : `${role}--${k}`);
+/** `<role>--<k>` with k >= 2 (no leading zero) → its parts. A name like `fe--x` is just an agent, never an instance. */
+export function parseSlotName(name) {
+    const m = /^(.+)--([2-9]|[1-9]\d+)$/.exec(name);
+    return m?.[1] && m[2] ? { role: m[1], k: Number(m[2]) } : undefined;
+}
+/**
+ * The most instances `role` may have in this run. `check(role, k)` is the caller's extra refusal for slot k (a path
+ * overlap, spec D-17): it returns a reason, and the cap stops before that slot. `opened` are instance names already in the
+ * run's slot table; they are not name clashes even though a bound project lists them among its agents.
+ */
+export function instanceCap(project, mode, role, check, opened = []) {
+    if (mode !== "worktree")
+        return { n: 1, reason: "agents take turns in the checkout, not in separate git worktrees" };
+    if (project.solo)
+        return { n: 1, reason: "a single agent runs alone" };
+    if (project.run?.layout !== "run")
+        return { n: 1, reason: "this run uses the legacy mailbox layout" };
+    if (role === project.lead)
+        return { n: 1, reason: `the lead (${role}) is never run as several instances` };
+    if (!NAME_RE.test(role))
+        return { n: 1, reason: `"${role}" is not a valid branch name, so its instances cannot be named` };
+    const max = project.dispatcher.max_instances ?? DEFAULT_MAX_INSTANCES;
+    for (let k = 2; k <= max; k++) {
+        const name = slotName(role, k);
+        if (name in project.agents && !opened.includes(name))
+            return { n: k - 1, reason: `agent "${name}" has the name instance ${k} of "${role}" would get, so "${role}" runs at most ${k - 1} instance(s) at a time` };
+        const refused = check?.(role, k);
+        if (refused)
+            return { n: k - 1, reason: `instance ${k} of "${role}" ${refused}` };
+    }
+    return { n: max };
+}
+const present = (v) => v !== undefined && v !== null && v !== "";
+/**
+ * What a mail's `parallel` field means (spec 23.3). `senderIsLead` is the router's own knowledge (the outbox owner), never the
+ * mail's `from`. `invalid` is a lead's mistake (the mail is sent back); `ignored` mail is delivered as an ordinary one.
+ */
+export function parallelFlag(input) {
+    const { value } = input;
+    if (value === undefined)
+        return "absent";
+    if (!input.senderIsLead)
+        return { ignored: "not-lead" };
+    if (typeof value !== "boolean")
+        return "invalid";
+    if (!value)
+        return "absent";
+    if (input.type !== "task" || present(input.replyTo) || present(input.thread))
+        return { ignored: "not-a-new-task" };
+    if (input.cap.n <= 1)
+        return { ignored: `parallel tasks run one at a time in this run${input.cap.reason ? `: ${input.cap.reason}` : ""}` };
+    return "on";
+}
+/**
+ * The instance of `role` that owns message `id`, so a revision goes back to it (spec 23.7.2 rule 1). Only instances the role has
+ * open count, then assign > from > about. Work from before the role was activated that involves it by name belongs to instance 1.
+ */
+export function ownersOf(id, role, ctx) {
+    const r = ctx.rec(id);
+    if (!r)
+        return undefined;
+    for (const slot of [r.assign, r.from, r.about])
+        if (slot !== undefined && ctx.opened.includes(slot))
+            return slot;
+    if (r.intent && (ctx.mark === undefined || r.intent.seq < ctx.mark) && involves(r.intent, role, ctx.claimAgent))
+        return ctx.opened[0] ?? role;
+    return undefined;
+}
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Whether a delivery already in the journal concerns `role` by its own name: sent to it, sent by it, or a dispatcher notice about
+ * it (a failed integration or a refused worktree). Uses only what the dispatcher wrote: journal fields and claim records.
+ */
+export function involves(intent, role, claimAgent) {
+    if (intent.to === role)
+        return true;
+    // the file is `<stamp>-<from>-<msg_id>.md` and a stamp has no "-", so what follows the first "-" is the sender
+    const tail = `-${intent.msg_id}.md`;
+    if (intent.file.endsWith(tail)) {
+        const head = intent.file.slice(0, -tail.length);
+        const dash = head.indexOf("-");
+        if (dash > 0 && head.slice(dash + 1) === role)
+            return true;
+    }
+    if (intent.source.startsWith("integration:")) {
+        const key = intent.source.slice("integration:".length);
+        if (!key || key.includes("/") || key.includes("\\") || key.includes(".."))
+            return false;
+        const agent = claimAgent(key);
+        if (agent !== undefined)
+            return agent === role;
+        return new RegExp(`^${escapeRe(role)}-\\d+$`).test(key);
+    }
+    if (intent.source.startsWith("refused:")) {
+        const parts = intent.source.split(":");
+        return parts.length >= 3 && parts[parts.length - 1] === role;
+    }
+    return false;
+}
+/**
+ * Where each waiting message of one role goes (spec 23.7.2). A decision never depends on a later message; a message that has to
+ * wait only holds back the new threads behind it for the same destination.
+ */
+export function planAssignments(input) {
+    const opened = [...input.opened];
+    const taken = new Set();
+    const out = { assign: [], waiting: [] };
+    // Where this plan already put each message: a later mail of the same batch that replies to it follows it before the journal is asked.
+    const planned = new Map();
+    const place = (m, a) => {
+        taken.add(a.slot);
+        planned.set(m.id, a.slot);
+        out.assign.push(a);
+    };
+    let parallelWait;
+    const wait = (m, reason) => out.waiting.push({ file: m.file, reason });
+    for (const m of input.held) {
+        const done = input.recorded(m.id);
+        if (done !== undefined) {
+            place(m, { file: m.file, slot: done, rule: "recorded" });
+            continue;
+        }
+        let owner;
+        for (const c of [m.replyTo, m.thread]) {
+            if (!c || c === m.id)
+                continue;
+            owner = planned.get(c) ?? input.owners(c);
+            if (owner !== undefined)
+                break;
+        }
+        if (owner !== undefined) {
+            place(m, { file: m.file, slot: owner, rule: "affinity", ...(m.to !== input.role && m.to !== owner ? { addressed: m.to } : {}) });
+            continue;
+        }
+        if (m.to !== input.role) {
+            const a = opened.includes(m.to) ? input.acceptsNew(m.to) : "unknown-slot";
+            if (a === true) {
+                place(m, { file: m.file, slot: m.to, rule: "addressed" });
+            }
+            else
+                wait(m, a);
+            continue;
+        }
+        if (m.parallel) {
+            if (parallelWait !== undefined) {
+                wait(m, parallelWait);
+                continue;
+            }
+            const free = opened.find((s) => input.acceptsNew(s) === true && !input.busy(s) && !taken.has(s));
+            if (free !== undefined) {
+                place(m, { file: m.file, slot: free, rule: "parallel" });
+                continue;
+            }
+            let why;
+            if (opened.length < input.cap) {
+                const name = slotName(input.role, opened.length + 1);
+                const may = input.coolingDown ? "cooldown" : input.mayOpen(name);
+                if (may === true) {
+                    opened.push(name);
+                    place(m, { file: m.file, slot: name, rule: "parallel", open: name });
+                    continue;
+                }
+                why = may;
+            }
+            else
+                why = opened.some((s) => input.acceptsNew(s) === true) ? "busy" : "cap";
+            parallelWait = why;
+            wait(m, why);
+            continue;
+        }
+        const a = input.acceptsNew(input.role);
+        if (a === true) {
+            place(m, { file: m.file, slot: input.role, rule: "default" });
+        }
+        else
+            wait(m, a);
+    }
+    return out;
+}
+/**
+ * The agents of a run with its opened instances added (spec 23.6): each `<role>--<k>` follows its role, copies the role's settings, keeps only
+ * its own task memory (the role's global/project memory become read-only `sharedMemory`) and cannot edit AGENT.md. Roles of the table that
+ * are not agents any more are skipped (a resume refuses those before it binds, `assertInstancesResumable`).
+ */
+export function synthesizeSlots(agents, table, taskMemory) {
+    const out = {};
+    for (const [name, a] of Object.entries(agents)) {
+        const slots = table.roles[name];
+        if (!slots) {
+            out[name] = a;
+            continue;
+        }
+        out[name] = { ...a, instance: { role: name, k: 1 } };
+        for (const slot of slots) {
+            const parsed = parseSlotName(slot);
+            if (!parsed || parsed.role !== name)
+                continue;
+            out[slot] = {
+                ...a,
+                name: slot,
+                memory: { task: taskMemory(slot) },
+                sharedMemory: { ...(a.memory.global ? { global: a.memory.global } : {}), ...(a.memory.project ? { project: a.memory.project } : {}) },
+                canEditAgentMd: false,
+                instance: { role: name, k: parsed.k },
+            };
+        }
+    }
+    return out;
+}
+/** The role an agent name stands for: the role itself, or the role of a bound instance. */
+export const roleOfName = (agents, name) => agents[name]?.instance?.role ?? name;
+/** How the lead is told who a mail came from (decision 8): a bound instance of a role with several shows its role and number. */
+export function senderLabel(name, agents) {
+    const i = agents[name]?.instance;
+    return i ? `${name} (${i.role}, instance ${i.k})` : name;
+}
+/** Key of the one failure sent to the lead about this set of waiting mails (spec D-16). */
+export const heldStallKey = (ids) => `held-stall:${crypto.createHash("sha256").update([...ids].sort().join("\n")).digest("hex").slice(0, 16)}`;
+/**
+ * Refuse, before anything is written, to resume a run whose slot table no longer fits the configuration (spec 23.10): a role that
+ * is gone or is now the lead, an instance name that is now a configured agent, or an opened instance `check` finds a conflict for.
+ */
+export function assertInstancesResumable(base, table, runId, projectName, check) {
+    for (const [role, slots] of Object.entries(table.roles)) {
+        if (!(role in base.agents)) {
+            throw new Error(`Run ${runId} has instances of "${role}", which is no longer an agent of project ${projectName}. Add "${role}" back to project.yaml to finish or resume this run, or clear it.`);
+        }
+        if (role === base.lead)
+            throw new Error(`Run ${runId} has instances of "${role}", which is now the lead of project ${projectName}; the lead never runs as several instances. Make "${role}" a member again to resume this run, or clear it.`);
+        for (const slot of slots.slice(1)) {
+            if (slot in base.agents)
+                throw new Error(`Run ${runId} has the instance "${slot}" of "${role}", but project ${projectName} now has an agent of that name. Rename that agent to resume this run, or clear it.`);
+            const parsed = parseSlotName(slot);
+            const conflict = parsed ? check?.(role, parsed.k) : undefined;
+            if (conflict)
+                throw new Error(`Run ${runId} cannot be resumed: ${slot} ${conflict}`);
+        }
+    }
+}
+// ---- containment of the shared memory (spec 23.11, D-17) ----
+/** Every directory an instance can write: what its policy allows, the folders of the files it may edit, and its working directory. */
+export const slotWritableRoots = (pol, work) => [
+    ...new Set([...pol.allowDirs, ...pol.allowFiles.map((f) => path.dirname(f)), ...work]),
+];
+/**
+ * The first pair of (shared memory path, writable root) where one contains the other, or undefined. `canon` resolves symlinks (the caller injects
+ * it); `caseInsensitive` compares in lower case (macOS volumes), which can only report a conflict that is not one, never miss one.
+ */
+export function containmentConflict(shared, roots, canon, caseInsensitive) {
+    const norm = (p) => (caseInsensitive ? canon(p).toLowerCase() : canon(p));
+    for (const s of shared) {
+        const cs = norm(s);
+        for (const w of roots) {
+            const cw = norm(w);
+            if (isInside(cs, cw) || isInside(cw, cs))
+                return { shared: s, root: w };
+        }
+    }
+    return undefined;
+}

package/dist/mailbox.d.ts

@@ -1,6 +1,7 @@
 import type { ResolvedProject } from "./config.js";
 import { type Step } from "./format.js";
 import { atomicWrite } from "./fs-util.js";
+import { type InstanceCap } from "./instances.js";
 import { RouteJournal } from "./message-store.js";
 export { atomicWrite };
 export declare const MESSAGE_TYPES: readonly ["task", "reply", "failure", "done", "ask"];
@@ -29,6 +30,8 @@ export declare function parseRaw(text: string): {
     body: string;
 };
 export declare function ensureProjectDirs(project: ResolvedProject): void;
+/** The mailbox and memory directories of one agent (a newly opened instance gets just its own). */
+export declare function ensureAgentDirs(project: ResolvedProject, name: string): void;
 export interface DeliverInput {
     from: string;
     to: string;
@@ -49,11 +52,22 @@ export declare function deliver(project: ResolvedProject, input: DeliverInput &
  * the plan (id, file name, timestamp) is journaled before anything is written, a retry writes the identical file,
  * and mail the recipient already read is never written again. Without a run (no journal) it just delivers.
  */
-export declare function deliverOnce(project: ResolvedProject, journal: RouteJournal | undefined, sourceKey: string, input: DeliverInput): {
+export declare function deliverOnce(project: ResolvedProject, journal: RouteJournal | undefined, sourceKey: string, input: DeliverInput, extra?: DeliverExtra): {
     msg: Message;
     fresh: boolean;
 };
+/** What a delivery records in the journal beyond the plain intent (spec 23.7.1); all of it only for roles with several instances. */
+export interface DeliverExtra {
+    held?: boolean;
+    parallel?: boolean;
+    from?: string;
+    about?: string;
+}
+/** Mail for a role that has instances waits here, in the role's inbox, until the assigner places it. */
+export declare const PENDING_DIR = "pending";
 export declare function readMessage(file: string): Message;
+/** `readMessage` for files that may be anything (held mail): a symlink, FIFO or other non-regular entry throws instead of being followed or blocking. */
+export declare function readMessageNoFollow(file: string): Message;
 /** Paths of the unread messages in an agent's inbox, oldest name first. Does not open them. */
 export declare function unreadFiles(project: ResolvedProject, agent: string): string[];
 export declare function listUnread(project: ResolvedProject, agent: string): Message[];
@@ -103,5 +117,21 @@ export interface RouteResult {
 export declare function finishDone(file: string): void;
 /** Set a `done` that broke the completion contract aside (in the outbox's `rejected/`). */
 export declare function rejectDone(file: string): void;
+/** What the router needs from the run to handle same-role instances (spec 23.7.1); a call without it routes as before. */
+export interface InstanceRouting {
+    /** The most instances `role` may have, and why it is lower than configured. */
+    cap(role: string): InstanceCap;
+    /** The role already has instances: its mail waits in `pending/`. */
+    held(role: string): boolean;
+    /** Make the role's instances durable (slot table, schema_version 3) before any file of the mail that opens them is written. */
+    enable(role: string): void;
+    /** A `parallel` field that was delivered as an ordinary mail, and why. */
+    ignored(reason: string, meta: {
+        from: string;
+        id: string;
+        to: string;
+        subject: string;
+    }): void;
+}
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
-export declare function routeOutboxes(project: ResolvedProject): RouteResult;
+export declare function routeOutboxes(project: ResolvedProject, routing?: InstanceRouting): RouteResult;

package/dist/mailbox.js

@@ -3,8 +3,9 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { formatWarning, missingSections, parseSteps } from "./format.js";
-import { atomicWrite } from "./fs-util.js";
+import { atomicWrite, readRegularFileNoFollow } from "./fs-util.js";
 import { countFormatRejection, formatRejectionKey, formatRejections, MAX_FORMAT_REJECTIONS } from "./format-rejections.js";
+import { parallelFlag, roleOfName } from "./instances.js";
 import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-store.js";
 import { inboxDir, outboxDir, sharedDir } from "./policy.js";
 import { activeRecordsBytes, RECORD_KINDS, RECORDS_BUDGET } from "./records.js";
@@ -38,14 +39,17 @@ export function ensureProjectDirs(project) {
     const handoff = sharedDir(project);
     if (handoff)
         fs.mkdirSync(handoff, { recursive: true });
-    for (const name of Object.keys(project.agents)) {
-        fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
-        fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });
-        const a = must(project.agents[name], `agent ${name}`);
-        for (const m of [a.memory.global, a.memory.project, a.memory.task])
-            if (m)
-                fs.mkdirSync(m, { recursive: true });
-    }
+    for (const name of Object.keys(project.agents))
+        ensureAgentDirs(project, name);
+}
+/** The mailbox and memory directories of one agent (a newly opened instance gets just its own). */
+export function ensureAgentDirs(project, name) {
+    fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
+    fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });
+    const a = must(project.agents[name], `agent ${name}`);
+    for (const m of [a.memory.global, a.memory.project, a.memory.task])
+        if (m)
+            fs.mkdirSync(m, { recursive: true });
 }
 /** Deliver a message into `to`'s inbox (dispatcher-side; senders other than agents allowed). */
 export function deliver(project, input) {
@@ -70,7 +74,7 @@ export function deliver(project, input) {
  * the plan (id, file name, timestamp) is journaled before anything is written, a retry writes the identical file,
  * and mail the recipient already read is never written again. Without a run (no journal) it just delivers.
  */
-export function deliverOnce(project, journal, sourceKey, input) {
+export function deliverOnce(project, journal, sourceKey, input, extra = {}) {
     if (!journal)
         return { msg: deliver(project, input), fresh: true };
     const prior = journal.get(sourceKey, input.to);
@@ -81,14 +85,23 @@ export function deliverOnce(project, journal, sourceKey, input) {
             msg_id: deterministicId(sourceKey, input.to),
             file: `${stamp()}-${input.from}-${deterministicId(sourceKey, input.to)}.md`,
             created: new Date().toISOString(),
+            ...(extra.held ? { held: true } : {}),
+            ...(extra.parallel ? { parallel: true } : {}),
+            ...(extra.from ? { from: extra.from } : {}),
+            ...(extra.about ? { about: extra.about } : {}),
         });
     fault("route:intent");
-    const dest = path.join(inboxDir(project, input.to), planned.file);
+    // A replay goes where the first attempt was planned to go: the journal's `held`, not the current state of the run.
+    const held = planned.held === true;
+    const inbox = inboxDir(project, held ? roleOfName(project.agents, input.to) : input.to);
+    const dest = path.join(held ? path.join(inbox, PENDING_DIR) : inbox, planned.file);
     const meta = deliveredMeta(project, input, planned);
     const want = serialize(meta, input.body);
     const alreadyRead = fs.existsSync(path.join(path.dirname(dest), "read", planned.file));
+    // A held mail that was delivered (or assigned) may have been moved out of `pending/` already: it is never written again.
+    const settled = held && (planned.delivered || journal.assigned(planned.msg_id) !== undefined);
     // Write the planned file; if one is already there, verify it instead of trusting it. Mail already read is never written again.
-    if (!alreadyRead && (!fs.existsSync(dest) || fs.readFileSync(dest, "utf8") !== want))
+    if (!settled && !alreadyRead && (!fs.existsSync(dest) || fs.readFileSync(dest, "utf8") !== want))
         atomicWrite(dest, want);
     fault("route:written");
     const fresh = !planned.delivered;
@@ -97,6 +110,8 @@ export function deliverOnce(project, journal, sourceKey, input) {
     fault("route:delivered");
     return { msg: { meta, body: input.body, file: dest }, fresh };
 }
+/** Mail for a role that has instances waits here, in the role's inbox, until the assigner places it. */
+export const PENDING_DIR = "pending";
 function deliveredMeta(project, input, planned) {
     return {
         id: planned.msg_id,
@@ -115,6 +130,14 @@ export function readMessage(file) {
     const meta = data;
     return { meta, body, file };
 }
+/** `readMessage` for files that may be anything (held mail): a symlink, FIFO or other non-regular entry throws instead of being followed or blocking. */
+export function readMessageNoFollow(file) {
+    const buf = readRegularFileNoFollow(file);
+    if (!buf)
+        throw new Error(`${file} is not a readable regular file`);
+    const { data, body } = parseRaw(buf.toString("utf8"));
+    return { meta: data, body, file };
+}
 /** Paths of the unread messages in an agent's inbox, oldest name first. Does not open them. */
 export function unreadFiles(project, agent) {
     const dir = inboxDir(project, agent);
@@ -176,12 +199,15 @@ function sameText(body) {
  * An earlier mail from `from` to `to` with the same type, the same reply target and the same text (unread or already read):
  * sending it again changes nothing and is how two agents end up in a loop. Texts too short to mean anything are never duplicates.
  */
-function earlierDuplicate(project, from, to, type, replyTo, body) {
+function earlierDuplicate(project, from, to, type, replyTo, body, held = false) {
     const text = sameText(body);
     if (text.length < 20)
         return undefined;
     const dir = inboxDir(project, to);
-    for (const d of [dir, path.join(dir, "read")]) {
+    const role = roleOfName(project.agents, to);
+    const slots = held ? Object.values(project.agents).filter((a) => roleOfName(project.agents, a.name) === role).map((a) => inboxDir(project, a.name)) : [dir];
+    const dirs = held ? [...slots.flatMap((d) => [d, path.join(d, "read")]), path.join(inboxDir(project, role), PENDING_DIR)] : [dir, path.join(dir, "read")];
+    for (const d of dirs) {
         if (!fs.existsSync(d))
             continue;
         for (const e of fs.readdirSync(d, { withFileTypes: true })) {
@@ -200,7 +226,7 @@ function earlierDuplicate(project, from, to, type, replyTo, body) {
     return undefined;
 }
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
-export function routeOutboxes(project) {
+export function routeOutboxes(project, routing) {
     const res = { delivered: [], rejected: [], warnings: [], asks: [] };
     const journal = project.run ? new RouteJournal(project.run.dir) : undefined;
     for (const sender of Object.values(project.agents)) {
@@ -276,7 +302,15 @@ export function routeOutboxes(project) {
                 reject(`missing "to".`);
                 continue;
             }
-            const bad = targets.find((t) => !project.agents[t] || t === sender.name || (sender.canMessage !== "all" && !sender.canMessage.includes(t)));
+            const roleOf = (n) => roleOfName(project.agents, n);
+            if (sender.instance) {
+                const same = targets.find((t) => t !== sender.name && roleOf(t) === roleOf(sender.name));
+                if (same !== undefined) {
+                    reject(`cannot message another instance of your own role ("${same}" is an instance of "${roleOf(sender.name)}"). Put what it needs in your reply to the lead.`);
+                    continue;
+                }
+            }
+            const bad = targets.find((t) => !project.agents[t] || t === sender.name || (sender.canMessage !== "all" && !sender.canMessage.includes(roleOf(t))));
             if (bad !== undefined) {
                 const why = !project.agents[bad]
                     ? `no such agent "${bad}"`
@@ -286,6 +320,18 @@ export function routeOutboxes(project) {
                 reject(why + ".");
                 continue;
             }
+            // `parallel` is read here from the outbox file, but only a verdict on it is kept: it goes to the journal (never back into the mail).
+            const flags = new Map();
+            if (routing && d.parallel !== undefined) {
+                for (const t of targets) {
+                    const role = roleOf(t);
+                    flags.set(t, parallelFlag({ value: d.parallel, senderIsLead: sender.name === project.lead, type, replyTo: d.reply_to, thread: d.thread, cap: routing.cap(role) }));
+                }
+                if ([...flags.values()].includes("invalid")) {
+                    reject(`parallel must be true or false (YAML boolean), not ${JSON.stringify(d.parallel)}. Write \`parallel: true\` on a new task to run it in a parallel instance, or leave the line out.`);
+                    continue;
+                }
+            }
             const missing = missingSections(type, parsed.body);
             if (missing.length && project.run?.layout === "run") {
                 const key = formatRejectionKey(sender.name, type, subject);
@@ -302,7 +348,7 @@ export function routeOutboxes(project) {
             for (const to of targets) {
                 if (journal?.get(source, to))
                     continue;
-                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body);
+                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body, !!routing?.held(roleOf(to)));
                 if (earlier)
                     repeats.set(to, earlier);
             }
@@ -333,7 +379,19 @@ export function routeOutboxes(project) {
             for (const to of targets) {
                 if (repeats.has(to))
                     continue;
-                const { msg, fresh } = deliverOnce(project, journal, source, { from: sender.name, to, type, subject, body, thread, reply_to: replyTo });
+                const flag = flags.get(to);
+                const role = roleOf(to);
+                if (typeof flag === "object" && !journal?.get(source, to))
+                    routing?.ignored(flag.ignored, { from: sender.name, id: deterministicId(source, to), to, subject });
+                // The first valid parallel task makes the role's instances durable before a single file of this mail exists.
+                if (routing && flag === "on" && !routing.held(role))
+                    routing.enable(role);
+                const held = !!routing?.held(role);
+                const { msg, fresh } = deliverOnce(project, journal, source, { from: sender.name, to, type, subject, body, thread, reply_to: replyTo }, {
+                    ...(held ? { held: true } : {}),
+                    ...(held && flag === "on" ? { parallel: true } : {}),
+                    ...(routing?.held(roleOf(sender.name)) ? { from: sender.name } : {}),
+                });
                 if (!fresh)
                     continue;
                 res.delivered.push({ from: sender.name, to, id: msg.meta.id, file: msg.file, type, subject });

package/dist/message-store.d.ts

@@ -9,15 +9,61 @@ export interface JournalEntry {
     file: string;
     created: string;
     delivered: boolean;
+    /** Same-role instances (spec 23): the mail waits in `inbox/<role>/pending/` for the assigner. Only written for an activated role. */
+    held?: true;
+    /** The lead marked it `parallel: true` (read only from here, never from the mail file). */
+    parallel?: true;
+    /** The instance of an activated role that sent it. */
+    from?: string;
+    /** The instance a dispatcher notice is about. */
+    about?: string;
+    /** Position of the intent among the journal's records (a line cut short by a crash does not count). */
+    seq?: number;
+}
+/** What the journal knows about one message id: where the assigner put it, who sent it or what it is about, and its delivery line. */
+export interface Ownership {
+    assign?: string;
+    from?: string;
+    about?: string;
+    intent?: {
+        seq: number;
+        to: string;
+        file: string;
+        source: string;
+        msg_id: string;
+    };
 }
 /** Append-only log of deliveries. A delivery is identified by `(source, recipient)`, never by a random id. */
 export declare class RouteJournal {
     private readonly file;
     private readonly entries;
+    private readonly byMsg;
+    private readonly byFileName;
+    private readonly assigns;
+    private readonly firstHeldSeq;
+    private seqNext;
     constructor(runDir: string);
+    /** Enter an intent in every index; `seq` is its position among the records read or appended. */
+    private index;
     get(source: string, to: string): JournalEntry | undefined;
     private append;
-    intent(e: Omit<JournalEntry, "delivered">): JournalEntry;
+    intent(e: Omit<JournalEntry, "delivered" | "seq">): JournalEntry;
+    /** The assigner's decision for a held mail, made durable before the file moves (spec 23.7.2). */
+    assign(a: {
+        msg_id: string;
+        file: string;
+        role: string;
+        slot: string;
+    }): void;
+    assigned(msgId: string): {
+        slot: string;
+        file: string;
+        role: string;
+    } | undefined;
+    byFile(file: string): JournalEntry | undefined;
+    /** Position of the first held intent addressed to `name`; undefined when there is none. */
+    firstHeld(name: string): number | undefined;
+    ownership(msgId: string): Ownership | undefined;
     delivered(source: string, to: string): void;
 }
 /** Stable id of one outbox file instance: who wrote it, its name, when, and what it said. */