agent-lyceum 0.4.14 → 0.6.0

package/README.md

@@ -24,23 +24,22 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 
 | Command | What it does |
 |---|---|
-| `init [-y]` | Create the home and a global agent library (`lead`, `fe-member`, `qa-member`). Asks before creating the default path. |
-| `project add <name> --dir <repo>` | Register a project: creates `projects/<name>/project.yaml`, shared folders and `COMMON.md`. |
-| `project list` / `project remove <name> [--purge]` | List projects / unregister (keeps context unless `--purge`). |
-| `validate [-p name] [--task-file f]` | Validate the merged config and print each agent's enforcement level. Exit 1 on errors. |
-| `run ["task"] [--task-file f] [-p name]` | Give the task to the lead and run the dispatcher until done. Give *either* text or `--task-file`. |
-| `resume [run-id] [-p name]` | Continue an interrupted or failed run (each `run` is its own task; without an id, the newest run that is neither done nor running): same run dir, sessions and round count; the task is not re-sent and unread mail is picked up again. Refuses if the run is still alive. For a run that is already done it continues nothing: it prints the recorded outcome and result and exits with the code for that outcome (`0` completed, `2` partial/blocked, `1` failed; a run from before outcomes were recorded counts as an unverified `partial`, exit `2`). A run that ended idle or at `max_rounds` has no unread mail left unless you add some, so resuming it ends idle again (exit `2`). |
-| `status [-p name] [--monitor]` | Agents, unread mail, what is running right now (agent, elapsed time, message being handled), last run (task source, rounds, end reason, output tokens). Without `--monitor` it also prints the full wake-by-wake record of the latest run; `--monitor` keeps a live page open showing only the latest three wakes of each run. `--task-id <id>` prints everything about one task (every wake, its result, log directory). `--task-list [project]` lists every run of the project with its id, state, rounds and task (feed the id to `resume`). `--json` prints the same report as JSON (`schema_version: 1`, no colour, nothing else on stdout; errors go to stderr with a non-zero exit); it works with `--task-list` and `--task-id`. Text and JSON are made from the same report. |
-| `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` | Delete a task (run) by id: its run directory (state, log, result, mailboxes), its **task memory**, and its agents' git worktrees, branches and snapshot refs. Global and project (long-term) memory is never touched. It refuses, and deletes nothing, while the run is still running or while a worktree holds work that is not in your repo (uncommitted, or committed but not brought in); it lists that work. `--keep-worktrees` keeps the worktrees and their branches and still clears the rest. `--dry-run` only prints what would be deleted and kept. Symlinks are never followed out of the project home. Progress is journaled in `projects/<name>/cleanup/`, so an interrupted `clear` is finished by repeating the same command. List ids with `status --task-list`. |
-| `config show --resolved [-p name] [--json]` | Print every effective setting (global library, project file and defaults merged) and where it came from: the file and key, `default`, or `inferred from <model key>` when the runtime was recognised from `model`. Project values replace global ones; lists (`can_message`, `owns`) are replaced, not merged; relative paths are resolved against the file they were written in. |
-| `doctor [-p name] [--json]` | Check the setup without running any agent: configuration, git (for parallel runs), the project lock, and what each runtime CLI supports, read from its `--version` and `--help` (JSON output, resume, sandbox settings, effort; each is `yes`, `no` or `unknown`). Exit 1 when something the team needs is explicitly unsupported. It does not read credentials: login status is reported as unknown. `run` and `resume` do the same capability check first: they refuse to start on an explicit `no` and warn on `unknown`. A real end-to-end check against the live CLIs (a tiny task) spends tokens and is deliberately manual. |
-| `unlock [-p name] --force` | Remove the project's run lock left behind by a crashed run (only one run per project at a time). Without `--force` it only shows who holds the lock. |
-
-**Stopping a run:** Ctrl-C (or SIGTERM) cancels it cleanly: running agents get SIGTERM, then SIGKILL after 5 s (their whole process tree), unread mail is kept, the lock is released and the exit code is `130`; continue later with `agent-lyceum resume`. A second Ctrl-C quits at once. A wake-up that exceeds `wake_timeout_sec` is stopped the same way and counts as a failed attempt. Each attempt's complete stdout/stderr is written to `runs/<run-id>/mail/attempts/<attempt>/log/`; only the last 64 KiB of each stream is kept in memory.
-
-**Exit codes of `run` / `resume`:** `0` only when the lead reported `outcome: completed`; `2` for `partial` or `blocked` (also when the run went idle or hit `max_rounds` without a done); `1` for `failed` (also when the lead itself failed); `130` for `cancelled`. *Upgrading:* before this version an `idle` run exited `0` and a failed lead exited `2`; scripts that treated `0` as "the run ended" must now check for `0` as "the work was completed". Runs that ended before outcomes were recorded show as unverified (`partial`) and are not reported as a success.
-
-Without `--project`, the project is the registered one whose `dir` is the longest prefix of the current directory; if none matches the command lists the registered projects and stops.
+| `init [-y]` | Create the home and the global agent library. [details](docs/commands.md#init) |
+| `project add <name> --dir <repo>` | Register a project. [details](docs/commands.md#project-add) |
+| `project list` / `project remove <name> [--purge]` | List or unregister projects. [details](docs/commands.md#project-list-and-remove) |
+| `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, `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)
 
@@ -57,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`:** the pane opens automatically at session start (it seats from 144 terminal columns; the status line works at any width); type the command to open it at any width. 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; click a tab to switch. It refreshes with the polling interval while open. Click **關閉** (Close) to dismiss it (Esc does not close it).
+- **`/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`):
 
@@ -66,6 +65,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 | `command` | CLI to run, split on spaces, e.g. `node /path/to/agent-lyceum/dist/cli.js` | `agent-lyceum` |
 | `project` | Registered project name(s) (`-p`); comma-separate to watch several; empty infers from the session's directory | empty |
 | `intervalSeconds` | How often status is polled | `1` |
+| `autoOpen` | Open the pane when a session starts (it seats only from 144 columns when opened unasked) | `false` |
 
 Changes take effect on the next session start. If the pane shows `無法取得狀態：...`, the `command` could not run (usually `dist/cli.js` was not built) or the project name is not registered.
 
@@ -89,14 +89,14 @@ Changes take effect on the next session start. If the pane shows `無法取得
 # project.yaml
 dir: ~/code/web-app
 team: { lead: lead }
-dispatcher: { max_rounds: 30, max_parallel: 1, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto }
+dispatcher: { max_rounds: 30, max_parallel: 1, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto, log_max_bytes: 8388608 }
 agents:
   lead:      { resume: true, can_message: all, can_edit_agent_md: true }
   fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
   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.
 
@@ -125,7 +125,7 @@ Enforcement is layered because no single mechanism is complete:
 
 - **Claude Code**: per-run `--settings` with `Edit(...)` rules **plus** the OS sandbox (`allowWrite`/`denyWrite`, `allowUnsandboxedCommands: false`). Without the sandbox, `python -c` and similar bypass Edit rules, so the sandbox is required for the `os` level.
 - **Codex**: `-s workspace-write` with `-c sandbox_workspace_write.writable_roots=[...]` (OS-enforced). Codex cannot forbid a single file inside the repo, so repo `CLAUDE.md`/`AGENTS.md` are protected by **post-hoc detection** only.
-- **All runtimes**: protected files are hashed before the run; after each wake-up unauthorized changes are reverted, logged, and reported to the lead.
+- **All runtimes**: protected files are hashed before the run; after each wake-up unauthorized changes are reverted, logged, and reported to the lead; what was written is kept in `runs/<run-id>/violations/` first.
 
 `validate` and `run` print every agent's level per category (`os`, `tool-rules`, `post-hoc`, `prompt-only`) and the paths it can write outside the repo. With `dispatcher.strict: true`, a run is refused unless memory, `AGENT.md` and other agents' context are OS-enforced.
 

package/README.zh-TW.md

@@ -24,23 +24,22 @@ npx agent-lyceum status
 
 | 指令 | 功能 |
 |---|---|
-| `init [-y]` | 建立 home 與全域 agent 庫（`lead`、`fe-member`、`qa-member`）。建立預設路徑前會先詢問。 |
-| `project add <name> --dir <repo>` | 註冊專案：建立 `projects/<name>/project.yaml`、共用資料夾與 `COMMON.md`。 |
-| `project list` / `project remove <name> [--purge]` | 列出專案／取消註冊（除非加 `--purge`，否則保留 context）。 |
-| `validate [-p name] [--task-file f]` | 驗證合併後的設定，並印出每個 agent 的防護等級。有錯誤時 exit 1。 |
-| `run ["task"] [--task-file f] [-p name]` | 把任務交給 lead，並執行 dispatcher 直到完成。任務文字與 `--task-file` 擇一提供。 |
-| `resume [run-id] [-p name]` | 接續被中斷或失敗的 run（每次 `run` 都是獨立任務；不指定 id 時接續最新一個尚未結束且未在執行的 run，指定 id 則接續該任務）：沿用同一個 run 目錄、session 與輪數，不會重送任務，未讀信件會重新處理。run 仍在執行時會拒絕。對已完成（done）的 run 不會繼續任何工作：只印出已記錄的結果狀態與內容，並以該結果對應的碼結束（`0` completed、`2` partial／blocked、`1` failed；在記錄結果狀態之前就結束的舊 run 視為未驗證的 `partial`，回傳 `2`）。因閒置或達 `max_rounds` 而結束的 run，除非補上新信件，否則已沒有未讀信件，接續後會再次以閒置結束（回傳 `2`）。 |
-| `status [-p name] [--monitor]` | 顯示 agent、未讀信件、目前正在執行的 agent（耗時、處理中的信件）、上次執行（任務來源、輪數、結束原因、output token 數）。不帶 `--monitor` 時會一併印出最新 run 的完整 wake 紀錄；`--monitor` 會常駐並持續更新，每個 run 只顯示最新三筆 wake。`--task-id <id>` 印出單一任務的完整內容（每次 wake、結果、log 目錄）。`--task-list [project]` 列出專案所有任務（run）的 id、狀態、輪數與任務內容，id 可直接給 `resume` 使用。加上 `--json` 會把同一份報告以 JSON 輸出（`schema_version: 1`、無顏色，stdout 只有 JSON；錯誤走 stderr 並以非零 exit code 結束），可搭配 `--task-list`、`--task-id`。文字與 JSON 由同一份報告產生。 |
-| `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` | 依 id 刪除一個任務（run）：它的 run 目錄（狀態、log、結果、信箱）、**任務記憶**，以及各 agent 的 git worktree、branch 與快照 ref。全域與專案層（長期）記憶一律不會動。run 仍在執行，或有 worktree 內的成果不在你的 repo 裡（未提交，或已提交但尚未整合進來）時會拒絕且什麼都不刪，並列出那些成果。`--keep-worktrees` 會保留 worktree 與 branch，其餘照樣清除。`--dry-run` 只列出會刪除與會保留的項目。絕不會順著 symlink 刪到專案 home 之外。進度會記在 `projects/<name>/cleanup/` 的 journal，所以中斷後重跑同一個指令即可完成。id 可用 `status --task-list` 查。 |
-| `config show --resolved [-p name] [--json]` | 印出每一項生效的設定（全域 agent 庫、專案檔與預設值合併後的結果）與它的來源：檔案與 key、`default`，或在 runtime 是由 `model` 辨識出來時顯示 `inferred from <model 的 key>`。專案的值覆蓋全域；清單（`can_message`、`owns`）是整個取代而非合併；相對路徑以寫它的那個檔案為基準解析。 |
-| `doctor [-p name] [--json]` | 在不執行任何 agent 的前提下檢查環境：設定、git（平行 run 需要）、專案鎖，以及各 runtime CLI 支援什麼（從 `--version` 與 `--help` 讀取：JSON 輸出、resume、sandbox 設定、effort，每項都是 `yes`、`no` 或 `unknown`）。只要團隊需要的功能被明確判定不支援就 exit 1。它不讀取憑證，登入狀態會回報為 unknown。`run` 與 `resume` 啟動前會先做同樣的能力檢查：明確 `no` 就拒絕啟動，`unknown` 則警告。要對真實 CLI 做端到端驗證（跑一個很小的任務）會花 token，刻意保留為手動。 |
-| `unlock [-p name] --force` | 移除當機的 run 留下的專案鎖（同一專案同時只能有一個 run）。不加 `--force` 只會顯示鎖的持有者。 |
-
-**中止 run：** Ctrl-C（或 SIGTERM）會乾淨地取消 run：執行中的 agent 先收到 SIGTERM，5 秒後 SIGKILL（連同整個子程序樹），未讀信件保留、專案鎖釋放，exit code 為 `130`；之後可用 `agent-lyceum resume` 接續。再按一次 Ctrl-C 會立刻結束。超過 `wake_timeout_sec` 的喚醒也以同樣方式停止，並算作一次失敗的嘗試。每次嘗試完整的 stdout／stderr 都寫在 `runs/<run-id>/mail/attempts/<attempt>/log/`，記憶體中每個串流只保留最後 64 KiB。
-
-**`run`／`resume` 的 exit code：** `0` 只代表 lead 回報 `outcome: completed`；`2` 代表 `partial` 或 `blocked`（run 閒置或達到 `max_rounds` 而沒有 done 也算）；`1` 代表 `failed`（lead 本身失敗也算）；`130` 代表 `cancelled`。*升級注意：* 舊版 `idle` 結束會回傳 `0`、lead 失敗回傳 `2`；原本把 `0` 當成「run 結束了」的腳本，現在 `0` 的意思是「工作確實完成」。在記錄結果狀態之前就結束的舊 run 會顯示為「未驗證」（`partial`），不會被當成成功。
-
-未指定 `--project` 時，會選用 `dir` 為目前目錄最長前綴的已註冊專案；若沒有符合的專案，指令會列出已註冊專案後停止。
+| `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) |
+| `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`，等待你回答時為 `3`，取消為 `130`（[退出碼](docs/commands.zh-TW.md#退出碼)）。未指定 `-p` 時，專案由目前目錄推斷（[選擇專案](docs/commands.zh-TW.md#選擇專案)）。
 
 ## 監控 mod（Claude Code）
 
@@ -57,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 啟動時面板會自動開啟（終端寬度需 144 欄以上才會顯示，狀態列不受影響）；也可輸入此指令在任何寬度開啟。每個專案顯示：執行 id 與狀態、任務、進度與清單、正在工作的 agent 與排隊中的信件、受阻的整合、備註與結果摘要、各 runtime 的 output tokens、各 agent 的喚醒統計、最近 8 次喚醒。每個任務（專案目前的執行與最近 3 次過往執行）是一個分頁，點分頁即可切換。面板開著時會依輪詢間隔自動更新，只能點 **關閉** 收起（Esc 不會關閉）。
+- **`/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`）：
 
@@ -66,6 +65,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 | `command` | 要執行的 CLI，以空白分隔，例如 `node /path/to/agent-lyceum/dist/cli.js` | `agent-lyceum` |
 | `project` | 已註冊的專案名稱（`-p`）；用逗號分隔可同時監看多個；留空則依 session 所在目錄推斷 | 空 |
 | `intervalSeconds` | 輪詢狀態的間隔（秒） | `1` |
+| `autoOpen` | session 啟動時自動開啟面板（未經操作開啟時，終端需 144 欄以上才會顯示） | `false` |
 
 設定變更要等下次啟動 session 才生效。面板若顯示 `無法取得狀態：...`，通常是 `command` 跑不起來（多半是還沒 build `dist/cli.js`），或專案名稱沒有註冊。
 
@@ -90,14 +90,14 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 # project.yaml
 dir: ~/code/web-app
 team: { lead: lead }
-dispatcher: { max_rounds: 30, max_parallel: 1, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto }
+dispatcher: { max_rounds: 30, max_parallel: 1, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto, log_max_bytes: 8388608 }
 agents:
   lead:      { resume: true, can_message: all, can_edit_agent_md: true }
   fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
   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。
 
@@ -126,7 +126,7 @@ Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可
 
 - **Claude Code**：每次執行帶入 `--settings`，內含 `Edit(...)` 規則，**加上** OS 沙箱（`allowWrite`/`denyWrite`、`allowUnsandboxedCommands: false`）。沒有沙箱時，`python -c` 之類的做法能繞過 Edit 規則，因此 `os` 等級必須啟用沙箱。
 - **Codex**：`-s workspace-write` 搭配 `-c sandbox_workspace_write.writable_roots=[...]`（由 OS 強制）。Codex 無法禁止 repo 內的單一檔案，所以 repo 的 `CLAUDE.md`/`AGENTS.md` 只能靠**事後偵測**保護。
-- **所有 runtime**：執行前會對受保護檔案做雜湊；每次喚醒後，未經授權的變更會被還原、記錄，並通報 lead。
+- **所有 runtime**：執行前會對受保護檔案做雜湊；每次喚醒後，未經授權的變更會被還原、記錄，並通報 lead；被寫入的內容會先留存在 `runs/<run-id>/violations/`。
 
 `validate` 與 `run` 會依類別（`os`、`tool-rules`、`post-hoc`、`prompt-only`）印出每個 agent 的防護等級，以及它能寫入 repo 之外的哪些路徑。設定 `dispatcher.strict: true` 時，除非記憶、`AGENT.md` 與其他 agent 的 context 都由 OS 強制保護，否則拒絕執行。
 

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/assert.d.ts

@@ -0,0 +1,2 @@
+/** For values the program's own invariants guarantee (never for user input): fail loudly instead of `value!`. */
+export declare function must<T>(value: T | undefined | null, what: string): T;

package/dist/assert.js

@@ -0,0 +1,6 @@
+/** For values the program's own invariants guarantee (never for user input): fail loudly instead of `value!`. */
+export function must(value, what) {
+    if (value === undefined || value === null)
+        throw new Error(`internal: ${what} is missing`);
+    return value;
+}