agent-lyceum 0.21.2 → 0.23.0

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 { commonFile, 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,6 +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 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;
@@ -88,7 +91,7 @@ export function buildSystemPrompt(project, agent) {
         ? `When the whole job is finished, send a message with \`type: done\` (no \`to\` needed). That ends the run. A summary in your reply text is never delivered and does not end the run: after the last teammate reply is verified you MUST send \`done\` (or a \`task\` for the remaining work), or the run stops as "idle" with no final report.`
         : `Report results to the lead by mail; the lead decides what happens next.`, isLead
         ? "Each wake-up handles one message, except that several `reply`/`failure` messages waiting together are handed to you in one wake-up: weigh them together, then decide the next step once."
-        : "Each wake-up handles one message. Do the work it asks, then send the replies that are needed, then stop.", "Mail that repeats an earlier mail of yours to the same agent (same type, same text) is not sent again; you are told, and should wait for the answer or ask for something different instead of resending.", "", "## Message format", "The body of every `task` and `reply` must contain these `##` headings, exactly as written (write `None` under a heading if there is nothing to say).", "Mail missing a heading is still delivered, but is flagged to the recipient.", "", `- \`task\`: ${REQUIRED_SECTIONS.task.map((h) => `\`## ${h}\``).join(", ")} (Upstream = id of the mail this task derives from, or \`None\`).`, `- \`reply\`: ${REQUIRED_SECTIONS.reply.map((h) => `\`## ${h}\``).join(", ")}.`, isLead
+        : "Each wake-up handles one message, except that consecutive `reply`/`failure` messages on the same thread may be handed to you together: handle them together. Do the work it asks, then send the replies that are needed, then stop.", "Mail that repeats an earlier mail of yours to the same agent (same type, same text) is not sent again; you are told, and should wait for the answer or ask for something different instead of resending.", "", "## Message format", "The body of every `task` and `reply` must contain these `##` headings, exactly as written (write `None` under a heading if there is nothing to say).", "A `task` or `reply` missing a heading is sent back to you (at most twice per sender + type + subject); after that it is delivered with a warning flagged to the recipient.", "", `- \`task\`: ${REQUIRED_SECTIONS.task.map((h) => `\`## ${h}\``).join(", ")} (Upstream = id of the mail this task derives from, or \`None\`).`, `- \`reply\`: ${REQUIRED_SECTIONS.reply.map((h) => `\`## ${h}\``).join(", ")}.`, isLead
         ? "- `done`: your final report to the user (shown when the run ends, saved as `result.md`). Its frontmatter must contain `outcome: completed|partial|blocked|failed`, and the body the headings `## Result` (the actual deliverable or conclusion, not just \"done\"), `## Files` (paths created or changed), `## Verification` (what you ran or checked, and what it showed) and `## Not done` (anything skipped or unverified, or `None`). Only `completed` means success, and it needs all four headings and every checklist step ticked; if work remains or is blocked, say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A `done` that breaks this is sent back to you and does not end the run. " + OPEN_PR_RULE
         : "- `done` has no required headings.", ...(agent.canAskUser
         ? [
@@ -130,18 +133,26 @@ export function buildSystemPrompt(project, agent) {
     }
     lines.push("", "## Rules");
     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)"}.`, PR_ATTRIBUTION_RULE, NO_DAEMONS_RULE);
+        (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 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");
 }
-/** Messages one wake-up handles: the oldest one, or for the lead a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so it decides once on all of it. */
+/** Messages one wake-up handles: the oldest one, or a run of `reply`/`failure` mail (up to LEAD_BATCH_LIMIT) so the agent decides once on all of it; the lead takes any such run, other agents only same-thread ones. */
 export function pickMessages(project, agent, queue) {
     const sorted = [...queue].sort((a, b) => path.basename(a.file).localeCompare(path.basename(b.file)));
-    if (agent.name !== project.lead || !BATCHABLE.has(sorted[0]?.meta.type))
+    const first = sorted[0];
+    if (!first || !BATCHABLE.has(first.meta.type))
         return sorted.slice(0, 1);
+    const isLead = agent.name === project.lead;
     const run = [];
     for (const m of sorted) {
         if (!BATCHABLE.has(m.meta.type) || run.length >= LEAD_BATCH_LIMIT)
             break;
+        if (!isLead && m.meta.thread !== first.meta.thread)
+            break;
         run.push(m);
     }
     return run;
@@ -158,6 +169,14 @@ 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, kind] of [
+        ["Project decisions", "decisions"],
+        ["Project lessons", "lessons"],
+    ]) {
+        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;
     if (handoffFile && notes?.text.trim()) {
@@ -198,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),
         "",
@@ -205,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)
@@ -247,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/run-session.js

