agent-lyceum 0.11.0 → 0.13.0

package/README.md

@@ -31,7 +31,7 @@ Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (already logged i
 | 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 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` / `clear --lock [run-id] --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 | `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) |
@@ -89,7 +89,7 @@ Changes take effect on the next session start. If the pane shows `無法取得
     ├── project.yaml                  # team, repo dir, overrides
     ├── agents/<agent>/{AGENT.md?, memory/}   # project-level persona (optional) + project memory
     ├── shared/common/COMMON.md
-    ├── lock.json                     # held while a run is active: one run per project
+    ├── locks/<run-id>.json           # held while that run is active (up to dispatcher.max_concurrent_runs at once)
     └── runs/<run-id>/{task.md, log.jsonl, state.json, snapshots/, agents/, mail/{inbox,outbox}/<agent>/}
 ```
 
@@ -99,7 +99,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, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto, log_max_bytes: 8388608 }
+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 }
 agents:
   lead:      { resume: true, can_message: all, can_edit_agent_md: true }
   fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
@@ -109,7 +109,7 @@ agents:
 
 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), `allow_web` (`none`|`search`|`fetch`; what the agent may use of the web, off unless set; see "Web access" below), `owns` (repo globs).
 
-Rules checked by `doctor`: ≥ 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.
+Rules checked by `doctor`: ≥ 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, and with `max_concurrent_runs > 1` the repo must be a git repository and `workspace_mode` must not be shared.
 
 ## How a run works
 
@@ -122,6 +122,31 @@ Rules checked by `doctor`: ≥ 2 agents (the lead and one member; the template h
 
 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.
 
+### Several runs at once
+
+By default a project runs one task at a time. Set `dispatcher.max_concurrent_runs: N` (N > 1, needs a git repository) to let up to N runs of the same project be active together; starting one more is refused and names the runs in the way. In this mode **every** run, including a run that has no parallel members and a solo `run --agent <name>`, works in its own git worktree: the lead in `projects/<name>/worktrees/<run-id>/<lead>` on branch `agent-lyceum/<run-id>/<lead>`, members in worktrees cut from the lead's. A run starts from your repo's `HEAD`, so your uncommitted changes are allowed and are **not** part of it (the start line says how many files that is). Your working tree, index and HEAD are never touched.
+
+- **Ending:** when a run ends (done, cancelled, failed, idle or round limit), the lead's work is committed once on its branch and written as `runs/<run-id>/lead.patch`, and the run prints `git merge <branch>`. A run that stops to ask you (`waiting`) is not finished: nothing is committed and no merge hint is printed; its work stays in the lead's worktree and `resume` continues in the same one.
+- **Decided at start:** a run records whether its lead works in a worktree (`lead_workspace` in its state). `resume` follows what the run was started with, not the current setting: a run started concurrent resumes in its worktree even if you lowered `max_concurrent_runs`, and a run started non-concurrent resumes non-concurrently even if you raised it. The setting only governs how many runs may be active at once and what new runs do.
+- **`tidy`:** `tidy` and `tidy --undo` need the project to themselves: they are refused while any run is active, and no run can start while they run, whatever `max_concurrent_runs` is.
+- **`clear`:** `clear <run-id>` refuses while the lead's branch is not merged (use `--keep-worktrees` to keep it). A lock left by a crashed run is removed with `clear --lock [run-id] [-p name] --force`; with several locks, name the run.
+
+Known limits:
+
+- The number of agent processes can reach `max_concurrent_runs × max_parallel`; there is no global cap.
+- A lead with `can_edit_agent_md: true` edits the `CLAUDE.md`/`AGENTS.md` in its own worktree; the change reaches your repo only when you merge its branch.
+- `COMMON.md` and the `AGENT.md` files are shared by all runs of the project. Each run's guard only judges what changes while its own agents are working, so an edit by one run is kept; but if two runs' wake-ups overlap in time, a change one makes while the other's agents are working can be reverted by the other.
+- Two runs that edit the same file are for you to reconcile when merging; agent-lyceum never merges.
+
+### Opening a pull request
+
+When your task asks for a pull request, the lead puts `open_pr: true` in the frontmatter of its `done` report. If the run then ends `completed` and the lead's branch has changes, agent-lyceum — not an agent — pushes `agent-lyceum/<run-id>/<lead>` to `origin` and runs `gh pr create` against the repo's default branch, using the lead's report as the description (ending with `🤖 Opened by agent-lyceum`). The run result prints the PR URL, and `state.json` records it as `pr_url`. Only the lead can ask: nobody else can send `done`, and no agent's sandbox is loosened — `git push` and `gh` run outside it, with your own credentials.
+
+- It needs a lead branch, so it works only when the run has its own worktree (`dispatcher.max_concurrent_runs` of 2 or more). Otherwise the request is reported and skipped.
+- A request that cannot be honoured (the run did not complete, no changes, no `gh`, no `origin`, push or `gh` failed) never changes how the run turned out. The run says why it was not opened and keeps the branch; when a push or `gh pr create` failed it also prints the commands to finish by hand.
+- Opening a pull request publishes the lead's branch and report to `origin`. An agent that asks for one (`open_pr: true`) can therefore get anything it can read inside its sandbox onto the remote, so only ask for a pull request in a task when that is acceptable. The push and `gh pr create` run from your main repository, never inside the agent's worktree, because an agent can write that directory.
+- agent-lyceum never merges and does not wait for CI or review. With `max_concurrent_runs` of 2 or more, `doctor` tells you whether `gh` and `origin` are there (it does not check that `gh` is logged in).
+
 ## Web access (`allow_web`)
 
 By default no agent can use the web. Claude Code agents are woken in headless `dontAsk` mode, where anything not explicitly allowed is refused, so `WebSearch` and `WebFetch` are denied unless you opt in per agent with `allow_web` (in `team.yaml` or `project.yaml`; the project value wins). It only decides whether the agent may use the web tools; the write scope below is unchanged.

package/README.zh-TW.md

@@ -31,7 +31,7 @@ npx agent-lyceum status
 | 診斷 | `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) |
