pi-legion 5.0.1 → 5.2.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 (79) hide show
  1. package/CHANGELOG.md +858 -0
  2. package/CONTRIBUTING.md +33 -2
  3. package/README.md +10 -5
  4. package/agents/centurion.md +32 -7
  5. package/agents/scout.md +11 -0
  6. package/docs/contracts/abort-soft-interrupt-v1.md +162 -0
  7. package/docs/contracts/centurion-declared-phases-v1.md +104 -0
  8. package/docs/contracts/declarative-phase-machine-v5.md +43 -0
  9. package/docs/contracts/extension-inheritance-wiring-v1.md +88 -0
  10. package/docs/contracts/finished-cache-eviction-v1.md +169 -0
  11. package/docs/contracts/galaxy-scratch-v1.md +78 -0
  12. package/docs/contracts/legion-chart-frame-buckets-v1.md +201 -0
  13. package/docs/contracts/legion-main-screen-mount-v1.md +161 -0
  14. package/docs/contracts/legion-page-floor-v1.md +129 -0
  15. package/docs/contracts/legion-session-continuity-v1.md +118 -0
  16. package/docs/contracts/mailbox-delivery-v1.md +162 -0
  17. package/docs/contracts/notice-claim-v1.md +206 -0
  18. package/docs/contracts/partial-failure-exit-v1.md +235 -0
  19. package/docs/contracts/proc-sweep-v1.md +107 -0
  20. package/docs/contracts/provider-empty-generation-retry-v1.md +161 -0
  21. package/docs/contracts/stall-visibility-v1.md +218 -0
  22. package/docs/contracts/subagent-renewal-v1.md +5 -3
  23. package/docs/contracts/vexillatio-nonblocking-launch-v1.md +1 -0
  24. package/docs/contracts/viz-frame-alloc-v1.md +123 -0
  25. package/docs/contracts/wait-mail-preempt-v1.md +117 -0
  26. package/docs/contracts/wait-not-stop.md +1 -1
  27. package/docs/design.md +4 -1
  28. package/docs/inprocess-supervisor.md +9 -3
  29. package/docs/legion-v2-contract.md +122 -20
  30. package/docs/vexillatio-contract.md +5 -1
  31. package/index.ts +1903 -130
  32. package/package.json +5 -5
  33. package/skills/pi-legion/SKILL.md +2 -1
  34. package/src/agents/agents.ts +26 -1
  35. package/src/agents/settings.ts +67 -2
  36. package/src/api.ts +17 -0
  37. package/src/extension/child-guard.ts +2 -1
  38. package/src/extension/join.ts +54 -0
  39. package/src/extension/legion-commands.ts +15 -4
  40. package/src/extension/legion-doctor.ts +48 -6
  41. package/src/extension/legion-status.ts +44 -2
  42. package/src/extension/legion-tools.ts +1044 -109
  43. package/src/extension/notify.ts +31 -2
  44. package/src/extension/playbook.ts +6 -3
  45. package/src/extension/runtime.ts +882 -81
  46. package/src/extension/spawn-hints.ts +52 -12
  47. package/src/extension/summary.ts +7 -15
  48. package/src/extension/timing.ts +4 -15
  49. package/src/legion/db.ts +23 -1
  50. package/src/legion/events.ts +7 -0
  51. package/src/legion/interrupt.ts +98 -0
  52. package/src/legion/mail-release.ts +266 -0
  53. package/src/legion/mail.ts +456 -29
  54. package/src/legion/nodes.ts +31 -0
  55. package/src/legion/phase-conditions.ts +7 -1
  56. package/src/legion/phase-machine.ts +160 -8
  57. package/src/legion/state-machine.ts +34 -2
  58. package/src/runs/acceptance.ts +105 -6
  59. package/src/runs/args.ts +16 -0
  60. package/src/runs/child-scope.ts +323 -0
  61. package/src/runs/extension-inheritance.ts +145 -19
  62. package/src/runs/orchestrator.ts +613 -55
  63. package/src/runs/store.ts +149 -5
  64. package/src/shared/proc-sweep.ts +317 -0
  65. package/src/shared/progress.ts +11 -2
  66. package/src/shared/session-map.ts +29 -0
  67. package/src/shared/session.ts +308 -6
  68. package/src/shared/types.ts +34 -0
  69. package/src/supervisor/inprocess-supervisor.ts +158 -12
  70. package/src/supervisor/race-timeout.ts +55 -0
  71. package/src/supervisor/routing-supervisor.ts +55 -4
  72. package/src/supervisor/rpc-supervisor.ts +215 -29
  73. package/src/supervisor/types.ts +439 -2
  74. package/src/tui/status.ts +2 -1
  75. package/src/tui/viz/canvas.ts +358 -36
  76. package/src/tui/viz/palette.ts +18 -2
  77. package/src/tui/viz/panels.ts +507 -104
  78. package/src/tui/viz/rate.ts +120 -15
  79. package/src/tui/viz/view.ts +72 -4
