agent-lyceum 0.25.1 → 0.27.0

package/dist/mailbox.js

@@ -2,9 +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 } from "./fs-util.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";
@@ -38,14 +41,17 @@ export function ensureProjectDirs(project) {
     const handoff = sharedDir(project);
     if (handoff)
         fs.mkdirSync(handoff, { recursive: true });
-    for (const name of Object.keys(project.agents)) {
-        fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
-        fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });
-        const a = must(project.agents[name], `agent ${name}`);
-        for (const m of [a.memory.global, a.memory.project, a.memory.task])
-            if (m)
-                fs.mkdirSync(m, { recursive: true });
-    }
+    for (const name of Object.keys(project.agents))
+        ensureAgentDirs(project, name);
+}
+/** The mailbox and memory directories of one agent (a newly opened instance gets just its own). */
+export function ensureAgentDirs(project, name) {
+    fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
+    fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });
+    const a = must(project.agents[name], `agent ${name}`);
+    for (const m of [a.memory.global, a.memory.project, a.memory.task])
+        if (m)
+            fs.mkdirSync(m, { recursive: true });
 }
 /** Deliver a message into `to`'s inbox (dispatcher-side; senders other than agents allowed). */
 export function deliver(project, input) {
@@ -60,6 +66,7 @@ export function deliver(project, input) {
         subject: input.subject,
         created: input.created ?? new Date().toISOString(),
         ...(project.run?.layout === "run" ? { run_id: project.run.id } : {}),
+        ...(input.tier ? { tier: input.tier } : {}),
     };
     const file = path.join(inboxDir(project, input.to), input.fileName ?? `${stamp()}-${input.from}-${id}.md`);
     atomicWrite(file, serialize(meta, input.body));
@@ -70,7 +77,7 @@ export function deliver(project, input) {
  * the plan (id, file name, timestamp) is journaled before anything is written, a retry writes the identical file,
  * and mail the recipient already read is never written again. Without a run (no journal) it just delivers.
  */
-export function deliverOnce(project, journal, sourceKey, input) {
+export function deliverOnce(project, journal, sourceKey, input, extra = {}) {
     if (!journal)
         return { msg: deliver(project, input), fresh: true };
     const prior = journal.get(sourceKey, input.to);
@@ -81,14 +88,23 @@ export function deliverOnce(project, journal, sourceKey, input) {
             msg_id: deterministicId(sourceKey, input.to),
             file: `${stamp()}-${input.from}-${deterministicId(sourceKey, input.to)}.md`,
             created: new Date().toISOString(),
+            ...(extra.held ? { held: true } : {}),
+            ...(extra.parallel ? { parallel: true } : {}),
+            ...(extra.from ? { from: extra.from } : {}),
+            ...(extra.about ? { about: extra.about } : {}),
         });
     fault("route:intent");
-    const dest = path.join(inboxDir(project, input.to), planned.file);
+    // A replay goes where the first attempt was planned to go: the journal's `held`, not the current state of the run.
+    const held = planned.held === true;
+    const inbox = inboxDir(project, held ? roleOfName(project.agents, input.to) : input.to);
+    const dest = path.join(held ? path.join(inbox, PENDING_DIR) : inbox, planned.file);
     const meta = deliveredMeta(project, input, planned);
     const want = serialize(meta, input.body);
     const alreadyRead = fs.existsSync(path.join(path.dirname(dest), "read", planned.file));
+    // A held mail that was delivered (or assigned) may have been moved out of `pending/` already: it is never written again.
+    const settled = held && (planned.delivered || journal.assigned(planned.msg_id) !== undefined);
     // Write the planned file; if one is already there, verify it instead of trusting it. Mail already read is never written again.
-    if (!alreadyRead && (!fs.existsSync(dest) || fs.readFileSync(dest, "utf8") !== want))
+    if (!settled && !alreadyRead && (!fs.existsSync(dest) || fs.readFileSync(dest, "utf8") !== want))
         atomicWrite(dest, want);
     fault("route:written");
     const fresh = !planned.delivered;
@@ -97,6 +113,8 @@ export function deliverOnce(project, journal, sourceKey, input) {
     fault("route:delivered");
     return { msg: { meta, body: input.body, file: dest }, fresh };
 }
+/** Mail for a role that has instances waits here, in the role's inbox, until the assigner places it. */
+export const PENDING_DIR = "pending";
 function deliveredMeta(project, input, planned) {
     return {
         id: planned.msg_id,
@@ -108,6 +126,7 @@ function deliveredMeta(project, input, planned) {
         subject: input.subject,
         created: planned.created,
         ...(project.run?.layout === "run" ? { run_id: project.run.id } : {}),
+        ...(input.tier ? { tier: input.tier } : {}),
     };
 }
 export function readMessage(file) {
@@ -115,6 +134,14 @@ export function readMessage(file) {
     const meta = data;
     return { meta, body, file };
 }
+/** `readMessage` for files that may be anything (held mail): a symlink, FIFO or other non-regular entry throws instead of being followed or blocking. */
+export function readMessageNoFollow(file) {
+    const buf = readRegularFileNoFollow(file);
+    if (!buf)
+        throw new Error(`${file} is not a readable regular file`);
+    const { data, body } = parseRaw(buf.toString("utf8"));
+    return { meta: data, body, file };
+}
 /** Paths of the unread messages in an agent's inbox, oldest name first. Does not open them. */
 export function unreadFiles(project, agent) {
     const dir = inboxDir(project, agent);
@@ -176,12 +203,15 @@ 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) {
+function earlierDuplicate(project, from, to, type, replyTo, body, held = false, tier = "high") {
     const text = sameText(body);
     if (text.length < 20)
         return undefined;
     const dir = inboxDir(project, to);
-    for (const d of [dir, path.join(dir, "read")]) {
+    const role = roleOfName(project.agents, to);
+    const slots = held ? Object.values(project.agents).filter((a) => roleOfName(project.agents, a.name) === role).map((a) => inboxDir(project, a.name)) : [dir];
+    const dirs = held ? [...slots.flatMap((d) => [d, path.join(d, "read")]), path.join(inboxDir(project, role), PENDING_DIR)] : [dir, path.join(dir, "read")];
+    for (const d of dirs) {
         if (!fs.existsSync(d))
             continue;
         for (const e of fs.readdirSync(d, { withFileTypes: true })) {
@@ -189,7 +219,7 @@ function earlierDuplicate(project, from, to, type, replyTo, body) {
                 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 {
@@ -200,8 +230,8 @@ function earlierDuplicate(project, from, to, type, replyTo, body) {
     return undefined;
 }
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
-export function routeOutboxes(project) {
-    const res = { delivered: [], rejected: [], warnings: [], asks: [] };
+export function routeOutboxes(project, routing) {
+    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);
@@ -214,14 +244,15 @@ export function routeOutboxes(project) {
             .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);
@@ -276,7 +307,15 @@ export function routeOutboxes(project) {
                 reject(`missing "to".`);
                 continue;
             }
-            const bad = targets.find((t) => !project.agents[t] || t === sender.name || (sender.canMessage !== "all" && !sender.canMessage.includes(t)));
+            const roleOf = (n) => roleOfName(project.agents, n);
+            if (sender.instance) {
+                const same = targets.find((t) => t !== sender.name && roleOf(t) === roleOf(sender.name));
+                if (same !== undefined) {
+                    reject(`cannot message another instance of your own role ("${same}" is an instance of "${roleOf(sender.name)}"). Put what it needs in your reply to the lead.`);
+                    continue;
+                }
+            }
+            const bad = targets.find((t) => !project.agents[t] || t === sender.name || (sender.canMessage !== "all" && !sender.canMessage.includes(roleOf(t))));
             if (bad !== undefined) {
                 const why = !project.agents[bad]
                     ? `no such agent "${bad}"`
@@ -286,6 +325,30 @@ export function routeOutboxes(project) {
                 reject(why + ".");
                 continue;
             }
+            // `parallel` is read here from the outbox file, but only a verdict on it is kept: it goes to the journal (never back into the mail).
+            const flags = new Map();
+            if (routing && d.parallel !== undefined) {
+                for (const t of targets) {
+                    const role = roleOf(t);
+                    flags.set(t, parallelFlag({ value: d.parallel, senderIsLead: sender.name === project.lead, type, replyTo: d.reply_to, thread: d.thread, cap: routing.cap(role) }));
+                }
+                if ([...flags.values()].includes("invalid")) {
+                    reject(`parallel must be true or false (YAML boolean), not ${JSON.stringify(d.parallel)}. Write \`parallel: true\` on a new task to run it in a parallel instance, or leave the line out.`);
+                    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);
@@ -302,7 +365,7 @@ export function routeOutboxes(project) {
             for (const to of targets) {
                 if (journal?.get(source, to))
                     continue;
-                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body);
+                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body, !!routing?.held(roleOf(to)), tierOf(to) ?? "high");
                 if (earlier)
                     repeats.set(to, earlier);
             }
@@ -310,18 +373,25 @@ export function routeOutboxes(project) {
                 .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;
@@ -333,7 +403,22 @@ export function routeOutboxes(project) {
             for (const to of targets) {
                 if (repeats.has(to))
                     continue;
-                const { msg, fresh } = deliverOnce(project, journal, source, { from: sender.name, to, type, subject, body, thread, reply_to: replyTo });
+                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, ...(tierOf(to) ? { tier: tierOf(to) } : {}) }, {
+                    ...(held ? { held: true } : {}),
+                    ...(held && flag === "on" ? { parallel: true } : {}),
+                    ...(routing?.held(roleOf(sender.name)) ? { from: sender.name } : {}),
+                });
                 if (!fresh)
                     continue;
                 res.delivered.push({ from: sender.name, to, id: msg.meta.id, file: msg.file, type, subject });

package/dist/message-store.d.ts

@@ -9,15 +9,61 @@ export interface JournalEntry {
     file: string;
     created: string;
     delivered: boolean;
+    /** Same-role instances (spec 23): the mail waits in `inbox/<role>/pending/` for the assigner. Only written for an activated role. */
+    held?: true;
+    /** The lead marked it `parallel: true` (read only from here, never from the mail file). */
+    parallel?: true;
+    /** The instance of an activated role that sent it. */
+    from?: string;
+    /** The instance a dispatcher notice is about. */
+    about?: string;
+    /** Position of the intent among the journal's records (a line cut short by a crash does not count). */
+    seq?: number;
+}
+/** What the journal knows about one message id: where the assigner put it, who sent it or what it is about, and its delivery line. */
+export interface Ownership {
+    assign?: string;
+    from?: string;
+    about?: string;
+    intent?: {
+        seq: number;
+        to: string;
+        file: string;
+        source: string;
+        msg_id: string;
+    };
 }
 /** Append-only log of deliveries. A delivery is identified by `(source, recipient)`, never by a random id. */
 export declare class RouteJournal {
     private readonly file;
     private readonly entries;
+    private readonly byMsg;
+    private readonly byFileName;
+    private readonly assigns;
+    private readonly firstHeldSeq;
+    private seqNext;
     constructor(runDir: string);
+    /** Enter an intent in every index; `seq` is its position among the records read or appended. */
+    private index;
     get(source: string, to: string): JournalEntry | undefined;
     private append;
-    intent(e: Omit<JournalEntry, "delivered">): JournalEntry;
+    intent(e: Omit<JournalEntry, "delivered" | "seq">): JournalEntry;
+    /** The assigner's decision for a held mail, made durable before the file moves (spec 23.7.2). */
+    assign(a: {
+        msg_id: string;
+        file: string;
+        role: string;
+        slot: string;
+    }): void;
+    assigned(msgId: string): {
+        slot: string;
+        file: string;
+        role: string;
+    } | undefined;
+    byFile(file: string): JournalEntry | undefined;
+    /** Position of the first held intent addressed to `name`; undefined when there is none. */
+    firstHeld(name: string): number | undefined;
+    ownership(msgId: string): Ownership | undefined;
     delivered(source: string, to: string): void;
 }
 /** Stable id of one outbox file instance: who wrote it, its name, when, and what it said. */

package/dist/message-store.js

@@ -15,6 +15,11 @@ export const mailDir = (runDir) => path.join(runDir, "mail");
 export class RouteJournal {
     file;
     entries = new Map();
+    byMsg = new Map();
+    byFileName = new Map();
+    assigns = new Map();
+    firstHeldSeq = new Map();
+    seqNext = 0;
     constructor(runDir) {
         this.file = path.join(mailDir(runDir), "journal.jsonl");
         let text = "";
@@ -30,27 +35,65 @@ export class RouteJournal {
             try {
                 const j = JSON.parse(line);
                 const key = `${j.source}\u0000${j.to}`;
-                if (j.t === "intent")
-                    this.entries.set(key, { source: j.source, to: j.to, msg_id: j.msg_id, file: j.file, created: j.created, delivered: false });
+                if (j.t === "intent") {
+                    this.index({
+                        source: j.source,
+                        to: j.to,
+                        msg_id: j.msg_id,
+                        file: j.file,
+                        created: j.created,
+                        delivered: false,
+                        ...(j.held === true ? { held: true } : {}),
+                        ...(j.parallel === true ? { parallel: true } : {}),
+                        ...(typeof j.from === "string" ? { from: j.from } : {}),
+                        ...(typeof j.about === "string" ? { about: j.about } : {}),
+                    });
+                }
                 else if (j.t === "delivered") {
                     const e = this.entries.get(key);
                     if (e)
                         e.delivered = true;
                 }
+                else if (j.t === "assign" && typeof j.msg_id === "string" && typeof j.slot === "string") {
+                    this.assigns.set(j.msg_id, { slot: j.slot, file: String(j.file), role: String(j.role) });
+                }
             }
             catch {
                 /* a line cut short by a crash: ignore it */
             }
         }
     }
+    /** Enter an intent in every index; `seq` is its position among the records read or appended. */
+    index(e) {
+        e.seq = this.seqNext++;
+        this.entries.set(`${e.source}\u0000${e.to}`, e);
+        this.byMsg.set(e.msg_id, e);
+        this.byFileName.set(e.file, e);
+        if (e.held && !this.firstHeldSeq.has(e.to))
+            this.firstHeldSeq.set(e.to, e.seq);
+        return e;
+    }
     get(source, to) {
         return this.entries.get(`${source}\u0000${to}`);
     }
     append(obj) {
         fs.mkdirSync(path.dirname(this.file), { recursive: true });
-        const fd = fs.openSync(this.file, "a");
+        const fd = fs.openSync(this.file, "a+");
         try {
-            fs.writeSync(fd, JSON.stringify(obj) + "\n");
+            let text = `${JSON.stringify(obj)}\n`;
+            // A crash or a short write can leave the last line without its newline; appending straight after it would glue the two into one
+            // unreadable line. The real tail is read on every append (one byte), so no cached check can go stale, even with another writer.
+            const size = fs.fstatSync(fd).size;
+            if (size > 0) {
+                const last = Buffer.alloc(1);
+                fs.readSync(fd, last, 0, 1, size - 1);
+                if (last[0] !== 0x0a)
+                    text = `\n${text}`;
+            }
+            const bytes = Buffer.from(text);
+            const written = fs.writeSync(fd, bytes);
+            if (written < bytes.length)
+                throw new Error(`Short write to ${this.file}: ${written} of ${bytes.length} bytes (disk full?). Resume the run after freeing space.`);
             fs.fsyncSync(fd);
         }
         finally {
@@ -59,9 +102,34 @@ export class RouteJournal {
     }
     intent(e) {
         this.append({ t: "intent", ...e });
-        const entry = { ...e, delivered: false };
-        this.entries.set(`${e.source}\u0000${e.to}`, entry);
-        return entry;
+        return this.index({ ...e, delivered: false });
+    }
+    /** The assigner's decision for a held mail, made durable before the file moves (spec 23.7.2). */
+    assign(a) {
+        this.append({ t: "assign", ...a });
+        this.assigns.set(a.msg_id, { slot: a.slot, file: a.file, role: a.role });
+    }
+    assigned(msgId) {
+        return this.assigns.get(msgId);
+    }
+    byFile(file) {
+        return this.byFileName.get(file);
+    }
+    /** Position of the first held intent addressed to `name`; undefined when there is none. */
+    firstHeld(name) {
+        return this.firstHeldSeq.get(name);
+    }
+    ownership(msgId) {
+        const intent = this.byMsg.get(msgId);
+        const assign = this.assigns.get(msgId)?.slot;
+        if (!intent && assign === undefined)
+            return undefined;
+        return {
+            ...(assign !== undefined ? { assign } : {}),
+            ...(intent?.from ? { from: intent.from } : {}),
+            ...(intent?.about ? { about: intent.about } : {}),
+            ...(intent ? { intent: { seq: intent.seq, to: intent.to, file: intent.file, source: intent.source, msg_id: intent.msg_id } } : {}),
+        };
     }
     delivered(source, to) {
         this.append({ t: "delivered", source, to });

package/dist/paths.d.ts

@@ -23,5 +23,12 @@ 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;
+/**
+ * `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
+ * yet (a directory about to be made) still compares equal to the same place reached through a symlink.
+ */
+export declare function canonicalPath(p: string): string;

package/dist/paths.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 export const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
@@ -43,8 +44,32 @@ 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.startsWith("..") && !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
+ * yet (a directory about to be made) still compares equal to the same place reached through a symlink.
+ */
+export function canonicalPath(p) {
+    const abs = path.resolve(p);
+    const rest = [];
+    let head = abs;
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(head), ...rest);
+        }
+        catch {
+            const up = path.dirname(head);
+            if (up === head)
+                return abs;
+            rest.unshift(path.basename(head));
+            head = up;
+        }
+    }
 }

package/dist/policy.d.ts

@@ -44,6 +44,7 @@ export declare const scratchCwd: (workDir: string) => string;
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export declare function repoDirFor(project: ResolvedProject, agent: string): string;
 export declare function writePolicy(project: ResolvedProject, agent: ResolvedAgent): WritePolicy;
+export declare function osSandboxAvailable(): boolean;
 /** Test seam: pretend the OS sandbox is (un)available; `undefined` re-probes the host. */
 export declare function setOsSandboxForTest(available: boolean | undefined): void;
 export declare function enforcementFor(project: ResolvedProject, agent: ResolvedAgent): AgentEnforcement;

package/dist/policy.js

@@ -136,13 +136,13 @@ export function writePolicy(project, agent) {
         deny.push(path.join(ws.root, ".git"), ...["commondir", "config.worktree", "gitdir"].map((f) => path.join(ws.gitDir, f)));
     return {
         allowDirs,
-        readDirs: [...(shared && !mayWriteShared ? [shared] : []), ...(isLead ? [] : [recordsDir(project)])],
+        readDirs: [...(shared && !mayWriteShared ? [shared] : []), ...(isLead ? [] : [recordsDir(project)]), ...Object.values(agent.sharedMemory ?? {})],
         allowFiles,
         deny: [...new Set(deny)],
     };
 }
 let sandboxProbe;
-function osSandboxAvailable() {
+export function osSandboxAvailable() {
     if (sandboxProbe !== undefined)
         return sandboxProbe;
     if (process.platform === "darwin")

package/dist/prompt.d.ts

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