+| 執行 | `clear <run-id> [-p name] [--dry-run] [--keep-worktrees]` / `clear --lock [run-id] --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) |
 | 執行 | `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) |
@@ -89,7 +89,7 @@ claude --plugin-dir /path/to/agent-lyceum/plugins/status-monitor
     ├── project.yaml                  # 團隊、repo 路徑、覆寫設定
     ├── agents/<agent>/{AGENT.md?, memory/}   # 專案層人設（選用）+ 專案記憶
     ├── shared/common/COMMON.md
-    ├── lock.json                     # run 執行期間持有：同一專案同時只能有一個 run
+    ├── locks/<run-id>.json           # 該 run 執行期間持有（同時最多 dispatcher.max_concurrent_runs 個）
     ├── task-memory/<run-id>/<agent>/   # 任務記憶：每次 run 獨立，不與其他任務共用
     └── runs/<run-id>/{task.md, log.jsonl, state.json, snapshots/, agents/, mail/{inbox,outbox}/<agent>/}
 ```
@@ -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, wake_timeout_sec: 600, retry: 1, strict: false, workspace_mode: auto, log_max_bytes: 8388608 }
+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 }
 agents:
   lead:      { resume: true, can_message: all, can_edit_agent_md: true }
   fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
@@ -110,7 +110,7 @@ agents:
 
 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）、`allow_web`（`none`|`search`|`fetch`：agent 可以使用多少網路，不設就是不開；見下方「網路存取」）、`owns`（repo glob）。
 
-`doctor` 檢查的規則：至少 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。
+`doctor` 檢查的規則：至少 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；而 `max_concurrent_runs > 1` 時，repo 必須是 git repository，且 `workspace_mode` 不能是 `shared`。
 
 ## 一次執行如何運作
 
@@ -123,6 +123,31 @@ Agent 欄位：`runtime`（`claude-code`|`codex`；若 `model` 可辨識則可
 
 平行執行（`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 只隔離檔案，無法隔離對外部服務、資料庫或網路的副作用。
 
