agent-lyceum 0.17.2 → 0.18.0

package/README.md

@@ -4,13 +4,25 @@
 
 **English** | [繁體中文](README.zh-TW.md)
 
-Run a **team of agents** (Claude Code and/or Codex) on your repo. They talk through file mailboxes, and each has its own persona (`AGENT.md`) and long-term memory. An agent can only write its own memory and outbox, never other agents' context or its own persona.
+Give a task to a **team of agents** (Claude Code and/or Codex) instead of one overloaded session. A lead splits the work, specialists such as a frontend dev, a reviewer or a PM do their part in your repo, and the run ends when the lead says it is done.
+
+## Why
+
+- **Roles that stay in role.** Each agent has its own persona (`AGENT.md`) and long-term memory, so a reviewer keeps reviewing instead of drifting into writing code.
+- **Agents can't rewrite the rules.** An agent can only write its own memory and outbox. It can't touch other agents' context or its own persona, and this is enforced by the OS sandbox where possible, not just by a prompt. See [Write scope](docs/write-scope.md).
+- **Mix runtimes.** Claude Code and Codex agents work in the same team.
+- **Nothing hidden.** Agents talk through plain-file mailboxes, so every message, decision and memory is a file you can read, grep and diff. The dispatcher never merges for you.
+
+**Not a fit** for small, one-shot edits: a single Claude Code or Codex session is faster and cheaper. Use a team when the task is big enough to split, review or run in parallel.
 
 ## Quick start
 
 Requires Node 20+, plus `claude` and/or `codex` on your `PATH` (logged in). macOS and Linux (Linux needs `bwrap` for OS sandboxing); Windows only gets warnings.
 
 ```bash
+npx agent-lyceum demo                       # 3 agents fix a failing test in a throwaway sandbox (real calls)
+
+# on your own repo:
 npx agent-lyceum init                       # create the home + global agent library
 npx agent-lyceum project add web --dir ~/code/web-app
 npx agent-lyceum doctor --project web       # check config, show enforcement levels
@@ -27,7 +39,7 @@ Latest unreleased code: `npx github:gogogohuang/agent-lyceum <command>`.
 3. Agents reply by writing mail to their own `outbox/`; the dispatcher checks `can_message` and delivers it.
 4. The run ends when the lead sends `done`.
 
-Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyceum-config/`, not in your repo. Agents edit your repo directly, or in git worktrees when running in parallel. agent-lyceum never merges. More: [How a run works](docs/how-it-works.md), [Configuration](docs/configuration.md).
+Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyceum-config/`, not in your repo. Concurrency needs no configuration. In a git repo with a commit, every run works in its own git worktree and ends on its own branch (`agent-lyceum/<run>/…`), members with pending mail wake in parallel, and any number of runs can be active at once; the result is not written into your working tree, so use `git merge <branch>` or `open_pr`, and note that a run starts from `HEAD` and does not see your uncommitted edits. In a non-git folder, a repo with no commit, or a repo using reftable, the run works directly in the folder, one agent at a time (an info line says why), and only one such run can be active. agent-lyceum never merges. Upgrading from a version with `owns`, `max_parallel`, `max_concurrent_runs` or `workspace_mode`: see [Upgrading](docs/upgrading-run-v2.md). More: [How a run works](docs/how-it-works.md), [Configuration](docs/configuration.md).
 
 ## Commands
 
@@ -41,6 +53,7 @@ Its own data (config, mailboxes, logs, memory, worktrees) lives in `~/agent-lyce
 | `resume` | Continue an interrupted run, or reopen a finished one with a follow-up. [details](docs/commands.md#resume) |
 | `clear` | Delete a run, or remove a stale lock. [details](docs/commands.md#clear) |
 | `call <agent>` | Ask one global agent on its own, outside any project. [details](docs/commands.md#call) |
+| `demo` | Try a 3-agent team on a throwaway sample repo. [details](docs/commands.md#demo) |
 | `tidy` | Have agents tidy their own memory (archives, never deletes). [details](docs/commands.md#tidy) |
 
 `agent-lyceum <command> --help` prints the full options. Ctrl-C cancels cleanly; [exit codes](docs/commands.md#exit-codes) tell scripts how a run ended.
@@ -55,7 +68,7 @@ dir: ~/code/web-app
 team: { lead: lead }
 agents:
   lead:      { can_message: all, can_edit_agent_md: true }
-  fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
+  fe-member: { runtime: codex, can_message: [lead] }
   pm:        { can_message: [lead], allow_web: fetch }
 ```
 

package/README.zh-TW.md

@@ -4,13 +4,25 @@
 
 [English](README.md) | **繁體中文**
 
-在你的 repo 上執行一個由多個 **agent**（Claude Code 和／或 Codex）組成的團隊。agent 之間透過檔案信箱溝通，各自有人設（`AGENT.md`）與長期記憶。agent 只能寫自己的記憶與寄件匣（outbox），不能改其他 agent 的 context，也不能改自己的人設。
+把任務交給一個 **agent 團隊**（Claude Code 和／或 Codex），而不是塞給單一個負荷過重的 session。lead 拆分工作，前端、reviewer、PM 等專長角色在你的 repo 裡各做各的，lead 回報 done 即結束。
+
+## 為什麼用它
+
+- **角色不會跑掉。** 每個 agent 有自己的人設（`AGENT.md`）與長期記憶，reviewer 會一直做 review，不會漸漸變成在寫程式。
+- **agent 改不了規則。** agent 只能寫自己的記憶與寄件匣（outbox），不能改其他 agent 的 context，也不能改自己的人設；能做到的地方由 OS 沙箱強制，而不只靠 prompt。見 [Write scope](docs/write-scope.zh-TW.md)。
+- **混用 runtime。** Claude Code 與 Codex agent 可在同一個團隊。
+- **沒有黑箱。** agent 透過純檔案信箱溝通，每則訊息、決策與記憶都是你能讀、能 grep、能 diff 的檔案；dispatcher 不會替你 merge。
+
+**不適合**小而單次的修改：單一 Claude Code 或 Codex session 更快更省。任務大到值得拆分、review 或平行執行時，再用團隊。
 
 ## 快速開始
 
 需求：Node 20+，以及 `PATH` 中有 `claude` 和／或 `codex`（已登入）。支援 macOS 與 Linux（Linux 需要 `bwrap` 才有 OS 沙箱）；Windows 只會顯示警告。
 
 ```bash
+npx agent-lyceum demo                       # 3 個 agent 在拋棄式沙箱裡修好一個失敗的測試（真實呼叫）
+
+# 用在你自己的 repo：
 npx agent-lyceum init                       # 建立 home 與全域 agent 庫
 npx agent-lyceum project add web --dir ~/code/web-app
 npx agent-lyceum doctor --project web       # 檢查設定並顯示各項防護等級
@@ -27,7 +39,7 @@ npx agent-lyceum status
 3. agent 把回信寫進自己的 `outbox/`，dispatcher 檢查 `can_message` 後投遞。
 4. lead 寄出 `done` 時，run 結束。
 
-工具自己的資料（設定、信箱、log、記憶、worktree）放在 `~/agent-lyceum-config/`，不放進你的 repo。agent 直接修改你的 repo；平行執行時則在各自的 git worktree 修改。agent-lyceum 不會幫你合併。詳見[一次執行如何運作](docs/how-it-works.zh-TW.md)、[設定](docs/configuration.zh-TW.md)。
+工具自己的資料（設定、信箱、log、記憶、worktree）放在 `~/agent-lyceum-config/`，不放進你的 repo。並行不需要任何設定。在有 commit 的 git repo 裡，每個 run 都在自己的 git worktree 工作，並結束在自己的 branch（`agent-lyceum/<run>/…`）；有待處理信件的成員會平行喚醒，同時也可有任意多個 run；結果不會寫進你的工作目錄，請用 `git merge <branch>` 或 `open_pr`，且 run 從 `HEAD` 起跑，看不到你未提交的修改。在非 git 資料夾、沒有 commit 的 repo 或使用 reftable 的 repo，run 直接在該資料夾工作、一次只跑一個 agent（會有一行說明原因），且同時只能有一個這樣的 run。agent-lyceum 不會幫你合併。從有 `owns`、`max_parallel`、`max_concurrent_runs` 或 `workspace_mode` 的版本升級：見[升級](docs/upgrading-run-v2.md)。詳見[一次執行如何運作](docs/how-it-works.zh-TW.md)、[設定](docs/configuration.zh-TW.md)。
 
 ## 指令
 
@@ -41,6 +53,7 @@ npx agent-lyceum status
 | `resume` | 繼續中斷的 run，或用追加需求重開已完成的 run。 [詳細](docs/commands.zh-TW.md#resume) |
 | `clear` | 刪除 run，或移除殘留的鎖。 [詳細](docs/commands.zh-TW.md#clear) |
 | `call <agent>` | 在任何專案之外單獨呼叫一個全域 agent。 [詳細](docs/commands.zh-TW.md#call) |
+| `demo` | 在拋棄式範例 repo 上試跑 3 個 agent 的團隊。 [詳細](docs/commands.zh-TW.md#demo) |
 | `tidy` | 讓 agent 整理自己的記憶（只封存，不刪除）。 [詳細](docs/commands.zh-TW.md#tidy) |
 
 `agent-lyceum <指令> --help` 會印出完整選項。Ctrl-C 可乾淨取消；腳本可依[結束碼](docs/commands.zh-TW.md#退出碼)判斷 run 的結果。
@@ -55,7 +68,7 @@ dir: ~/code/web-app
 team: { lead: lead }
 agents:
   lead:      { can_message: all, can_edit_agent_md: true }
-  fe-member: { runtime: codex, can_message: [lead], owns: ["src/web/**"] }
+  fe-member: { runtime: codex, can_message: [lead] }
   pm:        { can_message: [lead], allow_web: fetch }
 ```
 

package/dist/adapters/claude.js

@@ -27,13 +27,7 @@ export function buildClaudeSettings(project, agent) {
         allow.push("WebSearch");
     if (agent.allowWeb === "fetch")
         allow.push("WebFetch");
-    if (pol.restrictRepoToOwns) {
-        for (const g of pol.owns)
-            allow.push(rule("Edit", path.join(repo, g)));
-    }
-    else {
-        allow.push(rule("Edit", `${repo}/**`));
-    }
+    allow.push(rule("Edit", `${repo}/**`));
     for (const d of pol.allowDirs)
         allow.push(rule("Edit", `${d}/**`));
     for (const f of pol.allowFiles)

package/dist/call.js

@@ -33,7 +33,6 @@ export function resolveCallAgent(home, name) {
         canMessage: [],
         canAskUser: false,
         canEditAgentMd: false,
-        owns: [],
     };
 }
 /** The made-up project a call runs in: the working directory is its repo, and every other path is inside the call's own folder. */
@@ -54,7 +53,7 @@ export function callProject(home, agent, dir, callDir) {
         name: CALL_PROJECT,
         dir,
         lead: agent.name,
-        dispatcher: { ...DISPATCHER_DEFAULTS, max_parallel: 1, workspace_mode: "shared" },
+        dispatcher: DISPATCHER_DEFAULTS,
         agents: { [agent.name]: agent },
         paths,
         solo: "call",

package/dist/cli.js

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline/promises";
+import { spawnSync } from "node:child_process";
 import { Command } from "commander";
 import { ConfigError, findProjectForCwd, flattenResolved, listProjects, loadGlobal, resolveProject, resolveProjectWithSources } from "./config.js";
 import { openInEditor, prepareAnswers } from "./ask-answer.js";
@@ -10,9 +11,10 @@ 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 { planWorkspace } from "./worktree.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 { exitCodeForOutcome, RUNTIMES } from "./schema.js";
 import { absPath, assertName, NAME_RE, projectPaths, resolveHome } from "./paths.js";
 import { addProject, initHome, removeProject } from "./scaffold.js";
 import { buildStatusReport, buildTaskListReport, formatMonitor, formatRunDetail, formatStatusWithLog, formatTaskList, latestUnfinishedRun, listRuns, reopenCandidates, runIsAlive } from "./status.js";
@@ -21,6 +23,7 @@ import { callAgent, callProject, callsDir, resolveCallAgent } from "./call.js";
 import { formatEnforcement, validateProject } from "./validate.js";
 import { must } from "./assert.js";
 import { onlyAgent, soloProject } from "./solo.js";
+import { DEMO_PROJECT, DEMO_TASK, defaultDemoDir, detectRuntime, prepareDemo } from "./demo.js";
 const program = new Command();
 program
     .name("agent-lyceum")
@@ -130,10 +133,10 @@ function findRun(pr, query) {
     const list = r.candidates.map((c) => `  ${c.state.name ?? "(no name)"}  ${c.state.run_id}  ${c.state.task_summary}`).join("\n");
     return fail(`"${query}" matches several runs:\n${list}\nGive more of the name or id.`);
 }
-/** 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). */
+/** Take the lock of one run, or exit with the reason. `checkout`: the run works in the project checkout, so only one may be active. `exclusive`: it needs the whole project (memory tidy). */
 function takeLock(pr, runId, opts = {}) {
     try {
-        return acquireProjectLock(pr.paths.root, runId, { maxConcurrent: opts.ignoreLimit ? Number.MAX_SAFE_INTEGER : pr.dispatcher.max_concurrent_runs, exclusive: opts.exclusive });
+        return acquireProjectLock(pr.paths.root, runId, { checkout: opts.checkout, exclusive: opts.exclusive, dir: pr.dir, reason: opts.reason });
     }
     catch (e) {
         return fail(e.message);
@@ -195,17 +198,23 @@ function reportRun(summary, runDir) {
 const firstLine = (t) => t.trim().split("\n")[0].trim();
 /** Take the lock and continue a run; the lock is released when it stops (also when it stops because it waits for answers). */
 async function continueRun(pr, dir, runId, followup) {
-    const lease = takeLock(pr, runId);
+    const planned = loadRunState(dir);
+    // Where the run works is decided (from its state) before the lock is taken, and handed to the session as is.
+    const plan = planWorkspace(pr, planned);
+    const lease = takeLock(pr, runId, { checkout: !plan.leadWorktree, reason: "it was started without its own worktree" });
     const cancel = cancelOnSignals();
     try {
-        console.log(`Project ${pr.name} — repo ${pr.dir}`);
+        // Read the state again under the lock: another process may have changed it while we were checking.
         const state = loadRunState(dir);
+        if (state.lead_workspace !== planned.lead_workspace || state.workspace_mode !== planned.workspace_mode) {
+            throw new Error(`Run ${runId} changed while it was starting (where it works was ${planned.lead_workspace ? "its own worktree" : planned.workspace_mode ?? "unset"}, now ${state.lead_workspace ? "its own worktree" : state.workspace_mode ?? "unset"}); try again.`);
+        }
+        console.log(`Project ${pr.name} — repo ${pr.dir}`);
         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 ${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 });
+        return await runTeam({ project: pr, resume: state, plan, runDir: dir, signal: cancel.signal, followup });
     }
     finally {
         cancel.dispose();
@@ -287,7 +296,8 @@ program
         }
         const runId = newRunId();
         const runDir = path.join(pr.paths.runs, runId);
-        const lease = takeLock(pr, runId);
+        const plan = planWorkspace(pr);
+        const lease = takeLock(pr, runId, { checkout: !plan.leadWorktree, reason: plan.reason });
         let summary;
         const cancel = cancelOnSignals();
         try {
@@ -295,7 +305,7 @@ program
             console.log(`Project ${pr.name} — repo ${pr.dir}${opts.agent ? ` — solo: ${opts.agent}` : ""}`);
             console.log(`Task: ${prepared.source === "file" ? `file ${prepared.sourcePath}` : "text"} (${prepared.bytes} bytes${prepared.inline ? "" : ", passed by reference"})`);
             const name = opts.name ?? uniqueName(slugify(taskMessageBody(prepared).subject), taken);
-            summary = await runTeam({ project: pr, name, task: prepared, runDir, soloAgent: opts.agent, signal: cancel.signal });
+            summary = await runTeam({ project: pr, name, plan, task: prepared, runDir, soloAgent: opts.agent, signal: cancel.signal });
         }
         finally {
             cancel.dispose();
@@ -512,7 +522,7 @@ program
                 refuse(plan);
             return;
         }
-        const lease = takeLock(pr, full, { ignoreLimit: true });
+        const lease = takeLock(pr, full, { checkout: false });
         try {
             const plan = planRunCleanup(pr, full, { keepWorktrees: opts.keepWorktrees });
             if (plan.refusals.length)
@@ -772,11 +782,63 @@ program
         fail(e instanceof ConfigError ? e.message : e.message);
     }
 });
+program
+    .command("demo")
+    .summary("Try a 3-agent team on a tiny sample repo (real agents, a few minutes)")
+    .description("Build a throwaway sandbox (a tiny git repo with one failing test, plus its own agent-lyceum home), then run a lead, a frontend member and a QA member on it until `npm test` passes.\n\nIt uses real `claude` / `codex` calls, so it spends a little of your quota. Nothing outside the sandbox directory is touched; your own home and repos are not used.")
+    .option("--dir <path>", "the sandbox directory, must be empty or new (default: a new folder in the system temp dir)")
+    .option("--runtime <runtime>", `${RUNTIMES.join(" | ")} (default: whichever CLI is on your PATH)`)
+    .option("--setup-only", "build the sandbox and print the commands, but run no agents")
+    .option("-y, --yes", "do not ask before running real agents")
+    .action(async (opts) => {
+    try {
+        let runtime = opts.runtime;
+        if (runtime && !RUNTIMES.includes(runtime))
+            fail(`Unknown runtime "${runtime}". Use one of: ${RUNTIMES.join(", ")}.`);
+        runtime ??= detectRuntime();
+        if (!runtime) {
+            if (!opts.setupOnly)
+                fail("Neither `claude` nor `codex` was found on your PATH (and logged in). Install one, or use --setup-only to just look at the sandbox.");
+            runtime = "claude-code";
+        }
+        if (!opts.setupOnly && !opts.yes && interactive()) {
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            const ans = (await rl.question(`This runs a 3-agent team with real ${runtime} calls on a sample repo (a few minutes, a small amount of quota). Continue? [Y/n] `)).trim().toLowerCase();
+            rl.close();
+            if (ans === "n" || ans === "no")
+                fail("Aborted.");
+        }
+        const demo = prepareDemo(opts.dir ?? defaultDemoDir(), runtime);
+        const h = demo.home;
+        console.log(`Sandbox: ${demo.dir}  (runtime: ${runtime})\nRepo with one failing test: ${demo.repo}\n`);
+        const next = [
+            `agent-lyceum --home ${h} status -p ${DEMO_PROJECT}              # agents, mail, runs`,
+            `git -C ${demo.repo} log --oneline --stat                        # what the team changed`,
+            `rm -rf ${demo.dir}                                              # clean up when done`,
+        ];
+        if (opts.setupOnly) {
+            fs.writeFileSync(path.join(demo.dir, "task.md"), `${DEMO_TASK}\n`);
+            console.log(`Run the team yourself:\n  agent-lyceum --home ${h} run -p ${DEMO_PROJECT} --task-file ${path.join(demo.dir, "task.md")}\n\nThen:\n${next.map((l) => `  ${l}`).join("\n")}`);
+            return;
+        }
+        console.log(`Task for the lead:\n${DEMO_TASK.split("\n").map((l) => `  | ${l}`).join("\n")}\n`);
+        // The real `run`, in a child: the demo shows exactly what a normal run does (progress, Ctrl-C, exit codes).
+        const r = spawnSync(process.execPath, [...process.execArgv, process.argv[1], "--home", h, "run", DEMO_TASK, "-p", DEMO_PROJECT, "--name", "demo-slugify"], { stdio: "inherit", cwd: demo.repo });
+        const code = r.status ?? 1;
+        console.log(code === 0 ? "\nDone. See what happened:" : `\nThe run ended with exit code ${code} (see docs/commands.md#exit-codes). Look around:`);
+        console.log(next.map((l) => `  ${l}`).join("\n"));
+        process.exit(code);
+    }
+    catch (e) {
+        fail(e.message);
+    }
+});
 // `--help` lists the commands in three layers.
 const HELP_LAYERS = {
     "Project:": ["init", "project"],
     "Diagnose:": ["doctor", "status"],
     "Run:": ["run", "resume", "clear", "call", "tidy"],
+    "Try it:": ["demo"],
 };
 for (const [heading, names] of Object.entries(HELP_LAYERS))
     for (const c of program.commands)

package/dist/config.d.ts

@@ -22,7 +22,6 @@ export interface ResolvedAgent {
     canAskUser: boolean;
     /** Web access for this agent; undefined = not configured, so the runtime keeps its own default. */
     allowWeb?: WebLevel;
-    owns: string[];
     /** Where each field's value came from (for `validate` output). */
     sources: Record<string, Source>;
 }
@@ -35,6 +34,11 @@ export interface ResolvedProject {
     dispatcher: DispatcherSettings;
     agents: Record<string, ResolvedAgent>;
     paths: ProjectPaths;
+    /** Removed settings still present in config files (ignored); `validate` warns once per file. */
+    ignoredSettings?: {
+        file: string;
+        keys: string[];
+    }[];
     /** Set once the project is bound to one run (see `bindRunProject`): which run, and where its mail lives. */
     run?: {
         id: string;
@@ -61,7 +65,7 @@ export declare function loadGlobal(home: string): {
         can_edit_agent_md?: boolean | undefined;
         can_ask_user?: boolean | undefined;
         allow_web?: "fetch" | "none" | "search" | undefined;
-        owns?: string[] | undefined;
+        owns?: unknown;
     }>;
 };
 export declare function loadProjectRaw(home: string, name: string): {
@@ -71,12 +75,12 @@ export declare function loadProjectRaw(home: string, name: string): {
     };
     dispatcher: {
         max_rounds?: number | undefined;
-        max_parallel?: number | undefined;
-        max_concurrent_runs?: number | undefined;
+        max_parallel?: unknown;
+        max_concurrent_runs?: unknown;
         wake_timeout_sec?: number | undefined;
         retry?: number | undefined;
         strict?: boolean | undefined;
-        workspace_mode?: "auto" | "shared" | "worktree" | undefined;
+        workspace_mode?: unknown;
         log_max_bytes?: number | undefined;
     };
     agents: Record<string, {
@@ -93,7 +97,7 @@ export declare function loadProjectRaw(home: string, name: string): {
         can_edit_agent_md?: boolean | undefined;
         can_ask_user?: boolean | undefined;
         allow_web?: "fetch" | "none" | "search" | undefined;
-        owns?: string[] | undefined;
+        owns?: unknown;
     }>;
 };
 export declare function resolveProject(home: string, name: string): ResolvedProject;

package/dist/config.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import YAML from "yaml";
 import { absPath, homePaths, projectPaths, } from "./paths.js";
-import { DISPATCHER_DEFAULTS, GlobalConfig, ProjectConfig, inferRuntime, } from "./schema.js";
+import { DISPATCHER_DEFAULTS, GlobalConfig, REMOVED_AGENT_KEYS, REMOVED_DISPATCHER_KEYS, ProjectConfig, inferRuntime, } from "./schema.js";
 export class ConfigError extends Error {
 }
 function readYaml(file, schema, label) {
@@ -58,7 +58,8 @@ export function resolveProjectFrom(home, name, g, p) {
     const paths = projectPaths(home, name);
     const hp = homePaths(home);
     const lead = p.team.lead;
-    const dispatcher = { ...DISPATCHER_DEFAULTS, ...stripUndef(p.dispatcher) };
+    const { max_parallel: _mp, max_concurrent_runs: _mc, workspace_mode: _wm, ...liveDispatcher } = p.dispatcher;
+    const dispatcher = { ...DISPATCHER_DEFAULTS, ...stripUndef(liveDispatcher) };
     const agents = {};
     for (const agentName of Object.keys(p.agents)) {
         const gl = resolveLayer(g.agents[agentName], home);
@@ -134,13 +135,11 @@ export function resolveProjectFrom(home, name, g, p) {
         const canEdit = pick("can_edit_agent_md");
         const canAsk = pick("can_ask_user");
         const allowWeb = pick("allow_web");
-        const owns = pick("owns");
         for (const [k, v] of [
             ["resume", resume],
             ["can_message", canMessage],
             ["can_edit_agent_md", canEdit],
             ["can_ask_user", canAsk],
-            ["owns", owns],
         ]) {
             if (v === undefined)
                 sources[k] = "default";
@@ -157,7 +156,6 @@ export function resolveProjectFrom(home, name, g, p) {
             canEditAgentMd: canEdit ?? isLead,
             canAskUser: canAsk ?? isLead,
             allowWeb,
-            owns: owns ?? [],
             sources,
         };
     }
@@ -169,8 +167,28 @@ export function resolveProjectFrom(home, name, g, p) {
         dispatcher,
         agents,
         paths,
+        ignoredSettings: collectIgnored(hp.globalConfig, g, paths.config, p),
     };
 }
+/** The removed keys present in the global and project files, by full path, per file (empty files omitted). */
+function collectIgnored(globalFile, g, projectFile, p) {
+    const out = [];
+    const scan = (file, dispatcher, agents) => {
+        const keys = [];
+        for (const k of REMOVED_DISPATCHER_KEYS)
+            if (dispatcher?.[k] !== undefined)
+                keys.push(`dispatcher.${k}`);
+        for (const [name, a] of Object.entries(agents))
+            for (const k of REMOVED_AGENT_KEYS)
+                if (a[k] !== undefined)
+                    keys.push(`agents.${name}.${k}`);
+        if (keys.length)
+            out.push({ file, keys });
+    };
+    scan(globalFile, undefined, g.agents);
+    scan(projectFile, p.dispatcher, p.agents);
+    return out;
+}
 function stripUndef(o) {
     return Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
 }
@@ -205,7 +223,7 @@ export function findProjectForCwd(home, cwd) {
     }
     return best?.name;
 }
-const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "can_ask_user", "allow_web", "owns"];
+const AGENT_FIELDS = ["runtime", "model", "effort", "agent_md", "memory.global", "memory.project", "resume", "can_message", "can_edit_agent_md", "can_ask_user", "allow_web"];
 /** The resolved project plus, for every setting, the file and key it was taken from (or "default"). */
 export function resolveProjectWithSources(home, name) {
     const project = resolveProject(home, name);
@@ -264,7 +282,6 @@ export function flattenResolved(project) {
         v[`${p}.can_edit_agent_md`] = a.canEditAgentMd;
         v[`${p}.can_ask_user`] = a.canAskUser;
         v[`${p}.allow_web`] = a.allowWeb;
-        v[`${p}.owns`] = a.owns;
     }
     return v;
 }

package/dist/demo.d.ts

@@ -0,0 +1,13 @@
+import type { Runtime } from "./schema.js";
+export declare const DEMO_PROJECT = "demo";
+export declare const DEMO_TASK = "The sample repo has a failing test: `npm test` fails because slugify() in src/slug.js is not implemented.\n\nImplement slugify(text) so that it lowercases the text, turns every run of non-alphanumeric characters into a single \"-\", and trims leading and trailing \"-\". Do not edit the tests.\n\nPlan: the lead hands the implementation to fe-member, then asks qa-member to run `npm test` and review the change. Finish with `done` only after qa-member's verdict is pass.";
+/** Which runtime CLI is on the PATH and answers `--version`; claude-code wins when both are. */
+export declare function detectRuntime(): Runtime | undefined;
+export interface DemoSetup {
+    dir: string;
+    home: string;
+    repo: string;
+}
+/** A throwaway sandbox: a tiny git repo with one failing test, plus its own agent-lyceum home with a registered project. Touches nothing outside `dir`. */
+export declare function prepareDemo(dir: string, runtime: Runtime): DemoSetup;
+export declare function defaultDemoDir(): string;

package/dist/demo.js

@@ -0,0 +1,90 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { projectPaths } from "./paths.js";
+import { addProject, initHome } from "./scaffold.js";
+export const DEMO_PROJECT = "demo";
+export const DEMO_TASK = `The sample repo has a failing test: \`npm test\` fails because slugify() in src/slug.js is not implemented.
+
+Implement slugify(text) so that it lowercases the text, turns every run of non-alphanumeric characters into a single "-", and trims leading and trailing "-". Do not edit the tests.
+
+Plan: the lead hands the implementation to fe-member, then asks qa-member to run \`npm test\` and review the change. Finish with \`done\` only after qa-member's verdict is pass.`;
+const FILES = {
+    "package.json": `{
+  "name": "lyceum-demo",
+  "private": true,
+  "type": "module",
+  "scripts": { "test": "node --test" }
+}
+`,
+    "src/slug.js": `// Turn a title into a URL slug: "Hello, World!" -> "hello-world".
+export function slugify(text) {
+  throw new Error("not implemented");
+}
+`,
+    "test/slug.test.js": `import assert from "node:assert/strict";
+import { test } from "node:test";
+import { slugify } from "../src/slug.js";
+
+test("lowercases and joins words with a dash", () => {
+  assert.equal(slugify("Hello World"), "hello-world");
+});
+
+test("collapses punctuation and repeated separators", () => {
+  assert.equal(slugify("Hello,   World!!"), "hello-world");
+});
+
+test("trims leading and trailing separators", () => {
+  assert.equal(slugify("  --Agent Lyceum--  "), "agent-lyceum");
+});
+
+test("keeps digits", () => {
+  assert.equal(slugify("Top 10 tips"), "top-10-tips");
+});
+`,
+};
+/** Which runtime CLI is on the PATH and answers `--version`; claude-code wins when both are. */
+export function detectRuntime() {
+    for (const [runtime, bin] of [["claude-code", "claude"], ["codex", "codex"]]) {
+        const r = spawnSync(bin, ["--version"], { stdio: "ignore" });
+        if (r.status === 0)
+            return runtime;
+    }
+    return undefined;
+}
+/** A throwaway sandbox: a tiny git repo with one failing test, plus its own agent-lyceum home with a registered project. Touches nothing outside `dir`. */
+export function prepareDemo(dir, runtime) {
+    const root = path.resolve(dir);
+    if (fs.existsSync(root) && fs.readdirSync(root).length)
+        throw new Error(`${root} is not empty. Choose another --dir (or remove it).`);
+    const home = path.join(root, "home");
+    const repo = path.join(root, "repo");
+    fs.mkdirSync(repo, { recursive: true });
+    for (const [file, text] of Object.entries(FILES)) {
+        fs.mkdirSync(path.dirname(path.join(repo, file)), { recursive: true });
+        fs.writeFileSync(path.join(repo, file), text);
+    }
+    const git = (...args) => execFileSync("git", ["-C", repo, "-c", "user.name=agent-lyceum demo", "-c", "user.email=demo@example.com", ...args], { stdio: "ignore" });
+    try {
+        git("init", "-q", "-b", "main");
+        git("add", "-A");
+        git("commit", "-q", "-m", "demo: slugify is not implemented yet");
+    }
+    catch {
+        throw new Error("The demo needs `git` on your PATH.");
+    }
+    initHome(home);
+    addProject(home, DEMO_PROJECT, repo);
+    const cfg = projectPaths(home, DEMO_PROJECT).config;
+    let yaml = fs.readFileSync(cfg, "utf8");
+    yaml = yaml.replace("max_rounds: 0 ", "max_rounds: 20");
+    // One runtime for the whole team, and the roles scoped to the sample repo.
+    for (const agent of ["lead", "fe-member", "qa-member"])
+        yaml = yaml.replace(`  ${agent}:\n`, `  ${agent}:\n    runtime: ${runtime}\n`);
+    fs.writeFileSync(cfg, yaml);
+    return { dir: root, home, repo };
+}
+export function defaultDemoDir() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), "agent-lyceum-demo-"));
+}

package/dist/dispatcher.d.ts

@@ -3,4 +3,5 @@ import { newRunId } from "./run-store.js";
 export { newRunId };
 export type { ActiveWake, EndReason, RunState, SentTopic, WakeRecord, WakeTopic } from "./run-store.js";
 export { MAX_DONE_REJECTIONS, RESULT_FILE, type RunOptions, type RunSummary } from "./run-session.js";
-export declare function runTeam(opts: RunOptions): Promise<RunSummary>;
+/** `plan` is what the CLI decided before taking the run's lock. The CLI always passes it; the fallback exists only for direct callers and tests. */
+export declare function runTeam(opts: Omit<RunOptions, "plan"> & Partial<Pick<RunOptions, "plan">>): Promise<RunSummary>;

package/dist/dispatcher.js

@@ -1,7 +1,9 @@
 import { RunSession } from "./run-session.js";
 import { newRunId } from "./run-store.js";
+import { planWorkspace } from "./worktree.js";
 export { newRunId };
 export { MAX_DONE_REJECTIONS, RESULT_FILE } from "./run-session.js";
+/** `plan` is what the CLI decided before taking the run's lock. The CLI always passes it; the fallback exists only for direct callers and tests. */
 export async function runTeam(opts) {
-    return new RunSession(opts).run();
+    return new RunSession({ ...opts, plan: opts.plan ?? planWorkspace(opts.project, opts.resume) }).run();
 }

package/dist/doctor.js

@@ -6,7 +6,7 @@ import { tidyAdvice } from "./memory-tidy.js";
 import { listRunLocks, listUnreadableRunLocks, lockHolderAlive } from "./project-lock.js";
 import { runInvocation } from "./process-runner.js";
 import { validateProject } from "./validate.js";
-import { dirtyPaths, git, isGitRepo, resolveWorkspaceMode } from "./worktree.js";
+import { dirtyPaths, git, isolationBlocker } 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) {
@@ -116,20 +116,19 @@ export async function diagnoseProject(project, opts = {}) {
         checks.push({ level: i.level === "error" ? "error" : "warn", subject: "config", message: i.message });
     if (!v.issues.length)
         checks.push({ level: "ok", subject: "config", message: "Configuration is valid." });
-    if (fs.existsSync(project.dir) && isGitRepo(project.dir)) {
-        if (resolveWorkspaceMode(project.dispatcher) === "worktree") {
+    const blocker = fs.existsSync(project.dir) ? isolationBlocker(project.dir) : undefined;
+    if (fs.existsSync(project.dir)) {
+        if (blocker) {
+            checks.push({ level: "info", subject: "git", message: `Runs work directly in ${project.dir}, one agent at a time (${blocker}).` });
+        }
+        else {
             const dirty = dirtyPaths(project.dir);
-            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." });
+            checks.push(dirty.length
+                ? { level: "info", subject: "git", message: `${dirty.length} uncommitted change(s) in ${project.dir}: runs start from HEAD and do not see them.` }
+                : { level: "ok", subject: "git", message: "git repo with a commit: runs and agents work in their own worktrees." });
         }
     }
-    if (project.dispatcher.max_concurrent_runs > 1 && fs.existsSync(project.dir) && isGitRepo(project.dir)) {
+    if (fs.existsSync(project.dir) && !blocker) {
         const missing = [];
         if (!findOnPath("gh", opts.env?.PATH ?? process.env.PATH))
             missing.push("`gh` is not on PATH");

package/dist/paths.d.ts

@@ -26,5 +26,3 @@ export interface ProjectPaths {
 export declare function projectPaths(home: string, project: string): ProjectPaths;
 /** True when `child` is `parent` or inside it. */
 export declare function isInside(parent: string, child: string): boolean;
-/** Directory part of a glob that precedes the first wildcard segment. */
-export declare function globStaticPrefix(glob: string): string;

package/dist/paths.js

@@ -49,14 +49,3 @@ export function isInside(parent, child) {
     const rel = path.relative(parent, child);
     return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
-/** Directory part of a glob that precedes the first wildcard segment. */
-export function globStaticPrefix(glob) {
-    const segs = glob.split("/");
-    const out = [];
-    for (const s of segs) {
-        if (/[*?[\]{}]/.test(s))
-            break;
-        out.push(s);
-    }
-    return out.join("/");
-}