agent-lyceum 0.9.0 → 0.9.2

package/README.md

@@ -26,15 +26,17 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 |---|---|---|
 | Project | `init [-y]` | Create the home and the global agent library. [details](docs/commands.md#init) |
 | Project | `project add <name> --dir <repo>` | Register a project. [details](docs/commands.md#project-add) |
-| Project | `project list` / `project remove <name> [--purge]` | List or unregister projects. [details](docs/commands.md#project-list-and-remove) |
+| Project | `project` / `project remove <name> [--purge]` | List or unregister projects. [details](docs/commands.md#project-and-project-remove) |
 | Diagnose | `doctor [-p name] [--task-file f] [--resolved] [--json]` | Check config (with enforcement levels), git, the lock and runtime CLIs without running agents; `--resolved` prints every effective setting and its source. [details](docs/commands.md#doctor) |
 | Diagnose | `status [-p name] [--monitor]` | Show agents, mail, the current wake-up and past runs (`--json`, `--monitor`). [details](docs/commands.md#status) |
 | Run | `run ["task"] [--task-file f] [--agent a] [-p name]` | Give the task to the lead and run until done; with `--agent`, to one member alone. [details](docs/commands.md#run) |
 | Run | `resume [run-id] [--answer] [-p name]` | Continue an interrupted or failed run; `--answer` first answers the questions it is waiting on. [details](docs/commands.md#resume) |
 | Run | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` / `clear --lock --force` | Delete a run with its task memory and worktrees; or remove the lock a crashed run left behind. [details](docs/commands.md#clear) |
 | Run | `call <agent> ["task"] [--task-file f] [--dir d]` | Call one global agent on its own, outside any project; prints its answer. [details](docs/commands.md#call) |
-| Run | `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) |
-| Run | `memory restore <timestamp> -p name --agent a` | Undo a tidy: move its archived files back. [details](docs/commands.md#memory-restore) |
+| Run | `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#tidy) |
+| Run | `tidy --undo <timestamp> -p name --agent a` | Undo a tidy: move its archived files back. [details](docs/commands.md#tidy) |
+
+`agent-lyceum --help` lists each command with a one-line summary; `agent-lyceum <command> --help` prints its full description and options.
 
 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)).
 

package/README.zh-TW.md

@@ -26,15 +26,17 @@ npx agent-lyceum status
 |---|---|---|
 | 專案 | `init [-y]` | 建立 home 與全域 agent 庫。 [詳細](docs/commands.zh-TW.md#init) |
 | 專案 | `project add <name> --dir <repo>` | 註冊專案。 [詳細](docs/commands.zh-TW.md#project-add) |
-| 專案 | `project list` / `project remove <name> [--purge]` | 列出或取消註冊專案。 [詳細](docs/commands.zh-TW.md#project-list-and-remove) |
+| 專案 | `project` / `project remove <name> [--purge]` | 列出或取消註冊專案。 [詳細](docs/commands.zh-TW.md#project-and-project-remove) |
 | 診斷 | `doctor [-p name] [--task-file f] [--resolved] [--json]` | 不執行 agent，檢查設定（含防護等級）、git、鎖與 runtime CLI；`--resolved` 印出每項生效設定與其來源。 [詳細](docs/commands.zh-TW.md#doctor) |
 | 診斷 | `status [-p name] [--monitor]` | 顯示 agent、信件、目前執行與歷次 run（支援 `--json`、`--monitor`）。 [詳細](docs/commands.zh-TW.md#status) |
 | 執行 | `run ["task"] [--task-file f] [--agent a] [-p name]` | 把任務交給 lead 並執行到結束；加 `--agent` 則只交給某個成員單獨做。 [詳細](docs/commands.zh-TW.md#run) |
 | 執行 | `resume [run-id] [--answer] [-p name]` | 接續被中斷或失敗的 run；`--answer` 會先回答它等待中的問題。 [詳細](docs/commands.zh-TW.md#resume) |
 | 執行 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` / `clear --lock --force` | 刪除 run 與其任務記憶、worktree；或移除當機 run 留下的專案鎖。 [詳細](docs/commands.zh-TW.md#clear) |
 | 執行 | `call <agent> ["task"] [--task-file f] [--dir d]` | 單獨呼叫一個 global agent（不需專案），印出它的回答。 [詳細](docs/commands.zh-TW.md#call) |
-| 執行 | `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) |
+| 執行 | `tidy [-p name] [--agent a] [--layer project\|global] [--dry-run]` | 讓 agent 整理自己的記憶（只能手動觸發；封存而非刪除）。 [詳細](docs/commands.zh-TW.md#tidy) |
+| 執行 | `tidy --undo <時間戳> -p name --agent a` | 還原一次整理：把封存的檔案搬回。 [詳細](docs/commands.zh-TW.md#tidy) |
+
+`agent-lyceum --help` 只列出每個指令的一行簡述；`agent-lyceum <指令> --help` 會印出該指令的完整說明與選項。
 
 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#選擇專案)）。
 

package/dist/cli.js

@@ -71,7 +71,17 @@ program
         console.log(`  kept     ${path.relative(h, f)}`);
     console.log(`\nNext: agent-lyceum project add <name> --dir <your-repo>`);
 });
-const project = program.command("project").description("Manage registered projects");
+const project = program
+    .command("project")
+    .summary("List registered projects, or add / remove one")
+    .description("Without a subcommand, list the registered projects.\n\nSubcommands:\n  - add <name> --dir <repo>: register a project\n  - remove <name> [--purge]: unregister one")
+    .action(() => {
+    const list = listProjects(home());
+    if (!list.length)
+        console.log("No projects registered.");
+    for (const p of list)
+        console.log(`${p.name}  ->  ${p.dir}`);
+});
 project
     .command("add <name>")
     .description("Register a project (config and context live in the home, not in the repo)")
@@ -85,16 +95,6 @@ project
         fail(e.message);
     }
 });
-project
-    .command("list")
-    .description("List registered projects")
-    .action(() => {
-    const list = listProjects(home());
-    if (!list.length)
-        console.log("No projects registered.");
-    for (const p of list)
-        console.log(`${p.name}  ->  ${p.dir}`);
-});
 project
     .command("remove <name>")
     .description("Unregister a project (keeps its context unless --purge)")
@@ -222,7 +222,8 @@ async function driveRun(pr, runDir, first, assumeDefaults) {
 }
 program
     .command("run [task]")
-    .description('Start the dispatcher: give the task to the lead. Use "<task>" or --task-file <path>. With --agent, give it to that one member alone.')
+    .summary("Start the dispatcher with a task for the lead")
+    .description('Start the dispatcher: give the task to the lead.\n\nGive the task either way:\n  - "<task>": as text\n  - --task-file <path>: from a file\n\nWho gets it:\n  - by default, the lead\n  - --agent <name>: that one member alone')
     .option("-p, --project <name>")
     .option("--task-file <path>", "read the task from a file")
     .option("--agent <name>", "run only this member of the project, alone: it cannot mail teammates or ask you, and its own `done` ends the run")
@@ -268,7 +269,8 @@ program
 });
 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.")
+    .summary("Continue an interrupted (or failed) run")
+    .description("Continue an interrupted (or failed) run: same run dir, sessions and round count; the task is not re-sent.\n\nWhich run:\n  - without an id: the newest run that is not done or running\n  - with an id: that run")
     .option("-p, --project <name>")
     .option("--answer", "the run is waiting for answers: open ask-reply.md in $EDITOR, check the answers, then continue")
     .option("--no-edit", "with --answer: do not open the editor; check the file as it is")
@@ -347,9 +349,13 @@ function unlockProject(pr, force) {
 }
 program
     .command("clear [run-id]")
-    .description("Delete a task (run) by id: its run directory (state, log, result, mailboxes), its task memory and its agent worktrees, branches and snapshots. " +
-    "Long-term (global and project) memory is never touched. Refuses while the run is running, or while a worktree holds work that is not in the repo. " +
-    "With --lock (and no run id) it instead removes the run lock a crashed run left behind; that needs --force.")
+    .summary("Delete a run by id, or remove a stale run lock")
+    .description("Delete a task (run) by id: its run directory (state, log, result, mailboxes), its task memory and its agent worktrees, branches and snapshots.\n\n" +
+    "Long-term (global and project) memory is never touched.\n" +
+    "Refuses while the run is running, or while a worktree holds work that is not in the repo.\n\n" +
+    "With --lock (no run id) it does something else:\n" +
+    "  - removes the run lock a crashed run left behind\n" +
+    "  - needs --force to actually remove it")
     .option("-p, --project <name>")
     .option("--dry-run", "only list what would be deleted and what would be kept")
     .option("--lock", "remove the project's run lock left behind by a crashed run (takes no run id; needs --force)")
@@ -412,7 +418,8 @@ program
 });
 program
     .command("doctor")
-    .description("Check the setup without running any agent: configuration and enforcement levels, git, the project lock, and what each runtime CLI supports (from --version/--help). With --resolved, print every effective setting and where it came from instead.")
+    .summary("Check the setup without running any agent")
+    .description("Check the setup without running any agent. It checks:\n  - configuration and enforcement levels\n  - git\n  - the project lock\n  - what each runtime CLI supports (read from its --version and --help)\n\nWith --resolved it checks nothing and instead prints:\n  - every effective setting\n  - where each one came from")
     .option("-p, --project <name>")
     .option("--task-file <path>", "also check a task file")
     .option("--resolved", "print the merged settings (global library, project file, defaults) and their sources; runs no other check")
@@ -466,7 +473,8 @@ function printResolved(projectName, json) {
 }
 program
     .command("call <agent> [task]")
-    .description("Call one agent of the global library on its own, outside any project: it works in --dir (default: the current directory) and its final answer is printed. It cannot mail anyone or ask you.")
+    .summary("Call one global-library agent on its own, outside any project")
+    .description("Call one agent of the global library on its own, outside any project.\n\n  - it works in --dir (default: the current directory)\n  - its final answer is printed\n  - it cannot mail anyone or ask you")
     .option("--task-file <path>", "read the task from a file")
     .option("--dir <path>", "the directory the agent works in (default: the current directory)")
     .action(async (agentName, task, opts) => {
@@ -499,7 +507,6 @@ program
         fail(e instanceof ConfigError ? e.message : 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";
@@ -507,16 +514,44 @@ function layerOpt(v) {
         return "global";
     return fail(`--layer must be "project" or "global" (task memory is not tidied: \`clear\` deletes it).`);
 }
-memoryCmd
+program
     .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.")
+    .summary("Have agents tidy their own memory, or undo one tidy")
+    .description("Have agents tidy their own memory: merge duplicates, fix stale entries, archive what is obsolete (never deletes).\n\n" +
+    "Manual only; nothing triggers it automatically.\n\n" +
+    "With --undo <stamp> it tidies nothing and instead:\n" +
+    "  - moves that tidy's archived files back (never overwrites)\n" +
+    "  - re-adds them to MEMORY.md\n" +
+    "  - needs --agent, and cannot be combined with --dry-run")
     .option("-p, --project <name>")
-    .option("--agent <name>", "tidy only this agent (default: every agent)")
+    .option("--agent <name>", "tidy only this agent (default: every agent); required with --undo")
     .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")
+    .option("--undo <stamp>", "undo the tidy with this timestamp: move its archived files back")
     .action(async (opts) => {
     try {
         const layer = layerOpt(opts.layer);
+        if (opts.undo !== undefined) {
+            if (opts.dryRun)
+                fail("--undo cannot be combined with --dry-run.");
+            if (!opts.agent)
+                fail("--undo needs --agent <name>: an archive belongs to one agent's memory.");
+            const target = loadProject(opts.project);
+            const undoLease = takeLock(target, `restore-${tidyStamp()}`);
+            try {
+                const r = restoreMemory({ project: target, agent: opts.agent, layer, stamp: opts.undo });
+                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 ${opts.undo} holds no files to restore.`);
+            }
+            finally {
+                undoLease.release();
+            }
+            return;
+        }
         const pr = loadProject(opts.project);
         if (opts.dryRun) {
             const dry = await tidyMemory({ project: pr, layer, agent: opts.agent, dryRun: true });
@@ -544,7 +579,7 @@ memoryCmd
             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" : ""}`);
+                console.log(`  ${r.agent} (${r.layer}): tidied. Archive: ${path.join(r.dir, ".archive", r.archive ?? "")} — undo with: agent-lyceum tidy --undo ${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") {
@@ -559,34 +594,6 @@ memoryCmd
         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;
@@ -657,7 +664,7 @@ program
 const HELP_LAYERS = {
     "Project:": ["init", "project"],
     "Diagnose:": ["doctor", "status"],
-    "Run:": ["run", "resume", "clear", "call", "memory"],
+    "Run:": ["run", "resume", "clear", "call", "tidy"],
 };
 for (const [heading, names] of Object.entries(HELP_LAYERS))
     for (const c of program.commands)

package/dist/doctor.js

@@ -134,7 +134,7 @@ export async function diagnoseProject(project, opts = {}) {
         });
     }
     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).` });
+        checks.push({ level: "info", subject: "memory", message: `${a.agent}: ${a.reason}. Consider: agent-lyceum 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/memory-tidy.d.ts

@@ -88,7 +88,7 @@ export interface TidyResult {
 }
 /** 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`). */
+/** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum tidy`). */
 export declare function tidyMemory(o: TidyOptions): Promise<TidyResult[]>;
 export interface RestoreResult {
     restored: string[];

package/dist/memory-tidy.js

@@ -255,7 +255,7 @@ async function tidyOne(o, t, stamp) {
     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`). */
+/** Tidy the memory of the chosen agents, one after another. Only ever called by a person (`agent-lyceum 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 });

package/dist/status.d.ts

@@ -110,7 +110,7 @@ export interface StatusReport {
     };
     agents: AgentReport[];
     run?: RunReport;
-    /** Hints that a `memory tidy` might help. Only a suggestion; nothing runs it. */
+    /** Hints that a `tidy` might help. Only a suggestion; nothing runs it. */
     memory_advice?: string[];
 }
 export interface TaskListReport {

package/dist/status.js

@@ -430,6 +430,6 @@ export function formatStatusReport(report, now = Date.now(), color = false) {
     if (run)
         lines.push("", `輸出 tokens：${tokens(run.output_tokens)}`);
     if (report.memory_advice?.length)
-        lines.push("", `記憶：${report.memory_advice.join("；")}（建議執行 agent-lyceum memory tidy -p ${report.project.name}；status 只提示，不會自動整理）`);
+        lines.push("", `記憶：${report.memory_advice.join("；")}（建議執行 agent-lyceum tidy -p ${report.project.name}；status 只提示，不會自動整理）`);
     return lines.join("\n");
 }

package/package.json

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