@@ -0,0 +1,323 @@
1
+ /**
2
+ * One name, one scope (#312).
3
+ *
4
+ * Child names are resolved in four different places — `status`, `collect`,
5
+ * `stop`, `continue` — and before this module each one had its own idea of what
6
+ * a name means:
7
+ *
8
+ * - `status` went through {@link pickChildByName}, which walks EVERY run in
9
+ * the store and prefers a live record and then the newest `createdAt`, so a
10
+ * name could resolve to a node in another session's run;
11
+ * - `collect` acted on the orchestrator's own children map, i.e. only the
12
+ * direct children of one run.
13
+ *
14
+ * Same name, adjacent calls, two different nodes — and neither path ever
15
+ * reported the disagreement. The reported incident collected a *successful*
16
+ * demo child while the parent was trying to collect a *failed* one, and `stop`
17
+ * masked the whole thing as `No non-retired children to stop.`
18
+ *
19
+ * The fix is one resolution order, shared by all four callers:
20
+ *
21
+ * 1. the direct children of the current run win, always, and silently — the
22
+ * common case must not grow a new line of noise;
23
+ * 2. otherwise the same name may exist in other runs: exactly one candidate is
24
+ * a *reportable* answer (the caller decides whether that is enough to act
25
+ * on, or only to show);
26
+ * 3. two or more candidates are an ambiguity, never a guess.
27
+ *
28
+ * `direct` and `scan` are injected so this module stays free of store/runtime
29
+ * imports: it is the pure rule, and the two data sources are the caller's.
30
+ */
31
+
32
+ import type { ChildRecord, RunRecord } from "../shared/types.ts";
33
+
34
+ /** One same-named node found outside the current run. */
35
+ export interface ChildScopeCandidate {
36
+ runId: string;
37
+ nodeId?: string;
38
+ state: string;
39
+ sessionFile?: string;
40
+ }
41
+
42
+ /**
43
+ * What a name resolved to.
44
+ *
45
+ * - `direct`: this run's own child. Nothing is said about it beyond that.
46
+ * - `elsewhere`: not a direct child; `candidates` is what the name matched
47
+ * elsewhere. `length === 1` is unambiguous — show or act on it, but say so.
48
+ * `length >= 2` is an ambiguity the caller must report instead of picking.
49
+ * - `absent`: the name exists nowhere the caller can see.
50
+ */
51
+ export type ChildScopeHit =
52
+ | { kind: "direct"; name: string; child: ChildRecord }
53
+ | { kind: "elsewhere"; name: string; candidates: ChildScopeCandidate[] }
54
+ | { kind: "absent"; name: string; candidates: [] };
55
+
56
+ /** One node the caller may scan, with the run it lives in. */
57
+ export interface ChildScopeScanEntry extends ChildScopeCandidate {
58
+ name: string;
59
+ }
60
+
61
+ /**
62
+ * The node a resolution answered with, plus the run that holds it.
63
+ *
64
+ * Same shape `findChild` / `findChildAcrossStores` answer with, so a caller does
65
+ * not care which of them resolved it.
66
+ */
67
+ export interface ScopedRunChild {
68
+ runId: string;
69
+ run: RunRecord;
70
+ child: ChildRecord;
71
+ }
72
+
73
+ export function resolveChildScope(input: {
74
+ name: string;
75
+ /**
76
+ * Explicit scope from the tool call. When present only that run is scanned,
77
+ * so a caller can address a node by `runId` even when the name repeats.
78
+ */
79
+ runId?: string;
80
+ /** This run's own child, or `undefined`. Injected: see the module header. */
81
+ direct: (name: string) => ChildRecord | undefined;
82
+ /** Every node the caller may consider, across runs. */
83
+ scan: () => ChildScopeScanEntry[];
84
+ }): ChildScopeHit {
85
+ const { name, runId } = input;
86
+
87
+ // 1. Direct children first, and unscoped by `runId`: `direct` is already the
88
+ // current run by construction, and an explicit `runId` that names a
89
+ // different run narrows only the SEARCH below — the run this session
90
+ // actually owns still answers first, because that is the one it can act on.
91
+ const direct = input.direct(name);
92
+ if (direct) return { kind: "direct", name, child: direct };
93
+
94
+ // 2. Same name, other runs.
95
+ const seen = new Set<string>();
96
+ const candidates: ChildScopeCandidate[] = [];
97
+ for (const entry of input.scan()) {
98
+ if (entry.name !== name) continue;
99
+ if (runId !== undefined && entry.runId !== runId) continue;
100
+ // A run holds one record per name, so the identity is (runId, nodeId) —
101
+ // `nodeId` is absent on pre-M2 records, where the run alone is the key.
102
+ const key = `${entry.runId}\u0000${entry.nodeId ?? ""}`;
103
+ if (seen.has(key)) continue;
104
+ seen.add(key);
105
+ candidates.push({
106
+ runId: entry.runId,
107
+ ...(entry.nodeId ? { nodeId: entry.nodeId } : {}),
108
+ state: entry.state,
109
+ ...(entry.sessionFile ? { sessionFile: entry.sessionFile } : {}),
110
+ });
111
+ }
112
+
113
+ if (candidates.length === 0) return { kind: "absent", name, candidates: [] };
114
+ // Sorted so two resolutions of the same store produce the same message.
115
+ candidates.sort((a, b) => a.runId.localeCompare(b.runId));
116
+ return { kind: "elsewhere", name, candidates };
117
+ }
118
+
119
+ /**
120
+ * One line per candidate, `runId` / `nodeId` / `state` in that order.
121
+ *
122
+ * The caller owns the surrounding sentence — what a given action may do with the
123
+ * list differs — but the facts must look the same everywhere, so they are
124
+ * rendered in one place.
125
+ */
126
+ export function describeChildScopeCandidates(
127
+ candidates: readonly ChildScopeCandidate[],
128
+ ): string {
129
+ return candidates
130
+ .map((candidate) => {
131
+ const parts = [`run ${candidate.runId}`];
132
+ if (candidate.nodeId) parts.push(`node ${candidate.nodeId}`);
133
+ parts.push(`state ${candidate.state}`);
134
+ return ` - ${parts.join(" · ")}`;
135
+ })
136
+ .join("\n");
137
+ }
138
+
139
+ // ── wiring the rule to a store's run records ───────────────────────────────
140
+ //
141
+ // These three live here, next to the rule they implement, because there must be
142
+ // exactly ONE definition of "what a name means": the lazy resolver below and the
143
+ // callers that already hold every run both go through them.
144
+
145
+ /**
146
+ * The record `scopeRunId` actually owns for `name`, or `null`.
147
+ *
148
+ * This is the whole definition of "a direct child": an exact `(runId, name)`
149
+ * pair — never "the newest record with that name".
150
+ */
151
+ export function foundInScope(
152
+ runs: readonly RunRecord[],
153
+ scopeRunId: string | undefined,
154
+ name: string,
155
+ ): ScopedRunChild | null {
156
+ if (!scopeRunId) return null;
157
+ const run = runs.find((candidate) => candidate.runId === scopeRunId);
158
+ const child = run?.children.find((candidate) => candidate.name === name);
159
+ if (!run || !child) return null;
160
+ return { runId: run.runId, run, child };
161
+ }
162
+
163
+ /** {@link resolveChildScope}, wired to one store's run records. */
164
+ export function scopeHitFor(input: {
165
+ name: string;
166
+ /**
167
+ * The run whose children count as direct: the explicit `runId` when the caller
168
+ * named one, else the run this session owns. Separate from `explicitRunId` on
169
+ * purpose — see it below.
170
+ */
171
+ directRunId: string | undefined;
172
+ /**
173
+ * The `runId` the CALLER passed, which is the only thing allowed to narrow the
174
+ * cross-run search. The inferred session run must not: with it in the filter a
175
+ * name that lives in another run would come back `absent` instead of
176
+ * `elsewhere`, and the refusal that tells the caller where it actually is
177
+ * would never be reachable.
178
+ */
179
+ explicitRunId?: string | undefined;
180
+ runs: readonly RunRecord[];
181
+ }): ChildScopeHit {
182
+ return resolveChildScope({
183
+ name: input.name,
184
+ runId: input.explicitRunId,
185
+ direct: (name) => foundInScope(input.runs, input.directRunId, name)?.child,
186
+ scan: () =>
187
+ input.runs.flatMap((run) =>
188
+ run.children.map((child) => ({
189
+ runId: run.runId,
190
+ nodeId: child.nodeId,
191
+ name: child.name,
192
+ state: child.state,
193
+ sessionFile: child.sessionFile,
194
+ })),
195
+ ),
196
+ });
197
+ }
198
+
199
+ /**
200
+ * The one node an `elsewhere` hit points at, when it is unambiguous.
201
+ *
202
+ * `null` for `absent` and for an ambiguity: a caller that cannot name the node
203
+ * must not pick one, and the ambiguity is reported before this is consulted.
204
+ */
205
+ export function foundElsewhere(
206
+ runs: readonly RunRecord[],
207
+ name: string,
208
+ hit: ChildScopeHit,
209
+ ): ScopedRunChild | null {
210
+ if (hit.kind !== "elsewhere" || hit.candidates.length !== 1) return null;
211
+ const only = hit.candidates[0];
212
+ if (!only) return null;
213
+ return foundInScope(runs, only.runId, name);
214
+ }
215
+
216
+ /** What {@link resolveScopedChild} answers. */
217
+ export interface ScopedChildResolution {
218
+ /** What the name resolved to — the same three-way answer as {@link resolveChildScope}. */
219
+ readonly hit: ChildScopeHit;
220
+ /** The node the hit points at; `null` for `absent` and for an `elsewhere` ambiguity. */
221
+ readonly found: ScopedRunChild | null;
222
+ /**
223
+ * Every readable run, oldest first. Scans on FIRST use and at most once, so a
224
+ * caller that also needs the full registry (an overview, an owner verdict)
225
+ * pays for it a single time — and a caller that does not never pays at all.
226
+ *
227
+ * Treat the array as read-only.
228
+ */
229
+ runs(): RunRecord[];
230
+ }
231
+
232
+ /** A `readRun` that reports a malformed `runId` as "not found" instead of throwing. */
233
+ function readRunOrNull(
234
+ readRun: (runId: string) => RunRecord | null,
235
+ runId: string,
236
+ ): RunRecord | null {
237
+ try {
238
+ return readRun(runId);
239
+ } catch {
240
+ // `RunStore.readRun` rejects run ids that cannot be a directory name
241
+ // (`../../etc`, `a/b`). Such an id names no run, which is exactly what a
242
+ // caller-supplied `runId` deserves: `absent`, resolved like any other miss.
243
+ return null;
244
+ }
245
+ }
246
+
247
+ /**
248
+ * Resolve one name, paying for the run registry only when the answer needs it (#344).
249
+ *
250
+ * Every control call (`collect` / `status` / `steer` / `abort` / `retire` /
251
+ * `continue`) used to start with `store.listRuns()` — a `readdir` plus a
252
+ * `JSON.parse` per run — even when it already knew the run it was scoped to.
253
+ * The scan is O(runs) and the scope is usually free, so the order is inverted
254
+ * here: read the ONE run the scope names, and fall back to the registry only
255
+ * when the answer genuinely depends on other runs.
256
+ *
257
+ * The three steps, in order:
258
+ *
259
+ * 1. **direct hit** — `directRunId` is known (`params.runId` / the session's
260
+ * legion run / the run the runtime tracks the name under) and that run
261
+ * holds the name. The resolver's answer is `direct` by construction, and
262
+ * its scan is never consulted (see `resolveChildScope`: `direct` short-
263
+ * circuits before the scan), so one `readRun` answers it.
264
+ * 2. **explicit `runId`, name not in it** — the cross-run search is narrowed
265
+ * to that same run, so a scan could not produce a candidate: `absent`.
266
+ * 3. **everything else** — the name may live in another run. That is the case
267
+ * #312 exists for (report / refuse instead of adopting), and it needs the
268
+ * registry. `listRuns` is called once, through the store's cached scan.
269
+ *
270
+ * #312's strict-scope semantics are untouched: this function only decides WHICH
271
+ * reads happen, never what a hit means. Steps 1 and 2 are provably identical to
272
+ * what the scan would have answered, which is what makes the shortcut safe.
273
+ */
274
+ export function resolveScopedChild(input: {
275
+ name: string;
276
+ /** The `runId` the caller passed, if any (narrows the cross-run search). */
277
+ explicitRunId?: string | undefined;
278
+ /** The run this call is scoped to (see `scopeRunIdFor` in the caller). */
279
+ directRunId?: string | undefined;
280
+ /** O(1) single-run read. */
281
+ readRun: (runId: string) => RunRecord | null;
282
+ /** The full registry. Called at most once, and only when a scan is required. */
283
+ listRuns: () => RunRecord[];
284
+ }): ScopedChildResolution {
285
+ const { name, explicitRunId, directRunId } = input;
286
+ let scanned: RunRecord[] | undefined;
287
+ const runs = (): RunRecord[] => (scanned ??= input.listRuns());
288
+
289
+ if (directRunId !== undefined) {
290
+ const scopeRun = readRunOrNull(input.readRun, directRunId);
291
+ // The record's own `runId` has to agree with the directory the caller
292
+ // asked for: `foundInScope` matches on the FIELD, so a tampered run.json
293
+ // whose field disagrees with its directory is not a direct hit either.
294
+ const child =
295
+ scopeRun && scopeRun.runId === directRunId
296
+ ? scopeRun.children.find((candidate) => candidate.name === name)
297
+ : undefined;
298
+ if (scopeRun && child) {
299
+ return {
300
+ hit: { kind: "direct", name, child },
301
+ found: { runId: scopeRun.runId, run: scopeRun, child },
302
+ runs,
303
+ };
304
+ }
305
+ // Step 2: an explicit `runId` filters the scan to the very run just read
306
+ // (`scopeRunIdFor` puts the explicit id first, so the two agree), and "not
307
+ // in that run" is then `absent` without asking the registry. The equality
308
+ // test keeps this a shortcut instead of an assumption: given a scope that
309
+ // somehow differs from the explicit id, the scan below decides.
310
+ if (explicitRunId !== undefined && explicitRunId === directRunId) {
311
+ return { hit: { kind: "absent", name, candidates: [] }, found: null, runs };
312
+ }
313
+ }
314
+
315
+ // Step 3: the registry. One scan, memoized for whoever else needs it.
316
+ const all = runs();
317
+ const hit = scopeHitFor({ name, directRunId, explicitRunId, runs: all });
318
+ const found =
319
+ hit.kind === "direct"
320
+ ? foundInScope(all, directRunId, name)
321
+ : foundElsewhere(all, name, hit);
322
+ return { hit, found, runs };
323
+ }
@@ -286,14 +286,64 @@ export function parsePiList(output: string): string[] {
286
286
  return dirs;
287
287
  }
