agent-lyceum 0.26.0 → 0.27.0

package/README.md

@@ -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 |

package/README.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）
+
 ## 主題
 
 | 主題 | 閱讀 |

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,8 @@ 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;
@@ -52,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?: {
@@ -73,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;
@@ -100,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;

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 };
         }
@@ -278,6 +293,11 @@ export function resolveProjectWithSources(home, name) {
     }
     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}`;
@@ -307,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 };
 }
@@ -314,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
@@ -334,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/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/mailbox.d.ts

@@ -2,6 +2,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 type { Tier } from "./schema.js";
 import { RouteJournal } from "./message-store.js";
 export { atomicWrite };
 export declare const MESSAGE_TYPES: readonly ["task", "reply", "failure", "done", "ask"];
@@ -17,6 +18,8 @@ export interface MessageMeta {
     created: string;
     /** The run this mail belongs to. Stamped by the dispatcher; absent on mail of legacy runs. */
     run_id?: string;
+    /** The lead-chosen difficulty tier, validated by the dispatcher at delivery (spec 24.5.3). Absent = the ceiling. */
+    tier?: Tier;
 }
 export interface Message {
     meta: MessageMeta;
@@ -40,6 +43,8 @@ export interface DeliverInput {
     body: string;
     thread?: string;
     reply_to?: string;
+    /** Written to the mail only when set (spec 24.5.3), so mail without it is unchanged. */
+    tier?: Tier;
 }
 /** Deliver a message into `to`'s inbox (dispatcher-side; senders other than agents allowed). */
 export declare function deliver(project: ResolvedProject, input: DeliverInput & {
@@ -112,6 +117,15 @@ export interface RouteResult {
     }[];
     /** Latest `## Steps` checklist the lead sent, if any. */
     steps?: Step[];
+    /** `tier` fields delivered without effect (spec 24.5.2); the caller logs `tier_ignored` and sends the notes. */
+    tierIgnored: {
+        from: string;
+        id: string;
+        to: string;
+        subject: string;
+        type: string;
+        reason: "not-lead" | "not-a-task" | "no-tiers";
+    }[];
 }
 /** Move a handled `done` file out of the outbox (to `read/`). */
 export declare function finishDone(file: string): void;

package/dist/mailbox.js

@@ -2,10 +2,12 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
+import { duplicateNoticeKey, shouldNotifyDuplicate } from "./duplicate-notices.js";
 import { formatWarning, missingSections, parseSteps } from "./format.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 { effectiveTier, tierFlag } from "./tiers.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";
@@ -64,6 +66,7 @@ export function deliver(project, input) {
         subject: input.subject,
         created: input.created ?? new Date().toISOString(),
         ...(project.run?.layout === "run" ? { run_id: project.run.id } : {}),
+        ...(input.tier ? { tier: input.tier } : {}),
     };
     const file = path.join(inboxDir(project, input.to), input.fileName ?? `${stamp()}-${input.from}-${id}.md`);
     atomicWrite(file, serialize(meta, input.body));
