pi-crew 0.11.23 → 0.11.24

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 +11 -0
  2. package/agents/explorer.md +3 -3
  3. package/agents/librarian.md +3 -3
  4. package/dist/index.mjs +528 -525
  5. package/docs/dynamic-workflows.md +14 -2
  6. package/package.json +4 -4
  7. package/src/agents/discover-agents.ts +8 -2
  8. package/src/config/config-validation.ts +3 -1
  9. package/src/config/env-allowlist-registry.ts +5 -0
  10. package/src/config/env-vars.ts +9 -6
  11. package/src/config/role-tools.ts +7 -6
  12. package/src/extension/management.ts +7 -0
  13. package/src/extension/register.ts +15 -0
  14. package/src/extension/run-index.ts +24 -1
  15. package/src/extension/team-tool/destructive-gate.ts +208 -0
  16. package/src/extension/team-tool/goal-wrap.ts +11 -1
  17. package/src/extension/team-tool/goal.ts +13 -1
  18. package/src/extension/team-tool.ts +10 -0
  19. package/src/observability/exporters/otlp-exporter.ts +11 -1
  20. package/src/prompt/prompt-runtime.ts +102 -18
  21. package/src/runtime/broker/crew-broker-client.ts +7 -0
  22. package/src/runtime/broker/crew-broker.ts +104 -132
  23. package/src/runtime/broker/protocol/connection-state.ts +159 -1
  24. package/src/runtime/broker/protocol/events-replay.ts +50 -10
  25. package/src/runtime/child-pi/child-pi-constants.ts +9 -0
  26. package/src/runtime/child-pi/child-pi-rpc.ts +72 -7
  27. package/src/runtime/child-pi/child-pi-streams.ts +19 -3
  28. package/src/runtime/child-pi/postmortem-registry.ts +8 -2
  29. package/src/runtime/classifier/ambient-noise-gate.ts +5 -1
  30. package/src/runtime/compaction/tool-output-pruner.ts +20 -2
  31. package/src/runtime/crew-agent-records.ts +67 -4
  32. package/src/runtime/custom-tools/submit-result-tool.ts +17 -0
  33. package/src/runtime/deadletter.ts +5 -1
  34. package/src/runtime/dispatch-batch.ts +51 -10
  35. package/src/runtime/effectiveness.ts +24 -1
  36. package/src/runtime/finalize-run.ts +12 -1
  37. package/src/runtime/goal-workflow/dynamic-workflow-context.ts +12 -3
  38. package/src/runtime/goal-workflow/goal-evaluator.ts +30 -5
  39. package/src/runtime/goal-workflow/goal-loop-runner.ts +60 -3
  40. package/src/runtime/live-session/live-agent-control.ts +34 -14
  41. package/src/runtime/live-session/live-agent-manager.ts +20 -5
  42. package/src/runtime/live-session/live-session-runtime.ts +66 -81
  43. package/src/runtime/live-session/usage-bridge.ts +66 -2
  44. package/src/runtime/mcp-proxy.ts +10 -0
  45. package/src/runtime/model/model-fallback.ts +68 -0
  46. package/src/runtime/model/runtime-policy.ts +20 -6
  47. package/src/runtime/model/runtime-resolver.ts +5 -3
  48. package/src/runtime/orphan-worker-registry.ts +64 -24
  49. package/src/runtime/pi-spawn.ts +4 -1
  50. package/src/runtime/recovery/crash-recovery.ts +35 -2
  51. package/src/runtime/scheduling/batch-barrier.ts +42 -5
  52. package/src/runtime/scheduling/scheduler.ts +74 -29
  53. package/src/runtime/stale-reconciler.ts +41 -5
  54. package/src/runtime/surface/herdr-provider.ts +54 -1
  55. package/src/runtime/surface/launch-script.ts +7 -1
  56. package/src/runtime/surface/resolve-surface.ts +4 -1
  57. package/src/runtime/surface/tmux-provider.ts +32 -2
  58. package/src/runtime/task-runner/child-executor.ts +3 -2
  59. package/src/runtime/workspace-lock.ts +52 -4
  60. package/src/state/contracts.ts +2 -0
  61. package/src/state/coordination/process-lock.ts +50 -0
  62. package/src/state/event-log/cursor.ts +10 -1
  63. package/src/state/event-log/event-log-rotation.ts +26 -2
  64. package/src/state/event-log/worker-atomic-writer.ts +5 -0
  65. package/src/state/stores/active-run-registry.ts +56 -5
  66. package/src/state/stores/ownership-map.ts +26 -7
  67. package/src/state/stores/plan-store.ts +30 -1
  68. package/src/state/stores/sqlite-run-state.ts +91 -1
  69. package/src/state/types.ts +5 -0
  70. package/src/ui/dashboard-panes/agents-pane.ts +4 -3
  71. package/src/ui/dashboard-panes/plan-pane.ts +5 -3
  72. package/src/ui/dashboard-panes/transcript-pane.ts +2 -1
  73. package/src/ui/overlays/mailbox-detail-overlay.ts +5 -3
  74. package/src/ui/run-dashboard.ts +6 -4
  75. package/src/ui/run-snapshot-cache.ts +3 -2
  76. package/src/ui/settings-overlay.ts +68 -10
  77. package/src/ui/theme-discovery.ts +26 -7
  78. package/src/ui/transcript-viewer.ts +5 -3
  79. package/src/utils/visual.ts +84 -0
