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,220 @@
1
+ /**
2
+ * Which extensions a child session loads (#280).
3
+ *
4
+ * Policy has flipped. Children used to load extensions only when a role card
5
+ * opted in (`inheritExtensions: true`) or an operator set
6
+ * `PI_LEGION_CHILD_INHERIT_EXTENSIONS=1`. #43 made that the default because a
7
+ * heavy host extension (an LSP stack) cost ~1 GB per child, and at the time
8
+ * every child was a separate process.
9
+ *
10
+ * Two things changed that reasoning:
11
+ *
12
+ * - children are in-process by default now (#279), so "one more extension per
13
+ * child" no longer means another process's worth of memory
14
+ * - the opt-in list was per-role and hand-maintained, so in practice children
15
+ * silently lost host capabilities (a provider extension, a guard) that the
16
+ * role never knew to name
17
+ *
18
+ * The default is therefore "inherit everything the parent has", with two ways to
19
+ * narrow it: `excludeExtensions` (subtract specific ones) and
20
+ * `inheritExtensions: false` (load only what the card lists explicitly).
21
+ *
22
+ * Where the parent's list comes from: pi exposes no "list loaded extensions"
23
+ * API, and `pi list` reports only package DIRECTORIES. So discovery resolves
24
+ * each directory the same way pi's own loader does — `package.json`'s
25
+ * `pi.extensions`, else `index.ts`/`index.js` — and caches the result for the
26
+ * process. That covers package-shaped extensions, which is what `pi list`
27
+ * reports; single-file `--extension` arguments and builtins are not discoverable
28
+ * this way and must still be named explicitly (documented limitation, #280).
29
+ */
30
+
31
+ import * as fs from "node:fs";
32
+ import * as path from "node:path";
33
+ import { execFile } from "node:child_process";
34
+ import { promisify } from "node:util";
35
+ import type { AgentConfig } from "../shared/types.ts";
36
+
37
+ /** Env kill-switch, shared with the rpc path. Kept here to avoid a cycle. */
38
+ const CHILD_INHERIT_EXTENSIONS_ENV = "PI_LEGION_CHILD_INHERIT_EXTENSIONS";
39
+
40
+ /**
41
+ * Whether a child loads the host's discovered extensions (#280).
42
+ *
43
+ * Default TRUE: a child starts from everything the parent has and narrows from
44
+ * there. `inheritExtensions: false` on the card, or the env var, loads only the
45
+ * card's own list. The env var accepts either polarity so an operator can flip
46
+ * the whole tree without editing every card.
47
+ *
48
+ * Duplicated in `args.ts` (which re-exports it for the rpc argument builder)
49
+ * rather than imported, because `args.ts` already imports this module.
50
+ */
51
+ export function childInheritsExtensions(
52
+ agent: Pick<AgentConfig, "inheritExtensions">,
53
+ env: NodeJS.ProcessEnv = process.env,
54
+ ): boolean {
55
+ if (agent.inheritExtensions === false) return false;
56
+ const raw = env[CHILD_INHERIT_EXTENSIONS_ENV]?.trim().toLowerCase();
57
+ if (raw === "0" || raw === "false" || raw === "off" || raw === "no") return false;
58
+ if (raw === "1" || raw === "true" || raw === "on" || raw === "yes") return true;
59
+ return true;
60
+ }
61
+
62
+ const execFileAsync = promisify(execFile);
63
+
64
+ /** Host-discovered package extension paths, resolved once per process. */
65
+ let discovered: string[] | undefined;
66
+ /** In-flight discovery, so concurrent launches share one `pi list`. */
67
+ let discovery: Promise<string[]> | undefined;
68
+
69
+ /** Reset the cache. Test seam only. */
70
+ export function resetExtensionDiscoveryCache(): void {
71
+ discovered = undefined;
72
+ discovery = undefined;
73
+ }
74
+
75
+ /**
76
+ * Resolve a package directory to its extension entry points, exactly like pi's
77
+ * own loader: `package.json`'s `pi.extensions` first, then `index.ts`/`index.js`.
78
+ *
79
+ * A directory with neither is not an extension package (a theme pack, a skill
80
+ * bundle) and contributes nothing.
81
+ */
82
+ export function resolveExtensionEntries(dir: string): string[] {
83
+ const manifestPath = path.join(dir, "package.json");
84
+ try {
85
+ if (fs.existsSync(manifestPath)) {
86
+ const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as {
87
+ pi?: { extensions?: unknown };
88
+ };
89
+ const declared = manifest.pi?.extensions;
90
+ if (Array.isArray(declared)) {
91
+ const resolved = declared
92
+ .filter((entry): entry is string => typeof entry === "string" && entry.length > 0)
93
+ .map((entry) => path.resolve(dir, entry))
94
+ .filter((entry) => fs.existsSync(entry));
95
+ if (resolved.length > 0) return resolved;
96
+ }
97
+ }
98
+ } catch {
99
+ // Unreadable/invalid manifest: fall through to the index-file convention.
100
+ }
101
+ for (const candidate of ["index.ts", "index.js"]) {
102
+ const entry = path.join(dir, candidate);
103
+ if (fs.existsSync(entry)) return [entry];
104
+ }
105
+ return [];
106
+ }
107
+
108
+ /** Parse `pi list` output into the package directories it reports. */
109
+ export function parsePiList(output: string): string[] {
110
+ const dirs: string[] = [];
111
+ for (const raw of output.split("\n")) {
112
+ const line = raw.trim();
113
+ // Package dirs are the indented absolute paths; headers are `User packages:`
114
+ // and `npm:name@version` lines carry no leading slash.
115
+ if (!line.startsWith("/")) continue;
116
+ dirs.push(line);
117
+ }
118
+ return dirs;
119
+ }
120
+
121
+ /**
122
+ * Ask pi which packages are installed and resolve them to extension files.
123
+ *
124
+ * Never throws: a host without `pi` on PATH, or a `pi list` failure, degrades to
125
+ * "no discovered extensions" (children still get their explicit list plus the
126
+ * child-guard). Failure to discover must not fail a launch.
127
+ */
128
+ export async function discoverHostExtensions(env: NodeJS.ProcessEnv = process.env): Promise<string[]> {
129
+ if (discovered) return discovered;
130
+ discovery ??= (async () => {
131
+ let dirs: string[] = [];
132
+ try {
133
+ const { stdout } = await execFileAsync("pi", ["list"], {
134
+ env,
135
+ timeout: 15_000,
136
+ maxBuffer: 4 * 1024 * 1024,
137
+ });
138
+ dirs = parsePiList(stdout);
139
+ } catch {
140
+ dirs = [];
141
+ }
142
+ const entries = dirs.flatMap((dir) => resolveExtensionEntries(dir));
143
+ const seen = new Set<string>();
144
+ discovered = entries.filter((entry) => {
145
+ const key = path.resolve(entry);
146
+ if (seen.has(key)) return false;
147
+ seen.add(key);
148
+ return true;
149
+ });
150
+ return discovered;
151
+ })();
152
+ return discovery;
153
+ }
154
+
155
+ /** Synchronous read of whatever discovery has already produced. */
156
+ export function discoveredHostExtensions(): string[] | undefined {
157
+ return discovered;
158
+ }
159
+
160
+ /**
161
+ * Does this extension match an `excludeExtensions` entry?
162
+ *
163
+ * Both spellings are accepted because they answer different questions and both
164
+ * are natural to write:
165
+ *
166
+ * - a PATH (`/abs/.../index.ts`, `./relative`, `~/...`) compares resolved
167
+ * paths, so an exact file can be excluded
168
+ * - a NAME (`pi-lens`, `pi-any-endpoint`) compares against the containing
169
+ * package directory name, so a package can be excluded without knowing its
170
+ * entry layout
171
+ *
172
+ * A bare name never matches by path, and a path never matches by name, so the
173
+ * two cannot interfere.
174
+ */
175
+ export function matchesExcludedExtension(extension: string, exclude: string): boolean {
176
+ const target = exclude.trim();
177
+ if (!target) return false;
178
+ const isPathLike = target.startsWith("/") || target.startsWith("./") || target.startsWith("../") || target.startsWith("~");
179
+ if (isPathLike) {
180
+ const expanded = target.startsWith("~") ? path.join(process.env.HOME ?? "", target.slice(1)) : target;
181
+ return path.resolve(extension) === path.resolve(expanded);
182
+ }
183
+ // Name form: match the package directory that contains the entry file, or the
184
+ // entry file's own basename for a loose `foo.ts`.
185
+ const ext = extension.trim();
186
+ if (ext === target) return true;
187
+ const parts = path.resolve(ext).split(path.sep);
188
+ // `.../node_modules/<name>/...` — the package dir is the segment after node_modules.
189
+ const nodeModulesAt = parts.lastIndexOf("node_modules");
190
+ if (nodeModulesAt >= 0 && parts[nodeModulesAt + 1] === target) return true;
191
+ // `.../<name>/extensions/index.ts` or `.../<name>/index.ts`.
192
+ const file = parts.at(-1) ?? "";
193
+ const dir = parts.at(-2) ?? "";
194
+ if (dir === target) return true;
195
+ if (file === `${target}.ts` || file === `${target}.js`) return true;
196
+ return false;
197
+ }
198
+
199
+ /**
200
+ * The extensions a child should load explicitly.
201
+ *
202
+ * `inherit: false` (role card opted out) loads ONLY the card's own list. The
203
+ * default additionally carries every discovered host extension minus
204
+ * `excludeExtensions`. The child-guard is appended by the caller and is never
205
+ * subject to this policy — a child that skips it would lose the prompt/format
206
+ * contract regardless of what the card asked for.
207
+ */
208
+ export function inheritedExtensions(
209
+ agent: Pick<AgentConfig, "inheritExtensions" | "excludeExtensions">,
210
+ host: readonly string[],
211
+ env: NodeJS.ProcessEnv = process.env,
212
+ ): string[] {
213
+ // `inheritExtensions: false` (card) or the env kill-switch both mean "load
214
+ // only what the card names". Checked here rather than at the call sites so
215
+ // rpc and in-process cannot drift apart.
216
+ if (!childInheritsExtensions(agent, env)) return [];
217
+ const excluded = agent.excludeExtensions ?? [];
218
+ if (excluded.length === 0) return [...host];
219
+ return host.filter((ext) => !excluded.some((pattern) => matchesExcludedExtension(ext, pattern)));
220
+ }
@@ -20,7 +20,7 @@ import { appendEvent } from "../legion/events.ts";
20
20
  import { checkLaunchBudget, withLaunchBudget, type LegionBudgetLimits } from "../legion/budget.ts";