288
288
 
289
+ /**
290
+ * How much of `pi list`'s stderr the one-shot warning may echo.
291
+ *
292
+ * The warning has to be actionable (#317: "could not ask" used to look exactly
293
+ * like "nothing installed"), but it is also a single log line that must not turn
294
+ * a stack trace into the operator's terminal.
295
+ */
296
+ export const DISCOVERY_STDERR_LIMIT = 200;
297
+
298
+ /** Best-effort text of an unknown error field: never throws. */
299
+ function asText(value: unknown): string {
300
+ if (typeof value === "string") return value;
301
+ if (value === undefined || value === null) return "";
302
+ try {
303
+ return String(value);
304
+ } catch {
305
+ return "";
306
+ }
307
+ }
308
+
309
+ /**
310
+ * One bounded line explaining why a probe failed.
311
+ *
312
+ * `pi list` can fail with no stderr at all (a killed child, a bare `exit 4`), so
313
+ * the summary degrades through stderr → exit code → `error.message`. The code
314
+ * sits BEFORE the message on purpose: Node's `execFile` always fills `message`
315
+ * with `Command failed: pi list`, so a message-first order would make the exit
316
+ * code branch unreachable — and `pi list exited 4` says more than the generic
317
+ * wrapper text. A non-numeric code (`ENOENT`) still falls through to the message
318
+ * (`spawn pi ENOENT`), which is the actionable one there. It must never throw: a
319
+ * warning is not allowed to fail a launch (#317).
320
+ */
321
+ function describeProbeFailure(error: unknown): string {
322
+ const err = error as { stderr?: unknown; message?: unknown; code?: unknown } | undefined;
323
+ const stderr = asText(err?.stderr).replace(/\s+/g, " ").trim();
324
+ if (stderr) {
325
+ return stderr.length > DISCOVERY_STDERR_LIMIT ? `${stderr.slice(0, DISCOVERY_STDERR_LIMIT)}…` : stderr;
326
+ }
327
+ if (typeof err?.code === "number") return `pi list exited ${err.code} with no stderr`;
328
+ const message = asText(err?.message).replace(/\s+/g, " ").trim();
329
+ if (message) {
330
+ return message.length > DISCOVERY_STDERR_LIMIT ? `${message.slice(0, DISCOVERY_STDERR_LIMIT)}…` : message;
331
+ }
332
+ return "pi list failed with no output";
333
+ }
334
+
335
+ /** One probe's outcome: resolved entries, or the reason the probe could not answer. */
336
+ type DiscoveryProbe = { ok: true; entries: string[] } | { ok: false; reason: string };
337
+
289
338
  /**
290
339
  * Run one `pi list` and resolve it to extension entry paths.
291
340
  *
292
- * Returns `undefined` when discovery itself failed (no `pi` on PATH, non-zero
293
- * exit, timeout) so the caller can distinguish "nothing installed" from "could
294
- * not ask" — only the latter must stay retryable.
341
+ * Returns a failure (with a short reason) when discovery itself failed — no `pi`
342
+ * on PATH, non-zero exit, timeout — so the caller can both distinguish "nothing
343
+ * installed" from "could not ask" and say which one happened (#317). Only the
344
+ * latter stays retryable.
295
345
  */