@@ -1,4 +1,5 @@
1
1
  import type { UsageState } from "../../state/types.ts";
2
+ import { logInternalError } from "../../utils/internal-error.ts";
2
3
  import { usageFromValue } from "../session-usage.ts";
3
4
  import { trackTaskUsage } from "../usage-tracker.ts";
4
5
 
@@ -9,11 +10,11 @@ import { trackTaskUsage } from "../usage-tracker.ts";
9
10
  * ledger — the runtime module keeps only the call sites.
10
11
  */
11
12
 
12
- function asRecord(value: unknown): Record<string, unknown> | undefined {
13
+ export function asRecord(value: unknown): Record<string, unknown> | undefined {
13
14
  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
14
15
  }
15
16
 
16
- function isString(value: unknown): value is string {
17
+ export function isString(value: unknown): value is string {
17
18
  return typeof value === "string";
18
19
  }
19
20
 
@@ -91,3 +92,66 @@ export function trackUsageFromMessageEndEvent(taskId: string, event: unknown): v
91
92
  cost: usage.cost,
92
93
  });
93
94
  }
95
+
96
+ /**
97
+ * R6-9 (DR-03 round-6): best-effort usage extraction for the fault/watchdog
98
+ * escape returns. The success return reports usageFromSessionStats(session as SessionWithStats | undefined),
99
+ * but the fault/watchdog catch paths previously carried NO usage — whenever
100
+ * embeddedWorkers routed work to the embedded tier and the task faulted, the
101
+ * burned turns vanished from the budget (under-count). The session may be
102
+ * disposed or partially unusable after the fault, so stats collection is
103
+ * guarded — it can never turn a fault into a crash. Returns undefined when no
104
+ * usable stats surface exists.
105
+ */
106
+ export function faultPathUsage(session: SessionWithStats | undefined): UsageState | undefined {
107
+ try {
108
+ return usageFromSessionStats(session as SessionWithStats | undefined);
109
+ } catch (error) {
110
+ logInternalError("live-session.fault-usage-stats", error, "session stats unavailable on fault path");
111
+ return undefined;
112
+ }
113
+ }
114
+
115
+ /**
116
+ * Type-safe extractor for tool name from streaming events.
117
+ * Handles various event structures: { tool: { name } }, { toolName }, { name }.
118
+ */
119
+ export function extractToolName(obj: Record<string, unknown> | undefined): string | undefined {
120
+ if (!obj) return undefined;
121
+ const tool = asRecord(obj.tool);
122
+ if (isString(tool?.name)) return tool.name;
123
+ if (isString(obj.toolName)) return obj.toolName;
124
+ if (isString(obj.name)) return obj.name;
125
+ return undefined;
126
+ }
127
+
128
+ export function textFromContent(content: unknown): string[] {
129
+ if (typeof content === "string") return [content];
130
+ if (!Array.isArray(content)) return [];
131
+ return content.flatMap((part) => {
132
+ const obj = asRecord(part);
133
+ if (!obj) return [];
134
+ if (obj.type === "text" && typeof obj.text === "string") return [obj.text];
135
+ if (typeof obj.content === "string") return [obj.content];
136
+ return [];
137
+ });
138
+ }
139
+
140
+ export function eventText(event: unknown): string[] {
141
+ const obj = asRecord(event);
142
+ if (!obj) return [];
143
+ const text: string[] = [];
144
+ if (typeof obj.text === "string") text.push(obj.text);
145
+ text.push(...textFromContent(obj.content));
146
+ const message = asRecord(obj.message);
147
+ if (message) text.push(...textFromContent(message.content));
148
+ return text.filter((entry) => entry.trim());
149
+ }
150
+
151
+ export function finalAssistantText(event: unknown): string[] {
152
+ const obj = asRecord(event);
153
+ if (obj?.type !== "message_end") return [];
154
+ const message = asRecord(obj.message);
155
+ if (message?.role !== "assistant") return [];
156
+ return textFromContent(message.content);
157
+ }
@@ -206,3 +206,13 @@ export function stripMcpExtensions(base: LoadedExtensionsShape): LoadedExtension
206
206
  ],
