agent-lyceum 0.16.2 → 0.17.0

package/README.md

@@ -65,7 +65,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 
 **Use it.**
 - **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, `v` switches graph/text, `1`-`9` or Tab/Enter switch task, Esc returns to the prompt, running the command again also closes. It draws one block per agent, with the links between the lead and each member taken from `can_message` (`▼` the lead may write to the member, `▲` the member to the lead, `↕` both; yellow marks the latest hand-off). Each block shows what that agent is doing now, the mail it is handling and the mail queued for it as short readable sections by type (task: goal and acceptance criteria; reply: changes, verification, open items, risks; done: result and what is not done), and its wake count and output tokens. An agent that is working right now is drawn larger: its block gets a row of its own at the full width, and its text wraps instead of being cut, with the message it is handling shown in full (every line of every section); idle and queued blocks stay compact. Above the graph: the run id and state, task, progress bar and checklist; below it: blocked integrations, notes and the result summary. `v` switches to the plain text list (per-runtime tokens, per-agent statistics, the last 8 wakes). Every block lists the agents it may message in a "→" line, with the latest hand-off marked "●" (this also covers member-to-member targets, which get no glyph). When the graph area is narrower than 70 columns (compared with the pane's own width, as the host reports it), the blocks stack in one column and the link glyphs are left out. Each running task is a tab, newest first; finished and interrupted runs are not listed. 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, `v` switches graph/text, `e` expands or collapses the details, `1`-`9` or Tab/Enter switch task, Esc returns to the prompt, running the command again also closes. It draws one block per agent, with the links between the lead and each member taken from `can_message` (`▼` the lead may write to the member, `▲` the member to the lead, `↕` both; yellow marks the latest hand-off). Each block shows what that agent is doing now, the mail it is handling and the mail queued for it as one key line each: the point of the mail by type (task: the goal; reply: the changes; done: the result), plus any open item, risk or unfinished part it reports (none when it says None) — not the start of the text cut short. Press `e` to expand: every section of every mail (task: goal and acceptance criteria; reply: changes, verification, open items, risks; done: result and what is not done) and the full checklist; collapsed, the checklist is only the progress bar and the current step. Each block also shows its wake count and output tokens. An agent that is working right now is drawn larger: its block gets a row of its own at the full width, and its text wraps instead of being cut; idle and queued blocks stay compact. Above the graph: the run id and state, task, progress bar and checklist; below it: blocked integrations, notes and the result summary. `v` switches to the plain text list (per-runtime tokens, per-agent statistics, the last 8 wakes). Every block lists the agents it may message in a "→" line, with the latest hand-off marked "●" (this also covers member-to-member targets, which get no glyph). When the graph area is narrower than 70 columns (compared with the pane's own width, as the host reports it), the blocks stack in one column and the link glyphs are left out. 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`):
 
@@ -100,7 +100,7 @@ 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, max_concurrent_runs: 1, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto, log_max_bytes: 8388608 }
+dispatcher: { max_rounds: 0, max_parallel: 1, max_concurrent_runs: 1, wake_timeout_sec: 600, retry: 2, 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/**"] }
@@ -119,7 +119,7 @@ Rules checked by `doctor`: ≥ 2 agents (the lead and one member; the template h
 3. Every wake-up prompt contains the agent's `AGENT.md`, the team protocol, `COMMON.md` (read-only, ≤ 8 KB), the `MEMORY.md` index of each memory dir, the **oldest** unread message in full (one message per wake-up; the lead instead takes a run of up to 5 `reply`/`failure` messages at once and decides on them together), and titles of the queued ones, which stay unread until their own wake-up.
 4. Agents send mail by writing a Markdown file with frontmatter (`to`, `type`, `subject`) into **their own** `outbox/`. The dispatcher checks `can_message`, stamps the real sender, and moves it to the recipient's `inbox/`. Handled mail goes to `inbox/<agent>/read/`. Mailboxes belong to one run (`runs/<run-id>/mail/`), so mail never crosses runs. Runs started by older versions keep using the shared `shared/{inbox,outbox}/` mailboxes (their mail is never moved); resuming such a run shows that legacy layout.
    The body of every `task` and `reply` should carry fixed `##` headings (injected into each agent's prompt): `task` → `Goal`, `Acceptance criteria`, `Scope`, `Upstream`; `reply` → `Changes`, `Verification`, `Open items`, `Risks` (write `None` when empty; `done` is exempt). Mail missing a heading is still delivered, with a warning note prepended and a `format-warning` entry in the run log.
