agent-lyceum 0.4.14 → 0.6.0

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;
@@ -54,6 +54,8 @@ export declare function deliverOnce(project: ResolvedProject, journal: RouteJour
     fresh: boolean;
 };
 export declare function readMessage(file: string): Message;
+/** Paths of the unread messages in an agent's inbox, oldest name first. Does not open them. */
+export declare function unreadFiles(project: ResolvedProject, agent: string): string[];
 export declare function listUnread(project: ResolvedProject, agent: string): Message[];
 export declare function markRead(files: string[]): void;
 export interface RouteResult {
@@ -86,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

@@ -6,8 +6,9 @@ import { formatWarning, missingSections, parseSteps } from "./format.js";
 import { atomicWrite } from "./fs-util.js";
 import { deterministicId, fault, RouteJournal, sourceIdOf } from "./message-store.js";
 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");
 }
@@ -25,17 +26,17 @@ export function parseRaw(text) {
     const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
     if (!m)
         throw new Error("missing frontmatter (--- ... ---)");
-    const data = YAML.parse(m[1]);
+    const data = YAML.parse(m[1] ?? "");
     if (!data || typeof data !== "object" || Array.isArray(data))
         throw new Error("frontmatter is not a mapping");
-    return { data: data, body: m[2].trim() };
+    return { data: data, body: (m[2] ?? "").trim() };
 }
 export function ensureProjectDirs(project) {
     fs.mkdirSync(path.join(project.paths.shared, "common"), { recursive: true });
     for (const name of Object.keys(project.agents)) {
         fs.mkdirSync(path.join(inboxDir(project, name), "read"), { recursive: true });
         fs.mkdirSync(path.join(outboxDir(project, name), "rejected"), { recursive: true });
-        const a = project.agents[name];
+        const a = must(project.agents[name], `agent ${name}`);
         for (const m of [a.memory.global, a.memory.project, a.memory.task])
             if (m)
                 fs.mkdirSync(m, { recursive: true });
@@ -109,15 +110,19 @@ export function readMessage(file) {
     const meta = data;
     return { meta, body, file };
 }
-export function listUnread(project, agent) {
+/** Paths of the unread messages in an agent's inbox, oldest name first. Does not open them. */
+export function unreadFiles(project, agent) {
     const dir = inboxDir(project, agent);
     if (!fs.existsSync(dir))
         return [];
-    const files = fs
+    return fs
         .readdirSync(dir, { withFileTypes: true })
         .filter((e) => e.isFile() && e.name.endsWith(".md") && !e.name.startsWith("."))
         .map((e) => path.join(dir, e.name))
         .sort();
+}
+export function listUnread(project, agent) {
+    const files = unreadFiles(project, agent);
     const out = [];
     for (const f of files) {
         try {
@@ -160,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);
@@ -202,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/policy.js

@@ -1,6 +1,6 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { findOnPath } from "./fs-util.js";
 import { globStaticPrefix } from "./paths.js";
 export function commonFile(project) {
     return path.join(project.paths.shared, "common", "COMMON.md");
@@ -17,7 +17,7 @@ export function repoInstructionFiles(project) {
 export function memoryDirs(a) {
     return [a.memory.global, a.memory.project, a.memory.task].filter((x) => !!x);
 }
-const RUN_ENTRIES = ["state.json", "log.jsonl", "result.md", "task.md", "snapshots", "agents", "mail"];
+const RUN_ENTRIES = ["state.json", "log.jsonl", "log.1.jsonl", "result.md", "task.md", "snapshots", "violations", "agents", "mail"];
 const MAIL_ENTRIES = ["inbox", "claims", "attempts", "journal.jsonl"];
 function entries(dir) {
     try {
@@ -101,7 +101,7 @@ function osSandboxAvailable() {
     if (process.platform === "darwin")
         sandboxProbe = true;
     else if (process.platform === "linux")
-        sandboxProbe = spawnSync("which", ["bwrap"]).status === 0;
+        sandboxProbe = findOnPath("bwrap");
     else
         sandboxProbe = false;
     return sandboxProbe;

package/dist/process-runner.js

@@ -125,8 +125,7 @@ export function runInvocation(inv, opts) {
                 return;
             let text = partial + chunk.toString("utf8");
             partial = "";
-            let nl;
-            while ((nl = text.indexOf("\n")) >= 0) {
+            for (let nl = text.indexOf("\n"); nl >= 0; nl = text.indexOf("\n")) {
                 const line = text.slice(0, nl).replace(/\r$/, "");
                 text = text.slice(nl + 1);
                 if (skipping)

package/dist/project-lock.d.ts

@@ -3,7 +3,7 @@ export interface LockInfo {
     token: string;
     hostname: string;
     pid: number;
-    /** `ps` start time of `pid`, to tell the holder from a different process that reused the pid. */
+    /** Start time of `pid` (see `pidStartFrom`), to tell the holder from a different process that reused the pid. */
     pid_started?: string;
     run_id: string;
     acquired_at: string;
@@ -18,6 +18,15 @@ export interface ProjectLease {
 export interface LockOptions {
     heartbeatMs?: number;
 }
+/** Field 22 (starttime, in clock ticks) of a /proc/<pid>/stat line. The command name (field 2) may contain spaces and ")". */
+export declare function parseProcStat(text: string): string | undefined;
+export interface PidStartIo {
+    platform: NodeJS.Platform;
+    readFile(p: string): string | undefined;
+    ps(pid: number): string | undefined;
+}
+/** A start time that identifies one process: `proc:<ticks>` on Linux, the `ps` text elsewhere or when /proc cannot be read. */
+export declare function pidStartFrom(pid: number, io: PidStartIo): string | undefined;
 /** The lock of a project (`root` = the project's home directory), if one is held and readable. */
 export declare function inspectProjectLock(root: string): LockInfo | undefined;
 /**