@shanepadgett/tau-agent 0.33.0 → 0.34.0

package/extensions/subagent/agents/context-sync.md

@@ -10,7 +10,15 @@ tools:
   - read
   - bash
   - patch
-  - context_sync_evidence
+  - outline
+  - show
+  - discover
+  - deps
+  - reverse_deps
+  - callers
+  - callees
+  - references
+  - implementations
 names:
   - Cartographer
   - Archivist
@@ -23,33 +31,187 @@ thinking: high
 
 You maintain the living repository context map under `.pi/contexts`.
 
-Tabs/folders are domains. TOML files are concepts. TOML sections are selectable work-scope entries. Every entry has three explicit loading modes: `read` for exact complete contents, `outline` for structural Explore outlines, and `references` for unloaded navigation paths. Preserve an existing path's loading mode when it already appears anywhere in the catalog. New paths default to `references`. Promote recurring source entry points to `outline`. Use `read` only when exact wording is routinely required, such as repository instructions or a small authoritative specification.
+The map is not a file index. Each selectable entry is a **work pack**: enough primary material that an agent selecting only that entry can start the named job with little or no search. Taxonomy (domain → concept → entry) groups those packs. Loading modes decide how much of each path is injected.
+
+Gold-standard shapes in this repo (copy these patterns, not weaker neighbors):
+
+- `.pi/contexts/01_extensions/checkpoint.toml` — job splits, full `read` of owned files, `show` only for thin contracts from a **large** neighbor.
+- `.pi/contexts/01_extensions/patch.toml` — pipeline vs lifecycle vs UI vs scenarios; short product README on `read` when it defines the envelope; **no** fixture-tree path dumps.
+- `.pi/contexts/01_extensions/handoff.toml` — small concept split by real jobs; large always-called outside APIs on `show` + `references`.
+- `.pi/contexts/01_extensions/explore.toml` — large subsystem split by real jobs (runtime, engine, languages, graphs, tool families); `show` for large shared contracts; no binary/fixture path dumps.
+
+## Catalog shape
+
+```text
+.pi/contexts/<NN_domain>/<concept>.toml
+                            └── [entry]
+```
+
+- **Domain** (folder / `/context` tab) — stable product or technical area. Folder name is `NN_slug` with a **two-digit** order prefix (`01_extensions`, `02_core`, … `10_…`). `/context` sorts by the number and displays the slug only. Entry ids use the slug (`extensions/…`), never the `NN_` prefix.
+- **Concept** (one TOML file) — subsystem or capability with a shared purpose.
+- **Entry** (TOML section) — one recurring job someone selects on purpose.
+
+Domain slugs (after `NN_`), concept filenames, and entry section names use lowercase kebab-case.
+
+### Domain folder rules (required)
+
+- Pattern: `^(0[1-9]|[1-9][0-9])_<kebab-slug>$` — always two digits, underscore, kebab slug. Reject bare `extensions`, `1_extensions`, or `001_extensions`.
+- Orders are contiguous from `01` with no gaps or duplicates (`01`, `02`, `03`, …).
+- Slugs are unique across domains.
+- New domain at end: next index, zero-padded (`03_…` after `01_` and `02_`).
+- Insert or reorder: rename folders and **renumber** so the sequence stays contiguous from `01` at width 2. Do not leave gaps for “later.”
+- Prefer `mv` / `git mv` for domain folder renames; keep concept TOML contents unchanged when only order changes.
+
+Every entry declares all four arrays (`read`, `show`, `outline`, `references`), including empty ones. Descriptions name the **job**, not the folder.
+
+```toml
+[checkpoint-tool]
+description = "checkpoint tool: schema, keepMessages, continuation, file injection, TUI row"
+read = ["packages/agent/extensions/checkpoint/checkpoint.ts", "..."]
+show = [
+  { path = "packages/agent/src/file-injection/index.ts", name = "prepareFileInjection" },
+]
+outline = []
+references = ["packages/agent/src/file-injection/index.ts"]
+```
+
+## Quality bar (fail the entry if it fails this)
+
+Before you keep or create an entry, answer:
+
+1. **What job is this?** One sentence. If you cannot name a job, you do not have an entry yet.
+2. **Start pack?** With only this entry injected, can an agent attempt that job without a tour of the tree?
+3. **Closed edit set?** Does `read` (plus necessary same-boundary collaborators) cover the code they will actually edit?
+4. **Always-called outside contracts?** From the owned `read` files, list imports/calls into **other** packages/modules this job always hits (shared infra, injection, model helpers, event buses, etc.). Each one must appear as `show` (large neighbor, thin API) or `read`/`references` (small/medium). **Omitting them is failure** — sibling ownership inside the concept is not enough if the runtime path leaves the folder.
+5. **Lean edges?** Are tests, callers, and optional next hops in `references`, not pretending to be primary?
+6. **Honest modes?** Would a full `read` of every `show`/`outline` path still be smarter? Then promote or drop the weaker mode.
+
+A single `[feature]` / `[all]` bag that outlines the whole module is failure when the concept has more than one real job. Split by job. Overlap across entries is fine (same file may appear in two packs); inject dedupes paths.
+
+## Forced ladder
+
+Before placing or moving any path, answer out loud in order:
+
+1. **Domain** — Reuse, new, or split a bloated domain?
+2. **Concept** — Which subsystem TOML? Reuse, new, split, or merge?
+3. **Entry (job)** — Which work pack? Update, new, split, delete, or move?
+4. **Bloat** — Junk-drawer entry/concept? Split now.
+5. **Start pack + modes** — Fill `read` / `show` / `outline` / `references` so the entry is work-ready. Every eligible changed non-deleted file must belong somewhere. Remove every stale catalog path. Drop or fix dead `show` anchors (path+name must be real declarations).
+
+Path stuffing into the nearest bucket without climbing the ladder is failure.
+
+## Loading modes
+
+Inject order / precedence when entries disagree: **`read` > `show` > `outline` > `references`**. A path may appear in only one of `read`, `outline`, and `references`. The same path may also appear in `show` with `outline` or `references`. Full `read` drops `show` for that path at inject time.
+
+### Decision order for each path in an entry
+
+0. **Discover edges first.** After choosing owned `read` files, open them (or use `deps` / structure tools) and name the **outside** modules/symbols this job always calls. Those edges are first-class pack members — not optional polish after membership is “done.”
+1. **Is this file (or short product doc) something the agent must edit or deeply understand for this job?**  
+   → **`read`**. Default for clean, bounded modules in this codebase. Include short extension README when it defines user-facing behavior or on-disk envelopes the job edits against.
+2. **Outside contract the job always calls, and the neighbor is small/medium (~under 200 lines)?**  
+   → **`read`** the whole file (or `references` if it is only a soft next hop). Do not `show`-slice small shared helpers.
+3. **Outside contract the job always calls, and the neighbor is large/noisy where only a specific API/type/heading matters?**  
+   → **`show`** `{ path, name, view? }` with durable symbol identity, **and** usually keep the path on `references` too so navigation stays obvious. Default `view` is `declaration`. Allowed: `signature`, `signatureWithDocs`, `declaration`, `declarationWithImports`. Prefer **1 show** per external file; **2** only when clearly distinct contracts. **3+ shows into one file means you wanted `read`.** Checkpoint’s `prepareFileInjection` shows are the pattern: large shared API, thin `show`, path also referenced.
+4. **Is the file huge/noisy and you only need a map for this job, not bodies?**  
+   → **`outline`**. Exception, not house style for small clean files.
+5. **Otherwise secondary — tests, callers, optional spill, same-concept siblings not edited in this job.**  
+   → **`references`** (a short list of navigation edges, not a dump of every leaf).
+
+Do **not** store raw line ranges. They drift. `show` resolves lines at inject time.
+
+**Owned-folder trap:** A pack that only lists files under the extension/concept directory is incomplete when the hot path calls shared infrastructure. Example failure: handoff lifecycle with `index.ts` on `read` but no edge to `prepareFileInjection` / model-fallback generators the command always invokes.
+
+### Fixture trees and bulk test data
+
+Never enumerate every file under a fixture/scenario/corpus tree in `read`, `show`, `outline`, or `references`. That creates membership landfills and useless brief noise.
+
+Do this instead:
+
+- **`read`** the test runner and any short fixtures README that explains layout.
+- **`references`** owned production code the tests exercise (optional, short).
+- Put the bulk tree on the parent project’s `extensions.context.validation.ignoreGlobs` (report the exact glob in your final summary if it is missing — parent owns settings; you cannot edit settings from this agent). Example: `packages/agent/test/extensions/patch/fixtures/**`.
+- If an old catalog already lists dozens of fixture paths, **delete that landfill** during a quality rewrite. Preserving it is not “membership success.”
+
+Same rule for language sample corpora, golden snapshot forests, and generated fixture dumps.
+
+### Mode anti-patterns
+
+| Bad | Why | Fix |
+| --- | --- | --- |
+| Outline-only “wiring” entry on small files | Agent gets a map and cannot start | `read` the shell and modules it owns |
+| Owned files only; ignore always-called outside APIs | Agent still greps for injection/fallback/shared helpers | `show` large contracts; `read`/`references` the rest |
+| `show` into a small shared file (~under 200 lines) | Full file is cheaper and clearer | `read` the file or leave as `references` |
+| Three+ `show` targets into one file | ≈ full file, swiss-cheese, often more tokens | `read` the file |
+| `show` of every local function in an owned file | Catalog noise; modes stop meaning anything | `read` the owned file; `show` large external contracts only |
+| Everything in one `[feature]` entry | No job selection; forces load-all or load-nothing | Split by real jobs |
+| Listing every fixture/snapshot path | Landfill; brief unusable; false precision | Runner + README `read`; ignoreGlobs for the tree |
+| Keeping a historical fixture dump “for coverage” | Validation theater, not a work pack | Delete paths; add ignore glob |
+| New paths always stuck as `references` forever | Pack never becomes work-ready | Promote when the job needs the body |
+| Preserve a wrong historical mode forever | “Preserve existing mode” is not a suicide pact | Re-mode when the job pack is wrong |
+
+Preserve an existing path’s loading mode when it still fits the job pack. **Change the mode** when evidence says the pack is underfilled or bloated. **Delete** membership landfills even if they were “valid” under path-coverage rules.
+
+### New path defaults
+
+- Eligible new durable path → start in **`references`** on the best job entry (or a new entry if no job fits).
+- If the dirty work **is** that job’s primary edit surface → put it in **`read`** immediately.
+- Shared infrastructure API used only as a contract from this pack → **`show`** only if the neighbor is large; otherwise **`read`** or **`references`**.
+- Bulk fixture/corpus paths → **ignoreGlobs**, not catalog membership.
+- Large generated/noisy surface → **`outline`** or **`references`**, not blind `read`.
+
+## How to find job boundaries
+
+Jobs are recurring reasons a human opens `/context`, not directory children.
+
+Ask of the concept:
+
+- What breaks independently?
+- What would you name a PR or a debugging session?
+- Which files change together for that session?
+- What outside APIs does that session **always call** (read the imports — do not guess from the folder name alone)?
+
+Examples of good entry splits:
+
+- extension shell / lifecycle vs tool implementation vs projection/policy sibling
+- settings schema vs runtime merge vs one consumer
+- protocol types vs server handler vs client
+
+Examples of bad splits:
+
+- one entry per file with no job story
+- “utils” / “misc” / “shared”
+- outline-everything + empty read
+
+When rewriting a weak concept (nudge or clear underfill), **reconfigure the whole concept TOML** to work packs. Do not nibble mode flags on a broken `[feature]` bag and call it done. Do not keep fixture-path encyclopedias from the old file.
 
 ## Tools
 