207
207
  };
208
208
  }
209
+
210
+ /**
211
+ * R1-M2 part 2 (Wave-3): pure fail-closed decision — when G2 MCP enforcement
212
+ * could not be armed (SDK loader missing / degraded), a NON-PERMITTED role
213
+ * must ABORT the live-session spawn instead of warn+proceed (fail-open);
214
+ * permitted roles keep the warn+proceed behavior (their access is intended).
215
+ */
216
+ export function shouldFailClosedMcpEnforcement(mcpPermitted: boolean, degradationReason: string | undefined): boolean {
217
+ return degradationReason !== undefined && !mcpPermitted;
218
+ }
@@ -444,13 +444,81 @@ const NON_RETRYABLE_MODEL_FAILURE_PATTERNS = [
444
444
  /credit/i,
445
445
  ];
446
446
 
447
+ // R2-M-B2 (Wave-3): provider SAFETY/REFUSAL stop reasons must NOT be retried
448
+ // down the fallback chain ("safety-refusal laundering" — re-dispatching the
449
+ // same refused prompt to other models). The STRUCTURED stop reason is the
450
+ // authoritative signal; the legacy `/safety/i` substring in
451
+ // RETRYABLE_MODEL_FAILURE_PATTERNS stays as a FALLBACK only for errors that
452
+ // carry no structured marker (legacy serialization).
453
+ export const SAFETY_REFUSAL_STOP_REASONS: ReadonlySet<string> = new Set([
454
+ "refusal",
455
+ "refused",
456
+ "safety",
457
+ "safety_block",
458
+ "safety_block_consumed",
459
+ "content_policy",
460
+ "content_policy_violation",
461
+ "content_filter",
462
+ ]);
463
+
464
+ /** Normalize + match a stop reason (or stopReason/stop_reason value) against the refusal/safety set. */
465
+ export function isSafetyRefusalStopReason(reason: unknown): boolean {
466
+ if (typeof reason !== "string") return false;
467
+ return SAFETY_REFUSAL_STOP_REASONS.has(reason.trim().toLowerCase());
468
+ }
469
+
470
+ const SERIALIZED_STOP_REASON_MARKER = /(?:stop_reason|stopReason|stop reason)["':=\s]+["']?([a-z_\- ]+)/i;
471
+
472
+ /**
473
+ * Structured safety-refusal detection on an ERROR OBJECT (preferred) or a
474
+ * serialized error string: true when the error carries a stop_reason in the
475
+ * refusal/safety family. Object shape: `{ stopReason }`, `{ stop_reason }`,
476
+ * nested under `.error`/`.cause`, or the same marker serialized into a string
477
+ * (JSON.stringify'd errors, stderr tails).
478
+ */
479
+ export function hasStructuredSafetyRefusal(errorLike: unknown): boolean {
480
+ if (!errorLike) return false;
481
+ if (typeof errorLike === "string") {
482
+ const match = SERIALIZED_STOP_REASON_MARKER.exec(errorLike);
483
+ return match ? isSafetyRefusalStopReason(match[1]) : false;
484
+ }
485
+ if (typeof errorLike !== "object") return false;
486
+ const obj = errorLike as Record<string, unknown>;
487
+ if (isSafetyRefusalStopReason(obj.stopReason)) return true;
488
+ if (isSafetyRefusalStopReason(obj.stop_reason)) return true;
489
+ if (obj.error !== undefined && obj.error !== obj && hasStructuredSafetyRefusal(obj.error)) return true;
490
+ if (obj.cause !== undefined && obj.cause !== obj && hasStructuredSafetyRefusal(obj.cause)) return true;
491
+ // Error instances: message may carry the serialized marker.
492
+ if (typeof obj.message === "string") {
493
+ const match = SERIALIZED_STOP_REASON_MARKER.exec(obj.message);
494
+ if (match && isSafetyRefusalStopReason(match[1])) return true;
495
+ }
496
+ return false;
497
+ }
498
+
447
499
  export function isRetryableModelFailure(error: string | undefined): boolean {
448
500
  if (!error) return false;
501
+ // R2-M-B2 (Wave-3): structured safety/refusal stop reasons are checked
502
+ // FIRST — non-retryable even when the message text otherwise matches
503
+ // retryable-looking patterns ("overloaded", "transient", …). The plain
504
+ // `/safety/i` substring below remains as the LEGACY fallback for errors
505
+ // without a structured marker.
506
+ if (hasStructuredSafetyRefusal(error)) return false;
449
507
  // Auth / billing / invalid-key failures will never succeed on retry.
450
508
  if (NON_RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error))) return false;
