agent-lyceum 0.5.0 → 0.6.0

package/dist/config.js

@@ -130,11 +130,13 @@ export function resolveProject(home, name) {
         const resume = pick("resume");
         const canMessage = pick("can_message");
         const canEdit = pick("can_edit_agent_md");
+        const canAsk = pick("can_ask_user");
         const owns = pick("owns");
         for (const [k, v] of [
             ["resume", resume],
             ["can_message", canMessage],
             ["can_edit_agent_md", canEdit],
+            ["can_ask_user", canAsk],
             ["owns", owns],
         ]) {
             if (v === undefined)
@@ -150,6 +152,7 @@ export function resolveProject(home, name) {
             resume: resume ?? isLead,
             canMessage: canMessage ?? (isLead ? "all" : [lead]),
             canEditAgentMd: canEdit ?? isLead,
+            canAskUser: canAsk ?? isLead,
             owns: owns ?? [],
             sources,
         };
@@ -198,7 +201,7 @@ export function findProjectForCwd(home, cwd) {
     }
     return best?.name;
 }
-const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "owns"];
+const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "can_ask_user", "owns"];
 /** The resolved project plus, for every setting, the file and key it was taken from (or "default"). */
 export function resolveProjectWithSources(home, name) {
     const project = resolveProject(home, name);
@@ -255,6 +258,7 @@ export function flattenResolved(project) {
         v[`${p}.resume`] = a.resume;
         v[`${p}.can_message`] = a.canMessage;
         v[`${p}.can_edit_agent_md`] = a.canEditAgentMd;
+        v[`${p}.can_ask_user`] = a.canAskUser;
         v[`${p}.owns`] = a.owns;
     }
     return v;

package/dist/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { tidyAdvice } from "./memory-tidy.js";
 import { inspectProjectLock, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
@@ -132,6 +133,8 @@ export async function diagnoseProject(project, opts = {}) {
             message: alive ? `A run is active: ${lock.run_id} (pid ${lock.pid}).` : `A stale run lock is left by ${lock.run_id} (pid ${lock.pid} is gone); \`agent-lyceum unlock --force\` clears it.`,
         });
     }
+    for (const a of tidyAdvice(project))
+        checks.push({ level: "info", subject: "memory", message: `${a.agent}: ${a.reason}. Consider: agent-lyceum memory tidy -p ${project.name} --agent ${a.agent} (doctor only suggests; it never tidies).` });
     const runtimes = await probeProjectRuntimes(project, opts);
     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/mailbox.d.ts

@@ -3,7 +3,7 @@ import { type Step } from "./format.js";
 import { atomicWrite } from "./fs-util.js";
 import { RouteJournal } from "./message-store.js";
 export { atomicWrite };
-export declare const MESSAGE_TYPES: readonly ["task", "reply", "failure", "done"];
+export declare const MESSAGE_TYPES: readonly ["task", "reply", "failure", "done", "ask"];
 export type MessageType = (typeof MESSAGE_TYPES)[number];
 export interface MessageMeta {
     id: string;
@@ -88,6 +88,14 @@ export interface RouteResult {
         file: string;
         meta: Record<string, unknown>;
     };
+    /** Questions for the user. Like `done`, the file stays in the outbox until the caller has stored the questions. */
+    asks: {
+        from: string;
+        subject: string;
+        body: string;
+        file: string;
+        source: string;
+    }[];
     /** Latest `## Steps` checklist the lead sent, if any. */
     steps?: Step[];
 }

package/dist/mailbox.js

@@ -8,7 +8,7 @@ import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-stor
 import { inboxDir, outboxDir } from "./policy.js";
 import { must } from "./assert.js";
 export { atomicWrite };
-export const MESSAGE_TYPES = ["task", "reply", "failure", "done"];
+export const MESSAGE_TYPES = ["task", "reply", "failure", "done", "ask"];
 export function newId() {
     return crypto.randomBytes(3).toString("hex");
 }