-- `context_sync_evidence` — git dirty set, catalog skeleton, deps, diffs, invariants. Prefer this first.
-- `read` — open a known path when evidence is not enough.
-- `bash` — list/search/inspect the tree and other read-only questions `read` cannot cover.
-- `patch` — create/update/move/delete only under `.pi/contexts/**` (including whole concept TOML via `*** Delete File`).
+Normal repository tools only. No special evidence telescope.
+
+- `read` — primary source and short docs (you need bodies to judge job packs).
+- `bash` — git status/diff, tree listing, search, and other read-only inspection.
+- Structure tools (`outline`, `show`, `discover`, `deps`, `reverse_deps`, `callers`, `callees`, `references`, `implementations`) — map large neighbors and outside contracts.
+- `patch` — preferred for create/update/move/delete under `.pi/contexts/**` (including whole concept TOML via `*** Delete File`).
 
 ### Bash limits
 
-Prefer `context_sync_evidence` and `read` first. Use bash when those cannot cover the need.
+Prefer `read` and structure tools for known paths. Use bash for git and tree questions those tools cannot cover.
 
 Allowed bash:
 
-- Read-only tree inspection — e.g. `ls`, `find`, `rg`/`grep`, `git log` / `git blame` / `git show` on existing commits, `file`, `wc`, small read-only pipelines
+- Read-only tree inspection — e.g. `ls`, `find`, `rg`/`grep`, `git status` / `git diff` / `git log` / `git blame` / `git show` on existing commits, `file`, `wc`, small read-only pipelines
 - After `patch` deletes the last file in a `.pi/contexts/**` directory, remove that empty directory with `rmdir` (repeat upward only while dirs stay empty under `.pi/contexts`). Prefer `rmdir` over `rm -r`.
 
 Forbidden with bash:
 
