pi-legion 0.16.0 → 2.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 (89) hide show
  1. package/CONTRIBUTING.md +58 -0
  2. package/README.md +313 -640
  3. package/agents/advisor.md +7 -5
  4. package/agents/centurion.md +53 -0
  5. package/agents/designer.md +33 -33
  6. package/agents/planner.md +1 -2
  7. package/agents/prototype.md +2 -2
  8. package/agents/reviewer.md +67 -31
  9. package/agents/scout.md +6 -2
  10. package/agents/worker.md +12 -3
  11. package/docs/contracts/esc-abort-v1.md +131 -0
  12. package/docs/contracts/esc-cascade-v2.md +100 -0
  13. package/docs/design.md +44 -25
  14. package/docs/legion-v2-contract.md +461 -0
  15. package/docs/legion-v2-delivery.md +62 -0
  16. package/docs/retire-hardening-contract.md +125 -0
  17. package/docs/subagents-teams.md +76 -0
  18. package/docs/tui-viewer-contract.md +276 -0
  19. package/docs/vexillatio-contract.md +162 -0
  20. package/index.ts +1462 -286
  21. package/package.json +12 -9
  22. package/skills/pi-legion/SKILL.md +74 -96
  23. package/src/agents/agents.ts +6 -11
  24. package/src/agents/overrides.ts +2 -1
  25. package/src/agents/paths.ts +1 -1
  26. package/src/agents/settings.ts +268 -20
  27. package/src/api.ts +47 -48
  28. package/src/{herdr → backends/legacy}/client.ts +14 -69
  29. package/src/{shared → backends/legacy}/cursor-chat.ts +2 -2
  30. package/src/{herdr → backends/legacy}/runner.ts +22 -9
  31. package/src/backends/legacy/types.ts +138 -0
  32. package/src/extension/auto-doctor.ts +144 -0
  33. package/src/extension/budget.ts +2 -2
  34. package/src/extension/child-guard.ts +214 -201
  35. package/src/extension/event-bus.ts +263 -0
  36. package/src/extension/legion-commands.ts +719 -0
  37. package/src/extension/legion-doctor.ts +888 -0
  38. package/src/extension/legion-stop.ts +150 -0
  39. package/src/extension/legion-tools.ts +816 -0
  40. package/src/extension/notify.ts +24 -19
  41. package/src/extension/playbook.ts +20 -89
  42. package/src/extension/recycle.ts +2 -7
  43. package/src/extension/runtime.ts +655 -105
  44. package/src/extension/scout-guard.ts +483 -0
  45. package/src/extension/slash.ts +89 -438
  46. package/src/extension/spawn-hints.ts +79 -0
  47. package/src/extension/summary.ts +17 -58
  48. package/src/legion/budget.ts +165 -0
  49. package/src/legion/db.ts +242 -0
  50. package/src/legion/events.ts +150 -0
  51. package/src/legion/mail.ts +412 -0
  52. package/src/legion/nodes.ts +461 -0
  53. package/src/legion/rebuild.ts +533 -0
  54. package/src/legion/state-machine.ts +313 -0
  55. package/src/legion/usage.ts +101 -0
  56. package/src/runs/acceptance.ts +82 -25
  57. package/src/runs/args.ts +51 -5
  58. package/src/runs/hygiene.ts +335 -0
  59. package/src/runs/orchestrator.ts +790 -1683
  60. package/src/runs/owner.ts +61 -0
  61. package/src/runs/provision.ts +135 -0
  62. package/src/runs/store.ts +44 -17
  63. package/src/runs/verify-queue.ts +195 -0
  64. package/src/shared/name.ts +29 -0
  65. package/src/shared/output-cap.ts +57 -0
  66. package/src/shared/progress.ts +57 -135
  67. package/src/shared/session.ts +243 -171
  68. package/src/shared/types.ts +107 -208
  69. package/src/supervisor/child-memory.ts +140 -0
  70. package/src/supervisor/proc-tree.ts +103 -0
  71. package/src/supervisor/rpc-supervisor.ts +1033 -0
  72. package/src/supervisor/types.ts +153 -0
  73. package/src/supervisor/ui-proxy.ts +226 -0
  74. package/src/tui/chat-items.ts +330 -0
  75. package/src/tui/live-overlay.ts +874 -0
  76. package/src/tui/status.ts +553 -27
  77. package/src/tui/tree-view.ts +808 -0
  78. package/src/tui/viz/canvas.ts +119 -0
  79. package/src/tui/viz/layout.ts +111 -0
  80. package/src/tui/viz/model.ts +123 -0
  81. package/src/tui/viz/palette.ts +188 -0
  82. package/src/tui/viz/panels.ts +530 -0
  83. package/src/tui/viz/railway.ts +313 -0
  84. package/src/tui/viz/rate.ts +211 -0
  85. package/src/tui/viz/view.ts +228 -0
  86. package/src/extension/parent-label.ts +0 -115
  87. package/src/profiles/classify.ts +0 -375
  88. package/src/profiles/profiles.ts +0 -730
  89. package/src/runs/layout.ts +0 -258
@@ -1,29 +1,26 @@
1
1
  /**
2
- * Launch / collect / retire orchestration.
2
+ * Single-run orchestration over the RPC supervisor.
3
3
  *
4
- * Design refs: §5 (recycling), §9 (launch), §10 (collect).
5
- * Measured refs that shape this code:
6
- * F4 — pre-create the session file (closes the lazy-creation data-loss window)
7
- * F8 — `agent wait` covers a turn
8
- * F11 — clean exit is ctrl+d, NOT ctrl+c
9
- * F15 — `tab close` reaps everything atomically
10
- * F19 — `agent_pane_busy` race after a split; retry with backoff
11
- * F21 — errors arrive on stderr
12
- * F22 — a missing binary looks like a start timeout
13
- * F26 — `agent_status` cannot tell success from failure
14
- * F27 — after exit the agent is gone; collect BEFORE recycle or lose the outcome
15
- * F29 — a hard kill leaves no assistant message
4
+ * Process lifecycle belongs to LegionSupervisor. Session JSONL remains the
5
+ * sole source of execution outcomes; this module owns run records, budgets,
6
+ * lineage, acceptance and worktree setup.
16
7
  */
17
8
 
18
9
  import * as fs from "node:fs";
19
10
  import { randomBytes } from "node:crypto";
20
11
  import * as path from "node:path";
21
- import { readPaneDiagnostic } from "../herdr/client.ts";
22
- import { makeName } from "../shared/name.ts";
23
- import {
24
- encodeNestedPath,
25
- parseNestedPathEnv,
26
- } from "../shared/nested-path.ts";
12
+ import { modelCandidates } from "../agents/model-resolution.ts";
13
+ import { DEFAULT_TEAM, TEAM_ENV, type ActiveTeam } from "../agents/teams.ts";
14
+ import type { LegionSettings } from "../shared/types.ts";
15
+ import { LEGION_DB_ENV, LEGION_IDENTITY_ENV_KEYS, LEGION_NODE_ID_ENV, legionIdentityEnv } from "./args.ts";
16
+ import type { DatabaseSync } from "../legion/db.ts";
17
+ import type { RunStore } from "./store.ts";
18
+ import type { LegionEventBus, LegionProcessEventType } from "../extension/event-bus.ts";
19
+ import { appendEvent } from "../legion/events.ts";
20
+ import { withLaunchBudget, type LegionBudgetLimits } from "../legion/budget.ts";
21
+ import { getChildByName, getNode, insertNode, nodeIdForChild, sanitizeNodeSlug, type LegionNode, updateNode } from "../legion/nodes.ts";
22
+ import { upsertUsage } from "../legion/usage.ts";
23
+ import { evaluatePhaseTransition, isLegionPhase, isTerminalPhase } from "../legion/state-machine.ts";
27
24
  import { CHILD_ACCEPTANCE_ROLE_ENV, CHILD_ROLE_ENV } from "../extension/child-guard.ts";
