agent-lyceum 0.25.1 → 0.27.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
 
@@ -75,6 +75,10 @@ agents:
 
 Folder layout, every agent field and the rules `doctor` checks: [Configuration](docs/configuration.md).
 
+## Downgrading
+
+Older versions refuse a `team.yaml` or `project.yaml` that contains `model_tiers` (a load error, "Unrecognized key"). Before using an older binary, remove `model_tiers` from every `project.yaml` and from `team.yaml`. Other mail and run state are unaffected: older versions ignore a `tier` line in mail. See [Model tiers](docs/configuration.md#model-tiers). (Spec 24.3.2, 24.13)
+
 ## Topics
 
 | Topic | Read |
@@ -82,6 +86,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)。
 
 ## 指令
 
@@ -75,6 +75,10 @@ agents:
 
 資料夾結構、所有 agent 欄位與 `doctor` 檢查的規則：[設定](docs/configuration.zh-TW.md)。
 
+## 降級（改用舊版）
+
+舊版程式會拒絕載入含 `model_tiers` 的 `team.yaml` 或 `project.yaml`（載入錯誤，「Unrecognized key」）。改用舊版前，請先從每個 `project.yaml` 與 `team.yaml` 拿掉 `model_tiers`。其他信件與 run 狀態不受影響：舊版會忽略信件中的 `tier` 行。見[模型分級](docs/configuration.zh-TW.md#模型分級)。（spec 24.3.2、24.13）
+
 ## 主題
 
 | 主題 | 閱讀 |
@@ -82,6 +86,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/call.js

@@ -55,6 +55,8 @@ export function callProject(home, agent, dir, callDir) {
         lead: agent.name,
         dispatcher: DISPATCHER_DEFAULTS,
         agents: { [agent.name]: agent },
+        modelTiers: {},
+        modelTiersFrom: {},
         paths,
         solo: "call",
     };

package/dist/config.d.ts

@@ -33,6 +33,18 @@ export interface ResolvedAgent {
     }[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
+    /** Spec 24: the tiers this agent can run on (its runtime's ladder up to and including `model`); unset when nothing is below `model`. */
+    tiers?: string[];
+    /** 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;
@@ -42,6 +54,10 @@ export interface ResolvedProject {
     lead: string;
     dispatcher: DispatcherSettings;
     agents: Record<string, ResolvedAgent>;
+    /** Spec 24: non-empty model ladders per runtime, lowest first (project.yaml replaces team.yaml's per runtime). */
+    modelTiers: Partial<Record<Runtime, string[]>>;
+    /** Which file each ladder in `modelTiers` came from. */
+    modelTiersFrom: Partial<Record<Runtime, "global" | "project">>;
     paths: ProjectPaths;
     /** Removed settings still present in config files (ignored); `validate` warns once per file. */
     ignoredSettings?: {
@@ -52,7 +68,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>;
@@ -60,6 +79,10 @@ export interface ResolvedProject {
     solo?: "run" | "call";
 }
 export declare function loadGlobal(home: string): {
+    model_tiers?: {
+        "claude-code"?: string[] | undefined;
+        codex?: string[] | undefined;
+    } | undefined;
     agents: Record<string, {
         runtime?: "claude-code" | "codex" | undefined;
         model?: string | undefined;
@@ -87,6 +110,10 @@ export declare function loadProjectRaw(home: string, name: string): {
     team: {
         lead: string;
     };
+    model_tiers?: {
+        "claude-code"?: string[] | undefined;
+        codex?: string[] | undefined;
+    } | undefined;
     dispatcher: {
         max_rounds?: number | undefined;
         max_parallel?: unknown;
@@ -102,6 +129,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

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
-import { absPath, homePaths, projectPaths, } from "./paths.js";
-import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, } from "./schema.js";
+import { absPath, escapesParent, homePaths, projectPaths, } from "./paths.js";
+import { availableTiers } from "./tiers.js";
+import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, RUNTIMES, } from "./schema.js";
 export class ConfigError extends Error {
 }
 function readYaml(file, schema, label) {
@@ -60,6 +61,16 @@ export function resolveProjectFrom(home, name, g, p) {
     const lead = p.team.lead;
     const { max_parallel: _mp, max_concurrent_runs: _mc, workspace_mode: _wm, fallback: dispatcherFallback, ...liveDispatcher } = p.dispatcher;
     const dispatcher = { ...DISPATCHER_DEFAULTS, ...stripUndef(liveDispatcher) };
+    const modelTiers = {};
+    const modelTiersFrom = {};
+    for (const rt of RUNTIMES) {
+        const fromProject = p.model_tiers?.[rt] !== undefined;
+        const ladder = fromProject ? p.model_tiers?.[rt] : g.model_tiers?.[rt];
+        if (ladder?.length) {
+            modelTiers[rt] = [...ladder];
+            modelTiersFrom[rt] = fromProject ? "project" : "global";
+        }
+    }
     const agents = {};
     for (const agentName of Object.keys(p.agents)) {
         const gl = resolveLayer(g.agents[agentName], home);
@@ -144,6 +155,7 @@ export function resolveProjectFrom(home, name, g, p) {
             }
         }
         const { entries: fallback, invalid: fallbackInvalid } = resolveFallback(rawFallback, runtime);
+        const tiers = runtime ? availableTiers(modelTiers[runtime], model) : undefined;
         const isLead = agentName === lead;
         const resume = pick("resume");
         const canMessage = pick("can_message");
@@ -175,6 +187,7 @@ export function resolveProjectFrom(home, name, g, p) {
             fallbackShared,
             fallbackInvalid,
             sources,
+            ...(tiers ? { tiers } : {}),
         };
     }
     return {
@@ -184,6 +197,8 @@ export function resolveProjectFrom(home, name, g, p) {
         lead,
         dispatcher,
         agents,
+        modelTiers,
+        modelTiersFrom,
         paths,
         ignoredSettings: collectIgnored(hp.globalConfig, g, paths.config, p),
     };
@@ -252,7 +267,7 @@ export function findProjectForCwd(home, cwd) {
     let best;
     for (const pr of listProjects(home)) {
         const rel = path.relative(pr.dir, cwd);
-        if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel))) {
+        if (!escapesParent(rel)) {
             if (!best || pr.dir.length > best.len)
                 best = { name: pr.name, len: pr.dir.length };
         }
@@ -276,6 +291,13 @@ 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 rt of RUNTIMES) {
+        const from = project.modelTiersFrom[rt];
+        if (from)
+            sources[`model_tiers.${rt}`] = { file: from === "project" ? projectFile : globalFile, key: `model_tiers.${rt}` };
+    }
     for (const a of Object.values(project.agents)) {
         const at = (src, field) => {
             const key = `agents.${a.name}.${field}`;
@@ -305,6 +327,10 @@ export function resolveProjectWithSources(home, name) {
             else
                 sources[`agents.${a.name}.${f}`] = at(src, f);
         }
+        // The ladder is the runtime's, so its source is the ladder's own key (spec 24.9).
+        const ladderSrc = a.tiers ? sources[`model_tiers.${a.runtime}`] : undefined;
+        if (ladderSrc)
+            sources[`agents.${a.name}.model_tiers`] = ladderSrc;
     }
     return { project, sources };
 }
@@ -312,6 +338,9 @@ export function resolveProjectWithSources(home, name) {
 export function flattenResolved(project) {
     const v = { dir: project.dir, "team.lead": project.lead };
     const anyFallback = Object.values(project.agents).some((a) => a.fallback.length > 0);
+    for (const rt of RUNTIMES)
+        if (project.modelTiers[rt])
+            v[`model_tiers.${rt}`] = project.modelTiers[rt];
     for (const [k, val] of Object.entries(project.dispatcher)) {
         if (k === "fallback_cooldown_sec" && !anyFallback)
             continue; // keep `doctor --resolved` unchanged without fallback
@@ -332,6 +361,8 @@ export function flattenResolved(project) {
         v[`${p}.allow_web`] = a.allowWeb;
         if (a.fallback.length)
             v[`${p}.fallback`] = a.fallback;
+        if (a.tiers)
+            v[`${p}.model_tiers`] = a.tiers;
     }
     return v;
 }

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

@@ -0,0 +1,9 @@
+/** How many distinct sent-again mails of one repeat are announced to the sender before further repeats are set aside silently. */
+export declare const MAX_DUPLICATE_NOTICES = 2;
+/** Key of one sender's repeat of earlier mail; JSON keeps it unambiguous whatever the names contain. */
+export declare function duplicateNoticeKey(sender: string, repeats: Iterable<[string, string]>): string;
+/**
+ * Decide whether the repeat found in outbox mail `source` is announced. Idempotent per source: the notified source ids
+ * are stored, so a replay after a crash neither counts twice nor loses a notice it already earned.
+ */
+export declare function shouldNotifyDuplicate(runDir: string, key: string, source: string): boolean;

package/dist/duplicate-notices.js

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+/** How many distinct sent-again mails of one repeat are announced to the sender before further repeats are set aside silently. */
+export const MAX_DUPLICATE_NOTICES = 2;
+const FILE = "duplicate-notices.json";
+/** Key of one sender's repeat of earlier mail; JSON keeps it unambiguous whatever the names contain. */
+export function duplicateNoticeKey(sender, repeats) {
+    return JSON.stringify([sender, [...repeats].map(([to, id]) => [to, id]).sort()]);
+}
+function load(runDir) {
+    try {
+        const data = JSON.parse(fs.readFileSync(path.join(runDir, FILE), "utf8"));
+        return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Decide whether the repeat found in outbox mail `source` is announced. Idempotent per source: the notified source ids
+ * are stored, so a replay after a crash neither counts twice nor loses a notice it already earned.
+ */
+export function shouldNotifyDuplicate(runDir, key, source) {
+    const all = load(runDir);
+    const seen = Array.isArray(all[key]) ? all[key] : [];
+    if (seen.includes(source))
+        return true;
+    if (seen.length >= MAX_DUPLICATE_NOTICES)
+        return false;
+    all[key] = [...seen, source];
+    atomicWrite(path.join(runDir, FILE), `${JSON.stringify(all, null, 2)}\n`);
+    return true;
+}

package/dist/fallback.d.ts

@@ -7,6 +7,8 @@ export interface Candidate {
     model?: string;
     effort?: Effort;
     primary: boolean;
+    /** The cheaper model a lead's `tier` picked (spec 24.7): not the primary, and not a fallback either. */
+    tiered?: true;
     /** `<runtime>/<model>`; the cooldown and session key. */
     key: string;
 }
@@ -14,7 +16,7 @@ export interface Candidate {
  * The primary model followed by the agent's fallback chain, in order. An entry with the same key as the primary or as an
  * earlier entry is dropped: a chain shared through `dispatcher.fallback` may list the agent's own primary (spec 20.12).
  */
-export declare function candidatesFor(agent: ResolvedAgent): Candidate[];
+export declare function candidatesFor(agent: ResolvedAgent, tierModel?: string): Candidate[];
 /**
  * The agent as it runs on candidate `c`: itself for the primary; for a backup, the same agent on the backup's runtime, model
  * and effort, at the primary's effective web level (spec 20.12). A set `allow_web` carries over. Unset, claude-code has no web
@@ -39,7 +41,7 @@ export declare class Cooldowns {
     }>): Cooldowns;
 }
 /** The candidates for one wake: the chain minus those cooling down, or the whole chain when every one is (something must be tried). */
-export declare function planAttempts(agent: ResolvedAgent, cooldowns: Cooldowns, now: number): Candidate[];
+export declare function planAttempts(all: readonly Candidate[], cooldowns: Cooldowns, now: number): Candidate[];
 export type Step = "retry-same" | "next-candidate" | "stop";
 /**
  * What to do after a failed call (spec 20.2 decisions 2 and 5). `attemptsOnCurrent` counts the calls made on the current

package/dist/fallback.js

@@ -4,12 +4,18 @@ const keyOf = (runtime, model) => `${runtime}/${(model ?? "").trim().toLowerCase
  * The primary model followed by the agent's fallback chain, in order. An entry with the same key as the primary or as an
  * earlier entry is dropped: a chain shared through `dispatcher.fallback` may list the agent's own primary (spec 20.12).
  */
-export function candidatesFor(agent) {
+export function candidatesFor(agent, tierModel) {
     // `validate` refuses an agent without a runtime before anything is woken.
     const runtime = agent.runtime;
     const primary = { runtime, model: agent.model, effort: agent.effort, primary: true, key: keyOf(runtime, agent.model) };
     const out = [primary];
     const seen = new Set([primary.key]);
+    // A tier's cheaper model goes first (spec 24.7.1); one that is the ceiling itself adds nothing.
+    if (tierModel && keyOf(runtime, tierModel) !== primary.key) {
+        const key = keyOf(runtime, tierModel);
+        out.unshift({ runtime, model: tierModel, effort: agent.effort, primary: false, tiered: true, key });
+        seen.add(key);
+    }
     for (const f of agent.fallback) {
         const model = f.model || undefined;
         const key = keyOf(f.runtime, model);
@@ -28,6 +34,8 @@ export function candidatesFor(agent) {
 export function agentForCandidate(agent, c) {
     if (c.primary)
         return agent;
+    if (c.tiered)
+        return { ...agent, model: c.model };
     const allowWeb = agent.allowWeb ?? (agent.runtime === "claude-code" && c.runtime === "codex" ? "none" : undefined);
     return { ...agent, runtime: c.runtime, model: c.model, effort: c.effort, allowWeb };
 }
@@ -63,10 +71,9 @@ export class Cooldowns {
     }
 }
 /** The candidates for one wake: the chain minus those cooling down, or the whole chain when every one is (something must be tried). */
-export function planAttempts(agent, cooldowns, now) {
-    const all = candidatesFor(agent);
+export function planAttempts(all, cooldowns, now) {
     const warm = all.filter((c) => cooldowns.active(c.key, now) === 0);
-    return warm.length ? warm : all;
+    return warm.length ? warm : [...all];
 }
 /**
  * What to do after a failed call (spec 20.2 decisions 2 and 5). `attemptsOnCurrent` counts the calls made on the current

package/dist/guard.d.ts

@@ -9,6 +9,12 @@ export interface Violation {
     /** The kept copy is cut to MAX_KEEP_BYTES. */
     truncated?: boolean;
 }
+/** A change to a cross-run shared file that no agent of the batch may make, while another run of the project was live. */
+export interface Unattributed {
+    file: string;
+    agents: string[];
+    otherRuns: string[];
+}
 export declare const MAX_KEEP_BYTES: number;
 /**
  * Detects (and reverts) changes to protected files made by agents that may not edit them.
@@ -16,10 +22,20 @@ export declare const MAX_KEEP_BYTES: number;
  */
 export declare class ProtectedGuard {
     private project;
+    private otherLiveRuns;
     private baseline;
     /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
     private records;
-    constructor(project: ResolvedProject);
+    /** Changes kept (not reverted) because another live run may have made them; see `takeUnattributed`. */
+    private unattributed;
+    /** Other runs that were live at the last `rebase()` (or at `check()` time); computed once per batch. */
+    private liveAtBase;
+    /** `otherLiveRuns`: ids of the project's other runs that have a live lock holder right now. */
+    constructor(project: ResolvedProject, otherLiveRuns?: () => string[]);
+    /** The unattributed changes since the last call (they were kept and adopted as the baseline). */
+    takeUnattributed(): Unattributed[];
+    /** Files shared by every run of the project: only these can be changed by another run's lead. */
+    private crossRunShared;
     /**
      * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
      * judged: edits made in between (you, or another run of the project) are not the batch's doing.

package/dist/guard.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { readRegularFileNoFollow } from "./fs-util.js";
+import { escapesParent } from "./paths.js";
 import { mayEditProtected, recordsDir, repoInstructionFiles, sharedContextFiles, sharedIndex } from "./policy.js";
 export const MAX_KEEP_BYTES = 1024 * 1024;
 function safeName(file) {
@@ -13,18 +14,38 @@ function safeName(file) {
  */
 export class ProtectedGuard {
     project;
+    otherLiveRuns;
     baseline = new Map();
     /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
     records = new Map();
-    constructor(project) {
+    /** Changes kept (not reverted) because another live run may have made them; see `takeUnattributed`. */
+    unattributed = [];
+    /** Other runs that were live at the last `rebase()` (or at `check()` time); computed once per batch. */
+    liveAtBase = [];
+    /** `otherLiveRuns`: ids of the project's other runs that have a live lock holder right now. */
+    constructor(project, otherLiveRuns = () => []) {
         this.project = project;
+        this.otherLiveRuns = otherLiveRuns;
         this.rebase();
     }
+    /** The unattributed changes since the last call (they were kept and adopted as the baseline). */
+    takeUnattributed() {
+        const out = this.unattributed;
+        this.unattributed = [];
+        return out;
+    }
+    /** Files shared by every run of the project: only these can be changed by another run's lead. */
+    crossRunShared(file) {
+        if (sharedContextFiles(this.project).includes(file))
+            return true;
+        return Object.values(this.project.agents).some((a) => a.agentMd === file);
+    }
     /**
      * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
      * judged: edits made in between (you, or another run of the project) are not the batch's doing.
      */
     rebase() {
+        this.liveAtBase = this.otherLiveRuns();
         for (const f of ProtectedGuard.protectedFiles(this.project))
             this.baseline.set(f, read(f));
         this.records = readTree(recordsDir(this.project));
@@ -69,6 +90,7 @@ export class ProtectedGuard {
     /** Compare against the baseline after `running` agents finished; revert unauthorized changes. */
     check(running) {
         const violations = [];
+        const other = [...new Set([...this.liveAtBase, ...this.otherLiveRuns()])];
         for (const [file, before] of this.baseline) {
             const now = read(file);
             if (same(before, now))
@@ -78,6 +100,11 @@ export class ProtectedGuard {
                 this.baseline.set(file, now);
                 continue;
             }
+            if (other.length && this.crossRunShared(file)) {
+                this.baseline.set(file, now);
+                this.unattributed.push({ file, agents: running.map((a) => a.name), otherRuns: other });
+                continue;
+            }
             if (before === null) {
                 const kept = this.keep(file, now);
                 fs.rmSync(file, { force: true });
@@ -90,10 +117,10 @@ export class ProtectedGuard {
                 violations.push({ file, action: "restored", suspects: running.map((a) => a.name), ...kept });
             }
         }
-        this.checkRecords(running, violations);
+        this.checkRecords(running, violations, other);
         return violations;
     }
-    checkRecords(running, violations) {
+    checkRecords(running, violations, other) {
         const root = recordsDir(this.project);
         // Never write through a symlinked parent of the records tree: skip its protection for this batch.
         if (isLink(path.dirname(root)) || isLink(path.dirname(path.dirname(root))))
@@ -109,6 +136,10 @@ export class ProtectedGuard {
                 continue;
             if (lead)
                 continue;
+            if (other.length) {
+                this.unattributed.push({ file, agents: suspects, otherRuns: other });
+                continue;
+            }
             const kept = this.keep(file, cur);
             if (before === null) {
                 if (!insideRoot(root, path.dirname(file)))
@@ -124,7 +155,7 @@ export class ProtectedGuard {
                 violations.push({ file, action: "restored", suspects, ...kept });
             }
         }
-        if (lead)
+        if (lead || other.length)
             this.records = now;
     }
     /**
@@ -133,7 +164,7 @@ export class ProtectedGuard {
      */
     realDirs(root, dir, done, suspects, violations) {
         const rel = path.relative(root, dir);
-        if (rel.startsWith("..") || path.isAbsolute(rel))
+        if (escapesParent(rel))
             return false;
         let cur = root;
         for (const part of ["", ...(rel ? rel.split(path.sep) : [])]) {
@@ -167,7 +198,7 @@ function isLink(p) {
 function insideRoot(root, dir) {
     try {
         const r = path.relative(fs.realpathSync(root), fs.realpathSync(dir));
-        return !r.startsWith("..") && !path.isAbsolute(r);
+        return !escapesParent(r);
     }
     catch {
         return false;

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;