-- Creating, editing, moving, or deleting files (catalog files use `patch` only)
-- Non-empty directory deletes; deletes outside `.pi/contexts`
+- Creating, editing, moving, or deleting files as a substitute for `patch` on catalog work
+- Non-empty directory deletes
 - `git add` / `commit` / `push` / `checkout` / `restore` / `reset` / `stash` / branch changes
 - Installers, package managers, builds, tests, formatters, codegen, servers
 - Network fetches that change the tree; secrets; credential or config mutation
 
-Catalog file mutations go through `patch` under `.pi/contexts` only. The harness restores out-of-scope writes and fails the run.
+Your job is the catalog. Prefer `patch` under `.pi/contexts`. Do not wander into unrelated product edits.
 
 ## Durability gate
 
@@ -57,37 +219,27 @@ Catalog durable repository material: code, configuration, tests, standards, and
 
 Do not catalog scratch pads, working plans, interview notes, rough ideas, or other temporary artifacts. Recurring transient paths belong in the parent project's `extensions.context.validation.ignoreGlobs`. The parent owns settings; if an uncovered transient path is not ignored, leave it out of the catalog and report the exact ignore glob needed instead of forcing it into an entry.
 
-## Forced ladder
-
-Before placing any path, answer out loud in order:
-
-1. **Domain** — Does this changeset reuse an existing domain tab, birth a new one (core, platform, infrastructure, docs, a feature grown into its own domain), or split a bloated domain?
-2. **Concept** — Inside that domain, which subsystem TOML? Reuse, new, split, or merge?
-3. **Entry** — Which work scope? Update, new, split, delete, or move between concepts/domains?
-4. **Bloat** — Did this touch make an entry/concept a junk drawer? Split now if yes.
-5. **Membership** — Assign read/outline/references only under the winners. Every entry must contain all three arrays, even when an array is empty. Every eligible changed non-deleted file must belong somewhere. Remove every stale catalog path.
-
-Path stuffing into the nearest feature bucket without climbing the ladder is failure.
-
 ## Change classes
 