28
25
  import {
29
26
  ALLOW_NESTED_ENV,
@@ -31,134 +28,88 @@ import {
31
28
  MAX_TURNS_ENV,
32
29
  TOOL_TIMEOUT_MS_ENV,
33
30
  } from "../extension/budget.ts";
34
- import { modelCandidates } from "../agents/model-resolution.ts";
35
- import {
36
- DEFAULT_TEAM,
37
- TEAM_ENV,
38
- type ActiveTeam,
39
- } from "../agents/teams.ts";
40
- import { nativeModelFor } from "./kind.ts";
31
+ import { canUseCachedCollect } from "../extension/recycle.ts";
41
32
  import {
42
33
  countAssistantMessages,
43
34
  deriveOutcome,
44
- isLastTurnComplete,
45
- parseSessionFile,
46
35
  emptyParsedSession,
47
36
  extractVerdict,
48
- paneHasLiveReply,
49
- paneIsBusy,
50
- paneNeedsSubmitNudge,
51
- stripPromptEcho,
37
+ isLastTurnComplete,
38
+ isTransientConnectionFailure,
39
+ parseSessionFile,
52
40
  } from "../shared/session.ts";
41
+ import { encodeNestedPath, parseNestedPathEnv } from "../shared/nested-path.ts";
42
+ import { makeName } from "../shared/name.ts";
53
43
  import {
54
- cursorTurnSettled,
55
- findCursorChatDir,
56
- parseCursorChat,
57
- } from "../shared/cursor-chat.ts";
58
- import {
59
- type AgentConfig,
60
- type AgentKind,
61
44
  type AcceptanceResult,
45
+ type AgentConfig,
62
46
  type ChildRecord,
63
47
  DEFAULTS,
64
48
  ErrorCodes,
65
49
  type Execution,
66
50
  type Handle,
67
- type HerdrClient,
68
51
  MAX_NESTED_PATH_ENTRIES,
69
52
  type ModelOrigin,
70
53
  type NestedPathEntry,
71
- type Placement,
72
54
  type RunRecord,
73
55
  SubagentError,
74
56
  type Usage,
75
57
  } from "../shared/types.ts";
76
- import {
77
- mergeProgress,
78
- progressFromAgentInfo,
79
- progressFromPaneInfo,
80
- progressFromSession,
81
- type LiveProgress,
82
- } from "../shared/progress.ts";
58
+ import { RpcSupervisor } from "../supervisor/rpc-supervisor.ts";
59
+ import type { LegionSupervisor, SettleResult, SpawnInput } from "../supervisor/types.ts";
60
+ import type { PendingUIRequest, UIProxy } from "../supervisor/ui-proxy.ts";
61
+ import { nativeModelFor } from "./kind.ts";
83
62
  import { applyVerification, type VerifyRunner } from "./acceptance.ts";
84
- import { planKindStart } from "./kind.ts";
85
- import { canUseCachedCollect } from "../extension/recycle.ts";
86
63
  import {
87
64
  createChildWorktree,
88
65
  removeChildWorktree,
89
66
  resolveLaunchWorktree,
90
67
  } from "./worktree.ts";
91
- import {
92
- createSessionLayout,
93
- typeTabLabel,
94
- type SessionLayout,
95
- type TypeTabCreateResult,
96
- } from "./layout.ts";
68
+ import { provisionWorktree } from "./provision.ts";
69
+
70
+ export interface BudgetRefusedEvent {
71
+ type: "budget_refused";
72
+ requestedMaxDepth: number;
73
+ effectiveMaxDepth: number;
74
+ reason: string;
75
+ }
76
+
77
+ export interface OrchestratorLegionContext {
78
+ db: DatabaseSync;
79
+ dbPath: string;
80
+ nodeId: string;
81
+ parentNodeId?: string | null;
82
+ parentRunId?: string | null;
83
+ runId?: string;
84
+ runStore?: RunStore;
85
+ settings?: LegionSettings;
86
+ eventBus?: Pick<LegionEventBus, "emit">;
87
+ }
97
88
 
98
89
  export interface OrchestratorDeps {
99
- client: HerdrClient;
100
- /** Absolute path of the run directory; session files live here. */
90
+ supervisor?: LegionSupervisor;
91
+ uiProxy?: UIProxy;
101
92
  runDir: string;
102
- /** Working directory for child agents. */
103
93
  cwd: string;
104
- /** Called after every state change so the caller can persist. */
94
+ legion?: OrchestratorLegionContext;
105
95
  onChildUpdate?: (child: ChildRecord) => void;
106
- /** Injected for tests. */
107
96
  now?: () => number;
108
97
  sleep?: (ms: number) => Promise<void>;
109
- startRetries?: number;
110
- startRetryBackoffMs?: number;
111
- startTimeoutMs?: number;
112
- /**
113
- * Lineage of THIS process, read from the environment when running as a
114
- * child. Appended to when spawning children so a grandchild knows its full
115
- * ancestry (design §4.2).
116
- */
117
98
  parentPath?: NestedPathEntry[];
118
- /** Hard ceiling on nesting depth; launches beyond it are refused. */
119
99
  maxDepth?: number;
120
- /**
121
- * Maximum children this orchestrator may spawn. Enforces
122
- * `subagents.maxSubagentSpawnsPerSession` so a runaway fan-out cannot
123
- * exhaust the machine. `null`/undefined means unlimited.
124
- */
125
100
  maxSpawns?: number | null;
126
- /**
127
- * Session-wide tab/name registry. Same agent type shares one tab (each
128
- * child a pane). The extension passes one instance so parallel tool calls
129
- * cannot each create a tab; tests omit it and get an isolated registry.
130
- */
131
- layout?: SessionLayout;
132
- /** Injected so tests do not actually run `npm test`. */
133
101
  verifyRunner?: VerifyRunner;
134
- /**
135
- * Parent agent's herdr Space (`HERDR_WORKSPACE_ID`). Pins `tab create`
136
- * and adopt to that Space; without it herdr uses the UI-focused Space.
137
- */
138
- workspaceId?: string;
139
- /**
140
- * Parent Pi's herdr pane (`HERDR_PANE_ID`). Scopes the type-tab label so
141
- * another parent in the same Space does not adopt this tab.
142
- */
143
- parentPaneId?: string;
144
- /** Active team selection to inherit into child panes. */
102
+ /** Post-create bootstrap for child worktrees (legion.worktreeBootstrap). */
103
+ worktreeBootstrap?: string;
104
+ worktreeBootstrapTimeoutMs?: number;
145
105
  team?: ActiveTeam;
146
- /**
147
- * Extra child-side context from `subagents.childContext`, appended to
148
- * every child's system prompt after the role prompt.
149
- */
150
106
  childContext?: string;
151
- /**
152
- * Root of the cursor chat stores, overriding `~/.cursor/chats` — injects
153
- * the fake's store root in tests.
154
- */
155
- cursorChatsRoot?: string;
107
+ onBudgetRefused?: (event: BudgetRefusedEvent) => void;
156
108
  }
157
109
 
158
110
  export interface CollectResult {
159
111
  execution: Execution;
160
112
  output: string;
161
- /** Full output persisted to disk (`.output.md` in the run dir), when any. */
162
113
  outputFile?: string;
163
114
  usage: Usage | null;
164
115
  model: string | null;
@@ -166,75 +117,38 @@ export interface CollectResult {
166
117
  blocked?: boolean;
167
118
  }
168
119
 
169
- /**
170
- * How many times a collect may push its deadline past the caller's timeout when
171
- * the child's artifact is still growing (D). Total wait ≤ (1 + N) × timeoutMs.
172
- *
173
- * A hard-killed child writes nothing (F29), so a growing file is positive
174
- * evidence of a live, still-writing turn — reporting `running` for it was the
175
- * false-timeout that made the parent think a healthy worker had stalled.
176
- */
177
120
  export const COLLECT_GRACE_EXTENSIONS = 2;
178
-
179
- /** Environment variable carrying the lineage chain into a child process. */
121
+ /** Shown when the launch-time collect budget elapses and the child is still in-turn. */
122
+ export const COLLECT_DEADLINE_REASON = "collect deadline (cumulative since launch) exceeded; child still alive";
123
+ /** Shown when a live child's session ends on an OpenAI/GPT connection blip. */
124
+ export const TRANSIENT_CONNECTION_REASON = "transient connection error; RPC child still alive";
180
125
  const LINEAGE_ENV = "PI_SUBAGENT_PARENT_PATH";
181
- /** Environment variable carrying the depth ceiling into a child process. */
182
126
  const MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
183
- /** Environment variable marking a process as a subagent child. */
127
+ const UTILITY_CHILD_ENV = "PI_SUBAGENT_UTILITY_CHILD";
184
128
  const CHILD_ENV = "PI_SUBAGENT_CHILD";
129
+ const POLL_INTERVAL_MS = 500;
185
130
 
186
- const defaultSleep = (ms: number) =>
187
- new Promise<void>((r) => setTimeout(r, ms));
188
-
189
- /**
190
- * Whether an `agent get` result definitively reports the agent as gone.
191
- *
192
- * ONLY `NOT_FOUND` counts. A transport failure, a wedged or timed-out CLI
193
- * (HERDR_ERROR from the command timeout) says nothing about the child: the
194
- * agent may be perfectly alive while our control channel is broken. Callers
195
- * that act on "gone" (aborted verdicts, retire, relaunch) MUST use this, or a
196
- * host-side incident retires a live child (hw 2026-10-09).
197
- */
198
- function agentGone(
199
- res: { ok: true } | { ok: false; error: { code: string } },
200
- ): boolean {
201
- return !res.ok && res.error.code === ErrorCodes.NOT_FOUND;
202
- }
203
-
204
- /**
205
- * Await a teardown call whose failure is genuinely ignorable.
206
- *
207
- * Recycling is best-effort by design: a pane may already be gone, and the
208
- * session file survives either way (F12). Spelling that intent once keeps the
209
- * call sites free of `await x.catch(...)` chains, which mix two async styles
210
- * and hide which failures matter.
211
- */
212
- async function bestEffort(work: Promise<unknown>): Promise<void> {
213
- try {
214
- await work;
215
- } catch {
216
- /* teardown is best-effort */
217
- }
131
+ function parseDepthCeiling(raw: string | undefined): number | undefined {
132
+ if (raw === undefined || !/^\d+$/.test(raw.trim())) return undefined;
133
+ const value = Number(raw.trim());
134
+ return Number.isInteger(value) && value >= 0 ? value : undefined;
218
135
  }
219
136
 
220
- function canFallbackStart(error: unknown): boolean {
221
- if (!(error instanceof SubagentError)) return false;
222
- return (
223
- error.code !== ErrorCodes.NOT_FOUND &&
224
- error.code !== ErrorCodes.BUDGET_EXCEEDED &&
225
- error.code !== ErrorCodes.NAME_TAKEN
137
+ /** Root/process ceiling: inherited env, settings, and the saturated path cap. */
138
+ export function effectiveMaxDepth(settingsMaxDepth?: number): number {
139
+ return Math.min(
140
+ parseDepthCeiling(process.env[MAX_DEPTH_ENV]) ?? Number.POSITIVE_INFINITY,
141
+ settingsMaxDepth ?? Number.POSITIVE_INFINITY,
142
+ MAX_NESTED_PATH_ENTRIES,
226
143
  );
227
144
  }
228
145
 
229
- /**
230
- * Random hex token proving we created a pane (guards against killing others').
231
- * Crypto-safe: this token is the ownership proof persisted in run.json.
232
- */
146
+ const defaultSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
147
+
233
148
  function ownerToken(): string {
234
149
  return randomBytes(8).toString("hex");
235
150
  }
236
151
 
237
- /** Size of a collect artifact in bytes; 0 when missing or unreadable. */
238
152
  function artifactSize(file: string): number {
239
153
  try {
240
154
  return fs.statSync(file).size;
@@ -243,17 +157,10 @@ function artifactSize(file: string): number {
243
157
  }
244
158
  }
245
159
 
246
- /**
247
- * Derive the acceptance verdict (design §3.5).
248
- *
249
- * L2 reads the agent's own machine-readable verdict. An agent asserting success
250
- * is exactly the signal that cannot be trusted (F32), so a self-report can only
251
- * ever reach `attested` — never `verified`.
252
- *
253
- * L3 criteria are SEMANTIC (`must: "tests pass"`), so the runtime cannot decide
254
- * them. Rather than silently dropping the checklist, it is carried forward for
255
- * the caller to confirm; that is also why `verified` is never claimed here.
256
- */
160
+ function isApprovalRequest(request: PendingUIRequest): boolean {
161
+ return request.request.method === "confirm";
162
+ }
163
+
257
164
  function deriveAcceptance(
258
165
  parsed: ReturnType<typeof parseSessionFile>,
259
166
  execution: Execution,
@@ -261,12 +168,7 @@ function deriveAcceptance(
261
168
  opts: { completionGuard?: boolean } = {},
262
169
  ): AcceptanceResult {
263
170
  let acceptance: AcceptanceResult = { status: "unknown", level: "none" };
264
- // MUST read `lastTurnOutput`, not `output`: `output` is the last non-empty text
265
- // anywhere in the session, so it survives into a turn that produced none — and
266
- // a stale "ok" from an earlier turn would then be reported as
267
- // accepted/attested while `execution` says aborted (F39).
268
171
  const verdict = extractVerdict(parsed.lastTurnOutput ?? "");
269
-
270
172
  if (verdict) {
271
173
  acceptance = {
272
174
  status: verdict.ok ? "accepted" : "rejected",
@@ -275,56 +177,20 @@ function deriveAcceptance(
275
177
  };
276
178
  } else if (execution.status === "success") {
277
179
  acceptance = opts.completionGuard
278
- ? {
279
- status: "rejected",
280
- level: "none",
281
- reason: 'completionGuard: missing {"ok": true|false} verdict',
282
- }
283
- : {
284
- status: "unknown",
285
- level: "none",
286
- reason: "no machine-readable verdict",
287
- };
288
- } else if (
289
- execution.status === "unknown" ||
290
- execution.status === "running"
291
- ) {
292
- acceptance = {
293
- status: "unknown",
294
- level: "none",
295
- reason: execution.reason ?? execution.status,
296
- };
180
+ ? { status: "rejected", level: "none", reason: 'completionGuard: missing {"ok": true|false} verdict' }
181
+ : { status: "unknown", level: "none", reason: "no machine-readable verdict" };
182
+ } else if (execution.status === "unknown" || execution.status === "running") {
183
+ acceptance = { status: "unknown", level: "none", reason: execution.reason ?? execution.status };
297
184
  } else {
298
- acceptance = {
299
- status: "rejected",
300
- level: "none",
301
- reason: execution.reason ?? execution.status,
302
- };
185
+ acceptance = { status: "rejected", level: "none", reason: execution.reason ?? execution.status };
303
186
  }
304
-
305
187
  if (pendingCriteria?.length) {
306
- acceptance = {
307
- ...acceptance,
308
- pendingCriteria: pendingCriteria.map((c) => ({ ...c })),
309
- };
188
+ acceptance = { ...acceptance, pendingCriteria: pendingCriteria.map((criterion) => ({ ...criterion })) };
310
189
  }
311
-
312
190
  return acceptance;
313
191
  }
314
192
 
315
- /**
316
- * Pre-create the session file (F4).
317
- *
318
- * pi creates session files lazily: a child that dies before its first flush
319
- * leaves NO file, so there is nothing to resume. Creating it up front closes
320
- * that window and is verified to not interfere with normal writes.
321
- */
322
- /**
323
- * Pre-create an empty session file (F4) so pi cannot lose the first turn.
324
- *
325
- * Reports a clear error when the directory is unusable: a bare `mkdirSync`
326
- * surfaces as an opaque `ENOTDIR`/`EACCES` from deep inside the launcher.
327
- */
193
+ /** Pre-create an empty session file so the first Pi turn cannot be lost. */
328
194
  export function preCreateSessionFile(file: string): void {
329
195
  const dir = path.dirname(file);
330
196
  try {
@@ -334,1705 +200,946 @@ export function preCreateSessionFile(file: string): void {
334
200
  const code = (error as NodeJS.ErrnoException).code ?? "UNKNOWN";
335
201
  throw new SubagentError(
336
202
  `cannot write run artifacts to ${dir} (${code}). ` +
337
- `Subagent runs need a writable directory: pass a writable \`cwd\` ` +
338
- `to the subagent tool, or run from a checkout you can write to.`,
203
+ "Subagent runs need a writable cwd to write session data.",
339
204
  ErrorCodes.INVALID_PARAMS,
340
205
  { dir },
341
206
  );
342
207
  }
343
208
  }
344
209
 
345
- // The bundled `large-class` rule matches ANY class whose body contains a
346
- // method-like declaration (verified: a 2-member class trips it), so it fires on
347
- // every class in this file regardless of size and cannot be satisfied by
348
- // splitting. Orchestrator's own cohesion is tracked by the complexity rules.
210
+ function canFallbackStart(error: unknown): boolean {
211
+ return error instanceof SubagentError &&
212
+ error.code !== ErrorCodes.NOT_FOUND &&
213
+ error.code !== ErrorCodes.BUDGET_EXCEEDED &&
214
+ error.code !== ErrorCodes.NAME_TAKEN;
215
+ }
216
+
349
217
  // pi-lens-ignore: large-class
350
218
  export class Orchestrator {
351
- private readonly client: HerdrClient;
219
+ private readonly supervisor: LegionSupervisor;
220
+ private readonly uiProxy?: UIProxy;
352
221
  private readonly runDir: string;
353
222
  private readonly cwd: string;
354
- /** Overridden in tests: the cursor chat-store root (`~/.cursor/chats`). */
355
- private readonly cursorChatsRoot?: string;
356
223
  private readonly onChildUpdate: (child: ChildRecord) => void;
357
224
  private readonly now: () => number;
358
225
  private readonly sleep: (ms: number) => Promise<void>;
359
- private readonly startRetries: number;
360
- private readonly startBackoff: number;
361
- private readonly startTimeoutMs: number;
362
- /** Poll interval while waiting for a turn to produce its first output. */
363
- private readonly pollIntervalMs = 500;
364
- /**
365
- * Slice length for `agent wait`. A single remaining-timeout wait can hang
366
- * after F15 `tab close` reaps the agent; slicing lets collect notice
367
- * `agent_not_found` and abort instead of sitting until timeoutMs.
368
- */
369
- private readonly waitSliceMs = 2_000;
370
- /**
371
- * Minimum gap between paste-submit Enters for one non-pi child. A swallowed
372
- * nudge must be retried, but the TUI needs time to ingest the paste first —
373
- * pressing faster than this just queues noise (measured on a live pane).
374
- */
375
- private readonly nudgeIntervalMs = 1_500;
376
- /** Per-child timestamp of the last paste-submit Enter. */
377
- private readonly nudgeTimestamps = new Map<string, number>();
378
226
  private readonly parentPath: NestedPathEntry[];
379
- private readonly maxDepth: number;
227
+ private readonly maxDepthValue: number;
380
228
  private readonly maxSpawns: number | null;
381
- private readonly layout: SessionLayout;
382
229
  private readonly verifyRunner?: VerifyRunner;
383
- /**
384
- * Parent Space id for `tab create` / adopt. Empty or unset means herdr
385
- * places the tab in the UI-focused Space.
386
- */
387
- private readonly workspaceId?: string;
388
- /** Parent pane id used to uniquify type-tab labels across parent Pis. */
389
- private readonly parentPaneId?: string;
230
+ private readonly worktreeBootstrap?: string;
231
+ private readonly worktreeBootstrapTimeoutMs?: number;
390
232
  private readonly team?: ActiveTeam;
391
- /** Extra child-side context from `subagents.childContext`. */
392
233
  private readonly childContext?: string;
393
- /** Per-kind integration guard outcome, so one session probes/installs once. */
394
- private readonly integrationChecked = new Map<AgentKind, boolean>();
395
- /** Last type-tab used by a child of this orchestrator. */
396
- private lastTypeTabId: string | null = null;
234
+ private readonly onBudgetRefused?: (event: BudgetRefusedEvent) => void;
235
+ private readonly legion?: OrchestratorLegionContext;
236
+ private readonly requestedDepthCap?: number;
237
+ private depthWarningEmitted = false;
397
238
  private spawned = 0;
398
239
  private readonly children = new Map<string, ChildRecord>();
399
- private readonly counter = new Map<string, number>();
240
+ private readonly nameCounter = new Map<string, number>();
241
+ private readonly pendingWaits = new Map<string, Promise<SettleResult>>();
400
242
 
401
243
  constructor(deps: OrchestratorDeps) {
402
- this.client = deps.client;
244
+ this.supervisor = deps.supervisor ?? new RpcSupervisor();
245
+ const proxy = (this.supervisor as LegionSupervisor & { uiProxy?: UIProxy }).uiProxy;
246
+ this.uiProxy = deps.uiProxy ?? proxy;
403
247
  this.runDir = deps.runDir;
404
248
  this.cwd = deps.cwd;
405
- this.cursorChatsRoot = deps.cursorChatsRoot;
406
249
  this.onChildUpdate = deps.onChildUpdate ?? (() => {});
407
- this.now = deps.now ?? (() => Date.now());
250
+ this.now = deps.now ?? Date.now;
408
251
  this.sleep = deps.sleep ?? defaultSleep;
409
- this.startRetries = deps.startRetries ?? DEFAULTS.startRetries;
410
- this.startBackoff = deps.startRetryBackoffMs ?? DEFAULTS.startRetryBackoffMs;
411
- this.startTimeoutMs = deps.startTimeoutMs ?? DEFAULTS.startTimeoutMs;
412
- // Inherit lineage from the environment when this process is itself a child,
413
- // so nested subagents can be bounded and cycles are impossible.
414
- this.parentPath =
415
- deps.parentPath ?? parseNestedPathEnv(process.env[LINEAGE_ENV]);
416
- this.maxDepth =
417
- deps.maxDepth ??
418
- Number(process.env[MAX_DEPTH_ENV]) ??
419
- MAX_NESTED_PATH_ENTRIES;
420
- if (!Number.isFinite(this.maxDepth) || this.maxDepth < 1)
421
- this.maxDepth = MAX_NESTED_PATH_ENTRIES;
252
+ this.parentPath = deps.parentPath ?? parseNestedPathEnv(process.env[LINEAGE_ENV]);
253
+ const envDepth = parseDepthCeiling(process.env[MAX_DEPTH_ENV]);
254
+ const oversized = [deps.maxDepth, envDepth].filter(
255
+ (value): value is number => value !== undefined && value > MAX_NESTED_PATH_ENTRIES,
256
+ );
257
+ this.requestedDepthCap = oversized.length ? Math.max(...oversized) : undefined;
258
+ this.maxDepthValue = effectiveMaxDepth(deps.maxDepth);
422
259
  this.maxSpawns = deps.maxSpawns ?? null;
423
- this.layout = deps.layout ?? createSessionLayout();
424
260
  this.verifyRunner = deps.verifyRunner;
425
- const rawWorkspaceId =
426
- deps.workspaceId ?? process.env.HERDR_WORKSPACE_ID;
427
- this.workspaceId = rawWorkspaceId?.trim() || undefined;
428
- const rawParentPaneId =
429
- deps.parentPaneId ?? process.env.HERDR_PANE_ID;
430
- this.parentPaneId = rawParentPaneId?.trim() || undefined;
261
+ this.worktreeBootstrap = deps.worktreeBootstrap?.trim() || undefined;
262
+ this.worktreeBootstrapTimeoutMs = deps.worktreeBootstrapTimeoutMs;
431
263
  this.team = deps.team;
432
264
  this.childContext = deps.childContext?.trim() || undefined;
265
+ this.onBudgetRefused = deps.onBudgetRefused;
266
+ this.legion = deps.legion;
433
267
  }
434
268
 
435
- /** The lineage path a child of this process would receive. */
436
- childPath(agentName: string): NestedPathEntry[] {
437
- return [
438
- ...this.parentPath,
439
- { runId: path.basename(this.runDir), agent: agentName },
440
- ].slice(-MAX_NESTED_PATH_ENTRIES);
441
- }
269
+ get maxDepth(): number { return this.maxDepthValue; }
270
+ get depth(): number { return this.parentPath.length; }
442
271
 
443
- /** Current nesting depth (0 = a top-level orchestrator). */
444
- get depth(): number {
445
- return this.parentPath.length;
272
+ childPath(agentName: string): NestedPathEntry[] {
273
+ return [...this.parentPath, { runId: path.basename(this.runDir), agent: agentName }]
274
+ .slice(-MAX_NESTED_PATH_ENTRIES);
446
275
  }
447
276
 
448
277
  sessionFileFor(name: string): string {
449
278
  return path.join(this.runDir, `${name}.jsonl`);
450
279
  }
451
280
 
452
- /**
453
- * Names currently held by live agents across the WHOLE herdr session.
454
- *
455
- * herdr's agent-name namespace is global, not per-workspace: an unrelated
456
- * session (or a human) can hold `orchestrator`, `reviewer-0`, etc. Consulting
457
- * this before allocating avoids burning a retry on a name we can already see
458
- * is taken.
459
- */
460
- private async activeAgentNames(): Promise<Set<string>> {
461
- const res = await this.client.agentList();
462
- if (!res.ok) return new Set(); // best-effort: the retry path still covers us
463
- const names = new Set<string>();
464
- for (const agent of res.value) {
465
- if (agent.name) names.add(agent.name);
281
+ allocateName(agentName: string): string {
282
+ const seen = this.nameCounter.get(agentName) ?? 0;
283
+ for (let index = seen; index < seen + 1000; index += 1) {
284
+ const candidate = makeName(agentName, index);
285
+ if (this.children.has(candidate) || this.supervisor.isAlive(candidate)) continue;
286
+ this.nameCounter.set(agentName, index + 1);
287
+ return candidate;
466
288
  }
467
- return names;
289
+ const fallback = makeName(agentName, seen);
290
+ this.nameCounter.set(agentName, seen + 1);
291
+ return fallback;
468
292
  }
469
293
 
470
- /**
471
- * Allocate a herdr-valid name that is unique both within this run and
472
- * against `reserved` (names held by other live agents).
473
- */
474
- allocateName(agent: string, reserved?: ReadonlySet<string>): string {
475
- const seen = this.counter.get(agent) ?? 0;
476
- for (let i = seen; i < seen + 1000; i += 1) {
477
- const candidate = makeName(agent, i);
478
- if (!this.children.has(candidate) && !reserved?.has(candidate)) {
479
- this.counter.set(agent, i + 1);
480
- return candidate;
481
- }
294
+ private allocateLegionName(agentName: string): string {
295
+ const legion = this.legion;
296
+ if (!legion) return this.allocateName(agentName);
297
+ const seen = this.nameCounter.get(agentName) ?? 0;
298
+ for (let index = seen; index < seen + 1_000; index += 1) {
299
+ const candidate = makeName(agentName, index);
300
+ if (this.children.has(candidate) || getChildByName(legion.db, legion.nodeId, candidate) || this.supervisor.isAlive(candidate)) continue;
301
+ this.nameCounter.set(agentName, index + 1);
302
+ return candidate;
482
303
  }
483
- this.counter.set(agent, seen + 1);
484
- return makeName(agent, seen);
304
+ throw new SubagentError(`could not allocate a unique child name for ${agentName}`, ErrorCodes.NAME_TAKEN);
485
305
  }
486
306
 
487
- /** The type-tab last used by a child of this orchestrator (null before launch). */
488
- get tabId(): string | null {
489
- return this.lastTypeTabId;
307
+ private legionLocalName(name: string): string {
308
+ const prefix = `${this.legion?.nodeId}.`;
309
+ const local = name.startsWith(prefix) ? name.slice(prefix.length) : name;
310
+ return sanitizeNodeSlug(local);
490
311
  }
491
312
 
492
- /**
493
- * The tab for this agent type, created or adopted on first use.
494
- *
495
- * Same type = one tab, each child a pane. The first occupant takes the
496
- * tab's root pane; later ones split that root by explicit id rather than
497
- * `--current` (which needs HERDR_PANE_ID and fails headless).
498
- *
499
- * After a reload the in-memory registry is empty; we re-adopt by herdr
500
- * tab label so a second scout still joins the scout tab.
501
- */
502
- private async ensureTypeTab(
503
- agentType: string,
504
- env?: Record<string, string>,
505
- cwd: string = this.cwd,
506
- ): Promise<{ tabId: string; rootPaneId: string }> {
507
- const slot = await this.layout.acquireTypeTab(agentType, () =>
508
- this.createOrAdoptTypeTab(agentType, env, cwd),
509
- );
510
- this.lastTypeTabId = slot.tabId;
511
- return { tabId: slot.tabId, rootPaneId: slot.rootPaneId };
313
+ private childFromNode(name: string, node: LegionNode): ChildRecord {
314
+ if (node.status === "failed" || ["done", "failed", "aborted"].includes(node.phase ?? "")) {
315
+ throw new SubagentError(`legion child is terminal and cannot be resumed: ${node.id}`, ErrorCodes.BUDGET_EXCEEDED);
316
+ }
317
+ if (!node.sessionFile) throw new SubagentError(`legion child has no session to resume: ${node.id}`, ErrorCodes.NOT_FOUND);
318
+ 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 } : {}) };
512
319
  }
513
320
 
514
- private async createOrAdoptTypeTab(
515
- agentType: string,
516
- env?: Record<string, string>,
517
- cwd: string = this.cwd,
518
- ): Promise<TypeTabCreateResult> {
519
- const label = typeTabLabel(agentType, this.parentPaneId);
520
- const adopted = await this.adoptTabByLabel(label);
521
- if (adopted) return adopted;
522
-
523
- const res = await this.client.tabCreate({
524
- cwd,
525
- label,
526
- ...(env ? { env } : {}),
527
- focus: false,
528
- ...(this.workspaceId ? { workspaceId: this.workspaceId } : {}),
529
- });
530
- if (!res.ok) {
531
- throw new SubagentError(
532
- `tab create failed: ${res.error.message}`,
533
- res.error.code,
534
- );
321
+ 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 {
322
+ const legion = this.legion;
323
+ if (!legion) return null;
324
+ const parent = getNode(legion.db, legion.nodeId);
325
+ if (!parent) throw new SubagentError(`legion parent node not found: ${legion.nodeId}`, ErrorCodes.BUDGET_EXCEEDED);
326
+ const previous = getNode(legion.db, input.nodeId);
327
+ if (!previous && getChildByName(legion.db, legion.nodeId, input.name)) {
328
+ throw new SubagentError(`legion child already exists: ${input.name}`, ErrorCodes.NAME_TAKEN);
535
329
  }
536
- return {
537
- tabId: res.value.tab.tab_id,
538
- rootPaneId: res.value.rootPaneId,
539
- };
330
+ if (previous && (previous.status === "failed" || ["done", "failed", "aborted"].includes(previous.phase ?? ""))) {
331
+ throw new SubagentError(`legion child is terminal and cannot be resumed: ${input.nodeId}`, ErrorCodes.BUDGET_EXCEEDED);
332
+ }
333
+ const team = input.team ?? input.agent.extraFields?.team ?? this.team?.name;
334
+ // A utility node is a hard leaf and does not consume the recursive depth
335
+ // budget. Keep the real ledger depth, but allow this one generation.
336
+ const depthCeiling = input.utility
337
+ ? parent.depth + 1
338
+ : Math.min(legion.settings?.maxDepth ?? this.maxDepthValue, MAX_NESTED_PATH_ENTRIES);
339
+ const childCount = Number(legion.db.prepare("SELECT COUNT(*) AS count FROM nodes WHERE parent_id = ?").get(legion.nodeId)?.count ?? 0);
340
+ const maxChildren = previous ? Math.max(legion.settings?.maxChildrenPerNode ?? 8, childCount + 1) : legion.settings?.maxChildrenPerNode;
341
+ const activeReservation = previous && (previous.status === "starting" || previous.status === "running") ? 1 : 0;
342
+ const limits: LegionBudgetLimits = { maxDepth: depthCeiling, maxChildrenPerNode: maxChildren, maxActiveNodes: (legion.settings?.maxActiveNodes ?? 30) + activeReservation };
343
+ const gate = withLaunchBudget(legion.db, { parentId: legion.nodeId, depth: parent.depth + 1, nodeId: input.nodeId }, () => {
344
+ if (previous) {
345
+ 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);
346
+ return previous;
347
+ }
348
+ if (!input.runId) throw new SubagentError(`node run reservation is missing: ${input.nodeId}`, ErrorCodes.START_FAILED);
349
+ insertNode(legion.db, {
350
+ id: input.nodeId,
351
+ parentId: legion.nodeId,
352
+ name: input.name,
353
+ role: input.agent.name,
354
+ kind: input.agent.kind,
355
+ runId: input.runId,
356
+ sessionFile: input.sessionFile,
357
+ worktreePath: input.worktreePath ?? null,
358
+ model: input.model ?? null,
359
+ team: team && team !== DEFAULT_TEAM ? team : null,
360
+ status: "starting",
361
+ ...(input.agent.name === "centurion" ? { phase: "planning", phaseSince: this.now() } : {}),
362
+ taskSummary: input.task.slice(0, 2_000),
363
+ }, this.now);
364
+ return null;
365
+ }, { limits, now: this.now });
366
+ if (!gate.allowed) {
367
+ this.legion?.eventBus?.emit({ nodeId: input.nodeId, type: "budget_refused", data: { reason: gate.decision.reason, message: gate.decision.message, depth: gate.decision.depth, activeNodes: gate.decision.activeNodes, children: gate.decision.children, limits: gate.decision.limits }, ts: this.now() });
368
+ throw new SubagentError(`legion launch refused (${gate.decision.reason}): ${gate.decision.message}`, ErrorCodes.BUDGET_EXCEEDED);
369
+ }
370
+ return gate.value;
540
371
  }
541
372
 
542
- /**
543
- * Reuse a live herdr tab with this type's label (survives process reload).
544
- *
545
- * The root pane is treated as occupied: a later child must split, never
546
- * steal a pane that may already host an agent.
547
- */
548
- private async adoptTabByLabel(
549
- label: string,
550
- ): Promise<TypeTabCreateResult | null> {
551
- const tabs = await this.client.tabList(this.workspaceId);
552
- if (!tabs.ok) return null;
553
- const hit = tabs.value.find(
554
- (t) =>
555
- t.label === label &&
556
- (!this.workspaceId || t.workspace_id === this.workspaceId),
557
- );
558
- if (!hit) return null;
373
+ private async persistParentReservation(input: { nodeId: string; name: string; agent: AgentConfig; sessionFile: string; team?: string; model?: string; worktreePath?: string }): Promise<boolean> {
374
+ const legion = this.legion;
375
+ const parentRunId = legion?.runId;
376
+ if (!legion?.runStore || !parentRunId) return false;
377
+ const run = legion.runStore.readRun(parentRunId);
378
+ if (!run) throw new SubagentError(`parent run record not found: ${parentRunId}`, ErrorCodes.NOT_FOUND);
379
+ const previous = run.children.find((child) => child.name === input.name);
380
+ if (previous) {
381
+ if (previous.nodeId !== input.nodeId) throw new SubagentError(`child name is already assigned to ${previous.nodeId ?? previous.name}`, ErrorCodes.NAME_TAKEN);
382
+ await legion.runStore.updateChild(parentRunId, input.name, (child) => {
383
+ child.sessionFile = input.sessionFile;
384
+ child.state = "launching";
385
+ child.spawnedAt = new Date(this.now()).toISOString();
386
+ child.agent = input.agent.name;
387
+ child.kind = input.agent.kind;
388
+ child.nodeId = input.nodeId;
389
+ if (input.model) child.model = input.model;
390
+ if (input.worktreePath) child.worktreePath = input.worktreePath;
391
+ });
392
+ return false;
393
+ }
394
+ await legion.runStore.addChild(parentRunId, {
395
+ name: input.name,
396
+ nodeId: input.nodeId,
397
+ sessionFile: input.sessionFile,
398
+ ownerToken: `legion-${input.nodeId}`,
399
+ state: "launching",
400
+ spawnedAt: new Date(this.now()).toISOString(),
401
+ agent: input.agent.name,
402
+ kind: input.agent.kind,
403
+ ...(input.model ? { model: input.model } : {}),
404
+ ...(input.worktreePath ? { worktreePath: input.worktreePath } : {}),
405
+ });
406
+ return true;
407
+ }
559
408
 
560
- const panes = await this.client.paneList();
561
- if (!panes.ok) return null;
562
- const inTab = panes.value.filter((p) => p.tab_id === hit.tab_id);
563
- const root = inTab[0];
564
- if (!root) return null;
565
- return {
566
- tabId: hit.tab_id,
567
- rootPaneId: root.pane_id,
568
- rootOccupied: true,
569
- panes: inTab.map((p) => p.pane_id),
570
- };
409
+ private recordLegionLaunch(child: ChildRecord, agent: AgentConfig, task: string, teamOverride: string | undefined, resumed: boolean): void {
410
+ if (!this.legion || !child.nodeId) return;
411
+ const team = teamOverride ?? agent.extraFields?.team ?? this.team?.name;
412
+ const current = getNode(this.legion.db, child.nodeId);
413
+ const childRun = current?.runId ?? this.legion.runId ?? path.basename(this.runDir);
414
+ updateNode(this.legion.db, child.nodeId, { status: "running", runId: childRun, sessionFile: child.sessionFile, worktreePath: child.worktreePath ?? null, model: child.model ?? null, team: team && team !== DEFAULT_TEAM ? team : null, taskSummary: task.slice(0, 2_000) }, this.now);
415
+ this.emitStored(child.nodeId, resumed ? "node_resumed" : "node_launched", { parentId: this.legion.nodeId, runId: childRun, sessionFile: child.sessionFile, role: agent.name, kind: agent.kind });
571
416
  }
572
417
 
573
- /**
574
- * Create the pane an agent will occupy.
575
- *
576
- * `new-tab` gives the child a tab of its OWN. Everything else lands in the
577
- * type tab and is tiled automatically (3-column grid: fill a row of
578
- * three, then wrap down). Agent frontmatter `split-down` is
579
- * ignored here — stacking every child off the root looks like a column
580
- * of thin panes.
581
- */
582
- private async createPane(
583
- placement: Placement,
584
- agentType: string,
585
- env?: Record<string, string>,
586
- cwd: string = this.cwd,
587
- ): Promise<{ paneId: string; tabId?: string }> {
588
- if (placement === "new-tab") {
589
- const res = await this.client.tabCreate({
590
- cwd,
591
- label: `task:${agentType}`,
592
- ...(env ? { env } : {}),
593
- focus: false,
594
- ...(this.workspaceId ? { workspaceId: this.workspaceId } : {}),
595
- });
596
- if (!res.ok) {
597
- throw new SubagentError(
598
- `tab create failed: ${res.error.message}`,
599
- res.error.code,
600
- );
601
- }
602
- return { paneId: res.value.rootPaneId, tabId: res.value.tab.tab_id };
418
+ private recordSettled(child: ChildRecord, execution: Execution): void {
419
+ if (!this.legion || !child.nodeId || execution.status === "running" || child.state === "retired") return;
420
+ const status = execution.status === "success" ? "settled" : execution.status === "failed" || execution.status === "truncated" ? "failed" : "retired";
421
+ const current = getNode(this.legion.db, child.nodeId);
422
+ if (!current || current.status === status) return;
423
+ updateNode(this.legion.db, child.nodeId, { status }, this.now);
424
+ const eventType = status === "settled" ? "node_settled" : status === "failed" ? "node_failed" : "node_retired";
425
+ this.emitStored(child.nodeId, eventType, { execution: execution.status, reason: execution.reason });
426
+ if (execution.usage) {
427
+ upsertUsage(this.legion.db, { nodeId: child.nodeId, tokensIn: execution.usage.input + execution.usage.cacheRead + execution.usage.cacheWrite, tokensOut: execution.usage.output, costUsd: execution.usage.cost }, this.now);
603
428
  }
604
-
605
- await this.ensureTypeTab(agentType, env, cwd);
606
- return this.layout.assignPane(agentType, async (plan) => {
607
- const res = await this.client.paneSplit({
608
- target: plan.target,
609
- direction: plan.direction,
610
- cwd,
611
- ...(env ? { env } : {}),
612
- focus: false,
613
- });
614
- if (!res.ok) {
615
- this.layout.dropTypeTab(agentType);
616
- throw new SubagentError(
617
- `pane split failed: ${res.error.message}`,
618
- res.error.code,
619
- );
620
- }
621
- return res.value.pane_id;
622
- });
429
+ void this.supervisor.stats(child.name).then((usage) => {
430
+ if (usage) upsertUsage(this.legion!.db, { nodeId: child.nodeId!, tokensIn: usage.tokensIn, tokensOut: usage.tokensOut, costUsd: usage.costUsd }, this.now);
431
+ }).catch(() => {});
623
432
  }
624
433
 
625
- /**
626
- * Start an agent, retrying transient failures.
627
- *
628
- * Two measured races are retried rather than surfaced:
629
- * F19 — `agent_pane_busy` for a moment after a pane split.
630
- * F16 — `agent_name_taken`. herdr's name namespace is GLOBAL, so another
631
- * session holding `orchestrator` would otherwise fail our launch
632
- * outright; instead we allocate a fresh name and retry.
633
- *
634
- * Returns the name actually used, which may differ from `input.name`.
635
- */
636
- private async startWithRetry(input: {
637
- name: string;
638
- kind: AgentConfig["kind"];
639
- paneId: string;
640
- args: string[];
641
- /** Supplies a replacement name when the current one is taken. */
642
- reallocate?: () => string;
643
- }): Promise<string> {
644
- let name = input.name;
645
- let lastMessage = "start failed";
646
-
647
- for (let attempt = 0; attempt < this.startRetries; attempt += 1) {
648
- const res = await this.client.agentStart({
649
- name,
650
- kind: input.kind,
651
- paneId: input.paneId,
652
- args: input.args,
653
- timeoutMs: this.startTimeoutMs,
654
- });
655
- if (res.ok) return name;
434
+ private abortLegionPhase(nodeId: string): void {
435
+ if (!this.legion) return;
436
+ const node = getNode(this.legion.db, nodeId);
437
+ if (!node || !isLegionPhase(node.phase) || isTerminalPhase(node.phase)) return;
438
+ const decision = evaluatePhaseTransition({
439
+ from: node.phase,
440
+ to: "aborted",
441
+ reworkCount: node.reworkCount,
442
+ terminalReason: "parent_retire",
443
+ actorRole: "supervisor",
444
+ }, this.now);
445
+ if (!decision.allowed) return;
446
+ updateNode(this.legion.db, nodeId, { phase: decision.to, phaseSince: decision.phaseSince }, this.now);
447
+ this.emitStored(nodeId, "phase_change", decision.event.data);
448
+ }
656
449
 
657
- lastMessage = res.error.message;
450
+ private emitProcess(type: LegionProcessEventType, nodeId: string, data: unknown): void {
451
+ this.legion?.eventBus?.emit({ nodeId, type, data: data as Record<string, unknown> | null, ts: this.now() });
452
+ }
658
453
 
659
- // F16: the name is held by a live agent elsewhere. Take a new one and
660
- // retry instead of failing the launch.
661
- if (res.error.code === ErrorCodes.NAME_TAKEN && input.reallocate) {
662
- name = input.reallocate();
663
- await this.sleep(this.startBackoff + attempt * 50);
664
- continue;
665
- }
454
+ private emitStored(nodeId: string, type: Parameters<typeof appendEvent>[2], data: unknown): void {
455
+ if (!this.legion) return;
456
+ this.legion.eventBus?.emit(appendEvent(this.legion.db, nodeId, type, data, { now: this.now }));
457
+ }
666
458
 
667
- if (res.error.code !== ErrorCodes.PANE_BUSY) {
668
- // A real error. F22: a missing binary shows up as a timeout, so
669
- // attach the pane's contents to make the cause visible.
670
- const diagnostic = await readPaneDiagnostic(this.client, input.paneId, 30);
671
- throw new SubagentError(
672
- `agent start failed (${res.error.code}): ${res.error.message}${
673
- diagnostic ? `\n--- pane output ---\n${diagnostic}` : ""
674
- }`,
675
- res.error.code,
676
- { paneId: input.paneId },
677
- );
678
- }
679
- await this.sleep(this.startBackoff + attempt * 50);
680
- }
681
- throw new SubagentError(
682
- `agent start exhausted ${this.startRetries} retries: ${lastMessage}`,
683
- ErrorCodes.START_FAILED,
684
- );
459
+ private rollbackReservation(nodeId: string, previous: LegionNode | null): void {
460
+ if (!this.legion) return;
461
+ if (!previous) { this.legion.db.prepare("DELETE FROM nodes WHERE id = ?").run(nodeId); return; }
462
+ updateNode(this.legion.db, nodeId, { status: previous.status, runId: previous.runId, sessionFile: previous.sessionFile, worktreePath: previous.worktreePath, model: previous.model, team: previous.team, taskSummary: previous.taskSummary }, this.now);
685
463
  }
686
464
 
687
- /** Spawn-budget snapshot, for reporting and for tests. */
688
465
  budget(): { used: number; limit: number | null; remaining: number | null } {
689
466
  return {
690
467
  used: this.spawned,
691
468
  limit: this.maxSpawns,
692
- remaining:
693
- this.maxSpawns === null ? null : Math.max(0, this.maxSpawns - this.spawned),
469
+ remaining: this.maxSpawns === null ? null : Math.max(0, this.maxSpawns - this.spawned),
694
470
  };
695
471
  }
696
472
 
697
- /**
698
- * Launch a child agent. Returns a handle immediately; the child keeps
699
- * running in its pane even if this process dies (F13).
700
- */
473
+ private warnDepthCap(): void {
474
+ if (this.depthWarningEmitted || this.requestedDepthCap === undefined) return;
475
+ this.depthWarningEmitted = true;
476
+ const event: BudgetRefusedEvent = {
477
+ type: "budget_refused",
478
+ requestedMaxDepth: this.requestedDepthCap,
479
+ effectiveMaxDepth: this.maxDepthValue,
480
+ reason: `maxDepth is capped at ${MAX_NESTED_PATH_ENTRIES}`,
481
+ };
482
+ console.warn(
483
+ `[pi-legion] requested maxDepth ${event.requestedMaxDepth} exceeds the hard cap ${MAX_NESTED_PATH_ENTRIES}; using effective maxDepth ${event.effectiveMaxDepth}.`,
484
+ );
485
+ this.onBudgetRefused?.(event);
486
+ }
487
+
701
488
  async launch(input: {
702
489
  agent: AgentConfig;
703
490
  task: string;
704
491
  name?: string;
492
+ team?: string;
705
493
  model?: string;
706
494
  thinking?: string | false;
707
- placement?: Placement;
708
- /** Parent override; when omitted, the role's `worktree` flag is used. */
709
495
  worktree?: boolean;
710
- /**
711
- * How `model` was chosen. Decides whether a model the target CLI cannot
712
- * accept is refused or dropped (see `planModelCandidates`).
713
- *
714
- * Defaults to `"explicit"` when `model` was passed and `"inherited"`
715
- * otherwise. Callers that resolved a model themselves (the subagent tool)
716
- * MUST pass the real origin, or an inherited parent model will be
717
- * misreported as an explicit choice and refused.
718
- */
719
496
  modelOrigin?: ModelOrigin;
497
+ /** Vexillatio launch: bypass nested-depth gates while recording its parent-side Legion node. */
498
+ utilityDispatch?: boolean;
499
+ /** Mask inherited Legion identity from the spawned child process. */
500
+ stripLegionIdentity?: boolean;
720
501
  }): Promise<Handle> {
721
- // Allocate against BOTH our own children and the global herdr namespace.
722
- // herdr names are session-global, so an unrelated agent holding
723
- // `orchestrator` would otherwise cost us a failed start attempt.
724
- const reserved = await this.layout.liveNames(() => this.activeAgentNames());
725
- let name =
726
- input.name ??
727
- this.layout.claimName(
728
- input.agent.name,
729
- (n) => this.children.has(n) || reserved.has(n),
502
+ this.warnDepthCap();
503
+ if (input.agent.kind !== "pi") {
504
+ throw new SubagentError(
505
+ `RPC supervisor only supports pi children (received kind '${input.agent.kind}'); migrate the role to kind: pi or pin pi-legion v0.16.x`,
506
+ ErrorCodes.INVALID_PARAMS,
730
507
  );
731
- if (input.name) this.layout.rememberName(input.name);
732
-
733
- this.assertWithinBudgets();
734
-
735
- // Validate the model chain against the target kind BEFORE allocating any
736
- // resource (session file, temp dir, worktree, pane), so a refusal leaks
737
- // nothing — same invariant `assertWithinBudgets` honours above.
738
- const modelPlan = this.planModelCandidates({
508
+ }
509
+ const generated = input.name ?? (this.legion ? this.allocateLegionName(input.agent.name) : this.allocateName(input.agent.name));
510
+ const name = this.legion ? this.legionLocalName(generated) : generated;
511
+ const nodeId = this.legion ? nodeIdForChild(this.legion.nodeId, name) : undefined;
512
+ const ledgerPrevious = nodeId ? getNode(this.legion!.db, nodeId) : null;
513
+ const previous = this.children.get(name) ?? (ledgerPrevious ? this.childFromNode(name, ledgerPrevious) : undefined);
514
+ if (previous && !this.children.has(name)) this.children.set(name, previous);
515
+ // A utility dispatch is a hard leaf, not a nested command-chain launch.
516
+ // The frozen contract therefore skips assertWithinBudgets entirely.
517
+ if (!input.utilityDispatch) this.assertWithinBudgets(Boolean(previous));
518
+ if (this.supervisor.isAlive(name)) throw new SubagentError(`child is already alive: ${name}`, ErrorCodes.NAME_TAKEN);
519
+ const models = this.planModelCandidates({
739
520
  agent: input.agent,
740
521
  ...(input.model !== undefined ? { model: input.model } : {}),
741
- origin: input.modelOrigin ?? this.defaultModelOrigin(input),
522
+ origin: input.modelOrigin ?? (input.model !== undefined ? "explicit" : input.agent.modelSource?.type === "subagents.defaultModel" ? "inherited" : input.agent.model ? "explicit" : "inherited"),
742
523
  ...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
743
524
  });
744
-
745
- // A non-pi child's structured collection depends on herdr's integration
746
- // hook for that CLI reporting the session/chat id. Without it the child
747
- // still runs and even produces artifacts — but every completion is
748
- // misreported "failed: no session jsonl; collected from pane" (nj-hw
749
- // 2026-09-28: planner/advisor ran fine, all four reported failed).
750
- // Guard BEFORE any resource is allocated, same invariant as the model
751
- // chain above; auto-install is idempotent so a missing hook self-heals.
752
- await this.ensureIntegrationHook(input.agent.kind);
753
-
754
- let sessionFile = this.sessionFileFor(name);
755
- preCreateSessionFile(sessionFile);
756
-
757
- const tempDir = fs.mkdtempSync(path.join(this.runDir, `tmp-${name}-`));
758
- const placement = input.placement ?? input.agent.placement ?? "split-down";
759
- const useWorktree = resolveLaunchWorktree({
760
- roleDefault: input.agent.worktree,
761
- launch: input.worktree,
762
- });
763
-
764
- let paneId: string | null = null;
765
- let worktreePath: string | undefined;
766
- let worktreeBranch: string | undefined;
525
+ let sessionFile = previous?.sessionFile ?? this.sessionFileFor(name);
526
+ const tempDir = this.runDir;
527
+ const parentRole = this.legion ? getNode(this.legion.db, this.legion.nodeId)?.role : undefined;
528
+ const worktree = this.legion && input.agent.name === "centurion"
529
+ ? true
530
+ : this.legion && parentRole === "centurion"
531
+ ? false
532
+ : resolveLaunchWorktree({ roleDefault: input.agent.worktree, launch: input.worktree });
533
+ let worktreePath = previous?.worktreePath;
534
+ let worktreeBranch = previous?.worktreeBranch;
535
+ let createdWorktree = false;
536
+ let spawned = false;
537
+ let reservedNode: LegionNode | null = null;
538
+ let reserved = false;
539
+ let createdRunId: string | undefined;
540
+ let parentReservationCreated = false;
767
541
  try {
768
- if (useWorktree) {
769
- const tree = createChildWorktree({
770
- repoCwd: this.cwd,
771
- runDir: this.runDir,
772
- name,
773
- });
542
+ if (worktree && !worktreePath) {
543
+ const tree = createChildWorktree({ repoCwd: this.cwd, runDir: this.runDir, name });
774
544
  worktreePath = tree.path;
775
545
  worktreeBranch = tree.branch;
546
+ createdWorktree = true;
547
+ // Provision before any spawn: the child's first command and any
548
+ // plugin-run verify command would otherwise fail on a bare checkout.
549
+ // Failure throws through the existing rollback below (tree removed).
550
+ provisionWorktree({
551
+ worktreePath,
552
+ mode: this.worktreeBootstrap,
553
+ timeoutMs: this.worktreeBootstrapTimeoutMs,
554
+ });
776
555
  }
777
- const childCwd = worktreePath ?? this.cwd;
778
- const pane = await this.createPane(
779
- placement,
780
- input.agent.name,
781
- this.lineageEnv(name, input.agent),
782
- childCwd,
783
- );
784
- paneId = pane.paneId;
785
-
786
- const candidates = modelPlan.candidates;
787
- const started = await this.startWithModelFallback({
788
- name,
789
- kind: input.agent.kind,
790
- paneId,
791
- agent: input.agent,
792
- task: input.task,
793
- sessionFile,
794
- thinking: input.thinking ?? input.agent.thinking,
795
- tempDir,
796
- cwd: childCwd,
797
- candidates,
798
- ...(worktreeBranch ? { worktreeBranch } : {}),
799
- reallocate: () => {
800
- const next = this.layout.claimName(
801
- input.agent.name,
802
- (n) => this.children.has(n) || reserved.has(n),
803
- );
804
- sessionFile = this.rehomeSessionFile(sessionFile, next);
805
- return next;
806
- },
807
- });
808
- name = started.name;
809
- sessionFile = started.sessionFile;
810
- const usedModel = started.model;
811
- const thinking = input.thinking ?? input.agent.thinking;
812
-
813
- const child = this.recordChild({
814
- name,
556
+ const effectiveModel = models.candidates;
557
+ if (this.legion && nodeId && !previous && this.legion.runStore) {
558
+ const roleDepth = input.agent.maxSubagentDepth === undefined
559
+ ? Number.POSITIVE_INFINITY
560
+ : Number.isInteger(input.agent.maxSubagentDepth) && input.agent.maxSubagentDepth >= 1
561
+ ? input.agent.maxSubagentDepth
562
+ : 1;
563
+ const run = this.legion.runStore.createRun({
564
+ task: input.task,
565
+ cwd: worktreePath ?? this.cwd,
566
+ path: this.childPath(name),
567
+ maxDepth: input.utilityDispatch
568
+ ? this.depth + 1
569
+ : Math.min(this.maxDepthValue, this.depth + roleDepth, MAX_NESTED_PATH_ENTRIES),
570
+ nodeId,
571
+ herdr: { supervisor: "rpc", node_id: nodeId },
572
+ });
573
+ createdRunId = run.runId;
574
+ sessionFile = this.legion.runStore.sessionFileFor(run.runId, name);
575
+ }
576
+ preCreateSessionFile(sessionFile);
577
+ if (this.legion && nodeId) {
578
+ const reservationRunId = createdRunId ?? (previous ? ledgerPrevious?.runId : undefined) ?? this.legion.runId;
579
+ reservedNode = this.reserveNode({ nodeId, name, agent: input.agent, task: input.task, sessionFile, runId: reservationRunId, team: input.team, worktreePath, model: models.candidates[0], utility: Boolean(input.utilityDispatch && input.agent.utility) });
580
+ reserved = true;
581
+ parentReservationCreated = await this.persistParentReservation({ nodeId, name, agent: input.agent, sessionFile, ...(models.candidates[0] ? { model: models.candidates[0] } : {}), ...(worktreePath ? { worktreePath } : {}) });
582
+ }
583
+ const childEnv = this.lineageEnv(name, input.agent, input.team, nodeId);
584
+ if (input.stripLegionIdentity) {
585
+ for (const key of LEGION_IDENTITY_ENV_KEYS) delete childEnv[key];
586
+ }
587
+ let result: Awaited<ReturnType<LegionSupervisor["spawnChild"]>> | undefined;
588
+ let startedModel: string | undefined;
589
+ let lastError: unknown;
590
+ for (let index = 0; index < effectiveModel.length; index += 1) {
591
+ const model = effectiveModel[index];
592
+ const spawnInput: SpawnInput = {
593
+ name,
594
+ task: input.task,
595
+ agent: input.agent,
596
+ sessionFile,
597
+ tempDir,
598
+ cwd: worktreePath ?? this.cwd,
599
+ env: childEnv,
600
+ ...(model ? { model } : {}),
601
+ ...(input.stripLegionIdentity ? { stripLegionIdentity: true } : {}),
602
+ ...(input.thinking !== undefined ? { thinking: input.thinking } : input.agent.thinking !== undefined ? { thinking: input.agent.thinking } : {}),
603
+ ...(input.agent.allowNestedSubagents !== undefined && !input.agent.utility ? { allowNestedSubagents: input.agent.allowNestedSubagents } : {}),
604
+ ...(worktreeBranch ? { worktreeBranch } : {}),
605
+ ...(this.childContext ? { childContext: this.childContext } : {}),
606
+ };
607
+ try {
608
+ result = await this.supervisor.spawnChild(spawnInput);
609
+ startedModel = model;
610
+ spawned = true;
611
+ break;
612
+ } catch (error) {
613
+ lastError = error;
614
+ if (!canFallbackStart(error) || index === effectiveModel.length - 1) throw error;
615
+ }
616
+ }
617
+ if (!result) throw lastError ?? new SubagentError("RPC child start failed", ErrorCodes.START_FAILED);
618
+ if (previous) {
619
+ previous.state = "working";
620
+ previous.spawnedAt = new Date(this.now()).toISOString();
621
+ previous.retiredAt = undefined;
622
+ previous.execution = undefined;
623
+ previous.acceptance = undefined;
624
+ previous.outputFile = undefined;
625
+ previous.model = startedModel;
626
+ this.children.set(name, previous);
627
+ }
628
+ const child = previous ?? this.recordChild({
629
+ name: result.name,
630
+ ...(nodeId ? { nodeId } : {}),
815
631
  agent: input.agent,
816
- paneId: pane.paneId,
817
- tabId: pane.tabId,
818
- sessionFile,
819
- ...(usedModel ? { model: usedModel } : {}),
820
- ...(thinking !== undefined ? { thinking } : {}),
821
- ...(modelPlan.dropped.length ? { modelDropped: modelPlan.dropped } : {}),
632
+ sessionFile: result.sessionFile,
633
+ ...(startedModel ? { model: startedModel } : {}),
634
+ ...(input.thinking !== undefined ? { thinking: input.thinking } : input.agent.thinking !== undefined ? { thinking: input.agent.thinking } : {}),
822
635
  ...(worktreePath ? { worktreePath } : {}),
823
636
  ...(worktreeBranch ? { worktreeBranch } : {}),
824
- promptText: started.promptText,
825
637
  });
826
- // Sidebar metadata is not on the launch critical path.
827
- void this.announceChild(child, input.agent.name, usedModel).catch(
828
- () => {},
829
- );
830
-
638
+ if (previous) this.onChildUpdate(child);
639
+ if (this.legion && nodeId) this.recordLegionLaunch(child, input.agent, input.task, input.team, Boolean(reservedNode));
640
+ this.emitProcess("node_launched", nodeId ?? name, { name, agent: input.agent.name, pid: result.pid });
831
641
  return {
832
- name,
833
- paneId,
834
- sessionFile,
642
+ name: result.name,
643
+ sessionFile: result.sessionFile,
835
644
  runId: path.basename(this.runDir),
836
645
  agent: input.agent.name,
837
646
  kind: input.agent.kind,
838
647
  child,
839
648
  };
840
649
  } catch (error) {
841
- // Roll back the pane so a failed launch does not leak resources.
842
- if (paneId) {
843
- await bestEffort(this.client.paneClose(paneId));
844
- if (placement !== "new-tab") {
845
- await this.reapTypeTabIfEmpty(input.agent.name, paneId, undefined);
846
- }
650
+ if (spawned) await this.supervisor.retire(name).catch(() => {});
651
+ if (reserved && nodeId) this.rollbackReservation(nodeId, reservedNode);
652
+ if (parentReservationCreated && this.legion?.runStore) {
653
+ try { await this.legion.runStore.removeChild(this.legion.runId!, name, nodeId); } catch { /* rollback is best effort */ }
847
654
  }
848
- if (worktreePath) {
849
- removeChildWorktree({ repoCwd: this.cwd, dest: worktreePath });
655
+ if (createdRunId && this.legion?.runStore) {
656
+ try { fs.rmSync(this.legion.runStore.runDir(createdRunId), { recursive: true, force: true }); } catch { /* rollback is best effort */ }
850
657
  }
658
+ if (createdWorktree && worktreePath) removeChildWorktree({ repoCwd: this.cwd, dest: worktreePath });
851
659
  throw error;
852
- } finally {
853
- fs.rmSync(tempDir, { recursive: true, force: true });
854
660
  }
855
661
  }
856
662
 
857
- /**
858
- * How to classify the model when the caller did not say.
859
- *
860
- * A per-run `model` param is the caller's own choice, so it is explicit. When
861
- * only `agent.model` is set, `agent.modelSource` separates the two ways that
862
- * field gets filled: `applyDefaultModel` stamps
863
- * `subagents.defaultModel` (a global fallback → inherited), while frontmatter
864
- * and `agentOverrides` leave it unset (a deliberate per-role value →
865
- * explicit). The subagent tool always passes the real origin, so this default
866
- * only serves direct `Orchestrator.launch` callers.
867
- */
868
- private defaultModelOrigin(input: {
869
- agent: AgentConfig;
870
- model?: string;
871
- }): ModelOrigin {
872
- if (input.model !== undefined) return "explicit";
873
- const source = input.agent.modelSource?.type;
874
- if (source === "subagents.defaultModel") return "inherited";
875
- if (input.agent.model !== undefined) return "explicit";
876
- return "inherited";
877
- }
878
-
879
- /**
880
- * Build the model chain for a launch and decide what to do when the target
881
- * CLI cannot accept a candidate.
882
- *
883
- * `nativeModelFor` returns `undefined` for a model the kind cannot express
884
- * (e.g. a pi-shaped `provider/id` handed to cursor), which silently omits
885
- * `--model` and leaves the child on the CLI's own default. Whether that is a
886
- * bug or the intended outcome depends ENTIRELY on how the model was chosen:
887
- *
888
- * explicit — frontmatter / agentOverrides / preset / per-run `model`.
889
- * Someone deliberately named this model, so dropping it is a
890
- * mistake: refuse before any resource is allocated.
891
- * inherited — `subagents.defaultModel` or the parent session's model. The
892
- * parent is usually a different kind (pi), so its model is
893
- * simply not applicable and dropping it is the documented
894
- * behaviour (see `cursorModel`'s comment in kind.ts). Reported
895
- * via `dropped` instead of failing.
896
- *
897
- * Unacceptable candidates are REMOVED from the chain used for launching, for
898
- * both origins: leaving one in would make it the first attempt, and since a
899
- * dropped model yields no `--model` flag at all, the child would start on the
900
- * CLI default instead of falling through to the next candidate. An impossible
901
- * chain (`fallbackModels` where nothing fits) is refused only when the caller
902
- * chose explicitly; an inherited chain just becomes model-less.
903
- */
904
663
  private planModelCandidates(input: {
905
664
  agent: AgentConfig;
906
665
  model?: string;
907
666
  origin: ModelOrigin;
908
667
  thinking?: string | false;
909
668
  }): { candidates: Array<string | undefined>; dropped: string[] } {
910
- const requested = modelCandidates(
911
- input.model ?? input.agent.model,
912
- input.agent.fallbackModels,
913
- );
669
+ const requested = modelCandidates(input.model ?? input.agent.model, input.agent.fallbackModels);
914
670
  const thinking = input.thinking ?? input.agent.thinking;
915
- const kind = input.agent.kind;
916
-
917
- const usable: Array<string | undefined> = [];
671
+ const candidates: Array<string | undefined> = [];
918
672
  const dropped: string[] = [];
919
- for (const candidate of requested) {
920
- if (!candidate) {
921
- usable.push(candidate);
922
- continue;
923
- }
924
- if (nativeModelFor(kind, candidate, thinking) !== undefined) {
925
- usable.push(candidate);
926
- } else {
927
- dropped.push(candidate);
928
- }
929
- }
930
-
931
- // A model the kind cannot express is only a hard error when someone
932
- // deliberately named it AND nothing viable is left to fall back to.
933
- if (dropped.length > 0 && input.origin === "explicit" && usable.length === 0) {
934
- throw new SubagentError(
935
- `model '${dropped.join(", ")}' cannot be used with kind '${kind}' ` +
936
- `(it would be silently dropped and the child would run on the ` +
937
- `CLI default). Pick a model this CLI accepts, or remove it.`,
938
- ErrorCodes.INVALID_PARAMS,
939
- );
673
+ for (const model of requested) {
674
+ if (!model || nativeModelFor("pi", model, thinking) !== undefined) candidates.push(model);
675
+ else dropped.push(model);
940
676
  }
941
-
942
- // Every candidate was unusable. `startWithModelFallback` needs one entry
943
- // to make its start attempt, and a model-less start is exactly the
944
- // intended outcome here, so keep the `[undefined]` shape that
945
- // `modelCandidates` guarantees for an empty chain.
946
- if (usable.length === 0) return { candidates: [undefined], dropped };
947
-
948
- return { candidates: usable, dropped };
949
- }
950
-
951
- /**
952
- * Try each model candidate on the same pane. A start that fails for a
953
- * reason other than "name taken" / "not found" falls through to the next
954
- * id; NAME_TAKEN is already reallocated inside `startWithRetry`.
955
- */
956
- private async startWithModelFallback(input: {
957
- name: string;
958
- kind: AgentConfig["kind"];
959
- paneId: string;
960
- agent: AgentConfig;
961
- task: string;
962
- sessionFile: string;
963
- thinking?: string | false;
964
- tempDir: string;
965
- cwd: string;
966
- candidates: Array<string | undefined>;
967
- worktreeBranch?: string;
968
- reallocate: () => string;
969
- }): Promise<{
970
- name: string;
971
- sessionFile: string;
972
- model?: string;
973
- promptText: string;
974
- }> {
975
- let name = input.name;
976
- let sessionFile = input.sessionFile;
977
- let lastError: unknown;
978
- for (let i = 0; i < input.candidates.length; i += 1) {
979
- const model = input.candidates[i];
980
- const plan = planKindStart({
981
- agent: input.agent,
982
- task: input.task,
983
- sessionFile,
984
- model,
985
- thinking: input.thinking,
986
- tempDir: input.tempDir,
987
- cwd: input.cwd,
988
- allowNestedSubagents: input.agent.allowNestedSubagents,
989
- includeTask: false,
990
- childContext: this.childContext,
991
- ...(input.worktreeBranch
992
- ? { worktreeBranch: input.worktreeBranch }
993
- : {}),
994
- });
995
- try {
996
- name = await this.startWithRetry({
997
- name,
998
- kind: input.kind,
999
- paneId: input.paneId,
1000
- args: plan.args,
1001
- reallocate: () => {
1002
- const next = input.reallocate();
1003
- sessionFile = this.sessionFileFor(next);
1004
- return next;
1005
- },
1006
- });
1007
- const prompted = await this.client.agentPrompt(name, plan.taskText);
1008
- if (!prompted.ok) {
1009
- throw new SubagentError(
1010
- `agent prompt failed (${prompted.error.code}): ${prompted.error.message}`,
1011
- prompted.error.code,
1012
- { paneId: input.paneId },
1013
- );
1014
- }
1015
- return {
1016
- name,
1017
- sessionFile,
1018
- promptText: plan.taskText,
1019
- ...(plan.recordModel ? { model: plan.recordModel } : {}),
1020
- };
1021
- } catch (error) {
1022
- lastError = error;
1023
- if (!canFallbackStart(error) || i === input.candidates.length - 1) {
1024
- throw error;
1025
- }
1026
- }
677
+ if (dropped.length && input.origin === "explicit" && candidates.length === 0) {
678
+ throw new SubagentError(`model '${dropped.join(", ")}' cannot be used with kind 'pi'.`, ErrorCodes.INVALID_PARAMS);
1027
679
  }
1028
- throw lastError instanceof Error
1029
- ? lastError
1030
- : new SubagentError("agent start failed", ErrorCodes.START_FAILED);
680
+ return { candidates: candidates.length ? candidates : [undefined], dropped };
1031
681
  }
1032
682
 
1033
- /**
1034
- * Refuse a launch that would exceed the nesting ceiling or the spawn budget.
1035
- *
1036
- * Both are checked BEFORE any resource is created, so a refusal never leaks a
1037
- * pane; without the depth guard the lineage tree would be decorative and
1038
- * nesting could recurse forever.
1039
- */
1040
- private assertWithinBudgets(): void {
1041
- if (this.depth + 1 > this.maxDepth) {
683
+ private assertWithinBudgets(existingChild = false): void {
684
+ if (this.depth + 1 > this.maxDepthValue) {
1042
685
  throw new SubagentError(
1043
- `subagent nesting limit reached (depth ${this.depth}, max ${this.maxDepth}); ` +
1044
- `raise maxSubagentDepth to allow deeper nesting`,
686
+ `subagent nesting limit reached (depth ${this.depth}, max ${this.maxDepthValue}); raise maxSubagentDepth to allow deeper nesting`,
1045
687
  ErrorCodes.BUDGET_EXCEEDED,
1046
688
  );
1047
689
  }
1048
- if (this.maxSpawns !== null && this.spawned >= this.maxSpawns) {
690
+ if (!existingChild && this.maxSpawns !== null && this.spawned >= this.maxSpawns) {
1049
691
  throw new SubagentError(
1050
- `subagent spawn budget exhausted (${this.spawned}/${this.maxSpawns}); ` +
1051
- `raise subagents.maxSubagentSpawnsPerSession to allow more`,
692
+ `subagent spawn budget exhausted (${this.spawned}/${this.maxSpawns}); raise subagents.maxSubagentSpawnsPerSession to allow more`,
1052
693
  ErrorCodes.BUDGET_EXCEEDED,
1053
694
  );
1054
695
  }
1055
696
  }
1056
697
 
1057
- /**
1058
- * Non-pi kinds whose structured collection depends on a herdr integration
1059
- * hook. Keyed by `herdr integration` target name; `pi` itself reports its
1060
- * session path natively (F1) so it is exempt.
1061
- *
1062
- * Only `cursor` today: its chat-store collection is the one wired through
1063
- * `agent_session.source === "herdr:cursor"`. Other non-pi kinds currently
1064
- * collect from the pane by design (F7), so a missing hook there is not a
1065
- * telemetry break — adding them here when their structured channels land.
1066
- */
1067
- // pi-lens-ignore: large-class — static table, checked below
1068
- private static readonly INTEGRATION_DEPENDENT_KINDS = {
1069
- cursor: "cursor",
1070
- } as const satisfies Partial<Record<AgentKind, string>>;
698
+ private lineageEnv(name: string, agent: AgentConfig, teamOverride?: string, nodeId?: string): Record<string, string> {
699
+ const roleDepth = agent.maxSubagentDepth === undefined
700
+ ? Number.POSITIVE_INFINITY
701
+ : Number.isInteger(agent.maxSubagentDepth) && agent.maxSubagentDepth >= 1
702
+ ? agent.maxSubagentDepth
703
+ : 1;
704
+ const env: Record<string, string> = {
705
+ [LINEAGE_ENV]: encodeNestedPath(this.childPath(name)),
706
+ [MAX_DEPTH_ENV]: String(Math.min(this.maxDepthValue, this.depth + roleDepth, MAX_NESTED_PATH_ENTRIES)),
707
+ [CHILD_ENV]: "1",
708
+ [CHILD_ROLE_ENV]: agent.name,
709
+ };
710
+ const team = teamOverride ?? agent.extraFields?.team ?? this.team?.name;
711
+ if (team !== undefined && (team !== DEFAULT_TEAM || teamOverride === DEFAULT_TEAM || this.team?.source === "env")) env[TEAM_ENV] = team;
712
+ if (this.legion && nodeId) Object.assign(env, legionIdentityEnv(this.legion.dbPath, nodeId));
713
+ if (agent.acceptance?.role) env[CHILD_ACCEPTANCE_ROLE_ENV] = agent.acceptance.role;
714
+ if (agent.toolBudget?.maxToolCalls !== undefined) env[MAX_TOOL_CALLS_ENV] = String(agent.toolBudget.maxToolCalls);
715
+ if (agent.turnBudget?.maxTurns !== undefined) env[MAX_TURNS_ENV] = String(agent.turnBudget.maxTurns);
716
+ if (agent.toolTimeoutMs !== undefined) env[TOOL_TIMEOUT_MS_ENV] = String(agent.toolTimeoutMs);
717
+ if (agent.utility) env[UTILITY_CHILD_ENV] = "1";
718
+ // Utility identity takes precedence even when a role was misconfigured
719
+ // with allowNestedSubagents: utility children are always hard leaves.
720
+ if (agent.allowNestedSubagents && !agent.utility) env[ALLOW_NESTED_ENV] = "1";
721
+ return env;
722
+ }
1071
723
 
1072
- /**
1073
- * Ensure the herdr integration hook exists for a hook-dependent kind.
1074
- *
1075
- * The cursor collection path reads the SQLite chat store herdr locates via
1076
- * the sessionStart hook (`~/.cursor/herdr-agent-state.sh` reporting
1077
- * `agent_session.source = "herdr:cursor"`). Without the hook the child
1078
- * still runs — but every completion is misreported
1079
- * `failed: no session jsonl; collected from pane` even when the turn fully
1080
- * succeeded (nj-hw 2026-09-28: planner/advisor all "failed", all actually
1081
- * succeeded with multi-MB chat stores on disk).
1082
- *
1083
- * Contract:
1084
- * - hook present ("current") → proceed, remember per kind
1085
- * - hook missing → `herdr integration install <kind>` (idempotent, verified
1086
- * md5-stable on reinstall), re-check, then proceed
1087
- * - herdr cannot tell (`integration status` unsupported/errored) → proceed
1088
- * silently: an older herdr must not brick launches; the pane path then
1089
- * collects as before (F7 semantics)
1090
- * - install refused (e.g. cursor CLI absent) → refuse the launch with the
1091
- * fix in the message, BEFORE any pane/worktree is allocated — same
1092
- * leak-free invariant as `planModelCandidates` above
1093
- */
1094
- private async ensureIntegrationHook(kind: AgentKind): Promise<void> {
1095
- if (kind === "pi") return;
1096
- const table: Partial<Record<AgentKind, string>> =
1097
- Orchestrator.INTEGRATION_DEPENDENT_KINDS;
1098
- const target = table[kind];
1099
- if (!target) return;
1100
- if (this.integrationChecked.get(kind)) return;
1101
-
1102
- const status = await this.client.integrationStatus(target);
1103
- if (!status.ok || status.value === null) return; // cannot tell → proceed (F7 pane path)
1104
- if (!status.value.startsWith("not installed")) {
1105
- this.integrationChecked.set(kind, true);
1106
- return;
1107
- }
1108
-
1109
- const installed = await this.client.integrationInstall(target);
1110
- if (!installed.ok) {
1111
- throw new SubagentError(
1112
- `herdr's ${target} integration hook is missing and auto-install failed: ` +
1113
- `${installed.error.message}. Without the hook, ${target} children always ` +
1114
- `report "failed: no session jsonl" even when they succeed. ` +
1115
- `Fix: run \`herdr integration install ${target}\` manually, or use a pi-kind role.`,
1116
- ErrorCodes.START_FAILED,
1117
- );
1118
- }
1119
- // Re-check: a hook that reports "not installed" after a successful install
1120
- // (config dir mismatch, wrong user) would silently degrade every launch.
1121
- const verify = await this.client.integrationStatus(target);
1122
- if (verify.ok && verify.value !== null && verify.value.startsWith("not installed")) {
1123
- throw new SubagentError(
1124
- `herdr's ${target} integration hook still reports "not installed" after ` +
1125
- `install (${installed.value.slice(0, 120)}). Check herdr's integration ` +
1126
- `paths for this user, or run \`herdr integration install ${target}\` manually.`,
1127
- ErrorCodes.START_FAILED,
1128
- );
1129
- }
1130
- this.integrationChecked.set(kind, true);
1131
- }
1132
-
1133
- /**
1134
- * Lineage env for a child pane (design §4.2): a grandchild learns its full
1135
- * ancestry and is bounded by the same ceiling.
1136
- */
1137
- private lineageEnv(
1138
- name: string,
1139
- agent?: AgentConfig,
1140
- ): Record<string, string> {
1141
- const env: Record<string, string> = {
1142
- [LINEAGE_ENV]: encodeNestedPath(this.childPath(name)),
1143
- [MAX_DEPTH_ENV]: String(this.maxDepth),
1144
- [CHILD_ENV]: "1",
1145
- [CHILD_ROLE_ENV]: agent?.name ?? "",
1146
- };
1147
- if (
1148
- this.team &&
1149
- (this.team.name !== DEFAULT_TEAM || this.team.source === "env")
1150
- ) {
1151
- env[TEAM_ENV] = this.team.name;
1152
- }
1153
- if (agent?.acceptance?.role) {
1154
- env[CHILD_ACCEPTANCE_ROLE_ENV] = agent.acceptance.role;
1155
- }
1156
- if (agent?.toolBudget?.maxToolCalls !== undefined) {
1157
- env[MAX_TOOL_CALLS_ENV] = String(agent.toolBudget.maxToolCalls);
1158
- }
1159
- if (agent?.turnBudget?.maxTurns !== undefined) {
1160
- env[MAX_TURNS_ENV] = String(agent.turnBudget.maxTurns);
1161
- }
1162
- if (agent?.toolTimeoutMs !== undefined) {
1163
- env[TOOL_TIMEOUT_MS_ENV] = String(agent.toolTimeoutMs);
1164
- }
1165
- if (agent?.allowNestedSubagents) {
1166
- env[ALLOW_NESTED_ENV] = "1";
1167
- }
1168
- return env;
1169
- }
1170
-
1171
- /**
1172
- * Move a child's session file to follow a mid-launch rename so the resume
1173
- * credential stays valid; fall back to creating it if the rename cannot.
1174
- */
1175
- private rehomeSessionFile(from: string, toName: string): string {
1176
- const next = this.sessionFileFor(toName);
1177
- try {
1178
- fs.renameSync(from, next);
1179
- } catch {
1180
- preCreateSessionFile(next);
1181
- }
1182
- return next;
1183
- }
1184
-
1185
- /** Build the child record, register it, and publish the update. */
1186
724
  private recordChild(input: {
1187
725
  name: string;
726
+ nodeId?: string;
1188
727
  agent: AgentConfig;
1189
- paneId: string;
1190
- tabId: string | undefined;
1191
728
  sessionFile: string;
1192
729
  model?: string;
1193
730
  thinking?: string | false;
1194
- modelDropped?: string[];
1195
731
  worktreePath?: string;
1196
732
  worktreeBranch?: string;
1197
- promptText?: string;
1198
733
  }): ChildRecord {
1199
- const { name, agent, sessionFile } = input;
1200
734
  const child: ChildRecord = {
1201
- name,
1202
- paneId: input.paneId,
1203
- sessionFile,
735
+ name: input.name,
736
+ ...(input.nodeId ? { nodeId: input.nodeId } : {}),
737
+ sessionFile: input.sessionFile,
1204
738
  ownerToken: ownerToken(),
1205
739
  state: "working",
1206
740
  spawnedAt: new Date(this.now()).toISOString(),
1207
- agent: agent.name,
1208
- kind: agent.kind,
1209
- // Snapshot the declared criteria: `collect` may run in a later process
1210
- // that cannot re-read this agent definition.
1211
- ...(agent.acceptance?.criteria?.length
1212
- ? {
1213
- pendingCriteria: agent.acceptance.criteria.map((c) => ({
1214
- ...c,
1215
- })),
1216
- }
1217
- : {}),
1218
- ...(agent.onBlocked ? { onBlocked: agent.onBlocked } : {}),
1219
- ...(agent.completionGuard ? { completionGuard: true } : {}),
1220
- ...(input.tabId ? { tabId: input.tabId } : {}),
741
+ agent: input.agent.name,
742
+ kind: input.agent.kind,
743
+ ...(input.agent.acceptance?.criteria?.length ? { pendingCriteria: input.agent.acceptance.criteria.map((criterion) => ({ ...criterion })) } : {}),
744
+ ...(input.agent.onBlocked ? { onBlocked: input.agent.onBlocked } : {}),
745
+ ...(input.agent.completionGuard ? { completionGuard: true } : {}),
1221
746
  ...(input.model ? { model: input.model } : {}),
1222
747
  ...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
1223
- ...(input.modelDropped?.length
1224
- ? { modelDropped: [...input.modelDropped] }
1225
- : {}),
1226
748
  ...(input.worktreePath ? { worktreePath: input.worktreePath } : {}),
1227
749
  ...(input.worktreeBranch ? { worktreeBranch: input.worktreeBranch } : {}),
1228
- ...(input.promptText ? { promptText: input.promptText } : {}),
1229
750
  };
1230
- this.children.set(name, child);
751
+ this.children.set(input.name, child);
1231
752
  this.spawned += 1;
1232
753
  this.onChildUpdate(child);
1233
754
  return child;
1234
755
  }
1235
756
 
1236
- /** Surface the child in the herdr sidebar (design §8.4). */
1237
- private async announceChild(
1238
- child: ChildRecord,
1239
- agentName: string,
1240
- model?: string,
1241
- ): Promise<void> {
1242
- if (!child.paneId) return;
1243
- await this.client.paneReportMetadata({
1244
- paneId: child.paneId,
1245
- source: "pi-legion",
1246
- displayAgent: agentName,
1247
- tokens: {
1248
- agent: agentName,
1249
- model: model ?? "inherit",
1250
- ...(typeof child.thinking === "string"
1251
- ? { thinking: child.thinking }
1252
- : {}),
1253
- run: path.basename(this.runDir),
1254
- },
1255
- });
757
+ async steer(name: string, text: string): Promise<void> {
758
+ const child = this.requireChild(name);
759
+ await this.supervisor.steer(name, text);
760
+ this.emitProcess("node_steered", child.nodeId ?? name, { name, text });
761
+ this.clearBlocked(child);
1256
762
  }
1257
763
 
1258
- /** Send a follow-up prompt to a live child (steering, F10). */
1259
- async steer(name: string, message: string): Promise<void> {
1260
- const res = await this.client.agentPrompt(name, message);
1261
- if (!res.ok) {
1262
- throw new SubagentError(
1263
- `steer failed: ${res.error.message}`,
1264
- res.error.code,
1265
- );
1266
- }
764
+ async followUp(name: string, text: string): Promise<void> {
765
+ const child = this.requireChild(name);
766
+ await this.supervisor.followUp(name, text);
767
+ this.clearBlocked(child);
1267
768
  }
1268
769
 
1269
- /**
1270
- * Wait for the current turn to settle, then derive the outcome (F26-F31).
1271
- *
1272
- * Control plane is Herdr (`agent wait`) for every kind. Session jsonl is
1273
- * only a richer parser when the child actually wrote turns (pi). Otherwise
1274
- * the pane transcript is the result. `agent_status` is never success/failure
1275
- * (F26): it reports "done" for successes, LLM errors, and kills alike.
1276
- */
1277
- async collect(
1278
- name: string,
1279
- opts: { timeoutMs?: number } = {},
1280
- ): Promise<CollectResult> {
1281
- const child = this.children.get(name);
1282
- if (!child)
1283
- throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
1284
-
1285
- if (await this.isAgentBlocked(name)) return this.blockedResult(child);
1286
-
1287
- const timeoutMs = opts.timeoutMs ?? DEFAULTS.turnTimeoutMs;
1288
- let deadline = this.now() + timeoutMs;
1289
- // The chat dir may not exist yet at launch (cursor creates it lazily),
1290
- // so it is resolved per read, not cached — a launch-time null must not
1291
- // pin the whole collect to the pane path.
1292
- const chatDirNow = () => this.cursorChatDirOf(child);
1293
- const cursorChat = await chatDirNow();
1294
- const initial = cursorChat
1295
- ? parseCursorChat(cursorChat)
1296
- : parseSessionFile(child.sessionFile);
1297
-
1298
- const alreadySettled =
1299
- cursorChat && cursorTurnSettled(initial)
1300
- ? true
1301
- : isLastTurnComplete(initial);
1302
- let wait = alreadySettled
1303
- ? "settled"
1304
- : initial.turns.length > 0
1305
- ? await this.awaitTurn(child, initial, deadline, await chatDirNow())
1306
- : await this.awaitHerdrSettle(child, deadline);
1307
- // D: a timeout is only a verdict when the child's artifact is QUIET.
1308
- // While the session jsonl (or cursor store) is still growing the agent is
1309
- // demonstrably working, so grant a bounded extension instead of reporting
1310
- // `running` at the exact deadline. Fully sequential — no second waiter —
1311
- // so there is no race with the wait above.
1312
- for (
1313
- let grace = 0;
1314
- wait === "timeout" && grace < COLLECT_GRACE_EXTENSIONS;
1315
- grace += 1
1316
- ) {
1317
- const chatForProbe = await chatDirNow();
1318
- if (!(await this.collectArtifactGrowing(child, chatForProbe))) break;
1319
- // Extend by a full slice off the EXISTING deadline rather than
1320
- // re-basing on `now`: the probe already consumed one poll interval,
1321
- // so `now + timeoutMs` would drift past the (1+N)×timeoutMs bound.
1322
- deadline += timeoutMs;
1323
- wait =
1324
- initial.turns.length > 0
1325
- ? await this.awaitTurn(child, initial, deadline, chatForProbe)
1326
- : await this.awaitHerdrSettle(child, deadline);
1327
- }
1328
- if (wait === "blocked") return this.blockedResult(child);
1329
- const timedOut = wait === "timeout";
1330
-
1331
- // Re-resolve after the wait: the store appears (and the answer lands in
1332
- // it) while the child runs, so the initial read above is stale by now.
1333
- const chatAtCollect = await chatDirNow();
1334
- const parsed = chatAtCollect
1335
- ? parseCursorChat(chatAtCollect)
1336
- : parseSessionFile(child.sessionFile);
1337
- if (parsed.turns.length > 0) {
1338
- return this.finishCollect(
1339
- child,
1340
- parsed,
1341
- await this.resolveExecution(name, parsed, timedOut, timeoutMs),
1342
- deadline,
1343
- );
1344
- }
1345
-
1346
- if (wait === "gone") {
1347
- return this.finishCollect(
1348
- child,
1349
- parsed,
1350
- {
1351
- status: "aborted",
1352
- reason: "herdr agent gone (tab or pane closed)",
1353
- model: child.model ?? null,
1354
- },
1355
- deadline,
1356
- await this.readPaneOutput(child),
1357
- );
1358
- }
1359
-
1360
- return this.finishCollect(
1361
- child,
1362
- parsed,
1363
- await this.executionFromPane(child, timedOut, timeoutMs),
1364
- deadline,
1365
- await this.readPaneOutput(child),
1366
- );
770
+ async abort(name: string): Promise<void> {
771
+ const child = this.requireChild(name);
772
+ await this.supervisor.abort(name);
773
+ this.emitProcess("node_aborted", child.nodeId ?? name, { name });
1367
774
  }
1368
775
 
1369
- private async finishCollect(
1370
- child: ChildRecord,
1371
- parsed: ReturnType<typeof parseSessionFile>,
1372
- execution: Execution,
1373
- deadline: number,
1374
- paneOutput?: string,
1375
- ): Promise<CollectResult> {
1376
- const output = paneOutput ?? parsed.output;
1377
- const lastTurnOutput =
1378
- paneOutput !== undefined
1379
- ? stripPromptEcho(paneOutput, child.promptText)
1380
- : parsed.lastTurnOutput;
1381
- const forVerdict =
1382
- paneOutput !== undefined
1383
- ? { ...parsed, lastTurnOutput, output: paneOutput }
1384
- : parsed;
1385
- const acceptance = await applyVerification(
1386
- deriveAcceptance(forVerdict, execution, child.pendingCriteria, {
1387
- ...(child.completionGuard ? { completionGuard: true } : {}),
1388
- }),
1389
- {
1390
- cwd: child.worktreePath ?? this.cwd,
1391
- criteria: child.pendingCriteria,
1392
- run: this.verifyRunner,
1393
- timeoutMs: Math.max(5_000, deadline - this.now()),
1394
- },
1395
- );
1396
-
1397
- // C: only a real terminal outcome retires the child into `awaiting`. A
1398
- // `running` snapshot means collect timed out while the agent is still
1399
- // alive (F29) — flipping the record to `awaiting` made the parent read
1400
- // `status` as "turn over, just needs wrapping up". Keep it working so
1401
- // watch()'s re-arm (A) and any later collect still treat it as live.
1402
- if (execution.status !== "running") child.state = "awaiting";
1403
- child.execution = execution;
1404
- child.acceptance = acceptance;
1405
- this.onChildUpdate(child);
1406
-
1407
- // Persist the FULL output next to the session file. The parent's
1408
- // completion notice carries only a bounded preview; without a durable
1409
- // full-text artifact the parent must re-derive the text from the session
1410
- // jsonl (pi) or the SQLite chat store (cursor) by hand — every time.
1411
- // A `running` snapshot is a mid-turn partial, not a result: skip it so
1412
- // the file on disk is always a terminal answer. An EMPTY terminal output
1413
- // must also clear any EARLIER turn's artifact (stale vintage would hand
1414
- // the previous answer to a later cached collect as this turn's result).
1415
- let outputFile: string | undefined;
1416
- if (execution.status === "running") {
1417
- child.outputFile = undefined;
1418
- } else {
1419
- outputFile = this.writeOutputFile(child, output);
1420
- // Record the truth on the child: cachedCollect reads this, never a
1421
- // bare existsSync (which cannot tell turns apart).
1422
- child.outputFile = outputFile;
1423
- }
1424
- this.onChildUpdate(child);
1425
-
1426
- return {
1427
- execution,
1428
- output,
1429
- ...(outputFile ? { outputFile } : {}),
1430
- usage: parsed.usage,
1431
- model: parsed.model ?? child.model ?? null,
1432
- acceptance,
1433
- };
1434
- }
1435
-
1436
- /** Path of a child's persisted full-output artifact. */
1437
- private outputFileFor(name: string): string {
1438
- return path.join(this.runDir, `${name}.output.md`);
1439
- }
1440
-
1441
- /** Write the terminal output to disk; undefined when empty or unwritable.
1442
- *
1443
- * A terminal-but-empty output returns undefined AFTER removing a stale
1444
- * artifact from an earlier turn, so the run dir and ChildRecord agree. */
1445
- private writeOutputFile(
1446
- child: ChildRecord,
1447
- output: string,
1448
- ): string | undefined {
1449
- const file = this.outputFileFor(child.name);
1450
- const trimmed = output.trim();
1451
- if (!trimmed) {
1452
- try {
1453
- fs.rmSync(file, { force: true });
1454
- } catch {
1455
- // best-effort: the record no longer names it either way
1456
- }
1457
- return undefined;
1458
- }
1459
- try {
1460
- fs.writeFileSync(file, `${trimmed}\n`, { mode: 0o600 });
1461
- return file;
1462
- } catch {
1463
- // Best-effort: the preview still carries the text head, and the
1464
- // session file remains the fallback source.
1465
- return undefined;
1466
- }
1467
- }
1468
-
1469
- private async readPaneOutput(child: ChildRecord): Promise<string> {
1470
- if (!child.paneId) return "";
1471
- const read = await this.client.paneRead(child.paneId, {
1472
- source: "recent-unwrapped",
1473
- lines: 200,
1474
- });
1475
- return read.ok ? read.value : "";
776
+ private requireChild(name: string): ChildRecord {
777
+ const child = this.children.get(name);
778
+ if (!child) throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
779
+ return child;
1476
780
  }
1477
781
 
1478
- /**
1479
- * The child's cursor chat store directory, when it has one.
1480
- *
1481
- * herdr reports the chat id as `agent_session.value` for cursor children;
1482
- * the id is the directory name under `~/.cursor/chats/<project>/<id>/`.
1483
- * Returns null for pi kinds, unreadable ids, or a chat not yet on disk —
1484
- * the caller then falls back to the pane path.
1485
- */
1486
- private async cursorChatDirOf(child: ChildRecord): Promise<string | null> {
1487
- if (child.kind !== "cursor") return null;
1488
- const agentState = await this.client.agentGet(child.name);
1489
- if (!agentState.ok) return null;
1490
- const chatId = agentState.value.agent_session?.value;
1491
- if (!chatId) return null;
1492
- return findCursorChatDir(chatId, {
1493
- cwd: child.worktreePath ?? this.cwd,
1494
- ...(this.cursorChatsRoot ? { chatsRoot: this.cursorChatsRoot } : {}),
1495
- });
782
+ private pendingDialogs(name: string): PendingUIRequest[] {
783
+ return (this.uiProxy?.pending() ?? []).filter((request) => request.childName === name && isApprovalRequest(request));
1496
784
  }
1497
785
 
1498
- /**
1499
- * Outcome of a non-pi child, derived from its pane (no session jsonl — F7).
1500
- *
1501
- * The design contract (design.md §802, F7) pins non-pi kinds to `unknown`:
1502
- * without a session stopReason there is no authoritative success signal, and
1503
- * a pane reply is not one. Do NOT promote this to `success` — the lying part
1504
- * is elsewhere (see notify.completionStatusOf).
1505
- */
1506
- private async executionFromPane(
1507
- child: ChildRecord,
1508
- timedOut: boolean,
1509
- timeoutMs: number,
1510
- ): Promise<Execution> {
1511
- if (!timedOut) {
1512
- return {
1513
- status: "unknown",
1514
- reason: "no session jsonl; collected from pane",
1515
- model: child.model ?? null,
1516
- };
1517
- }
1518
- const agentState = await this.client.agentGet(child.name);
1519
- if (agentState.ok || !agentGone(agentState)) {
1520
- // Not found means gone; any OTHER failure (a wedged/timed-out CLI,
1521
- // transport error) says nothing about the child, so assume alive.
1522
- // Reporting `aborted` here would retire a LIVE child (F29 is only a
1523
- // verdict for a genuinely missing agent).
1524
- return {
1525
- status: "running",
1526
- reason: agentState.ok
1527
- ? `collect timed out after ${timeoutMs}ms; the agent is still alive`
1528
- : `collect timed out after ${timeoutMs}ms; agent status unavailable (${agentState.error.code}), assuming alive`,
1529
- model: child.model ?? null,
1530
- };
786
+ async approveBlocked(name: string): Promise<void> {
787
+ for (const request of this.pendingDialogs(name)) {
788
+ if (request.request.method === "confirm") this.uiProxy?.respond(request.id, { confirmed: true });
1531
789
  }
1532
- return {
1533
- status: "aborted",
1534
- reason: "herdr agent gone (tab or pane closed)",
1535
- model: child.model ?? null,
1536
- };
1537
- }
1538
-
1539
- /**
1540
- * Return a previously collected snapshot without waiting on the child.
1541
- *
1542
- * Used when the parent model calls `collect` after auto-watch already
1543
- * derived the outcome (and possibly recycled the pane).
1544
- */
1545
- cachedCollect(name: string): CollectResult | undefined {
1546
790
  const child = this.children.get(name);
1547
- if (!child?.execution) return undefined;
1548
- if (!canUseCachedCollect(child.state)) return undefined;
1549
- const parsed = fs.existsSync(child.sessionFile)
1550
- ? parseSessionFile(child.sessionFile)
1551
- : emptyParsedSession();
1552
- // Read the recorded truth, not existsSync: the file on disk may be an
1553
- // EARLIER turn's artifact (this turn's collect wrote none), and a fresh
1554
- // `running` snapshot must not resurrect it either.
1555
- const cached: CollectResult = {
1556
- execution: child.execution,
1557
- output: parsed.output,
1558
- usage: parsed.usage ?? child.execution.usage ?? null,
1559
- model: parsed.model ?? child.execution.model ?? null,
1560
- acceptance:
1561
- child.acceptance ?? { status: "unknown", level: "none" },
1562
- ...(child.state === "blocked" ? { blocked: true } : {}),
1563
- };
1564
- if (child.outputFile) cached.outputFile = child.outputFile;
1565
- return cached;
1566
- }
1567
-
1568
- /** Unblock a child after the parent approved the pending tool. */
1569
- async approveBlocked(name: string): Promise<void> {
1570
- this.clearBlocked(name);
1571
- await bestEffort(this.client.agentSendKeys(name, "y"));
791
+ if (child) this.clearBlocked(child);
1572
792
  }
1573
793
 
1574
- /** Unblock a child after the parent denied the pending tool. */
1575
794
  async rejectBlocked(name: string): Promise<void> {
1576
- this.clearBlocked(name);
1577
- await bestEffort(this.client.agentSendKeys(name, "n"));
795
+ for (const request of this.pendingDialogs(name)) {
796
+ if (request.request.method === "confirm") this.uiProxy?.respond(request.id, { confirmed: false });
797
+ }
798
+ const child = this.children.get(name);
799
+ if (child) this.clearBlocked(child);
1578
800
  }
1579
801
 
1580
- /**
1581
- * Herdr-native settle: sliced `agent wait` then a session-file quiet window.
1582
- * Used when jsonl has no turns yet (any kind, including pi before first write)
1583
- * and as phase 2 of `awaitTurn`.
1584
- *
1585
- * Slices rather than one remaining-timeout wait so F15 `tab close` surfaces
1586
- * as `gone` instead of hanging until the worker timeout.
1587
- */
1588
- private async awaitHerdrSettle(
1589
- child: ChildRecord,
1590
- deadline: number,
1591
- ): Promise<"settled" | "timeout" | "blocked" | "gone"> {
1592
- while (this.now() < deadline) {
1593
- const presence = await this.agentPresence(child.name);
1594
- if (presence === "blocked") return "blocked";
1595
- if (presence === "gone") return "gone";
1596
- const remaining = Math.max(1, deadline - this.now());
1597
- const waited = await this.client.agentWait(child.name, {
1598
- timeoutMs: Math.min(remaining, this.waitSliceMs),
1599
- });
1600
- if (waited.ok) {
1601
- if (child.kind === "pi") {
1602
- await this.waitForQuiet(child.sessionFile, deadline);
1603
- }
1604
- const after = await this.agentPresence(child.name);
1605
- if (after === "blocked") return "blocked";
1606
- if (after === "gone") return "gone";
1607
- if (await this.nonPiPaneStillWorking(child)) {
1608
- continue;
1609
- }
1610
- return "settled";
1611
- }
1612
- // `agent wait` failed. Distinguish "agent gone" from a transient CLI
1613
- // failure (a wedged/timed-out command surfaces as a generic error):
1614
- // ONE extra agentGet answers both presence questions, instead of two
1615
- // calls that — under a wedged CLI — each burn the full command
1616
- // timeout and stretch one loop iteration past the deadline.
1617
- const afterFailure = await this.agentPresence(child.name);
1618
- if (afterFailure === "gone") return "gone";
1619
- if (afterFailure === "blocked") return "blocked";
1620
- if (this.now() >= deadline) return "timeout";
1621
- await this.sleep(this.pollIntervalMs);
1622
- }
1623
- return "timeout";
802
+ private clearBlocked(child: ChildRecord): void {
803
+ if (child.state !== "blocked") return;
804
+ child.state = "working";
805
+ child.execution = undefined;
806
+ this.onChildUpdate(child);
1624
807
  }
1625
808
 
1626
- /**
1627
- * Non-pi kinds have no jsonl, so `agent wait` + an empty-file quiet window
1628
- * is not a turn boundary. Cursor in particular collapses a large prompt
1629
- * into `[Pasted text #N]` and looks idle to herdr — collect used to return
1630
- * in ~7s and recycle the pane while the child was still Working.
1631
- *
1632
- * Keep waiting until the pane has a live reply. While the TUI is still on
1633
- * trust / paste chrome WITH a non-empty input box, send Enter and keep
1634
- * polling.
1635
- *
1636
- * The nudge must be RETRIED, not sent once: measured on a live cursor pane,
1637
- * a single early Enter was swallowed and the child sat on
1638
- * `→ [Pasted text #1 +82 lines]` until the collect deadline. The pane only
1639
- * accepts the paste once the TUI has finished ingesting it, and the input
1640
- * box then returns to its `Add a follow-up` placeholder — that transition is
1641
- * what stops the retries, so a healthy long turn is never pressed at.
1642
- */
1643
- private async nonPiPaneStillWorking(
1644
- child: ChildRecord,
1645
- ): Promise<boolean> {
1646
- if (child.kind === "pi") return false;
1647
- if (!child.paneId) return false;
1648
- // Structured channel first: when the cursor chat store already shows a
1649
- // settled turn, the reply is in hand and the pane's rendering is
1650
- // irrelevant (it can lag the store or wrap the text).
1651
- const chatDir = await this.cursorChatDirOf(child);
1652
- const structured = chatDir ? parseCursorChat(chatDir) : null;
1653
- if (structured && cursorTurnSettled(structured)) {
1654
- return false;
809
+ async collect(name: string, opts: { timeoutMs?: number; signal?: AbortSignal } = {}): Promise<CollectResult> {
810
+ const child = this.requireChild(name);
811
+ const abortedSnapshot = (): CollectResult => this.interruptedCollect(child, parseSessionFile(child.sessionFile));
812
+ if (opts.signal?.aborted) return abortedSnapshot();
813
+ if (this.pendingDialogs(name).length) return this.blockedResult(child);
814
+ const timeoutMs = opts.timeoutMs ?? DEFAULTS.turnTimeoutMs;
815
+ let deadline = this.now() + timeoutMs;
816
+ const initial = parseSessionFile(child.sessionFile);
817
+ // A connection blip writes stopReason "error" before the client retries.
818
+ // That looks like a finished turn, but the RPC child is still in it.
819
+ // Skipping the supervisor wait here is what retired a live worker.
820
+ let wait: "settled" | "timeout" | "blocked" | "gone" | "aborted" = isLastTurnComplete(initial) && !this.liveConnectionBlip(child, initial)
821
+ ? "settled"
822
+ : await this.awaitSupervisor(child, deadline, opts.signal);
823
+ if (wait === "aborted" || opts.signal?.aborted) return abortedSnapshot();
824
+ for (let attempt = 0; wait === "timeout" && attempt < COLLECT_GRACE_EXTENSIONS; attempt += 1) {
825
+ if (opts.signal?.aborted) return abortedSnapshot();
826
+ if (!(await this.collectArtifactGrowing(child, opts.signal))) break;
827
+ if (opts.signal?.aborted) return abortedSnapshot();
828
+ deadline += timeoutMs;
829
+ wait = await this.awaitSupervisor(child, deadline, opts.signal);
830
+ if (wait === "aborted" || opts.signal?.aborted) return abortedSnapshot();
1655
831
  }
1656
- const paneOutput = await this.readPaneOutput(child);
1657
- // A live spinner / token counter / `ctrl+c to stop` means the turn is
1658
- // still running. Without this the half-streamed answer tripped the reply
1659
- // test below, collect returned early, and the child was reported failed
1660
- // while it was still writing.
1661
- if (paneIsBusy(paneOutput)) {
1662
- await this.sleep(this.pollIntervalMs);
1663
- return true;
832
+ if (wait === "blocked") return this.blockedResult(child);
833
+ let parsed = parseSessionFile(child.sessionFile);
834
+ if (wait === "settled" && countAssistantMessages(parsed) > 0) {
835
+ await this.waitForQuiet(child.sessionFile, deadline, opts.signal);
836
+ if (opts.signal?.aborted) return abortedSnapshot();
1664
837
  }
1665
- // With a chat store, the STORE settles the turn — never the pane's
1666
- // rendered text. Measured: the TUI wraps the banner/model name/Tip across
1667
- // lines in a different shape every run, so "pane looks like a reply" is
1668
- // not a signal. The pane remains responsible only for the input side
1669
- // (submitting the paste) below.
1670
- if (!structured) {
1671
- if (paneHasLiveReply(stripPromptEcho(paneOutput, child.promptText))) {
1672
- return false;
838
+ if (opts.signal?.aborted) return abortedSnapshot();
839
+ parsed = parseSessionFile(child.sessionFile);
840
+ let execution = deriveOutcome(parsed);
841
+ if (wait === "timeout" && this.supervisor.isAlive(name) && !isLastTurnComplete(parsed)) {
842
+ // `timeoutMs` is the budget from launch, not the length of this status check.
843
+ execution = { ...execution, status: "running", reason: COLLECT_DEADLINE_REASON };
844
+ } else if (wait === "gone" && parsed.turns.length === 0) {
845
+ execution = { status: "aborted", reason: "RPC child exited before writing session JSONL", model: child.model ?? null };
846
+ } else if (this.supervisor.isAlive(name) && isTransientConnectionFailure(execution)) {
847
+ // Same non-terminal signal as the deadline path: watch() re-arms on
848
+ // `running` and does not retire. An already-settled blip has to keep
849
+ // waiting here, or the next collect would reproduce it instantly.
850
+ if (wait !== "timeout") {
851
+ const held = await this.waitOutTransientConnection(child, deadline, opts.signal);
852
+ if (held === "aborted" || opts.signal?.aborted) return abortedSnapshot();
853
+ if (held === "blocked") return this.blockedResult(child);
854
+ parsed = parseSessionFile(child.sessionFile);
855
+ execution = deriveOutcome(parsed);
1673
856
  }
1674
- }
1675
- // Still working. Return true so `awaitHerdrSettle` keeps polling; the
1676
- // deadline is enforced by its own loop condition, which surfaces as
1677
- // `timeout` (→ `running`, pane kept) rather than a false `settled`.
1678
- if (paneNeedsSubmitNudge(paneOutput)) {
1679
- if (this.now() - this.lastNudgeAt(child.name) >= this.nudgeIntervalMs) {
1680
- this.nudgeTimestamps.set(child.name, this.now());
1681
- await bestEffort(this.client.agentSendKeys(child.name, "enter"));
857
+ if (this.supervisor.isAlive(name) && (isTransientConnectionFailure(execution) || !isLastTurnComplete(parsed))) {
858
+ execution = { ...execution, status: "running", reason: TRANSIENT_CONNECTION_REASON };
859
+ } else if (!this.supervisor.isAlive(name) && parsed.turns.length === 0) {
860
+ execution = { status: "aborted", reason: "RPC child exited before writing session JSONL", model: child.model ?? null };
1682
861
  }
1683
862
  }
1684
- await this.sleep(this.pollIntervalMs);
1685
- return true;
863
+ return this.finishCollect(child, parsed, execution, deadline);
1686
864
  }
1687
865
 
1688
- /** When `name` was last sent a paste-submit Enter (0 = never). */
1689
- private lastNudgeAt(name: string): number {
1690
- return this.nudgeTimestamps.get(name) ?? 0;
866
+ /** True when the session's latest outcome is a connection blip and the process is up. */
867
+ private liveConnectionBlip(child: ChildRecord, parsed: ReturnType<typeof parseSessionFile>): boolean {
868
+ return this.supervisor.isAlive(child.name) && isTransientConnectionFailure(deriveOutcome(parsed));
1691
869
  }
1692
870
 
1693
871
  /**
1694
- * Wait for the child's current turn to start and then settle.
1695
- *
1696
- * Two phases, because they answer different questions: phase 1 asks "did the
1697
- * turn produce anything at all?" (a collect issued right after launch would
1698
- * otherwise read the previous, empty state and report "unknown"), phase 2
1699
- * waits for that turn to stop growing.
872
+ * Hold a live child whose session currently ends on a connection blip.
1700
873
  *
1701
- * Bounded by BOTH the deadline and an iteration cap: if an injected clock does
1702
- * not advance with `sleep`, the deadline alone would spin forever.
1703
- *
1704
- * @returns whether the turn settled, timed out, hit a tool approval, or the
1705
- * herdr agent disappeared (tab/pane close).
874
+ * Returns once the session moves past that blip, the process exits, a UI
875
+ * approval arrives, the parent aborts, or the cumulative deadline passes.
1706
876
  */
1707
- private async awaitTurn(
877
+ private async waitOutTransientConnection(
1708
878
  child: ChildRecord,
1709
- initial: ReturnType<typeof parseSessionFile>,
1710
879
  deadline: number,
1711
- cursorChat?: string | null,
1712
- ): Promise<"settled" | "timeout" | "blocked" | "gone"> {
1713
- const before = countAssistantMessages(initial);
1714
- const timeoutMs = deadline - this.now();
1715
- const maxPolls = Math.max(1, Math.ceil(timeoutMs / this.pollIntervalMs)) + 10;
1716
-
1717
- let progressed = false;
880
+ signal?: AbortSignal,
881
+ ): Promise<"aborted" | "blocked" | "done"> {
882
+ const maxPolls = Math.max(1, Math.ceil(Math.max(0, deadline - this.now()) / POLL_INTERVAL_MS));
1718
883
  for (let poll = 0; poll < maxPolls; poll += 1) {
1719
- const presence = await this.agentPresence(child.name);
1720
- if (presence === "blocked") return "blocked";
1721
- if (presence === "gone") return "gone";
1722
- const parsed = cursorChat
1723
- ? parseCursorChat(cursorChat)
1724
- : parseSessionFile(child.sessionFile);
1725
- if (countAssistantMessages(parsed) > before) {
1726
- progressed = true;
1727
- break;
1728
- }
1729
- if (this.now() >= deadline) break;
1730
- await this.sleep(this.pollIntervalMs);
1731
- }
1732
-
1733
- // Nothing ever appeared: gone is an abort; otherwise the caller gave up.
1734
- if (!progressed) {
1735
- if (await this.isAgentGone(child.name)) return "gone";
1736
- return "timeout";
884
+ if (signal?.aborted) return "aborted";
885
+ if (this.pendingDialogs(child.name).length) return "blocked";
886
+ if (!this.supervisor.isAlive(child.name)) return "done";
887
+ if (!isTransientConnectionFailure(deriveOutcome(parseSessionFile(child.sessionFile)))) return "done";
888
+ if (this.now() >= deadline) return "done";
889
+ if (await this.sleepOrAbort(POLL_INTERVAL_MS, signal)) return "aborted";
1737
890
  }
1738
-
1739
- return this.awaitHerdrSettle(child, deadline);
891
+ return "done";
1740
892
  }
1741
893
 
1742
- private async agentPresence(
1743
- name: string,
1744
- ): Promise<"blocked" | "gone" | "live"> {
1745
- const agentState = await this.client.agentGet(name);
1746
- if (!agentState.ok) {
1747
- return agentGone(agentState) ? "gone" : "live";
1748
- }
1749
- return agentState.value.agent_status === "blocked" ? "blocked" : "live";
894
+ private interruptedCollect(child: ChildRecord, parsed: ReturnType<typeof parseSessionFile>): CollectResult {
895
+ return {
896
+ execution: { status: "running", reason: "aborted by parent" },
897
+ output: parsed.output,
898
+ usage: parsed.usage,
899
+ model: parsed.model ?? child.model ?? null,
900
+ acceptance: { status: "unknown", level: "none", reason: "aborted by parent" },
901
+ };
1750
902
  }
1751
903
 
1752
- private async isAgentBlocked(name: string): Promise<boolean> {
1753
- return (await this.agentPresence(name)) === "blocked";
904
+ private async awaitSupervisor(
905
+ child: ChildRecord,
906
+ deadline: number,
907
+ signal?: AbortSignal,
908
+ ): Promise<"settled" | "timeout" | "blocked" | "gone" | "aborted"> {
909
+ if (signal?.aborted) return "aborted";
910
+ if (this.pendingDialogs(child.name).length) return "blocked";
911
+ let pending = signal ? undefined : this.pendingWaits.get(child.name);
912
+ if (!pending) {
913
+ const wait = this.supervisor.waitSettled(
914
+ child.name,
915
+ Math.max(1, deadline - this.now()),
916
+ ...(signal ? [signal] : []),
917
+ );
918
+ pending = wait;
919
+ if (!signal) {
920
+ this.pendingWaits.set(child.name, pending);
921
+ const current = pending;
922
+ void current.then(
923
+ () => { if (this.pendingWaits.get(child.name) === current) this.pendingWaits.delete(child.name); },
924
+ () => { if (this.pendingWaits.get(child.name) === current) this.pendingWaits.delete(child.name); },
925
+ );
926
+ }
927
+ }
928
+ let unsubscribe: (() => void) | undefined;
929
+ let removeAbortListener: (() => void) | undefined;
930
+ try {
931
+ const waitForSettle = pending.then((settled) =>
932
+ settled.reason === "aborted by parent"
933
+ ? "aborted" as const
934
+ : this.settleDisposition(settled, child.name),
935
+ );
936
+ if (!this.uiProxy && !signal) return await waitForSettle;
937
+ const waitForChildEvent = waitForSettle.then((result) => {
938
+ if (result === "settled" && child.state === "retired") return "gone" as const;
939
+ return result;
940
+ });
941
+ const blocked = new Promise<"blocked">((resolve) => {
942
+ if (!this.uiProxy) return;
943
+ unsubscribe = this.uiProxy.onRequest((request) => {
944
+ if (request.childName !== child.name || !isApprovalRequest(request) || child.state === "retired") return;
945
+ child.state = "blocked";
946
+ this.onChildUpdate(child);
947
+ resolve("blocked");
948
+ });
949
+ });
950
+ if (this.pendingDialogs(child.name).length) return "blocked";
951
+ const races: Array<Promise<"settled" | "timeout" | "blocked" | "gone" | "aborted">> = [waitForChildEvent];
952
+ if (this.uiProxy) races.push(blocked);
953
+ if (signal) {
954
+ races.push(new Promise((resolve) => {
955
+ const onAbort = () => resolve("aborted");
956
+ removeAbortListener = () => signal.removeEventListener("abort", onAbort);
957
+ if (signal.aborted) onAbort();
958
+ else signal.addEventListener("abort", onAbort, { once: true });
959
+ }));
960
+ }
961
+ return await Promise.race(races);
962
+ } finally {
963
+ unsubscribe?.();
964
+ removeAbortListener?.();
965
+ }
1754
966
  }
1755
967
 
1756
- private async isAgentGone(name: string): Promise<boolean> {
1757
- return (await this.agentPresence(name)) === "gone";
968
+ private settleDisposition(result: SettleResult, name: string): "settled" | "timeout" | "gone" {
969
+ if (result.settled) return "settled";
970
+ if (result.reason === "timeout" || (!result.abnormal && this.supervisor.isAlive(name))) return "timeout";
971
+ // A connection blip reported as an abnormal settle must not look like
972
+ // the process exited while that process is still alive.
973
+ if (this.supervisor.isAlive(name) && isTransientConnectionFailure(result.reason)) return "timeout";
974
+ return "gone";
1758
975
  }
1759
976
 
1760
977
  private blockedResult(child: ChildRecord): CollectResult {
1761
978
  const parsed = parseSessionFile(child.sessionFile);
1762
- const execution: Execution = {
1763
- status: "running",
1764
- reason: "blocked: waiting for approval",
1765
- };
1766
- const acceptance = deriveAcceptance(
1767
- parsed,
1768
- execution,
1769
- child.pendingCriteria,
1770
- {
1771
- ...(child.completionGuard ? { completionGuard: true } : {}),
1772
- },
979
+ const execution: Execution = { status: "running", reason: "blocked: waiting for a child UI approval" };
980
+ const acceptance = deriveAcceptance(parsed, execution, child.pendingCriteria, {
981
+ ...(child.completionGuard ? { completionGuard: true } : {}),
982
+ });
983
+ if (child.state !== "retired") {
984
+ child.state = "blocked";
985
+ child.execution = execution;
986
+ child.acceptance = acceptance;
987
+ this.onChildUpdate(child);
988
+ }
989
+ return { execution, output: parsed.output, usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance, blocked: true };
990
+ }
991
+
992
+ private async finishCollect(child: ChildRecord, parsed: ReturnType<typeof parseSessionFile>, execution: Execution, deadline: number): Promise<CollectResult> {
993
+ const acceptance = await applyVerification(
994
+ deriveAcceptance(parsed, execution, child.pendingCriteria, { ...(child.completionGuard ? { completionGuard: true } : {}) }),
995
+ { cwd: child.worktreePath ?? this.cwd, criteria: child.pendingCriteria, run: this.verifyRunner, timeoutMs: Math.max(5_000, deadline - this.now()) },
1773
996
  );
1774
- child.state = "blocked";
997
+ const isRetired = () => child.state === "retired";
998
+ // A running child can finish its in-flight collect while an explicit stop
999
+ // is retiring it. Record the result, but never demote a retired lifecycle
1000
+ // state back to awaiting; only a later launch/resume may revive that child.
1001
+ if (execution.status !== "running" && !isRetired()) child.state = "awaiting";
1775
1002
  child.execution = execution;
1776
1003
  child.acceptance = acceptance;
1777
- this.onChildUpdate(child);
1778
- return {
1779
- execution,
1780
- output: parsed.output,
1781
- usage: parsed.usage,
1782
- model: parsed.model,
1783
- acceptance,
1784
- blocked: true,
1785
- };
1004
+ if (execution.status !== "running") this.recordSettled(child, execution);
1005
+ if (!isRetired()) this.onChildUpdate(child);
1006
+ const output = execution.status !== "running" && parsed.lastTurnOutput === null ? "" : parsed.output;
1007
+ if (isRetired()) {
1008
+ return { execution, output, usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance };
1009
+ }
1010
+ let outputFile: string | undefined;
1011
+ if (execution.status === "running") child.outputFile = undefined;
1012
+ else {
1013
+ outputFile = this.writeOutputFile(child, output);
1014
+ child.outputFile = outputFile;
1015
+ }
1016
+ if (!isRetired()) this.onChildUpdate(child);
1017
+ return { execution, output, ...(outputFile ? { outputFile } : {}), usage: parsed.usage, model: parsed.model ?? child.model ?? null, acceptance };
1786
1018
  }
1787
1019
 
1788
- private clearBlocked(name: string): void {
1789
- const child = this.children.get(name);
1790
- if (!child) return;
1791
- child.state = "working";
1792
- child.execution = undefined;
1793
- this.onChildUpdate(child);
1794
- }
1020
+ private outputFileFor(name: string): string { return path.join(this.runDir, `${name}.output.md`); }
1795
1021
 
1796
- /**
1797
- * Derive the outcome, disambiguating a timeout from a real abort.
1798
- *
1799
- * Both present as "no reply to the last prompt" (F29), so the discriminator
1800
- * is whether the agent is still alive:
1801
- * alive + no reply -> still running (we timed out)
1802
- * gone + no reply -> aborted (killed mid-turn)
1803
- */
1804
- private async resolveExecution(
1805
- name: string,
1806
- parsed: ReturnType<typeof parseSessionFile>,
1807
- timedOut: boolean,
1808
- timeoutMs: number,
1809
- ): Promise<Execution> {
1810
- const execution = deriveOutcome(parsed);
1811
- if (!timedOut || execution.status !== "aborted") return execution;
1812
-
1813
- const agentState = await this.client.agentGet(name);
1814
- // Only a definitive NOT_FOUND means the agent is gone. Any other error
1815
- // (a wedged/timed-out CLI) must NOT flip `aborted` back — but it also
1816
- // must not CONFIRM it: agentStatus.ok means alive (the running branch),
1817
- // while a transport failure leaves the derived outcome standing, which
1818
- // is the pre-timeout behaviour for a hard kill (F29).
1819
- if (!agentState.ok) {
1820
- return agentGone(agentState)
1821
- ? execution
1822
- : {
1823
- ...execution,
1824
- status: "running",
1825
- reason: `collect timed out after ${timeoutMs}ms; agent status unavailable (${agentState.error.code}), assuming alive`,
1826
- };
1022
+ private writeOutputFile(child: ChildRecord, output: string): string | undefined {
1023
+ const file = this.outputFileFor(child.name);
1024
+ const trimmed = output.trim();
1025
+ if (!trimmed) {
1026
+ try { fs.rmSync(file, { force: true }); } catch { /* stale output is best-effort cleanup */ }
1027
+ return undefined;
1827
1028
  }
1828
-
1829
- return {
1830
- ...execution,
1831
- status: "running",
1832
- reason: `collect timed out after ${timeoutMs}ms; the agent is still alive`,
1833
- };
1029
+ try {
1030
+ fs.writeFileSync(file, `${trimmed}\n`, { mode: 0o600 });
1031
+ return file;
1032
+ } catch { return undefined; }
1834
1033
  }
1835
1034
 
1836
- /**
1837
- * Whether the child's artifact grew since the last poll (D).
1838
- *
1839
- * Cheap, non-blocking probe in the spirit of `waitForQuiet`'s size check:
1840
- * it samples the cursor chat store (`store.db`) when there is one, else the
1841
- * session jsonl, waits one poll interval, and samples again. A delta means
1842
- * the agent is mid-write — a live turn, not a stalled one. `waitForQuiet`
1843
- * itself is not reusable here: it returns on QUIET and would needlessly
1844
- * discard the "still growing" answer we actually want.
1845
- *
1846
- * Deliberately returns `false` once the file is gone/unreadable (size 0 both
1847
- * samples): no signal means no grace, so the caller keeps the plain timeout.
1848
- */
1849
- private async collectArtifactGrowing(
1850
- child: ChildRecord,
1851
- cursorChat: string | null,
1852
- ): Promise<boolean> {
1853
- const target = cursorChat
1854
- ? path.join(cursorChat, "store.db")
1855
- : child.sessionFile;
1856
- const before = artifactSize(target);
1857
- if (before <= 0) return false;
1858
- await this.sleep(this.pollIntervalMs);
1859
- return artifactSize(target) > before;
1035
+ private async collectArtifactGrowing(child: ChildRecord, signal?: AbortSignal): Promise<boolean> {
1036
+ const before = artifactSize(child.sessionFile);
1037
+ if (before <= 0 || signal?.aborted) return false;
1038
+ if (await this.sleepOrAbort(POLL_INTERVAL_MS, signal)) return false;
1039
+ return artifactSize(child.sessionFile) > before;
1860
1040
  }
1861
1041
 
1862
- /**
1863
- * Wait until the session file stops growing for `settleQuietMs`.
1864
- *
1865
- * Guards against deriving an outcome from a half-written turn: the file is
1866
- * flushed incrementally, so a `stop` seen mid-stream may not be the last
1867
- * message the child will write.
1868
- */
1869
- private async waitForQuiet(
1870
- sessionFile: string,
1871
- deadline: number,
1872
- ): Promise<void> {
1873
- let lastSize = -1;
1874
- let quietSince = this.now();
1875
- const maxPolls = Math.max(
1876
- 1,
1877
- Math.ceil(DEFAULTS.turnTimeoutMs / this.pollIntervalMs),
1878
- );
1879
-
1880
- // Bounded by iterations as well as the deadline: an injected `sleep` that
1881
- // does not advance the clock would otherwise spin here forever.
1882
- for (let poll = 0; poll < maxPolls; poll += 1) {
1883
- let size = 0;
1884
- try {
1885
- size = fs.statSync(sessionFile).size;
1886
- } catch {
1887
- size = 0;
1888
- }
1889
-
1890
- if (size !== lastSize) {
1891
- lastSize = size;
1892
- quietSince = this.now();
1893
- } else if (this.now() - quietSince >= DEFAULTS.settleQuietMs) {
1042
+ private async sleepOrAbort(ms: number, signal?: AbortSignal): Promise<boolean> {
1043
+ if (!signal) {
1044
+ await this.sleep(ms);
1045
+ return false;
1046
+ }
1047
+ if (signal.aborted) return true;
1048
+ return new Promise<boolean>((resolve) => {
1049
+ let settled = false;
1050
+ let timer: ReturnType<typeof setTimeout> | undefined;
1051
+ const cleanup = () => {
1052
+ signal.removeEventListener("abort", onAbort);
1053
+ if (timer) clearTimeout(timer);
1054
+ };
1055
+ const finish = (aborted: boolean) => {
1056
+ if (settled) return;
1057
+ settled = true;
1058
+ cleanup();
1059
+ resolve(aborted);
1060
+ };
1061
+ const onAbort = () => finish(true);
1062
+ signal.addEventListener("abort", onAbort, { once: true });
1063
+ if (signal.aborted) {
1064
+ onAbort();
1894
1065
  return;
1895
1066
  }
1067
+ timer = setTimeout(() => finish(false), ms);
1068
+ });
1069
+ }
1896
1070
 
1071
+ private async waitForQuiet(sessionFile: string, deadline: number, signal?: AbortSignal): Promise<void> {
1072
+ let previous = -1;
1073
+ let quietSince = this.now();
1074
+ const maxPolls = Math.max(1, Math.ceil(DEFAULTS.turnTimeoutMs / POLL_INTERVAL_MS));
1075
+ for (let poll = 0; poll < maxPolls; poll += 1) {
1076
+ if (signal?.aborted) return;
1077
+ const size = artifactSize(sessionFile);
1078
+ if (size !== previous) { previous = size; quietSince = this.now(); }
1079
+ else if (this.now() - quietSince >= DEFAULTS.settleQuietMs) return;
1897
1080
  if (this.now() >= deadline) return;
1898
- await this.sleep(this.pollIntervalMs);
1081
+ if (await this.sleepOrAbort(POLL_INTERVAL_MS, signal)) return;
1899
1082
  }
1900
1083
  }
1901
1084
 
1902
- /**
1903
- * Recycle a child.
1904
- *
1905
- * ORDER IS MANDATORY (F27): snapshot the outcome BEFORE the agent disappears,
1906
- * because `agent get` returns `agent_not_found` once it exits.
1907
- */
1908
- async retire(name: string): Promise<ChildRecord> {
1085
+ cachedCollect(name: string): CollectResult | undefined {
1909
1086
  const child = this.children.get(name);
1910
- if (!child)
1911
- throw new SubagentError(`unknown child: ${name}`, ErrorCodes.NOT_FOUND);
1912
-
1913
- // 1. Capture the outcome while the session is still the source of truth.
1914
- if (!child.execution && fs.existsSync(child.sessionFile)) {
1915
- const parsed = parseSessionFile(child.sessionFile);
1916
- child.execution = deriveOutcome(parsed);
1917
- }
1087
+ if (!child?.execution || !canUseCachedCollect(child.state)) return undefined;
1088
+ const parsed = fs.existsSync(child.sessionFile) ? parseSessionFile(child.sessionFile) : emptyParsedSession();
1089
+ const cached: CollectResult = {
1090
+ execution: child.execution,
1091
+ output: child.execution.status !== "running" && parsed.lastTurnOutput === null ? "" : parsed.output,
1092
+ usage: parsed.usage ?? child.execution.usage ?? null,
1093
+ model: parsed.model ?? child.execution.model ?? child.model ?? null,
1094
+ acceptance: child.acceptance ?? { status: "unknown", level: "none" },
1095
+ ...(child.state === "blocked" ? { blocked: true } : {}),
1096
+ };
1097
+ if (child.outputFile) cached.outputFile = child.outputFile;
1098
+ return cached;
1099
+ }
1918
1100
 
1919
- // 2. Graceful exit first (F11: ctrl+d, never ctrl+c), then force-close.
1920
- const paneId = child.paneId;
1921
- const tabId = child.tabId;
1922
- if (paneId) {
1923
- const alive = await this.client.agentGet(name);
1924
- // Only skip the graceful ctrl+d when the agent is DEFINITIVELY gone
1925
- // (NOT_FOUND). A wedged/timed-out `agent get` says nothing — skipping
1926
- // ctrl+d then force-closing the pane would kill a live agent mid-turn
1927
- // (the session file survives, F12, but unsaved turn state does not).
1928
- if (alive.ok || !agentGone(alive)) {
1929
- await bestEffort(this.client.agentSendKeys(name, "ctrl+d"));
1930
- await this.sleep(600);
1931
- await bestEffort(this.client.agentSendKeys(name, "ctrl+d"));
1932
- await this.sleep(1_200);
1101
+ async retire(name: string): Promise<ChildRecord> {
1102
+ const child = this.requireChild(name);
1103
+ if (child.state === "retired") return child;
1104
+ if (!child.execution && fs.existsSync(child.sessionFile)) child.execution = deriveOutcome(parseSessionFile(child.sessionFile));
1105
+ if (this.supervisor.isAlive(name)) await this.supervisor.retire(name);
1106
+ if (child.nodeId && this.legion) {
1107
+ if (child.execution && child.execution.status !== "unknown" && child.execution.status !== "running") {
1108
+ this.recordSettled(child, child.execution);
1109
+ if (child.execution.status !== "aborted") this.emitStored(child.nodeId, "node_retired", { parentId: this.legion.nodeId, execution: child.execution.status });
1110
+ } else {
1111
+ updateNode(this.legion.db, child.nodeId, { status: "retired" }, this.now);
1112
+ this.emitStored(child.nodeId, "node_retired", { parentId: this.legion.nodeId });
1933
1113
  }
1934
- // F12: closing the pane is safe — the session file survives and resumes.
1935
- await bestEffort(this.client.paneClose(paneId));
1936
- await this.reapTypeTabIfEmpty(child.agent ?? "", paneId, tabId);
1114
+ this.abortLegionPhase(child.nodeId);
1937
1115
  }
1938
-
1939
1116
  child.state = "retired";
1940
1117
  child.retiredAt = new Date(this.now()).toISOString();
1941
- child.paneId = null;
1118
+ this.emitProcess("node_retired", child.nodeId ?? name, { name });
1942
1119
  this.onChildUpdate(child);
1943
1120
  return child;
1944
1121
  }
1945
1122
 
1946
- /**
1947
- * After closing a child's pane, drop the type tab if it is now empty.
1948
- *
1949
- * Same-type agents share a tab; leaving an empty tab behind is the leftover
1950
- * the parent used to have to close by hand.
1951
- */
1952
- private async reapTypeTabIfEmpty(
1953
- agentType: string,
1954
- paneId: string,
1955
- tabId: string | undefined,
1956
- ): Promise<void> {
1957
- const released = agentType
1958
- ? this.layout.releasePane(agentType, paneId)
1959
- : { tabId: undefined, empty: true };
1960
- if (!released.empty) return;
1961
-
1962
- const candidate = released.tabId ?? tabId;
1963
- if (!candidate) return;
1964
-
1965
- // Another parent (or another Orchestrator of the same parent) may have
1966
- // panes in this tab that our in-memory layout never tracked. Closing on
1967
- // "our map is empty" would kill those (F15 is atomic). Ask herdr first.
1968
- const panes = await this.client.paneList();
1969
- if (!panes.ok) return;
1970
- const left = panes.value.filter(
1971
- (p) => p.tab_id === candidate && p.pane_id !== paneId,
1972
- );
1973
- if (left.length > 0) return;
1974
- await bestEffort(this.client.tabClose(candidate));
1975
- }
1976
-
1977
- /** Retire every known child; optionally reap the whole tab (F15). */
1978
- async retireAll(opts: { tabId?: string } = {}): Promise<ChildRecord[]> {
1979
- const retired: ChildRecord[] = [];
1123
+ async retireAll(): Promise<ChildRecord[]> {
1124
+ const results: ChildRecord[] = [];
1980
1125
  for (const name of [...this.children.keys()]) {
1981
- try {
1982
- retired.push(await this.retire(name));
1983
- } catch {
1984
- // Keep going: one bad child must not block the rest.
1985
- }
1126
+ try { results.push(await this.retire(name)); } catch { /* continue with other child processes */ }
1986
1127
  }
1987
- if (opts.tabId) await bestEffort(this.client.tabClose(opts.tabId));
1988
- return retired;
1128
+ return results;
1989
1129
  }
1990
1130
 
1991
- /**
1992
- * Audit for orphan panes: panes present in our tab but absent from our tree.
1993
- * herdr enforces no isolation (F23-F25), so this detects — never prevents —
1994
- * out-of-band pane creation.
1995
- */
1996
- async auditOrphans(tabId: string): Promise<string[]> {
1997
- const res = await this.client.paneList();
1998
- if (!res.ok) return [];
1999
- const known = new Set(
2000
- [...this.children.values()].flatMap((c) => (c.paneId ? [c.paneId] : [])),
2001
- );
2002
- return res.value.flatMap((p) =>
2003
- p.tab_id === tabId && !known.has(p.pane_id) ? [p.pane_id] : [],
2004
- );
2005
- }
2006
-
2007
- /**
2008
- * Best-effort live fields for the parent status widget.
2009
- *
2010
- * Pi children are covered by session jsonl. Non-pi kinds (F7) have no
2011
- * session ref, so this also reads `agent get` / pane title and maps
2012
- * whatever labels, tokens, or model-like title those CLIs expose.
2013
- */
2014
- async probeProgress(name: string): Promise<LiveProgress> {
2015
- const child = this.children.get(name);
2016
- if (!child) return {};
2017
- const parts: LiveProgress[] = [];
2018
- if (child.paneId) {
2019
- const pane = await this.client.paneGet(child.paneId);
2020
- if (pane.ok) parts.push(progressFromPaneInfo(pane.value));
2021
- }
2022
- const agentState = await this.client.agentGet(name);
2023
- if (agentState.ok) parts.push(progressFromAgentInfo(agentState.value));
2024
- parts.push(progressFromSession(parseSessionFile(child.sessionFile)));
2025
- return mergeProgress(...parts);
2026
- }
1131
+ childrenSnapshot(): ChildRecord[] { return [...this.children.values()]; }
2027
1132
 
2028
- childrenSnapshot(): ChildRecord[] {
2029
- return [...this.children.values()];
1133
+ /** Whether the RPC process for this child is still running. */
1134
+ isChildAlive(name: string): boolean {
1135
+ return this.supervisor.isAlive(name);
2030
1136
  }
2031
1137
 
2032
- /** Rehydrate from a persisted run record (crash recovery). */
2033
1138
  restore(record: RunRecord): void {
2034
1139
  for (const child of record.children) {
2035
- this.children.set(child.name, { ...child });
1140
+ const node = this.legion && !child.nodeId ? getChildByName(this.legion.db, this.legion.nodeId, child.name) : null;
1141
+ this.children.set(child.name, { ...child, ...(node ? { nodeId: node.id } : {}) });
2036
1142
  }
1143
+ this.spawned = Math.max(this.spawned, record.budget.spawned);
2037
1144
  }
2038
1145
  }