21
21
  import { getChildByName, getNode, insertNode, nodeIdForChild, sanitizeNodeSlug, type LegionNode, updateNode } from "../legion/nodes.ts";
22
22
  import { upsertUsage } from "../legion/usage.ts";
23
- import { evaluatePhaseTransition, isLegionPhase, isTerminalPhase } from "../legion/state-machine.ts";
23
+ import { evaluatePhaseTransition, isTerminalPhase } from "../legion/state-machine.ts";
24
24
  import { CHILD_ACCEPTANCE_ROLE_ENV, CHILD_ROLE_ENV } from "../extension/child-guard.ts";
25
25
  import {
26
26
  ALLOW_NESTED_ENV,
@@ -46,6 +46,7 @@ import {
46
46
  type ChildRecord,
47
47
  DEFAULTS,
48
48
  ErrorCodes,
49
+ unknownChildError,
49
50
  type Execution,
50
51
  type Handle,
51
52
  MAX_NESTED_PATH_ENTRIES,
@@ -74,7 +75,6 @@ import { type ChildLaunchContext, currentChildContext, runInChildContext } from
74
75
  import { inProcessDepth, runAtAbsoluteDepth } from "../supervisor/inprocess-depth.ts";
75
76
  import { subscribeInProcessSlotReleases } from "../supervisor/routing-supervisor.ts";
76
77
  import type { LegionSupervisor, SettleResult, SpawnInput } from "../supervisor/types.ts";
77
- import { isInProcessSpawn, resolveSpawnMode } from "../supervisor/spawn-mode.ts";
78
78
  import type { PendingUIRequest, UIProxy } from "../supervisor/ui-proxy.ts";
79
79
  import { applyVerification, type VerifyRunner } from "./acceptance.ts";
80
80
  import {
@@ -413,6 +413,7 @@ export class Orchestrator {
413
413
  private readonly onLaunchQueueNotice?: (line: string) => void;
414
414
  private depthWarningEmitted = false;
415
415
  private worktreeDeniedWarningEmitted = false;
416
+ private spawnModeDeniedWarningEmitted = false;
416
417
  private spawned = 0;
417
418
  private readonly children = new Map<string, ChildRecord>();
418
419
  private readonly nameCounter = new Map<string, number>();
@@ -534,7 +535,7 @@ export class Orchestrator {
534
535
  return { name, nodeId: node.id, sessionFile: node.sessionFile, ownerToken: `legion-${node.id}`, state: "retired", spawnedAt: new Date(node.createdAt).toISOString(), agent: node.role, kind: node.kind as AgentConfig["kind"], ...(node.model ? { model: node.model } : {}), ...(node.worktreePath ? { worktreePath: node.worktreePath } : {}) };
535
536
  }
536
537
 
537
- private reserveNode(input: { nodeId: string; name: string; agent: AgentConfig; task: string; sessionFile: string; runId?: string; team?: string; worktreePath?: string; model?: string; utility?: boolean }): LegionNode | null {
538
+ private reserveNode(input: { nodeId: string; name: string; agent: AgentConfig; task: string; sessionFile: string; runId?: string; team?: string; worktreePath?: string; model?: string; utility?: boolean; inProcess?: boolean }): LegionNode | null {
538
539
  const legion = this.legion;
539
540
  if (!legion) return null;
540
541
  const parent = getNode(legion.db, legion.nodeId);
@@ -559,17 +560,22 @@ export class Orchestrator {
559
560
  const maxChildren = legion.settings?.maxChildrenPerNode ?? 8;
560
561
  const activeReservation = previous && (previous.status === "starting" || previous.status === "running") ? 1 : 0;
561
562
  // In-process children use subagents.inprocess.* only — do not spend RPC legion.* slots (#197).
562
- const limits: LegionBudgetLimits = isInProcessSpawn(input.agent)
563
- ? {
564
- maxDepth: MAX_NESTED_PATH_ENTRIES,
565
- maxChildrenPerNode: Number.MAX_SAFE_INTEGER,
566
- maxActiveNodes: Number.MAX_SAFE_INTEGER,
567
- }
568
- : {
569
- maxDepth: depthCeiling,
570
- maxChildrenPerNode: maxChildren,
571
- maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation,
572
- };
563
+ //
564
+ // #279: keyed on the ARBITRATED backend, not the role card's spelling. A role
565
+ // that pins `spawnMode: rpc` is demoted to in-process before this runs, and
566
+ // reading the raw card again would charge the rpc buckets for a launch that
567
+ // never runs there (the two backends have separate limits by design).
568
+ // #279: in-process launches are budgeted again. #197 granted them unlimited
569
+ // ledger headroom because rpc was the default and only rpc spent these slots.
570
+ // Now that rpc is reserved for centurion, every other role runs
571
+ // in-process — so "unlimited" would mean "avoid rpc, escape the caps", and a
572
+ // worker could nest without bound. They still get the `inprocess.*` pools
573
+ // enforced inside the in-process supervisor; this restores the ledger floor.
574
+ const limits: LegionBudgetLimits = {
575
+ maxDepth: depthCeiling,
576
+ maxChildrenPerNode: maxChildren,
577
+ maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation,
578
+ };
573
579
  const gate = withLaunchBudget(legion.db, { parentId: legion.nodeId, depth: parent.depth + 1, nodeId: input.nodeId }, () => {
574
580
  if (previous) {
575
581
  updateNode(legion.db, input.nodeId, { status: "starting", sessionFile: input.sessionFile, worktreePath: input.worktreePath ?? previous.worktreePath, model: input.model ?? previous.model, team: team && team !== DEFAULT_TEAM ? team : previous.team }, this.now);
@@ -664,7 +670,11 @@ export class Orchestrator {
664
670
  private abortLegionPhase(nodeId: string): void {
665
671
  if (!this.legion) return;
666
672
  const node = getNode(this.legion.db, nodeId);
667
- if (!node || !isLegionPhase(node.phase) || isTerminalPhase(node.phase)) return;
673
+ // #298: a declared machine may name phases the built-in union does not know,
674
+ // and an ABORT must never be blocked by that — a team that cannot be stopped
675
+ // is a safety hole. `isTerminalPhase` still covers the built-in names; a
676
+ // custom name resolves through the machine when one is attached.
677
+ if (!node || !node.phase || isTerminalPhase(node.phase)) return;
668
678
  const decision = evaluatePhaseTransition({
669
679
  from: node.phase,
670
680
  to: "aborted",
@@ -735,6 +745,32 @@ export class Orchestrator {
735
745
  this.onBudgetRefused?.(event);
736
746
  }
737
747
 
748
+ /**
749
+ * #279: only `name === "centurion"` may run on the rpc backend.
750
+ *
751
+ * `warnWorktreeDenied` above already forces `worktree: false` for everyone
752
+ * else, but that guard keys on the worktree REQUEST — a role card that pins
753
+ * `spawnMode: rpc` explicitly never consults `resolveSpawnMode`, so it slipped
754
+ * through and got a separate process (the exact isolation the worktree rule
755
+ * exists to reserve). This closes that bypass. Like the worktree rule it warns
756
+ * once per run and demotes, never throws: a stale role card must not turn every
757
+ * launch in the tree into a hard failure.
758
+ */
759
+ private warnSpawnModeDenied(agentName: string): void {
760
+ if (this.spawnModeDeniedWarningEmitted) return;
761
+ this.spawnModeDeniedWarningEmitted = true;
762
+ const event: BudgetRefusedEvent = {
763
+ type: "budget_refused",
764
+ reason: "spawn_mode_denied_non_centurion",
765
+ agent: agentName,
766
+ };
767
+ console.warn(
768
+ `[pi-legion] rpc denied for non-centurion role '${agentName}'; forced spawnMode: inprocess. ` +
769
+ `Fix the role card (remove spawnMode: rpc) or dispatch a centurion when you need an isolated process.`,
770
+ );
771
+ this.onBudgetRefused?.(event);
772
+ }
773
+
738
774
  async launch(
739
775
  input: LaunchInput,
740
776
  /**
@@ -772,6 +808,24 @@ export class Orchestrator {
772
808
  const tempDir = this.runDir;
773
809
  const parentRole = this.legion ? getNode(this.legion.db, this.legion.nodeId)?.role : undefined;
774
810
  const isCenturion = input.agent.name === "centurion";
811
+ // #281: only the ROOT session may dispatch a centurion.
812
+ //
813
+ // Every other guard here keys on the CHILD's role, so without this a worker
814
+ // could dispatch a centurion and silently acquire worktree + rpc isolation
815
+ // (measured: `subagent({agent:"centurion"})` from a worker launched on rpc
816
+ // with a fresh worktree). A centurion exists to own an isolated tree and its
817
+ // own team; nesting one inside another agent's turn produces a second
818
+ // command chain the root cannot collect, so it is refused rather than
819
+ // demoted — a demoted centurion can neither create a worktree nor do its job.
820
+ //
821
+ // Refused BEFORE any worktree/dir is created, so a rejected dispatch leaves
822
+ // no artifacts behind.
823
+ if (isCenturion && this.legion && this.legion.nodeId !== "root") {
824
+ throw new SubagentError(
825
+ `only the root session may dispatch a centurion; '${parentRole ?? this.legion.nodeId}' at '${this.legion.nodeId}' cannot`,
826
+ ErrorCodes.BUDGET_EXCEEDED,
827
+ );
828
+ }
775
829
  // #214 D4: only centurion may hold worktree. Legion path still forces
776
830
  // centurion→true and centurion-parent→member false; non-centurion
777
831
  // requests from any source are demoted below (D1: warn, never throw).
@@ -794,19 +848,19 @@ export class Orchestrator {
794
848
  this.warnWorktreeDenied(input.agent.name);
795
849
  worktree = false;
796
850
  }
797
- // Spawn-mode arbitration (contract D2). `resolveSpawnMode` only reports the
798
- // configured intent; the launch context decides whether an OMITTED mode can
799
- // actually run in-process. An omitted mode falls back to rpc when this
800
- // launch needs worktree isolation (a hard requirement of the in-process
801
- // backend). An explicit value is never downgraded (invariant I6) — a bad
802
- // explicit combination still throws below.
803
- // `kind !== "pi"` is NOT re-tested here: the early guard above (before this
804
- // arbitration) already refuses it, so such a clause would be dead code.
805
- const explicitMode = input.agent.spawnMode !== undefined;
806
- const mode: SpawnMode =
807
- !explicitMode && worktree === true
808
- ? "rpc"
809
- : resolveSpawnMode(input.agent);
851
+ // Spawn-mode arbitration. Role cards no longer carry a `spawnMode` field:
852
+ // the backend is a property of the LAUNCH, not a role, so a card cannot pin
853
+ // itself to a process model. rpc exists for exactly one reason — it is the
854
+ // only backend that can host a worktree child — so the rule collapses to:
855
+ //
856
+ // worktree isolation ⇒ rpc; everything else ⇒ in-process.
857
+ //
858
+ // A centurion is the only role allowed to hold a worktree (#214), so it is
859
+ // also the only role that reaches rpc (#279). Nothing to deny here anymore:
860
+ // a non-centurion cannot request worktree in the first place (the guard
861
+ // above forces it false), and there is no card field left to smuggle a
862
+ // backend request through.
863
+ const mode: SpawnMode = worktree === true ? "rpc" : "inprocess";
810
864
  const inProcess = mode === "inprocess";
811
865
  // Downstream must see the arbitrated result, otherwise RoutingSupervisor
812
866
  // re-resolves the omitted field to `inprocess` on its own and throws
@@ -822,12 +876,17 @@ export class Orchestrator {
822
876
  // The `&& worktree` short-circuit keeps the rpc path returning the
823
877
  // original object (invariant I3: zero diff on the RPC backend).
824
878
  // reserveNode() and SpawnInput.agent below both receive this clone.
825
- const agent: AgentConfig = mode === input.agent.spawnMode && worktree
826
- ? input.agent
827
- : { ...input.agent, spawnMode: mode, ...(worktree ? {} : { worktree: false }) };
879
+ const agent: AgentConfig = { ...input.agent, spawnMode: mode, ...(worktree ? {} : { worktree: false }) };
828
880
  // A utility dispatch is a hard leaf, not a nested command-chain launch.
829
- // In-process children use subagents.inprocess.* budgets (never RPC keys).
830
- if (!input.utilityDispatch && !inProcess) this.assertWithinBudgets(Boolean(previous));
881
+ //
882
+ // #279: this check now covers EVERY backend. It used to be `!inProcess`,
883
+ // because #197 gave in-process its own `subagents.inprocess.*` buckets. But
884
+ // rpc is reserved for centurion, so every other role now runs in-process —
885
+ // leaving them unchecked here would mean "avoid rpc, escape the depth and
886
+ // per-session spawn ceilings", and a worker could nest without bound.
887
+ // The in-process supervisor still enforces its own `inprocess.*` limits;
888
+ // this is an additional floor, not a replacement.
889
+ if (!input.utilityDispatch) this.assertWithinBudgets(Boolean(previous));
831
890
  if (this.supervisor.isAlive(name)) throw new SubagentError(`child is already alive: ${name}`, ErrorCodes.NAME_TAKEN);
832
891
  // D4: the name-occupancy check must cover QUEUED records too. `previous`
833
892
  // deliberately ignores them (D3-a: its placeholder session path is not a resume
@@ -941,7 +1000,7 @@ export class Orchestrator {
941
1000
  preCreateSessionFile(sessionFile);
942
1001
  if (this.legion && nodeId) {
943
1002
  const reservationRunId = createdRunId ?? (previous ? ledgerPrevious?.runId : undefined) ?? this.legion.runId;
944
- reservedNode = this.reserveNode({ nodeId, name, agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models[0], utility: Boolean(input.utilityDispatch && input.agent.utility) });
1003
+ reservedNode = this.reserveNode({ nodeId, name, agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models[0], utility: Boolean(input.utilityDispatch && input.agent.utility), inProcess });
945
1004
  reserved = true;
946
1005
  parentReservationCreated = await this.persistParentReservation({ nodeId, name, agent: input.agent, sessionFile, ...(models[0] ? { model: models[0] } : {}), ...(worktreePath ? { worktreePath } : {}) });
947
1006
  }
@@ -994,6 +1053,17 @@ export class Orchestrator {
994
1053
  allowNested: input.agent.allowNestedSubagents === true && !input.agent.utility,
995
1054
  utility: Boolean(input.utilityDispatch && input.agent.utility),
996
1055
  spawnMode: "inprocess" as const,
1056
+ // #295: the in-process child shares the HOST's process.env, so
1057
+ // `env` below never reaches its guard. Carry the budget here,
1058
+ // where the child context is the only channel that survives.
1059
+ ...(() => {
1060
+ const budget = {
1061
+ ...(agent.toolBudget?.maxToolCalls !== undefined ? { maxToolCalls: agent.toolBudget.maxToolCalls } : {}),
1062
+ ...(agent.turnBudget?.maxTurns !== undefined ? { maxTurns: agent.turnBudget.maxTurns } : {}),
1063
+ ...(agent.toolTimeoutMs !== undefined ? { toolTimeoutMs: agent.toolTimeoutMs } : {}),
1064
+ };
1065
+ return Object.keys(budget).length > 0 ? { budget } : {};
1066
+ })(),
997
1067
  },
998
1068
  }
999
1069
  : {}),
@@ -1137,14 +1207,14 @@ export class Orchestrator {
1137
1207
  * skips the *queue*, never `assertWithinLimits` / `withLaunchBudget` (I-O1). A
1138
1208
  * launch that still loses the real gate is re-queued instead of failing (D2-c).
1139
1209
  */
1140
- private probeAdmission(name: string, ctx: AdmissionProbeContext): AdmissionVerdict {
1141
- if (ctx.inProcess) {
1142
- const probe = inProcessProbeOf(this.supervisor);
1143
- // No readable counts (a test double) → nothing to probe.
1144
- if (!probe) return { admitted: true };
1145
- const counts = probe.admissionCounts(name);
1146
- return evaluateInProcessAdmission(counts, this.inflightFor(counts.parentKey, ctx));
1147
- }
1210
+
1211
+ /**
1212
+ * The legion ledger gate, shared by the rpc and in-process admission paths
1213
+ * (#279). Read-only (`checkLaunchBudget`), never `withLaunchBudget` — a probe
1214
+ * must not insert a `starting` row (R3/F10) and must not emit
1215
+ * `budget_refused`, which belongs to `reserveNode` (D1-b).
1216
+ */
1217
+ private probeLedgerAdmission(name: string, ctx: AdmissionProbeContext): ReturnType<Orchestrator["probeAdmission"]> {
1148
1218
  // rpc/legion: the ledger gate. Read-only (`checkLaunchBudget`), never
1149
1219
  // `withLaunchBudget` — a probe must not insert a `starting` row (R3/F10) and
1150
1220
  // must not emit `budget_refused`, which belongs to `reserveNode` (D1-b).
@@ -1202,10 +1272,33 @@ export class Orchestrator {
1202
1272
  }
1203
1273
  return { admitted: true };
1204
1274
  }
1205
- // `max_depth` / `parent_not_found`: permanent, never queued (D1).
1275
+
1206
1276
  return { admitted: true };
1207
1277
  }
1208
1278
 
1279
+ private probeAdmission(name: string, ctx: AdmissionProbeContext): AdmissionVerdict {
1280
+ if (ctx.inProcess) {
1281
+ // #279: the ledger floor applies to in-process launches too. It used to be
1282
+ // skipped entirely (#197 gave in-process unlimited ledger headroom), but
1283
+ // rpc is now reserved for centurion — so "skip the ledger" would
1284
+ // mean every non-centurion role escapes `maxChildrenPerNode` /
1285
+ // `maxActiveNodes`. `reserveNode` already charges these slots, so without
1286
+ // this probe the launch is REFUSED there after admission was granted here.
1287
+ //
1288
+ // Two gates now apply and the stricter wins: this ledger check (fanout /
1289
+ // active / depth) plus the `inprocess.*` pools probed below.
1290
+ const ledgerVerdict = this.probeLedgerAdmission(name, ctx);
1291
+ if (ledgerVerdict.admitted !== true) return ledgerVerdict;
1292
+ const probe = inProcessProbeOf(this.supervisor);
1293
+ // No readable counts (a test double) → nothing to probe.
1294
+ if (!probe) return { admitted: true };
1295
+ const counts = probe.admissionCounts(name);
1296
+ return evaluateInProcessAdmission(counts, this.inflightFor(counts.parentKey, ctx));
1297
+ }
1298
+ return this.probeLedgerAdmission(name, ctx);
1299
+
1300
+ }
1301
+
1209
1302
  /**
1210
1303
  * The process-level queue for this run directory (§13.6 / I-O6).
1211
1304
  *
@@ -1955,7 +2048,7 @@ export class Orchestrator {
1955
2048
 
1956
2049
  private requireChild(name: string): ChildRecord {
1957
2050
  const child = this.children.get(name);
1958
- if (!child) throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
2051
+ if (!child) throw unknownChildError(name);
1959
2052
  return child;
1960
2053
  }
1961
2054
 
@@ -0,0 +1,137 @@
1
+ /**
2
+ * Renewal progress signal (subagent-renewal contract v1, W1 / D2 + D2-a + D8).
3
+ *
4
+ * Answers exactly one question: *since the last renewal baseline, did the child
5
+ * produce observable output?* Only output signals count (session JSONL rows and
6
+ * worktree file changes) — process liveness, CPU time and token spend are
7
+ * explicitly excluded (§7-3: they also grow while a child loops on failure).
8
+ *
9
+ * Measured session shape (`.pi-subagents/runs/<run>/<child>.jsonl`): every row
10
+ * is `{"type":"message","id","parentId","timestamp","message":{"role",...}}`
11
+ * where `message.role` is `assistant` / `toolResult` / `user` / `system`.
12
+ * Top-level `type` is `message`, so the row kind lives in `message.role`; a
13
+ * legacy flat `{"type":"toolResult"}` row is accepted too.
14
+ */
15
+
16
+ import * as fs from "node:fs";
17
+
18
+ /** A renewal point: when it was taken plus the session line count then (D8). */
19
+ export interface ProgressBaseline {
20
+ /** Unix ms when this baseline was taken (D8). */
21
+ readonly at: number;
22
+ /** Session JSONL line count at baseline time. */
23
+ readonly lines: number;
24
+ }
25
+
26
+ export interface ProgressMeasure {
27
+ /** New `toolResult` rows since the baseline (strongest evidence — a tool returned). */
28
+ readonly toolResults: number;
29
+ /** New assistant messages since the baseline. */
30
+ readonly assistantMessages: number;
31
+ /** Files created/modified in the worktree since the baseline, when measurable. */
32
+ readonly filesChanged: number | undefined;
33
+ /** D2-a: does this count as "real progress"? */
34
+ readonly progressed: boolean;
35
+ }
36
+
37
+ /** D2-a thresholds, exported so tests and docs cannot drift. */
38
+ export const PROGRESS_MIN_TOOL_RESULTS = 3;
39
+ export const PROGRESS_MIN_FILES_CHANGED = 1;
40
+
41
+ /**
42
+ * Default line reader: the file's raw lines, or `undefined` when unreadable.
43
+ * Never throws — a child that was killed mid-write leaves a torn final line,
44
+ * and a missing file is a normal "nothing to measure" state.
45
+ */
46
+ export function readSessionLines(file: string): string[] | undefined {
47
+ let text: string;
48
+ try {
49
+ text = fs.readFileSync(file, "utf8");
50
+ } catch {
51
+ return undefined;
52
+ }
53
+ return splitLines(text);
54
+ }
55
+
56
+ /**
57
+ * Split on `\n`, dropping the phantom element a trailing newline produces so
58
+ * the count matches "number of lines written". A torn tail without a trailing
59
+ * newline is kept (the parser skips it).
60
+ */
61
+ function splitLines(text: string): string[] {
62
+ const lines = text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
63
+ if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
64
+ return lines;
65
+ }
66
+
67
+ /** Row kind, or `undefined` for non-message / malformed rows. */
68
+ function rowKind(line: string): "assistant" | "toolResult" | undefined {
69
+ const trimmed = line.trim();
70
+ if (!trimmed) return undefined;
71
+ let decoded: unknown;
72
+ try {
73
+ decoded = JSON.parse(trimmed);
74
+ } catch {
75
+ // Torn line, or a non-JSON header: skip, never throw.
76
+ return undefined;
77
+ }
78
+ if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded)) return undefined;
79
+ const event = decoded as Record<string, unknown>;
80
+ // Measured shape: {type:"message", message:{role}}.
81
+ const message = event.message;
82
+ if (message && typeof message === "object" && !Array.isArray(message)) {
83
+ const role = (message as Record<string, unknown>).role;
84
+ if (role === "assistant") return "assistant";
85
+ if (role === "toolResult") return "toolResult";
86
+ }
87
+ // Legacy flat shape: {type:"toolResult"} / {type:"assistant"}.
88
+ if (event.type === "assistant") return "assistant";
89
+ if (event.type === "toolResult") return "toolResult";
90
+ return undefined;
91
+ }
92
+
93
+ /** Non-negative integer, or `undefined` when the counter is not measurable. */
94
+ function normalizeCount(value: number | undefined): number | undefined {
95
+ if (value === undefined || !Number.isFinite(value)) return undefined;
96
+ return Math.max(0, Math.floor(value));
97
+ }
98
+
99
+ /**
100
+ * Measure progress since `baseline`. Rows at or before `baseline.lines` are
101
+ * history and are never counted (D8).
102
+ *
103
+ * `progressed` follows D2-a exactly:
104
+ * `toolResults >= PROGRESS_MIN_TOOL_RESULTS || filesChanged >= PROGRESS_MIN_FILES_CHANGED`,
105
+ * with an unmeasurable `filesChanged` dropping out of the comparison.
106
+ */
107
+ export function measureProgress(input: {
108
+ sessionFile: string;
109
+ baseline: ProgressBaseline;
110
+ /** Injectable for tests: returns the session file's raw lines, or undefined when unreadable. */
111
+ readLines?: (file: string) => string[] | undefined;
112
+ /** Injectable: count of changed files in the worktree, or undefined when not measurable. */
113
+ countFilesChanged?: () => number | undefined;
114
+ }): ProgressMeasure {
115
+ const lines = (input.readLines ?? readSessionLines)(input.sessionFile);
116
+ const filesChanged = normalizeCount(input.countFilesChanged?.());
117
+ if (!lines) return { toolResults: 0, assistantMessages: 0, filesChanged, progressed: hasFileProgress(filesChanged) };
118
+
119
+ // Baseline beyond the current file (truncated/rotated): nothing is new.
120
+ const start = Math.max(0, Math.min(normalizeCount(input.baseline.lines) ?? 0, lines.length));
121
+ let toolResults = 0;
122
+ let assistantMessages = 0;
123
+ for (let i = start; i < lines.length; i += 1) {
124
+ const kind = rowKind(lines[i] ?? "");
125
+ if (kind === "toolResult") toolResults += 1;
126
+ else if (kind === "assistant") assistantMessages += 1;
127
+ }
128
+
129
+ const progressed = toolResults >= PROGRESS_MIN_TOOL_RESULTS || hasFileProgress(filesChanged);
130
+
131
+ return { toolResults, assistantMessages, filesChanged, progressed };
132
+ }
133
+
134
+ /** D2-a's file half; an unmeasurable count never counts as progress. */
135
+ function hasFileProgress(filesChanged: number | undefined): boolean {
136
+ return filesChanged !== undefined && filesChanged >= PROGRESS_MIN_FILES_CHANGED;
137
+ }