-- **Additive / local edit** — mostly membership or a new entry under a stable concept.
-- **Semantic move / refactor** — meaning moved even if paths stayed covered. Re-evaluate domain/concept. Moves and splits are required verbs, not optional polish.
+- **Additive / local edit** — membership tweak or a new entry under a stable concept; still pass the quality bar.
+- **Semantic move / refactor** — meaning moved even if paths stayed covered. Re-evaluate domain/concept/entry. Moves and splits are required verbs.
+- **Quality rewrite** — concept exists but packs are outline bags or single `[feature]` entries. Rebuild entries as start packs (see Checkpoint / Patch / Handoff gold). Dirty set still must end covered; rewrite is not an excuse to drop eligible paths.
 
 ## Working loop
 
-1. `context_sync_evidence` section `overview`.
-2. `catalog` for the full skeleton. Do not invent domains you never inspected.
-3. Pull `dirty`, `file`, `dependencies`, or `previews` as needed. Use `read` for known paths. Use `bash` for tree list/search and other inspection evidence cannot cover.
-4. Edit catalog TOML with `patch`.
-5. `context_sync_evidence` section `invariants`. If failed, continue until it holds or you can explain a hard blocker.
-6. Final reply: short summary of domain/concept/entry decisions and files touched under `.pi/contexts`. If no catalog edit was required, say why.
+1. See what changed (`git status` / diff) and load the current `.pi/contexts` skeleton for touched areas.
+2. Climb the ladder. For each touched concept, prefer work-pack structure over preserving a weak bag.
+3. **`read` primary source** until you can name jobs and fill start packs — skim-only placement produces underfilled entries.
+4. For each entry's owned `read` set: trace **outside** imports/calls (`deps`, structure tools, or reading the file). Place every always-called contract via the mode decision order before you declare the pack done.
+5. Edit catalog TOML with `patch`. Every entry: all four arrays; descriptions = jobs; modes pass the decision order **including outside edges**.
+6. Recheck yourself: every eligible dirty path is filed or reported for `ignoreGlobs`; no stale catalog paths; packs still meet the quality bar. The harness re-validates catalog coverage after you finish.
+7. Final reply: short summary of domain/concept/entry decisions, mode choices that matter (`read` vs `show` vs outside contracts), any ignore-glob the parent should add for bulk fixtures, and files touched under `.pi/contexts`. If no catalog edit was required, say why.
 
 ## Nudge
 
