agent-lyceum 0.5.0 → 0.6.0

package/README.md

@@ -30,13 +30,16 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 | `validate [-p name] [--task-file f]` | Validate the merged config and show each agent's enforcement level. [details](docs/commands.md#validate) |
 | `run ["task"] [--task-file f] [-p name]` | Give the task to the lead and run until done. [details](docs/commands.md#run) |
 | `resume [run-id] [-p name]` | Continue an interrupted or failed run. [details](docs/commands.md#resume) |
+| `answer <run-id> [--no-edit] [-p name]` | Answer the questions a waiting run asked, then continue it. [details](docs/commands.md#answer) |
 | `status [-p name] [--monitor]` | Show agents, mail, the current wake-up and past runs (`--json`, `--monitor`). [details](docs/commands.md#status) |
 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` | Delete a run with its task memory and worktrees. [details](docs/commands.md#clear) |
 | `config show --resolved [-p name] [--json]` | Print every effective setting and where it came from. [details](docs/commands.md#config-show) |
 | `doctor [-p name] [--json]` | Check config, git, the lock and runtime CLIs without running agents. [details](docs/commands.md#doctor) |
+| `memory tidy [-p name] [--agent a] [--layer project\|global] [--dry-run]` | Have agents tidy their own memory (manual only; archives, never deletes). [details](docs/commands.md#memory-tidy) |
+| `memory restore <timestamp> -p name --agent a` | Undo a tidy: move its archived files back. [details](docs/commands.md#memory-restore) |
 | `unlock [-p name] --force` | Remove the project lock a crashed run left behind. [details](docs/commands.md#unlock) |
 
-Ctrl-C cancels a run cleanly and it can be continued with `resume` ([Stopping a run](docs/commands.md#stopping-a-run)). `run` and `resume` exit `0` only when the lead reported `completed`, `2` for partial or blocked, `1` for failed, `130` for cancelled ([Exit codes](docs/commands.md#exit-codes)). Without `-p`, the project is inferred from the current directory ([Choosing the project](docs/commands.md#choosing-the-project)).
+Ctrl-C cancels a run cleanly and it can be continued with `resume` ([Stopping a run](docs/commands.md#stopping-a-run)). `run` and `resume` exit `0` only when the lead reported `completed`, `2` for partial or blocked, `1` for failed, `3` while waiting for your answers, `130` for cancelled ([Exit codes](docs/commands.md#exit-codes)). Without `-p`, the project is inferred from the current directory ([Choosing the project](docs/commands.md#choosing-the-project)).
 
 ## Monitor mod (Claude Code)
 
@@ -53,7 +56,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 **Use it.**
 - **Status line:** always on once loaded (`team 讀取中…` until the first poll, `team 無法取得狀態：…` when the CLI cannot run); shows the run state, round `n/max`, output tokens, the current step and unread mail. With several projects it shows one overview line (`team 1/3 running · a ... | b ...`).
 - **Toasts:** a message pops up when a run finishes, is interrupted, or an agent's wake fails (prefixed `[project]` when several are watched). Nothing to do.
-- **`/status-monitor`:** type it to open (or, if already open, close) the pane. It is off at session start unless `autoOpen` is set. In the **fullscreen layout** (`"tui": "fullscreen"` in `~/.claude/settings.json`, restart the session to apply; `/tui fullscreen` does the same) from 110 terminal columns it docks on the right at half the terminal width, and tabs and **關閉** (Close) can be clicked. Otherwise it shows above the prompt; the layout is fixed when the session starts, so a session started on the main screen stays that way. Keyboard (works in both): `x` closes, `1`-`9` or Tab/Enter switch task, Esc returns to the prompt, running the command again also closes. It shows, per project: the run id and state, task, progress and checklist, the agents working now and the queued mail, blocked integrations, notes and result summary, output tokens per runtime, per-agent wake statistics, the last 8 wakes. Each task (a project's current run and its last 3 past runs) is a tab. It refreshes with the polling interval while open.
+- **`/status-monitor`:** type it to open (or, if already open, close) the pane. It is off at session start unless `autoOpen` is set. In the **fullscreen layout** (`"tui": "fullscreen"` in `~/.claude/settings.json`, restart the session to apply; `/tui fullscreen` does the same) from 110 terminal columns it docks on the right at half the terminal width, and tabs and **關閉** (Close) can be clicked. Otherwise it shows above the prompt; the layout is fixed when the session starts, so a session started on the main screen stays that way. Keyboard (works in both): `x` closes, `1`-`9` or Tab/Enter switch task, Esc returns to the prompt, running the command again also closes. It shows, per project: the run id and state, task, progress and checklist, the agents working now and the queued mail, blocked integrations, notes and result summary, output tokens per runtime, per-agent wake statistics, the last 8 wakes. Each running task is a tab, newest first; finished and interrupted runs are not listed. It refreshes with the polling interval while open.
 
 **Configure it.** In `~/.claude/settings.json` under `pluginConfigs."status-monitor@inline"` (`options`):
 
@@ -93,7 +96,7 @@ agents:
   qa-member: { can_message: [lead], owns: ["tests/**"] }
 ```
 
-Agent fields: `runtime` (`claude-code`|`codex`; optional when `model` is recognizable: `opus`/`sonnet`/`haiku`/`claude-*` → Claude Code, `gpt-*`/`o3`/`*codex*` → Codex; precedence: project runtime > project model > global runtime > global model), `model`, `effort` (Claude Code: `low`|`medium`|`high`|`xhigh`|`max` via `--effort`; Codex: `minimal`|`low`|`medium`|`high`|`xhigh` via `model_reasoning_effort`; unset = CLI default), `agent_md`, `memory.global` / `memory.project`, `resume`, `can_message` (`all` or list; default `[lead]`, lead default `all`), `can_edit_agent_md` (default only the lead), `owns` (repo globs).
+Agent fields: `runtime` (`claude-code`|`codex`; optional when `model` is recognizable: `opus`/`sonnet`/`haiku`/`claude-*` → Claude Code, `gpt-*`/`o3`/`*codex*` → Codex; precedence: project runtime > project model > global runtime > global model), `model`, `effort` (Claude Code: `low`|`medium`|`high`|`xhigh`|`max` via `--effort`; Codex: `minimal`|`low`|`medium`|`high`|`xhigh` via `model_reasoning_effort`; unset = CLI default), `agent_md`, `memory.global` / `memory.project`, `resume`, `can_message` (`all` or list; default `[lead]`, lead default `all`), `can_edit_agent_md` (default only the lead), `can_ask_user` (may send `type: ask` mail to you and pause the run for an answer; default only the lead), `owns` (repo globs).
 
 Rules checked by `validate`: ≥ 2 agents (the lead and one member; the template has three), the lead is a listed agent, every agent has a runtime (explicit or inferred from `model`) and an existing `AGENT.md`, `effort` is valid for the agent's runtime (warning if `runtime` contradicts a recognizable `model`), `can_message` targets exist, memory dirs don't overlap, and with `max_parallel > 1` every non-lead agent needs non-overlapping `owns` and the repo must be a git repository.
 

package/README.zh-TW.md

@@ -30,13 +30,16 @@ npx agent-lyceum status
 | `validate [-p name] [--task-file f]` | 驗證設定並顯示每個 agent 的防護等級。 [詳細](docs/commands.zh-TW.md#validate) |
 | `run ["task"] [--task-file f] [-p name]` | 把任務交給 lead 並執行到結束。 [詳細](docs/commands.zh-TW.md#run) |
 | `resume [run-id] [-p name]` | 接續被中斷或失敗的 run。 [詳細](docs/commands.zh-TW.md#resume) |
+| `answer <run-id> [--no-edit] [-p name]` | 回答等待中的 run 提出的問題，並接續執行。 [詳細](docs/commands.zh-TW.md#answer) |
 | `status [-p name] [--monitor]` | 顯示 agent、信件、目前執行與歷次 run（支援 `--json`、`--monitor`）。 [詳細](docs/commands.zh-TW.md#status) |
 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` | 刪除 run 與其任務記憶、worktree。 [詳細](docs/commands.zh-TW.md#clear) |
 | `config show --resolved [-p name] [--json]` | 印出每項生效設定與其來源。 [詳細](docs/commands.zh-TW.md#config-show) |
 | `doctor [-p name] [--json]` | 不執行 agent，檢查設定、git、鎖與 runtime CLI。 [詳細](docs/commands.zh-TW.md#doctor) |
+| `memory tidy [-p name] [--agent a] [--layer project\|global] [--dry-run]` | 讓 agent 整理自己的記憶（只能手動觸發；封存而非刪除）。 [詳細](docs/commands.zh-TW.md#memory-tidy) |
+| `memory restore <時間戳> -p name --agent a` | 還原一次整理：把封存的檔案搬回。 [詳細](docs/commands.zh-TW.md#memory-restore) |
 | `unlock [-p name] --force` | 移除當機 run 留下的專案鎖。 [詳細](docs/commands.zh-TW.md#unlock) |
 
-Ctrl-C 會乾淨地取消 run，之後可用 `resume` 接續（[中止 run](docs/commands.zh-TW.md#中止-run)）。`run`／`resume` 只有在 lead 回報 `completed` 時才 exit `0`；`partial`／`blocked` 為 `2`，`failed` 為 `1`，取消為 `130`（[退出碼](docs/commands.zh-TW.md#退出碼)）。未指定 `-p` 時，專案由目前目錄推斷（[選擇專案](docs/commands.zh-TW.md#選擇專案)）。
+Ctrl-C 會乾淨地取消 run，之後可用 `resume` 接續（[中止 run](docs/commands.zh-TW.md#中止-run)）。`run`／`resume` 只有在 lead 回報 `completed` 時才 exit `0`；`partial`／`blocked` 為 `2`，`failed` 為 `1`，等待你回答時為 `3`，取消為 `130`（[退出碼](docs/commands.zh-TW.md#退出碼)）。未指定 `-p` 時，專案由目前目錄推斷（[選擇專案](docs/commands.zh-TW.md#選擇專案)）。
 
 ## 監控 mod（Claude Code）
 
@@ -53,7 +56,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 **操作。**
 - **狀態列：** 載入後常駐（第一次輪詢前顯示 `team 讀取中…`，CLI 跑不起來時顯示 `team 無法取得狀態：…`），顯示執行狀態、輪數 `n/max`、output tokens、目前步驟與未讀信件。監看多個專案時顯示一行總覽（`team 1/3 執行中 · a ... | b ...`）。
 - **通知：** 執行完成、被中斷或某個 agent 喚醒失敗時會跳出訊息（監看多個專案時前面加 `[專案名]`），不需要任何操作。
-- **`/status-monitor`：** 輸入即開啟面板（已開著則關閉）。session 啟動時預設不開，除非設定 `autoOpen`。在 **fullscreen 版面**（`~/.claude/settings.json` 設 `"tui": "fullscreen"` 後重開 session；`/tui fullscreen` 效果相同）且終端寬度 110 欄以上時，面板會靠右 dock 在終端寬度的一半，分頁與 **關閉** 都可以用滑鼠點。否則顯示在輸入框上方；版面在 session 啟動時就固定，從主畫面啟動的 session 不會變。鍵盤操作兩種版面都能用：`x` 關閉，`1`-`9` 或 Tab/Enter 切換任務，Esc 回到輸入框，再執行一次指令也會關閉。每個專案顯示：執行 id 與狀態、任務、進度與清單、正在工作的 agent 與排隊中的信件、受阻的整合、備註與結果摘要、各 runtime 的 output tokens、各 agent 的喚醒統計、最近 8 次喚醒。每個任務（專案目前的執行與最近 3 次過往執行）是一個分頁。面板開著時會依輪詢間隔自動更新。
+- **`/status-monitor`：** 輸入即開啟面板（已開著則關閉）。session 啟動時預設不開，除非設定 `autoOpen`。在 **fullscreen 版面**（`~/.claude/settings.json` 設 `"tui": "fullscreen"` 後重開 session；`/tui fullscreen` 效果相同）且終端寬度 110 欄以上時，面板會靠右 dock 在終端寬度的一半，分頁與 **關閉** 都可以用滑鼠點。否則顯示在輸入框上方；版面在 session 啟動時就固定，從主畫面啟動的 session 不會變。鍵盤操作兩種版面都能用：`x` 關閉，`1`-`9` 或 Tab/Enter 切換任務，Esc 回到輸入框，再執行一次指令也會關閉。每個專案顯示：執行 id 與狀態、任務、進度與清單、正在工作的 agent 與排隊中的信件、受阻的整合、備註與結果摘要、各 runtime 的 output tokens、各 agent 的喚醒統計、最近 8 次喚醒。每個執行中的任務是一個分頁，最新的排最前面；已結束或已中斷的不列出。面板開著時會依輪詢間隔自動更新。
 
 **設定。** 在 `~/.claude/settings.json` 的 `pluginConfigs."status-monitor@inline"`（`options`）：
 
@@ -94,7 +97,7 @@ agents:
   qa-member: { can_message: [lead], owns: ["tests/**"] }
 ```
 
-Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可省略：`opus`/`sonnet`/`haiku`/`claude-*` → Claude Code，`gpt-*`/`o3`/`*codex*` → Codex；優先順序：專案 runtime > 專案 model > 全域 runtime > 全域 model）、`model`、`effort`（Claude Code：`low`|`medium`|`high`|`xhigh`|`max`，經 `--effort`；Codex：`minimal`|`low`|`medium`|`high`|`xhigh`，經 `model_reasoning_effort`；未設則用 CLI 預設）、`agent_md`、`memory.global` / `memory.project`、`resume`、`can_message`（`all` 或清單；預設 `[lead]`，lead 預設 `all`）、`can_edit_agent_md`（預設只有 lead）、`owns`（repo glob）。
+Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可省略：`opus`/`sonnet`/`haiku`/`claude-*` → Claude Code，`gpt-*`/`o3`/`*codex*` → Codex；優先順序：專案 runtime > 專案 model > 全域 runtime > 全域 model）、`model`、`effort`（Claude Code：`low`|`medium`|`high`|`xhigh`|`max`，經 `--effort`；Codex：`minimal`|`low`|`medium`|`high`|`xhigh`，經 `model_reasoning_effort`；未設則用 CLI 預設）、`agent_md`、`memory.global` / `memory.project`、`resume`、`can_message`（`all` 或清單；預設 `[lead]`，lead 預設 `all`）、`can_edit_agent_md`（預設只有 lead）、`can_ask_user`（可用 `type: ask` 信件向你提問並暫停 run 等待回答；預設只有 lead）、`owns`（repo glob）。
 
 `validate` 檢查的規則：至少 2 個 agent（lead 加一位成員；範本預設是三位）、lead 在 agent 清單內、每個 agent 都有 runtime（明設或由 `model` 推斷）且 `AGENT.md` 存在、`effort` 對該 runtime 合法（若 `runtime` 與可辨識的 `model` 矛盾則警告）、`can_message` 的目標存在、記憶資料夾互不重疊，且當 `max_parallel > 1` 時，每個非 lead 的 agent 都必須有互不重疊的 `owns`，repo 也必須是 git repository。
 

package/dist/adapters/claude.js

@@ -35,6 +35,8 @@ export function buildClaudeSettings(project, agent) {
         allow.push(rule("Edit", f));
     const deny = pol.deny.flatMap(denyRules);
     return {
+        // The user's own and plugin hooks (e.g. a hook that asks the user a question) would block every tool call of a headless wake-up.
+        disableAllHooks: true,
         permissions: { allow, deny },
         sandbox: {
             enabled: true,

package/dist/ask-answer.d.ts

@@ -0,0 +1,10 @@
+export interface PrepareResult {
+    complete: boolean;
+    problems: string[];
+    path: string;
+}
+/** Read the ask-reply file of a waiting run. With `assumeDefaults`, unanswered questions that have a suggestion take it (and the file is saved). */
+export declare function prepareAnswers(runDir: string, opts: {
+    assumeDefaults?: boolean;
+}): PrepareResult;
+export declare function openInEditor(file: string, env?: NodeJS.ProcessEnv): void;

package/dist/ask-answer.js

@@ -0,0 +1,21 @@
+import { spawnSync } from "node:child_process";
+import { applyDefaults, askReplyPath, checkAnswers, describeCheck, isComplete, readAskReply, writeAskReply } from "./ask-reply.js";
+/** Read the ask-reply file of a waiting run. With `assumeDefaults`, unanswered questions that have a suggestion take it (and the file is saved). */
+export function prepareAnswers(runDir, opts) {
+    const file = askReplyPath(runDir);
+    let reply = readAskReply(runDir);
+    if (!reply)
+        return { complete: false, problems: ["ask-reply.md does not exist"], path: file };
+    if (opts.assumeDefaults) {
+        reply = applyDefaults(reply);
+        writeAskReply(runDir, reply);
+    }
+    const check = checkAnswers(reply);
+    return { complete: isComplete(check), problems: describeCheck(check), path: file };
+}
+export function openInEditor(file, env = process.env) {
+    const editor = env.VISUAL || env.EDITOR || "vi";
+    const r = spawnSync(`${editor} ${JSON.stringify(file)}`, { shell: true, stdio: "inherit", env });
+    if (r.error || (r.status ?? 0) !== 0)
+        throw new Error(`The editor "${editor}" failed${r.error ? `: ${r.error.message}` : ` (exit ${r.status})`}.`);
+}

package/dist/ask-reply.d.ts

@@ -0,0 +1,65 @@
+export declare const MAX_QUESTIONS_PER_ASK = 10;
+export declare const ASK_REPLY_FILE = "ask-reply.md";
+export type AnswerSource = "user" | "default";
+export interface AskQuestion {
+    id: string;
+    text: string;
+    options?: string[];
+    suggested?: {
+        value: string;
+        reason?: string;
+    };
+    /** The agent that asked; the answer goes back to it. */
+    asker: string;
+    answer?: {
+        value: string;
+        by: AnswerSource;
+    };
+    /** The answer was already sent to the asker. */
+    delivered?: boolean;
+}
+export interface AskReply {
+    status: "pending" | "answered";
+    /** Who asked the latest batch. */
+    askedBy: string;
+    /** The round of the latest batch. */
+    round: number;
+    questions: AskQuestion[];
+}
+export type NewQuestion = Omit<AskQuestion, "asker" | "answer" | "delivered">;
+export declare const askReplyPath: (runDir: string) => string;
+export declare function parseAskBody(body: string): {
+    ok: true;
+    questions: NewQuestion[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseAskReply(text: string): AskReply;
+export declare function renderAskReply(r: AskReply): string;
+export declare function readAskReply(runDir: string): AskReply | undefined;
+export declare function writeAskReply(runDir: string, r: AskReply): void;
+/** Add a batch of questions, keeping everything already in the file. The same id with the same text is skipped (a re-routed ask after a crash). */
+export declare function addBatch(existing: AskReply | undefined, asker: string, round: number, qs: NewQuestion[]): {
+    ok: true;
+    reply: AskReply;
+} | {
+    ok: false;
+    error: string;
+};
+export interface AnswerCheck {
+    missing: string[];
+    invalid: {
+        id: string;
+        reason: string;
+    }[];
+}
+export declare const isComplete: (c: AnswerCheck) => boolean;
+/** Only questions whose answer was not sent yet count. */
+export declare function checkAnswers(r: AskReply): AnswerCheck;
+export declare function describeCheck(c: AnswerCheck): string[];
+export declare function applyDefaults(r: AskReply): AskReply;
+export declare function askersWithAnswers(r: AskReply): string[];
+/** The body of the `reply` mail that carries the answers back to `asker`. */
+export declare function renderAnswers(r: AskReply, asker: string): string;
+export declare function markDelivered(r: AskReply): AskReply;

package/dist/ask-reply.js

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+export const MAX_QUESTIONS_PER_ASK = 10;
+export const ASK_REPLY_FILE = "ask-reply.md";
+export const askReplyPath = (runDir) => path.join(runDir, "mail", ASK_REPLY_FILE);
+// ---- a tiny reader for the few tags used here (no XML dependency) ----
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const unesc = (s) => s.replace(/&quot;/g, '"').replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+function tags(xml, name) {
+    const re = new RegExp(`<${name}((?:\\s+[\\w-]+="[^"]*")*)\\s*(?:/>|>([\\s\\S]*?)</${name}>)`, "g");
+    return [...xml.matchAll(re)].map((m) => {
+        const attrs = {};
+        for (const a of (m[1] ?? "").matchAll(/([\w-]+)="([^"]*)"/g))
+            attrs[a[1]] = unesc(a[2]);
+        return { attrs, inner: m[2] ?? "" };
+    });
+}
+const first = (xml, name) => tags(xml, name)[0];
+const textOf = (t) => unesc((t?.inner ?? "").trim());
+// ---- the body of an `ask` mail ----
+export function parseAskBody(body) {
+    const block = first(body, "ask");
+    if (!block)
+        return { ok: false, error: "the body has no <ask>…</ask> block" };
+    const found = tags(block.inner, "question");
+    if (found.length === 0)
+        return { ok: false, error: "the <ask> block needs at least one <question>" };
+    if (found.length > MAX_QUESTIONS_PER_ASK)
+        return { ok: false, error: `at most ${MAX_QUESTIONS_PER_ASK} questions per ask (got ${found.length}); ask the most important ones first` };
+    const seen = new Set();
+    const questions = [];
+    for (const [i, q] of found.entries()) {
+        const id = q.attrs.id?.trim();
+        if (!id || !/^[\w.-]+$/.test(id))
+            return { ok: false, error: `question ${i + 1} needs an id attribute made of letters, digits, "_", "-" or "."` };
+        if (seen.has(id))
+            return { ok: false, error: `duplicate question id "${id}"` };
+        seen.add(id);
+        const text = textOf(first(q.inner, "text"));
+        if (!text)
+            return { ok: false, error: `question "${id}" needs a non-empty <text>` };
+        const options = tags(first(q.inner, "options")?.inner ?? "", "option").map((o) => textOf(o)).filter(Boolean);
+        const sug = first(q.inner, "suggested");
+        const suggested = sug && textOf(sug) ? { value: textOf(sug), ...(sug.attrs.reason ? { reason: sug.attrs.reason } : {}) } : undefined;
+        if (suggested && options.length && !options.includes(suggested.value))
+            return { ok: false, error: `the suggested value of question "${id}" must be one of its options` };
+        questions.push({ id, text, ...(options.length ? { options } : {}), ...(suggested ? { suggested } : {}) });
+    }
+    return { ok: true, questions };
+}
+// ---- the ask-reply file ----
+export function parseAskReply(text) {
+    const root = first(text, "ask-reply");
+    if (!root)
+        throw new Error("ask-reply.md has no <ask-reply> root tag");
+    const askedBy = root.attrs.asked_by ?? "";
+    const questions = tags(root.inner, "question").map((q) => {
+        const ans = first(q.inner, "answer");
+        const value = textOf(ans);
+        const options = tags(first(q.inner, "options")?.inner ?? "", "option").map((o) => textOf(o));
+        const sug = first(q.inner, "suggested");
+        return {
+            id: q.attrs.id ?? "",
+            text: textOf(first(q.inner, "text")),
+            ...(options.length ? { options } : {}),
+            ...(sug && textOf(sug) ? { suggested: { value: textOf(sug), ...(sug.attrs.reason ? { reason: sug.attrs.reason } : {}) } } : {}),
+            asker: q.attrs.asker ?? askedBy,
+            ...(value ? { answer: { value, by: ans?.attrs.by === "default" ? "default" : "user" } } : {}),
+            ...(q.attrs.delivered === "true" ? { delivered: true } : {}),
+        };
+    });
+    return { status: root.attrs.status === "answered" ? "answered" : "pending", askedBy, round: Number(root.attrs.round) || 0, questions };
+}
+export function renderAskReply(r) {
+    const out = [`<ask-reply status="${r.status}" asked_by="${esc(r.askedBy)}" round="${r.round}">`];
+    for (const q of r.questions) {
+        out.push(`  <question id="${esc(q.id)}" asker="${esc(q.asker)}"${q.delivered ? ` delivered="true"` : ""}>`);
+        out.push(`    <text>${esc(q.text)}</text>`);
+        if (q.options?.length)
+            out.push(`    <options>`, ...q.options.map((o) => `      <option>${esc(o)}</option>`), `    </options>`);
+        if (q.suggested)
+            out.push(`    <suggested${q.suggested.reason ? ` reason="${esc(q.suggested.reason)}"` : ""}>${esc(q.suggested.value)}</suggested>`);
+        out.push(q.answer ? `    <answer by="${q.answer.by}">${esc(q.answer.value)}</answer>` : `    <answer></answer>`);
+        out.push(`  </question>`);
+    }
+    out.push(`</ask-reply>`);
+    return out.join("\n") + "\n";
+}
+export function readAskReply(runDir) {
+    const file = askReplyPath(runDir);
+    if (!fs.existsSync(file))
+        return undefined;
+    return parseAskReply(fs.readFileSync(file, "utf8"));
+}
+export function writeAskReply(runDir, r) {
+    atomicWrite(askReplyPath(runDir), renderAskReply(r));
+}
+// ---- batches, answers ----
+/** Add a batch of questions, keeping everything already in the file. The same id with the same text is skipped (a re-routed ask after a crash). */
+export function addBatch(existing, asker, round, qs) {
+    const base = existing ?? { status: "pending", askedBy: asker, round, questions: [] };
+    const added = [];
+    for (const q of qs) {
+        const old = base.questions.find((x) => x.id === q.id);
+        if (old) {
+            if (old.text === q.text)
+                continue;
+            return { ok: false, error: `question id "${q.id}" is already used in this run for a different question; use a new id` };
+        }
+        added.push({ ...q, asker });
+    }
+    if (added.length === 0)
+        return { ok: true, reply: base };
+    return { ok: true, reply: { status: "pending", askedBy: asker, round, questions: [...base.questions, ...added] } };
+}
+export const isComplete = (c) => c.missing.length === 0 && c.invalid.length === 0;
+function problem(q) {
+    const v = q.answer?.value.trim();
+    if (!v)
+        return undefined;
+    if (q.options?.length && !q.options.includes(v) && !/^other:\s*\S/.test(v))
+        return `must be one of: ${q.options.join(", ")} — or start with "other:" and write your own`;
+    return undefined;
+}
+/** Only questions whose answer was not sent yet count. */
+export function checkAnswers(r) {
+    const c = { missing: [], invalid: [] };
+    for (const q of r.questions) {
+        if (q.delivered)
+            continue;
+        if (!q.answer?.value.trim())
+            c.missing.push(q.id);
+        else {
+            const reason = problem(q);
+            if (reason)
+                c.invalid.push({ id: q.id, reason });
+        }
+    }
+    return c;
+}
+export function describeCheck(c) {
+    return [...c.missing.map((id) => `${id}: no answer yet`), ...c.invalid.map((i) => `${i.id}: ${i.reason}`)];
+}
+export function applyDefaults(r) {
+    return {
+        ...r,
+        questions: r.questions.map((q) => (!q.delivered && !q.answer?.value.trim() && q.suggested ? { ...q, answer: { value: q.suggested.value, by: "default" } } : q)),
+    };
+}
+export function askersWithAnswers(r) {
+    return [...new Set(r.questions.filter((q) => !q.delivered && q.answer?.value.trim()).map((q) => q.asker))];
+}
+/** The body of the `reply` mail that carries the answers back to `asker`. */
+export function renderAnswers(r, asker) {
+    const out = [`<answers>`];
+    for (const q of r.questions.filter((x) => !x.delivered && x.asker === asker && x.answer?.value.trim())) {
+        out.push(`  <question id="${esc(q.id)}">`, `    <text>${esc(q.text)}</text>`, `    <answer by="${q.answer?.by}">${esc(q.answer?.value ?? "")}</answer>`, `  </question>`);
+    }
+    out.push(`</answers>`);
+    return out.join("\n");
+}
+export function markDelivered(r) {
+    return { ...r, status: "answered", questions: r.questions.map((q) => (q.answer?.value.trim() ? { ...q, delivered: true } : q)) };
+}

package/dist/cli.js

@@ -4,6 +4,8 @@ import path from "node:path";
 import readline from "node:readline/promises";
 import { Command } from "commander";
 import { ConfigError, findProjectForCwd, flattenResolved, listProjects, resolveProject, resolveProjectWithSources } from "./config.js";
+import { openInEditor, prepareAnswers } from "./ask-answer.js";
+import { restoreMemory, tidyMemory, tidyStamp } from "./memory-tidy.js";
 import { RESULT_FILE, runTeam } from "./dispatcher.js";
 import { executeRunCleanup, planRunCleanup } from "./run-cleanup.js";
 import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
@@ -177,7 +179,7 @@ function cancelOnSignals() {
         },
     };
 }
-function reportRun(summary, runDir) {
+function printRun(summary, runDir) {
     console.log(`\nRun ${summary.runId} ended: ${summary.endReason}, outcome: ${summary.outcome}, after ${summary.rounds} round(s). Logs: ${path.join(runDir, "log.jsonl")}`);
     if (summary.outcomeNote)
         console.log(`Note: ${summary.outcomeNote}`);
@@ -187,13 +189,72 @@ function reportRun(summary, runDir) {
         console.log(`\nLead's final message — ${summary.doneMessage.subject}\n\n${summary.doneMessage.body}`);
         console.log(`\nResult saved to: ${path.join(runDir, RESULT_FILE)}`);
     }
+}
+function reportRun(summary, runDir) {
+    printRun(summary, runDir);
     process.exit(exitCodeForOutcome(summary.outcome));
 }
+/** Take the lock and continue a run; the lock is released when it stops (also when it stops because it waits for answers). */
+async function continueRun(pr, dir, runId) {
+    const lease = takeLock(pr, runId);
+    const cancel = cancelOnSignals();
+    try {
+        console.log(`Project ${pr.name} — repo ${pr.dir}`);
+        const state = loadRunState(dir);
+        console.log(`Resuming run ${state.run_id} (${state.end_reason ?? "interrupted"}) at round ${state.rounds}/${pr.dispatcher.max_rounds}: ${state.task_summary}`);
+        // Read the state again under the lock: another process may have changed it while we were checking.
+        return await runTeam({ project: pr, resume: state, runDir: dir, signal: cancel.signal });
+    }
+    finally {
+        cancel.dispose();
+        lease.release();
+    }
+}
+const interactive = () => !!process.stdin.isTTY && !!process.stdout.isTTY;
+function printWaiting(pr, runId, file, problems) {
+    console.log(`\nRun ${runId} is waiting for your answers.\n  File: ${file}`);
+    for (const p of problems)
+        console.log(`  - ${p}`);
+    console.log(`Answer with: agent-lyceum answer ${runId} -p ${pr.name}   (or edit the file, then: agent-lyceum resume ${runId} -p ${pr.name})`);
+}
+/**
+ * Keep going while the run stops to ask and the questions can be settled right now: by --assume-defaults, or (in a terminal)
+ * by opening the editor. Otherwise print where to answer and exit 3.
+ */
+async function driveRun(pr, runDir, first, assumeDefaults) {
+    let summary = first;
+    while (summary.outcome === "waiting") {
+        let prep = prepareAnswers(runDir, { assumeDefaults });
+        while (!prep.complete && interactive()) {
+            console.log(`\nRun ${summary.runId} needs your answers (${prep.path}).`);
+            openInEditor(prep.path);
+            prep = prepareAnswers(runDir, {});
+            if (prep.complete)
+                break;
+            console.log("Some answers are missing or invalid:");
+            for (const p of prep.problems)
+                console.log(`  - ${p}`);
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const again = (await rl.question("Edit again? [Y/n] ")).trim().toLowerCase();
+            rl.close();
+            if (again === "n" || again === "no")
+                break;
+        }
+        if (!prep.complete) {
+            printRun(summary, runDir);
+            printWaiting(pr, summary.runId, prep.path, prep.problems);
+            process.exit(3);
+        }
+        summary = await continueRun(pr, runDir, summary.runId);
+    }
+    return reportRun(summary, runDir);
+}
 program
     .command("run [task]")
     .description('Start the dispatcher: give the task to the lead. Use "<task>" or --task-file <path>.')
     .option("-p, --project <name>")
     .option("--task-file <path>", "read the task from a file")
+    .option("--assume-defaults", "when the run stops to ask, use the suggested answer for every question that has one")
     .action(async (task, opts) => {
     try {
         const pr = loadProject(opts.project);
@@ -218,7 +279,7 @@ program
             cancel.dispose();
             lease.release();
         }
-        reportRun(summary, runDir);
+        await driveRun(pr, runDir, summary, !!opts.assumeDefaults);
     }
     catch (e) {
         fail(e instanceof ConfigError ? e.message : e.message);
@@ -228,6 +289,7 @@ program
     .command("resume [run-id]")
     .description("Continue an interrupted (or failed) run: same run dir, sessions and round count; the task is not re-sent. Without an id, picks the newest run that is not done or running; with an id, continues that run.")
     .option("-p, --project <name>")
+    .option("--assume-defaults", "if the run waits for answers, use the suggested answer for every unanswered question that has one")
     .action(async (runId, opts) => {
     try {
         const pr = loadProject(opts.project);
@@ -263,20 +325,51 @@ program
         }
         if (state.rounds >= pr.dispatcher.max_rounds)
             fail(`Run ${state.run_id} used ${state.rounds}/${pr.dispatcher.max_rounds} rounds; raise dispatcher.max_rounds in project.yaml first.`);
-        const lease = takeLock(pr, state.run_id);
-        let summary;
-        const cancel = cancelOnSignals();
-        try {
-            console.log(`Project ${pr.name} — repo ${pr.dir}`);
-            console.log(`Resuming run ${state.run_id} (${state.end_reason ?? "interrupted"}) at round ${state.rounds}/${pr.dispatcher.max_rounds}: ${state.task_summary}`);
-            // Read the state again under the lock: another process may have changed it while we were checking.
-            summary = await runTeam({ project: pr, resume: loadRunState(dir), runDir: dir, signal: cancel.signal });
+        if (state.end_reason === "waiting") {
+            const prep = prepareAnswers(dir, { assumeDefaults: !!opts.assumeDefaults });
+            if (!prep.complete) {
+                printWaiting(pr, state.run_id, prep.path, prep.problems);
+                process.exit(3);
+            }
         }
-        finally {
-            cancel.dispose();
-            lease.release();
+        const summary = await continueRun(pr, dir, state.run_id);
+        await driveRun(pr, dir, summary, !!opts.assumeDefaults);
+    }
+    catch (e) {
+        fail(e instanceof ConfigError ? e.message : e.message);
+    }
+});
+program
+    .command("answer <run-id>")
+    .description("Answer the questions a waiting run asked: opens ask-reply.md in $EDITOR, checks the answers, then continues the run. With --no-edit it only checks a file you already edited.")
+    .option("-p, --project <name>")
+    .option("--no-edit", "do not open the editor; check the file as it is")
+    .option("--assume-defaults", "use the suggested answer for every unanswered question that has one")
+    .action(async (runId, opts) => {
+    try {
+        assertName("run", runId);
+        const pr = loadProject(opts.project);
+        const dir = path.join(pr.paths.runs, runId);
+        if (!fs.existsSync(path.join(dir, "state.json")))
+            fail(`Run "${runId}" not found in ${pr.paths.runs}.`);
+        const state = loadRunState(dir);
+        if (state.end_reason !== "waiting")
+            fail(`Run ${runId} is not waiting for answers (${state.end_reason ?? "not finished"}).`);
+        if (opts.edit)
+            openInEditor(prepareAnswers(dir, {}).path);
+        const prep = prepareAnswers(dir, { assumeDefaults: !!opts.assumeDefaults });
+        if (!prep.complete) {
+            printWaiting(pr, runId, prep.path, prep.problems);
+            process.exit(3);
         }
-        reportRun(summary, dir);
+        const res = validateProject(pr);
+        for (const i of res.issues)
+            console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
+        if (!res.ok)
+            fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
+        await preflight(pr);
+        const summary = await continueRun(pr, dir, runId);
+        await driveRun(pr, dir, summary, !!opts.assumeDefaults);
     }
     catch (e) {
         fail(e instanceof ConfigError ? e.message : e.message);
@@ -407,6 +500,94 @@ program
         fail(e.message);
     }
 });
+const memoryCmd = program.command("memory").description("Look after the agents' long-term memory");
+function layerOpt(v) {
+    if (v === undefined || v === "project")
+        return "project";
+    if (v === "global")
+        return "global";
+    return fail(`--layer must be "project" or "global" (task memory is not tidied: \`clear\` deletes it).`);
+}
+memoryCmd
+    .command("tidy")
+    .description("Have agents tidy their own memory: merge duplicates, fix stale entries, archive what is obsolete (never deletes). Manual only; nothing triggers it automatically.")
+    .option("-p, --project <name>")
+    .option("--agent <name>", "tidy only this agent (default: every agent)")
+    .option("--layer <layer>", "project (default) or global; global memory is shared by every project, so it is never tidied unless you ask")
+    .option("--dry-run", "only show the memory sizes and what changed in the project; wake nobody, change nothing")
+    .action(async (opts) => {
+    try {
+        const layer = layerOpt(opts.layer);
+        const pr = loadProject(opts.project);
+        if (opts.dryRun) {
+            const dry = await tidyMemory({ project: pr, layer, agent: opts.agent, dryRun: true });
+            if (dry.length === 0)
+                console.log(`No agent has ${layer} memory configured. ${layer === "project" ? "The template gives agents global memory only: set `memory.project` for an agent in project.yaml (or use --layer global)." : "Set `memory.global` for an agent."}`);
+            return;
+        }
+        const res = validateProject(pr);
+        for (const i of res.issues)
+            console.error(`${i.level === "error" ? "ERROR" : "warn "}  ${i.message}`);
+        if (!res.ok)
+            fail("Configuration is invalid; fix the errors above (see `agent-lyceum validate`).");
+        await preflight(pr);
+        const lease = takeLock(pr, `tidy-${tidyStamp()}`);
+        const cancel = cancelOnSignals();
+        let results;
+        try {
+            results = await tidyMemory({ project: pr, layer, agent: opts.agent, signal: cancel.signal });
+        }
+        finally {
+            cancel.dispose();
+            lease.release();
+        }
+        if (results.length === 0)
+            console.log(`No agent has ${layer} memory configured. ${layer === "project" ? "The template gives agents global memory only: set `memory.project` for an agent in project.yaml (or tidy global memory with --layer global)." : "Set `memory.global` for an agent."}`);
+        for (const r of results) {
+            if (r.status === "tidied")
+                console.log(`  ${r.agent} (${r.layer}): tidied. Archive: ${path.join(r.dir, ".archive", r.archive ?? "")} — undo with: agent-lyceum memory restore ${r.archive} -p ${pr.name} --agent ${r.agent}${r.layer === "global" ? " --layer global" : ""}`);
+            else if (r.status === "skipped")
+                console.log(`  ${r.agent} (${r.layer}): skipped — ${r.problems.join("; ")}`);
+            else if (r.status === "failed") {
+                console.error(`  ${r.agent} (${r.layer}): FAILED, memory restored to how it was`);
+                for (const p of r.problems)
+                    console.error(`    - ${p}`);
+            }
+        }
+        process.exit(results.some((r) => r.status === "failed") ? 1 : 0);
+    }
+    catch (e) {
+        fail(e instanceof ConfigError ? e.message : e.message);
+    }
+});
+memoryCmd
+    .command("restore <stamp>")
+    .description("Move the files of one tidy's archive back (nothing that exists now is overwritten) and re-add them to MEMORY.md")
+    .option("-p, --project <name>")
+    .requiredOption("--agent <name>")
+    .option("--layer <layer>", "project (default) or global")
+    .action((stamp, opts) => {
+    try {
+        const layer = layerOpt(opts.layer);
+        const pr = loadProject(opts.project);
+        const lease = takeLock(pr, `restore-${tidyStamp()}`);
+        try {
+            const r = restoreMemory({ project: pr, agent: opts.agent, layer, stamp });
+            for (const f of r.restored)
+                console.log(`  restored  ${f}`);
+            for (const s of r.skipped)
+                console.log(`  skipped   ${s.rel}: ${s.reason}`);
+            if (!r.restored.length && !r.skipped.length)
+                console.log(`Archive ${stamp} holds no files to restore.`);
+        }
+        finally {
+            lease.release();
+        }
+    }
+    catch (e) {
+        fail(e.message);
+    }
+});
 function useColor() {
     if (process.env.NO_COLOR)
         return false;

package/dist/config.d.ts

@@ -18,6 +18,8 @@ export interface ResolvedAgent {
     resume: boolean;
     canMessage: "all" | string[];
     canEditAgentMd: boolean;
+    /** May send `type: ask` mail to the user (the run then waits for the answer). */
+    canAskUser: boolean;
     owns: string[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
@@ -53,6 +55,7 @@ export declare function loadGlobal(home: string): {
         resume?: boolean | undefined;
         can_message?: "all" | string[] | undefined;
         can_edit_agent_md?: boolean | undefined;
+        can_ask_user?: boolean | undefined;
         owns?: string[] | undefined;
     }>;
 };
@@ -82,6 +85,7 @@ export declare function loadProjectRaw(home: string, name: string): {
         resume?: boolean | undefined;
         can_message?: "all" | string[] | undefined;
         can_edit_agent_md?: boolean | undefined;
+        can_ask_user?: boolean | undefined;
         owns?: string[] | undefined;
     }>;
 };