451
509
  return RETRYABLE_MODEL_FAILURE_PATTERNS.some((pattern) => pattern.test(error));
452
510
  }
453
511
 
512
+ /**
513
+ * R2-M-B2 companion for call sites that still hold the structured CAUSE
514
+ * object: consult it FIRST (authoritative), then fall back to the string
515
+ * classification of `message`.
516
+ */
517
+ export function isRetryableModelFailureFrom(cause: unknown, message?: string): boolean {
518
+ if (hasStructuredSafetyRefusal(cause)) return false;
519
+ return isRetryableModelFailure(message ?? (cause instanceof Error ? cause.message : undefined));
520
+ }
521
+
454
522
  export function formatModelAttemptNote(attempt: ModelAttemptSummary, nextModel?: string): string {
455
523
  const failure = attempt.error?.trim() || `exit ${attempt.exitCode ?? 1}`;
456
524
  return nextModel
@@ -40,6 +40,21 @@ export function resolveEmbeddedFaultThreshold(policy: CrewRuntimeConfig["embedde
40
40
  * (the same depth>0 rule is applied to the embedded upgrade itself).
41
41
  * - Otherwise, use `isolationPolicy.defaultRuntime` when configured, then fall back to globalKind.
42
42
  */
43
+ /**
44
+ * wave-2b (mock double-gate): PI_CREW_MOCK_LIVE_SESSION is a test seam that
45
+ * flips production runtime selection (policy + resolver) and fabricates a
46
+ * mock session — single-gated, an env var inherited from a hostile parent
47
+ * would silently downgrade a worker to a mock. Mirror the existing
48
+ * double-gated seams (PI_CREW_TEST_ASYNC_INLINE + PI_CREW_ALLOW_MOCK in
49
+ * async-runner.ts; PI_TEAMS_MOCK_CHILD_PI + PI_CREW_ALLOW_MOCK in
50
+ * mock-fixtures.ts): the mock only engages when PI_CREW_ALLOW_MOCK is ALSO
51
+ * set, and PI_CREW_ALLOW_MOCK is filtered from child envs.
52
+ */
53
+ export function mockLiveSessionEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
54
+ if (env.PI_CREW_MOCK_LIVE_SESSION !== "success") return false;
55
+ return env.PI_CREW_ALLOW_MOCK === "1" || env.PI_CREW_ALLOW_MOCK === "true";
56
+ }
57
+
43
58
  export function resolveTaskRuntimeKind(
44
59
  globalKind: CrewRuntimeKind,
45
60
  role: string,
@@ -51,22 +66,21 @@ export function resolveTaskRuntimeKind(
51
66
  // Safety: when already inside a pi-crew worker (depth > 0), never nest live-session.
52
67
  // Live-session creates in-process Pi agent sessions, which would recursively
53
68
  // try to use pi-crew, leading to "Cannot read properties of undefined" errors.
54
- // Exception: when PI_CREW_MOCK_LIVE_SESSION is set, we're in a test harness
55
- // that mocks the live-session path — forcing child-process would spawn a real
56
- // pi process and hang the test.
57
- if (globalKind === "live-session" && currentCrewDepth(env) > 0 && env.PI_CREW_MOCK_LIVE_SESSION !== "success") return "child-process";
69
+ // Exception: the double-gated mock seam (mockLiveSessionEnabled) — forcing
70
+ // child-process would spawn a real pi process and hang the test harness.
71
+ if (globalKind === "live-session" && currentCrewDepth(env) > 0 && !mockLiveSessionEnabled(env)) return "child-process";
58
72
  const isolatedRoles = isolationPolicy?.isolatedRoles ?? [];
59
73
  if (isolatedRoles.includes(role)) return "child-process";
60
74
  // U11 embedded-tier upgrade (DEFAULT-OFF). Guards mirror the depth guard
61
75
  // above: an in-process embedded session has the SAME nesting hazard, so
62
76
  // depth>0 keeps the task on child-process regardless of which kind the
63
77
  // caller resolved — the guard is EXTENDED to the embedded path, never
64
- // weakened (PI_CREW_MOCK_LIVE_SESSION keeps its test-harness exception).
78
+ // weakened (the double-gated mock seam keeps its test-harness exception).
65
79
  if (
66
80
  embedded?.policy?.enabled === true &&
67
81
  (embedded.policy.roles ?? []).includes(role) &&
68
82
  (embedded.faultCount ?? 0) < resolveEmbeddedFaultThreshold(embedded.policy) &&
69
- (currentCrewDepth(env) <= 0 || env.PI_CREW_MOCK_LIVE_SESSION === "success")
83
+ (currentCrewDepth(env) <= 0 || mockLiveSessionEnabled(env))
70
84
  ) {
71
85
  return "live-session";
72
86
  }
@@ -1,6 +1,7 @@
1
1
  import type { PiTeamsConfig } from "../../config/config.ts";
2
2
  import type { RuntimeResolutionState } from "../../state/types.ts";
3
3
  import type { CrewRuntimeKind } from "../crew-agent-runtime.ts";
4
+ import { mockLiveSessionEnabled } from "./runtime-policy.ts";
4
5
 
5
6
  export type CrewRuntimeMode = "auto" | "scaffold" | "child-process" | "live-session";
6
7
 
@@ -35,7 +36,8 @@ export async function isLiveSessionRuntimeAvailable(
35
36
  timeoutMs = 1500,
36
37
  env: NodeJS.ProcessEnv = process.env,
37
38
  ): Promise<{ available: boolean; reason?: string }> {
38
- if (env.PI_CREW_MOCK_LIVE_SESSION === "success") {
39
+ // wave-2b: double-gated mock seam — see mockLiveSessionEnabled.
40
+ if (mockLiveSessionEnabled(env)) {
39
41
  return {
40
42
  available: true,
41
43
  reason: "Mock live-session runtime is enabled.",
@@ -112,8 +114,8 @@ export async function resolveCrewRuntime(config: PiTeamsConfig, env: NodeJS.Proc
112
114
  }
113
115
  // auto mode: use child-process unless preferLiveSession is explicitly enabled
114
116
  if (requestedMode === "auto") {
115
- // Check for mock env var first (for testing)
116
- if (env.PI_CREW_MOCK_LIVE_SESSION === "success") {
117
+ // Check for the double-gated mock seam first (for testing)
118
+ if (mockLiveSessionEnabled(env)) {
117
119
  const live = await isLiveSessionRuntimeAvailable(1500, env);
118
120
  if (live.available) return liveCaps(requestedMode);
119
121
  }
@@ -174,31 +174,46 @@ function isValidId(id: string): boolean {
174
174
  return true;
175
175
  }
176
176
 
177
- function readRegistry(): OrphanWorkerEntry[] {
177
+ // FAMILY-2 (2026-10-17): strict read variant — ENOENT still maps to [] (a
178
+ // missing registry is a legitimate empty state), but any OTHER fault
179
+ // (EACCES/EBUSY/parse error/shape mismatch) THROWS. RMW callers
180
+ // (registerWorker/unregisterWorker) must skip their write on a strict-read
181
+ // fault: persisting the resulting [] would WIPE every sibling entry and
182
+ // orphan those workers until host exit.
183
+ function readRegistryStrict(): OrphanWorkerEntry[] {
178
184
  const p = getRegistryPath();
185
+ // Atomic read: if file doesn't exist, readFileSync throws ENOENT
186
+ // which we handle explicitly. This eliminates the TOCTOU window
187
+ // between existsSync and readFileSync.
188
+ let raw: string;
179
189
  try {
180
- // Atomic read: if file doesn't exist, readFileSync throws ENOENT
181
- // which we handle explicitly. This eliminates the TOCTOU window
182
- // between existsSync and readFileSync.
183
- const raw = fs.readFileSync(p, "utf-8");
184
- const parsed = JSON.parse(raw);
185
- if (!Array.isArray(parsed)) return [];
186
- return parsed.filter(
187
- (e): e is OrphanWorkerEntry =>
188
- typeof e === "object" &&
189
- e !== null &&
190
- typeof e.pid === "number" &&
191
- typeof e.sessionId === "string" &&
192
- typeof e.runId === "string" &&
193
- typeof e.registeredAt === "number" &&
194
- typeof (e as OrphanWorkerEntry).parentPid === "number" &&
195
- typeof (e as OrphanWorkerEntry).parentPidStartTime === "number" &&
196
- typeof (e as OrphanWorkerEntry).startTime === "number",
197
- );
190
+ raw = fs.readFileSync(p, "utf-8");
191
+ } catch (error) {
192
+ if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
193
+ throw error;
194
+ }
195
+ const parsed: unknown = JSON.parse(raw); // corrupt JSON throws (strict)
196
+ if (!Array.isArray(parsed)) {
197
+ throw new Error(`orphan-worker-registry: expected array, got ${typeof parsed}`);
198
+ }
199
+ return parsed.filter(
200
+ (e): e is OrphanWorkerEntry =>
201
+ typeof e === "object" &&
202
+ e !== null &&
203
+ typeof e.pid === "number" &&
204
+ typeof e.sessionId === "string" &&
205
+ typeof e.runId === "string" &&
206
+ typeof e.registeredAt === "number" &&
207
+ typeof (e as OrphanWorkerEntry).parentPid === "number" &&
208
+ typeof (e as OrphanWorkerEntry).parentPidStartTime === "number" &&
209
+ typeof (e as OrphanWorkerEntry).startTime === "number",
210
+ );
211
+ }
212
+
213
+ function readRegistry(): OrphanWorkerEntry[] {
214
+ try {
215
+ return readRegistryStrict();
198
216
  } catch (error) {
199
- if ((error as NodeJS.ErrnoException).code === "ENOENT") {
200
- return [];
201
- }
202
217
  // Silent failure is deliberate for robustness (registry read failures
203
218
  // shouldn't crash the process), but log at warning level to aid troubleshooting.
204
219
  logInternalError("orphan-worker-registry", new Error(`readRegistry failed: ${error}`), undefined, "warn");
@@ -278,7 +293,20 @@ export function registerWorker(
278
293
  const startTime = getProcessStartTime(pid) ?? 0;
279
294
  const parentPidStartTime = Number.isFinite(parentPid) && parentPid > 0 ? (getProcessStartTime(parentPid) ?? 0) : 0;
280
295
  withFileLockSync(getRegistryPath(), () => {
281
- const entries = readRegistry();
296
+ // FAMILY-2: strict read — a read fault must SKIP the write (persisting
297
+ // the [] rebuild would wipe every sibling entry), not mask as empty.
298
+ let entries: OrphanWorkerEntry[];
299
+ try {
300
+ entries = readRegistryStrict();
301
+ } catch (error) {
302
+ logInternalError(
303
+ "orphan-worker-registry.register",
304
+ error instanceof Error ? error : new Error(String(error)),
305
+ `pid=${pid} runId=${runId} — skipping write (registry read fault)`,
306
+ "warn",
307
+ );
308
+ return;
309
+ }
282
310
  // Dedupe by PID
283
311
  const filtered = entries.filter((e) => e.pid !== pid);
284
312
  filtered.push({
@@ -301,7 +329,19 @@ export function registerWorker(
301
329
  export function unregisterWorker(pid: number): void {
302
330
  if (!Number.isFinite(pid) || pid <= 0) return;
303
331
  withFileLockSync(getRegistryPath(), () => {
304
- const entries = readRegistry();
332
+ // FAMILY-2: strict read — skip the write on a read fault (see registerWorker).
333
+ let entries: OrphanWorkerEntry[];
334
+ try {
335
+ entries = readRegistryStrict();
336
+ } catch (error) {
337
+ logInternalError(
338
+ "orphan-worker-registry.unregister",
339
+ error instanceof Error ? error : new Error(String(error)),
340
+ `pid=${pid} — skipping write (registry read fault)`,
341
+ "warn",
342
+ );
343
+ return;
344
+ }
305
345
  const filtered = entries.filter((e) => e.pid !== pid);
306
346
  if (filtered.length !== entries.length) {
307
347
  writeRegistry(filtered);
@@ -96,7 +96,10 @@ function isWithinAllowedPrefixes(resolvedPath: string): boolean {
96
96
  }
97
97
  }
98
98
 
99
- return allowedPrefixes.some((prefix) => normalized.startsWith(prefix));
99
+ // R2-L-A9 (wave-2b): a bare startsWith accepts sibling-name escapes
100
+ // (prefix "/opt/pi" also matches "/opt/pwned"). The prefix must match the
101
+ // path itself or a path-separator-bounded descendant.
102
+ return allowedPrefixes.some((prefix) => normalized === prefix || normalized.startsWith(prefix + path.sep));
100
103
  }
101
104
 
102
105
  function resolvePiPackageRoot(): string | undefined {
@@ -700,6 +700,7 @@ export function purgeStaleActiveRunIndex(
700
700
  // is fire-and-forget so it stays OUTSIDE the lock to avoid blocking the
701
701
  // critical section on async IPC.
702
702
  let abortedFreshLiveness = false;
703
+ let abortedIntentionalWait = false; // R2-M-A3: keep intentional-wait runs
703
704
  try {
704
705
  const fullLoaded = loadRunManifestById(entry.cwd, entry.runId);
705
706
  if (fullLoaded) {
@@ -709,6 +710,14 @@ export function purgeStaleActiveRunIndex(
709
710
  const fresh = loadRunManifestById(entry.cwd, entry.runId);
710
711
  if (!fresh) return;
711
712
  if (fresh.manifest.status !== "running") return;
713
+ // R2-M-A3 (2026-10-17): mirror :135/:329/:937 — purgeStaleActiveRunIndex
714
+ // was the only recovery path without an isIntentionalWait guard: a run
715
+ // parked on a plan approval / pending ask was purge-CANCELLED here even
716
+ // though every sibling recovery path preserves it. KEEP the entry.
717
+ if (isIntentionalWait(fresh.manifest, now)) {
718
+ abortedIntentionalWait = true;
719
+ return;
720
+ }
712
721
  // R7-6 (2026-10-16): under-lock liveness revalidation — the pre-lock
713
722
  // gate used inputs read BEFORE the lock; a concurrent `team resume`
714
723
  // adoption may have rewritten them in that window (fresh
@@ -747,6 +756,14 @@ export function purgeStaleActiveRunIndex(
747
756
  }
748
757
  }
749
758
  updateRunStatus(fresh.manifest, "cancelled", "Orphaned run: worker process dead and no recent activity");
759
+ // R2-M-A3: clear waitState on cancel (mirror cancelOrphanedRuns :431-438) —
760
+ // an orphan-cancelled run must not keep the park pointer shielding it
761
+ // from staleness repair for the full waiting TTL.
762
+ if (fresh.manifest.waitState) {
763
+ const cleared = { ...fresh.manifest, waitState: undefined, updatedAt: new Date(now).toISOString() };
764
+ saveRunManifest(cleared);
765
+ fresh.manifest = cleared;
766
+ }
750
767
  });
751
768
  // R7-6: only terminate live agents when the cancel actually landed —
752
769
  // an aborted (fresh-evidence) run is alive; terminating it would kill
@@ -767,7 +784,9 @@ export function purgeStaleActiveRunIndex(
767
784
  }
768
785
  // R7-6: a fresh-evidence abort means the run is alive again — KEEP the
769
786
  // registry entry (live-claim signal) instead of unregistering it.
770
- if (abortedFreshLiveness) {
787
+ // R2-M-A3: an intentional-wait abort keeps the entry too (same reasoning —
788
+ // the run is parked on a human decision, not crashed).
789
+ if (abortedFreshLiveness || abortedIntentionalWait) {
771
790
  kept.push(entry.runId);
772
791
  continue;
773
792
  }
@@ -794,12 +813,19 @@ export function purgeStaleActiveRunIndex(
794
813
  if (!hasRecentLifeEvidence(entry, manifest.updatedAt, now, staleThresholdMs)) {
795
814
  let cancelledUnderLock = false;
796
815
  let abortedFreshLiveness = false;
816
+ let abortedIntentionalWait = false; // R2-M-A3: keep intentional-wait runs
797
817
  try {
798
818
  const fullLoaded = loadRunManifestById(entry.cwd, entry.runId);
799
819
  if (fullLoaded && fullLoaded.manifest.status === "running") {
800
820
  withRunLockSync(fullLoaded.manifest, () => {
801
821
  const fresh = loadRunManifestById(entry.cwd, entry.runId);
802
822
  if (fresh?.manifest.status !== "running") return;
823
+ // R2-M-A3 (2026-10-17): mirror the step-5 guard (and :135/:329/:937) — a
824
+ // parked run (plan approval / pending ask) is not an orphan. KEEP it.
825
+ if (isIntentionalWait(fresh.manifest, now)) {
826
+ abortedIntentionalWait = true;
827
+ return;
828
+ }
803
829
  // R7-6 (2026-10-16): under-lock liveness revalidation — the pre-lock
804
830
  // gate used inputs read BEFORE the lock; a concurrent `team resume`
805
831
  // adoption may have rewritten them in that window (fresh
@@ -846,6 +872,12 @@ export function purgeStaleActiveRunIndex(
846
872
  Math.round(staleThresholdMs / 60000) +
847
873
  " minutes",
848
874
  );
875
+ // R2-M-A3: clear waitState on cancel (mirror :431-438 + step 5 above).
876
+ if (fresh.manifest.waitState) {
877
+ const cleared = { ...fresh.manifest, waitState: undefined, updatedAt: new Date(now).toISOString() };
878
+ saveRunManifest(cleared);
879
+ fresh.manifest = cleared;
880
+ }
849
881
  cancelledUnderLock = true;
850
882
  });
851
883
  // R7-1/R7-6: only terminate live agents when the cancel actually landed
@@ -867,7 +899,8 @@ export function purgeStaleActiveRunIndex(
867
899
  }
868
900
  // R7-1/R7-6: a fresh-evidence abort means the run is alive again — KEEP
869
901
  // the registry entry (live-claim signal) instead of unregistering it.
870
- if (abortedFreshLiveness) {
902
+ // R2-M-A3: an intentional-wait abort keeps the entry too.
903
+ if (abortedFreshLiveness || abortedIntentionalWait) {
871
904
  kept.push(entry.runId);
872
905
  continue;
873
906
  }
@@ -55,8 +55,19 @@ export class BatchBarrier {
55
55
  }
56
56
  >();
57
57
 
58
- /** Register a member at spawn time. Idempotent per (batchId, agentId). */
58
+ /** R2-L-B6 (SEV-10): consolidated-notified batches are FREED (member maps
59
+ * dropped) and remembered here as tombstones so `alreadyNotified` stays
60
+ * true and late `markTerminal`/`register` calls never re-notify. Bounded
61
+ * (evict-oldest) — previously every batchId leaked its member maps for the
62
+ * session lifetime (zero production callers of dispose()). */
63
+ private readonly notifiedTombstones = new Map<string, number>();
64
+ private static readonly TOMBSTONE_CAP = 256;
65
+
66
+ /** Register a member at spawn time. Idempotent per (batchId, agentId).
67
+ * R2-L-B6: no-op for a tombstoned (already notified) batch — the member
68
+ * map is intentionally gone and must not resurrect a re-notifiable batch. */
59
69
  register(batchId: string, agentId: string, meta?: { description?: string; type?: string }): void {
70
+ if (this.notifiedTombstones.has(batchId)) return;
60
71
  let batch = this.batches.get(batchId);
61
72
  if (!batch) {
62
73
  batch = {
@@ -83,6 +94,18 @@ export class BatchBarrier {
83
94
  * on-the-fly as a batch-of-one so its terminal state is not silently lost.
84
95
  */
85
96
  markTerminal(batchId: string, member: BatchMember): BatchSnapshot {
97
+ // R2-L-B6: the batch already fired its consolidated notification and was
98
+ // freed — report notified:true so the caller NEVER re-notifies a late
99
+ // member (documented late-spawn semantics), without resurrecting the map.
100
+ if (this.notifiedTombstones.has(batchId)) {
101
+ return {
102
+ batchId,
103
+ members: [{ ...member }],
104
+ terminal: [{ ...member }],
105
+ allDone: true,
106
+ notified: true,
107
+ };
108
+ }
86
109
  let batch = this.batches.get(batchId);
87
110
  if (!batch) {
88
111
  batch = {
@@ -117,13 +140,22 @@ export class BatchBarrier {
117
140
 
118
141
  /** Has the consolidated notification already been emitted for this batch? */
119
142
  alreadyNotified(batchId: string): boolean {
120
- return this.batches.get(batchId)?.notified ?? false;
143
+ return this.batches.get(batchId)?.notified ?? this.notifiedTombstones.has(batchId);
121
144
  }
122
145
 
123
- /** Mark the consolidated notification as emitted. No-op if already set. */
146
+ /** Mark the consolidated notification as emitted. No-op if already set.
147
+ * R2-L-B6: DISPOSE the batch here — once the consolidated notify fired, the
148
+ * member maps are dead weight; keep only a bounded tombstone so
149
+ * `alreadyNotified`/late `markTerminal` preserve their answers. */
124
150
  markNotified(batchId: string): void {
125
151
  const batch = this.batches.get(batchId);
126
152
  if (batch) batch.notified = true;
153
+ this.batches.delete(batchId);
154
+ this.notifiedTombstones.set(batchId, Date.now());
155
+ if (this.notifiedTombstones.size > BatchBarrier.TOMBSTONE_CAP) {
156
+ const oldest = this.notifiedTombstones.keys().next().value;
157
+ if (oldest !== undefined) this.notifiedTombstones.delete(oldest);
158
+ }
127
159
  }
128
160
 
129
161
  /** Read-only snapshot (for tests / debugging). */
@@ -141,7 +173,12 @@ export class BatchBarrier {
141
173
 
142
174
  /** Drop a batch (used on cleanup / test reset). */
143
175
  dispose(batchId?: string): void {
144
- if (batchId === undefined) this.batches.clear();
145
- else this.batches.delete(batchId);
176
+ if (batchId === undefined) {
177
+ this.batches.clear();
178
+ this.notifiedTombstones.clear();
179
+ } else {
180
+ this.batches.delete(batchId);
181
+ this.notifiedTombstones.delete(batchId);
182
+ }
146
183
  }
147
184
  }