pi-legion 4.0.0 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/CHANGELOG.md +168 -1
  2. package/README.md +101 -44
  3. package/agents/centurion.md +20 -16
  4. package/agents/scout.md +3 -1
  5. package/agents/worker.md +5 -7
  6. package/docs/contracts/declarative-phase-machine-v5.md +128 -0
  7. package/docs/contracts/subagent-renewal-v1.md +260 -0
  8. package/docs/headless-child-contract.md +6 -3
  9. package/docs/inprocess-supervisor.md +70 -24
  10. package/docs/legion-v2-contract.md +9 -0
  11. package/docs/spawn-mode-visibility-v1.md +4 -1
  12. package/index.ts +598 -44
  13. package/package.json +2 -2
  14. package/src/agents/agents.ts +293 -36
  15. package/src/agents/overrides.ts +3 -1
  16. package/src/agents/settings.ts +6 -18
  17. package/src/extension/child-guard.ts +25 -1
  18. package/src/extension/legion-tools.ts +66 -21
  19. package/src/extension/notify.ts +136 -4
  20. package/src/extension/playbook.ts +2 -2
  21. package/src/extension/runtime.ts +56 -1
  22. package/src/extension/summary.ts +13 -4
  23. package/src/extension/timing.ts +8 -4
  24. package/src/legion/phase-conditions.ts +164 -0
  25. package/src/legion/phase-machine.ts +403 -0
  26. package/src/legion/state-machine.ts +219 -115
  27. package/src/runs/args.ts +32 -18
  28. package/src/runs/extension-inheritance.ts +220 -0
  29. package/src/runs/orchestrator.ts +137 -44
  30. package/src/runs/progress-signal.ts +137 -0
  31. package/src/runs/store-lookup.ts +270 -0
  32. package/src/shared/types.ts +88 -3
  33. package/src/supervisor/child-context.ts +19 -0
  34. package/src/supervisor/inprocess-supervisor.ts +29 -5
  35. package/src/supervisor/routing-supervisor.ts +2 -1
  36. package/src/supervisor/rpc-supervisor.ts +2 -2
  37. package/src/tui/tree-view.ts +56 -0
  38. package/src/tui/viz/palette.ts +0 -3
  39. package/agents/advisor.md +0 -110
  40. package/agents/designer.md +0 -87
  41. package/agents/planner.md +0 -53
  42. package/agents/prototype.md +0 -72
  43. package/agents/reviewer.md +0 -113