@@ -382,6 +382,8 @@ export class RunSession {
                     state.sessions[sessionKey] = result.sessionId;
                 if (result.outputTokens)
                     state.output_tokens += result.outputTokens;
+                state.cache_read_tokens += result.cacheReadTokens ?? 0;
+                state.cache_write_tokens += result.cacheWriteTokens ?? 0;
                 delete state.active[agent.name];
                 // With a chain only: which model ran, what it replaced, why it failed.
                 const which = chain ? { runtime: c.runtime, model: c.model, fallback_from: c.primary || !replaced ? undefined : modelLabel(replaced), kind: result.kind } : {};
@@ -392,6 +394,8 @@ export class RunSession {
                     duration_ms: Date.now() - started,
                     ok: result.ok,
                     output_tokens: result.outputTokens,
+                    cache_read_tokens: result.cacheReadTokens,
+                    cache_write_tokens: result.cacheWriteTokens,
                     handling,
                     error: result.error,
                     ...which,

package/dist/run-store.d.ts

@@ -32,6 +32,9 @@ export interface WakeRecord {
     duration_ms: number;
     ok: boolean;
     output_tokens?: number;
+    /** Prompt-cache input tokens read / written by this wake (claude only). */
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
     handling: WakeTopic[];
     /** Mail this wake handed to others; `to` is "(done)" for the lead's final message. */
     sent?: SentTopic[];
@@ -105,6 +108,9 @@ export interface RunState {
     pr_url?: string;
     sessions: Record<string, string>;
     output_tokens: number;
+    /** Run totals of the wakes' prompt-cache input tokens (0 for runs before this was recorded, and for codex). */
+    cache_read_tokens: number;
+    cache_write_tokens: number;
     /** `runtime`/`model` only for agents with a fallback chain. */
     last_wake: Record<string, {
         at: string;

package/dist/run-store.js

@@ -46,6 +46,8 @@ const WireState = z
     ask_rejections: z.record(z.string(), nonNeg).optional(),
     sessions: z.record(z.string(), z.string()).optional(),
     output_tokens: nonNeg.optional(),
+    cache_read_tokens: nonNeg.optional(),
+    cache_write_tokens: nonNeg.optional(),
     last_wake: z.record(z.string(), z.any()).optional(),
     pid: z.number().optional(),
     task_summary: z.string().optional(),
@@ -86,6 +88,8 @@ function normalize(w) {
         max_rounds: w.max_rounds ?? 0,
         sessions: w.sessions ?? {},
         output_tokens: w.output_tokens ?? 0,
+        cache_read_tokens: w.cache_read_tokens ?? 0,
+        cache_write_tokens: w.cache_write_tokens ?? 0,
         last_wake: w.last_wake ?? {},
         pid: w.pid ?? 0,
         task_summary: w.task_summary ?? "",

package/dist/scaffold.js

@@ -6,7 +6,8 @@ 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, architecture decisions, conventions) accurate and short.
+- Keep \`COMMON.md\` (shared team context: goal, conventions) accurate and short.
+- 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/dist/status-watch.d.ts

@@ -1,6 +1,6 @@
 import type { ResolvedProject } from "./config.js";
 import { type StatusReport } from "./status.js";
-/** What `status --json --watch` prints, one JSON object per line: the project's report plus one per running task. */
+/** What `status --json --watch` prints, one JSON object per line: the project's report plus one per task that is not completed. */
 export type WatchFrame = {
     schema_version: 1;
     report?: StatusReport;
@@ -8,9 +8,10 @@ export type WatchFrame = {
     error?: string;
 };
 /**
- * The frame for now. Every running task gets its own report; a task that was running in the previous frame
- * and has ended since is included once more, so the reader sees it finish (and can toast) before it is dropped.
- * `tracked` is that previous set; it is replaced by the ids running now.
+ * The frame for now. Every task that is not completed (running, interrupted, waiting for answers, or ended partial,
+ * blocked, failed or cancelled) gets its own report, so it stays listed until it is resumed to completion or cleared.
+ * A task that was running in the previous frame and has completed since is included once more, so the reader sees
+ * it finish (and can toast) before it is dropped. `tracked` is that previous set; it is replaced by the ids running now.
  */
 export declare function buildWatchFrame(project: ResolvedProject, tracked: Set<string>): WatchFrame;
 export interface WatchDeps {

package/dist/status-watch.js

@@ -1,16 +1,17 @@
 import fs from "node:fs";
-import { buildStatusReport, buildTaskListReport } from "./status.js";
+import { buildStatusReport, buildTaskListReport, isCompletedRun } from "./status.js";
 /**
- * The frame for now. Every running task gets its own report; a task that was running in the previous frame
- * and has ended since is included once more, so the reader sees it finish (and can toast) before it is dropped.
- * `tracked` is that previous set; it is replaced by the ids running now.
+ * The frame for now. Every task that is not completed (running, interrupted, waiting for answers, or ended partial,
+ * blocked, failed or cancelled) gets its own report, so it stays listed until it is resumed to completion or cleared.
+ * A task that was running in the previous frame and has completed since is included once more, so the reader sees
+ * it finish (and can toast) before it is dropped. `tracked` is that previous set; it is replaced by the ids running now.
  */
 export function buildWatchFrame(project, tracked) {
-    const running = buildTaskListReport(project)
-        .runs.filter((r) => r.state === "running")
-        .map((r) => r.run_id);
+    const all = buildTaskListReport(project).runs;
+    const running = all.filter((r) => r.state === "running").map((r) => r.run_id);
+    const open = all.filter((r) => !isCompletedRun(r)).map((r) => r.run_id);
     const runs = {};
-    for (const id of new Set([...running, ...tracked]))
+    for (const id of new Set([...open, ...tracked]))
         runs[id] = buildStatusReport(project, id);
     const report = buildStatusReport(project);
     tracked.clear();

package/dist/status.d.ts

@@ -43,6 +43,8 @@ export interface Paint {
     cyan: (t: string) => string;
 }
 export declare function paint(on: boolean): Paint;
+/** "快取 讀 288,124 寫 21,364 命中 93%": the share of cached input that was read, not written. Empty when nothing was recorded. */
+export declare function cacheText(read: number | undefined, write: number | undefined): string;
 export declare function progressBar(done: number, total: number, width?: number, c?: Paint): string;
 export interface QueueItem {
     agent: string;
@@ -74,6 +76,9 @@ export interface RunReport {
     /** Set when an agent kept failing and the run stopped: `resume` after fixing the cause. */
     failure?: RunFailure;
     output_tokens: number;
+    /** Prompt-cache input tokens read / written over the run (claude only; 0 when unknown). */
+    cache_read_tokens: number;
+    cache_write_tokens: number;
     task_source: "text" | "file";
     task_path?: string;
     task_summary: string;
@@ -161,6 +166,8 @@ export declare function buildRunReport(run: {
 }, project?: ResolvedProject, opts?: {
     detail?: boolean;
 }): RunReport;
+/** A run that ended with a verified-or-inferred `completed` outcome: the only kind the monitor stops listing. */
+export declare const isCompletedRun: (r: Pick<RunReport, "state" | "outcome">) => boolean;
 /** The status of a project: its agents and one run (the newest running one, else the newest, or the one named by `runId`). */
 export declare function buildStatusReport(base: ResolvedProject, runId?: string, now?: number): StatusReport;
 /** Every run of the project, newest first. */

package/dist/status.js

@@ -120,6 +120,11 @@ const cols = (t) => [...t].reduce((n, ch) => n + ((ch.codePointAt(0) ?? 0) >= 0x
 const padCols = (t, n) => t + " ".repeat(Math.max(0, n - cols(t)));
 const clip = (t, n) => (t.length > n ? t.slice(0, n - 1) + "…" : t);
 const tokens = (n) => (n ? n.toLocaleString("en-US") : "0");
+/** "快取 讀 288,124 寫 21,364 命中 93%": the share of cached input that was read, not written. Empty when nothing was recorded. */
+export function cacheText(read, write) {
+    const [r, w] = [read ?? 0, write ?? 0];
+    return r + w > 0 ? `快取 讀 ${tokens(r)} 寫 ${tokens(w)} 命中 ${Math.round((100 * r) / (r + w))}%` : "";
+}
 function since(iso, now) {
     const sec = Math.max(0, Math.round((now - Date.parse(iso)) / 1000));
     return sec < 60 ? `${sec}s` : `${Math.floor(sec / 60)}m${String(sec % 60).padStart(2, "0")}s`;
@@ -207,6 +212,8 @@ export function buildRunReport(run, project, opts = {}) {
         max_rounds: s.max_rounds,
         ...(s.failure ? { failure: s.failure } : {}),
         output_tokens: s.output_tokens,
+        cache_read_tokens: s.cache_read_tokens ?? 0,
+        cache_write_tokens: s.cache_write_tokens ?? 0,
         task_source: s.task_source,
         task_path: s.task_path,
         task_summary: s.task_summary,
@@ -226,6 +233,8 @@ export function buildRunReport(run, project, opts = {}) {
         ...(ask ? { ask } : {}),
     };
 }
+/** A run that ended with a verified-or-inferred `completed` outcome: the only kind the monitor stops listing. */
+export const isCompletedRun = (r) => r.state === "ended" && r.outcome === "completed";
 const projectInfo = (p) => ({ name: p.name, dir: p.dir, lead: p.lead });
 /** The fallback part of an agent's report: nothing at all for an agent without a chain. */
 function fallbackView(a, state, now) {
@@ -362,7 +371,7 @@ function summaryBlock(run, now, c) {
 /** What a run is doing / did, one line per wake. */
 function describeRun(s, now, c, limit = Infinity) {
     const lines = [
-        `${c.bold("執行 " + runLabel(s))}  [${stateColor(c, reportLabel(s))}]  輪次 ${roundsLabel(s.rounds, s.max_rounds)}  輸出 tokens ${tokens(s.output_tokens)}`,
+        `${c.bold("執行 " + runLabel(s))}  [${stateColor(c, reportLabel(s))}]  輪次 ${roundsLabel(s.rounds, s.max_rounds)}  輸出 tokens ${tokens(s.output_tokens)}${cacheText(s.cache_read_tokens, s.cache_write_tokens) ? `  ${cacheText(s.cache_read_tokens, s.cache_write_tokens)}` : ""}`,
         `  任務：${taskText(s)}`,
     ];
     const steps = stepsLine(s.steps, c);
@@ -501,7 +510,7 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     if (fb.length)
         lines.push("", ...fb);
     if (run)
-        lines.push("", `輸出 tokens：${tokens(run.output_tokens)}`);
+        lines.push("", `輸出 tokens：${tokens(run.output_tokens)}${cacheText(run.cache_read_tokens, run.cache_write_tokens) ? `　${cacheText(run.cache_read_tokens, run.cache_write_tokens)}` : ""}`);
     if (report.memory_advice?.length)
         lines.push("", `記憶：${report.memory_advice.join("；")}（建議執行 agent-lyceum tidy -p ${report.project.name}；status 只提示，不會自動整理）`);
     return lines.join("\n");

package/package.json

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