+### 同時執行多個 task
+
+預設一個專案一次只跑一個 task。設定 `dispatcher.max_concurrent_runs: N`（N > 1，需要 git repository）後，同一專案最多可有 N 個 run 同時進行；再多開一個會被拒絕，並列出擋住的 run。此模式下**每個** run（包括沒有平行成員的 run，以及單獨的 `run --agent <name>`）都在自己的 git worktree 工作：lead 在 `projects/<name>/worktrees/<run-id>/<lead>`、branch 為 `agent-lyceum/<run-id>/<lead>`，成員的 worktree 則從 lead 的內容分出。run 從你 repo 的 `HEAD` 起跑，所以允許你有未提交的修改，但這些修改**不會**在其中（啟動訊息會寫出有幾個檔案）。你的工作目錄、index 與 HEAD 一律不會被動到。
+
+- **結束：** run 結束時（done、cancelled、failed、idle 或達到輪數上限），lead 的成果會一次提交在它的 branch 上，並寫成 `runs/<run-id>/lead.patch`，run 會印出 `git merge <branch>`。停下來向你提問（`waiting`）的 run 還沒結束：不會提交、也不會印 merge 提示；成果留在 lead 的 worktree，`resume` 會在同一個 worktree 繼續。
+- **啟動時決定：** run 會在狀態中記錄 lead 是否在 worktree 工作（`lead_workspace`）。`resume` 沿用 run 啟動時的方式，而不是看目前的設定：以併發模式啟動的 run，即使你之後調低 `max_concurrent_runs`，仍會在它的 worktree 接續；以非併發模式啟動的 run，即使你之後調高，仍以非併發方式接續。這個設定只決定同時可有幾個 run，以及新的 run 怎麼做。
+- **`tidy`：** `tidy` 與 `tidy --undo` 需要獨占專案：有任何 run 在執行時會拒絕，執行期間也不能啟動任何 run，與 `max_concurrent_runs` 的值無關。
+- **`clear`：** lead 的 branch 尚未合併時，`clear <run-id>` 會拒絕（用 `--keep-worktrees` 可保留它）。當機 run 留下的鎖用 `clear --lock [run-id] [-p name] --force` 移除；有多把鎖時要指定是哪個 run。
+
+已知限制：
+
+- agent 程序數量最多可達 `max_concurrent_runs × max_parallel`，沒有全域上限。
+- `can_edit_agent_md: true` 的 lead 修改的是它自己 worktree 裡的 `CLAUDE.md`／`AGENTS.md`；這些修改要等你合併它的 branch 才會進到你的 repo。
+- `COMMON.md` 與各 `AGENT.md` 由專案的所有 run 共用。每個 run 的防護只判斷它自己的 agent 工作期間發生的修改，所以某個 run 的修改會被保留；但若兩個 run 的喚醒時間重疊，一個 run 在另一個 run 的 agent 工作期間所做的修改，可能被另一個 run 還原。
+- 兩個 run 修改同一個檔案時，要由你在合併時自行整合；agent-lyceum 從不自動合併。
+
+### 開 PR
+
+當你的 task 要求開 PR 時，lead 會在它的 `done` 報告的 frontmatter 加上 `open_pr: true`。如果 run 之後以 `completed` 結束，且 lead 的 branch 有變更，就由 agent-lyceum（不是 agent）把 `agent-lyceum/<run-id>/<lead>` 推到 `origin`，並對 repo 的預設分支執行 `gh pr create`，以 lead 的報告作為描述（結尾為 `🤖 Opened by agent-lyceum`）。run 的結果會印出 PR 網址，`state.json` 也會把它記為 `pr_url`。只有 lead 能提出要求：其他人都不能送出 `done`，也沒有任何 agent 的沙箱被放寬——`git push` 與 `gh` 在沙箱外以你自己的憑證執行。
+
+- 它需要 lead 的 branch，所以只有在 run 有自己的 worktree 時（`dispatcher.max_concurrent_runs` 為 2 或以上）才有作用。否則這個要求會被回報並略過。
+- 無法照辦的要求（run 沒有完成、沒有變更、沒有 `gh`、沒有 `origin`、push 或 `gh` 失敗）絕不會改變 run 的結果。run 會說明沒有開的原因並保留 branch；push 或 `gh pr create` 失敗時，還會印出可手動完成的指令。
+- 開 PR 會把 lead 的 branch 與報告發布到 `origin`。因此，提出要求（`open_pr: true`）的 agent 能把它在沙箱內讀得到的任何東西送上遠端，所以只有在可以接受這件事時，才在 task 裡要求開 PR。push 與 `gh pr create` 從你的主 repo 執行，絕不在 agent 的 worktree 裡執行，因為 agent 能寫入那個目錄。
+- agent-lyceum 從不合併，也不等待 CI 或審查。`max_concurrent_runs` 為 2 以上時，`doctor` 會告訴你有沒有 `gh` 與 `origin`（不會檢查 `gh` 是否已登入）。
+
 ## 網路存取（`allow_web`）
 
 預設所有 agent 都不能使用網路。Claude Code 的 agent 是用無頭的 `dontAsk` 模式喚醒的，沒有明確允許的工具一律拒絕，所以 `WebSearch` 與 `WebFetch` 會被擋掉，要替個別 agent 用 `allow_web` 開放（寫在 `team.yaml` 或 `project.yaml`，專案層蓋過全域層）。它只決定 agent 能不能用網路工具，下面的寫入範圍不變。

package/dist/ask-answer.js

@@ -1,13 +1,14 @@
 import { spawnSync } from "node:child_process";
-import { applyDefaults, askReplyPath, checkAnswers, describeCheck, isComplete, readAskReply, writeAskReply } from "./ask-reply.js";
+import { applyDefaults, askReplyPath, checkAnswers, describeCheck, isComplete, readAskReply, resolveOptionLetters, 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);
+    const resolved = resolveOptionLetters(reply);
+    if (JSON.stringify(resolved) !== JSON.stringify(reply) || opts.assumeDefaults) {
+        reply = opts.assumeDefaults ? applyDefaults(resolved) : resolved;
         writeAskReply(runDir, reply);
     }
     const check = checkAnswers(reply);