@@ -0,0 +1,270 @@
1
+ /**
2
+ * Cross-store child lookup (issue #270).
3
+ *
4
+ * Child records live under `<cwd>/.pi-subagents`, so a control call such as
5
+ * `subagent({action:"status", name})` can only see children launched from the
6
+ * exact same `cwd`. In practice that assumption breaks in two ordinary ways:
7
+ *
8
+ * 1. A user launches from one directory and later runs a control call from
9
+ * another. Nothing records "where you launched it", so the miss is
10
+ * indistinguishable from a typo.
11
+ * 2. A `worktree: true` role (centurion) is spawned INTO a git worktree:
12
+ * `orchestrator.ts` passes `cwd: worktreePath ?? this.cwd` to the child, so
13
+ * the child's own run store lands in `<runDir>/worktrees/<name>/.pi-subagents`
14
+ * — a tree the parent's root store can never enumerate.
15
+ *
16
+ * The fix is a bounded, read-only search of the stores that can plausibly hold
17
+ * the record, plus a message that names the directory instead of asking the
18
+ * caller to remember it.
19
+ *
20
+ * Bounded on purpose:
21
+ * - only stores reachable from the two known roots (the current `cwd` and the
22
+ * caller's `cwd`), never a scan of `$HOME` or the filesystem;
23
+ * - at most `MAX_SEARCHED_STORES` candidates, each probed with a single
24
+ * `readdir` of `runs/`;
25
+ * - `readdir` only — never `createRun`/`ensureRootUsable`, because a lookup
26
+ * must not materialise directories in a tree the user cannot write.
27
+ */
28
+
29
+ import * as fs from "node:fs";
30
+ import * as path from "node:path";
31
+ import { RunStore, pickChildByName } from "./store.ts";
32
+ import type { RunRecord } from "../shared/types.ts";
33
+
34
+ /** Directory name every run store uses. */
35
+ export const STORE_DIR_NAME = ".pi-subagents";
36
+
37
+ /**
38
+ * Hard cap on candidate stores. A worktree-heavy run can nest a store per
39
+ * centurion; the cap keeps a pathological tree from turning one status call
40
+ * into a filesystem walk.
41
+ */
42
+ export const MAX_SEARCHED_STORES = 24;
43
+
44
+ /** A store that actually contains run records (so a miss there is meaningful). */
45
+ export interface CandidateStore {
46
+ rootDir: string;
47
+ /** Why this directory is a candidate, for the error message. */
48
+ reason: "cwd" | "caller-cwd" | "sibling" | "worktree";
49
+ /** Run records found in it (empty when the directory is unreadable). */
50
+ runs: readonly RunRecord[];
51
+ }
52
+
53
+ /** The store a lookup resolved to, when it did. */
54
+ export interface ResolvedChildLocation {
55
+ storeRoot: string;
56
+ runId: string;
57
+ reason: CandidateStore["reason"];
58
+ name: string;
59
+ }
60
+
61
+ function isDirectory(target: string): boolean {
62
+ try {
63
+ return fs.statSync(target).isDirectory();
64
+ } catch {
65
+ return false;
66
+ }
67
+ }
68
+
69
+ /**
70
+ * Cheap existence probe: does `<root>/runs` hold at least one run directory?
71
+ *
72
+ * Deliberately one `readdir`, not `run.json` parsing: a store that exists but
73
+ * holds no runs must NOT be offered as "the place to look", because a miss
74
+ * there would send the caller in a circle.
75
+ */
76
+ function hasRuns(rootDir: string): boolean {
77
+ try {
78
+ return fs
79
+ .readdirSync(path.join(rootDir, "runs"), { withFileTypes: true })
80
+ .some((entry) => entry.isDirectory());
81
+ } catch {
82
+ return false;
83
+ }
84
+ }
85
+
86
+ function storeRootOf(cwd: string): string {
87
+ return path.join(cwd, STORE_DIR_NAME);
88
+ }
89
+
90
+ /**
91
+ * The store roots worth probing for one lookup, most likely first.
92
+ *
93
+ * `cwd` is the store the call already resolved (so its runs are already loaded
94
+ * by the caller and it is listed here only for completeness). `parentOf` climbs
95
+ * the run's own `worktrees/` directory, which is where a worktree child's store
96
+ * lives: `<runDir>/worktrees/<child>/.pi-subagents`.
97
+ */
98
+ export function candidateStoreRoots(input: {
99
+ cwd: string;
100
+ /** The directory the caller's context runs in, when it differs from `cwd`. */
101
+ callerCwd?: string | undefined;
102
+ /** Run directory of the store already searched (`<root>/runs/<runId>`). */
103
+ runDir?: string | undefined;
104
+ }): Array<{ rootDir: string; reason: CandidateStore["reason"] }> {
105
+ const out: Array<{ rootDir: string; reason: CandidateStore["reason"] }> = [];
106
+ const seen = new Set<string>();
107
+ const push = (rootDir: string, reason: CandidateStore["reason"]): void => {
108
+ const resolved = path.resolve(rootDir);
109
+ if (seen.has(resolved) || out.length >= MAX_SEARCHED_STORES) return;
110
+ seen.add(resolved);
111
+ out.push({ rootDir: resolved, reason });
112
+ };
113
+
114
+ push(storeRootOf(input.cwd), "cwd");
115
+ if (input.callerCwd !== undefined) push(storeRootOf(input.callerCwd), "caller-cwd");
116
+
117
+ // Sibling stores: a session started in `<base>/legion-demo` leaves its records
118
+ // there, and the reported case had the caller standing in `<base>` — one level
119
+ // up, looking at an empty store. Probing the immediate children of both known
120
+ // directories covers "I launched from a subdirectory" without a filesystem
121
+ // walk.
122
+ for (const base of [input.cwd, input.callerCwd]) {
123
+ if (base === undefined) continue;
124
+ let entries: fs.Dirent[] = [];
125
+ try {
126
+ entries = fs.readdirSync(base, { withFileTypes: true });
127
+ } catch {
128
+ entries = [];
129
+ }
130
+ for (const entry of entries) {
131
+ if (!entry.isDirectory() || entry.name === STORE_DIR_NAME) continue;
132
+ push(path.join(base, entry.name, STORE_DIR_NAME), "sibling");
133
+ }
134
+ }
135
+
136
+ // Worktree stores: every `<runDir>/worktrees/<name>` is a spawn root whose
137
+ // `.pi-subagents` belongs to that child. One level of `worktrees/` is the
138
+ // real shape (`src/runs/worktree.ts`); deeper nesting is reached by the
139
+ // recursive search below rather than by guessing path names here.
140
+ if (input.runDir !== undefined) {
141
+ const worktreesDir = path.join(input.runDir, "worktrees");
142
+ let entries: fs.Dirent[] = [];
143
+ try {
144
+ entries = fs.readdirSync(worktreesDir, { withFileTypes: true });
145
+ } catch {
146
+ entries = [];
147
+ }
148
+ for (const entry of entries) {
149
+ if (!entry.isDirectory()) continue;
150
+ push(path.join(worktreesDir, entry.name, STORE_DIR_NAME), "worktree");
151
+ }
152
+ }
153
+ return out;
154
+ }
155
+
156
+ /**
157
+ * Look for `name` in every candidate store.
158
+ *
159
+ * Returns the first hit plus every candidate that was actually examined, so the
160
+ * caller can report "searched these directories" instead of a single guess.
161
+ * Read-only: a store directory is only opened when `runs/` already has entries.
162
+ */
163
+ export function resolveChildAcrossStores(input: {
164
+ name: string;
165
+ cwd: string;
166
+ callerCwd?: string | undefined;
167
+ runDir?: string | undefined;
168
+ /** Injectable for tests. */
169
+ roots?: ReturnType<typeof candidateStoreRoots>;
170
+ }): { found: ResolvedChildLocation | null; searched: CandidateStore[] } {
171
+ const roots = input.roots ?? candidateStoreRoots(input);
172
+ const searched: CandidateStore[] = [];
173
+ for (const candidate of roots) {
174
+ if (!hasRuns(candidate.rootDir)) continue;
175
+ let runs: readonly RunRecord[];
176
+ try {
177
+ runs = new RunStore({ rootDir: candidate.rootDir }).listRuns();
178
+ } catch {
179
+ continue;
180
+ }
181
+ searched.push({ rootDir: candidate.rootDir, reason: candidate.reason, runs });
182
+ const picked = pickChildByName([...runs], input.name);
183
+ if (picked) {
184
+ return {
185
+ found: {
186
+ storeRoot: candidate.rootDir,
187
+ runId: picked.run.runId,
188
+ reason: candidate.reason,
189
+ name: picked.child.name,
190
+ },
191
+ searched,
192
+ };
193
+ }
194
+ }
195
+ return { found: null, searched };
196
+ }
197
+
198
+ /** Distinct child names visible across the searched stores, for a miss message. */
199
+ export function knownChildNames(
200
+ searched: readonly CandidateStore[],
201
+ limit = 12,
202
+ ): { names: string[]; total: number; truncated: boolean } {
203
+ const seen = new Set<string>();
204
+ for (const store of searched) {
205
+ for (const run of store.runs) {
206
+ for (const child of run.children) seen.add(child.name);
207
+ }
208
+ }
209
+ const all = [...seen].sort();
210
+ return { names: all.slice(0, limit), total: all.length, truncated: all.length > limit };
211
+ }
212
+
213
+ /** Where a store sits relative to the cwd the caller used, for the message. */
214
+ function describeRoot(rootDir: string, cwd: string, reason: CandidateStore["reason"]): string {
215
+ const relative = path.relative(cwd, rootDir);
216
+ const label =
217
+ reason === "worktree"
218
+ ? " (a child's worktree)"
219
+ : reason === "caller-cwd"
220
+ ? " (the caller's cwd)"
221
+ : reason === "sibling"
222
+ ? " (a neighbouring directory)"
223
+ : "";
224
+ if (relative === "" || relative === STORE_DIR_NAME) return `${rootDir}${label}`;
225
+ return `${rootDir}${label}`;
226
+ }
227
+
228
+ /**
229
+ * The miss message.
230
+ *
231
+ * Structure follows the house style used by `spawn-hints.ts`: what was searched,
232
+ * why the miss is expected, then the exact next command. Three concrete
233
+ * improvements over the old text:
234
+ *
235
+ * - the absolute directory is printed (the old `${cwd}/.pi-subagents` was a
236
+ * path concatenation that only looked absolute);
237
+ * - names actually present are listed once each and capped, so the message
238
+ * stays readable on a busy store (measured 146 records / 61 unique names
239
+ * previously produced a 1717-character error);
240
+ * - it suggests `cwd:` with a real directory rather than "the same cwd you
241
+ * used for launch", which the caller cannot know.
242
+ */
243
+ export function unknownChildMessage(input: {
244
+ name: string;
245
+ cwd: string;
246
+ searched: readonly CandidateStore[];
247
+ }): string {
248
+ const lines: string[] = [`unknown child: ${input.name}`];
249
+ if (input.searched.length === 0) {
250
+ lines.push(` no child records found near ${input.cwd}: ${storeRootOf(input.cwd)} has no runs`);
251
+ lines.push(
252
+ ` Fix: pass \`cwd\` with the directory you launched from — records live in <cwd>/${STORE_DIR_NAME}.`,
253
+ );
254
+ return lines.join("\n");
255
+ }
256
+ lines.push(" searched:");
257
+ for (const store of input.searched) {
258
+ lines.push(` - ${describeRoot(store.rootDir, input.cwd, store.reason)}`);
259
+ }
260
+ const known = knownChildNames(input.searched);
261
+ if (known.names.length > 0) {
262
+ lines.push(
263
+ ` known here: ${known.names.join(", ")}${known.truncated ? `, … (${known.total} total)` : ""}`,
264
+ );
265
+ }
266
+ lines.push(
267
+ ` Fix: child records are scoped to a store — retry with \`cwd\` set to the directory listed above that owns the run.`,
268
+ );
269
+ return lines.join("\n");
270
+ }
@@ -58,6 +58,19 @@ export type OnBlockedPolicy = "forward" | "auto-approve" | "notify";
58
58
  */
