agent-lyceum 0.22.0 → 0.23.0

package/dist/adapters/claude.d.ts

@@ -1,7 +1,12 @@
+import { type WritePolicy } from "../policy.js";
 import type { ResolvedAgent, ResolvedProject } from "../config.js";
 import type { ErrorKind } from "../schema.js";
 import type { Invocation, WakeInput } from "./types.js";
-export declare function buildClaudeSettings(project: ResolvedProject, agent: ResolvedAgent): Record<string, unknown>;
+/** `override`: a policy that replaces the agent's own; `cwd` is then the (scratch) directory the runtime starts in, in place of the repo. */
+export declare function buildClaudeSettings(project: ResolvedProject, agent: ResolvedAgent, override?: {
+    policy: WritePolicy;
+    cwd: string;
+}): Record<string, unknown>;
 export declare function buildClaudeInvocation(input: WakeInput): Invocation;
 /**
  * The text the rules read: the result message (only when it is an error message: pass `result` for an `is_error` run), stderr, and the HTTP status

package/dist/adapters/claude.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { repoDirFor, writePolicy } from "../policy.js";
+import { repoDirFor, scratchCwd, writePolicy } from "../policy.js";
 /** Claude Code path rules: `//abs/path` — a leading "/" plus the absolute path. */
 const rule = (tool, p) => `${tool}(/${p})`;
 function denyRules(p) {
@@ -17,10 +17,11 @@ function denyRules(p) {
         out.push(rule("Edit", `${p}/**`));
     return out;
 }
-export function buildClaudeSettings(project, agent) {
-    const pol = writePolicy(project, agent);
-    const ws = project.workspaces?.[agent.name];
-    const repo = repoDirFor(project, agent.name);
+/** `override`: a policy that replaces the agent's own; `cwd` is then the (scratch) directory the runtime starts in, in place of the repo. */
+export function buildClaudeSettings(project, agent, override) {
+    const pol = override?.policy ?? writePolicy(project, agent);
+    const ws = override ? undefined : project.workspaces?.[agent.name];
+    const repo = override?.cwd ?? repoDirFor(project, agent.name);
     const allow = ["Bash", "Read", "Glob", "Grep"];
     // Web tools are opt-in: `search` is the lighter one (snippets only), `fetch` also pulls whole pages into the agent's context.
     if (agent.allowWeb === "search" || agent.allowWeb === "fetch")
@@ -41,7 +42,7 @@ export function buildClaudeSettings(project, agent) {
             enabled: true,
             allowUnsandboxedCommands: false,
             filesystem: {
-                allowWrite: [ws?.root ?? project.dir, ...pol.allowDirs, ...pol.allowFiles],
+                allowWrite: [override?.cwd ?? ws?.root ?? project.dir, ...pol.allowDirs, ...pol.allowFiles],
                 denyWrite: pol.deny,
             },
         },
@@ -52,10 +53,13 @@ export function buildClaudeInvocation(input) {
     fs.mkdirSync(workDir, { recursive: true });
     const settingsFile = path.join(workDir, "claude-settings.json");
     const systemFile = path.join(workDir, "system-prompt.md");
-    fs.writeFileSync(settingsFile, JSON.stringify(buildClaudeSettings(project, agent), null, 2));
+    const repo = input.policy ? scratchCwd(workDir) : repoDirFor(project, agent.name);
+    const scope = input.policy ? { policy: input.policy, cwd: repo } : undefined;
+    if (scope)
+        fs.mkdirSync(repo, { recursive: true });
+    fs.writeFileSync(settingsFile, JSON.stringify(buildClaudeSettings(project, agent, scope), null, 2));
     fs.writeFileSync(systemFile, input.systemPrompt);
-    const pol = writePolicy(project, agent);
-    const repo = repoDirFor(project, agent.name);
+    const pol = input.policy ?? writePolicy(project, agent);
     const addDirs = [...pol.allowDirs, ...pol.readDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === repo || d.startsWith(repo + path.sep)));
     const args = [
         "-p",

package/dist/adapters/codex.js

@@ -1,9 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
-import { repoDirFor, writePolicy } from "../policy.js";
+import { repoDirFor, scratchCwd, writePolicy } from "../policy.js";
 export function codexWritableRoots(input) {
-    const pol = writePolicy(input.project, input.agent);
-    const work = repoDirFor(input.project, input.agent.name);
+    const pol = input.policy ?? writePolicy(input.project, input.agent);
+    const work = input.policy ? scratchCwd(input.workDir) : repoDirFor(input.project, input.agent.name);
     const roots = [...pol.allowDirs, ...pol.allowFiles.map((f) => path.dirname(f))].filter((d) => !(d === work || d.startsWith(work + path.sep)));
     return [...new Set(roots)];
 }
@@ -52,8 +52,10 @@ export function codexOutputTokens(jsonl) {
 const CODEX_WEB_SEARCH = { none: "disabled", search: "cached", fetch: "live" };
 export function buildCodexInvocation(input) {
     const { project, agent, workDir } = input;
-    const repo = repoDirFor(project, agent.name);
+    const repo = input.policy ? scratchCwd(workDir) : repoDirFor(project, agent.name);
     fs.mkdirSync(workDir, { recursive: true });
+    if (input.policy)
+        fs.mkdirSync(repo, { recursive: true });
     const lastFile = path.join(workDir, "codex-last-message.txt");
     const roots = codexWritableRoots(input);
     const common = [

package/dist/adapters/types.d.ts

@@ -1,5 +1,6 @@
 import type { ErrorKind } from "../schema.js";
 import type { ResolvedAgent, ResolvedProject } from "../config.js";
+import type { WritePolicy } from "../policy.js";
 import type { AgentWorkspace } from "../worktree.js";
 export interface WakeInput {
     project: ResolvedProject;
@@ -16,6 +17,11 @@ export interface WakeInput {
     signal?: AbortSignal;
     /** Where the full stdout/stderr of this invocation are written. */
     logDir?: string;
+    /**
+     * Replaces the agent's normal write policy (memory tidy: only the dirs being tidied). The repo is then not writable
+     * either: the runtime starts in an empty scratch dir inside `workDir` and may only read the repo.
+     */
+    policy?: WritePolicy;
 }
 export interface WakeResult {
     ok: boolean;

package/dist/cli.js

@@ -693,7 +693,11 @@ program
                     console.log(`  restored  ${f}`);
                 for (const s of r.skipped)
                     console.log(`  skipped   ${s.rel}: ${s.reason}`);
-                if (!r.restored.length && !r.skipped.length)
+                for (const f of r.records?.restored ?? [])
+                    console.log(`  restored  records/${f}`);
+                for (const k of r.records?.skipped ?? [])
+                    console.log(`  skipped   records/${k.rel}: ${k.reason}`);
+                if (!r.restored.length && !r.skipped.length && !r.records?.restored.length && !r.records?.skipped.length)
                     console.log(`Archive ${opts.undo} holds no files to restore.`);
             }
             finally {
@@ -728,11 +732,11 @@ program
             console.log(`No agent has ${layer} memory configured. ${layer === "project" ? "The template gives agents global memory only: set `memory.project` for an agent in project.yaml (or tidy global memory with --layer global)." : "Set `memory.global` for an agent."}`);
         for (const r of results) {
             if (r.status === "tidied")
-                console.log(`  ${r.agent} (${r.layer}): tidied. Archive: ${path.join(r.dir, ".archive", r.archive ?? "")} — undo with: agent-lyceum tidy --undo ${r.archive} -p ${pr.name} --agent ${r.agent}${r.layer === "global" ? " --layer global" : ""}`);
+                console.log(`  ${r.agent} (${r.layer}): tidied. Archive: ${path.join(r.dir, ".archive", r.archive ?? "")}${r.recordsDir && r.recordsDir !== r.dir ? `, records: ${path.join(r.recordsDir, ".archive", r.archive ?? "")}` : ""} — undo with: agent-lyceum tidy --undo ${r.archive} -p ${pr.name} --agent ${r.agent}${r.layer === "global" ? " --layer global" : ""}`);
             else if (r.status === "skipped")
                 console.log(`  ${r.agent} (${r.layer}): skipped — ${r.problems.join("; ")}`);
             else if (r.status === "failed") {
-                console.error(`  ${r.agent} (${r.layer}): FAILED, memory restored to how it was`);
+                console.error(`  ${r.agent} (${r.layer}): FAILED, ${r.recordsDir === r.dir ? "project records" : r.recordsDir ? "memory and project records" : "memory"} restored to how it was`);
                 for (const p of r.problems)
                     console.error(`    - ${p}`);
             }

package/dist/doctor.js

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import { findOnPath } from "./fs-util.js";
 import { tidyAdvice } from "./memory-tidy.js";
+import { listRecords, RECORD_KINDS } from "./records.js";
 import { listRunLocks, listUnreadableRunLocks, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
@@ -169,6 +170,17 @@ export async function diagnoseProject(project, opts = {}) {
     }
     for (const a of tidyAdvice(project))
         checks.push({ level: "info", subject: "memory", message: `${a.agent}: ${a.reason}. Consider: agent-lyceum tidy -p ${project.name} --agent ${a.agent} (doctor only suggests; it never tidies).` });
+    for (const kind of RECORD_KINDS) {
+        const recs = listRecords(project, kind);
+        const ids = new Set(recs.map((r) => r.id));
+        for (const r of recs) {
+            if (r.invalid)
+                checks.push({ level: "warn", subject: "records", message: `${r.file}: ${r.invalid}` });
+            for (const s of r.supersedes)
+                if (!ids.has(s))
+                    checks.push({ level: "warn", subject: "records", message: `${r.file}: supersedes "${s}", but no ${kind} entry has that id.` });
+        }
+    }
     const runtimes = await probeProjectRuntimes(project, opts, true);
     checks.push(...judgeRuntimes(project, runtimes));
     checks.push({ level: "info", subject: "login", message: "Login status is unknown: agent-lyceum does not read credentials, and the CLIs offer no read-only login check it can rely on." });

package/dist/fs-util.d.ts

@@ -10,3 +10,8 @@ export declare function readFileCapped(file: string, limit: number): {
     text: string;
     truncated: boolean;
 } | undefined;
+/**
+ * The bytes of a regular file, opened without following a symlink and without blocking (a FIFO opens at once and fails the
+ * fstat check). undefined for anything else or on any error: never throws, never hangs.
+ */
+export declare function readRegularFileNoFollow(file: string): Buffer | undefined;

package/dist/fs-util.js

@@ -58,3 +58,27 @@ export function readFileCapped(file, limit) {
         }
     }
 }
+/**
+ * The bytes of a regular file, opened without following a symlink and without blocking (a FIFO opens at once and fails the
+ * fstat check). undefined for anything else or on any error: never throws, never hangs.
+ */
+export function readRegularFileNoFollow(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0));
+        if (!fs.fstatSync(fd).isFile())
+            return undefined;
+        return fs.readFileSync(fd);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { }
+        }
+    }
+}

package/dist/guard.d.ts

@@ -17,6 +17,8 @@ export declare const MAX_KEEP_BYTES: number;
 export declare class ProtectedGuard {
     private project;
     private baseline;
+    /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
+    private records;
     constructor(project: ResolvedProject);
     /**
      * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
@@ -30,4 +32,10 @@ export declare class ProtectedGuard {
     private keep;
     /** Compare against the baseline after `running` agents finished; revert unauthorized changes. */
     check(running: ResolvedAgent[]): Violation[];
+    private checkRecords;
+    /**
+     * Make every directory from the records root down to `dir` a real directory. A symlink or file standing in for one is an
+     * unauthorized change: unlink it (never follow it), recreate the directory and report it. False when `dir` is not safe to write into.
+     */
+    private realDirs;
 }

package/dist/guard.js

@@ -1,7 +1,8 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { mayEditProtected, repoInstructionFiles, sharedContextFiles, sharedIndex } from "./policy.js";
+import { readRegularFileNoFollow } from "./fs-util.js";
+import { mayEditProtected, recordsDir, repoInstructionFiles, sharedContextFiles, sharedIndex } from "./policy.js";
 export const MAX_KEEP_BYTES = 1024 * 1024;
 function safeName(file) {
     return file.replace(/[\\/:]/g, "_").replace(/^_+/, "");
@@ -13,6 +14,8 @@ function safeName(file) {
 export class ProtectedGuard {
     project;
     baseline = new Map();
+    /** Regular files of the records tree (including `.archive/`); only the lead may change them. */
+    records = new Map();
     constructor(project) {
         this.project = project;
         this.rebase();
@@ -24,6 +27,7 @@ export class ProtectedGuard {
     rebase() {
         for (const f of ProtectedGuard.protectedFiles(this.project))
             this.baseline.set(f, read(f));
+        this.records = readTree(recordsDir(this.project));
     }
     static protectedFiles(project) {
         const files = new Set();
@@ -86,8 +90,126 @@ export class ProtectedGuard {
                 violations.push({ file, action: "restored", suspects: running.map((a) => a.name), ...kept });
             }
         }
+        this.checkRecords(running, violations);
         return violations;
     }
+    checkRecords(running, violations) {
+        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))))
+            return;
+        const now = readTree(root);
+        const lead = running.some((a) => a.name === this.project.lead);
+        const suspects = running.map((a) => a.name);
+        const fixedDirs = new Set();
+        for (const file of new Set([...this.records.keys(), ...now.keys()])) {
+            const before = this.records.get(file) ?? null;
+            const cur = now.get(file) ?? null;
+            if (same(before, cur))
+                continue;
+            if (lead)
+                continue;
+            const kept = this.keep(file, cur);
+            if (before === null) {
+                if (!insideRoot(root, path.dirname(file)))
+                    continue;
+                fs.rmSync(file, { force: true });
+                violations.push({ file, action: "removed", suspects, ...kept });
+            }
+            else {
+                if (!this.realDirs(root, path.dirname(file), fixedDirs, suspects, violations))
+                    continue;
+                fs.rmSync(file, { recursive: true, force: true });
+                fs.writeFileSync(file, before);
+                violations.push({ file, action: "restored", suspects, ...kept });
+            }
+        }
+        if (lead)
+            this.records = now;
+    }
+    /**
+     * Make every directory from the records root down to `dir` a real directory. A symlink or file standing in for one is an
+     * unauthorized change: unlink it (never follow it), recreate the directory and report it. False when `dir` is not safe to write into.
+     */
+    realDirs(root, dir, done, suspects, violations) {
+        const rel = path.relative(root, dir);
+        if (rel.startsWith("..") || path.isAbsolute(rel))
+            return false;
+        let cur = root;
+        for (const part of ["", ...(rel ? rel.split(path.sep) : [])]) {
+            cur = part ? path.join(cur, part) : cur;
+            let st;
+            try {
+                st = fs.lstatSync(cur);
+            }
+            catch { }
+            if (st?.isDirectory())
+                continue;
+            if (st) {
+                fs.rmSync(cur, { force: true });
+                if (!done.has(cur))
+                    violations.push({ file: cur, action: "removed", suspects, ...this.keep(cur, null) });
+                done.add(cur);
+            }
+            fs.mkdirSync(cur, { recursive: true });
+        }
+        return insideRoot(root, dir);
+    }
+}
+function isLink(p) {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function insideRoot(root, dir) {
+    try {
+        const r = path.relative(fs.realpathSync(root), fs.realpathSync(dir));
+        return !r.startsWith("..") && !path.isAbsolute(r);
+    }
+    catch {
+        return false;
+    }
+}
+/** Regular files under `dir`, recursively; symlinks and special files are not followed or read. */
+function readTree(dir) {
+    const out = new Map();
+    try {
+        if (!fs.lstatSync(dir).isDirectory())
+            return out; // a symlinked root is never walked
+    }
+    catch {
+        return out;
+    }
+    const walk = (d) => {
+        let names;
+        try {
+            names = fs.readdirSync(d);
+        }
+        catch {
+            return;
+        }
+        for (const n of names) {
+            const f = path.join(d, n);
+            try {
+                const st = fs.lstatSync(f);
+                if (st.isDirectory())
+                    walk(f);
+                else if (st.isFile()) {
+                    const buf = readRegularFileNoFollow(f);
+                    if (buf)
+                        out.set(f, buf);
+                }
+            }
+            catch {
+                // vanished while scanning
+            }
+        }
+    };
+    walk(dir);
+    return out;
 }
 function read(file) {
     try {

package/dist/mailbox.js

@@ -7,6 +7,7 @@ import { atomicWrite } from "./fs-util.js";
 import { countFormatRejection, formatRejectionKey, formatRejections, MAX_FORMAT_REJECTIONS } from "./format-rejections.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";
 import { must } from "./assert.js";
 export { atomicWrite };
 export const MESSAGE_TYPES = ["task", "reply", "failure", "done", "ask"];
@@ -259,6 +260,11 @@ export function routeOutboxes(project) {
                     reject(`only the lead ("${project.lead}") may send a "done" message.`);
                     continue;
                 }
+                const over = RECORD_KINDS.map((k) => ({ k, n: activeRecordsBytes(project, k) })).filter((x) => x.n > RECORDS_BUDGET);
+                if (over.length) {
+                    reject(`${over.map((x) => `records/${x.k} hold ${x.n} bytes of active entries`).join(" and ")}; the budget is ${RECORDS_BUDGET} bytes (6 KB) per kind. Merge entries, or mark obsolete ones "status: superseded" (or name them in a newer entry's "supersedes"), then send "done" again.`);
+                    continue;
+                }
                 res.done = { from: sender.name, subject, body: parsed.body, file, meta: d };
                 const ds = parseSteps(parsed.body);
                 if (ds.length)

package/dist/memory-tidy.d.ts

@@ -84,6 +84,8 @@ export interface TidyResult {
     status: "tidied" | "skipped" | "failed" | "dry-run";
     /** The archive stamp of a finished tidy. */
     archive?: string;
+    /** Set when the project records were tidied too: their folder (its archive is `<recordsDir>/.archive/<archive>`). */
+    recordsDir?: string;
     problems: string[];
 }
 /** Scratch space of one tidy (snapshot and the invocation's logs); outside every memory dir and every run. */
@@ -96,8 +98,19 @@ export interface RestoreResult {
         rel: string;
         reason: string;
     }[];
+    /** The same for the project records archive of that stamp, when the lead's undo found one. */
+    records?: {
+        restored: string[];
+        skipped: {
+            rel: string;
+            reason: string;
+        }[];
+    };
 }
-/** Move the files of one tidy's archive back to where they were. Nothing that exists now is overwritten. */
+/**
+ * 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 declare function restoreMemory(o: {
     project: ResolvedProject;
     agent: string;

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/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,7 +4,7 @@ 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;
 export declare const LEAD_BATCH_LIMIT = 5;
 export declare function readPersona(agent: ResolvedAgent): string;
@@ -17,12 +17,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 +49,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): {

package/dist/prompt.js

@@ -2,7 +2,8 @@ import fs from "node:fs";
 import { readFileCapped } from "./fs-util.js";
 import path from "node:path";
 import { REQUIRED_SECTIONS } from "./format.js";
-import { archiveFile, commonFile, decisionsFile, lessonsFile, memoryDirs, outboxDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
+import { buildRecordsView, RECORDS_BUDGET } from "./records.js";
+import { commonFile, memoryDirs, outboxDir, recordsKindDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
     if (dir === agent.memory.task)
         return "task (this task only, isolated)";
@@ -11,8 +12,8 @@ function memoryLabel(agent, dir) {
 export const COMMON_LIMIT = 8 * 1024;
 export const MEMORY_INDEX_LIMIT = 4 * 1024;
 export const HANDOFF_LIMIT = COMMON_LIMIT;
-/** Cap of each of DECISIONS.md and LESSONS.md in a prompt. */
-export const CONTEXT_LIMIT = 6 * 1024;
+/** Cap of each kind of project record (decisions, lessons) in a prompt. */
+export const CONTEXT_LIMIT = RECORDS_BUDGET;
 export const LEAD_BATCH_LIMIT = 5;
 const BATCHABLE = new Set(["reply", "failure"]);
 const readCapped = readFileCapped;
@@ -134,7 +135,7 @@ export function buildSystemPrompt(project, agent) {
     lines.push("- Never edit any `AGENT.md`, `COMMON.md`, or the repository's own `CLAUDE.md`/`AGENTS.md`" +
         (isLead || agent.canEditAgentMd ? " unless you need to as lead (changes are logged)." : "."), "- Never touch another agent's memory, inbox or outbox, or the team's config files.", `- The shared team context is in \`${commonFile(project)}\`${isLead ? " (you maintain it; keep it short)" : " (read-only)"}.`, ...(isLead
         ? [
-            `- You also keep two durable records for every future run of this project: \`${decisionsFile(project)}\` (what was decided and why; a new decision replaces the one it contradicts) and \`${lessonsFile(project)}\` (heuristics and pitfalls that stay true). Update them before you send \`done\`. Each is shown in prompts only up to ${CONTEXT_LIMIT / 1024} KB: move the oldest entries into \`${archiveFile(decisionsFile(project))}\` / \`${archiveFile(lessonsFile(project))}\` (read on demand) to keep them under it.`,
+            `- 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);
     return lines.join("\n");
@@ -168,16 +169,13 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff
             parts.push(`\n[COMMON.md was truncated at ${COMMON_LIMIT} bytes — the lead should condense it.]`);
         }
     }
-    for (const [title, file] of [
-        ["Project decisions (DECISIONS.md)", decisionsFile(project)],
-        ["Project lessons (LESSONS.md)", lessonsFile(project)],
+    for (const [title, kind] of [
+        ["Project decisions", "decisions"],
+        ["Project lessons", "lessons"],
     ]) {
-        const rec = readCapped(file, CONTEXT_LIMIT);
-        if (!rec?.text.trim())
-            continue; // nothing recorded yet: no heading, no tokens
-        parts.push("", `# ${title}`, rec.text.trim());
-        if (rec.truncated)
-            parts.push(`\n[${path.basename(file)} was truncated at ${CONTEXT_LIMIT} bytes — the lead should move the oldest entries to ${path.basename(archiveFile(file))}.]`);
+        const view = buildRecordsView(project, kind, CONTEXT_LIMIT);
+        if (view)
+            parts.push("", `# ${title}`, view); // nothing recorded yet: no heading, no tokens
     }
     const handoffFile = handoff ? sharedIndex(project) : undefined;
     const notes = handoffFile ? readCapped(handoffFile, HANDOFF_LIMIT) : undefined;
@@ -219,6 +217,8 @@ export function buildUserPrompt(project, agent, unread, handleCount = 1, handoff
 }
 /** The prompts of a memory-tidy wake-up: a maintenance job, not a task, so it has none of the mail protocol. */
 export function buildTidyPrompts(agent, ctx) {
+    const { dir, archiveDir, records } = ctx;
+    const touch = [dir ? `your ${ctx.layer} memory (\`${dir}\`)` : "", records ? `the project records (\`${records.dir}\`)` : ""].filter(Boolean).join(" and ");
     const systemPrompt = [
         readPersona(agent),
         "",
@@ -226,35 +226,46 @@ export function buildTidyPrompts(agent, ctx) {
         "",
         "# Memory tidy (injected by agent-lyceum)",
         "",
-        `You are **${agent.name}**. This wake-up is a maintenance job, not a task: there is no mail to send or read, and nothing to do in the repository. Your only job is to tidy your own ${ctx.layer} memory so it stays small, accurate and useful.`,
+        `You are **${agent.name}**. This wake-up is a maintenance job, not a task: there is no mail to send or read, and nothing to do in the repository. Your only job is to tidy ${records ? touch : `your own ${ctx.layer} memory`} so it stays small, accurate and useful.`,
         "",
         "## What you may touch",
-        `Only files inside \`${ctx.dir}\`. Everything else is read-only. Do not touch your other memory directories, \`${ctx.dir}/.tidy-state.json\` or the archive folders of earlier tidies.`,
-        "",
-        "## What to do",
-        "- Merge entries that say the same thing; keep one file with the combined, current content.",
-        "- Rewrite entries that are stale (see the project changes and the missing paths below); correct them if you can tell what is true now, otherwise keep them and say so in the report.",
-        "- Keep `MEMORY.md` as the index: one line per entry, each pointing at an existing file, and nothing for files that were archived.",
-        "- **When unsure, keep it.** Prefer leaving an entry alone over losing information.",
-        "",
-        "## Never delete",
-        `To retire a file, move it into the archive folder, keeping its relative path (\`${ctx.dir}/x/y.md\` goes to \`${ctx.archiveDir}/x/y.md\`). Never delete a file. \`MEMORY.md\` itself is never archived. A file whose content you merged into another one is archived too.`,
-        "",
-        "## Before you finish",
-        `Write \`${ctx.archiveDir}/tidy-report.md\` — even when you changed nothing — with these headings: \`## Merged\` (what was combined into what), \`## Archived\` (each archived file and why), \`## Unsure\` (things you kept but doubt). Write \`None\` under a heading with nothing to say. The tidy is rolled back if the report is missing or any file went missing.`,
+        `Only files inside ${[dir ? `\`${dir}\`` : "", records ? `\`${records.dir}\`` : ""].filter(Boolean).join(" and ")}. Everything else is read-only. Do not touch your other memory directories, \`${dir ? `${dir}/` : ""}.tidy-state.json\` or the archive folders of earlier tidies.`,
+        ...(dir && archiveDir
+            ? [
+                "",
+                records ? "## What to do with your memory" : "## What to do",
+                "- Merge entries that say the same thing; keep one file with the combined, current content.",
+                "- Rewrite entries that are stale (see the project changes and the missing paths below); correct them if you can tell what is true now, otherwise keep them and say so in the report.",
+                "- Keep `MEMORY.md` as the index: one line per entry, each pointing at an existing file, and nothing for files that were archived.",
+                "- **When unsure, keep it.** Prefer leaving an entry alone over losing information.",
+                "",
+                "## Never delete",
+                `To retire a file, move it into the archive folder, keeping its relative path (\`${dir}/x/y.md\` goes to \`${archiveDir}/x/y.md\`). Never delete a file. \`MEMORY.md\` itself is never archived. A file whose content you merged into another one is archived too.`,
+                "",
+                records ? "## Before you finish (memory)" : "## Before you finish",
+                `Write \`${archiveDir}/tidy-report.md\` — even when you changed nothing — with these headings: \`## Merged\` (what was combined into what), \`## Archived\` (each archived file and why), \`## Unsure\` (things you kept but doubt). Write \`None\` under a heading with nothing to say. The tidy is rolled back if the report is missing or any file went missing.`,
+            ]
+            : []),
+        ...(records
+            ? [
+                "",
+                "## What to do with the project records",
+                `The records are the project's durable decisions and lessons, one file per entry (\`${records.dir}/decisions/<id>.md\`, \`${records.dir}/lessons/<id>.md\`). Every entry has frontmatter with \`status\` (\`active\` or \`superseded\`), \`date\` (YYYY-MM-DD) and \`title\` (one line), optionally \`run\` and \`supersedes\` (a list of ids).`,
+                "- Merge entries that say the same thing into one entry (write the merged content, then archive the entries that were merged).",
+                "- When a newer entry replaces an older one, list the old id under `supersedes` in the newer entry, or set the old entry to `status: superseded`.",
+                "- Archive entries that are obsolete.",
+                "- Keep the frontmatter valid: `status`, `date` and `title` are required; the id is the file name without `.md` and uses only lowercase letters, digits and `-`.",
+                "- **When unsure, keep it.** Never delete a file.",
+                `To archive a record, move it into \`${records.archiveDir}\`, keeping its relative path (\`${records.dir}/lessons/x.md\` goes to \`${records.archiveDir}/lessons/x.md\`).`,
+                `Write \`${records.archiveDir}/tidy-report.md\` — even when you changed nothing — with the headings \`## Merged\`, \`## Archived\`, \`## Unsure\` (\`None\` when empty). The tidy of both folders is rolled back if the report is missing or any file went missing.`,
+            ]
+            : []),
     ].join("\n");
-    const parts = [
-        `Archive directory: ${ctx.archiveDir}`,
-        `Layer: ${ctx.layer}${ctx.layer === "global" ? " (shared by every project; do not judge entries by one project's code)" : ""}`,
-        `Memory directory: ${ctx.dir}`,
-        "",
-        "# Files",
-        ...(ctx.files.length ? ctx.files.map((f) => `${f.rel}  ${f.bytes} B  modified ${f.mtime.slice(0, 10)}`) : ["(none)"]),
-        "",
-        `# MEMORY.md (${ctx.dir}/MEMORY.md)`,
-        ctx.index.trim() ? ctx.index.trim() : "(no MEMORY.md)",
-    ];
-    if (ctx.layer === "project") {
+    const parts = [];
+    if (dir && archiveDir) {
+        parts.push(`Archive directory: ${archiveDir}`, `Layer: ${ctx.layer}${ctx.layer === "global" ? " (shared by every project; do not judge entries by one project's code)" : ""}`, `Memory directory: ${dir}`, "", "# Files", ...(ctx.files.length ? ctx.files.map((f) => `${f.rel}  ${f.bytes} B  modified ${f.mtime.slice(0, 10)}`) : ["(none)"]), "", `# MEMORY.md (${dir}/MEMORY.md)`, ctx.index.trim() ? ctx.index.trim() : "(no MEMORY.md)");
+    }
+    if (ctx.layer === "project" && dir) {
         const c = ctx.changes;
         parts.push("", "# Changes in the project since the last tidy");
         if (!c)
@@ -268,7 +279,14 @@ export function buildTidyPrompts(agent, ctx) {
                 parts.push("", "Files changed:", ...c.stat);
         }
     }
-    parts.push("", "# Paths named in the memory that no longer exist");
-    parts.push(...(ctx.missing.length ? ctx.missing.map((m) => `- \`${m.path}\` (mentioned in ${m.file})`) : ["(none found)"]));
+    if (dir) {
+        parts.push("", "# Paths named in the memory that no longer exist");
+        parts.push(...(ctx.missing.length ? ctx.missing.map((m) => `- \`${m.path}\` (mentioned in ${m.file})`) : ["(none found)"]));
+    }
+    if (records) {
+        parts.push(...(parts.length ? [""] : []), "# Project records", `Records archive directory: ${records.archiveDir}`, `Records directory: ${records.dir}`, "", "Entries (kind/id  status  date  size  title):", ...(records.entries.length
+            ? records.entries.map((e) => `${e.rel}  ${e.status}  ${e.date || "no date"}  ${e.bytes} B  ${e.title}${e.invalid ? `  [INVALID: ${e.invalid}]` : ""}`)
+            : ["(none)"]), ...(records.otherFiles.length ? ["", "Other files (leave them alone):", ...records.otherFiles.map((f) => `${f.rel}  ${f.bytes} B`)] : []));
+    }
     return { systemPrompt, userPrompt: parts.join("\n") };
 }

package/dist/records.d.ts

@@ -0,0 +1,30 @@
+import type { ResolvedProject } from "./config.js";
+export type RecordKind = "decisions" | "lessons";
+export declare const RECORD_KINDS: readonly RecordKind[];
+/** Cap of one kind's effective-active entries in a prompt (and, for `done`, the most they may add up to). */
+export declare const RECORDS_BUDGET: number;
+export interface ProjectRecord {
+    kind: RecordKind;
+    id: string;
+    file: string;
+    status: "active" | "superseded";
+    /** `YYYY-MM-DD`; empty when the frontmatter is invalid. */
+    date: string;
+    run?: string;
+    supersedes: string[];
+    title: string;
+    body: string;
+    /** Why the entry could not be read as a record; set entries still count as active so nothing silently disappears. */
+    invalid?: string;
+}
+/** Every `*.md` entry of one kind, sorted by id. Entries that cannot be parsed are listed with `invalid` set; a missing folder is an empty list. */
+export declare function listRecords(project: ResolvedProject, kind: RecordKind): ProjectRecord[];
+/** Entries shown in prompts: `status: active` and not named in another entry's `supersedes`. */
+export declare function effectiveActive(records: ProjectRecord[]): ProjectRecord[];
+/** Bytes the effective-active entries of a kind take in a prompt (each rendered whole, as `buildRecordsView` does). */
+export declare function activeRecordsBytes(project: ResolvedProject, kind: RecordKind): number;
+/**
+ * The text of one kind for a prompt: effective-active entries, newest first, whole entries only until the budget is
+ * used (never cut inside one); the rest are one line each, to read on demand. Undefined when there is nothing to show.
+ */
+export declare function buildRecordsView(project: ResolvedProject, kind: RecordKind, budgetBytes?: number): string | undefined;

package/dist/records.js

@@ -0,0 +1,130 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { readRegularFileNoFollow } from "./fs-util.js";
+import { recordsDir, recordsKindDir } from "./policy.js";
+export const RECORD_KINDS = ["decisions", "lessons"];
+/** Cap of one kind's effective-active entries in a prompt (and, for `done`, the most they may add up to). */
+export const RECORDS_BUDGET = 6 * 1024;
+const ID_RE = /^[a-z0-9-]+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+function parseEntry(kind, file) {
+    const id = path.basename(file, ".md");
+    const fallback = { kind, id, file, status: "active", date: "", supersedes: [], title: path.basename(file), body: "" };
+    // Never open a symlink (it could point into .archive/ or outside the tree) or a FIFO/device (it blocks the reader).
+    const buf = readRegularFileNoFollow(file);
+    if (!buf)
+        return { ...fallback, invalid: "not a readable regular file (symlinks and special files are never read)" };
+    const text = buf.toString("utf8");
+    const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/.exec(text);
+    if (!m)
+        return { ...fallback, body: text.trim(), invalid: "missing frontmatter" };
+    const body = (m[2] ?? "").trim();
+    let fm;
+    try {
+        fm = parseYaml(m[1]);
+    }
+    catch (e) {
+        return { ...fallback, body, invalid: `frontmatter is not valid YAML: ${e.message.split("\n")[0]}` };
+    }
+    if (!fm || typeof fm !== "object" || Array.isArray(fm))
+        return { ...fallback, body, invalid: "frontmatter is not a mapping" };
+    const f = fm;
+    const problems = [];
+    if (!ID_RE.test(id))
+        problems.push("file name must be lowercase letters, digits and -");
+    if (f.status !== "active" && f.status !== "superseded")
+        problems.push("status must be active or superseded");
+    // YAML parses an unquoted 2026-01-02 as a Date.
+    const date = f.date instanceof Date ? f.date.toISOString().slice(0, 10) : f.date;
+    if (typeof date !== "string" || !DATE_RE.test(date))
+        problems.push("date must be YYYY-MM-DD");
+    if (typeof f.title !== "string" || !f.title.trim() || /[\r\n]/.test(f.title.trim()))
+        problems.push("title must be one non-empty line");
+    let supersedes = [];
+    if (f.supersedes !== undefined) {
+        if (Array.isArray(f.supersedes) && f.supersedes.every((x) => typeof x === "string"))
+            supersedes = f.supersedes;
+        else
+            problems.push("supersedes must be a list of ids");
+    }
+    if (f.run !== undefined && typeof f.run !== "string")
+        problems.push("run must be a string");
+    if (problems.length)
+        return { ...fallback, body, invalid: problems.join("; ") };
+    return {
+        kind,
+        id,
+        file,
+        status: f.status,
+        date: date,
+        run: f.run,
+        supersedes,
+        title: f.title.trim(),
+        body,
+    };
+}
+/** Every `*.md` entry of one kind, sorted by id. Entries that cannot be parsed are listed with `invalid` set; a missing folder is an empty list. */
+export function listRecords(project, kind) {
+    const dir = recordsKindDir(project, kind);
+    let names;
+    try {
+        // A symlinked records/ or kind folder could point at archived or outside entries: list nothing, never descend.
+        for (const d of [recordsDir(project), dir])
+            if (!fs.lstatSync(d).isDirectory())
+                return [];
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names
+        .filter((n) => n.endsWith(".md"))
+        .sort()
+        .map((n) => parseEntry(kind, path.join(dir, n)));
+}
+/** Entries shown in prompts: `status: active` and not named in another entry's `supersedes`. */
+export function effectiveActive(records) {
+    const replaced = new Set();
+    for (const r of records)
+        for (const id of r.supersedes)
+            if (id !== r.id)
+                replaced.add(id);
+    return records.filter((r) => r.status === "active" && !replaced.has(r.id));
+}
+function newestFirst(records) {
+    return [...records].sort((a, b) => b.date.localeCompare(a.date) || b.id.localeCompare(a.id));
+}
+function renderEntry(r) {
+    return `## ${r.title} [${r.id}]${r.body ? `\n${r.body}` : ""}`;
+}
+/** Bytes the effective-active entries of a kind take in a prompt (each rendered whole, as `buildRecordsView` does). */
+export function activeRecordsBytes(project, kind) {
+    return Buffer.byteLength(effectiveActive(listRecords(project, kind)).map(renderEntry).join("\n\n"));
+}
+/**
+ * The text of one kind for a prompt: effective-active entries, newest first, whole entries only until the budget is
+ * used (never cut inside one); the rest are one line each, to read on demand. Undefined when there is nothing to show.
+ */
+export function buildRecordsView(project, kind, budgetBytes = RECORDS_BUDGET) {
+    const entries = newestFirst(effectiveActive(listRecords(project, kind)));
+    if (entries.length === 0)
+        return undefined;
+    const shown = [];
+    let used = 0;
+    let i = 0;
+    for (; i < entries.length; i++) {
+        const text = renderEntry(entries[i]);
+        const size = Buffer.byteLength(text) + (shown.length ? 2 : 0);
+        if (used + size > budgetBytes)
+            break;
+        shown.push(text);
+        used += size;
+    }
+    const rest = entries.slice(i);
+    const parts = [...shown];
+    if (rest.length) {
+        parts.push(`${shown.length ? "More" : "These"} active entries did not fit in ${budgetBytes} bytes; read the file on demand:`, rest.map((r) => `- [${r.id}] ${r.title} (read: ${r.file})`).join("\n"));
+    }
+    return parts.join("\n\n");
+}

package/dist/scaffold.js

@@ -7,7 +7,7 @@ const PERSONAS = {
 You coordinate the team. You receive the user's task, break it into concrete pieces, and delegate each piece to the right teammate by mail.
 
 - Keep \`COMMON.md\` (shared team context: goal, conventions) accurate and short.
-- Before you send \`done\`, record what was decided and why in \`DECISIONS.md\` and what the project learned in \`LESSONS.md\` (next to \`COMMON.md\`); later runs start from them.
+- Before you send \`done\`, record what was decided and why as decision entries, and what the project learned as lesson entries, in the records folders named in your rules (one file per entry, with frontmatter); mark outdated entries \`superseded\`. Later runs start from the effective-active ones (about 6 KB per kind).
 - Write every task with the standard task headings, and cite the mail it derives from under Upstream so teammates can trace it.
 - When a teammate reports back, decide the next step: assign follow-up work, ask another teammate to verify, or accept the result.
 - Teammates cannot message each other by default; route everything through yourself.

package/package.json

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