agent-lyceum 0.25.1 → 0.27.0

package/dist/scaffold.d.ts

@@ -1,3 +1,6 @@
+/** The lead's guidance on `parallel: true` (spec 23.12 point 5). Only `init` writes it, into a new lead AGENT.md. */
+export declare const LEAD_PARALLEL_HINT = "Mark a task `parallel: true` only when it is independent and touches different files from the other open tasks; list each task's files in `## Scope` first; shared components, types, routes and tokens go first, alone.";
+export declare const GLOBAL_TEAM_YAML = "# Global agent library. Projects pick agents from here by name and may override any field.\n# Relative paths here are resolved against this folder. \"~\" is allowed.\nagents:\n  lead:\n    runtime: claude-code        # claude-code | codex\n    agent_md: agents/lead/AGENT.md\n    memory: { global: agents/lead/memory }\n    # model: opus          # most capable model: keep it for the lead\n  fe-member:\n    runtime: claude-code\n    agent_md: agents/fe-member/AGENT.md\n    memory: { global: agents/fe-member/memory }\n    # model: sonnet        # cheaper model for routine work\n  qa-member:\n    runtime: claude-code\n    agent_md: agents/qa-member/AGENT.md\n    memory: { global: agents/qa-member/memory }\n    # model: sonnet        # cheaper model for routine work\n  # Model hints (comments only):\n  # - a read-only search/explorer role suits \"model: haiku\", the cheapest tier (the alias resolves per provider; on the Anthropic API it is claude-haiku-5-5).\n  # - a reviewer can run on the other runtime (\"runtime: codex\"); leave the codex model unset to use the CLI default.\n";
 export interface InitResult {
     home: string;
     created: string[];

package/dist/scaffold.js

@@ -1,6 +1,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import { assertName, homePaths, projectPaths } from "./paths.js";
+/** The lead's guidance on `parallel: true` (spec 23.12 point 5). Only `init` writes it, into a new lead AGENT.md. */
+export const LEAD_PARALLEL_HINT = "Mark a task `parallel: true` only when it is independent and touches different files from the other open tasks; list each task's files in `## Scope` first; shared components, types, routes and tokens go first, alone.";
 const PERSONAS = {
     lead: `# Lead
 
@@ -11,6 +13,7 @@ You coordinate the team. You receive the user's task, break it into concrete pie
 - Write every task with the standard task headings, and cite the mail it derives from under Upstream so teammates can trace it.
 - When a teammate reports back, decide the next step: assign follow-up work, ask another teammate to verify, or accept the result.
 - Teammates cannot message each other by default; route everything through yourself.
+- ${LEAD_PARALLEL_HINT}
 - When the whole job is verified and finished, send a \`done\` message summarising what was delivered.
 `,
     "fe-member": `# Frontend member
@@ -30,21 +33,27 @@ You verify work: run and write tests, reproduce bugs, and review changes against
 - Besides the standard reply headings, add a \`## Verdict\` section containing \`pass\` or \`fail\`, and put your prioritised list of issues under Open items.
 `,
 };
-const GLOBAL_TEAM_YAML = `# Global agent library. Projects pick agents from here by name and may override any field.
+export const GLOBAL_TEAM_YAML = `# Global agent library. Projects pick agents from here by name and may override any field.
 # Relative paths here are resolved against this folder. "~" is allowed.
 agents:
   lead:
     runtime: claude-code        # claude-code | codex
     agent_md: agents/lead/AGENT.md
     memory: { global: agents/lead/memory }
+    # model: opus          # most capable model: keep it for the lead
   fe-member:
     runtime: claude-code
     agent_md: agents/fe-member/AGENT.md
     memory: { global: agents/fe-member/memory }
+    # model: sonnet        # cheaper model for routine work
   qa-member:
     runtime: claude-code
     agent_md: agents/qa-member/AGENT.md
     memory: { global: agents/qa-member/memory }
+    # model: sonnet        # cheaper model for routine work
+  # Model hints (comments only):
+  # - a read-only search/explorer role suits "model: haiku", the cheapest tier (the alias resolves per provider; on the Anthropic API it is claude-haiku-5-5).
+  # - a reviewer can run on the other runtime ("runtime: codex"); leave the codex model unset to use the CLI default.
 `;
 export function initHome(home) {
     const hp = homePaths(home);

package/dist/schema.d.ts

@@ -108,11 +108,23 @@ export declare const DispatcherPartial: z.ZodObject<{
         }>>;
     }, z.core.$strict>>>;
     fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
+    max_instances: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
 export declare const REMOVED_DISPATCHER_KEYS: readonly ["max_parallel", "max_concurrent_runs", "workspace_mode"];
 export declare const REMOVED_AGENT_KEYS: readonly ["owns"];
+/** One runtime's model ladder, lowest first; `[]` = no ladder for that runtime (overrides team.yaml). */
+export declare const ModelTiersPartial: z.ZodObject<{
+    "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
+    codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const TIERS: readonly ["low", "mid", "high"];
+export type Tier = (typeof TIERS)[number];
 export declare const GlobalConfig: z.ZodObject<{
+    model_tiers: z.ZodOptional<z.ZodObject<{
+        "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
+        codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
             "claude-code": "claude-code";
@@ -164,6 +176,10 @@ export declare const ProjectConfig: z.ZodObject<{
     team: z.ZodObject<{
         lead: z.ZodString;
     }, z.core.$strict>;
+    model_tiers: z.ZodOptional<z.ZodObject<{
+        "claude-code": z.ZodOptional<z.ZodArray<z.ZodString>>;
+        codex: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     dispatcher: z.ZodDefault<z.ZodObject<{
         max_rounds: z.ZodOptional<z.ZodNumber>;
         max_parallel: z.ZodOptional<z.ZodUnknown>;
@@ -189,6 +205,7 @@ export declare const ProjectConfig: z.ZodObject<{
             }>>;
         }, z.core.$strict>>>;
         fallback_cooldown_sec: z.ZodOptional<z.ZodNumber>;
+        max_instances: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         runtime: z.ZodOptional<z.ZodEnum<{
@@ -245,6 +262,8 @@ export interface DispatcherSettings {
     log_max_bytes: number;
     /** How long a primary that hit rate_limit/quota is skipped within a run, unless the CLI says when to come back. */
     fallback_cooldown_sec: number;
+    /** Most instances of one role at a time. Not in `DISPATCHER_DEFAULTS`, so `doctor --resolved` lists it only when written; the default lives in `instances.ts`. */
+    max_instances?: number;
 }
 export declare const DISPATCHER_DEFAULTS: DispatcherSettings;
 /** How a run turned out, independent of why it stopped (`EndReason`). Only "completed" means success. */

package/dist/schema.js

@@ -65,13 +65,24 @@ export const DispatcherPartial = z
     log_max_bytes: z.number().int().min(0).optional(),
     fallback: z.array(FallbackEntryPartial).optional(),
     fallback_cooldown_sec: z.number().int().min(0).optional(),
+    /** Most instances of one role at a time (spec 23); 1 turns parallel tasks off. Unset = `DEFAULT_MAX_INSTANCES`. */
+    max_instances: z.number().int().min(1).max(8).optional(),
 })
     .strict();
 /** Settings that no longer exist; files that still carry them load, and `validate` warns. */
 export const REMOVED_DISPATCHER_KEYS = ["max_parallel", "max_concurrent_runs", "workspace_mode"];
 export const REMOVED_AGENT_KEYS = ["owns"];
+/** One runtime's model ladder, lowest first; `[]` = no ladder for that runtime (overrides team.yaml). */
+export const ModelTiersPartial = z
+    .object({
+    "claude-code": z.array(z.string().trim().min(1)).optional(),
+    codex: z.array(z.string().trim().min(1)).optional(),
+})
+    .strict();
+export const TIERS = ["low", "mid", "high"];
 export const GlobalConfig = z
     .object({
+    model_tiers: ModelTiersPartial.optional(),
     agents: z.record(z.string(), AgentPartial).default({}),
 })
     .strict();
@@ -79,6 +90,7 @@ export const ProjectConfig = z
     .object({
     dir: z.string(),
     team: z.object({ lead: z.string() }).strict(),
+    model_tiers: ModelTiersPartial.optional(),
     dispatcher: DispatcherPartial.default({}),
     agents: z.record(z.string(), AgentPartial).default({}),
 })

package/dist/status.d.ts

@@ -48,6 +48,8 @@ export declare function cacheText(read: number | undefined, write: number | unde
 export declare function progressBar(done: number, total: number, width?: number, c?: Paint): string;
 export interface QueueItem {
     agent: string;
+    /** Mail waiting for a free instance of the role in `agent` (spec 23.7): not woken yet, placed by the dispatcher. Only for roles with instances. */
+    held?: true;
     from: string;
     type: string;
     subject: string;
@@ -105,6 +107,8 @@ export interface RunReport {
         ok: boolean;
         error?: string;
     }>;
+    /** Only when the run has same-role instances: each role's open instances, the role itself first. */
+    instances?: Record<string, string[]>;
     /** Present while the run waits for the user: the file to fill in and how many questions are still open. */
     ask?: {
         path: string;
@@ -116,6 +120,9 @@ export interface AgentReport {
     name: string;
     runtime?: string;
     lead: boolean;
+    /** Only for the rows of a role that has instances (the role itself is instance 1): the role and the instance number. */
+    role?: string;
+    instance?: number;
     unread: number;
     /** Who this agent may send mail to (`all` expanded, itself left out). */
     can_message: string[];

package/dist/status.js

@@ -5,7 +5,9 @@ import { RESULT_FILE } from "./dispatcher.js";
 import { bindRunProject, loadRunState, outcomeOf, roundsLabel, runLabel } from "./run-store.js";
 import { candidatesFor } from "./fallback.js";
 import { briefOf, digestOf } from "./format.js";
-import { listUnread } from "./mailbox.js";
+import { PENDING_DIR, listUnread, readMessageNoFollow } from "./mailbox.js";
+import { parseSlotName } from "./instances.js";
+import { inboxDir } from "./policy.js";
 import { tidyAdvice } from "./memory-tidy.js";
 import { inspectRunLock, lockHolderAlive } from "./project-lock.js";
 /** The run to show: the newest one still running (a resumed run keeps its old id, so newer runs may sit above it), else the newest run. */
@@ -154,7 +156,7 @@ function stepsLine(steps, c, finished = false) {
     return `目前：${clip(cur.text, 60)}`;
 }
 /** Order the dispatcher will wake agents: the lead first, otherwise the oldest mail. */
-function queueOf(project) {
+function queueOf(project, instances) {
     const rows = Object.values(project.agents)
         .map((a) => ({ agent: a.name, msg: listUnread(project, a.name)[0] }))
         .flatMap((r) => (r.msg ? [{ agent: r.agent, msg: r.msg }] : []));
@@ -163,7 +165,7 @@ function queueOf(project) {
             return x.agent === project.lead ? -1 : 1;
         return path.basename(x.msg.file).localeCompare(path.basename(y.msg.file));
     });
-    return rows.map((r) => ({
+    const items = rows.map((r) => ({
         agent: r.agent,
         from: r.msg.meta.from,
         type: r.msg.meta.type,
@@ -171,14 +173,44 @@ function queueOf(project) {
         brief: briefOf(r.msg.body),
         digest: digestOf(r.msg.meta.type, r.msg.body),
     }));
+    return [...items, ...heldQueue(project, instances)];
 }
+/** Mail the assigner still holds for roles with instances, oldest first per role. Unreadable files are skipped. */
+function heldQueue(project, instances) {
+    const out = [];
+    for (const role of Object.keys(instances?.roles ?? {}).sort()) {
+        const dir = path.join(inboxDir(project, role), PENDING_DIR);
+        let files = [];
+        try {
+            files = fs.readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith(".")).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            try {
+                const m = readMessageNoFollow(path.join(dir, f));
+                out.push({ agent: role, held: true, from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) });
+            }
+            catch {
+                /* a half-written file: the next poll sees it */
+            }
+        }
+    }
+    return out;
+}
+/** How an agent is named on the text pages: an instance of a role shows as `role #k`. */
+const shownName = (name, slots) => {
+    const i = parseSlotName(name);
+    return i && slots?.[i.role]?.[i.k - 1] === name ? `${i.role} #${i.k}` : name;
+};
 /** One run as `status` sees it. Without `project`, liveness falls back to the recorded pid and there is no queue. */
 export function buildRunReport(run, project, opts = {}) {
     const s = run.state;
     const detail = opts.detail ?? true;
     const live = runIsAlive(s, project) && !s.end_reason;
     const o = outcomeOf(s);
-    const bound = project ? bindRunProject(project, run.dir, s.mail_layout) : undefined;
+    const bound = project ? bindRunProject(project, run.dir, s.mail_layout, s.instances) : undefined;
     const result = path.join(run.dir, RESULT_FILE);
     const hasResult = detail && s.end_reason === "done" && fs.existsSync(result);
     const cur = s.steps?.find((x) => !x.done);
@@ -221,7 +253,7 @@ export function buildRunReport(run, project, opts = {}) {
         current_step: cur?.text ?? null,
         active: s.active,
         // mail still waiting is what `resume` will pick up, so it is shown for every run that did not finish with a done
-        queue: detail && bound && s.end_reason !== "done" ? queueOf(bound) : [],
+        queue: detail && bound && s.end_reason !== "done" ? queueOf(bound, s.instances) : [],
         wakes: s.wakes,
         notes: s.notes ?? [],
         blocked_integrations: s.blocked_integrations ?? [],
@@ -230,6 +262,7 @@ export function buildRunReport(run, project, opts = {}) {
         mail_layout: s.mail_layout,
         workspace_mode: s.workspace_mode,
         last_wake: s.last_wake,
+        ...(s.instances ? { instances: s.instances.roles } : {}),
         ...(ask ? { ask } : {}),
     };
 }
@@ -277,7 +310,7 @@ export function buildStatusReport(base, runId, now = Date.now()) {
     else
         run = currentRun(base);
     // Mail is per run: count the unread mail of the run being shown.
-    const project = run ? bindRunProject(base, run.dir, run.state.mail_layout) : base;
+    const project = run ? bindRunProject(base, run.dir, run.state.mail_layout, run.state.instances) : base;
     const report = run ? buildRunReport(run, base) : undefined;
     let advice = [];
     try {
@@ -286,13 +319,21 @@ export function buildStatusReport(base, runId, now = Date.now()) {
     catch {
         /* a hint only: never let it break status */
     }
-    return {
+    const wakes = run?.state.wakes ?? [];
+    const below = new Set();
+    for (const a of Object.values(project.agents)) {
+        const last = wakes.filter((w) => w.agent === a.name).at(-1);
+        if (last?.tier && !last.fallback_from && last.runtime === a.runtime && !candidatesFor(a).some((c) => c.primary && c.key === `${last.runtime}/${(last.model ?? "").trim().toLowerCase()}`))
+            below.add(a.name);
+    }
+    const out = {
         schema_version: 1,
         project: projectInfo(base),
         agents: Object.values(project.agents).map((a) => ({
             name: a.name,
             runtime: a.runtime,
             lead: a.name === project.lead,
+            ...(a.instance ? { role: a.instance.role, instance: a.instance.k } : {}),
             unread: listUnread(project, a.name).length,
             can_message: (a.canMessage === "all" ? Object.keys(project.agents) : a.canMessage).filter((n) => n !== a.name),
             last_wake: run?.state.last_wake[a.name],
@@ -301,6 +342,8 @@ export function buildStatusReport(base, runId, now = Date.now()) {
         run: report,
         ...(advice.length ? { memory_advice: advice } : {}),
     };
+    belowCeiling.set(out, below);
+    return out;
 }
 /** Every run of the project, newest first. */
 export function buildTaskListReport(project) {
@@ -309,10 +352,10 @@ export function buildTaskListReport(project) {
 // ---- text pages ----
 /** Agents in wake order, newest last; the ones working now are bracketed. */
 function flowLine(r, c) {
-    const names = (r.wakes ?? []).map((w) => w.agent);
+    const names = (r.wakes ?? []).map((w) => shownName(w.agent, r.instances));
     const shown = names.slice(-7);
     const parts = shown.map((n) => c.cyan(n));
-    const activeNames = r.live ? Object.keys(r.active ?? {}) : [];
+    const activeNames = r.live ? Object.keys(r.active ?? {}).map((n) => shownName(n, r.instances)) : [];
     const out = (names.length > shown.length ? "… → " : "") + parts.join(" → ");
     if (!activeNames.length)
         return out || "（尚無）";
@@ -320,7 +363,7 @@ function flowLine(r, c) {
 }
 /** The state label of a report: an outcome that was only inferred (old runs) is not shown as a checked result. */
 const reportLabel = (r) => runStateLabel({ end_reason: r.end_reason, outcome: r.outcome_verified ? r.outcome : undefined }, r.live);
-const mailText = (m) => `來自 ${m.from} 的 ${m.type}：「${clip(m.subject, 60)}」`;
+const mailText = (m, slots) => `來自 ${shownName(m.from, slots)} 的 ${m.type}：「${clip(m.subject, 60)}」${m.held ? "（保留中，等待空閒實例）" : ""}`;
 const taskText = (s) => s.task_summary ?? (s.task_source === "file" ? `檔案 ${s.task_path}` : "文字");
 /** The readable top block: what is happening, what is next, how far along the task is. */
 function summaryBlock(run, now, c) {
@@ -338,7 +381,7 @@ function summaryBlock(run, now, c) {
     const active = Object.entries(s.active ?? {});
     if (active.length) {
         for (const [i, [agent, a]] of active.entries()) {
-            lines.push(`${i === 0 ? L("現在：") : "          "}${c.cyan(agent)} ${live ? c.green(`工作中 ${since(a.since, now)}`) : c.yellow("曾在工作（已中斷）")}，處理 ${handlingText(a.handling)}`);
+            lines.push(`${i === 0 ? L("現在：") : "          "}${c.cyan(shownName(agent, s.instances))} ${live ? c.green(`工作中 ${since(a.since, now)}`) : c.yellow("曾在工作（已中斷）")}，處理 ${handlingText(a.handling)}`);
         }
     }
     else
@@ -346,7 +389,7 @@ function summaryBlock(run, now, c) {
     const queue = s.queue;
     if (queue.length) {
         for (const [i, q] of queue.slice(0, 3).entries())
-            lines.push(`${i === 0 ? L("下一個：") : "          "}${c.cyan(q.agent)} ← ${mailText(q)}`);
+            lines.push(`${i === 0 ? L("下一個：") : "          "}${c.cyan(q.agent)} ← ${mailText(q, s.instances)}`);
         if (queue.length > 3)
             lines.push(c.dim(`          … 還有 ${queue.length - 3} 筆`));
     }
@@ -387,10 +430,10 @@ function describeRun(s, now, c, limit = Infinity) {
     if (wakes.length > limit)
         lines.push(c.dim(`  … 省略較早的 ${wakes.length - limit} 筆（不帶 --monitor 可看完整紀錄）`));
     for (const w of limit < wakes.length ? wakes.slice(-limit) : wakes) {
-        lines.push(`  #${w.round} ${c.cyan(w.agent)} ${okText(c, w.ok)} (${Math.round(w.duration_ms / 1000)}s, ${tokens(w.output_tokens)} tok) — ${handlingText(w.handling)}`, `      → ${sentText(w.sent)}`);
+        lines.push(`  #${w.round} ${c.cyan(shownName(w.agent, s.instances))} ${okText(c, w.ok)} (${Math.round(w.duration_ms / 1000)}s, ${tokens(w.output_tokens)} tok) — ${handlingText(w.handling)}`, `      → ${sentText(w.sent)}`);
     }
     for (const [agent, a] of Object.entries(s.active ?? {})) {
-        lines.push(`  #${a.round} ${c.cyan(agent)} ${c.green(`工作中 ${since(a.since, now)}`)} — ${handlingText(a.handling)}`);
+        lines.push(`  #${a.round} ${c.cyan(shownName(agent, s.instances))} ${c.green(`工作中 ${since(a.since, now)}`)} — ${handlingText(a.handling)}`);
     }
     return lines;
 }
@@ -479,6 +522,19 @@ function fallbackLines(agents, c) {
     }
     return out;
 }
+/** Agents whose latest wake ran on a tiered model below the ceiling; kept off the report so `status --json` is unchanged. */
+const belowCeiling = new WeakMap();
+/** An agent whose latest wake ran on a model below its ceiling (spec 24.9): one line each, in agent order. */
+function tierLines(report, c) {
+    const out = [];
+    const wakes = report.run?.wakes ?? [];
+    for (const a of report.agents) {
+        const last = wakes.filter((w) => w.agent === a.name).at(-1);
+        if (last?.tier && last.runtime && belowCeiling.get(report)?.has(a.name))
+            out.push(`  ${c.cyan(a.name)} ${c.yellow(`tier ${last.tier}`)}（${modelName(`${last.runtime}/${last.model ?? ""}`)}）`);
+    }
+    return out;
+}
 export function formatStatusReport(report, now = Date.now(), color = false) {
     const c = paint(color);
     const run = report.run;
@@ -486,7 +542,7 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     const rows = [header];
     for (const a of report.agents) {
         const lw = a.last_wake;
-        rows.push([a.name + (a.lead ? " (lead)" : ""), a.runtime ?? "?", String(a.unread), lw ? `${lw.ok ? "成功" : "失敗"} ${lw.at}` : "-"]);
+        rows.push([(a.instance && a.instance >= 2 && a.role ? `${a.role} #${a.instance}` : a.name) + (a.lead ? " (lead)" : ""), a.runtime ?? "?", String(a.unread), lw ? `${lw.ok ? "成功" : "失敗"} ${lw.at}` : "-"]);
     }
     const w = header.map((_, i) => Math.max(...rows.map((r) => cols(r[i] ?? ""))));
     // Pad on the plain text first so ANSI codes never skew the column widths.
@@ -509,6 +565,9 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     const fb = fallbackLines(report.agents, c);
     if (fb.length)
         lines.push("", ...fb);
+    const tl = tierLines(report, c);
+    if (tl.length)
+        lines.push(...(fb.length ? [] : [""]), ...tl);
     if (run)
         lines.push("", `輸出 tokens：${tokens(run.output_tokens)}${cacheText(run.cache_read_tokens, run.cache_write_tokens) ? `　${cacheText(run.cache_read_tokens, run.cache_write_tokens)}` : ""}`);
     if (report.memory_advice?.length)

package/dist/tiers.d.ts

@@ -0,0 +1,27 @@
+import { type Tier } from "./schema.js";
+export declare function isTier(v: unknown): v is Tier;
+/** Index of `model` on `ladder` (trim + lowercase, like the fallback keys), or -1. */
+export declare function ladderIndex(ladder: readonly string[], model: string | undefined): number;
+/**
+ * The tiers an agent can run on: the ladder from its lowest entry up to and including `model` (the ceiling).
+ * `undefined` when there is nothing below the ceiling (no ladder, no model, model not on it, or it is the lowest entry).
+ */
+export declare function availableTiers(ladder: readonly string[] | undefined, model: string | undefined): string[] | undefined;
+/** `low` = lowest, `high` = ceiling, `mid` = `tiers[floor(n/2)]` (the higher middle when n is even). */
+export declare function modelForTier(tiers: readonly string[], tier: Tier): string;
+export type TierFlag = "absent" | "invalid" | Tier | {
+    ignored: "not-lead" | "not-a-task" | "no-tiers";
+};
+/** Judge the `tier` frontmatter of one outgoing mail, in the order of spec 24.5.2. Not wired anywhere yet. */
+export declare function tierFlag(i: {
+    value: unknown;
+    senderIsLead: boolean;
+    type: string;
+    recipientTiers?: string[];
+}): TierFlag;
+/** A mail without a valid tier counts as `high` (the ceiling). */
+export declare function effectiveTier(meta: {
+    tier?: unknown;
+}): Tier;
+/** The tier a wake runs at: the highest of the batch when every mail has a valid one, else `undefined` (the ceiling). */
+export declare function wakeTier(tiers: readonly unknown[]): Tier | undefined;

package/dist/tiers.js

@@ -0,0 +1,49 @@
+import { TIERS } from "./schema.js";
+const norm = (m) => (m ?? "").trim().toLowerCase();
+export function isTier(v) {
+    return typeof v === "string" && TIERS.includes(v);
+}
+/** Index of `model` on `ladder` (trim + lowercase, like the fallback keys), or -1. */
+export function ladderIndex(ladder, model) {
+    const m = norm(model);
+    return m ? ladder.findIndex((e) => norm(e) === m) : -1;
+}
+/**
+ * The tiers an agent can run on: the ladder from its lowest entry up to and including `model` (the ceiling).
+ * `undefined` when there is nothing below the ceiling (no ladder, no model, model not on it, or it is the lowest entry).
+ */
+export function availableTiers(ladder, model) {
+    if (!ladder?.length)
+        return undefined;
+    const i = ladderIndex(ladder, model);
+    return i >= 1 ? ladder.slice(0, i + 1) : undefined;
+}
+/** `low` = lowest, `high` = ceiling, `mid` = `tiers[floor(n/2)]` (the higher middle when n is even). */
+export function modelForTier(tiers, tier) {
+    const n = tiers.length;
+    return tiers[tier === "low" ? 0 : tier === "high" ? n - 1 : Math.floor(n / 2)];
+}
+/** Judge the `tier` frontmatter of one outgoing mail, in the order of spec 24.5.2. Not wired anywhere yet. */
+export function tierFlag(i) {
+    if (i.value === undefined || i.value === null || i.value === "")
+        return "absent";
+    if (!i.senderIsLead)
+        return { ignored: "not-lead" };
+    if (!isTier(i.value))
+        return "invalid";
+    if (i.type !== "task")
+        return { ignored: "not-a-task" };
+    if (!i.recipientTiers || i.recipientTiers.length < 2)
+        return { ignored: "no-tiers" };
+    return i.value;
+}
+/** A mail without a valid tier counts as `high` (the ceiling). */
+export function effectiveTier(meta) {
+    return isTier(meta.tier) ? meta.tier : "high";
+}
+/** The tier a wake runs at: the highest of the batch when every mail has a valid one, else `undefined` (the ceiling). */
+export function wakeTier(tiers) {
+    if (tiers.length === 0 || !tiers.every(isTier))
+        return undefined;
+    return TIERS[Math.max(...tiers.map((t) => TIERS.indexOf(t)))];
+}

package/dist/validate.js

@@ -1,7 +1,8 @@
 import fs from "node:fs";
 import { enforcementFor, memoryDirs } from "./policy.js";
 import { isInside } from "./paths.js";
-import { inferRuntime, RUNTIME_EFFORTS } from "./schema.js";
+import { inferRuntime, RUNTIME_EFFORTS, RUNTIMES } from "./schema.js";
+import { ladderIndex } from "./tiers.js";
 import { must } from "./assert.js";
 export function validateProject(project) {
     const issues = [];
@@ -15,7 +16,30 @@ export function validateProject(project) {
     if (!fs.existsSync(project.dir) || !fs.statSync(project.dir).isDirectory()) {
         err(`Project dir does not exist: ${project.dir}`);
     }
+    for (const rt of RUNTIMES) {
+        const ladder = project.modelTiers[rt];
+        if (!ladder)
+            continue;
+        const seen = new Set();
+        ladder.forEach((m, i) => {
+            const other = inferRuntime(m);
+            if (other !== rt)
+                err(`model_tiers.${rt}[${i}]: "${m}" is not a ${rt} model (recognised as ${other ?? "nothing"}). List only ${rt} models, lowest first.`);
+            const k = m.trim().toLowerCase();
+            if (seen.has(k))
+                err(`model_tiers.${rt}: "${m}" is listed twice.`);
+            seen.add(k);
+        });
+    }
     for (const a of Object.values(project.agents)) {
+        const ladder = a.runtime ? project.modelTiers[a.runtime] : undefined;
+        if (a.runtime && ladder) {
+            if (!a.model)
+                warn(`Agent "${a.name}" has no model, so model_tiers.${a.runtime} does not apply to it: it always runs on its runtime's default model.`);
+            else if (ladderIndex(ladder, a.model) < 0) {
+                err(`Agent "${a.name}": model "${a.model}" is not on model_tiers.${a.runtime} (${ladder.join(", ")}). Add it to the ladder, or set model_tiers.${a.runtime}: [] in project.yaml to turn the ladder off for this project.`);
+            }
+        }
         if (!a.runtime)
             err(`Agent "${a.name}" has no runtime (set runtime, or a recognizable model such as opus/sonnet/haiku/claude-* or gpt-*/codex-*).`);
         const modelRuntime = inferRuntime(a.model);
@@ -39,6 +63,9 @@ export function validateProject(project) {
             }
         }
     }
+    if (Object.keys(project.modelTiers).length > 0 && !Object.values(project.agents).some((a) => a.name !== project.lead && a.tiers)) {
+        warn("model_tiers is set, but no member can run below its model (each member's model is the lowest entry of its ladder): tiers have no effect.");
+    }
     // Memory directories must not overlap between agents (or equal each other).
     const mem = [];
     for (const a of Object.values(project.agents))

package/dist/worktree.d.ts

@@ -81,6 +81,7 @@ export declare function snapshotHead(project: ResolvedProject, runId: string): s
  * `from`: the checkout to snapshot — the lead's worktree in a concurrent run; by default your repo's working tree.
  */
 export declare function snapshotBase(project: ResolvedProject, runId: string, n: number, from?: AgentWorkspace): string;
+export declare const workspaceRoot: (project: ResolvedProject, runId: string, agent: string) => string;
 /**
  * The agent's own checkout of the snapshot `baseRef`, at `<project home>/worktrees/<run>/<agent>`.
  * An existing checkout is reused: untouched, when it already is on this snapshot (resume) or holds unfinished
@@ -144,6 +145,11 @@ export declare function integrateAgentChanges(project: ResolvedProject, changes:
  * Throws when the metadata predates recording the git dir and the git dir cannot be told for certain.
  */
 export declare function existingAgentWorkspace(project: ResolvedProject, runId: string, agent: string): AgentWorkspace | undefined;
+/**
+ * The git dir recorded in an agent's worktree metadata, read-only (never completes or rewrites legacy metadata). undefined when there
+ * is no readable metadata or it predates recording the git dir.
+ */
+export declare function recordedGitDir(project: ResolvedProject, runId: string, agent: string): string | undefined;
 export interface WorkspaceWork {
     agent: string;
     root: string;

package/dist/worktree.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { atomicWrite } from "./fs-util.js";
+import { escapesParent } from "./paths.js";
 const IDENTITY = {
     GIT_AUTHOR_NAME: "agent-lyceum",
     GIT_AUTHOR_EMAIL: "agent-lyceum@localhost",
@@ -290,7 +291,7 @@ export function snapshotBase(project, runId, n, from) {
         fs.rmSync(index, { force: true });
     }
 }
-const workspaceRoot = (project, runId, agent) => path.join(project.paths.root, "worktrees", runId, agent);
+export const workspaceRoot = (project, runId, agent) => path.join(project.paths.root, "worktrees", runId, agent);
 /** The user's repo's git common dir, as a real absolute path. Asked of the user's repo, never of a worktree. */
 const commonDirOf = (top) => fs.realpathSync(git(top, ["rev-parse", "--path-format=absolute", "--git-common-dir"]));
 /** The admin dirs under `<commonDir>/worktrees/` whose `gitdir` file names `<root>/.git` (the file may hold a relative path). */
@@ -474,7 +475,7 @@ export function collectAgentChanges(workspace) {
             const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(p), target));
             if (path.posix.isAbsolute(target))
                 violations.push(`${f.path}: symlink to an absolute path (${target})`);
-            else if (resolved.startsWith(".."))
+            else if (escapesParent(resolved, "/"))
                 violations.push(`${f.path}: symlink leaves the project directory (${target})`);
         }
     }
@@ -594,6 +595,19 @@ export function existingAgentWorkspace(project, runId, agent) {
     }
     return fs.existsSync(root) ? describeWorkspace(project, root, agent, meta) : undefined;
 }
+/**
+ * The git dir recorded in an agent's worktree metadata, read-only (never completes or rewrites legacy metadata). undefined when there
+ * is no readable metadata or it predates recording the git dir.
+ */
+export function recordedGitDir(project, runId, agent) {
+    try {
+        const meta = JSON.parse(fs.readFileSync(`${workspaceRoot(project, runId, agent)}.json`, "utf8"));
+        return typeof meta.gitDir === "string" && meta.gitDir ? meta.gitDir : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** What is in an agent's worktree that exists nowhere else: uncommitted changes, and commits whose files are not in the main repo. */
 export function inspectWorkspace(project, runId, agent, target) {
     const root = workspaceRoot(project, runId, agent);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-lyceum",
-  "version": "0.25.1",
+  "version": "0.27.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",