@@ -123,6 +126,7 @@ function deliveredMeta(project, input, planned) {
         subject: input.subject,
         created: planned.created,
         ...(project.run?.layout === "run" ? { run_id: project.run.id } : {}),
+        ...(input.tier ? { tier: input.tier } : {}),
     };
 }
 export function readMessage(file) {
@@ -199,7 +203,7 @@ 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, held = false) {
+function earlierDuplicate(project, from, to, type, replyTo, body, held = false, tier = "high") {
     const text = sameText(body);
     if (text.length < 20)
         return undefined;
@@ -215,7 +219,7 @@ function earlierDuplicate(project, from, to, type, replyTo, body, held = false)
                 continue;
             try {
                 const m = readMessage(path.join(d, e.name));
-                if (m.meta.from === from && m.meta.type === type && (m.meta.reply_to ?? "") === (replyTo ?? "") && sameText(m.body) === text)
+                if (m.meta.from === from && m.meta.type === type && (m.meta.reply_to ?? "") === (replyTo ?? "") && sameText(m.body) === text && effectiveTier(m.meta) === tier)
                     return m;
             }
             catch {
@@ -227,7 +231,7 @@ function earlierDuplicate(project, from, to, type, replyTo, body, held = false)
 }
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
 export function routeOutboxes(project, routing) {
-    const res = { delivered: [], rejected: [], warnings: [], asks: [] };
+    const res = { delivered: [], rejected: [], warnings: [], asks: [], tierIgnored: [] };
     const journal = project.run ? new RouteJournal(project.run.dir) : undefined;
     for (const sender of Object.values(project.agents)) {
         const dir = outboxDir(project, sender.name);
@@ -240,14 +244,15 @@ export function routeOutboxes(project, routing) {
             .sort((a, b) => fs.statSync(a).mtimeMs - fs.statSync(b).mtimeMs || a.localeCompare(b));
         for (const file of files) {
             const source = sourceIdOf(sender.name, file);
-            const reject = (reason) => {
-                deliverOnce(project, journal, `reject:${source}`, {
-                    from: "dispatcher",
-                    to: sender.name,
-                    type: "failure",
-                    subject: `Message ${path.basename(file)} was rejected`,
-                    body: `Your outbox message \`${path.basename(file)}\` was not delivered: ${reason}\n\nIt was moved to \`rejected/\`.`,
-                });
+            const reject = (reason, notify = true) => {
+                if (notify)
+                    deliverOnce(project, journal, `reject:${source}`, {
+                        from: "dispatcher",
+                        to: sender.name,
+                        type: "failure",
+                        subject: `Message ${path.basename(file)} was rejected`,
+                        body: `Your outbox message \`${path.basename(file)}\` was not delivered: ${reason}\n\nIt was moved to \`rejected/\`.`,
+                    });
                 const dest = path.join(dir, "rejected", path.basename(file));
                 fs.mkdirSync(path.dirname(dest), { recursive: true });
                 fs.renameSync(file, dest);
@@ -332,6 +337,18 @@ export function routeOutboxes(project, routing) {
                     continue;
                 }
             }
+            // `tier` is judged per recipient like `parallel`, before the duplicate check, which needs the effective tier (spec 24.5.2, 24.5.4).
+            const tiers = new Map();
+            for (const t of targets)
+                tiers.set(t, tierFlag({ value: d.tier, senderIsLead: sender.name === project.lead, type, recipientTiers: project.agents[t]?.tiers }));
+            if ([...tiers.values()].includes("invalid")) {
+                reject(`tier must be low, mid or high, not ${JSON.stringify(d.tier)}. Write \`tier: low\` (or mid/high) on a task to run it on a cheaper model, or leave the line out to use the member's own model.`);
+                continue;
+            }
+            const tierOf = (to) => {
+                const f = tiers.get(to);
+                return f === "low" || f === "mid" || f === "high" ? f : undefined;
+            };
             const missing = missingSections(type, parsed.body);
             if (missing.length && project.run?.layout === "run") {
                 const key = formatRejectionKey(sender.name, type, subject);
@@ -348,7 +365,7 @@ export function routeOutboxes(project, routing) {
             for (const to of targets) {
                 if (journal?.get(source, to))
                     continue;
-                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body, !!routing?.held(roleOf(to)));
+                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body, !!routing?.held(roleOf(to)), tierOf(to) ?? "high");
                 if (earlier)
                     repeats.set(to, earlier);
             }
@@ -356,18 +373,25 @@ export function routeOutboxes(project, routing) {
                 .map(([to, m]) => `to "${to}" it repeats mail ${m.meta.id} ("${m.meta.subject}", ${m.meta.created}) with the same content`)
                 .join("; ");
             const REPEAT_HELP = "Do not send it again: if that mail has not been answered yet, wait for the reply; if you need something different, change what you ask for; if the work is finished, the lead sends `done`.";
+            // A failure mail wakes the sender; an agent that answers with the same text again would be woken forever, so after
+            // MAX_DUPLICATE_NOTICES notices for the same repeated mail the repeat is still set aside and logged, but not announced.
+            // Bound to a run directory (either layout); a project-only mailbox has no place to count and stays unbounded.
+            const notifyRepeat = !repeats.size ||
+                !project.run ||
+                shouldNotifyDuplicate(project.run.dir, duplicateNoticeKey(sender.name, [...repeats].map(([to, m]) => [to, m.meta.id])), source);
             if (repeats.size === targets.length) {
-                reject(`it is a duplicate: ${repeatNote()}, so it was not sent again. ${REPEAT_HELP}`);
+                reject(`it is a duplicate: ${repeatNote()}, so it was not sent again. ${REPEAT_HELP}`, notifyRepeat);
                 continue;
             }
             if (repeats.size) {
-                deliverOnce(project, journal, `dup:${source}`, {
-                    from: "dispatcher",
-                    to: sender.name,
-                    type: "failure",
-                    subject: `Part of ${path.basename(file)} was not sent`,
-                    body: `Your outbox message \`${path.basename(file)}\` was delivered, except that ${repeatNote()}. ${REPEAT_HELP}`,
-                });
+                if (notifyRepeat)
+                    deliverOnce(project, journal, `dup:${source}`, {
+                        from: "dispatcher",
+                        to: sender.name,
+                        type: "failure",
+                        subject: `Part of ${path.basename(file)} was not sent`,
+                        body: `Your outbox message \`${path.basename(file)}\` was delivered, except that ${repeatNote()}. ${REPEAT_HELP}`,
+                    });
                 res.rejected.push({ from: sender.name, file, reason: `duplicate: ${repeatNote()}` });
             }
             const body = missing.length ? `${formatWarning(type, missing)}\n\n${parsed.body}` : parsed.body;
@@ -381,13 +405,16 @@ export function routeOutboxes(project, routing) {
                     continue;
                 const flag = flags.get(to);
                 const role = roleOf(to);
+                const tf = tiers.get(to);
+                if (typeof tf === "object" && !journal?.get(source, to))
+                    res.tierIgnored.push({ from: sender.name, id: deterministicId(source, to), to, subject, type, reason: tf.ignored });
                 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 }, {
+                const { msg, fresh } = deliverOnce(project, journal, source, { from: sender.name, to, type, subject, body, thread, reply_to: replyTo, ...(tierOf(to) ? { tier: tierOf(to) } : {}) }, {
                     ...(held ? { held: true } : {}),
                     ...(held && flag === "on" ? { parallel: true } : {}),
                     ...(routing?.held(roleOf(sender.name)) ? { from: sender.name } : {}),

package/dist/paths.d.ts

@@ -23,6 +23,8 @@ export interface ProjectPaths {
     taskMemory: string;
 }
 export declare function projectPaths(home: string, project: string): ProjectPaths;
+/** True when a relative path leaves its base: it is `..`, starts with a `..` segment, or is absolute. A name like `..x` is not an escape. */
+export declare function escapesParent(rel: string, sep?: string): boolean;
 /** True when `child` is `parent` or inside it. */
 export declare function isInside(parent: string, child: string): boolean;
 /**