59
59
  export const DEFAULT_ON_BLOCKED: OnBlockedPolicy = "auto-approve";
60
60
 
61
+ /**
62
+ * D5 default: a role that does not say otherwise may be renewed after its turn
63
+ * budget is exhausted. Parse leaves the field absent — consumers apply this.
64
+ */
65
+ export const DEFAULT_RENEWABLE = true;
66
+
67
+ /**
68
+ * D6 default: two renewals cover "the task was under-estimated"; a third means
69
+ * the task split is wrong. `0` is a meaningful value (renewal disabled), so
70
+ * consumers must test against `undefined`, never falsiness.
71
+ */
72
+ export const DEFAULT_MAX_RENEWALS = 2;
73
+
61
74
  export type AcceptanceLevel = "none" | "attested" | "verified";
62
75
 
63
76
  export interface AcceptanceCriterion {
@@ -109,11 +122,24 @@ export interface AgentConfig {
109
122
  inheritProjectContext: boolean;
110
123
  inheritSkills: boolean;
111
124
  /**
112
- * Load the host's discovered extensions (settings `packages`, project
113
- * extensions) in the child. Default false: children get `--no-extensions`
114
- * plus only explicit `--extension` paths (#43).
125
+ * Load the host's discovered extensions in the child. Default true (#280):
126
+ * a child starts from everything the parent has, then narrows it.
127
+ *
128
+ * `false` loads ONLY the card's own `extensions` / `subagentOnlyExtensions`
129
+ * — the pre-#280 behaviour, kept for roles that must stay hermetic. The
130
+ * child-guard is appended regardless; a child that skipped it would break
131
+ * the prompt/format contract no matter what the card asked for.
115
132
  */
116
133
  inheritExtensions?: boolean;
134
+ /**
135
+ * Extensions to subtract from the inherited set (#280).
136
+ *
137
+ * Entries are either a PATH (`/abs/.../index.ts`, `./rel`, `~/rel` — exact
138
+ * file match) or a NAME (`pi-lens`, `pi-any-endpoint` — the package
139
+ * directory or a loose `<name>.ts|js` entry). Ignored when
140
+ * `inheritExtensions: false`, because there is nothing to subtract from.
141
+ */
142
+ excludeExtensions?: string[];
117
143
 
118
144
  // ── behavior ──
119
145
  output?: string;
@@ -126,7 +152,26 @@ export interface AgentConfig {
126
152
  completionGuard?: boolean;
127
153
  maxSubagentDepth?: number;
128
154
  allowNestedSubagents?: boolean;
155
+ /**
156
+ * D5: may this role be renewed after an exhausted turn budget?
157
+ * Default true (DEFAULT_RENEWABLE); consumers read the field and fall back.
158
+ */
159
+ renewable?: boolean;
160
+ /**
161
+ * D6: how many renewals this role may receive.
162
+ * Default 2 (DEFAULT_MAX_RENEWALS); 0 disables renewal.
163
+ */
164
+ maxRenewals?: number;
129
165
  utility?: boolean;
166
+ /**
167
+ * #298: this role's team defines its own phase machine.
168
+ *
169
+ * Only meaningful on a team root (a centurion). Omitted means the built-in
170
+ * four-phase pipeline, so an undeclared team behaves exactly as before.
171
+ * Validated at load: an invalid machine is rejected rather than surfacing
172
+ * mid-run after the team has already spent tokens.
173
+ */
174
+ phases?: import("../legion/phase-machine.ts").PhaseMachine;
130
175
  toolBudget?: ToolBudgetConfig;
131
176
  turnBudget?: TurnBudgetConfig;
132
177
  disabled?: boolean;
@@ -312,6 +357,20 @@ export interface ChildRecord {
312
357
  spawnedAt: string;
313
358
  retiredAt?: string;
314
359
 
360
+ // renewal (subagent-renewal contract v1 §6: the budget lives on the child
361
+ // record in the parent run.json, never in the ledger)
362
+ /**
363
+ * D8: progress baseline taken at spawn and reset after each renewal.
364
+ *
365
+ * Structurally identical to W1's `ProgressBaseline`; declared inline because
366
+ * `src/shared` must not import from `src/runs` (the dependency points the
367
+ * other way). Only session rows at or after `lines` count as progress, so
368
+ * work done before a renewal can never be re-counted as "still moving".
369
+ */
370
+ renewalBaseline?: { at: number; lines: number };
371
+ /** D6: renewals already granted to this child. */
372
+ renewalsUsed?: number;
373
+
315
374
  // outcome (snapshot taken before child retirement — F27)
316
375
  execution?: Execution;
317
376
  acceptance?: AcceptanceResult;
@@ -534,6 +593,13 @@ export interface LegionPhaseTimeouts {
534
593
  implementing?: number;
535
594
  reviewing?: number;
536
595
  verifying?: number;
596
+ /**
597
+ * #298: a declared phase machine may name phases of its own, so this type
598
+ * cannot stay closed. The named fields above keep autocomplete for the
599
+ * built-in pipeline; the index signature admits custom ids without turning
600
+ * them into `any`.
601
+ */
602
+ [phase: string]: number | undefined;
537
603
  }
538
604
 
539
605
  /** Settings for the v2 legion tree, incrementally consumed by its milestones. */
@@ -764,6 +830,25 @@ export class SubagentError extends Error {
764
830
  }
765
831
  }
766
832
 
833
+ /**
834
+ * The one "name is not in this registry" error (#288).
835
+ *
836
+ * Six call sites (four supervisors, the orchestrator, and the stop loop) each
837
+ * spelled this by hand. They mean exactly the same thing — the caller asked
838
+ * about a child this process is not tracking — so the text should not drift
839
+ * between them.
840
+ *
841
+ * Deliberately terse. This is a runtime guard, not a lookup diagnostic: the
842
+ * user-facing miss message with the searched-store list comes from
843
+ * `unknownChildMessage` in `runs/store-lookup.ts`, which runs a real cross-store
844
+ * search before giving up. Printing that machinery here would be wrong, because
845
+ * at this layer a miss genuinely is a programming error (or a race), not a
846
+ * "wrong cwd" situation.
847
+ */
848
+ export function unknownChildError(name: string): SubagentError {
849
+ return new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
850
+ }
851
+
767
852
  export const ErrorCodes = {
768
853
  DISABLED: "DISABLED",
769
854
  START_FAILED: "START_FAILED",
@@ -47,6 +47,25 @@ export interface ChildLaunchContext {
47
47
  utility: boolean;
48
48
  /** Spawn backend of this child, so the child's doctor/diagnostics can self-report. */
49
49
  spawnMode: SpawnMode;
50
+ /**
51
+ * Per-child budgets, carried here because `process.env` cannot (#295).
52
+ *
53
+ * The parent computes these in `Orchestrator.lineageEnv` and hands them over
54
+ * as `SpawnInput.env`. A spawned rpc child receives that object as its real
55
+ * environment, so `childBudgetFromEnv()` finds it. An in-process child shares
56
+ * the HOST's `process.env` instead — the object is just a field on the spawn
57
+ * input — so the guard saw the parent's (absent) values and `toolBudget: 3`
58
+ * permitted 12 tool calls.
59
+ *
60
+ * Same reasoning as identity above: anything a child must observe per-session
61
+ * cannot travel through `process.env` when the child is a Task/AsyncLocalStorage
62
+ * scope rather than a process.
63
+ */
64
+ budget?: {
65
+ maxToolCalls?: number;
66
+ maxTurns?: number;
67
+ toolTimeoutMs?: number;
68
+ };
50
69
  }
51
70
 
52
71
  const STORE_KEY = Symbol.for("pi-legion.child-context.als");
@@ -10,6 +10,7 @@
10
10
 
11
11
  import { statSync } from "node:fs";
12
12
  import { formatChildTask } from "../extension/child-guard.ts";
13
+ import { childBudgetFromEnv } from "../extension/budget.ts";
13
14
  import { parseSessionFile } from "../shared/session.ts";
14
15
  import {
15
16
  applyThinkingSuffix,
@@ -18,6 +19,7 @@ import {
18
19
  } from "../runs/args.ts";
19
20
  import {
20
21
  ErrorCodes,
22
+ unknownChildError,
21
23
  isThinkingLevel,
22
24
  type InProcessLimits,
23
25
  SubagentError,
@@ -146,10 +148,17 @@ export function buildInProcessSessionPlan(
146
148
  const { text: systemPromptText, mode: systemPromptMode } =
147
149
  resolveInProcessSystemPrompt(input);
148
150
 
149
- const noExtensions = !childInheritsExtensions(input.agent);
150
- const additionalExtensionPaths = noExtensions
151
- ? collectChildExtensions(input.agent)
152
- : [];
151
+ // #280: pi's own discovery is ALWAYS disabled, and the full extension list is
152
+ // passed explicitly. Two reasons:
153
+ //
154
+ // - the inherited set is now computed by us (minus `excludeExtensions`), so
155
+ // letting pi discover on top of it would re-add an excluded extension
156
+ // - `additionalExtensionPaths` loads independently of `noExtensions`, so the
157
+ // child-guard arrives either way — but only this shape keeps rpc and
158
+ // in-process byte-identical (rpc also emits `--no-extensions` + explicit
159
+ // `--extension` flags)
160
+ const noExtensions = true;
161
+ const additionalExtensionPaths = collectChildExtensions(input.agent);
153
162
 
154
163
  return {
155
164
  cwd: input.cwd,
@@ -371,9 +380,24 @@ function resolveChildLaunchContext(input: SpawnInput): ChildLaunchContext {
371
380
  utility: Boolean(input.agent.utility),
372
381
  spawnMode: "inprocess",
373
382
  ...(acceptanceRole ? { acceptanceRole } : {}),
383
+ // #295: read the budgets off `SpawnInput.env` — the same keys the rpc child
384
+ // gets as its real environment — and carry them in the context, because the
385
+ // in-process child shares the host's process.env and cannot see them there.
386
+ ...budgetFromSpawnEnv(input.env),
374
387
  };
375
388
  }
376
389
 
390
+ /** Extract the child budget keys from a spawn env, for the in-process channel. */
391
+ function budgetFromSpawnEnv(env: NodeJS.ProcessEnv | undefined): {
392
+ budget?: ChildLaunchContext["budget"];
393
+ } {
394
+ if (!env) return {};
395
+ const budget = childBudgetFromEnv(env);
396
+ return budget.maxToolCalls === undefined && budget.maxTurns === undefined && budget.toolTimeoutMs === undefined
397
+ ? {}
398
+ : { budget };
399
+ }
400
+
377
401
  function recordOf(value: unknown): Record<string, unknown> | null {
378
402
  return typeof value === "object" && value !== null && !Array.isArray(value)
379
403
  ? (value as Record<string, unknown>)
@@ -1333,7 +1357,7 @@ export class InProcessSupervisor implements LegionSupervisor {
1333
1357
  private requireChild(name: string): ChildRecord {
1334
1358
  const child = this.children.get(name);
1335
1359
  if (!child) {
1336
- throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
1360
+ throw unknownChildError(name);
1337
1361
  }
1338
1362
  return child;
1339
1363
  }
@@ -9,6 +9,7 @@
9
9
 
10
10
  import {
11
11
  ErrorCodes,
12
+ unknownChildError,
12
13
  SubagentError,
13
14
  type InProcessLimits,
14
15
  } from "../shared/types.ts";
@@ -231,6 +232,6 @@ export class RoutingSupervisor implements LegionSupervisor {
231
232
  this.owners.set(name, "rpc");
232
233
  return this.rpc;
233
234
  }
234
- throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
235
+ throw unknownChildError(name);
235
236
  }
236
237
  }
@@ -14,7 +14,7 @@ import { buildPiArgs, LEGION_IDENTITY_ENV_KEYS } from "../runs/args.ts";
14
14
  import { TEMP_OWNER_FILE, writeOwnerFile } from "../runs/owner.ts";
15
15
  import { checkMemoryGate, childMemoryEnv } from "./child-memory.ts";
16
16
  import { enrichFailureWithAutoDoctor } from "../extension/auto-doctor.ts";
17
- import { ErrorCodes, SubagentError } from "../shared/types.ts";
17
+ import { ErrorCodes, SubagentError, unknownChildError } from "../shared/types.ts";
18
18
  import {
19
19
  InMemoryUIProxy,
20
20
  extensionActivityToUIRequest,
@@ -605,7 +605,7 @@ export class RpcSupervisor implements LegionSupervisor {
605
605
  private requireChild(name: string): ChildRecord {
606
606
  const child = this.children.get(name);
607
607
  if (!child) {
608
- throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
608
+ throw unknownChildError(name);
609
609
  }
610
610
  return child;
611
611
  }
@@ -45,6 +45,8 @@ const TERMINAL_STATUSES: ReadonlySet<string> = new Set<string>(
45
45
  NODE_STATUSES.filter((status) => isTerminalState(status)),
46
46
  );
47
47
 
48
+ import type { PhaseMachine } from "../legion/phase-machine.ts";
49
+
48
50
  export interface TreeNodeSnapshot extends LegionNode {
49
51
  /** Snapshot from legion.db usage table (≤30s granularity). */
50
52
  tokensTotal?: number;
@@ -63,6 +65,15 @@ export interface TreeNodeSnapshot extends LegionNode {
63
65
  * that as unknown, never as `rpc`.
64
66
  */
65
67
  spawnMode?: SpawnMode;
68
+ /**
69
+ * #298: the phase machine this node runs under, when known.
70
+ *
71
+ * Only the team root's card declares one, so children inherit their ancestor's.
72
+ * Absent means the built-in four-phase pipeline — renderers should show that
73
+ * default rather than nothing, because "no machine" and "the default machine"
74
+ * are the same thing to the runtime.
75
+ */
76
+ phaseMachine?: PhaseMachine;
66
77
  }
67
78
 
68
79
  export interface TreeViewTheme {
@@ -296,6 +307,48 @@ export function createTreeView(
296
307
  return `${" ".repeat(Math.max(0, node.depth))}${isSelected ? "│" : " "} ⎿ ${detail.join(" · ")}`;
297
308
  }
298
309
 
310
+ /**
311
+ * The expanded phase machine for the selected node (#298).
312
+ *
313
+ * Before the machine became declarative this was unnecessary: the seven phases
314
+ * were fixed and an operator could hold them in their head. Now each team can
315
+ * declare its own phases, so "where is this team and what may it do next" is
316
+ * only answerable by reading the machine. The runtime refuses illegal moves and
317
+ * names the legal ones, but nothing showed the WHOLE picture — this does.
318
+ *
319
+ * Rendered only for the node that DECLARES the machine (the team root) and only
320
+ * while it is selected, so the tree does not become a wall of config.
321
+ */
322
+ function machineLines(node: TreeNodeSnapshot, isSelected: boolean): string[] {
323
+ if (!isSelected) return [];
324
+ // Only a node that DECLARES a machine shows one. Falling back to the built-in
325
+ // machine here would unfold seven phases under every selected row — a wall of
326
+ // config on a node that never configured anything, and it shifted every row's
327
+ // position (breaking scrolling and collapse).
328
+ const machine = node.phaseMachine;
329
+ if (!machine || machine.phases.length === 0) return [];
330
+ const current = node.phase;
331
+ const indent = " ".repeat(Math.max(0, node.depth)) + (isSelected ? "│" : " ");
332
+ const out: string[] = [];
333
+ out.push(`${indent} phases · current: ${safeText(current ?? "-")}`);
334
+ for (const phase of machine.phases) {
335
+ const here = phase.id === current;
336
+ const marker = here ? "●" : "○";
337
+ const timeout = phase.timeoutMs !== undefined ? ` ${Math.round(phase.timeoutMs / 1000)}s` : "";
338
+ out.push(`${indent} ${marker} ${safeText(phase.id)}${timeout}${here ? " ← now" : ""}`);
339
+ for (const rule of phase.next) {
340
+ const bits: string[] = [];
341
+ if (rule.require?.length) bits.push(`if ${rule.require.join(" & ")}`);
342
+ if (rule.actorRole) bits.push(`by ${rule.actorRole}`);
343
+ if (rule.rework) bits.push("rework");
344
+ const suffix = bits.length ? ` (${bits.join(", ")})` : "";
345
+ out.push(`${indent} → ${safeText(rule.to)}${suffix}`);
346
+ }
347
+ if (phase.next.length === 0) out.push(`${indent} (terminal)`);
348
+ }
349
+ return out;
350
+ }
351
+
299
352
  /**
300
353
  * Current-turn elapsed for the tree detail line: live while the node runs,
301
354
  * frozen at the node's terminal transition once it settles.
@@ -754,6 +807,9 @@ export function createTreeView(
754
807
  lines.push(fitLine(styleNodeLine(head, node, isSelected), contentWidth));
755
808
  if (childCount > 0 && !isExpanded) continue;
756
809
  lines.push(fitLine(styleNodeLine(rowDetail(node, isSelected), node, isSelected), contentWidth));
810
+ for (const line of machineLines(node, isSelected)) {
811
+ lines.push(fitLine(styleNodeLine(line, node, isSelected), contentWidth));
812
+ }
757
813
  }
758
814
  return lines;
759
815
  }
@@ -15,11 +15,8 @@ export interface VizTheme {
15
15
 
16
16
  export const ROLE_TOKENS: Readonly<Record<string, string>> = {
17
17
  centurion: "accent",
18
- planner: "syntaxKeyword",
19
18
  worker: "syntaxVariable",
20
19
  scout: "syntaxNumber",
21
- reviewer: "syntaxFunction",
22
- advisor: "syntaxString",
23
20
  };
24
21
 
25
22
  /** Fallback pool for roles that are not in the table (deterministic hash pick). */