agent-lyceum 0.26.0 → 0.28.0

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";
@@ -25,14 +27,31 @@ export function serialize(meta, body) {
     const fm = YAML.stringify(meta).trimEnd();
     return `---\n${fm}\n---\n\n${body.trim()}\n`;
 }
+const ID_KEYS = new Set(["id", "reply_to", "thread", "about", "run_id"]);
 export function parseRaw(text) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!m)
         throw new Error("missing frontmatter (--- ... ---)");
-    const data = YAML.parse(m[1] ?? "");
+    const fm = m[1] ?? "";
+    const data = YAML.parse(fm);
     if (!data || typeof data !== "object" || Array.isArray(data))
         throw new Error("frontmatter is not a mapping");
-    return { data: data, body: (m[2] ?? "").trim() };
+    const out = data;
+    // Ids are 8 hex characters: `79e76911` parses as Infinity and `01234567` as 1234567.
+    // Only an id key that came out as a number is re-read from its source text; everything else stays as YAML.parse returned it.
+    if (Object.entries(out).some(([k, v]) => ID_KEYS.has(k) && typeof v === "number")) {
+        const doc = YAML.parseDocument(fm);
+        if (YAML.isMap(doc.contents)) {
+            for (const pair of doc.contents.items) {
+                const key = YAML.isScalar(pair.key) ? String(pair.key.value) : "";
+                if (!ID_KEYS.has(key) || typeof out[key] !== "number" || !YAML.isScalar(pair.value))
+                    continue;
+                if (pair.value.type === "PLAIN" && typeof pair.value.source === "string")
+                    out[key] = pair.value.source;
+            }
+        }
+    }
+    return { data: out, body: (m[2] ?? "").trim() };
 }
 export function ensureProjectDirs(project) {
     fs.mkdirSync(path.join(project.paths.shared, "common"), { recursive: true });
@@ -64,6 +83,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 +143,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 +220,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 +236,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 +248,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 +261,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 +354,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 +382,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 +390,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 +422,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;
 /**

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

@@ -50,3 +50,36 @@ export declare function setOsSandboxForTest(available: boolean | undefined): voi
 export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;
 /** Can `agent` legitimately change this protected file? */
 export declare function mayEditProtected(project: ResolvedProject, agent: ResolvedAgent, file: string): boolean;
+export type SandboxRelation = "equal" | "inside" | "contains";
+export interface SandboxPathConflict {
+    key: "write" | "unix_sockets";
+    index: number;
+    path: string;
+    protectedPath: string;
+    reason: string;
+    relation: SandboxRelation;
+}
+/** Pure (spec 25.4.3): which canonical sandbox paths equal, sit inside or contain a protected path. Callers canonicalize. */
+export declare function sandboxPathConflicts(entries: {
+    key: "write" | "unix_sockets";
+    index: number;
+    path: string;
+}[], protectedPaths: {
+    path: string;
+    reason: string;
+}[]): SandboxPathConflict[];
+/** What a runtime really applies of an agent's allowances (spec 25.9): the tuple a fallback must not exceed. */
+export interface SandboxCaps {
+    network: "none" | "domains" | "all";
+    localBinding: boolean;
+    unixSockets: boolean;
+}
+export declare const NETWORK_RANK: {
+    readonly none: 0;
+    readonly domains: 1;
+    readonly all: 2;
+};
+/** Without an OS sandbox nothing is applied, so every runtime is equal there. */
+export declare function sandboxCaps(agent: ResolvedAgent, runtime?: string | undefined): SandboxCaps;
+/** Components in which `backup` applies more than `primary`, as `name: primary -> backup`. */
+export declare function sandboxCapExcess(primary: SandboxCaps, backup: SandboxCaps): string[];

package/dist/policy.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { findOnPath } from "./fs-util.js";
+import { canonicalPath } from "./paths.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
 }
@@ -88,6 +89,8 @@ export function writePolicy(project, agent) {
         ...(ws ? [ws.gitDir] : []),
         ...(shared && mayWriteShared ? [shared] : []),
         ...(isLead ? [recordsDir(project)] : []),
+        // Spec 25: canonical, because the OS sandbox compares real paths (`/tmp` is `/private/tmp` on macOS).
+        ...(agent.sandbox?.write ?? []).map(canonicalPath),
     ];
     const allowFiles = [];
     if (isLead)
@@ -180,6 +183,8 @@ export function enforcementFor(project, agent) {
         if (agent.canEditAgentMd)
             notes.push("can_edit_agent_md widens Codex writable roots to whole agent directories.");
     }