@@ -165,7 +165,7 @@ export function rejectDone(file) {
 }
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
 export function routeOutboxes(project) {
-    const res = { delivered: [], rejected: [], warnings: [] };
+    const res = { delivered: [], rejected: [], warnings: [], asks: [] };
     const journal = project.run ? new RouteJournal(project.run.dir) : undefined;
     for (const sender of Object.values(project.agents)) {
         const dir = outboxDir(project, sender.name);
@@ -207,10 +207,18 @@ export function routeOutboxes(project) {
             }
             const type = (d.type ?? "reply");
             if (!MESSAGE_TYPES.includes(type) || type === "failure") {
-                reject(`unknown or not allowed message type "${String(d.type)}" (use task, reply or done).`);
+                reject(`unknown or not allowed message type "${String(d.type)}" (use task, reply, ask or done).`);
                 continue;
             }
             const subject = String(d.subject ?? "(no subject)");
+            if (type === "ask") {
+                if (!sender.canAskUser) {
+                    reject(`you may not ask the user directly (can_ask_user is off for "${sender.name}"). Put the question in a reply to the lead ("${project.lead}"), who can ask.`);
+                    continue;
+                }
+                res.asks.push({ from: sender.name, subject, body: parsed.body, file, source });
+                continue;
+            }
             if (type === "done") {
                 if (sender.name !== project.lead) {
                     reject(`only the lead ("${project.lead}") may send a "done" message.`);

package/dist/memory-tidy.d.ts

@@ -0,0 +1,115 @@
+import { type Invoker } from "./adapters/index.js";
+import type { ResolvedProject } from "./config.js";
+export type Layer = "project" | "global";
+export declare const ARCHIVE_DIR = ".archive";
+export declare const TIDY_STATE_FILE = ".tidy-state.json";
+export declare const TIDY_REPORT_FILE = "tidy-report.md";
+export declare const STAMP_RE: RegExp;
+/** `20261008T031500Z`: UTC, sortable, safe in a file name. */
+export declare const tidyStamp: (d?: Date) => string;
+export interface MemoryTarget {
+    agent: string;
+    layer: Layer;
+    dir: string;
+}
+/** The memory directories to tidy. Without `agent`, every agent that has a directory for the layer; with it, that agent or an error. */
+export declare function targetsFor(project: ResolvedProject, opts: {
+    layer: Layer;
+    agent?: string;
+}): MemoryTarget[];
+export interface MemoryFile {
+    rel: string;
+    bytes: number;
+    mtime: string;
+}
+/** Every file under `dir` (the archive included, the state file not), `/`-separated and sorted. */
+export declare function listMemoryFiles(dir: string): MemoryFile[];
+export interface MemoryStats {
+    files: number;
+    bytes: number;
+    indexBytes: number;
+    oldest?: string;
+    newest?: string;
+}
+/** Size and age of the live files (the archive is not counted). */
+export declare function memoryStats(dir: string): MemoryStats;
+/** Content hash of every file (the archive included), to tell whether a directory changed. */
+export declare function fingerprint(dir: string): Record<string, string>;
+/** Copy each directory aside (a directory that does not exist is remembered as absent). */
+export declare function snapshotDirs(dirs: string[], into: string): void;
+/** Put each directory back as `snapshotDirs` saw it, removing whatever was added since. */
+export declare function restoreDirs(dirs: string[], from: string): void;
+/**
+ * Nothing may disappear: every file that existed before is still in place, or archived under the same relative
+ * path in this tidy's archive folder. Earlier archives must stay as they were; MEMORY.md is never archived.
+ */
+export declare function verifyConservation(before: string[], dir: string, stamp: string): string[];
+export interface TidyState {
+    /** HEAD of the project repo when the last tidy finished. */
+    head?: string;
+    at: string;
+    /** The archive folder of that tidy. */
+    archive?: string;
+}
+export declare function readTidyState(dir: string): TidyState | undefined;
+export declare function writeTidyState(dir: string, st: TidyState): void;
+export interface ProjectChanges {
+    head?: string;
+    since?: string;
+    log: string[];
+    stat: string[];
+    note?: string;
+}
+export declare function projectChanges(repoDir: string, since?: string): ProjectChanges;
+export interface MissingPath {
+    file: string;
+    path: string;
+}
+/** Backticked paths in the live Markdown files of `dir` that do not exist. Relative ones are looked up in `repoDir` (skipped without it). */
+export declare function findMissingPaths(dir: string, repoDir: string | undefined): MissingPath[];
+export interface TidyOptions {
+    project: ResolvedProject;
+    layer: Layer;
+    agent?: string;
+    dryRun?: boolean;
+    invoker?: Invoker;
+    signal?: AbortSignal;
+    say?: (line: string) => void;
+    now?: () => Date;
+}
+export interface TidyResult {
+    agent: string;
+    layer: Layer;
+    dir: string;
+    status: "tidied" | "skipped" | "failed" | "dry-run";
+    /** The archive stamp of a finished tidy. */
+    archive?: string;
+    problems: string[];
+}
+/** Scratch space of one tidy (snapshot and the invocation's logs); outside every memory dir and every run. */
+export declare const tidyWorkDir: (project: ResolvedProject, stamp: string, agent: string) => string;
+/** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum memory tidy`). */
+export declare function tidyMemory(o: TidyOptions): Promise<TidyResult[]>;
+export interface RestoreResult {
+    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. */
+export declare function restoreMemory(o: {
+    project: ResolvedProject;
+    agent: string;
+    layer: Layer;
+    stamp: string;
+}): RestoreResult;
+/** The stamps of the archives in a memory directory, oldest first. */
+export declare function listArchives(dir: string): string[];
+export declare const ADVICE_COMMITS = 50;
+export interface TidyAdvice {
+    agent: string;
+    reason: string;
+}
+/** Hints only: project memory whose index is larger than what an agent is shown, or whose baseline is far behind. Never acts. */
+export declare function tidyAdvice(project: ResolvedProject): TidyAdvice[];

package/dist/memory-tidy.js

@@ -0,0 +1,351 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+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 { buildTidyPrompts, MEMORY_INDEX_LIMIT } from "./prompt.js";
+import { git, isGitRepo } from "./worktree.js";
+export const ARCHIVE_DIR = ".archive";
+export const TIDY_STATE_FILE = ".tidy-state.json";
+export const TIDY_REPORT_FILE = "tidy-report.md";
+export const STAMP_RE = /^\d{8}T\d{6}Z$/;
+/** `20261008T031500Z`: UTC, sortable, safe in a file name. */
+export const tidyStamp = (d = new Date()) => d.toISOString().replace(/[-:]/g, "").replace(/\.\d+Z$/, "Z");
+/** The memory directories to tidy. Without `agent`, every agent that has a directory for the layer; with it, that agent or an error. */
+export function targetsFor(project, opts) {
+    const pick = (name) => {
+        const dir = project.agents[name]?.memory[opts.layer];
+        return dir ? { agent: name, layer: opts.layer, dir } : undefined;
+    };
+    if (opts.agent) {
+        if (!project.agents[opts.agent])
+            throw new Error(`No agent "${opts.agent}" in project ${project.name}. Agents: ${Object.keys(project.agents).join(", ")}.`);
+        const t = pick(opts.agent);
+        if (!t)
+            throw new Error(`Agent "${opts.agent}" has no ${opts.layer} memory directory.`);
+        return [t];
+    }
+    return Object.keys(project.agents).flatMap((n) => pick(n) ?? []);
+}
+function walk(dir, base, out) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            walk(full, base, out);
+        else if (e.isFile()) {
+            const rel = path.relative(base, full).split(path.sep).join("/");
+            if (rel === TIDY_STATE_FILE)
+                continue;
+            const st = fs.statSync(full);
+            out.push({ rel, bytes: st.size, mtime: st.mtime.toISOString() });
+        }
+    }
+}
+/** Every file under `dir` (the archive included, the state file not), `/`-separated and sorted. */
+export function listMemoryFiles(dir) {
+    const out = [];
+    walk(dir, dir, out);
+    return out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+}
+/** Size and age of the live files (the archive is not counted). */
+export function memoryStats(dir) {
+    const live = listMemoryFiles(dir).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`));
+    const times = live.map((f) => f.mtime).sort();
+    return {
+        files: live.length,
+        bytes: live.reduce((n, f) => n + f.bytes, 0),
+        indexBytes: live.find((f) => f.rel === "MEMORY.md")?.bytes ?? 0,
+        oldest: times[0],
+        newest: times.at(-1),
+    };
+}
+/** Content hash of every file (the archive included), to tell whether a directory changed. */
+export function fingerprint(dir) {
+    const out = {};
+    for (const f of listMemoryFiles(dir))
+        out[f.rel] = crypto.createHash("sha256").update(fs.readFileSync(path.join(dir, f.rel))).digest("hex");
+    return out;
+}
+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) {
+    fs.rmSync(into, { recursive: true, force: true });
+    fs.mkdirSync(into, { recursive: true });
+    dirs.forEach((d, i) => {
+        if (fs.existsSync(d))
+            fs.cpSync(d, slot(into, i), { recursive: true });
+    });
+}
+/** Put each directory back as `snapshotDirs` saw it, removing whatever was added since. */
+export function restoreDirs(dirs, from) {
+    dirs.forEach((d, i) => {
+        fs.rmSync(d, { recursive: true, force: true });
+        if (fs.existsSync(slot(from, i)))
+            fs.cpSync(slot(from, i), d, { recursive: true });
+    });
+}
+/**
+ * Nothing may disappear: every file that existed before is still in place, or archived under the same relative
+ * path in this tidy's archive folder. Earlier archives must stay as they were; MEMORY.md is never archived.
+ */
+export function verifyConservation(before, dir, stamp) {
+    const problems = [];
+    for (const rel of before) {
+        const here = fs.existsSync(path.join(dir, rel));
+        if (here)
+            continue;
+        const inArchive = !rel.startsWith(`${ARCHIVE_DIR}/`) && rel !== "MEMORY.md" && fs.existsSync(path.join(dir, ARCHIVE_DIR, stamp, rel));
+        if (!inArchive)
+            problems.push(rel === "MEMORY.md" ? `MEMORY.md is missing (the index must stay in place)` : `${rel} is gone: it is neither in place nor under ${ARCHIVE_DIR}/${stamp}/`);
+    }
+    return problems;
+}
+export function readTidyState(dir) {
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(dir, TIDY_STATE_FILE), "utf8"));
+        return j && typeof j === "object" && typeof j.at === "string" ? j : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function writeTidyState(dir, st) {
+    atomicWrite(path.join(dir, TIDY_STATE_FILE), JSON.stringify(st, null, 2));
+}
+const LOG_LINES = 50;
+const STAT_LINES = 40;
+function tryGit(cwd, args) {
+    try {
+        return git(cwd, args);
+    }
+    catch {
+        return undefined;
+    }
+}
+const lines = (s) => (s ? s.split("\n").filter(Boolean) : []);
+export function projectChanges(repoDir, since) {
+    if (!fs.existsSync(repoDir) || !isGitRepo(repoDir))
+        return { log: [], stat: [], note: "the project directory is not a git repository" };
+    const head = tryGit(repoDir, ["rev-parse", "HEAD"]);
+    if (!head)
+        return { log: [], stat: [], note: "the repository has no commits yet" };
+    if (!since)
+        return { head, log: [], stat: [], note: "first tidy: there is no earlier baseline, only the path check applies" };
+    if (since === head)
+        return { head, since, log: [], stat: [], note: "no commits since the last tidy" };
+    if (tryGit(repoDir, ["cat-file", "-t", `${since}^{commit}`]) !== "commit")
+        return { head, since, log: [], stat: [], note: "the baseline commit of the last tidy no longer exists in this repository (history was rewritten?)" };
+    const log = lines(tryGit(repoDir, ["log", "--oneline", "--no-decorate", `${since}..${head}`]));
+    const stat = lines(tryGit(repoDir, ["diff", "--stat", since, head]));
+    return {
+        head,
+        since,
+        log: log.length > LOG_LINES ? [...log.slice(0, LOG_LINES), `… and ${log.length - LOG_LINES} more commits`] : log,
+        stat: stat.length > STAT_LINES ? [...stat.slice(0, STAT_LINES - 1), stat.at(-1) ?? ""] : stat,
+    };
+}
+const PATH_TOKEN = /`([^`\n]+)`/g;
+function looksLikePath(t) {
+    if (!t.includes("/") || /\s/.test(t) || t.includes("://"))
+        return false;
+    if (/^-|[*?{}<>$|;&=]/.test(t))
+        return false;
+    return true;
+}
+/** Backticked paths in the live Markdown files of `dir` that do not exist. Relative ones are looked up in `repoDir` (skipped without it). */
+export function findMissingPaths(dir, repoDir) {
+    const seen = new Set();
+    const out = [];
+    for (const f of listMemoryFiles(dir)) {
+        if (f.rel.startsWith(`${ARCHIVE_DIR}/`) || !f.rel.endsWith(".md"))
+            continue;
+        const text = fs.readFileSync(path.join(dir, f.rel), "utf8");
+        for (const m of text.matchAll(PATH_TOKEN)) {
+            const tok = (m[1] ?? "").trim();
+            if (!looksLikePath(tok))
+                continue;
+            const abs = tok.startsWith("~/") ? path.join(os.homedir(), tok.slice(2)) : path.isAbsolute(tok) ? tok : repoDir ? path.join(repoDir, tok) : undefined;
+            if (!abs || fs.existsSync(abs))
+                continue;
+            const key = `${f.rel}\0${tok}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ file: f.rel, path: tok });
+        }
+    }
+    return out;
+}
+/** Scratch space of one tidy (snapshot and the invocation's logs); outside every memory dir and every run. */
+export const tidyWorkDir = (project, stamp, agent) => path.join(project.paths.root, "tidy-work", stamp, agent);
+const kb = (n) => (n < 1024 ? `${n} B` : `${(n / 1024).toFixed(1)} KiB`);
+function describeTarget(t, project, say) {
+    const s = memoryStats(t.dir);
+    say(`${t.agent} (${t.layer}): ${s.files} file(s), ${kb(s.bytes)}, MEMORY.md ${kb(s.indexBytes)}${s.oldest ? `, modified ${s.oldest.slice(0, 10)} … ${s.newest?.slice(0, 10)}` : ""}`);
+    if (t.layer === "project") {
+        const c = projectChanges(project.dir, readTidyState(t.dir)?.head);
+        say(`  project changes: ${c.note ?? `${c.log.length} commit(s) since ${c.since?.slice(0, 8)}`}`);
+    }
+    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) {
+    const { project } = o;
+    const say = o.say ?? ((s) => console.log(s));
+    const base = { agent: t.agent, layer: t.layer, dir: t.dir };
+    const agent = project.agents[t.agent];
+    const live = listMemoryFiles(t.dir).filter((f) => !f.rel.startsWith(`${ARCHIVE_DIR}/`));
+    if (live.length === 0)
+        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 othersBefore = others.map((d) => fingerprint(d));
+    const archiveDir = path.join(t.dir, 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 });
+    ensureProjectDirs(project);
+    snapshotDirs(dirs, snapshot);
+    const fail = (problems) => {
+        restoreDirs(dirs, snapshot);
+        fs.rmSync(snapshot, { recursive: true, force: true });
+        return { ...base, status: "failed", problems };
+    };
+    say(`tidying ${t.layer} memory of ${t.agent} (${live.length} file(s)) …`);
+    const invoke = o.invoker ?? realInvoker;
+    const result = await invoke({
+        project,
+        agent,
+        workDir,
+        systemPrompt: prompts.systemPrompt,
+        userPrompt: prompts.userPrompt,
+        timeoutSec: project.dispatcher.wake_timeout_sec,
+        signal: o.signal,
+        logDir: path.join(workDir, "log"),
+    }).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`);
+    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: [] };
+}
+/** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum memory 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 results = [];
+    for (const t of targets) {
+        if (o.dryRun) {
+            describeTarget(t, o.project, say);
+            results.push({ agent: t.agent, layer: t.layer, dir: t.dir, status: "dry-run", problems: [] });
+            continue;
+        }
+        const r = await tidyOne(o, t, tidyStamp(o.now?.()));
+        results.push(r);
+        if (o.signal?.aborted)
+            break;
+    }
+    return results;
+}
+function titleOf(file, rel) {
+    const text = fs.readFileSync(file, "utf8");
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    const name = fm ? /^name:\s*(.+)$/m.exec(fm[1] ?? "")?.[1]?.trim() : undefined;
+    if (name)
+        return name;
+    const h = /^#\s+(.+)$/m.exec(text)?.[1]?.trim();
+    return h || path.basename(rel, path.extname(rel));
+}
+function pruneEmpty(dir, stop) {
+    for (let d = dir; d !== stop && d.startsWith(stop + path.sep); d = path.dirname(d)) {
+        if (fs.readdirSync(d).length)
+            break;
+        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)"}.`);
+    const restored = [];
+    const skipped = [];
+    const inArchive = listMemoryFiles(archive).filter((f) => f.rel !== TIDY_REPORT_FILE);
+    for (const f of inArchive) {
+        const from = path.join(archive, f.rel);
+        const to = path.join(t.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;
+        }
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.renameSync(from, to);
+        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 };
+}
+/** The stamps of the archives in a memory directory, oldest first. */
+export function listArchives(dir) {
+    try {
+        return fs.readdirSync(path.join(dir, ARCHIVE_DIR)).filter((n) => STAMP_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+}
+export const ADVICE_COMMITS = 50;
+/** Hints only: project memory whose index is larger than what an agent is shown, or whose baseline is far behind. Never acts. */
+export function tidyAdvice(project) {
+    const out = [];
+    for (const t of targetsFor(project, { layer: "project" })) {
+        if (!fs.existsSync(t.dir))
+            continue;
+        const s = memoryStats(t.dir);
+        if (s.indexBytes > MEMORY_INDEX_LIMIT) {
+            out.push({ agent: t.agent, reason: `MEMORY.md is ${s.indexBytes} bytes, more than the ${MEMORY_INDEX_LIMIT} an agent is shown` });
+            continue;
+        }
+        const since = readTidyState(t.dir)?.head;
+        if (!since || !fs.existsSync(project.dir) || !isGitRepo(project.dir))
+            continue;
+        const n = Number(tryGit(project.dir, ["rev-list", "--count", `${since}..HEAD`]));
+        if (Number.isFinite(n) && n >= ADVICE_COMMITS)
+            out.push({ agent: t.agent, reason: `${n} commits since the last tidy` });
+    }
+    return out;
+}

package/dist/prompt.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedAgent, ResolvedProject } from "./config.js";
 import type { Message } from "./mailbox.js";
+import type { Layer, MemoryFile, MissingPath, ProjectChanges } from "./memory-tidy.js";
 export declare const COMMON_LIMIT: number;
 export declare const MEMORY_INDEX_LIMIT: number;
 export declare const LEAD_BATCH_LIMIT = 5;
@@ -9,3 +10,22 @@ export declare function buildSystemPrompt(project: ResolvedProject, agent: Resol
 /** 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. */
 export declare function pickMessages(project: ResolvedProject, agent: ResolvedAgent, queue: Message[]): Message[];
 export declare function buildUserPrompt(project: ResolvedProject, agent: ResolvedAgent, unread: Message[], handleCount?: number): string;
+export interface TidyContext {
+    layer: Layer;
+    /** The memory directory being tidied. */
+    dir: string;
+    /** Absolute path of this tidy's archive folder (the agent creates it). */
+    archiveDir: string;
+    /** Live files only (the archive is not listed). */
+    files: MemoryFile[];
+    /** MEMORY.md text ("" when there is none). */
+    index: string;
+    /** What changed in the project since the last tidy (project layer only). */
+    changes?: ProjectChanges;
+    missing: MissingPath[];
+}
+/** 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): {
+    systemPrompt: string;
+    userPrompt: string;
+};