package/dist/ask-reply.d.ts

@@ -55,6 +55,8 @@ export interface AnswerCheck {
     }[];
 }
 export declare const isComplete: (c: AnswerCheck) => boolean;
+/** An answer that is just a letter ("b", "B:", "b)") becomes the one option that starts with that letter and a ":", "." or ")". No match, or more than one, leaves it as typed. */
+export declare function resolveOptionLetters(r: AskReply): AskReply;
 /** Only questions whose answer was not sent yet count. */
 export declare function checkAnswers(r: AskReply): AnswerCheck;
 export declare function describeCheck(c: AnswerCheck): string[];

package/dist/ask-reply.js

@@ -123,6 +123,19 @@ function problem(q) {
         return `must be one of: ${q.options.join(", ")} — or start with "other:" and write your own`;
     return undefined;
 }
+/** An answer that is just a letter ("b", "B:", "b)") becomes the one option that starts with that letter and a ":", "." or ")". No match, or more than one, leaves it as typed. */
+export function resolveOptionLetters(r) {
+    return {
+        ...r,
+        questions: r.questions.map((q) => {
+            const v = q.answer?.value.trim().match(/^([A-Za-z])[:.)]?$/)?.[1]?.toLowerCase();
+            if (q.delivered || !v || !q.options?.length)
+                return q;
+            const hits = q.options.filter((o) => o.toLowerCase().match(/^([a-z])[:.)]/)?.[1] === v);
+            return hits.length === 1 && q.answer ? { ...q, answer: { ...q.answer, value: hits[0] } } : q;
+        }),
+    };
+}
 /** Only questions whose answer was not sent yet count. */
 export function checkAnswers(r) {
     const c = { missing: [], invalid: [] };

package/dist/cli.js

@@ -9,7 +9,7 @@ import { restoreMemory, tidyMemory, tidyStamp } from "./memory-tidy.js";
 import { RESULT_FILE, runTeam } from "./dispatcher.js";
 import { executeRunCleanup, planRunCleanup } from "./run-cleanup.js";
 import { diagnoseProject, formatDoctor, preflightRuntimes } from "./doctor.js";
-import { acquireProjectLock, forceUnlock, inspectProjectLock, lockHolderAlive } from "./project-lock.js";
+import { acquireProjectLock, forceUnlock, inspectRunLock, listRunLocks, listUnreadableRunLocks, LOCK_FILE, lockHolderAlive } from "./project-lock.js";
 import { loadRunState, newRunId, outcomeOf } from "./run-store.js";
 import { exitCodeForOutcome } from "./schema.js";
 import { absPath, assertName, projectPaths, resolveHome } from "./paths.js";
@@ -116,10 +116,10 @@ async function preflight(pr) {
     if (r.errors.length)
         fail(`${r.errors.map((e) => `ERROR  ${e}`).join("\n")}\nFix the above (see \`agent-lyceum doctor\`).`);
 }
-/** Take the project's single-run lock, or exit with the reason. */
-function takeLock(pr, runId) {
+/** Take the lock of one run, or exit with the reason. `ignoreLimit`: the caller does not start a run (e.g. `clear`). `exclusive`: it needs the whole project (memory tidy). */
+function takeLock(pr, runId, opts = {}) {
     try {
-        return acquireProjectLock(pr.paths.root, runId);
+        return acquireProjectLock(pr.paths.root, runId, { maxConcurrent: opts.ignoreLimit ? Number.MAX_SAFE_INTEGER : pr.dispatcher.max_concurrent_runs, exclusive: opts.exclusive });
     }
     catch (e) {
         return fail(e.message);
@@ -156,6 +156,17 @@ function printRun(summary, runDir) {
         console.log(`Note: ${summary.outcomeNote}`);
     if (summary.verification)
         console.log(`Verification (as reported by the lead, not checked by agent-lyceum): ${summary.verification}`);
+    if (summary.resultBranch?.files) {
+        console.log(`\nThe work is on branch ${summary.resultBranch.branch} (${summary.resultBranch.files} file(s)); your working tree was not touched.\nBring it in with: git merge ${summary.resultBranch.branch}${summary.resultBranch.patch ? `\n(or apply the patch: git apply ${summary.resultBranch.patch})` : ""}`);
+    }
+    if (summary.pr) {
+        if (summary.pr.status === "opened")
+            console.log(`\nPull request opened: ${summary.pr.url}`);
+        else if (summary.pr.status === "skipped")
+            console.log(`\nA pull request was asked for but not opened: ${summary.pr.reason}`);
+        else
+            console.log(`\nThe pull request could not be opened (${summary.pr.step}: ${summary.pr.reason}).${summary.pr.manual.length ? ` To finish by hand:\n${summary.pr.manual.map((m) => `  ${m}`).join("\n")}` : ""}`);
+    }
     if (summary.doneMessage) {
         console.log(`\nLead's final message — ${summary.doneMessage.subject}\n\n${summary.doneMessage.body}`);
         console.log(`\nResult saved to: ${path.join(runDir, RESULT_FILE)}`);
@@ -330,22 +341,51 @@ program
     }
 });
 /** Color when writing to a terminal, unless NO_COLOR is set; FORCE_COLOR overrides. */
-/** `clear --lock`: show who holds the project lock; remove it only with --force. */
-function unlockProject(pr, force) {
-    const info = inspectProjectLock(pr.paths.root);
-    if (!info && !fs.existsSync(path.join(pr.paths.root, "lock.json"))) {
-        console.log(`Project ${pr.name} has no run lock.`);
+/** `clear --lock [run-id]`: show who holds a run lock; remove it only with --force. With several locks, name the run. */
+function unlockProject(pr, runId, force) {
+    const root = pr.paths.root;
+    const locks = listRunLocks(root);
+    const unreadable = listUnreadableRunLocks(root);
+    if (runId && unreadable.includes(runId)) {
+        console.log(`The lock file of run ${runId} exists but cannot be read.`);
+        if (!force)
+            fail("Not removed. Check that no run is active, then repeat with --force.");
+        forceUnlock(root, runId);
+        console.log(`Lock removed. Resume the run with: agent-lyceum resume ${runId}`);
         return;
     }
-    if (info) {
-        console.log(`Lock held for run ${info.run_id} by pid ${info.pid} on ${info.hostname}, last heartbeat ${info.heartbeat_at}${lockHolderAlive(info) ? " (that process is still alive)" : " (that process is gone)"}.`);
+    if (!runId && unreadable.length && locks.length + unreadable.length > 1) {
+        const list = [...locks.map((l) => `  ${l.run_id}  pid ${l.pid}${lockHolderAlive(l) ? " (alive)" : " (gone)"}`), ...unreadable.map((id) => `  ${id}  (lock file cannot be read)`)].join("\n");
+        fail(`Several runs hold a lock:\n${list}\nName the one to unlock: agent-lyceum clear --lock <run-id> --force`);
+    }
+    if (!runId && unreadable.length && !locks.length) {
+        fail(`The lock file of run ${unreadable[0]} cannot be read. Name it to remove it: agent-lyceum clear --lock ${unreadable[0]} --force`);
+    }
+    if (!runId && locks.length > 1) {
+        const list = locks.map((l) => `  ${l.run_id}  pid ${l.pid}${lockHolderAlive(l) ? " (alive)" : " (gone)"}`).join("\n");
+        fail(`Several runs hold a lock:\n${list}\nName the one to unlock: agent-lyceum clear --lock <run-id> --force`);
     }
-    else
+    const target = runId ?? locks[0]?.run_id;
+    if (!target) {
+        if (!fs.existsSync(path.join(root, LOCK_FILE))) {
+            console.log(`Project ${pr.name} has no run lock.`);
+            return;
+        }
         console.log("The lock file exists but cannot be read.");
+        if (!force)
+            fail("Not removed. Check that no run is active, then repeat with --force.");
+        forceUnlock(root);
+        console.log("Lock removed.");
+        return;
+    }
+    const info = inspectRunLock(root, target);
+    if (!info)
+        fail(`Run "${target}" holds no readable lock. List the locks with: agent-lyceum doctor`);
+    console.log(`Lock held for run ${info.run_id} by pid ${info.pid} on ${info.hostname}, last heartbeat ${info.heartbeat_at}${lockHolderAlive(info) ? " (that process is still alive)" : " (that process is gone)"}.`);
     if (!force)
         fail("Not removed. Check that no run is active, then repeat with --force.");
-    forceUnlock(pr.paths.root);
-    console.log("Lock removed. Resume the run with: agent-lyceum resume");
+    forceUnlock(root, target);
+    console.log(`Lock removed. Resume the run with: agent-lyceum resume ${target}`);
 }
 program
     .command("clear [run-id]")
@@ -353,20 +393,20 @@ program
     .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" +
+    "With --lock it does something else (the run id is optional):\n" +
+    "  - removes the run lock a crashed run left behind (name the run when several hold a lock)\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)")
+    .option("--lock", "remove the run lock left behind by a crashed run (give its run id when several runs hold a lock; needs --force)")
     .option("--force", "with --lock: remove the lock even though its owner cannot be confirmed dead")
     .option("--keep-worktrees", "keep the agents' worktrees and branches (and their snapshots), and still clear the run and its task memory")
     .action((runId, opts) => {
     try {
         if (opts.lock) {
             if (runId)
-                fail("--lock takes no run id.");
-            return unlockProject(loadProject(opts.project), !!opts.force);
+                assertName("run", runId);
+            return unlockProject(loadProject(opts.project), runId, !!opts.force);
         }
         if (opts.force)
             fail("--force only goes with --lock.");
@@ -394,7 +434,7 @@ program
                 refuse(plan);
             return;
         }
-        const lease = takeLock(pr, runId);
+        const lease = takeLock(pr, runId, { ignoreLimit: true });
         try {
             const plan = planRunCleanup(pr, runId, { keepWorktrees: opts.keepWorktrees });
             if (plan.refusals.length)
@@ -537,7 +577,7 @@ program
             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()}`);
+            const undoLease = takeLock(target, `restore-${tidyStamp()}`, { exclusive: true });
             try {
                 const r = restoreMemory({ project: target, agent: opts.agent, layer, stamp: opts.undo });
                 for (const f of r.restored)
@@ -565,7 +605,7 @@ program
         if (!res.ok)
             fail("Configuration is invalid; fix the errors above (see `agent-lyceum doctor`).");
         await preflight(pr);
-        const lease = takeLock(pr, `tidy-${tidyStamp()}`);
+        const lease = takeLock(pr, `tidy-${tidyStamp()}`, { exclusive: true });
         const cancel = cancelOnSignals();
         let results;
         try {

package/dist/config.d.ts

@@ -72,6 +72,7 @@ export declare function loadProjectRaw(home: string, name: string): {
     dispatcher: {
         max_rounds?: number | undefined;
         max_parallel?: number | undefined;
+        max_concurrent_runs?: number | undefined;
         wake_timeout_sec?: number | undefined;
         retry?: number | undefined;
         strict?: boolean | undefined;

package/dist/doctor.js

@@ -1,11 +1,12 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { findOnPath } from "./fs-util.js";
 import { tidyAdvice } from "./memory-tidy.js";
-import { inspectProjectLock, lockHolderAlive } from "./project-lock.js";
+import { listRunLocks, listUnreadableRunLocks, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
-import { dirtyPaths, isGitRepo, resolveWorkspaceMode } from "./worktree.js";
+import { dirtyPaths, git, isGitRepo, resolveWorkspaceMode } from "./worktree.js";
 const BINARY = { "claude-code": "claude", codex: "codex" };
 /** Run a read-only CLI query (`--version`, `--help`): bounded in time and output, never an agent task. */
 async function query(cmd, args, opts) {
@@ -118,21 +119,46 @@ export async function diagnoseProject(project, opts = {}) {
     if (fs.existsSync(project.dir) && isGitRepo(project.dir)) {
         if (resolveWorkspaceMode(project.dispatcher) === "worktree") {
             const dirty = dirtyPaths(project.dir);
-            if (dirty.length)
+            if (dirty.length && project.dispatcher.max_concurrent_runs > 1) {
+                checks.push({ level: "info", subject: "git", message: `${dirty.length} uncommitted change(s) in ${project.dir}: concurrent runs start from HEAD and do not see them.` });
+            }
+            else if (dirty.length) {
                 checks.push({ level: "warn", subject: "git", message: `${dirty.length} uncommitted change(s) in ${project.dir}: a parallel run would refuse to start until they are committed or stashed.` });
+            }
             else
                 checks.push({ level: "ok", subject: "git", message: "Repo is clean; parallel runs can start." });
         }
     }
-    const lock = inspectProjectLock(project.paths.root);
-    if (lock) {
+    if (project.dispatcher.max_concurrent_runs > 1 && fs.existsSync(project.dir) && isGitRepo(project.dir)) {
+        const missing = [];
+        if (!findOnPath("gh", opts.env?.PATH ?? process.env.PATH))
+            missing.push("`gh` is not on PATH");
+        let remotes = "";
+        try {
+            remotes = git(project.dir, ["remote"]);
+        }
+        catch {
+            /* no remotes readable */
+        }
+        if (!remotes.split(/\s+/).includes("origin"))
+            missing.push("the repo has no `origin` remote");
+        checks.push(missing.length
+            ? { level: "info", subject: "pr", message: `A run cannot open a pull request (a lead asks for one with \`open_pr: true\`): ${missing.join("; ")}.` }
+            : { level: "ok", subject: "pr", message: "`gh` and `origin` found: a run can open a pull request when the lead asks for one." });
+    }
+    for (const lock of listRunLocks(project.paths.root)) {
         const alive = lockHolderAlive(lock);
         checks.push({
             level: "warn",
             subject: "lock",
-            message: alive ? `A run is active: ${lock.run_id} (pid ${lock.pid}).` : `A stale run lock is left by ${lock.run_id} (pid ${lock.pid} is gone); \`agent-lyceum clear --lock --force\` clears it.`,
+            message: alive
+                ? `A run is active: ${lock.run_id} (pid ${lock.pid}).`
+                : `A stale run lock is left by ${lock.run_id} (pid ${lock.pid} is gone); \`agent-lyceum clear --lock ${lock.run_id} --force\` clears it.`,
         });
     }
+    for (const id of listUnreadableRunLocks(project.paths.root)) {
+        checks.push({ level: "warn", subject: "lock", message: `The lock file of run ${id} cannot be read; if no run is active, \`agent-lyceum clear --lock ${id} --force\` clears it.` });
+    }
     for (const a of tidyAdvice(project))
         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);

package/dist/guard.d.ts

@@ -18,6 +18,11 @@ export declare class ProtectedGuard {
     private project;
     private baseline;
     constructor(project: ResolvedProject);
+    /**
+     * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
+     * judged: edits made in between (you, or another run of the project) are not the batch's doing.
+     */
+    rebase(): void;
     static protectedFiles(project: ResolvedProject): string[];
     /** Copy the current protected files into `dir` for the audit trail. */
     saveSnapshot(dir: string): void;

package/dist/guard.js

@@ -15,7 +15,14 @@ export class ProtectedGuard {
     baseline = new Map();
     constructor(project) {
         this.project = project;
-        for (const f of ProtectedGuard.protectedFiles(project))
+        this.rebase();
+    }
+    /**
+     * Take the current files as the baseline. Called right before a batch is woken, so only what changes while it runs is
+     * judged: edits made in between (you, or another run of the project) are not the batch's doing.
+     */
+    rebase() {
+        for (const f of ProtectedGuard.protectedFiles(this.project))
             this.baseline.set(f, read(f));
     }
     static protectedFiles(project) {

package/dist/open-pr.d.ts

@@ -0,0 +1,47 @@
+/** Runs `git` or `gh` in `cwd`. Injected so tests never touch a network or a real remote. */
+export type CommandRunner = (cmd: "git" | "gh", args: string[], cwd: string) => {
+    ok: boolean;
+    out: string;
+};
+/**
+ * The real thing: runs outside any agent sandbox, with the user's own git and gh credentials.
+ * Prompts are off, so a missing credential fails at once instead of hanging until the timeout.
+ */
+export declare const realRunner: CommandRunner;
+/** The one line that says who opened the pull request. It names no agent and no role. */
+export declare const PR_FOOTER = "\uD83E\uDD16 Opened by agent-lyceum";
+/** First non-empty line of the task summary, cut to 72 characters. */
+export declare function prTitle(taskSummary: string): string;
+/** The lead's `done` report as written, then one footer line. */
+export declare function prBody(doneBody: string): string;
+/** The repo's default branch: `origin/HEAD`, else what `gh` says, else `main`. */
+export declare function defaultBase(cwd: string, run: CommandRunner): string;
+export type OpenPrResult = {
+    status: "opened";
+    url: string;
+} | {
+    status: "failed";
+    step: "push" | "create" | "write";
+    reason: string;
+    manual: string[];
+};
+/** What happened to a requested pull request; `skipped` means it was asked for but the run could not support it. */
+export type PrOutcome = OpenPrResult | {
+    status: "skipped";
+    reason: string;
+};
+export interface OpenPrInput {
+    /**
+     * The main repo: never a directory an agent can write. An agent can rewrite its worktree's git pointers and so plant hooks or
+     * config that git would run here, outside the sandbox. The branch is in the shared refs, so pushing it from the main repo works.
+     */
+    cwd: string;
+    branch: string;
+    title: string;
+    body: string;
+    /** Where the description is written for `gh --body-file` (and for finishing by hand). */
+    bodyFile: string;
+    run: CommandRunner;
+}
+/** Push the branch and open a pull request against the default branch. Never throws; says how to finish by hand when a step fails. */
+export declare function openPullRequest(i: OpenPrInput): OpenPrResult;

package/dist/open-pr.js

@@ -0,0 +1,71 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { atomicWrite } from "./fs-util.js";
+/**
+ * The real thing: runs outside any agent sandbox, with the user's own git and gh credentials.
+ * Prompts are off, so a missing credential fails at once instead of hanging until the timeout.
+ */
+export const realRunner = (cmd, args, cwd) => {
+    try {
+        const out = execFileSync(cmd, args, {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 120_000,
+            env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GH_PROMPT_DISABLED: "1" },
+        });
+        return { ok: true, out: out.trim() };
+    }
+    catch (e) {
+        const err = e;
+        return { ok: false, out: String(err.stderr ?? err.message).trim() };
+    }
+};
+/** The one line that says who opened the pull request. It names no agent and no role. */
+export const PR_FOOTER = "🤖 Opened by agent-lyceum";
+const TITLE_MAX = 72;
+const BODY_MAX = 60_000; // GitHub rejects bodies over 65536 characters
+/** First non-empty line of the task summary, cut to 72 characters. */
+export function prTitle(taskSummary) {
+    const first = taskSummary.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "agent-lyceum task";
+    return first.length > TITLE_MAX ? `${first.slice(0, TITLE_MAX - 1)}…` : first;
+}
+/** The lead's `done` report as written, then one footer line. */
+export function prBody(doneBody) {
+    return `${doneBody.trim().slice(0, BODY_MAX)}\n\n${PR_FOOTER}\n`;
+}
+/** The repo's default branch: `origin/HEAD`, else what `gh` says, else `main`. */
+export function defaultBase(cwd, run) {
+    const sym = run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], cwd);
+    const m = sym.ok ? /^origin\/(.+)$/.exec(sym.out) : null;
+    if (m?.[1])
+        return m[1];
+    const gh = run("gh", ["repo", "view", "--json", "defaultBranchRef", "--jq", ".defaultBranchRef.name"], cwd);
+    return gh.ok && gh.out ? gh.out : "main";
+}
+const firstLine = (s) => s.split(/\r?\n/).find((l) => l.trim())?.trim() ?? "no output";
+/** POSIX single-quote: safe to paste into a shell whatever the string holds. */
+const sh = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** Push the branch and open a pull request against the default branch. Never throws; says how to finish by hand when a step fails. */
+export function openPullRequest(i) {
+    const base = defaultBase(i.cwd, i.run);
+    try {
+        atomicWrite(i.bodyFile, i.body);
+    }
+    catch (e) {
+        return { status: "failed", step: "write", reason: firstLine(e.message ?? String(e)), manual: [] };
+    }
+    const createArgs = ["pr", "create", "--head", i.branch, "--base", base, "--title", i.title, "--body-file", i.bodyFile];
+    const manualPush = `git -C ${sh(i.cwd)} push -u origin ${sh(i.branch)}`;
+    const manualCreate = `gh pr create --head ${sh(i.branch)} --base ${sh(base)} --title ${sh(i.title)} --body-file ${sh(path.resolve(i.bodyFile))}`;
+    const push = i.run("git", ["push", "-u", "origin", i.branch], i.cwd);
+    if (!push.ok)
+        return { status: "failed", step: "push", reason: firstLine(push.out), manual: [manualPush, manualCreate] };
+    const created = i.run("gh", createArgs, i.cwd);
+    if (!created.ok)
+        return { status: "failed", step: "create", reason: firstLine(created.out), manual: [manualCreate] };
+    const url = created.out.split(/\s+/).find((w) => /^https?:\/\//.test(w));
+    if (!url)
+        return { status: "failed", step: "create", reason: `gh printed no URL: ${firstLine(created.out)}`, manual: [manualCreate] };
+    return { status: "opened", url };
+}

package/dist/policy.d.ts

@@ -26,6 +26,7 @@ export interface WritePolicy {
 export declare function commonFile(project: ResolvedProject): string;
 export declare function outboxDir(project: ResolvedProject, agent: string): string;
 export declare function inboxDir(project: ResolvedProject, agent: string): string;
+/** The repo's own CLAUDE.md/AGENTS.md: in the lead's worktree when it has one (concurrent runs), else in the repo. */
 export declare function repoInstructionFiles(project: ResolvedProject): string[];
 export declare function memoryDirs(a: ResolvedAgent): string[];
 /** The repo directory this agent works in: its own worktree, or the main repo. */

package/dist/policy.js

@@ -11,8 +11,10 @@ export function outboxDir(project, agent) {
 export function inboxDir(project, agent) {
     return path.join(project.paths.inboxRoot, agent);
 }
+/** The repo's own CLAUDE.md/AGENTS.md: in the lead's worktree when it has one (concurrent runs), else in the repo. */
 export function repoInstructionFiles(project) {
-    return [path.join(project.dir, "CLAUDE.md"), path.join(project.dir, "AGENTS.md")];
+    const dir = repoDirFor(project, project.lead);
+    return [path.join(dir, "CLAUDE.md"), path.join(dir, "AGENTS.md")];
 }
 export function memoryDirs(a) {
     return [a.memory.global, a.memory.project, a.memory.task].filter((x) => !!x);
@@ -130,7 +132,7 @@ export function enforcementFor(project, agent) {
         agent: agent.name,
         runtime: agent.runtime ?? "?",
         ...e,
-        writablePaths: [...pol.allowDirs, ...pol.allowFiles.filter((f) => !f.startsWith(project.dir + path.sep))],
+        writablePaths: [...pol.allowDirs, ...pol.allowFiles.filter((f) => !f.startsWith(project.dir + path.sep) && !f.startsWith(repoDirFor(project, project.lead) + path.sep))],
         notes,
     };
 }