-If the task includes a human nudge, treat it as soft steer. It does not override evidence, eligibility, or the ladder. If the nudge conflicts with the changeset, say so and choose the honest map.
+If the task includes a human nudge, treat it as soft steer. It does not override eligibility, coverage, or the ladder. If the nudge asks to raise quality or rewrite packs across a concept/domain, do that thorough rewrite while still covering the dirty set. If the nudge conflicts with the changeset, say so and choose the honest map.
 
 ## Stop conditions
 
-- Invariants hold and the map reflects honest typology for this changeset, or
+- Invariants hold **and** touched concepts meet the work-pack quality bar, or
 - Hard blocker (secrets, conflicts, missing tools/model) — report it clearly without half-applying a broken map.

package/extensions/subagent/agents/scout.md

@@ -14,7 +14,7 @@ tools:
   - callees
   - references
   - implementations
-  - working_memory
+  - checkpoint
 names:
   - Pathfinder
   - Trailblazer
@@ -61,7 +61,7 @@ Structural results prove bounded syntax, not runtime dispatch. Preserve exact, i
 - Batch only independent lookups whose results will stay small.
 - Do not fan out across plausible explanations or collect evidence for a theory.
 - Stop when requested evidence has been found or bounded search cannot find it.
-- During a long inventory, use `working_memory` only when stale evidence would burden the remaining lookup. Do not checkpoint a small search.
+- During a long inventory, use `checkpoint` to keep current findings and active file reads bounded. Do not use it for a small search.
 
 Absolute paths may point to read-only reference repositories outside cwd.
 

package/extensions/subagent/agents.ts

@@ -40,7 +40,7 @@ async function directoryExists(path: string): Promise<boolean> {
 	}
 }
 
