agent-lyceum 0.21.2 → 0.22.0

package/dist/adapters/claude.d.ts

@@ -19,6 +19,8 @@ interface ClaudeResult {
     session_id?: string;
     usage?: {
         output_tokens?: number;
+        cache_read_input_tokens?: number;
+        cache_creation_input_tokens?: number;
     };
     is_error?: boolean;
 }

package/dist/adapters/claude.js

@@ -133,6 +133,8 @@ function interpretClaude(j, stdout, stderr, code) {
         text: String(j.result ?? ""),
         sessionId: j.session_id,
         outputTokens: j.usage?.output_tokens,
+        cacheReadTokens: j.usage?.cache_read_input_tokens,
+        cacheWriteTokens: j.usage?.cache_creation_input_tokens,
         error: ok ? undefined : String(j.result ?? stderr).slice(0, 500),
         kind: ok ? undefined : classifyClaudeError({ code, stdout, stderr, result: j.is_error && j.result !== undefined ? String(j.result) : undefined }),
     };

package/dist/adapters/types.d.ts

@@ -22,6 +22,9 @@ export interface WakeResult {
     text: string;
     sessionId?: string;
     outputTokens?: number;
+    /** Prompt-cache usage (claude only): input tokens read from / written to the cache. */
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
     exitCode: number | null;
     timedOut: boolean;
     error?: string;
@@ -35,6 +38,8 @@ export type Parsed = {
     text: string;
     sessionId?: string;
     outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
     error?: string;
     /** Set on failure only; `unknown` when no rule recognizes the output. */
     kind?: ErrorKind;

package/dist/format-rejections.d.ts

@@ -0,0 +1,6 @@
+/** How many times one sender's mail (same type and subject) is sent back for missing sections before it is delivered with a warning instead. */
+export declare const MAX_FORMAT_REJECTIONS = 2;
+export declare function formatRejectionKey(from: string, type: string, subject: string): string;
+export declare function formatRejections(runDir: string, key: string): number;
+/** Record one more rejection for `key` and return the new count. */
+export declare function countFormatRejection(runDir: string, key: string): number;

package/dist/format-rejections.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+/** How many times one sender's mail (same type and subject) is sent back for missing sections before it is delivered with a warning instead. */
+export const MAX_FORMAT_REJECTIONS = 2;
+const FILE = "format-rejections.json";
+export function formatRejectionKey(from, type, subject) {
+    return `${from}|${type}|${subject.trim().toLowerCase()}`;
+}
+function load(runDir) {
+    try {
+        const data = JSON.parse(fs.readFileSync(path.join(runDir, FILE), "utf8"));
+        return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function formatRejections(runDir, key) {
+    return load(runDir)[key] ?? 0;
+}
+/** Record one more rejection for `key` and return the new count. */
+export function countFormatRejection(runDir, key) {
+    const all = load(runDir);
+    const n = (all[key] ?? 0) + 1;
+    all[key] = n;
+    atomicWrite(path.join(runDir, FILE), `${JSON.stringify(all, null, 2)}\n`);
+    return n;
+}

package/dist/guard.js

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { commonFile, mayEditProtected, repoInstructionFiles, sharedIndex } from "./policy.js";
+import { mayEditProtected, repoInstructionFiles, sharedContextFiles, sharedIndex } from "./policy.js";
 export const MAX_KEEP_BYTES = 1024 * 1024;
 function safeName(file) {
     return file.replace(/[\\/:]/g, "_").replace(/^_+/, "");
@@ -29,7 +29,8 @@ export class ProtectedGuard {
         const files = new Set();
         for (const a of Object.values(project.agents))
             files.add(a.agentMd);
-        files.add(commonFile(project));
+        for (const f of sharedContextFiles(project))
+            files.add(f);
         for (const f of repoInstructionFiles(project))
             files.add(f);
         const handoff = sharedIndex(project);

package/dist/mailbox.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import YAML from "yaml";
 import { formatWarning, missingSections, parseSteps } from "./format.js";
 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 { must } from "./assert.js";
@@ -279,6 +280,15 @@ export function routeOutboxes(project) {
                 reject(why + ".");
                 continue;
             }
+            const missing = missingSections(type, parsed.body);
+            if (missing.length && project.run?.layout === "run") {
+                const key = formatRejectionKey(sender.name, type, subject);
+                if (formatRejections(project.run.dir, key) < MAX_FORMAT_REJECTIONS) {
+                    const n = countFormatRejection(project.run.dir, key);
+                    reject(`this ${type} is missing required section(s): ${missing.map((s) => `\`## ${s}\``).join(", ")}. Add them (write \`None\` where a section is empty) and send it again. (Attempt ${n} of ${MAX_FORMAT_REJECTIONS}; after that it is delivered with a warning.)`);
+                    continue;
+                }
+            }
             const replyTo = d.reply_to ? String(d.reply_to) : undefined;
             const thread = d.thread ? String(d.thread) : undefined;
             // Mail whose delivery was already planned (a replay after a crash) is not a repeat of itself.
@@ -308,7 +318,6 @@ export function routeOutboxes(project) {
                 });
                 res.rejected.push({ from: sender.name, file, reason: `duplicate: ${repeatNote()}` });
             }
-            const missing = missingSections(type, parsed.body);
             const body = missing.length ? `${formatWarning(type, missing)}\n\n${parsed.body}` : parsed.body;
             if (sender.name === project.lead) {
                 const st = parseSteps(parsed.body);

package/dist/policy.d.ts

@@ -23,6 +23,13 @@ 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;
+/** 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;
 export declare function inboxDir(project: ResolvedProject, agent: string): string;
 /** The repo's own CLAUDE.md/AGENTS.md: in the lead's worktree when it has one (concurrent runs), else in the repo. */

package/dist/policy.js

@@ -4,6 +4,22 @@ 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");
+}
+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");
+}
+/** 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)];
+}
 export function outboxDir(project, agent) {
     return path.join(project.paths.outboxRoot, agent);
 }
@@ -77,7 +93,7 @@ export function writePolicy(project, agent) {
     ];
     const allowFiles = [];
     if (isLead)
-        allowFiles.push(commonFile(project));
+        allowFiles.push(...sharedContextFiles(project));
     if (mayWriteShared && sharedIdx)
         allowFiles.push(sharedIdx);
     if (agent.canEditAgentMd) {
@@ -100,7 +116,8 @@ export function writePolicy(project, agent) {
             deny.push(outboxDir(project, a.name));
         deny.push(inboxDir(project, a.name));
     }
-    addDeny(commonFile(project));
+    for (const f of sharedContextFiles(project))
+        addDeny(f);
     for (const f of repoInstructionFiles(project))
         addDeny(f);
     if (shared && !mayWriteShared)

package/dist/prompt.d.ts

@@ -4,6 +4,8 @@ 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. */
+export declare const CONTEXT_LIMIT: number;
 export declare const LEAD_BATCH_LIMIT = 5;
 export declare function readPersona(agent: ResolvedAgent): string;
 /** The protocol of an agent working alone: no teammates, no ask. `run --agent` still ends with a `done` mail; `call` just answers. */
@@ -12,7 +14,7 @@ export declare function buildSoloSystemPrompt(project: ResolvedProject, agent: R
 export declare function buildCallUserPrompt(agent: ResolvedAgent, task: string): string;
 /** Everything that goes to the runtime's system prompt: the persona plus the team protocol. */
 export declare function buildSystemPrompt(project: ResolvedProject, agent: ResolvedAgent): string;
-/** 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 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 TidyContext {

package/dist/prompt.js

@@ -2,7 +2,7 @@ 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 { archiveFile, commonFile, decisionsFile, lessonsFile, memoryDirs, outboxDir, repoDirFor, sharedDir, sharedIndex } from "./policy.js";
 function memoryLabel(agent, dir) {
     if (dir === agent.memory.task)
         return "task (this task only, isolated)";
@@ -11,6 +11,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;
 export const LEAD_BATCH_LIMIT = 5;
 const BATCHABLE = new Set(["reply", "failure"]);
 const readCapped = readFileCapped;
@@ -88,7 +90,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 +132,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 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.`,
+        ]
+        : []), 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 +168,17 @@ 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)],
+    ]) {
+        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 handoffFile = handoff ? sharedIndex(project) : undefined;
     const notes = handoffFile ? readCapped(handoffFile, HANDOFF_LIMIT) : undefined;
     if (handoffFile && notes?.text.trim()) {

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 in \`DECISIONS.md\` and what the project learned in \`LESSONS.md\` (next to \`COMMON.md\`); later runs start from them.
 - 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.22.0",
   "description": "Config + dispatcher for teams of Claude Code / Codex agents with scoped context and file-based mailboxes",
   "keywords": [
     "ai",