296
- async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<string[] | undefined> {
346
+ async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<DiscoveryProbe> {
297
347
  let dirs: string[];
298
348
  try {
299
349
  const { stdout } = await execFileAsync("pi", ["list"], {
@@ -302,17 +352,20 @@ async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<string[] |
302
352
  maxBuffer: 4 * 1024 * 1024,
303
353
  });
304
354
  dirs = parsePiList(stdout);
305
- } catch {
306
- return undefined;
355
+ } catch (error) {
356
+ return { ok: false, reason: describeProbeFailure(error) };
307
357
  }
308
358
  const entries = dirs.flatMap((dir) => resolveExtensionEntries(dir));
309
359
  const seen = new Set<string>();
310
- return entries.filter((entry) => {
311
- const key = path.resolve(entry);
312
- if (seen.has(key)) return false;
313
- seen.add(key);
314
- return true;
315
- });
360
+ return {
361
+ ok: true,
362
+ entries: entries.filter((entry) => {
363
+ const key = path.resolve(entry);
364
+ if (seen.has(key)) return false;
365
+ seen.add(key);
366
+ return true;
367
+ }),
368
+ };
316
369
  }
317
370
 
318
371
  /**
@@ -332,6 +385,40 @@ async function resolveHostExtensions(env: NodeJS.ProcessEnv): Promise<string[] |
332
385
  */
333
386
  export const FAILURE_TTL_MS = 5_000;
334
387
 
388
+ /**
389
+ * Record a failed probe (the `failedAt` backoff stamp) and warn ONCE.
390
+ *
391
+ * The stamp doubles as the "already told the operator" bit (#317): while it is
392
+ * set, a later failing probe updates the time but stays quiet, so a host that
393
+ * will never have `pi list` working cannot flood the log once per spawn.
394
+ *
395
+ * Scope of "once": one warning per PROCESS. A successful probe caches through
396
+ * `discovered`, and `ensureHostExtensions` short-circuits on that forever — so
397
+ * once discovery has worked there is no further probe to fail, and the stamp
398
+ * being deleted on success cannot produce a second warning in production. The
399
+ * only way back is `resetExtensionDiscoveryCache`, which is a test seam and also
400
+ * clears the stamp, i.e. a genuinely fresh start. No extra state is needed for
401
+ * this bound (the frozen backoff already models exactly this window).
402
+ *
403
+ * Never throws: the warning itself must not be able to fail a launch, and an
404
+ * empty `pi list` stderr must not turn into a TypeError here.
405
+ */
406
+ function noteDiscoveryFailure(reason: string): void {
407
+ const alreadyReported = store.failedAt !== undefined;
408
+ store.failedAt = Date.now();
409
+ if (alreadyReported) return;
410
+ const retryS = Math.round(FAILURE_TTL_MS / 1000);
411
+ try {
412
+ console.error(
413
+ `[pi-legion] host extension discovery failed (pi list): ${reason}. ` +
414
+ `Children get 0 inherited extensions until a probe succeeds (next attempt after ${retryS}s); ` +
415
+ "run `/legion doctor` (Extensions) or set PI_LEGION_CHILD_EXTENSIONS=<paths> to load them explicitly.",
416
+ );
417
+ } catch {
418
+ // A log line that cannot be written must not break the spawn either.
419
+ }
420
+ }
421
+
335
422
  /**
336
423
  * Discover the host's extensions once per process and return them.
337
424
  *
@@ -350,6 +437,10 @@ export const FAILURE_TTL_MS = 5_000;
350
437
  * that keeps the three warm-up points idempotent (R2-b). Once the stamp ages out,
351
438
  * the next call probes again, so a failure is never a permanent off switch (F23).
352
439
  *
440
+ * #317 adds visibility only: the failure is now also reported once (see
441
+ * `noteDiscoveryFailure`) and is readable through `hostExtensionDiscoveryState`.
442
+ * Neither the never-reject contract nor the backoff semantics changed.
443
+ *
353
444
  * `env` is handed to `execFile` (a caller can point discovery at a specific
354
445
  * PATH); the cache itself is process-wide and does not vary by env.
355
446
  */
@@ -359,21 +450,21 @@ export async function ensureHostExtensions(env: NodeJS.ProcessEnv = process.env)
359
450
  if (!store.inFlight) {
360
451
  store.inFlight = (async () => {
361
452
  try {
362
- const resolved = await resolveHostExtensions(env);
363
- if (!resolved) {
364
- store.failedAt = Date.now();
453
+ const probe = await resolveHostExtensions(env);
454
+ if (!probe.ok) {
455
+ noteDiscoveryFailure(probe.reason);
365
456
  return [];
366
457
  }
367
- store.discovered = resolved;
458
+ store.discovered = probe.entries;
368
459
  // A success supersedes any earlier failure, so the backoff stamp must not
369
460
  // outlive it — otherwise a later re-probe (after a reset) would inherit an
370
461
  // unrelated window.
371
462
  delete store.failedAt;
372
- return resolved;
373
- } catch {
463
+ return probe.entries;
464
+ } catch (error) {
374
465
  // Belt and braces: the contract is "never rejects", and a launch must
375
466
  // never fail because the host could not be asked about packages.
376
- store.failedAt = Date.now();
467
+ noteDiscoveryFailure(describeProbeFailure(error));
377
468
  return [];
378
469
  } finally {
379
470
  // Success caches through `discovered`; failure leaves the `failedAt`
@@ -400,6 +491,41 @@ export function discoveredHostExtensions(): string[] | undefined {
400
491
  return store.discovered;
401
492
  }
402
493
 
494
+ /**
495
+ * What this process knows about host extension discovery, read-only (#317).
496
+ *
497
+ * Exists because `discoveredHostExtensions() ?? []` collapses two different
498
+ * situations into one empty array: "the host really ships no package extensions"
499
+ * and "we could not ask" (and a third: "we never asked"). A caller that wants to
500
+ * tell them apart — `/legion doctor` does — reads this instead of guessing.
501
+ *
502
+ * Pure in-memory read: no probe, no subprocess. That is deliberate, so doctor
503
+ * can report `never` without silently kicking off a 0.3–0.9 s `pi list`.
504
+ */
505
+ export interface HostExtensionDiscoveryState {
506
+ /** `ok` = a probe succeeded (count is the resolved set, possibly 0). */
507
+ status: "ok" | "failed" | "unknown";
508
+ /** Entries the last successful probe resolved; 0 unless `status` is `ok`. */
509
+ count: number;
510
+ /** `Date.now()` of the last FAILED probe (only set when `status` is `failed`). */
511
+ at?: number;
512
+ }
513
+
514
+ export type HostExtensionDiscoveryStatus = HostExtensionDiscoveryState["status"];
515
+
516
+ /**
517
+ * Read the discovery state without changing it.
518
+ *
519
+ * A success wins over a stale stamp on purpose: `ensureHostExtensions` deletes
520
+ * `failedAt` on success, so both being set only means a reset raced a re-probe —
521
+ * the cache is the newer truth either way.
522
+ */
523
+ export function hostExtensionDiscoveryState(): HostExtensionDiscoveryState {
524
+ if (store.discovered !== undefined) return { status: "ok", count: store.discovered.length };
525
+ if (store.failedAt !== undefined) return { status: "failed", count: 0, at: store.failedAt };
526
+ return { status: "unknown", count: 0 };
527
+ }
528
+
403
529
  /**
404
530
  * Does this extension match an `excludeExtensions` entry?
405
531
  *