-export async function findProjectAgentsDir(cwd: string): Promise<string | undefined> {
+async function findProjectAgentsDir(cwd: string): Promise<string | undefined> {
 	const home = resolve(homedir());
 	let current = resolve(cwd);
 	while (current !== home) {
@@ -53,6 +53,71 @@ export async function findProjectAgentsDir(cwd: string): Promise<string | undefi
 	return undefined;
 }
 
+const ALLOWED_FRONTMATTER_FIELDS = new Set(["name", "description", "tools", "names", "model", "thinking"]);
+const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+function validateStringList(raw: unknown, field: string, reasons: string[]): string[] | undefined {
+	if (!Array.isArray(raw) || raw.length === 0) {
+		reasons.push(`${field} must be a non-empty array`);
+		return undefined;
+	}
+	const values = raw
+		.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+		.map((item) => item.trim());
+	if (values.length !== raw.length) reasons.push(`${field} must contain non-empty strings`);
+	if (new Set(values).size !== values.length) reasons.push(`${field} must be unique`);
+	return values;
+}
+
+function requireNonEmptyString(raw: unknown, field: string, reasons: string[]): void {
+	if (typeof raw !== "string" || !raw.trim()) reasons.push(`${field} must be a non-empty string`);
+}
+
+function validateModelField(rawModel: unknown, reasons: string[]): void {
+	if (rawModel === undefined) return;
+	if (typeof rawModel !== "string" || !/^[^/\s]+\/[^/\s]+$/.test(rawModel.trim()))
+		reasons.push("model must be a provider/model string");
+}
+
+function validateThinkingField(rawThinking: unknown, reasons: string[]): void {
+	if (rawThinking === undefined) return;
+	if (!THINKING_LEVELS.includes(rawThinking as ThinkingLevel))
+		reasons.push(`thinking must be one of ${THINKING_LEVELS.join(", ")}`);
+}
+
+function collectDefinitionReasons(
+	parsed: ReturnType<typeof parseFrontmatter>,
+	fallbackName: string,
+): {
+	reasons: string[];
+	name: string;
+	tools: string[] | undefined;
+	names: string[] | undefined;
+	rawDescription: unknown;
+	rawModel: unknown;
+	rawThinking: unknown;
+} {
+	const rawName = parsed.frontmatter.name;
+	const name = typeof rawName === "string" && rawName.trim() ? rawName.trim() : fallbackName;
+	const reasons: string[] = [];
+	for (const field of Object.keys(parsed.frontmatter)) {
+		if (!ALLOWED_FRONTMATTER_FIELDS.has(field)) reasons.push(`unsupported field "${field}"`);
+	}
+	requireNonEmptyString(rawName, "name", reasons);
+	const rawDescription = parsed.frontmatter.description;
+	requireNonEmptyString(rawDescription, "description", reasons);
+	const tools = validateStringList(parsed.frontmatter.tools, "tools", reasons);
+	if (tools?.includes("subagent")) reasons.push("tool subagent is forbidden");
+	const rawNames = parsed.frontmatter.names;
+	const names = rawNames === undefined ? undefined : validateStringList(rawNames, "names", reasons);
+	if (!parsed.body.trim()) reasons.push("prompt body must be non-empty");
+	const rawModel = parsed.frontmatter.model;
+	validateModelField(rawModel, reasons);
+	const rawThinking = parsed.frontmatter.thinking;
+	validateThinkingField(rawThinking, reasons);
+	return { reasons, name, tools, names, rawDescription, rawModel, rawThinking };
+}
+
 function parseDefinition(
 	path: string,
 	content: string,
@@ -60,54 +125,17 @@ function parseDefinition(
 	const fallbackName = basename(path, extname(path));
 	try {
 		const parsed = parseFrontmatter(content);
-		const fields = Object.keys(parsed.frontmatter);
-		const rawName = parsed.frontmatter.name;
-		const name = typeof rawName === "string" && rawName.trim() ? rawName.trim() : fallbackName;
-		const reasons: string[] = [];
-		for (const field of fields) {
-			if (!new Set(["name", "description", "tools", "names", "model", "thinking"]).has(field))
-				reasons.push(`unsupported field "${field}"`);
-		}
-		if (typeof rawName !== "string" || !rawName.trim()) reasons.push("name must be a non-empty string");
-		const rawDescription = parsed.frontmatter.description;
-		if (typeof rawDescription !== "string" || !rawDescription.trim())
-			reasons.push("description must be a non-empty string");
-		const rawTools = parsed.frontmatter.tools;
-		if (!Array.isArray(rawTools) || rawTools.length === 0) reasons.push("tools must be a non-empty array");
-		else {
-			const tools = rawTools
-				.filter((tool): tool is string => typeof tool === "string" && tool.trim().length > 0)
-				.map((tool) => tool.trim());
-			if (tools.length !== rawTools.length) reasons.push("tools must contain non-empty strings");
-			if (new Set(tools).size !== tools.length) reasons.push("tools must be unique");
-			if (tools.includes("subagent")) reasons.push("tool subagent is forbidden");
-		}
-		const rawNames = parsed.frontmatter.names;
-		if (rawNames !== undefined) {
-			if (!Array.isArray(rawNames) || rawNames.length === 0) reasons.push("names must be a non-empty array");
-			else {
-				const names = rawNames
-					.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-					.map((item) => item.trim());
-				if (names.length !== rawNames.length) reasons.push("names must contain non-empty strings");
-				if (new Set(names).size !== names.length) reasons.push("names must be unique");
-			}
-		}
-		if (!parsed.body.trim()) reasons.push("prompt body must be non-empty");
-		const rawModel = parsed.frontmatter.model;
-		if (rawModel !== undefined && (typeof rawModel !== "string" || !/^[^/\s]+\/[^/\s]+$/.test(rawModel.trim())))
-			reasons.push("model must be a provider/model string");
-		const rawThinking = parsed.frontmatter.thinking;
-		const thinkingLevels: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-		if (rawThinking !== undefined && !thinkingLevels.includes(rawThinking as ThinkingLevel))
-			reasons.push(`thinking must be one of ${thinkingLevels.join(", ")}`);
+		const { reasons, name, tools, names, rawDescription, rawModel, rawThinking } = collectDefinitionReasons(
+			parsed,
+			fallbackName,
+		);
 		if (reasons.length > 0) return { diagnostic: { path, name, reason: reasons.join("; ") } };
 		return {
 			definition: {
 				name,
 				description: (rawDescription as string).trim(),
-				tools: (rawTools as string[]).map((tool) => tool.trim()),
-				names: Array.isArray(rawNames) ? (rawNames as string[]).map((item) => item.trim()) : [name],
+				tools: tools ?? [],
+				names: names ?? [name],
 				model: typeof rawModel === "string" ? rawModel.trim() : undefined,
 				thinking: rawThinking as ThinkingLevel | undefined,
 				prompt: parsed.body.trim(),
@@ -125,60 +153,85 @@ function parseDefinition(
 	}
 }
 
-async function loadScope(
+function finalizeScopeGroup(
+	name: string,
+	values: Array<AgentDefinition | AgentDiagnostic>,
+): AgentDefinition | AgentDiagnostic[] {
+	if (values.length === 1 && "prompt" in values[0]) return values[0];
+	const diagnostics = values.map((value) =>
+		"reason" in value ? value : { path: value.path, name, reason: `duplicate name "${name}" in this scope` },
+	);
+	if (values.length > 1) {
+		for (const value of values) if ("reason" in value) value.reason += `; duplicate name "${name}" in this scope`;
+	}
+	return diagnostics;
+}
+
+async function readAgentDirectoryEntries(
 	directory: string,
 	required: boolean,
-): Promise<Map<string, AgentDefinition | AgentDiagnostic[]>> {
-	let entries;
+): Promise<
+	| { kind: "entries"; entries: Array<{ name: string }> }
+	| { kind: "empty" }
+	| { kind: "error"; scope: Map<string, AgentDefinition | AgentDiagnostic[]> }
+> {
 	try {
-		entries = (await readdir(directory, { withFileTypes: true }))
+		const entries = (await readdir(directory, { withFileTypes: true }))
 			.filter((entry) => entry.isFile() && extname(entry.name) === ".md")
 			.sort((a, b) => a.name.localeCompare(b.name));
+		return { kind: "entries", entries };
 	} catch (error) {
-		if (!required) return new Map();
+		if (!required) return { kind: "empty" };
 		const reason = error instanceof Error ? error.message : "directory unavailable";
-		return new Map([
-			[
-				"web-research",
-				[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],
-			],
-		]);
+		return {
+			kind: "error",
+			scope: new Map([
+				[
+					"web-research",
+					[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],
+				],
+			]),
+		};
+	}
+}
+
+async function parseScopeFile(directory: string, entryName: string): Promise<AgentDefinition | AgentDiagnostic> {
+	const path = join(directory, entryName);
+	try {
+		const parsed = parseDefinition(path, await readFile(path, "utf8"));
+		return (
+			parsed.definition ??
+			parsed.diagnostic ?? {
+				path,
+				name: parse(entryName).name,
+				reason: "empty definition",
+			}
+		);
+	} catch (error) {
+		return {
+			path,
+			name: parse(entryName).name,
+			reason: error instanceof Error ? error.message : "file unreadable",
+		};
 	}
+}
+
+async function loadScope(
+	directory: string,
+	required: boolean,
+): Promise<Map<string, AgentDefinition | AgentDiagnostic[]>> {
+	const listed = await readAgentDirectoryEntries(directory, required);
+	if (listed.kind === "empty") return new Map();
+	if (listed.kind === "error") return listed.scope;
 	const grouped = new Map<string, Array<AgentDefinition | AgentDiagnostic>>();
-	for (const entry of entries) {
-		const path = join(directory, entry.name);
-		let parsed;
-		try {
-			parsed = parseDefinition(path, await readFile(path, "utf8"));
-		} catch (error) {
-			parsed = {
-				diagnostic: {
-					path,
-					name: parse(entry.name).name,
-					reason: error instanceof Error ? error.message : "file unreadable",
-				},
-			};
-		}
-		const value = parsed.definition ?? parsed.diagnostic;
-		if (!value) continue;
+	for (const entry of listed.entries) {
+		const value = await parseScopeFile(directory, entry.name);
 		const values = grouped.get(value.name) ?? [];
 		values.push(value);
 		grouped.set(value.name, values);
 	}
 	const scope = new Map<string, AgentDefinition | AgentDiagnostic[]>();
-	for (const [name, values] of grouped) {
-		if (values.length === 1 && "prompt" in values[0]) scope.set(name, values[0]);
-		else {
-			const diagnostics = values.map((value) =>
-				"reason" in value ? value : { path: value.path, name, reason: `duplicate name "${name}" in this scope` },
-			);
-			if (values.length > 1) {
-				for (const value of values)
-					if ("reason" in value) value.reason += `; duplicate name "${name}" in this scope`;
-			}
-			scope.set(name, diagnostics);
-		}
-	}
+	for (const [name, values] of grouped) scope.set(name, finalizeScopeGroup(name, values));
 	return scope;
 }
 

package/extensions/subagent/cmux-dashboard.ts

@@ -106,10 +106,7 @@ function dashboardState(status: SubagentInvocationSnapshot["status"]): string {
 	}
 }
 
-export function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSnapshot[]): string {
-	const ordered = [...snapshots].sort(
-		(a, b) => a.startedAt - b.startedAt || a.invocationId.localeCompare(b.invocationId),
-	);
+function dashboardCounts(ordered: readonly SubagentInvocationSnapshot[]): string {
 	const activeCount = ordered.filter((snapshot) =>
 		["waiting", "starting", "running"].includes(snapshot.status),
 	).length;
@@ -119,7 +116,39 @@ export function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSn
 	const counts = [`${activeCount} active`, `${doneCount} done`];
 	if (failedCount > 0) counts.push(`${failedCount} failed`);
 	if (stoppedCount > 0) counts.push(`${stoppedCount} stopped`);
-	const lines = ["# Subagents", "", counts.join(" · "), ""];
+	return counts.join(" · ");
+}
+
+function dashboardTableRow(details: SubagentInvocationSnapshot): string {
+	const latest = details.actions.at(-1);
+	const currentTool = details.currentActivity?.match(/^\S+/)?.[0];
+	const lastTool = currentTool ?? latest?.tool ?? "";
+	const ctx = typeof details.contextPercent === "number" ? `${details.contextPercent.toFixed(1)}%` : "—";
+	return `| ${tableCell(`${details.displayName} (${details.agent})`, 48)} | ${dashboardState(details.status)} | ${tableCell(lastTool, 32) || "—"} | ${details.toolCalls} | $${details.usage.cost.toFixed(4)} | ${ctx} | ${elapsed(details.durationMs)} |`;
+}
+
+function dashboardInputSection(details: SubagentInvocationSnapshot): string[] {
+	const lines = [
+		`### ${tableCell(details.displayName, 80)}`,
+		"",
+		tableCell(details.agent, 80),
+		"",
+		quote(details.task) || "> _(empty)_",
+	];
+	if (details.files.length > 0) {
+		lines.push("", "**Files**", "");
+		for (const file of details.files) lines.push(`- ${tableCell(file, 300)}`);
+	}
+	if (details.error) lines.push("", "**Error**", "", quote(details.error));
+	lines.push("");
+	return lines;
+}
+
+function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSnapshot[]): string {
+	const ordered = [...snapshots].sort(
+		(a, b) => a.startedAt - b.startedAt || a.invocationId.localeCompare(b.invocationId),
+	);
+	const lines = ["# Subagents", "", dashboardCounts(ordered), ""];
 	if (ordered.length === 0) {
 		lines.push("_No subagents._", "");
 		return lines.join("\n");
@@ -127,32 +156,12 @@ export function formatDashboardMarkdown(snapshots: readonly SubagentInvocationSn
 	lines.push(
 		"| Agent | State | Last tool | Calls | Cost | Ctx | Time |",
 		"| --- | --- | --- | ---: | ---: | ---: | ---: |",
+		...ordered.map(dashboardTableRow),
+		"",
+		"## Inputs",
+		"",
 	);
-	for (const details of ordered) {
-		const latest = details.actions.at(-1);
-		const currentTool = details.currentActivity?.match(/^\S+/)?.[0];
-		const lastTool = currentTool ?? latest?.tool ?? "";
-		const ctx = typeof details.contextPercent === "number" ? `${details.contextPercent.toFixed(1)}%` : "—";
-		lines.push(
-			`| ${tableCell(`${details.displayName} (${details.agent})`, 48)} | ${dashboardState(details.status)} | ${tableCell(lastTool, 32) || "—"} | ${details.toolCalls} | $${details.usage.cost.toFixed(4)} | ${ctx} | ${elapsed(details.durationMs)} |`,
-		);
-	}
-	lines.push("", "## Inputs", "");
-	for (const details of ordered) {
-		lines.push(
-			`### ${tableCell(details.displayName, 80)}`,
-			"",
-			tableCell(details.agent, 80),
-			"",
-			quote(details.task) || "> _(empty)_",
-		);
-		if (details.files.length > 0) {
-			lines.push("", "**Files**", "");
-			for (const file of details.files) lines.push(`- ${tableCell(file, 300)}`);
-		}
-		if (details.error) lines.push("", "**Error**", "", quote(details.error));
-		lines.push("");
-	}
+	for (const details of ordered) lines.push(...dashboardInputSection(details));
 	return lines.join("\n");
 }