agent-lyceum 0.26.0 → 0.27.0

package/dist/paths.js

@@ -44,10 +44,13 @@ export function projectPaths(home, project) {
         taskMemory: path.join(root, "task-memory"),
     };
 }
+/** 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 function escapesParent(rel, sep = path.sep) {
+    return rel === ".." || rel.startsWith(`..${sep}`) || path.isAbsolute(rel);
+}
 /** True when `child` is `parent` or inside it. */
 export function isInside(parent, child) {
-    const rel = path.relative(parent, child);
-    return rel === "" || (rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel));
+    return !escapesParent(path.relative(parent, child));
 }
 /**
  * `p` with symlinks resolved as far as it exists: the real path of its deepest existing ancestor plus the rest. A path that does not exist

package/dist/prompt.d.ts

@@ -1,8 +1,17 @@
 import type { ResolvedAgent, ResolvedProject } from "./config.js";
 import type { Message } from "./mailbox.js";
 import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-tidy.js";
+/** Lead-only rules that keep the number of wake-ups down; placed after the progress-tracking block. */
+export declare const WAKE_ECONOMY_SECTION: string[];
 /** The lead's system prompt gets this at its very end when same-role instances are possible in the run (spec 23.12). No trailing newline. */
 export declare const PARALLEL_SECTION: (n: number) => string;
+/** The lead's system prompt ends with this when a member can run a task on a cheaper model (spec 24.10); `members` = [name, model of low, mid, high]. No trailing newline. */
+export declare const TIER_SECTION: (members: {
+    name: string;
+    low: string;
+    mid: string;
+    high: string;
+}[]) => string;
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
 export declare const HANDOFF_LIMIT: number;

package/dist/prompt.js

@@ -3,6 +3,7 @@ import { cutUtf8, readFileCapped } from "./fs-util.js";
 import path from "node:path";
 import { REQUIRED_SECTIONS } from "./format.js";
 import { senderLabel, slotName } from "./instances.js";
+import { modelForTier } from "./tiers.js";
 import { buildRecordsView, RECORDS_BUDGET } from "./records.js";
 import { commonFile, memoryDirs, outboxDir, recordsKindDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
@@ -13,6 +14,15 @@ function memoryLabel(agent, dir) {
     const kind = dir === (agent.memory.global ?? agent.sharedMemory?.global) ? "global (all projects" : "project (all tasks of this project";
     return shared ? `${kind}, read-only for you: ${instance1} maintains it)` : `${kind})`;
 }
+/** Lead-only rules that keep the number of wake-ups down; placed after the progress-tracking block. */
+export const WAKE_ECONOMY_SECTION = [
+    "## Keeping wake-ups few",
+    "Every wake-up re-reads your whole context (prompt, memory, mail), so the number of wake-ups, yours and your teammates', is the main cost of a run.",
+    "- Send all work that is independent of each other in the same wake-up (for example the implementation and the matching docs), each task naming its reviewer, instead of one task per wake-up.",
+    "- When a reply arrives while other work you sent is still out and the reply needs nothing from you yet, send no mail: note it in your task memory and end the wake-up. Decide the next step once, when the rest is back; replies waiting together are handed to you in one wake-up.",
+    "- Skip the QA layer (the verification role and its reviewer) for a small fix: a change of a few lines that has a reproduction test which failed before and passes after, and an approving code review. Send QA for large changes, changes across modules, and changes to user-visible behaviour.",
+    "- Use the most capable (most expensive) model only at three moments: before the plan is final, when the same error shows up a second time, and before you send `done`. In other rounds prefer teammates on cheaper models; read-only search work suits the cheapest one.",
+];
 /** The lead's system prompt gets this at its very end when same-role instances are possible in the run (spec 23.12). No trailing newline. */
 export const PARALLEL_SECTION = (n) => [
     "## Parallel tasks",
@@ -24,6 +34,13 @@ export const PARALLEL_SECTION = (n) => [
     "- When rate limits hit, fewer instances may start; waiting tasks run when an instance is free.",
     "- After parallel work is back, have one member type-check and test the combined result before you report `done`.",
 ].join("\n");
+/** The lead's system prompt ends with this when a member can run a task on a cheaper model (spec 24.10); `members` = [name, model of low, mid, high]. No trailing newline. */
+export const TIER_SECTION = (members) => [
+    "## Task tiers",
+    "Some members can run a task on a cheaper model than their own. Add the frontmatter line `tier: low`, `tier: mid` or `tier: high` to a `task` you send them; without it they use their own model. Pick by difficulty: `low` for mechanical work with an exact spec (renames, a one-line fix, running a given command), `mid` for routine changes in one module, `high` (or no tier) for design, debugging, reviews and anything unclear. A tier lasts for that one task: replies and later mail on the thread run on the member's own model, so put `tier` again on each follow-up task. Each model keeps its own session, so a member that resumes sessions does not see what it did on another model; say in the task what it needs. If a tiered task comes back poor, send it again with a higher tier.",
+    "Members and the models each tier uses:",
+    ...members.map((m) => `- ${m.name}: low ${m.low}, mid ${m.mid}, high ${m.high}`),
+].join("\n");
 export const COMMON_LIMIT = 8 * 1024;
 export const MEMORY_INDEX_LIMIT = 4 * 1024;
 export const HANDOFF_LIMIT = COMMON_LIMIT;
@@ -148,7 +165,7 @@ export function buildSystemPrompt(project, agent) {
             "Your final `done` mail must also include the full `## Steps` checklist. Tick only steps that were actually done and verified; leave undone ones",
             "(e.g. build, app start, commit) unticked and say so in the mail instead of reporting them as finished.",
         ]
-        : []), ...(isLead && sharedDir(project) ? handoffRule(sharedDir(project)) : []), "", "## Memory");
+        : []), ...(isLead ? ["", ...WAKE_ECONOMY_SECTION] : []), ...(isLead && sharedDir(project) ? handoffRule(sharedDir(project)) : []), "", "## Memory");
     const mems = memoryDirs(agent);
     const sharedMems = Object.values(agent.sharedMemory ?? {});
     if (mems.length === 0)