-5. The run ends when the lead sends `type: done`, when all mailboxes are empty, or after `max_rounds` wake-ups. A `done` must declare `outcome: completed|partial|blocked|failed` in its frontmatter and carry `## Result`, `## Files`, `## Verification`, `## Not done`; `completed` also needs every `## Steps` item ticked. A `done` that breaks this is sent back to the lead (twice at most, then it is kept as `partial`). Agent-lyceum does not verify what the lead reports. A failed wake-up is retried once, then reported to the lead as a failure message (if the lead itself fails, the run aborts).
+5. The run ends when the lead sends `type: done`, when all mailboxes are empty, or after `max_rounds` wake-ups when you set a limit (the default `0` means no limit). A `done` must declare `outcome: completed|partial|blocked|failed` in its frontmatter and carry `## Result`, `## Files`, `## Verification`, `## Not done`; `completed` also needs every `## Steps` item ticked. A `done` that breaks this is sent back to the lead (twice at most, then it is kept as `partial`). Agent-lyceum does not verify what the lead reports. A failed wake-up is retried up to `retry` times (default 2, so 3 calls in all); if the agent still fails, the run stops (`agent_failed`, or `lead_failed` for the lead) instead of carrying on without it: the message it was handling stays unread, and the end message says how to look into the failure and how to continue (`agent-lyceum resume <run>` after fixing the cause, or `clear` to give up). Mail that repeats an earlier mail from the same sender to the same recipient (same type, reply target and text, whitespace aside) is not delivered again: the sender is told, which keeps two agents from looping on the same message.
 
 Parallelism (`max_parallel > 1`) only runs agents with disjoint `owns`, and never alongside the lead. Each non-lead agent then works in its **own git worktree** (`projects/<name>/worktrees/<run-id>/<agent>`, branch `agent-lyceum/<run-id>/<agent>`) cut from a snapshot of the repo as it is when the agent is woken (`refs/agent-lyceum/<run-id>/base-<n>`; it includes the lead's uncommitted and new, non-ignored files; your HEAD, branches and working tree are not touched). `dispatcher.workspace_mode` is `auto` (worktrees when `max_parallel > 1`), `worktree` or `shared`; `shared` cannot be combined with parallel agents. A parallel run refuses to start while the repo has uncommitted changes of yours, and when the repo is not a git repository (run sequentially instead). When a member finishes, the dispatcher commits its worktree and brings the changes into your working tree (not your index or HEAD) before the lead reads the member's mail. Every changed path is checked first: it must be inside the member's `owns` (renames and deletions included), must not be `CLAUDE.md`/`AGENTS.md`, and symlinks may not point out of the project or the member's `owns`. If a file also changed in your repo since the member's snapshot, if a check fails, or if `git apply` fails, nothing is applied: the work stays on its branch and worktree, a report and patch are written to `runs/<run-id>/integration/`, the lead is told, and the run cannot end as `completed` (it ends `blocked`). A worktree isolates files only: it cannot isolate side effects on external services, databases or the network.
 
@@ -147,7 +147,7 @@ A finished (`done`) run can be reopened with a follow-up request: `agent-lyceum
 
 - **Which runs:** only a finished run can be reopened. A run that is still running is refused; a run that is not finished is refused when given text (resume it without text first). Without text nothing changes: a finished run just prints its result. Without a run, the candidates are the finished runs, newest first: exactly one is used, none is an error, and several are listed (in a terminal you pick one by number or name; without a terminal the command fails and lists them). A lone argument counts as follow-up text only when it cannot be a run reference (it contains whitespace or a character a run name cannot contain); a one-word follow-up needs `resume <run> "<text>"` or `--task-file`.
 - **What is kept:** the follow-up is saved as `runs/<run-id>/followups/<n>.md`. Each `done` report is kept as `done-<n>.md`, and `result.md` is always the latest. `state.json` gains `name`, `reopened`, `round_floor` and `step_base` (all optional, so older runs still load). The progress (`## Steps`) carries on: the checklist at the reopen stays, and the steps the lead lists for the follow-up are added after it (a step it lists again only takes the new tick); for the follow-up's `completed` only its own steps must be ticked. Unresolved blocked integrations stay; the done-contract reminders start afresh for each reopened segment.
-- **Round limit:** `max_rounds` counts from the reopen: `rounds` keeps accumulating, and the limit is the rounds at reopen plus `max_rounds`.
+- **Round limit:** with a `max_rounds` set, it counts from the reopen: `rounds` keeps accumulating, and the limit is the rounds at reopen plus `max_rounds`.
 - **The lead's branch** (runs with a lead worktree): if the branch was already merged into your `HEAD` and the lead worktree is clean and untouched since the run ended, the worktree and the branch (same name, `agent-lyceum/<run-id>/<lead>`) are re-cut from your current `HEAD`, and a line says so. Otherwise the same worktree and branch continue. If a pull request was already recorded (`pr_url`) and the branch was not re-cut, a new `open_pr: true` only pushes ("pull request updated") while that pull request is still open; if it was merged (a squash merge included) or closed, a new pull request is opened instead. If the branch was re-cut, the recorded `pr_url` is cleared (the old URL stays in the run's notes) and a new pull request is opened when asked. agent-lyceum still never merges.
 - **Handoff notes:** before it sends `done`, the lead writes what a follow-up will need into `task-memory/<run-id>/_shared/` in the agent-lyceum home (`MEMORY.md` is the index): decisions and why, interfaces agreed, current state, what is left and the next steps, pitfalls met. Members can read this folder but not write it (a run started with `run --agent` has one agent, which is its own lead and writes it; `call` has none). Once a run is reopened, every wake-up of every agent gets `MEMORY.md` in its prompt (the first 8 KB; a longer index is cut and flagged), and the reopened `task` mail's `Upstream` names it; the first segment's prompts do not contain it. If the lead sends `done` without having changed `MEMORY.md` in that segment, the run is not blocked: a note `shared-not-updated` is added to the run's notes. `clear` deletes the folder with the task memory; `tidy` does not touch it. It holds notes about this task only; lessons that outlive it belong in project or global memory.
 

package/README.zh-TW.md

@@ -65,7 +65,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
 
 **操作。**
 - **通知：** 執行完成、被中斷或某個 agent 喚醒失敗時會跳出訊息（監看多個專案時前面加 `[專案名]`），不需要任何操作。
-- **`/status-monitor`：** 輸入即開啟面板（已開著則關閉）。session 啟動時預設不開，除非設定 `autoOpen`。在 **fullscreen 版面**（`~/.claude/settings.json` 設 `"tui": "fullscreen"` 後重開 session；`/tui fullscreen` 效果相同）且終端寬度 110 欄以上時，面板會靠右 dock 在終端寬度的一半，分頁與 **關閉** 都可以用滑鼠點。否則顯示在輸入框上方；版面在 session 啟動時就固定，從主畫面啟動的 session 不會變。鍵盤操作兩種版面都能用：`x` 關閉，`v` 切換圖形／文字，`1`-`9` 或 Tab/Enter 切換任務，Esc 回到輸入框，再執行一次指令也會關閉。面板為每個 agent 畫一個區塊，並依 `can_message` 在 lead 與各成員之間畫出連結（`▼` lead 可寄給成員、`▲` 成員可寄給 lead、`↕` 雙向；黃色表示最近一次寄信的那條邊）。每個區塊顯示該 agent 現在在做什麼、正在處理與排隊中的信（依信種整理成可讀的重點：task 看目標與驗收，reply 看變更、驗證、待辦與風險，done 看結果與未完成），以及喚醒次數與輸出 token。正在運作的 agent 會被放大：它的區塊獨佔一整列、使用全寬，文字自動換行而不截斷，正在處理的那封信完整顯示（每個段落的每一行）；閒置與排隊中的區塊維持精簡。圖形上方是執行 id 與狀態、任務、進度條與清單；下方是受阻的整合、備註與結果摘要。按 `v` 切換成純文字清單（各 runtime 的 token、各 agent 統計、最近 8 次喚醒）。每個區塊以「→」一行列出它可以寄信的對象，最近一次寄信的對象標 「●」（成員之間的對象也在此，不畫符號）。當圖形區域寬度少於 70 欄（以面板本身的寬度比較，由 host 回報），區塊改成單欄堆疊，不畫連結符號。每個執行中的任務是一個分頁，最新的排最前面；已結束或已中斷的不列出。面板開著時會依輪詢間隔自動更新。
+- **`/status-monitor`：** 輸入即開啟面板（已開著則關閉）。session 啟動時預設不開，除非設定 `autoOpen`。在 **fullscreen 版面**（`~/.claude/settings.json` 設 `"tui": "fullscreen"` 後重開 session；`/tui fullscreen` 效果相同）且終端寬度 110 欄以上時，面板會靠右 dock 在終端寬度的一半，分頁與 **關閉** 都可以用滑鼠點。否則顯示在輸入框上方；版面在 session 啟動時就固定，從主畫面啟動的 session 不會變。鍵盤操作兩種版面都能用：`x` 關閉，`v` 切換圖形／文字，`e` 展開／收合細節，`1`-`9` 或 Tab/Enter 切換任務，Esc 回到輸入框，再執行一次指令也會關閉。面板為每個 agent 畫一個區塊，並依 `can_message` 在 lead 與各成員之間畫出連結（`▼` lead 可寄給成員、`▲` 成員可寄給 lead、`↕` 雙向；黃色表示最近一次寄信的那條邊）。每個區塊顯示該 agent 現在在做什麼、正在處理與排隊中的信，每封信預設只顯示一行重點：依信種挑出它在講什麼（task 是目標，reply 是變更，done 是結果），再加上信裡回報的待辦、風險或未完成（寫 None 就不顯示）——不是把開頭截短。按 `e` 展開：每封信的每個段落（task 看目標與驗收，reply 看變更、驗證、待辦與風險，done 看結果與未完成）和完整的步驟清單；收合時清單只有進度條與目前步驟。每個區塊也顯示喚醒次數與輸出 token。正在運作的 agent 會被放大：它的區塊獨佔一整列、使用全寬，文字自動換行而不截斷；閒置與排隊中的區塊維持精簡。圖形上方是執行 id 與狀態、任務、進度條與清單；下方是受阻的整合、備註與結果摘要。按 `v` 切換成純文字清單（各 runtime 的 token、各 agent 統計、最近 8 次喚醒）。每個區塊以「→」一行列出它可以寄信的對象，最近一次寄信的對象標 「●」（成員之間的對象也在此，不畫符號）。當圖形區域寬度少於 70 欄（以面板本身的寬度比較，由 host 回報），區塊改成單欄堆疊，不畫連結符號。每個執行中的任務是一個分頁，最新的排最前面；已結束或已中斷的不列出。面板開著時會依輪詢間隔自動更新。
 
 **設定。** 在 `~/.claude/settings.json` 的 `pluginConfigs."status-monitor@inline"`（`options`）：
 