+    if (agent.sandbox)
+        notes.push(...sandboxNotes(agent, os));
     return {
         agent: agent.name,
         runtime: agent.runtime ?? "?",
@@ -188,7 +193,82 @@ export function enforcementFor(project, agent) {
         notes,
     };
 }
+/** Doctor lines for an agent's sandbox allowances (spec 25.7, 25.10): what is requested and what its runtime really applies. */
+function sandboxNotes(agent, os) {
+    const s = agent.sandbox;
+    if (!s)
+        return [];
+    const claude = agent.runtime === "claude-code";
+    const notes = [];
+    if (!os) {
+        notes.push(claude
+            ? "no OS sandbox; sandbox.write changes Edit tool rules only; network/local_binding/unix_sockets have no effect."
+            : "no OS sandbox; enforcement is prompt-only; sandbox allowances provide no OS enforcement.");
+    }
+    if (s.network.length) {
+        notes.push(`network: ${s.network.join(", ")} (${claude ? "claude-code: per-domain" : "codex: all hosts"})`);
+        if (!claude)
+            notes.push(`warn: sandbox.network is all-or-nothing on Codex: this agent may reach any host, not only ${s.network.join(", ")}.`);
+    }
+    if (s.localBinding) {
+        notes.push(claude ? (process.platform === "darwin" ? "local_binding: on" : "local_binding: requested, no effect on this platform (macOS only)") : "local_binding: requested, not supported by codex");
+        if (!claude)
+            notes.push("warn: sandbox.local_binding has no Codex setting; whether a workspace-write sandbox lets it bind ports is unverified. sandbox.network turns on all network access, not only binding.");
+    }
+    if (s.unixSockets.length) {
+        notes.push(`unix_sockets: ${s.unixSockets.map(canonicalPath).join(", ")} (${claude ? "applied" : "not applied by codex"})`);
+        if (!claude)
+            notes.push("warn: sandbox.unix_sockets has no per-socket Codex control; no setting emitted.");
+    }
+    for (const [key, list] of [["write", s.write], ["unix_sockets", s.unixSockets]]) {
+        list.forEach((p, i) => {
+            if (!fs.existsSync(p))
+                notes.push(`info: sandbox.${key}[${i}] ${p} does not exist yet`);
+        });
+    }
+    return notes;
+}
 /** Can `agent` legitimately change this protected file? */
 export function mayEditProtected(project, agent, file) {
     return writePolicy(project, agent).allowFiles.includes(file);
 }
+const within = (parent, p) => p === parent || p.startsWith(parent.endsWith(path.sep) ? parent : parent + path.sep);
+/** Pure (spec 25.4.3): which canonical sandbox paths equal, sit inside or contain a protected path. Callers canonicalize. */
+export function sandboxPathConflicts(entries, protectedPaths) {
+    const out = [];
+    for (const e of entries) {
+        for (const pp of protectedPaths) {
+            const relation = e.path === pp.path ? "equal" : within(pp.path, e.path) ? "inside" : within(e.path, pp.path) ? "contains" : undefined;
+            if (relation)
+                out.push({ ...e, protectedPath: pp.path, reason: pp.reason, relation });
+        }
+    }
+    return out;
+}
+export const NETWORK_RANK = { none: 0, domains: 1, all: 2 };
+/** Without an OS sandbox nothing is applied, so every runtime is equal there. */
+export function sandboxCaps(agent, runtime = agent.runtime) {
+    const s = agent.sandbox;
+    const none = { network: "none", localBinding: false, unixSockets: false };
+    if (!s || !osSandboxAvailable())
+        return none;
+    if (runtime === "claude-code") {
+        return {
+            network: s.network.length ? "domains" : "none",
+            localBinding: s.localBinding && process.platform === "darwin",
+            unixSockets: s.unixSockets.length > 0,
+        };
+    }
+    return { ...none, network: s.network.length ? "all" : "none" };
+}
+/** Components in which `backup` applies more than `primary`, as `name: primary -> backup`. */
+export function sandboxCapExcess(primary, backup) {
+    const out = [];
+    if (NETWORK_RANK[backup.network] > NETWORK_RANK[primary.network])
+        out.push(`network: ${primary.network} -> ${backup.network}`);
+    if (backup.localBinding && !primary.localBinding)
+        out.push("local_binding: off -> on");
+    if (backup.unixSockets && !primary.unixSockets)
+        out.push("unix_sockets: off -> on");
+    return out;
+}

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). */