agent-lyceum 0.22.0 → 0.24.0

package/dist/memory-tidy.js

@@ -5,8 +5,9 @@ import path from "node:path";
 import { realInvoker } from "./adapters/index.js";
 import { atomicWrite } from "./fs-util.js";
 import { ensureProjectDirs } from "./mailbox.js";
-import { memoryDirs } from "./policy.js";
+import { commonFile, memoryDirs, recordsDir, repoDirFor, writePolicy } from "./policy.js";
 import { buildTidyPrompts, MEMORY_INDEX_LIMIT } from "./prompt.js";
+import { activeRecordsBytes, effectiveActive, listRecords, RECORD_KINDS, RECORDS_BUDGET } from "./records.js";
 import { git, isGitRepo } from "./worktree.js";
 export const ARCHIVE_DIR = ".archive";
 export const TIDY_STATE_FILE = ".tidy-state.json";
@@ -76,6 +77,10 @@ export function fingerprint(dir) {
         out[f.rel] = crypto.createHash("sha256").update(fs.readFileSync(path.join(dir, f.rel))).digest("hex");
     return out;
 }
+/** The content hashes of every earlier tidy's archive in `dir` (not this tidy's own folder), which no tidy may touch. */
+function earlierArchives(dir, stamp) {
+    return Object.fromEntries(Object.entries(fingerprint(dir)).filter(([rel]) => rel.startsWith(`${ARCHIVE_DIR}/`) && !rel.startsWith(`${ARCHIVE_DIR}/${stamp}/`)));
+}
 const slot = (into, i) => path.join(into, String(i));
 /** Copy each directory aside (a directory that does not exist is remembered as absent). */
 export function snapshotDirs(dirs, into) {
@@ -199,34 +204,97 @@ function describeTarget(t, project, say) {
     for (const m of findMissingPaths(t.dir, t.layer === "project" ? project.dir : undefined))
         say(`  missing path: ${m.path} (in ${m.file})`);
 }
-async function tidyOne(o, t, stamp) {
+/** The live files of the project records (the archive is not listed). */
+const liveRecordFiles = (project) => (isPlainDir(recordsDir(project)) ? listMemoryFiles(recordsDir(project)).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`)) : []);
+function isPlainDir(p) {
+    try {
+        return fs.lstatSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function describeRecords(project, say) {
+    const live = liveRecordFiles(project);
+    const bytes = live.reduce((n, f) => n + f.bytes, 0);
+    const active = RECORD_KINDS.map((k) => `${k} ${effectiveActive(listRecords(project, k)).length}`).join(", ");
+    say(`records ${recordsDir(project)}: ${live.length} file(s), ${kb(bytes)}; active: ${active}`);
+}
+/** The lead's wake-up also tidies the project records, in a default project-layer tidy or with `--agent <lead>`. */
+const recordsInScope = (o) => o.layer === "project" && (!o.agent || o.agent === o.project.lead);
+function recordsContext(project, archiveDir, live) {
+    const dir = recordsDir(project);
+    const entries = [];
+    const known = new Set();
+    for (const kind of RECORD_KINDS)
+        for (const r of listRecords(project, kind)) {
+            const rel = `${kind}/${path.basename(r.file)}`;
+            known.add(rel);
+            entries.push({ kind, id: r.id, rel, status: r.status, date: r.date, bytes: live.find((f) => f.rel === rel)?.bytes ?? 0, title: r.title, invalid: r.invalid });
+        }
+    return { dir, archiveDir, entries, otherFiles: live.filter((f) => !known.has(f.rel)) };
+}
+const hasReport = (archiveDir) => {
+    const f = path.join(archiveDir, TIDY_REPORT_FILE);
+    return fs.existsSync(f) && fs.readFileSync(f, "utf8").trim() !== "";
+};
+/** Tidy one agent's memory directory (`dir`, if it has files) and, for the lead, the project records, in one wake-up. */
+async function tidyOne(o, t, stamp, withRecords) {
     const { project } = o;
     const say = o.say ?? ((s) => console.log(s));
-    const base = { agent: t.agent, layer: t.layer, dir: t.dir };
+    const base = { agent: t.agent, layer: t.layer, dir: t.dir ?? recordsDir(project) };
     const agent = project.agents[t.agent];
-    const live = listMemoryFiles(t.dir).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`));
-    if (live.length === 0)
+    const live = t.dir ? listMemoryFiles(t.dir).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`)) : [];
+    const recLive = withRecords ? liveRecordFiles(project) : [];
+    const memPart = live.length > 0;
+    const recPart = recLive.length > 0;
+    if (!memPart && !recPart)
         return { ...base, status: "skipped", problems: ["no memory files: nothing to tidy"] };
-    const dirs = memoryDirs(agent);
-    const others = dirs.filter((d) => d !== t.dir);
-    const before = listMemoryFiles(t.dir).map((f) => f.rel);
+    const recDir = recordsDir(project);
+    const dirs = [...memoryDirs(agent), ...(recPart ? [recDir] : [])];
+    const others = dirs.filter((d) => d !== t.dir && d !== recDir);
+    const before = t.dir && memPart ? listMemoryFiles(t.dir).map((f) => f.rel) : [];
+    const recBefore = recPart ? listMemoryFiles(recDir).map((f) => f.rel) : [];
+    const watched = [commonFile(project)].filter((f) => fs.existsSync(f));
+    const watchedBefore = watched.map((f) => fs.readFileSync(f, "utf8"));
     const othersBefore = others.map((d) => fingerprint(d));
-    const archiveDir = path.join(t.dir, ARCHIVE_DIR, stamp);
+    const archivesBefore = { mem: t.dir && memPart ? earlierArchives(t.dir, stamp) : {}, rec: recPart ? earlierArchives(recDir, stamp) : {} };
+    const archiveDir = t.dir ? path.join(t.dir, ARCHIVE_DIR, stamp) : undefined;
+    const recArchive = path.join(recDir, ARCHIVE_DIR, stamp);
     const workDir = tidyWorkDir(project, stamp, t.agent);
     const snapshot = path.join(workDir, "snapshot");
-    const state = readTidyState(t.dir);
-    const changes = t.layer === "project" ? projectChanges(project.dir, state?.head) : undefined;
-    const missing = findMissingPaths(t.dir, t.layer === "project" ? project.dir : undefined);
-    const index = fs.existsSync(path.join(t.dir, "MEMORY.md")) ? fs.readFileSync(path.join(t.dir, "MEMORY.md"), "utf8") : "";
-    const prompts = buildTidyPrompts(agent, { layer: t.layer, dir: t.dir, archiveDir, files: live, index, changes, missing });
+    const state = t.dir ? readTidyState(t.dir) : undefined;
+    const changes = memPart && t.layer === "project" ? projectChanges(project.dir, state?.head) : undefined;
+    const missing = memPart && t.dir ? findMissingPaths(t.dir, t.layer === "project" ? project.dir : undefined) : [];
+    const index = t.dir && fs.existsSync(path.join(t.dir, "MEMORY.md")) ? fs.readFileSync(path.join(t.dir, "MEMORY.md"), "utf8") : "";
+    const prompts = buildTidyPrompts(agent, {
+        layer: t.layer,
+        ...(memPart ? { dir: t.dir, archiveDir } : {}),
+        files: live,
+        index,
+        changes,
+        missing,
+        ...(recPart ? { records: recordsContext(project, recArchive, recLive) } : {}),
+    });
     ensureProjectDirs(project);
     snapshotDirs(dirs, snapshot);
     const fail = (problems) => {
         restoreDirs(dirs, snapshot);
+        for (const [i, f] of watched.entries())
+            atomicWrite(f, watchedBefore[i]);
         fs.rmSync(snapshot, { recursive: true, force: true });
-        return { ...base, status: "failed", problems };
+        return { ...base, status: "failed", ...(recPart ? { recordsDir: recDir } : {}), problems };
+    };
+    // The runtime may write only the directories being tidied (and read what it could read before): not the repo, outbox or shared files.
+    const normal = writePolicy(project, agent);
+    const allowDirs = [...(memPart && t.dir ? [t.dir] : []), ...(recPart ? [recDir] : [])];
+    const policy = {
+        allowDirs,
+        allowFiles: [],
+        readDirs: [...new Set([repoDirFor(project, t.agent), ...normal.readDirs, ...normal.allowDirs.filter((d) => !allowDirs.includes(d)), ...normal.allowFiles.map((f) => path.dirname(f))])],
+        deny: normal.deny,
     };
-    say(`tidying ${t.layer} memory of ${t.agent} (${live.length} file(s)) …`);
+    say(`tidying ${t.layer} memory of ${t.agent} (${live.length} file(s)${recPart ? `, ${recLive.length} project record file(s)` : ""}) …`);
     const invoke = o.invoker ?? realInvoker;
     const result = await invoke({
         project,
@@ -237,36 +305,76 @@ async function tidyOne(o, t, stamp) {
         timeoutSec: project.dispatcher.wake_timeout_sec,
         signal: o.signal,
         logDir: path.join(workDir, "log"),
+        policy,
     }).catch((e) => ({ ok: false, text: "", exitCode: null, timedOut: false, error: e.message }));
     if (!result.ok)
         return fail([`the wake-up failed: ${result.error ?? "unknown error"}`]);
-    const problems = [];
-    others.forEach((d, i) => {
-        if (JSON.stringify(fingerprint(d)) !== JSON.stringify(othersBefore[i]))
-            problems.push(`the agent changed ${d}, which is not the ${t.layer} memory being tidied`);
-    });
-    problems.push(...verifyConservation(before, t.dir, stamp));
-    const reportFile = path.join(archiveDir, TIDY_REPORT_FILE);
-    if (!fs.existsSync(reportFile) || fs.readFileSync(reportFile, "utf8").trim() === "")
-        problems.push(`${ARCHIVE_DIR}/${stamp}/${TIDY_REPORT_FILE} is missing or empty`);
+    // Anything that throws from here on (a report path that is a directory, a state file that cannot be written) is a failed tidy that is rolled back.
+    let problems = [];
+    try {
+        others.forEach((d, i) => {
+            if (JSON.stringify(fingerprint(d)) !== JSON.stringify(othersBefore[i]))
+                problems.push(`the agent changed ${d}, which is not the ${t.layer} memory being tidied`);
+        });
+        watched.forEach((f, i) => {
+            if (!fs.existsSync(f) || fs.readFileSync(f, "utf8") !== watchedBefore[i])
+                problems.push(`the agent changed ${f}, which a tidy may not touch`);
+        });
+        if (memPart && t.dir && archiveDir) {
+            if (JSON.stringify(earlierArchives(t.dir, stamp)) !== JSON.stringify(archivesBefore.mem))
+                problems.push(`the agent changed an earlier archive under ${path.join(t.dir, ARCHIVE_DIR)}`);
+            problems.push(...verifyConservation(before, t.dir, stamp));
+            if (!hasReport(archiveDir))
+                problems.push(`${ARCHIVE_DIR}/${stamp}/${TIDY_REPORT_FILE} is missing or empty`);
+        }
+        if (recPart) {
+            if (JSON.stringify(earlierArchives(recDir, stamp)) !== JSON.stringify(archivesBefore.rec))
+                problems.push(`project records: the agent changed an earlier archive under ${path.join(recDir, ARCHIVE_DIR)}`);
+            problems.push(...verifyConservation(recBefore, recDir, stamp).map((p) => `project records: ${p}`));
+            if (!hasReport(recArchive))
+                problems.push(`project records: ${ARCHIVE_DIR}/${stamp}/${TIDY_REPORT_FILE} is missing or empty`);
+        }
+        if (!problems.length && memPart && t.dir)
+            writeTidyState(t.dir, { ...(changes?.head ? { head: changes.head } : {}), at: (o.now?.() ?? new Date()).toISOString(), archive: stamp });
+    }
+    catch (e) {
+        problems = [...problems, `the tidy could not be checked or finished: ${e.message}`];
+    }
     if (problems.length)
         return fail(problems);
     fs.rmSync(snapshot, { recursive: true, force: true });
-    writeTidyState(t.dir, { ...(changes?.head ? { head: changes.head } : {}), at: (o.now?.() ?? new Date()).toISOString(), archive: stamp });
-    return { ...base, status: "tidied", archive: stamp, problems: [] };
+    return { ...base, status: "tidied", archive: stamp, ...(recPart ? { recordsDir: recDir } : {}), problems: [] };
 }
 /** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum tidy`). */
 export async function tidyMemory(o) {
     const say = o.say ?? ((s) => console.log(s));
-    const targets = targetsFor(o.project, { layer: o.layer, agent: o.agent });
+    const withRecords = recordsInScope(o) && liveRecordFiles(o.project).length > 0;
+    const lead = o.project.lead;
+    let targets;
+    try {
+        targets = targetsFor(o.project, { layer: o.layer, agent: o.agent });
+    }
+    catch (e) {
+        // `--agent <lead>` with no project memory directory is fine when there are records to tidy.
+        if (!(withRecords && o.agent === lead && o.project.agents[lead]))
+            throw e;
+        targets = [];
+    }
     const results = [];
-    for (const t of targets) {
+    const stamp = tidyStamp(o.now?.()); // one per tidy, for every agent
+    const jobs = targets.map((t) => ({ ...t }));
+    if (withRecords && !jobs.some((j) => j.agent === lead))
+        jobs.push({ agent: lead, layer: o.layer, dir: undefined });
+    for (const j of jobs) {
         if (o.dryRun) {
-            describeTarget(t, o.project, say);
-            results.push({ agent: t.agent, layer: t.layer, dir: t.dir, status: "dry-run", problems: [] });
+            if (j.dir)
+                describeTarget(j, o.project, say);
+            if (withRecords && j.agent === lead)
+                describeRecords(o.project, say);
+            results.push({ agent: j.agent, layer: j.layer, dir: j.dir ?? recordsDir(o.project), status: "dry-run", problems: [] });
             continue;
         }
-        const r = await tidyOne(o, t, tidyStamp(o.now?.()));
+        const r = await tidyOne(o, j, stamp, withRecords && j.agent === lead);
         results.push(r);
         if (o.signal?.aborted)
             break;
@@ -289,20 +397,13 @@ function pruneEmpty(dir, stop) {
         fs.rmdirSync(d);
     }
 }
-/** Move the files of one tidy's archive back to where they were. Nothing that exists now is overwritten. */
-export function restoreMemory(o) {
-    if (!STAMP_RE.test(o.stamp))
-        throw new Error(`"${o.stamp}" is not an archive stamp (expected something like 20261008T031500Z).`);
-    const [t] = targetsFor(o.project, { layer: o.layer, agent: o.agent });
-    const archive = path.join(t.dir, ARCHIVE_DIR, o.stamp);
-    if (!fs.existsSync(archive))
-        throw new Error(`No archive ${o.stamp} for ${o.agent} (${o.layer}). Archives: ${listArchives(t.dir).join(", ") || "(none)"}.`);
+/** Move the files of `archive` back under `dir`. Nothing that exists now is overwritten. */
+function moveBack(dir, archive) {
     const restored = [];
     const skipped = [];
-    const inArchive = listMemoryFiles(archive).filter((f) => f.rel !== TIDY_REPORT_FILE);
-    for (const f of inArchive) {
+    for (const f of listMemoryFiles(archive).filter((f) => f.rel !== TIDY_REPORT_FILE)) {
         const from = path.join(archive, f.rel);
-        const to = path.join(t.dir, f.rel);
+        const to = path.join(dir, f.rel);
         if (fs.existsSync(to)) {
             skipped.push({ rel: f.rel, reason: "a file with this name exists now; it was not overwritten" });
             continue;
@@ -312,13 +413,43 @@ export function restoreMemory(o) {
         pruneEmpty(path.dirname(from), archive);
         restored.push(f.rel);
     }
-    const indexFile = path.join(t.dir, "MEMORY.md");
-    const index = fs.existsSync(indexFile) ? fs.readFileSync(indexFile, "utf8") : "";
-    const add = restored.filter((rel) => rel.endsWith(".md") && !index.includes(rel)).map((rel) => `- [${titleOf(path.join(t.dir, rel), rel)}](${rel}) — restored from tidy ${o.stamp}`);
-    if (add.length)
-        atomicWrite(indexFile, `${index.replace(/\n*$/, index ? "\n" : "")}${add.join("\n")}\n`);
     return { restored, skipped };
 }
+/**
+ * Move the files of one tidy's archive back to where they were. Nothing that exists now is overwritten.
+ * For the lead on the project layer this covers the project records archive of the same stamp too; either archive may be the only one.
+ */
+export function restoreMemory(o) {
+    if (!STAMP_RE.test(o.stamp))
+        throw new Error(`"${o.stamp}" is not an archive stamp (expected something like 20261008T031500Z).`);
+    const isLead = o.layer === "project" && o.agent === o.project.lead;
+    const recDir = recordsDir(o.project);
+    const recArchive = path.join(recDir, ARCHIVE_DIR, o.stamp);
+    const recHas = isLead && isPlainDir(recDir) && fs.existsSync(recArchive);
+    let dir;
+    try {
+        dir = targetsFor(o.project, { layer: o.layer, agent: o.agent })[0].dir;
+    }
+    catch (e) {
+        if (!(isLead && o.project.agents[o.agent]))
+            throw e;
+    }
+    const archive = dir ? path.join(dir, ARCHIVE_DIR, o.stamp) : undefined;
+    const memHas = !!archive && fs.existsSync(archive);
+    if (!memHas && !recHas) {
+        const recs = isLead ? `${dir ? "; project records archives: " : " Project records archives: "}${listArchives(recDir).join(", ") || "(none)"}` : "";
+        throw new Error(`No archive ${o.stamp} for ${o.agent} (${o.layer}).${dir ? ` Archives: ${listArchives(dir).join(", ") || "(none)"}` : ""}${recs}.`);
+    }
+    const mem = dir && memHas ? moveBack(dir, archive) : { restored: [], skipped: [] };
+    if (dir && memHas) {
+        const indexFile = path.join(dir, "MEMORY.md");
+        const index = fs.existsSync(indexFile) ? fs.readFileSync(indexFile, "utf8") : "";
+        const add = mem.restored.filter((rel) => rel.endsWith(".md") && !index.includes(rel)).map((rel) => `- [${titleOf(path.join(dir, rel), rel)}](${rel}) — restored from tidy ${o.stamp}`);
+        if (add.length)
+            atomicWrite(indexFile, `${index.replace(/\n*$/, index ? "\n" : "")}${add.join("\n")}\n`);
+    }
+    return { ...mem, ...(recHas ? { records: moveBack(recDir, recArchive) } : {}) };
+}
 /** The stamps of the archives in a memory directory, oldest first. */
 export function listArchives(dir) {
     try {
@@ -347,5 +478,10 @@ export function tidyAdvice(project) {
         if (Number.isFinite(n) && n >= ADVICE_COMMITS)
             out.push({ agent: t.agent, reason: `${n} commits since the last tidy` });
     }
+    for (const kind of RECORD_KINDS) {
+        const bytes = activeRecordsBytes(project, kind);
+        if (bytes > RECORDS_BUDGET)
+            out.push({ agent: project.lead, reason: `active ${kind} records are ${bytes} bytes, more than the ${RECORDS_BUDGET} an agent is shown (\`done\` is refused while over)` });
+    }
     return out;
 }

package/dist/message-store.js

@@ -158,10 +158,30 @@ export function listAttempts(runDir) {
     }
     return out;
 }
+/**
+ * One more than the highest number any entry under `attempts/` already uses for this claim. Only names count (a damaged JSON or a
+ * bare folder still holds its number), because a new attempt's paths come from the name and a rename would overwrite them.
+ */
+function nextAttemptNumber(runDir, claimId) {
+    const dir = path.join(mailDir(runDir), "attempts");
+    const re = new RegExp(`^${claimId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-a(\\d+)(\\.json)?$`);
+    let max = 0;
+    if (fs.existsSync(dir)) {
+        for (const name of fs.readdirSync(dir)) {
+            const m = re.exec(name);
+            const used = m ? Number(m[1]) : 0;
+            if (Number.isSafeInteger(used) && used > max)
+                max = used;
+        }
+    }
+    if (!Number.isSafeInteger(max + 1))
+        throw new Error(`attempt numbers exhausted for claim ${claimId} (highest used: ${max}) in ${dir}`);
+    return max + 1;
+}
 /** Start the next attempt for a claim (a1, a2, ...). */
 export function beginAttempt(runDir, claimId) {
     const claim = loadClaim(runDir, claimId);
-    const n = listAttempts(runDir).filter((a) => a.claim_id === claimId).length + 1;
+    const n = nextAttemptNumber(runDir, claimId);
     const rec = { id: `${claimId}-a${n}`, claim_id: claimId, agent: claim.agent, n, status: "started", started_at: new Date().toISOString() };
     saveAttempt(runDir, rec);
     return rec;
@@ -182,6 +202,7 @@ export function parkOutbox(runDir, outbox, attemptId) {
             continue;
         fs.mkdirSync(dest, { recursive: true });
         fs.renameSync(path.join(outbox, e.name), path.join(dest, e.name));
+        fault("park:moved");
         moved.push(e.name);
     }
     return moved;

package/dist/paths.d.ts

@@ -16,7 +16,6 @@ export interface ProjectPaths {
     config: string;
     agentsDir: string;
     shared: string;
-    common: string;
     inboxRoot: string;
     outboxRoot: string;
     runs: string;

package/dist/paths.js

@@ -37,7 +37,6 @@ export function projectPaths(home, project) {
         config: path.join(root, "project.yaml"),
         agentsDir: path.join(root, "agents"),
         shared,
-        common: path.join(shared, "COMMON.md"),
         inboxRoot: path.join(shared, "inbox"),
         outboxRoot: path.join(shared, "outbox"),
         runs: path.join(root, "runs"),

package/dist/policy.d.ts

@@ -23,11 +23,9 @@ export interface WritePolicy {
     deny: string[];
 }
 export declare function commonFile(project: ResolvedProject): string;
-/** Durable decisions and lessons of the project, kept next to COMMON.md: the lead writes them, everyone else reads them. */
-export declare function decisionsFile(project: ResolvedProject): string;
-export declare function lessonsFile(project: ResolvedProject): string;
-/** Where the lead moves entries that no longer fit under the prompt cap; read on demand, never injected. */
-export declare function archiveFile(file: string): string;
+/** Durable decisions and lessons of the project, one file per entry: the lead writes them, everyone else reads them. `.archive/` is tidy's output, never shown in prompts. */
+export declare function recordsDir(project: ResolvedProject): string;
+export declare function recordsKindDir(project: ResolvedProject, kind: "decisions" | "lessons"): string;
 /** The lead-maintained files shared by every run of the project. */
 export declare function sharedContextFiles(project: ResolvedProject): string[];
 export declare function outboxDir(project: ResolvedProject, agent: string): string;
@@ -41,6 +39,8 @@ export declare const SHARED_DIR = "_shared";
 export declare function sharedDir(project: ResolvedProject): string | undefined;
 /** The index of the handoff notes: the one file shown in prompts, and the one the guard watches. */
 export declare function sharedIndex(project: ResolvedProject): string | undefined;
+/** The working directory of a wake-up that runs under a policy override: an empty dir, so nothing of the repo is writable by default. */
+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;

package/dist/policy.js

@@ -4,21 +4,16 @@ import { findOnPath } from "./fs-util.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
 }
-/** Durable decisions and lessons of the project, kept next to COMMON.md: the lead writes them, everyone else reads them. */
-export function decisionsFile(project) {
-    return path.join(project.paths.shared, "common", "DECISIONS.md");
+/** Durable decisions and lessons of the project, one file per entry: the lead writes them, everyone else reads them. `.archive/` is tidy's output, never shown in prompts. */
+export function recordsDir(project) {
+    return path.join(project.paths.shared, "common", "records");
 }
-export function lessonsFile(project) {
-    return path.join(project.paths.shared, "common", "LESSONS.md");
-}
-/** Where the lead moves entries that no longer fit under the prompt cap; read on demand, never injected. */
-export function archiveFile(file) {
-    return file.replace(/\.md$/, "_ARCHIVE.md");
+export function recordsKindDir(project, kind) {
+    return path.join(recordsDir(project), kind);
 }
 /** The lead-maintained files shared by every run of the project. */
 export function sharedContextFiles(project) {
-    const [d, l] = [decisionsFile(project), lessonsFile(project)];
-    return [commonFile(project), d, l, archiveFile(d), archiveFile(l)];
+    return [commonFile(project)];
 }
 export function outboxDir(project, agent) {
     return path.join(project.paths.outboxRoot, agent);
@@ -74,6 +69,8 @@ function runDenyPaths(project) {
         ...[...MAIL_ENTRIES, ...entries(mail)].filter((e) => e !== "outbox").map((e) => path.join(mail, e)),
     ]);
 }
+/** The working directory of a wake-up that runs under a policy override: an empty dir, so nothing of the repo is writable by default. */
+export const scratchCwd = (workDir) => path.join(workDir, "cwd");
 /** The repo directory this agent works in: its own worktree, or the main repo. */
 export function repoDirFor(project, agent) {
     return project.workspaces?.[agent]?.dir ?? project.dir;
@@ -90,6 +87,7 @@ export function writePolicy(project, agent) {
         ...(project.solo === "call" ? [] : [outboxDir(project, agent.name)]),
         ...(ws ? [ws.gitDir] : []),
         ...(shared && mayWriteShared ? [shared] : []),
+        ...(isLead ? [recordsDir(project)] : []),
     ];
     const allowFiles = [];
     if (isLead)
@@ -122,6 +120,8 @@ export function writePolicy(project, agent) {
         addDeny(f);
     if (shared && !mayWriteShared)
         deny.push(shared);
+    if (!isLead)
+        deny.push(recordsDir(project));
     deny.push(...runDenyPaths(project), project.paths.config, path.join(project.home, "team.yaml"));
     // In a worktree: other agents' checkouts are off limits, and so are this checkout's own copies of the protected files.
     for (const [name, other] of Object.entries(project.workspaces ?? {}))
@@ -136,7 +136,7 @@ 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] : [],
+        readDirs: [...(shared && !mayWriteShared ? [shared] : []), ...(isLead ? [] : [recordsDir(project)])],
         allowFiles,
         deny: [...new Set(deny)],
     };

package/dist/prompt.d.ts

@@ -4,8 +4,11 @@ import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-ti
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
 export declare const HANDOFF_LIMIT: number;
-/** Cap of each of DECISIONS.md and LESSONS.md in a prompt. */
+/** Cap of each kind of project record (decisions, lessons) in a prompt. */
 export declare const CONTEXT_LIMIT: number;
+/** Largest mail body put in a prompt (the inline task limit), and the total for the mails handled in one wake-up. */
+export declare const MAIL_BODY_LIMIT: number;
+export declare const MAIL_BATCH_LIMIT: number;
 export declare const LEAD_BATCH_LIMIT = 5;
 export declare function readPersona(agent: ResolvedAgent): string;
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
@@ -17,12 +20,31 @@ export declare function buildSystemPrompt(project: ResolvedProject, agent: Resol
 /** 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 declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
 export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number, handoff?: boolean): string;
+export interface TidyRecordsContext {
+    /** The project records folder (`<shared>/common/records`). */
+    dir: string;
+    /** Absolute path of this tidy's archive folder for the records (the agent creates it). */
+    archiveDir: string;
+    /** One line per entry: kind, id, status, date, size and title (the archive is not listed). */
+    entries: {
+        kind: string;
+        id: string;
+        rel: string;
+        status: string;
+        date: string;
+        bytes: number;
+        title: string;
+        invalid?: string;
+    }[];
+    /** Live files that are not entries (kept as they are). */
+    otherFiles: MemoryFile[];
+}
 export interface TidyContext {
     layer: Layer;
-    /** The memory directory being tidied. */
-    dir: string;
+    /** The memory directory being tidied; absent when only the project records are tidied (the lead has no memory directory). */
+    dir?: string;
     /** Absolute path of this tidy's archive folder (the agent creates it). */
-    archiveDir: string;
+    archiveDir?: string;
     /** Live files only (the archive is not listed). */
     files: MemoryFile[];
     /** MEMORY.md text ("" when there is none). */
@@ -30,6 +52,8 @@ export interface TidyContext {
     /** What changed in the project since the last tidy (project layer only). */
     changes?: ProjectChanges;
     missing: MissingPath[];
+    /** Set only for the lead's project-layer tidy: the project records are tidied in the same wake-up. */
+    records?: TidyRecordsContext;
 }
 /** The prompts of a memory-tidy wake-up: a maintenance job, not a task, so it has none of the mail protocol. */
 export declare function buildTidyPrompts(agent: ResolvedAgent, ctx: TidyContext): {