@@ -169,8 +186,18 @@ export function buildSystemPrompt(project, agent) {
             `- You also keep two kinds of durable records for every future run of this project, one Markdown file per entry: decisions in \`${recordsKindDir(project, "decisions")}/\` (what was decided and why) and lessons in \`${recordsKindDir(project, "lessons")}/\` (heuristics and pitfalls that stay true). The file name without \`.md\` is the entry id (lowercase letters, digits, \`-\`). Each file starts with YAML frontmatter between \`---\` lines: \`status: active|superseded\`, \`date: YYYY-MM-DD\`, \`title: <one line>\`, optionally \`run: <run id>\` and \`supersedes: [<ids of entries of the same kind>]\`; the body is the decision or lesson and its reason. Prompts show only effective-active entries (\`status: active\` and not named in another entry's \`supersedes\`), newest first, up to ${CONTEXT_LIMIT / 1024} KB per kind, and list what does not fit as one line each. When an entry becomes outdated, mark it \`status: superseded\` or name it in a new entry's \`supersedes\`. Add or update entries before you send \`done\`.`,
         ]
         : []), PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
-    const text = lines.join("\n");
-    return isLead && project.run?.instances ? `${text}\n\n${PARALLEL_SECTION(project.run.instances.max)}` : text;
+    let text = lines.join("\n");
+    if (isLead && project.run?.instances)
+        text = `${text}\n\n${PARALLEL_SECTION(project.run.instances.max)}`;
+    if (isLead) {
+        const members = Object.values(project.agents)
+            .filter((a) => a.name !== project.lead && (!a.instance || a.instance.k === 1) && (a.tiers?.length ?? 0) >= 2)
+            .sort((x, y) => (x.name < y.name ? -1 : x.name > y.name ? 1 : 0))
+            .map((a) => ({ name: a.name, low: modelForTier(a.tiers, "low"), mid: modelForTier(a.tiers, "mid"), high: modelForTier(a.tiers, "high") }));
+        if (members.length)
+            text = `${text}\n\n${TIER_SECTION(members)}`;
+    }
+    return text;
 }
 /** Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so the agent decides once on all of it; the lead takes any such run, other agents only same-thread ones. */
 export function pickMessages(project, agent, queue) {

package/dist/run-session.d.ts

@@ -127,6 +127,8 @@ export declare class RunSession {
     private saveState;
     private journal;
     private note;
+    /** Spec 24.5.2: log every tier that was dropped; tell the sender once per reason (`no-tiers` is log-only). */
+    private noteTierIgnored;
     /** Bind the project to this run again, after its slot table changed. */
     private rebind;
     /** What the router needs to hold and place mail for roles with several instances (spec 23.7.1). */

package/dist/run-session.js

@@ -4,6 +4,7 @@ import { realInvoker } from "./adapters/index.js";
 import { agentForCandidate, candidatesFor, Cooldowns, defaultSleep, planAttempts, runWithFallback } from "./fallback.js";
 import { briefOf, digestOf, doneContract, mergeSteps, parseSteps } from "./format.js";
 import { ProtectedGuard } from "./guard.js";
+import { listRunLocks, lockHolderAlive } from "./project-lock.js";
 import { addBatch, askersWithAnswers, askReplyPath, checkAnswers, describeCheck, isComplete, markDelivered, parseAskBody, readAskReply, renderAnswers, resolveOptionLetters, writeAskReply } from "./ask-reply.js";
 import { deliver, deliverOnce, ensureAgentDirs, ensureProjectDirs, finishDone, listUnread, PENDING_DIR, readMessageNoFollow, rejectDone, routeOutboxes, unreadFiles } from "./mailbox.js";
 import { instanceContainment } from "./instance-containment.js";
@@ -20,6 +21,7 @@ import { bindRunProject, newRunId, newRunState, roundLimit, roundsLabel, saveRun
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
+import { modelForTier, wakeTier } from "./tiers.js";
 import { openPullRequest, prBody, prTitle, realRunner } from "./open-pr.js";
 export { newRunId };
 export const RESULT_FILE = "result.md";
@@ -37,6 +39,8 @@ function readIndex(file) {
 }
 /** The `state.sessions` key of the session an agent runs in on candidate `c`: a backup has a session of its own. */
 const sessionKeyOf = (agent, c) => (c.primary ? agent.name : `${agent.name}@${c.key}`);
+/** Why `key` is cooling down, for a message. */
+const cooldownKind = (cd, key) => cd.toJSON()[key]?.kind ?? "unknown";
 /** `runtime/model`, or the runtime alone for its default model. */
 const modelLabel = (c) => (c.model ? `${c.runtime}/${c.model}` : c.runtime);
 /** Each model given up on once, in order, with its last failure (retries on the same model are one entry). */
@@ -241,7 +245,8 @@ export class RunSession {
         }
         const saveState = () => saveRunState(runDir, state);
         // Concurrent runs: the repo's instruction files the run can touch are the lead worktree's copies; your own tree is never watched (or restored).
-        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project);
+        const otherLiveRuns = () => listRunLocks(project.paths.root).filter((l) => l.run_id !== runId && lockHolderAlive(l)).map((l) => l.run_id);
+        const guard = new ProtectedGuard(leadSpace ? { ...project, workspaces: { ...project.workspaces, [project.lead]: leadSpace } } : project, otherLiveRuns);
         if (resume) {
             log("resume", { rounds: state.rounds, interrupted: Object.keys(resume.active ?? {}) });
             if (opts.followup) {
@@ -320,6 +325,21 @@ export class RunSession {
         log("note", { text });
         say(`  ${text}`);
     }
+    /** Spec 24.5.2: log every tier that was dropped; tell the sender once per reason (`no-tiers` is log-only). */
+    noteTierIgnored(route) {
+        for (const t of route.tierIgnored) {
+            this.log("tier_ignored", { from: t.from, id: t.id, to: t.to, reason: t.reason });
+            if (t.reason === "no-tiers")
+                continue;
+            const key = `tier\u0000${t.from}\u0000${t.reason}`;
+            if (this.ignoredNoted.has(key))
+                continue;
+            this.ignoredNoted.add(key);
+            this.note(t.reason === "not-lead"
+                ? `${t.from}'s mail ${t.id} has \`tier\`, but only the lead (${this.project.lead}) can choose a member's tier: it was delivered without one.`
+                : `${t.from}'s mail ${t.id} ("${t.subject}") has \`tier\` but is a ${t.type}: tiers apply to tasks only, so it was delivered without one.`);
+        }
+    }
     /** Bind the project to this run again, after its slot table changed. */
     rebind() {
         this.project = withCapability(bindRunProject(this.base, this.runDir, this.layout, this.state.instances), this.wsMode, this.instanceCheck, this.state.instances);
@@ -555,11 +575,21 @@ export class RunSession {
             timeoutSec: cfg.wake_timeout_sec,
         };
         // Without a fallback chain (one candidate) the loop, its output and its records are exactly those of plain retries (spec 20.2 decision 11).
-        const all = candidatesFor(agent);
+        // A lead's `tier` (spec 24.5.3): only for an agent with a ladder, and only a valid value counts.
+        const tier = agent.tiers && agent.tiers.length >= 2 ? wakeTier(unread.map((m) => m.meta.tier)) : undefined;
+        const all = candidatesFor(agent, tier && agent.tiers ? modelForTier(agent.tiers, tier) : undefined);
         const chain = all.length > 1;
-        const candidates = chain ? planAttempts(agent, cooldowns, Date.now()) : all;
+        const candidates = chain ? planAttempts(all, cooldowns, Date.now()) : all;
+        const ceiling = must(all.find((c) => c.primary), "the agent's own model");
+        const tieredFirst = all[0]?.tiered ? all[0] : undefined;
         // The model a backup's calls stand in for: the one switched away from in this wake, or the cooling-down primary it started past.
-        let replaced = candidates[0]?.primary ? undefined : all[0];
+        // A tier's cheaper model is not a fallback (spec 24.7.3): only chain entries have one.
+        let replaced = candidates[0]?.primary || candidates[0]?.tiered ? undefined : ceiling;
+        if (tieredFirst && !candidates[0]?.tiered) {
+            const left = Math.ceil(cooldowns.active(tieredFirst.key, Date.now()) / 1000);
+            say(`  ${agent.name} tier ${tier} model ${modelLabel(tieredFirst)} is cooling down (${cooldownKind(cooldowns, tieredFirst.key)}, ${left}s left): starting on ${modelLabel(candidates[0])}`);
+            log("tier_step_up", { agent: agent.name, tier, from: modelLabel(tieredFirst), to: modelLabel(candidates[0]), reason: "cooldown" });
+        }
         let calls = 0;
         let stoppedByCancel = false;
         const outcome = await runWithFallback({
@@ -580,8 +610,19 @@ export class RunSession {
                 return state.max_rounds > 0 && state.rounds >= state.max_rounds ? "stop" : undefined;
             },
             onSwitch: (from, to, kind) => {
-                replaced = from;
+                if (!from.tiered)
+                    replaced = from;
                 this.syncCooldowns();
+                if (from.tiered) {
+                    log("tier_step_up", { agent: agent.name, tier, from: modelLabel(from), to: modelLabel(to), reason: kind ?? "unknown" });
+                    if (opts.signal?.aborted)
+                        return;
+                    say(`  ${agent.name} stepping up from tier ${tier} (${modelLabel(from)}) to ${modelLabel(to)} (${kind ?? "unknown error"})`);
+                    const resumesTo = agent.resume && !!state.sessions[sessionKeyOf(agent, to)];
+                    this.note(`${agent.name}'s tier ${tier} model ${modelLabel(from)} failed (${kind ?? "unknown error"}); it is woken again on ${modelLabel(to)}, which ${resumesTo ? "resumes its own earlier session" : "starts a fresh session"}, and redoes this wake-up. ` +
+                        `Anything the failed attempts already did outside the mailbox (file edits, commands) was not undone: side effects may have happened.`);
+                    return;
+                }
                 if (opts.signal?.aborted)
                     return;
                 say(`  ${agent.name} falling back to ${modelLabel(to)} (${kind ?? "unknown error"})`);
@@ -603,7 +644,7 @@ export class RunSession {
                 const redo = this.redoContext(agent.name, unread.map((m) => m.meta.id), att.id, attempt);
                 const userPrompt = redoUserPrompt(base.userPrompt, { attempt, error: ctx.previous?.error, prior: redo.prior, drafts: redo.drafts, taskMemory: agent.memory.task });
                 const retryN = chain ? ctx.candidateAttempt : attempt;
-                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime})${retryN ? ` — retry ${retryN}` : ""}`);
+                say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${chain ? modelLabel(c) : agent.runtime}${c.tiered ? `, tier ${tier}` : ""})${retryN ? ` — retry ${retryN}` : ""}`);
                 const sessionId = agent.resume ? state.sessions[sessionKey] : undefined;
                 const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
                 // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
@@ -632,7 +673,7 @@ export class RunSession {
                 state.cache_write_tokens += result.cacheWriteTokens ?? 0;
                 delete state.active[agent.name];
                 // With a chain only: which model ran, what it replaced, why it failed.
-                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || !replaced ? undefined : modelLabel(replaced), kind: result.kind } : {};
+                const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || c.tiered ? undefined : modelLabel(replaced ?? ceiling), kind: result.kind } : {};
                 state.wakes.push({
                     round,
                     agent: agent.name,
@@ -645,8 +686,9 @@ export class RunSession {
                     handling,
                     error: result.error,
                     ...which,
+                    ...(tier ? { tier } : {}),
                 });
-                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}) };
+                state.last_wake[agent.name] = { at: new Date().toISOString(), ok: result.ok, error: result.error, ...(chain ? { runtime: c.runtime, model: c.model } : {}), ...(tier ? { tier } : {}) };
                 log("wake", {
                     agent: agent.name,
                     runtime: c.runtime,
@@ -659,6 +701,7 @@ export class RunSession {
                     error: result.error,
                     ...(redo.prior.length ? { redo_of: redo.prior.map((a) => a.id) } : {}),
                     ...(chain ? { model: c.model, fallback_from: which.fallback_from, kind: result.kind } : {}),
+                    ...(tier ? { tier } : {}),
                 });
                 this.saveState();
                 if (result.ok) {
@@ -820,6 +863,11 @@ export class RunSession {
                     (v.saved ? `\n\nWhat was written is kept at \`${v.saved}\` (sha256 ${v.sha256}${v.truncated ? ", truncated to 1 MiB" : ""}). If it is worth keeping, have an agent that may edit this file redo it.` : ""),
             });
         }
+        // Another run's lead edited a cross-run shared file: kept, not a violation of this batch, nobody is woken for it.
+        for (const u of guard.takeUnattributed()) {
+            say(`  shared file changed by another live run (${u.otherRuns.join(", ")}); kept: ${u.file}`);
+            log("protected-change-unattributed", { ...u });
+        }
         // Crash seam: every wake of the batch is finished and marked output_ready; nothing of it is integrated or routed yet.
         fault("wake:ready");
         batch.forEach((a, i) => {
@@ -851,6 +899,7 @@ export class RunSession {
                 contract = undefined;
             }
         }
+        this.noteTierIgnored(route);
         const askAccepted = this.handleAsks(route);
         for (const d of route.delivered)
             log("route", d);

package/dist/run-store.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedProject } from "./config.js";
 import type { DigestSection, Step } from "./format.js";
-import { type ErrorKind, type Runtime, type RunOutcome } from "./schema.js";
+import { type ErrorKind, type Runtime, type RunOutcome, type Tier } from "./schema.js";
 import type { ResultBranch } from "./worktree.js";
 export declare const STATE_FILE = "state.json";
 /** The newest state format this version reads. */
@@ -51,6 +51,8 @@ export interface WakeRecord {
     fallback_from?: string;
     /** With a fallback chain only: why the call failed. */
     kind?: ErrorKind;
+    /** The tier this wake ran at (spec 24): set only when every mail it handled carried a valid one. */
+    tier?: Tier;
 }
 /** A model given up on during a wake with a fallback chain, for `failure.tried`. */
 export interface TriedModel {
@@ -123,6 +125,7 @@ export interface RunState {
         error?: string;
         runtime?: Runtime;
         model?: string;
+        tier?: Tier;
     }>;
     /** Process running this dispatcher, so a monitor can tell "running" from "interrupted". */
     pid: number;

package/dist/scaffold.d.ts

@@ -1,5 +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

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

@@ -113,7 +113,18 @@ export declare const DispatcherPartial: z.ZodObject<{
 /** 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";
@@ -165,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>;

package/dist/schema.js

@@ -72,8 +72,17 @@ export const DispatcherPartial = z
 /** 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();
@@ -81,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.js

@@ -319,7 +319,14 @@ 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) => ({
@@ -335,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) {
@@ -513,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;
@@ -543,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.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",
@@ -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})`);
         }
     }

package/package.json

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