@@ -100,7 +100,7 @@ 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, max_concurrent_runs: 1, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto, log_max_bytes: 8388608 }
+dispatcher: { max_rounds: 0, max_parallel: 1, max_concurrent_runs: 1, wake_timeout_sec: 600, retry: 2, 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/**"] }
@@ -119,7 +119,7 @@ Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可
 3. 每次喚醒的 prompt 都包含：該 agent 的 `AGENT.md`、團隊協定、`COMMON.md`（唯讀，≤ 8 KB）、每個記憶資料夾的 `MEMORY.md` 索引、**最舊**一封未讀信件全文（每次喚醒只處理一封；lead 例外，會一次拿到連續最多 5 封 `reply`/`failure` 並一併決策），以及排隊中信件的標題；排隊的信維持未讀，等各自的喚醒再處理。
 4. agent 寄信的方式，是在**自己的** `outbox/` 寫一個含 frontmatter（`to`、`type`、`subject`）的 Markdown 檔。dispatcher 會檢查 `can_message`、蓋上真正的寄件者，並移到收件者的 `inbox/`。處理完的信件移至 `inbox/<agent>/read/`。信箱屬於單一 run（`runs/<run-id>/mail/`），信件不會跨 run。舊版本啟動的 run 繼續使用共用的 `shared/{inbox,outbox}/` 信箱（信件不會被搬移），接續這類 run 時會沿用舊版配置。
    每封 `task` 和 `reply` 的內文應包含固定的 `##` 標題（會注入每個 agent 的 prompt）：`task` → `Goal`、`Acceptance criteria`、`Scope`、`Upstream`；`reply` → `Changes`、`Verification`、`Open items`、`Risks`（沒內容就寫 `None`；`done` 免檢）。缺標題的信仍會送達，但開頭會加上警告說明，run log 也會記一筆 `format-warning`。
-5. 結束條件：lead 寄出 `type: done`、所有信箱都空了，或喚醒次數達到 `max_rounds`。`done` 的 frontmatter 必須有 `outcome: completed|partial|blocked|failed`，內文要有 `## Result`、`## Files`、`## Verification`、`## Not done`；`completed` 還要求 `## Steps` 全部勾選。不符合的 `done` 會退回給 lead（最多兩次，之後以 `partial` 收下）。agent-lyceum 不會驗證 lead 回報的內容是否屬實。喚醒失敗會重試一次，之後以失敗訊息通知 lead（若 lead 本身失敗，則整個 run 中止）。
+5. 結束條件：lead 寄出 `type: done`、所有信箱都空了，或（有設上限時）喚醒次數達到 `max_rounds`；預設 `0` 代表不限輪數。`done` 的 frontmatter 必須有 `outcome: completed|partial|blocked|failed`，內文要有 `## Result`、`## Files`、`## Verification`、`## Not done`；`completed` 還要求 `## Steps` 全部勾選。不符合的 `done` 會退回給 lead（最多兩次，之後以 `partial` 收下）。agent-lyceum 不會驗證 lead 回報的內容是否屬實。喚醒失敗最多重試 `retry` 次（預設 2，即最多呼叫 3 次）；仍然失敗就停止整個 run（成員失敗為 `agent_failed`，lead 失敗為 `lead_failed`），不會少了它繼續跑：它正在處理的那封信維持未讀，結束訊息會告訴你怎麼查原因與怎麼繼續（修正後 `agent-lyceum resume <run>`，或用 `clear` 放棄）。同一個寄件人寄給同一個收件人、type、reply_to 與內文（忽略空白差異）都相同的信不會再被投遞，並通知寄件人，避免兩個 agent 對著同一封信繞圈。
 
 平行執行（`max_parallel > 1`）只會同時跑 `owns` 互不相交的 agent，且絕不與 lead 同時執行。此時每個非 lead 的 agent 都在**自己的 git worktree**（`projects/<name>/worktrees/<run-id>/<agent>`，branch `agent-lyceum/<run-id>/<agent>`）工作；worktree 是從喚醒當下 repo 的快照（`refs/agent-lyceum/<run-id>/base-<n>`，包含 lead 尚未提交的修改與新增、未被 ignore 的檔案）切出來的，你的 HEAD、branch 與工作目錄都不會被動到。`dispatcher.workspace_mode` 可設為 `auto`（`max_parallel > 1` 時用 worktree）、`worktree` 或 `shared`；`shared` 不能與平行 agent 並用。平行 run 在 repo 有你自己未提交的修改時，或 repo 不是 git repository 時，會拒絕啟動（請改為序列執行）。成員完成後，dispatcher 會提交它 worktree 中的修改，並在 lead 讀到該成員的信之前，把變更套用到你的工作目錄（不動你的 index 與 HEAD）。每個被改動的路徑都會先檢查：必須在該成員的 `owns` 內（rename 與刪除也算）、不得是 `CLAUDE.md`／`AGENTS.md`，symlink 不得指向專案或該成員 `owns` 之外。若同一檔案在成員的快照之後又在你的 repo 被改過、檢查未通過，或 `git apply` 失敗，就一個檔案都不套用：成果保留在它的 branch 與 worktree，報告與 patch 寫到 `runs/<run-id>/integration/`，並通知 lead，且這個 run 不能以 `completed` 結束（會以 `blocked` 結束）。worktree 只隔離檔案，無法隔離對外部服務、資料庫或網路的副作用。
 
@@ -147,7 +147,7 @@ Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可
 
 - **哪些 run：** 只有已完成的 run 能重開。仍在執行的 run 會拒絕；尚未完成的 run 若帶文字也會拒絕（先不帶文字 resume 它）。不帶文字時行為不變：已完成的 run 只印出結果。沒指定 run 時，候選是已完成的 run，由新到舊：剛好一個就用它，沒有就報錯，有多個就列出（在終端機可用編號或名稱選；非互動環境則報錯並列出候選）。只有一個參數時，只有在它不可能是 run 參照（含空白，或含 run 名稱不能用的字元）才會被當成追加要求；單一個詞的追加要求要寫成 `resume <run> "<text>"` 或用 `--task-file`。
 - **保留什麼：** 追加要求存成 `runs/<run-id>/followups/<n>.md`。每份 `done` 報告保留為 `done-<n>.md`，`result.md` 永遠是最新一份。`state.json` 新增 `name`、`reopened`、`round_floor`、`step_base`（都是選填，舊的 run 照樣能讀）。進度（`## Steps`）會接續：重開時的清單保留，lead 為追加要求列的步驟接在後面（再次列出的舊步驟只更新勾選狀態）；追加要求的 `completed` 只要求它自己的步驟全部勾選。未解決的 blocked integration 會保留；每段重開的 done 規範提醒重新計算。
-- **輪數上限：** `max_rounds` 從重開時起算：`rounds` 持續累加，上限是重開當下的輪數加 `max_rounds`。
+- **輪數上限：** 有設 `max_rounds` 時，它從重開時起算：`rounds` 持續累加，上限是重開當下的輪數加 `max_rounds`。
 - **lead 的 branch**（lead 有 worktree 的 run）：若該 branch 已合併進你的 `HEAD`，且 lead 的 worktree 乾淨、自 run 結束後沒被動過，worktree 與 branch（同名，`agent-lyceum/<run-id>/<lead>`）會從你目前的 `HEAD` 重新切出，並印一行說明。否則沿用原本的 worktree 與 branch。若已記錄 PR（`pr_url`）且 branch 沒有重切，新的 `open_pr: true` 只會 push（「pull request updated」），而且只在該 PR 仍開啟時；若它已被合併（含 squash merge）或關閉，就改開一個新的 PR；若 branch 重切了，已記錄的 `pr_url` 會被清掉（舊網址留在 run 的 notes），要求時再開一個新的 PR。agent-lyceum 仍然從不合併。
 - **交接筆記：** lead 在送 `done` 之前，把追加要求會用到的內容寫進 agent-lyceum home 裡的 `task-memory/<run-id>/_shared/`（`MEMORY.md` 為索引）：做過的決定與理由、介面約定、目前狀態、剩下的事與下一步、踩過的坑。成員可讀不可寫（用 `run --agent` 啟動的 run 只有一個 agent，它就是自己的 lead，所以可寫；`call` 沒有這個資料夾）。run 重開後，每個 agent 的每次喚醒都在 prompt 裡拿到 `MEMORY.md`（前 8 KB，較長的索引會被截斷並標示），重開的 `task` 信的 `Upstream` 也會指向它；第一段的 prompt 不含它。若 lead 在該段沒有更動 `MEMORY.md` 就送出 `done`，run 不會被擋，只會在 run 的 notes 加一筆 `shared-not-updated`。`clear` 會連同任務記憶一併刪除；`tidy` 不會動它。只放這個 task 的筆記，跨 task 的教訓仍放 project 或 global memory。
 

package/dist/cli.js

@@ -10,7 +10,8 @@ import { RESULT_FILE, runTeam } from "./dispatcher.js";
 import { executeRunCleanup, planRunCleanup } from "./run-cleanup.js";
 import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
 import { acquireProjectLock, forceUnlock, inspectRunLock, listRunLocks, listUnreadableRunLocks, LOCK_FILE, lockHolderAlive } from "./project-lock.js";
-import { loadRunState, newRunId, outcomeOf, resolveRun, roundLimit, runLabel, slugify, uniqueName } from "./run-store.js";
+import { loadRunState, newRunId, outcomeOf, resolveRun, roundLimit, roundsLabel, runLabel, slugify, uniqueName } from "./run-store.js";
+import { failureGuide } from "./run-outcome.js";
 import { exitCodeForOutcome } from "./schema.js";
 import { absPath, assertName, NAME_RE, projectPaths, resolveHome } from "./paths.js";
 import { addProject, initHome, removeProject } from "./scaffold.js";
@@ -167,6 +168,8 @@ function printRun(summary, runDir) {
     console.log(`\nRun ${runLabel({ name: summary.name, run_id: 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}`);
+    if (summary.failure)
+        console.log(failureGuide(summary.project, summary.name ?? summary.runId, summary.failure, runDir));
     if (summary.verification)
         console.log(`Verification (as reported by the lead, not checked by agent-lyceum): ${summary.verification}`);
     if (summary.resultBranch?.files) {
@@ -200,7 +203,7 @@ async function continueRun(pr, dir, runId, followup) {
         if (followup)
             console.log(`Reopening run ${runLabel(state)} (follow-up ${(state.reopened?.length ?? 0) + 1}): ${firstLine(followup.text)}`);
         else
-            console.log(`Resuming run ${runLabel(state)} (${state.end_reason ?? "interrupted"}) at round ${state.rounds}/${roundLimit(state, pr.dispatcher.max_rounds)}: ${state.task_summary}`);
+            console.log(`Resuming run ${runLabel(state)} (${state.end_reason ?? "interrupted"}) at round ${roundsLabel(state.rounds, roundLimit(state, 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, followup });
     }
@@ -393,8 +396,8 @@ program
             process.exit(exitCodeForOutcome(o.outcome));
         }
         // A reopen recalculates the round limit from where the run stands.
-        if (!reopen && state.rounds >= roundLimit(state, pr.dispatcher.max_rounds))
-            fail(`Run ${runLabel(state)} used ${state.rounds}/${roundLimit(state, pr.dispatcher.max_rounds)} rounds; raise dispatcher.max_rounds in project.yaml first.`);
+        if (!reopen && roundLimit(state, pr.dispatcher.max_rounds) > 0 && state.rounds >= roundLimit(state, pr.dispatcher.max_rounds))
+            fail(`Run ${runLabel(state)} used ${state.rounds}/${roundLimit(state, pr.dispatcher.max_rounds)} rounds; raise dispatcher.max_rounds in project.yaml (or set it to 0 for no limit) first.`);
         if (opts.answer && state.end_reason !== "waiting")
             fail(`Run ${runLabel(state)} is not waiting for answers (${state.end_reason ?? "not finished"}).`);
         if (state.end_reason === "waiting") {

package/dist/mailbox.js

@@ -166,6 +166,37 @@ export function rejectDone(file) {
     fs.mkdirSync(path.dirname(dest), { recursive: true });
     fs.renameSync(file, dest);
 }
+/** A body with whitespace collapsed and the dispatcher's own format warning removed, so the same text compares equal. */
+function sameText(body) {
+    return body.replace(/^\[agent-lyceum\][^\n]*(\n|$)\s*/, "").replace(/\s+/g, " ").trim();
+}
+/**
+ * An earlier mail from `from` to `to` with the same type, the same reply target and the same text (unread or already read):
+ * sending it again changes nothing and is how two agents end up in a loop. Texts too short to mean anything are never duplicates.
+ */
+function earlierDuplicate(project, from, to, type, replyTo, body) {
+    const text = sameText(body);
+    if (text.length < 20)
+        return undefined;
+    const dir = inboxDir(project, to);
+    for (const d of [dir, path.join(dir, "read")]) {
+        if (!fs.existsSync(d))
+            continue;
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            if (!e.isFile() || !e.name.endsWith(".md") || e.name.startsWith("."))
+                continue;
+            try {
+                const m = readMessage(path.join(d, e.name));
+                if (m.meta.from === from && m.meta.type === type && (m.meta.reply_to ?? "") === (replyTo ?? "") && sameText(m.body) === text)
+                    return m;
+            }
+            catch {
+                /* an unreadable file is not a duplicate of anything */
+            }
+        }
+    }
+    return undefined;
+}
 /** Validate each agent's outbox and move accepted mail into recipients' inboxes. Safe to run again after a crash. */
 export function routeOutboxes(project) {
     const res = { delivered: [], rejected: [], warnings: [], asks: [] };
@@ -250,6 +281,33 @@ export function routeOutboxes(project) {
             }
             const replyTo = d.reply_to ? String(d.reply_to) : undefined;
             const thread = d.thread ? String(d.thread) : undefined;
+            // Mail whose delivery was already planned (a replay after a crash) is not a repeat of itself.
+            const repeats = new Map();
+            for (const to of targets) {
+                if (journal?.get(source, to))
+                    continue;
+                const earlier = earlierDuplicate(project, sender.name, to, type, replyTo, parsed.body);
+                if (earlier)
+                    repeats.set(to, earlier);
+            }
+            const repeatNote = () => [...repeats]
+                .map(([to, m]) => `to "${to}" it repeats mail ${m.meta.id} ("${m.meta.subject}", ${m.meta.created}) with the same content`)
+                .join("; ");
+            const REPEAT_HELP = "Do not send it again: if that mail has not been answered yet, wait for the reply; if you need something different, change what you ask for; if the work is finished, the lead sends `done`.";
+            if (repeats.size === targets.length) {
+                reject(`it is a duplicate: ${repeatNote()}, so it was not sent again. ${REPEAT_HELP}`);
+                continue;
+            }
+            if (repeats.size) {
+                deliverOnce(project, journal, `dup:${source}`, {
+                    from: "dispatcher",
+                    to: sender.name,
+                    type: "failure",
+                    subject: `Part of ${path.basename(file)} was not sent`,
+                    body: `Your outbox message \`${path.basename(file)}\` was delivered, except that ${repeatNote()}. ${REPEAT_HELP}`,
+                });
+                res.rejected.push({ from: sender.name, file, reason: `duplicate: ${repeatNote()}` });
+            }
             const missing = missingSections(type, parsed.body);
             const body = missing.length ? `${formatWarning(type, missing)}\n\n${parsed.body}` : parsed.body;
             if (sender.name === project.lead) {
@@ -258,6 +316,8 @@ export function routeOutboxes(project) {
                     res.steps = st;
             }
             for (const to of targets) {
+                if (repeats.has(to))
+                    continue;
                 const { msg, fresh } = deliverOnce(project, journal, source, { from: sender.name, to, type, subject, body, thread, reply_to: replyTo });
                 if (!fresh)
                     continue;

package/dist/prompt.js

@@ -88,7 +88,7 @@ export function buildSystemPrompt(project, agent) {
         ? `When the whole job is finished, send a message with \`type: done\` (no \`to\` needed). That ends the run. A summary in your reply text is never delivered and does not end the run: after the last teammate reply is verified you MUST send \`done\` (or a \`task\` for the remaining work), or the run stops as "idle" with no final report.`
         : `Report results to the lead by mail; the lead decides what happens next.`, isLead
         ? "Each wake-up handles one message, except that several `reply`/`failure` messages waiting together are handed to you in one wake-up: weigh them together, then decide the next step once."
-        : "Each wake-up handles one message. Do the work it asks, then send the replies that are needed, then stop.", "", "## Message format", "The body of every `task` and `reply` must contain these `##` headings, exactly as written (write `None` under a heading if there is nothing to say).", "Mail missing a heading is still delivered, but is flagged to the recipient.", "", `- \`task\`: ${REQUIRED_SECTIONS.task.map((h) => `\`## ${h}\``).join(", ")} (Upstream = id of the mail this task derives from, or \`None\`).`, `- \`reply\`: ${REQUIRED_SECTIONS.reply.map((h) => `\`## ${h}\``).join(", ")}.`, isLead
+        : "Each wake-up handles one message. Do the work it asks, then send the replies that are needed, then stop.", "Mail that repeats an earlier mail of yours to the same agent (same type, same text) is not sent again; you are told, and should wait for the answer or ask for something different instead of resending.", "", "## Message format", "The body of every `task` and `reply` must contain these `##` headings, exactly as written (write `None` under a heading if there is nothing to say).", "Mail missing a heading is still delivered, but is flagged to the recipient.", "", `- \`task\`: ${REQUIRED_SECTIONS.task.map((h) => `\`## ${h}\``).join(", ")} (Upstream = id of the mail this task derives from, or \`None\`).`, `- \`reply\`: ${REQUIRED_SECTIONS.reply.map((h) => `\`## ${h}\``).join(", ")}.`, isLead
         ? "- `done`: your final report to the user (shown when the run ends, saved as `result.md`). Its frontmatter must contain `outcome: completed|partial|blocked|failed`, and the body the headings `## Result` (the actual deliverable or conclusion, not just \"done\"), `## Files` (paths created or changed), `## Verification` (what you ran or checked, and what it showed) and `## Not done` (anything skipped or unverified, or `None`). Only `completed` means success, and it needs all four headings and every checklist step ticked; if work remains or is blocked, say `partial`/`blocked`/`failed` (those need only `## Result` and `## Not done`). A `done` that breaks this is sent back to you and does not end the run. " + OPEN_PR_RULE
         : "- `done` has no required headings.", ...(agent.canAskUser
         ? [

package/dist/run-outcome.d.ts

@@ -16,7 +16,17 @@ export declare function resolveDoneOutcome(contract: DoneContract, rejections: n
 export declare function endOutcome(endReason: EndReason, done?: {
     outcome: RunOutcome;
     note?: string;
+}, failure?: {
+    agent: string;
+    error?: string;
+    attempts: number;
 }): {
     outcome: RunOutcome;
     note?: string;
 };
+/** What to tell the user when an agent kept failing and the run stopped: where to look, what to fix, how to go on. */
+export declare function failureGuide(project: string, run: string, f: {
+    agent: string;
+    error?: string;
+    attempts: number;
+}, runDir: string): string;

package/dist/run-outcome.js

@@ -1,3 +1,4 @@
+import path from "node:path";
 /** What a lead's `done` amounts to: its declared outcome, unless the contract is broken or member work never reached the repo. */
 export function resolveDoneOutcome(contract, rejections, unintegrated) {
     const ok = contract.missing.length === 0;
@@ -10,12 +11,18 @@ export function resolveDoneOutcome(contract, rejections, unintegrated) {
     return { outcome, note, verification: contract.verification };
 }
 /** How a run turned out, from why it stopped (`done` carries the lead's own verdict). */
-export function endOutcome(endReason, done) {
+export function endOutcome(endReason, done, failure) {
     switch (endReason) {
         case "done":
             return { outcome: done?.outcome ?? "partial", note: done?.note };
         case "lead_failed":
-            return { outcome: "failed", note: "The lead's wake-up failed." };
+        case "agent_failed":
+            return {
+                outcome: "failed",
+                note: failure
+                    ? `${failure.agent} failed ${failure.attempts} time(s) in a row (${failure.error ?? "unknown error"}), so the run stopped. The message it was handling is still unread.`
+                    : "The lead's wake-up failed.",
+            };
         case "waiting":
             return { outcome: "waiting", note: "Waiting for your answers. Fill in ask-reply.md or run `agent-lyceum resume <run-id> --answer`, then continue with `agent-lyceum resume`." };
         case "cancelled":
@@ -26,3 +33,16 @@ export function endOutcome(endReason, done) {
             return { outcome: "partial", note: "Stopped at the round limit before the lead sent done." };
     }
 }
+/** What to tell the user when an agent kept failing and the run stopped: where to look, what to fix, how to go on. */
+export function failureGuide(project, run, f, runDir) {
+    return [
+        "",
+        `${f.agent} was called ${f.attempts} time(s) and failed every time (${f.error ?? "unknown error"}). The run stopped; nothing was lost: the message ${f.agent} was handling is still unread and the work done so far is kept.`,
+        "To fix it:",
+        `  1. Read why it failed: ${path.join(runDir, "log.jsonl")} (event "wake"), and the full output of each attempt in ${path.join(runDir, "mail", "attempts")}`,
+        `  2. Fix the cause: the ${f.agent} CLI (installed, logged in, model name), a timeout (dispatcher.wake_timeout_sec), or its AGENT.md / the message it keeps failing on. Check with: agent-lyceum doctor -p ${project}`,
+        "To go on:",
+        `  agent-lyceum resume ${run} -p ${project}      (the same message is handled again; the task is not re-sent)`,
+        `  Or give up on it: agent-lyceum clear ${run} -p ${project}`,
+    ].join("\n");
+}

package/dist/run-session.d.ts

@@ -33,6 +33,14 @@ export interface RunSummary {
     resultBranch?: ResultBranch;
     /** The lead asked for a pull request: what became of it. */
     pr?: PrOutcome;
+    /** The project's name, for the commands printed after the run. */
+    project: string;
+    /** The run stopped because this agent kept failing. */
+    failure?: {
+        agent: string;
+        error?: string;
+        attempts: number;
+    };
 }
 export interface RunOptions {
     project: ResolvedProject;
@@ -78,6 +86,7 @@ export declare class RunSession {
     private pendingDoneFile;
     private doneOutcome;
     private doneNote;
+    private failure;
     private doneVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     private openPrRequested;

package/dist/run-session.js

@@ -13,7 +13,7 @@ import { outboxDir, ownsDirs, sharedIndex } from "./policy.js";
 import { buildSystemPrompt, buildUserPrompt, pickMessages } from "./prompt.js";
 import { atomicWrite, readFileCapped } from "./fs-util.js";
 import { assertWorktreeRunnable, collectAgentChanges, dirtyPaths, existingAgentWorkspace, finishLeadBranch, integrateAgentChanges, prepareAgentWorkspace, recutLeadWorkspace, refusedIntegration, resolveWorkspaceMode, snapshotBase, snapshotHead, toplevel } from "./worktree.js";
-import { bindRunProject, newRunId, newRunState, roundLimit, saveRunState } from "./run-store.js";
+import { bindRunProject, newRunId, newRunState, roundLimit, roundsLabel, saveRunState } from "./run-store.js";
 import { soloProject } from "./solo.js";
 import { taskMessageBody } from "./task.js";
 import { must } from "./assert.js";
@@ -58,6 +58,7 @@ export class RunSession {
     pendingDoneFile;
     doneOutcome;
     doneNote;
+    failure;
     doneVerification;
     /** The accepted `done` carried `open_pr: true` (only the lead can send `done`). */
     openPrRequested = false;
@@ -124,7 +125,7 @@ export class RunSession {
         }
         let state;
         if (resume) {
-            state = { ...resume, max_rounds: roundLimit(resume, cfg.max_rounds), pid: process.pid, ended_at: undefined, end_reason: undefined, workspace_mode: wsMode, outcome: undefined, outcome_note: undefined, verification: undefined, active: {}, wakes: [...resume.wakes] };
+            state = { ...resume, max_rounds: roundLimit(resume, cfg.max_rounds), pid: process.pid, ended_at: undefined, end_reason: undefined, failure: undefined, workspace_mode: wsMode, outcome: undefined, outcome_note: undefined, verification: undefined, active: {}, wakes: [...resume.wakes] };
             // A wake that was running when the process died never finished; keep it in the history as interrupted.
             for (const [agent, a] of Object.entries(resume.active ?? {})) {
                 state.wakes.push({
@@ -304,14 +305,16 @@ export class RunSession {
         };
         let result;
         for (let attempt = 0; attempt <= cfg.retry; attempt++) {
-            if (state.rounds >= state.max_rounds) {
-                result = { ok: false, text: "", exitCode: null, timedOut: false, error: "round limit reached" };
-                break;
+            if (state.max_rounds > 0 && state.rounds >= state.max_rounds) {
+                // The round limit (when one is set) ends the run; this message stays unread for the resume.
+                abandonClaim(runDir, claim.id);
+                claims.delete(agent.name);
+                return { ok: false, cancelled: true };
             }
             const round = ++state.rounds;
             const started = Date.now();
             const att = beginAttempt(runDir, claim.id);
-            say(`[round ${state.rounds}/${state.max_rounds}] waking ${agent.name} (${agent.runtime})${attempt ? ` — retry ${attempt}` : ""}`);
+            say(`[round ${roundsLabel(state.rounds, state.max_rounds)}] waking ${agent.name} (${agent.runtime})${attempt ? ` — retry ${attempt}` : ""}`);
             const sessionId = agent.resume ? state.sessions[agent.name] : undefined;
             const handling = unread.map((m) => ({ from: m.meta.from, type: m.meta.type, subject: m.meta.subject, brief: briefOf(m.body), digest: digestOf(m.meta.type, m.body) }));
             // What the panel shows for the message being worked on is uncut; the wake record below keeps the short digest.
@@ -380,16 +383,10 @@ export class RunSession {
         if (result?.ok)
             markOutputReady(runDir, claim.id);
         if (!result?.ok) {
-            if (agent.name === project.lead)
-                return { ok: false };
-            deliverOnce(project, this.journal(), `wakefail:${claim.id}`, {
-                from: "dispatcher",
-                to: project.lead,
-                type: "failure",
-                subject: `${agent.name} failed`,
-                body: `Agent "${agent.name}" could not handle message(s) "${unread.map((m) => m.meta.subject).join('", "')}".\n\nError: ${result?.error ?? "unknown"}\n\nDecide whether to retry, reassign, or adjust the plan.`,
-            });
-            return { ok: false };
+            // The agent failed every time it was called: the run stops here (see settle) and its message stays unread for the resume.
+            abandonClaim(runDir, claim.id);
+            claims.delete(agent.name);
+            return { ok: false, error: result?.error, attempts: cfg.retry + 1 };
         }
         return { ok: true };
     }
@@ -553,10 +550,12 @@ export class RunSession {
             this.endReason = "waiting";
             return;
         }
-        const leadIdx = batch.findIndex((a) => a.name === project.lead);
-        const leadResult = leadIdx >= 0 ? results[leadIdx] : undefined;
-        if (leadResult && !leadResult.ok && !leadResult.cancelled) {
-            this.endReason = "lead_failed";
+        const failedIdx = results.findIndex((r) => !r.ok && !r.cancelled);
+        if (failedIdx >= 0) {
+            const failed = must(batch[failedIdx], "failed agent");
+            this.failure = { agent: failed.name, error: results[failedIdx]?.error, attempts: results[failedIdx]?.attempts ?? this.cfg.retry + 1 };
+            state.failure = this.failure;
+            this.endReason = failed.name === project.lead ? "lead_failed" : "agent_failed";
             return;
         }
     }
@@ -757,7 +756,7 @@ export class RunSession {
                 this.endReason = "idle";
                 break;
             }
-            if (state.rounds >= state.max_rounds) {
+            if (state.max_rounds > 0 && state.rounds >= state.max_rounds) {
                 this.endReason = "max_rounds";
                 break;
             }
@@ -799,7 +798,7 @@ export class RunSession {
                 this.endReason = "cancelled";
         }
         const endReason = must(this.endReason, "end reason");
-        const { outcome, note: outcomeNote } = endOutcome(endReason, endReason === "done" ? { outcome: this.doneOutcome ?? "partial", note: this.doneNote } : undefined);
+        const { outcome, note: outcomeNote } = endOutcome(endReason, endReason === "done" ? { outcome: this.doneOutcome ?? "partial", note: this.doneNote } : undefined, this.failure);
         state.end_reason = endReason;
         state.outcome = outcome;
         state.outcome_note = outcomeNote;
@@ -819,6 +818,6 @@ export class RunSession {
         this.saveState();
         if (this.pendingDoneFile)
             finishDone(this.pendingDoneFile);
-        return { runId, name: state.name, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined, resultBranch, pr };
+        return { runId, name: state.name, runDir, rounds: state.rounds, endReason, outcome, outcomeNote, verification: this.doneVerification, doneMessage: this.doneMessage, askReplyPath: endReason === "waiting" ? askReplyPath(runDir) : undefined, resultBranch, pr, project: project.name, failure: this.failure };
     }
 }

package/dist/run-store.d.ts

@@ -4,7 +4,7 @@ import type { RunOutcome } from "./schema.js";
 import type { ResultBranch } from "./worktree.js";
 export declare const STATE_FILE = "state.json";
 export declare const STATE_SCHEMA_VERSION = 2;
-export type EndReason = "done" | "idle" | "max_rounds" | "lead_failed" | "cancelled" | "waiting";
+export type EndReason = "done" | "idle" | "max_rounds" | "lead_failed" | "agent_failed" | "cancelled" | "waiting";
 export type MailLayout = "run" | "legacy";
 export interface WakeTopic {
     from: string;
@@ -97,6 +97,12 @@ export interface RunState {
     active: Record<string, ActiveWake>;
     /** Finished wakes, oldest first. */
     wakes: WakeRecord[];
+    /** Set when the run stopped because an agent kept failing: who, the last error, how many times it was called. */
+    failure?: {
+        agent: string;
+        error?: string;
+        attempts: number;
+    };
     /** Checklist progress: seeded from the task, then replaced by the lead's latest `## Steps` (after a reopen, added to `step_base`). */
     steps?: Step[];
     /** The checklist as it stood at the last reopen: the follow-up's steps are shown after it, and its open steps do not hold up the follow-up's done. */
@@ -154,4 +160,7 @@ export type Resolved = {
 };
 /** Find a run by full id, exact name, or a prefix of either that matches exactly one run. An exact id or name always wins. */
 export declare function resolveRun(runs: RunRef[], query: string): Resolved;
+/** The round the run stops at; 0 (`dispatcher.max_rounds: 0`) means there is no limit. */
 export declare const roundLimit: (state: Pick<RunState, "round_floor">, maxRounds: number) => number;
+/** `rounds`, or `rounds/limit` when the run has a limit. */
+export declare const roundsLabel: (rounds: number, limit: number) => string;

package/dist/run-store.js

@@ -23,7 +23,7 @@ const WireState = z
     ended_at: z.string().optional(),
     rounds: nonNeg.optional(),
     max_rounds: nonNeg.optional(),
-    end_reason: z.enum(["done", "idle", "max_rounds", "lead_failed", "cancelled", "waiting"]).optional(),
+    end_reason: z.enum(["done", "idle", "max_rounds", "lead_failed", "agent_failed", "cancelled", "waiting"]).optional(),
     outcome: z.enum(["completed", "partial", "blocked", "failed", "waiting", "cancelled"]).optional(),
     outcome_note: z.string().optional(),
     verification: z.string().optional(),
@@ -39,6 +39,7 @@ const WireState = z
     wakes: z.array(z.any()).optional(),
     solo_agent: z.string().optional(),
     steps: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
+    failure: z.object({ agent: z.string(), error: z.string().optional(), attempts: z.number() }).optional(),
     step_base: z.array(z.object({ text: z.string(), done: z.boolean() })).optional(),
     name: z.string().optional(),
     reopened: z.array(z.object({ at: z.string() })).optional(),
@@ -121,7 +122,7 @@ export function outcomeOf(s) {
         return { outcome: s.outcome, verified: true };
     if (!s.end_reason)
         return undefined;
-    return { outcome: s.end_reason === "lead_failed" ? "failed" : s.end_reason === "cancelled" ? "cancelled" : s.end_reason === "waiting" ? "waiting" : "partial", verified: false };
+    return { outcome: s.end_reason === "lead_failed" || s.end_reason === "agent_failed" ? "failed" : s.end_reason === "cancelled" ? "cancelled" : s.end_reason === "waiting" ? "waiting" : "partial", verified: false };
 }
 const NAME_MAX = 30;
 export function slugify(text) {
@@ -157,4 +158,7 @@ export function resolveRun(runs, query) {
         return { ok: true, run: pool[0] };
     return { ok: false, reason: pool.length ? "ambiguous" : "none", candidates: pool };
 }
-export const roundLimit = (state, maxRounds) => (state.round_floor ?? 0) + maxRounds;
+/** The round the run stops at; 0 (`dispatcher.max_rounds: 0`) means there is no limit. */
+export const roundLimit = (state, maxRounds) => (maxRounds > 0 ? (state.round_floor ?? 0) + maxRounds : 0);
+/** `rounds`, or `rounds/limit` when the run has a limit. */
+export const roundsLabel = (rounds, limit) => (limit > 0 ? `${rounds}/${limit}` : String(rounds));

package/dist/scaffold.js

@@ -85,12 +85,12 @@ dir: ${repo}            # the repo the agents work in (the tool never writes con
 team:
   lead: lead
 dispatcher:
-  max_rounds: 30        # stop after this many agent wake-ups
+  max_rounds: 0         # 0 = no limit on wake-ups; set a number to stop a run after that many
   max_parallel: 1       # >1 needs non-overlapping "owns" for every non-lead agent, and a git repo
   max_concurrent_runs: 1  # >1 lets several runs of this project be active at once, each in its own git worktree (needs a git repo); every run's work stays on its own branch
   workspace_mode: auto  # auto = a git worktree per non-lead agent when max_parallel > 1; shared | worktree to force
   wake_timeout_sec: 600
-  retry: 1
+  retry: 2              # an agent that fails is called again up to this many times; if it still fails the run stops (resume it after fixing the cause)
   log_max_bytes: 8388608  # log.jsonl is renamed to log.1.jsonl past this size; 0 = never
   strict: false         # true = refuse to start unless context protection is OS-enforced
 agents:

package/dist/schema.js

@@ -43,7 +43,7 @@ export const AgentPartial = z
     .strict();
 export const DispatcherPartial = z
     .object({
-    max_rounds: z.number().int().positive().optional(),
+    max_rounds: z.number().int().min(0).optional(),
     max_parallel: z.number().int().positive().optional(),
     max_concurrent_runs: z.number().int().positive().optional(),
     wake_timeout_sec: z.number().int().positive().optional(),
@@ -67,11 +67,11 @@ export const ProjectConfig = z
 })
     .strict();
 export const DISPATCHER_DEFAULTS = {
-    max_rounds: 30,
+    max_rounds: 0,
     max_parallel: 1,
     max_concurrent_runs: 1,
     wake_timeout_sec: 600,
-    retry: 1,
+    retry: 2,
     strict: false,
     workspace_mode: "auto",
     log_max_bytes: 8 * 1024 * 1024,

package/dist/status.d.ts

@@ -69,7 +69,14 @@ export interface RunReport {
     started_at: string;
     ended_at?: string;
     rounds: number;
+    /** 0 = no limit. */
     max_rounds: number;
+    /** Set when an agent kept failing and the run stopped: `resume` after fixing the cause. */
+    failure?: {
+        agent: string;
+        error?: string;
+        attempts: number;
+    };
     output_tokens: number;
     task_source: "text" | "file";
     task_path?: string;

package/dist/status.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { askReplyPath, readAskReply } from "./ask-reply.js";
 import { RESULT_FILE } from "./dispatcher.js";
-import { bindRunProject, loadRunState, outcomeOf, runLabel } from "./run-store.js";
+import { bindRunProject, loadRunState, outcomeOf, roundsLabel, runLabel } from "./run-store.js";
 import { briefOf, digestOf } from "./format.js";
 import { listUnread } from "./mailbox.js";
 import { tidyAdvice } from "./memory-tidy.js";
@@ -204,6 +204,7 @@ export function buildRunReport(run, project, opts = {}) {
         ended_at: s.ended_at,
         rounds: s.rounds,
         max_rounds: s.max_rounds,
+        ...(s.failure ? { failure: s.failure } : {}),
         output_tokens: s.output_tokens,
         task_source: s.task_source,
         task_path: s.task_path,
@@ -289,11 +290,11 @@ function summaryBlock(run, now, c) {
     const s = run;
     const live = s.live;
     const lines = [
-        `${c.bold("執行 " + runLabel(s))}  [${stateColor(c, reportLabel(s))}]  第 ${s.rounds}/${s.max_rounds} 輪`,
+        `${c.bold("執行 " + runLabel(s))}  [${stateColor(c, reportLabel(s))}]  第 ${roundsLabel(s.rounds, s.max_rounds)} 輪`,
         `${L("任務：")}${taskText(s)}`,
     ];
     const steps = stepsLine(s.steps, c, s.end_reason === "done");
-    lines.push(`${L("進度：")}${steps ?? `無清單；已用 ${s.rounds}/${s.max_rounds} 輪（lead 可在信中加入 "## Steps" 清單）`}`);
+    lines.push(`${L("進度：")}${steps ?? `無清單；已用 ${roundsLabel(s.rounds, s.max_rounds)} 輪（lead 可在信中加入 "## Steps" 清單）`}`);
     const active = Object.entries(s.active ?? {});
     if (active.length) {
         for (const [i, [agent, a]] of active.entries()) {
@@ -319,6 +320,9 @@ function summaryBlock(run, now, c) {
     const lastWake = (s.wakes ?? []).at(-1);
     if (lastWake)
         lines.push(`${L("上一次：")}#${lastWake.round} ${c.cyan(lastWake.agent)} ${okText(c, lastWake.ok)} → ${sentText(lastWake.sent)}`);
+    if (s.failure) {
+        lines.push(`${L("需要處理：")}${c.red(`${s.failure.agent} 呼叫 ${s.failure.attempts} 次都失敗`)}（${clip(s.failure.error ?? "未知錯誤", 80)}）`, c.dim(`          查 log 找原因並修正後，執行 agent-lyceum resume ${s.run_id} 從同一封信繼續（或 agent-lyceum clear ${s.run_id} 放棄）`));
+    }
     if (s.ask)
         lines.push(`${L("等你回答：")}${s.ask.unanswered}/${s.ask.total} 題未答 → ${s.ask.path}`, c.dim(`          填完後執行 agent-lyceum resume ${s.run_id} --answer`));
     lines.push(`${L("流程：")}${flowLine(s, c)}`);
@@ -327,7 +331,7 @@ function summaryBlock(run, now, c) {
 /** What a run is doing / did, one line per wake. */
 function describeRun(s, now, c, limit = Infinity) {
     const lines = [
-        `${c.bold("執行 " + runLabel(s))}  [${stateColor(c, reportLabel(s))}]  輪次 ${s.rounds}/${s.max_rounds}  輸出 tokens ${tokens(s.output_tokens)}`,
+        `${c.bold("執行 " + runLabel(s))}  [${stateColor(c, reportLabel(s))}]  輪次 ${roundsLabel(s.rounds, s.max_rounds)}  輸出 tokens ${tokens(s.output_tokens)}`,
         `  任務：${taskText(s)}`,
     ];
     const steps = stepsLine(s.steps, c);
@@ -401,7 +405,7 @@ export function formatTaskListReport(report, color = false) {
             ...(named ? [s.name ?? ""] : []),
             s.run_id,
             reportLabel(s),
-            `${s.rounds}/${s.max_rounds}`,
+            roundsLabel(s.rounds, s.max_rounds),
             s.steps?.length ? (s.current_step ? clip(s.current_step, 30) : "全部完成") : "-",
             clip(taskText(s), 60),
         ]);

package/package.json

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