agent-lyceum 0.25.1 → 0.26.0

package/README.md

@@ -40,7 +40,7 @@ Latest unreleased code: `npx github:gogogohuang/agent-lyceum <command>`.
 3. Agents reply by writing mail to their own `outbox/`; the dispatcher checks `can_message` and delivers it.
 4. The run ends when the lead sends `done`.
 
-Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyceum-config/`, not in your repo. Concurrency needs no configuration. In a git repo with a commit, every run works in its own git worktree and ends on its own branch (`agent-lyceum/<run>/…`), members with pending mail wake in parallel, and any number of runs can be active at once; the result is not written into your working tree, so use `git merge <branch>` or `open_pr`, and note that a run starts from `HEAD` and does not see your uncommitted edits. In a non-git folder, a repo with no commit, or a repo using reftable, the run works directly in the folder, one agent at a time (an info line says why), and only one such run can be active. agent-lyceum never merges. Upgrading from a version with `owns`, `max_parallel`, `max_concurrent_runs` or `workspace_mode`: see [Upgrading](docs/upgrading-run-v2.md). More: [How a run works](docs/how-it-works.md), [Configuration](docs/configuration.md).
+Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyceum-config/`, not in your repo. Concurrency needs no configuration. In a git repo with a commit, every run works in its own git worktree and ends on its own branch (`agent-lyceum/<run>/…`), members with pending mail wake in parallel, and any number of runs can be active at once; the result is not written into your working tree, so use `git merge <branch>` or `open_pr`, and note that a run starts from `HEAD` and does not see your uncommitted edits. In a non-git folder, a repo with no commit, or a repo using reftable, the run works directly in the folder, one agent at a time (an info line says why), and only one such run can be active. A lead can mark independent tasks `parallel: true` so one member works on several at once, each in its own worktree (worktree mode only, the lead decides, at most `dispatcher.max_instances` per member, default 4); see [How a run works](docs/how-it-works.md#parallel-instances-of-one-member). agent-lyceum never merges. Upgrading from a version with `owns`, `max_parallel`, `max_concurrent_runs` or `workspace_mode`: see [Upgrading](docs/upgrading-run-v2.md). More: [How a run works](docs/how-it-works.md), [Configuration](docs/configuration.md).
 
 ## Commands
 
@@ -82,6 +82,6 @@ Folder layout, every agent field and the rules `doctor` checks: [Configuration](
 | Run lifecycle, parallel agents, several runs at once, follow-ups, opening a PR | [How a run works](docs/how-it-works.md) |
 | What agents may write, sandbox levels, known gaps | [Write scope](docs/write-scope.md) |
 | Letting an agent search or fetch the web | [Web access](docs/web-access.md) |
-| Live run status inside Claude Code | [Monitor mod](docs/monitor.md) |
+| Live run status inside Claude Code (a framed, state-coloured tree of agents; pane or full-width band) | [Monitor mod](docs/monitor.md) |
 | All commands in full | [Commands](docs/commands.md) |
 | Coming from an older version | [Upgrading to run v2](docs/upgrading-run-v2.md) |

package/README.zh-TW.md

@@ -40,7 +40,7 @@ npx agent-lyceum status
 3. agent 把回信寫進自己的 `outbox/`，dispatcher 檢查 `can_message` 後投遞。
 4. lead 寄出 `done` 時，run 結束。
 
-工具自己的資料（設定、信箱、log、記憶、worktree）放在 `~/agent-lyceum-config/`，不放進你的 repo。並行不需要任何設定。在有 commit 的 git repo 裡，每個 run 都在自己的 git worktree 工作，並結束在自己的 branch（`agent-lyceum/<run>/…`）；有待處理信件的成員會平行喚醒，同時也可有任意多個 run；結果不會寫進你的工作目錄，請用 `git merge <branch>` 或 `open_pr`，且 run 從 `HEAD` 起跑，看不到你未提交的修改。在非 git 資料夾、沒有 commit 的 repo 或使用 reftable 的 repo，run 直接在該資料夾工作、一次只跑一個 agent（會有一行說明原因），且同時只能有一個這樣的 run。agent-lyceum 不會幫你合併。從有 `owns`、`max_parallel`、`max_concurrent_runs` 或 `workspace_mode` 的版本升級：見[升級](docs/upgrading-run-v2.md)。詳見[一次執行如何運作](docs/how-it-works.zh-TW.md)、[設定](docs/configuration.zh-TW.md)。
+工具自己的資料（設定、信箱、log、記憶、worktree）放在 `~/agent-lyceum-config/`，不放進你的 repo。並行不需要任何設定。在有 commit 的 git repo 裡，每個 run 都在自己的 git worktree 工作，並結束在自己的 branch（`agent-lyceum/<run>/…`）；有待處理信件的成員會平行喚醒，同時也可有任意多個 run；結果不會寫進你的工作目錄，請用 `git merge <branch>` 或 `open_pr`，且 run 從 `HEAD` 起跑，看不到你未提交的修改。在非 git 資料夾、沒有 commit 的 repo 或使用 reftable 的 repo，run 直接在該資料夾工作、一次只跑一個 agent（會有一行說明原因），且同時只能有一個這樣的 run。lead 可以把互不相依的 task 標成 `parallel: true`，讓一位成員同時處理多件，各在自己的 worktree（僅 worktree 模式、由 lead 決定、每位成員最多 `dispatcher.max_instances` 個，預設 4）；見[一次執行如何運作](docs/how-it-works.zh-TW.md#同一成員的平行實例)。agent-lyceum 不會幫你合併。從有 `owns`、`max_parallel`、`max_concurrent_runs` 或 `workspace_mode` 的版本升級：見[升級](docs/upgrading-run-v2.md)。詳見[一次執行如何運作](docs/how-it-works.zh-TW.md)、[設定](docs/configuration.zh-TW.md)。
 
 ## 指令
 
@@ -82,6 +82,6 @@ agents:
 | run 的生命週期、平行 agent、同時多個 run、追加需求、開 PR | [一次執行如何運作](docs/how-it-works.zh-TW.md) |
 | agent 能寫什麼、沙箱等級、已知缺口 | [寫入範圍](docs/write-scope.zh-TW.md) |
 | 讓 agent 搜尋或讀取網頁 | [網路存取](docs/web-access.zh-TW.md) |
-| 在 Claude Code 內看即時 run 狀態 | [監控 mod](docs/monitor.zh-TW.md) |
+| 在 Claude Code 內看即時 run 狀態（每個 agent 一個依狀態上色的外框，樹狀排列；面板或整寬橫幅） | [監控 mod](docs/monitor.zh-TW.md) |
 | 所有指令的完整說明 | [指令](docs/commands.zh-TW.md) |
 | 從舊版升級 | [升級到 run v2](docs/upgrading-run-v2.md) |

package/dist/config.d.ts

@@ -33,6 +33,16 @@ export interface ResolvedAgent {
     }[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
+    /** Set when the run bound this agent as an instance of a role that has several (spec 23): which role, and the instance number. */
+    instance?: {
+        role: string;
+        k: number;
+    };
+    /** Instances 2 and up: the role's global/project memory, which only instance 1 may write. */
+    sharedMemory?: {
+        global?: string;
+        project?: string;
+    };
 }
 export interface ResolvedProject {
     home: string;
@@ -52,7 +62,10 @@ export interface ResolvedProject {
     run?: {
         id: string;
         dir: string;
-        layout: "run" | "legacy";
+        layout: "run" | "legacy"; /** Set by the run when same-role instances are possible: the lead's prompt then explains `parallel: true`. */
+        instances?: {
+            max: number;
+        };
     };
     /** Agents working in their own git worktree instead of `dir` (set by the dispatcher for the wake-ups in progress). */
     workspaces?: Record<string, AgentWorkspace>;
@@ -102,6 +115,7 @@ export declare function loadProjectRaw(home: string, name: string): {
             effort?: "high" | "low" | "max" | "medium" | "minimal" | "xhigh" | undefined;
         }[] | undefined;
         fallback_cooldown_sec?: number | undefined;
+        max_instances?: number | undefined;
     };
     agents: Record<string, {
         runtime?: "claude-code" | "codex" | undefined;

package/dist/config.js

@@ -276,6 +276,8 @@ export function resolveProjectWithSources(home, name) {
             continue;
         sources[`dispatcher.${k}`] = raw.dispatcher[k] !== undefined ? { file: projectFile, key: `dispatcher.${k}` } : { default: true };
     }
+    if (raw.dispatcher.max_instances !== undefined)
+        sources["dispatcher.max_instances"] = { file: projectFile, key: "dispatcher.max_instances" };
     for (const a of Object.values(project.agents)) {
         const at = (src, field) => {
             const key = `agents.${a.name}.${field}`;

package/dist/doctor-instances.d.ts

@@ -0,0 +1,4 @@
+import type { DoctorCheck } from "./doctor.js";
+import type { ResolvedProject } from "./config.js";
+/** Same-role instances (spec 23.13): what doctor says about them. Reads configuration and paths only. */
+export declare function diagnoseInstances(project: ResolvedProject, blocker: string | undefined, platform?: NodeJS.Platform): DoctorCheck[];

package/dist/doctor-instances.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { DEFAULT_MAX_INSTANCES, instanceCap } from "./instances.js";
+import { NAME_RE, canonicalPath, isInside } from "./paths.js";
+import { osSandboxAvailable } from "./policy.js";
+import { git } from "./worktree.js";
+/** Same-role instances (spec 23.13): what doctor says about them. Reads configuration and paths only. */
+export function diagnoseInstances(project, blocker, platform = process.platform) {
+    const checks = [];
+    const written = project.dispatcher.max_instances;
+    const max = written ?? DEFAULT_MAX_INSTANCES;
+    const add = (level, message) => checks.push({ level, subject: "instances", message });
+    if (written !== undefined && written > 1 && blocker) {
+        add("warn", `dispatcher.max_instances is ${written}, but runs here take turns in the checkout (${blocker}): parallel tasks run one at a time.`);
+    }
+    if (blocker || max <= 1 || project.solo)
+        return checks;
+    const asRun = { ...project, run: { id: "doctor", dir: "", layout: "run" } };
+    const members = Object.keys(project.agents).filter((n) => n !== project.lead);
+    const usable = [];
+    for (const role of members) {
+        if (!NAME_RE.test(role)) {
+            add("info", `"${role}" cannot run as several instances (name is not a valid branch name).`);
+            continue;
+        }
+        const cap = instanceCap(asRun, "worktree", role);
+        if (cap.n < max && cap.reason)
+            add("warn", cap.reason);
+        if (cap.n > 1)
+            usable.push(role);
+    }
+    if (!osSandboxAvailable()) {
+        for (const role of usable) {
+            if (project.agents[role]?.runtime !== "codex")
+                continue;
+            add(written !== undefined ? "warn" : "info", `only "${role}" writes its memory; its other instances are only told not to (Codex without an OS sandbox).`);
+        }
+    }
+    // The shared memory must not contain, or lie inside, a folder an extra instance writes: that is under the run data roots.
+    const roots = [project.paths.taskMemory, project.paths.runs, path.join(project.paths.root, "worktrees")];
+    try {
+        roots.push(git(project.dir, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
+    }
+    catch {
+        /* not readable: the other roots still count */
+    }
+    const ci = platform === "darwin";
+    const norm = (p) => (ci ? canonicalPath(p).toLowerCase() : canonicalPath(p));
+    for (const role of usable) {
+        const a = project.agents[role];
+        for (const s of [a?.memory.global, a?.memory.project]) {
+            if (!s)
+                continue;
+            const cs = norm(s);
+            const contains = roots.find((r) => isInside(cs, norm(r)));
+            const inside = roots.find((r) => isInside(norm(r), cs));
+            if (contains)
+                add("warn", `"${role}" runs one task at a time: its memory ${s} contains ${contains}, where its other instances would write. Move the memory elsewhere to allow parallel tasks.`);
+            else if (inside)
+                add("warn", `the memory of "${role}" (${s}) is inside ${inside}, where instances write; this may prevent extra instances for some runs. Move the memory elsewhere to be sure parallel tasks are possible.`);
+        }
+    }
+    return checks;
+}

package/dist/doctor.d.ts

@@ -44,3 +44,5 @@ export declare function preflightRuntimes(project: ResolvedProject, opts?: Probe
 /** Everything `agent-lyceum doctor` reports. Reads configuration and asks the CLIs for `--version`/`--help`; never runs an agent. */
 export declare function diagnoseProject(project: ResolvedProject, opts?: ProbeOptions): Promise<DoctorReport>;
 export declare function formatDoctor(r: DoctorReport): string;
+/** One-line summary counted from the checks; `info` and `ok` never count. */
+export declare function doctorFooter(r: DoctorReport): string;

package/dist/doctor.js

@@ -7,6 +7,7 @@ import { listRecords, RECORD_KINDS } from "./records.js";
 import { listRunLocks, listUnreadableRunLocks, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
+import { diagnoseInstances } from "./doctor-instances.js";
 import { dirtyPaths, git, isolationBlocker } from "./worktree.js";
 const BINARY = { "claude-code": "claude", codex: "codex" };
 /** Run a read-only CLI query (`--version`, `--help`): bounded in time and output, never an agent task. */
@@ -138,6 +139,8 @@ export async function diagnoseProject(project, opts = {}) {
                 : { level: "ok", subject: "git", message: "git repo with a commit: runs and agents work in their own worktrees." });
         }
     }
+    if (fs.existsSync(project.dir))
+        checks.push(...diagnoseInstances(project, blocker));
     if (fs.existsSync(project.dir) && !blocker) {
         const missing = [];
         if (!findOnPath("gh", opts.env?.PATH ?? process.env.PATH))
@@ -195,6 +198,19 @@ export function formatDoctor(r) {
     for (const c of r.runtimes) {
         lines.push(`  ${c.runtime}: ${c.binary === "missing" ? "not installed" : `${c.version ?? "version unknown"}; json ${c.json}, resume ${c.resume}, sandbox ${c.sandbox}, effort ${c.effort}`}`);
     }
-    lines.push("", r.ok ? "No problems found." : "Problems found.");
+    lines.push("", doctorFooter(r));
     return lines.join("\n");
 }
+/** One-line summary counted from the checks; `info` and `ok` never count. */
+export function doctorFooter(r) {
+    const errors = r.checks.filter((c) => c.level === "error").length;
+    const warns = r.checks.filter((c) => c.level === "warn").length;
+    const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+    if (errors > 0) {
+        const parts = [plural(errors, "error"), ...(warns > 0 ? [plural(warns, "warning")] : [])];
+        return `Problems found: ${parts.join(", ")} (marked ERROR${warns > 0 ? " / warn" : ""} above).`;
+    }
+    if (warns > 0)
+        return `No errors; ${plural(warns, "warning")} to review (marked warn above).`;
+    return "No problems found.";
+}

package/dist/instance-containment.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedProject } from "./config.js";
+import { type MailLayout } from "./run-store.js";
+import { type AgentWorkspace } from "./worktree.js";
+export interface InstanceContainment {
+    /** Why instance `k` of `role` must not exist (it could write the role's shared memory), judged on the paths it will get; undefined when fine. */
+    check: (role: string, k: number) => string | undefined;
+    /** The same judgment with the worktree it actually got (root and git dir). */
+    checkWorkspace: (role: string, k: number, ws: Pick<AgentWorkspace, "root" | "gitDir">) => string | undefined;
+}
+/**
+ * D-17 as one object per run: reads the file system only through `canonicalPath` (lstat/realpath), writes nothing. The shared memory of a role
+ * is its `memory.global`/`memory.project`; an instance k >= 2 may write its task memory, outbox, worktree and git dir, none of which may
+ * contain or lie inside the shared memory (the OS sandbox and the Codex writable roots are built from the same paths).
+ */
+export declare function instanceContainment(base: ResolvedProject, runDir: string, layout: MailLayout, platform?: NodeJS.Platform): InstanceContainment;

package/dist/instance-containment.js

@@ -0,0 +1,36 @@
+import { containmentConflict, slotName, slotWritableRoots } from "./instances.js";
+import { canonicalPath } from "./paths.js";
+import { writePolicy } from "./policy.js";
+import { bindRunProject } from "./run-store.js";
+import { recordedGitDir, workspaceRoot } from "./worktree.js";
+/**
+ * D-17 as one object per run: reads the file system only through `canonicalPath` (lstat/realpath), writes nothing. The shared memory of a role
+ * is its `memory.global`/`memory.project`; an instance k >= 2 may write its task memory, outbox, worktree and git dir, none of which may
+ * contain or lie inside the shared memory (the OS sandbox and the Codex writable roots are built from the same paths).
+ */
+export function instanceContainment(base, runDir, layout, platform = process.platform) {
+    const runId = runDir.split(/[\\/]/).filter(Boolean).pop() ?? "";
+    const judge = (role, k, work) => {
+        const agent = base.agents[role];
+        const shared = [agent?.memory.global, agent?.memory.project].filter((x) => !!x);
+        if (!shared.length || k < 2)
+            return undefined;
+        const slots = Array.from({ length: k }, (_, i) => slotName(role, i + 1));
+        const bound = bindRunProject(base, runDir, layout, { roles: { [role]: slots } });
+        const inst = bound.agents[slotName(role, k)];
+        if (!inst)
+            return undefined;
+        const roots = slotWritableRoots(writePolicy(bound, inst), work);
+        const c = containmentConflict(shared, roots, canonicalPath, platform === "darwin");
+        return c ? `could write the shared memory ${c.shared} of "${role}": its writable path ${c.root} contains it or lies inside it` : undefined;
+    };
+    return {
+        check: (role, k) => {
+            // An instance that already has a worktree is judged on the git dir recorded for it (read-only), not only on the predicted root.
+            const slot = slotName(role, k);
+            const gitDir = recordedGitDir(base, runId, slot);
+            return judge(role, k, [workspaceRoot(base, runId, slot), ...(gitDir ? [gitDir] : [])]);
+        },
+        checkWorkspace: (role, k, ws) => judge(role, k, [ws.root, ws.gitDir]),
+    };
+}

package/dist/instances.d.ts

@@ -0,0 +1,183 @@
+import type { ResolvedAgent, ResolvedProject } from "./config.js";
+import type { WorkspaceMode } from "./worktree.js";
+/** Instances one role may have at the same time when `dispatcher.max_instances` is not written. */
+export declare const DEFAULT_MAX_INSTANCES = 4;
+/** Instance 1 is the role itself; the others are `<role>--<k>`. */
+export declare const slotName: (role: string, k: number) => string;
+/** `<role>--<k>` with k >= 2 (no leading zero) → its parts. A name like `fe--x` is just an agent, never an instance. */
+export declare function parseSlotName(name: string): {
+    role: string;
+    k: number;
+} | undefined;
+export interface InstanceCap {
+    /** How many instances the role may have at once (1 = no parallel). */
+    n: number;
+    /** Why `n` is 1 (or lower than configured); set whenever the limit is not simply the configured one. */
+    reason?: string;
+}
+type CapProject = Pick<ResolvedProject, "lead" | "solo" | "run" | "dispatcher"> & {
+    agents: Record<string, unknown>;
+};
+/**
+ * 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 declare function instanceCap(project: CapProject, mode: WorkspaceMode, role: string, check?: (role: string, k: number) => string | undefined, opened?: readonly string[]): InstanceCap;
+export type ParallelFlag = "absent" | "invalid" | "on" | {
+    ignored: string;
+};
+/**
+ * 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 declare function parallelFlag(input: {
+    value: unknown;
+    senderIsLead: boolean;
+    type: string;
+    replyTo?: unknown;
+    thread?: unknown;
+    cap: InstanceCap;
+}): ParallelFlag;
+/** What the route journal holds about one message id; every field is written by the dispatcher, never read from mail text. */
+export interface OwnerRecord {
+    /** Slot the assigner placed it in. */
+    assign?: string;
+    /** Instance that sent it. */
+    from?: string;
+    /** Instance a dispatcher notice is about. */
+    about?: string;
+    /** Its delivery (intent) line: order in the journal, recipient, inbox file name, route source key. */
+    intent?: {
+        seq: number;
+        to: string;
+        file: string;
+        source: string;
+        msg_id: string;
+    };
+}
+export interface OwnersCtx {
+    /** `state.instances.roles[role]`: the role's open instances, `[0]` is the role itself. */
+    opened: readonly string[];
+    rec: (id: string) => OwnerRecord | undefined;
+    /** Journal position of the role's first held intent (its activation); undefined while it is not in the journal yet. */
+    mark: number | undefined;
+    /** `agent` of `mail/claims/<id>.json`; undefined when there is no readable claim. */
+    claimAgent: (claimId: string) => string | undefined;
+}
+/**
+ * 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 declare function ownersOf(id: string, role: string, ctx: OwnersCtx): string | undefined;
+/**
+ * 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 declare function involves(intent: {
+    to: string;
+    file: string;
+    source: string;
+    msg_id: string;
+}, role: string, claimAgent: (claimId: string) => string | undefined): boolean;
+/** A message waiting in `mail/inbox/<role>/pending/`, as the journal describes it. */
+export interface HeldMsg {
+    file: string;
+    id: string;
+    /** The recipient name on the mail: the role or one of its instances. */
+    to: string;
+    replyTo?: string;
+    thread?: string;
+    /** The journal says the lead marked it `parallel: true`. */
+    parallel: boolean;
+}
+export type Acceptance = true | "blocked" | "refused" | "cap";
+export interface PlanInput {
+    role: string;
+    /** Waiting mail in delivery (file name) order. */
+    held: readonly HeldMsg[];
+    /** The role's open instances, `[0]` is the role itself. */
+    opened: readonly string[];
+    /** Effective instance limit. */
+    cap: number;
+    /** `ownersOf(id, role)` with everything but the id bound. */
+    owners: (id: string) => string | undefined;
+    /** The slot the journal already recorded for a message. */
+    recorded: (id: string) => string | undefined;
+    /** Whether a slot may take a new thread (not refused, not blocked, within the cap). */
+    acceptsNew: (slot: string) => Acceptance;
+    /** The slot's inbox has unread mail. */
+    busy: (slot: string) => boolean;
+    /** The role's primary model is cooling down after a rate limit. */
+    coolingDown: boolean;
+    /** Whether a new instance of that name may be opened. */
+    mayOpen: (name: string) => true | "collision" | "containment";
+}
+export interface Assignment {
+    file: string;
+    slot: string;
+    rule: "recorded" | "affinity" | "addressed" | "parallel" | "default";
+    /** Set when the slot has to be opened first. */
+    open?: string;
+    /** Set when an affinity placed a message addressed to another instance. */
+    addressed?: string;
+}
+export interface Plan {
+    assign: Assignment[];
+    waiting: {
+        file: string;
+        reason: string;
+    }[];
+}
+/**
+ * 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 declare function planAssignments(input: PlanInput): Plan;
+/** A run's slot table: `roles[<role>]` lists the role's open instances, `[0]` is the role itself. */
+export interface SlotTable {
+    roles: Record<string, string[]>;
+}
+/**
+ * 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 declare function synthesizeSlots(agents: Record<string, ResolvedAgent>, table: SlotTable, taskMemory: (slot: string) => string): Record<string, ResolvedAgent>;
+/** The role an agent name stands for: the role itself, or the role of a bound instance. */
+export declare const roleOfName: (agents: Record<string, {
+    instance?: {
+        role: string;
+    };
+} | undefined>, name: string) => string;
+/** 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 declare function senderLabel(name: string, agents: Record<string, {
+    instance?: {
+        role: string;
+        k: number;
+    };
+} | undefined>): string;
+/** Key of the one failure sent to the lead about this set of waiting mails (spec D-16). */
+export declare const heldStallKey: (ids: readonly string[]) => string;
+/**
+ * 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 declare function assertInstancesResumable(base: {
+    lead: string;
+    agents: Record<string, unknown>;
+}, table: SlotTable, runId: string, projectName: string, check?: (role: string, k: number) => string | undefined): void;
+/** Every directory an instance can write: what its policy allows, the folders of the files it may edit, and its working directory. */
+export declare const slotWritableRoots: (pol: {
+    allowDirs: readonly string[];
+    allowFiles: readonly string[];
+}, work: readonly string[]) => string[];
+/**
+ * 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 declare function containmentConflict(shared: readonly string[], roots: readonly string[], canon: (p: string) => string, caseInsensitive: boolean): {
+    shared: string;
+    root: string;
+} | undefined;
+export {};