@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +195 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +7 -6
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +42 -21
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +77 -21
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +65 -29
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +7 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +204 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +718 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +489 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1223 -402
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +364 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +20 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -335,7 +335,6 @@ function resolveProbeStatus(text: string, timedOut: boolean): ProbeStatus {
335
335
 
336
336
  async function probeModel(
337
337
  pi: Pick<ExtensionAPI, "exec"> | { exec?: ExtensionAPI["exec"] },
338
- ctx: Pick<ExtensionContext, "cwd">,
339
338
  fullId: string,
340
339
  ): Promise<{ status: ProbeStatus; message?: string }> {
341
340
  if (typeof pi.exec !== "function") {
@@ -401,7 +400,7 @@ function filterDominatedModels(models: ProviderModelCatalogModel[]): ProviderMod
401
400
  return models.filter((candidate, index) => !models.some((other, otherIndex) => otherIndex !== index && dominatesModel(other, candidate)));
402
401
  }
403
402
 
404
- function buildProfileFile(kind: ProfileKind, models: { cheap: string; medium: string; strong: string }): SubagentProfileFile {
403
+ function buildProfileFile(models: { cheap: string; medium: string; strong: string }): SubagentProfileFile {
405
404
  return {
406
405
  subagents: {
407
406
  agentOverrides: {
@@ -544,7 +543,7 @@ export async function refreshProviderModelCatalog(
544
543
  const fullId = `${modelRecord.provider}/${modelRecord.id}`;
545
544
  const probe = options.probe === false
546
545
  ? { status: "skipped" as const, message: "Live probing disabled." }
547
- : await probeModel(pi, ctx, fullId);
546
+ : await probeModel(pi, fullId);
548
547
  observedModels.push({ rawModel, modelRecord, fullId, probe });
549
548
  }
550
549
  const classificationContext = buildClassificationContext(observedModels.map(({ modelRecord }) => ({
@@ -624,8 +623,8 @@ export async function generateProfilesForProvider(
624
623
  const dir = ensureSubagentProfilesDir();
625
624
  const quotaPath = path.join(dir, `${normalizedProvider}.quota.json`);
626
625
  const qualityPath = path.join(dir, `${normalizedProvider}.quality.json`);
627
- writeJsonFile(quotaPath, buildProfileFile("quota", quotaModels));
628
- writeJsonFile(qualityPath, buildProfileFile("quality", qualityModels));
626
+ writeJsonFile(quotaPath, buildProfileFile(quotaModels));
627
+ writeJsonFile(qualityPath, buildProfileFile(qualityModels));
629
628
  const selectedModels = new Set([...Object.values(quotaModels), ...Object.values(qualityModels)]);
630
629
  const selectedHeuristicFallbackCount = profileModels.filter((model) => selectedModels.has(model.fullId) && modelUsesHeuristicClassification(model)).length;
631
630
  return { quotaPath, qualityPath, catalogPath, quotaModels, qualityModels, heuristicFallbackCount, selectedHeuristicFallbackCount };
@@ -649,7 +648,7 @@ export async function checkSubagentProfile(
649
648
  const probeModelId = modelInfo ? `${modelInfo.fullId}${thinkingSuffix}` : entry.model;
650
649
  let probe = probeCache.get(probeModelId);
651
650
  if (!probe) {
652
- probe = await probeModel(pi, ctx, probeModelId);
651
+ probe = await probeModel(pi, probeModelId);
653
652
  probeCache.set(probeModelId, probe);
654
653
  }
655
654
  results.push({
@@ -4,9 +4,13 @@ import * as path from "node:path";
4
4
  import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
5
5
  import { TEMP_ROOT_DIR, type ActiveAsyncCapacitySnapshot, type AsyncStatus } from "../../shared/types.ts";
6
6
  import { readStatus } from "../../shared/utils.ts";
7
+ import { checkPidLiveness, type PidLiveness } from "./stale-run-reconciler.ts";
7
8
  import { readProcessTerminal } from "./process-terminal.ts";
8
9
 
9
10
  export const ACTIVE_ASYNC_CAPACITY_DIR = path.join(TEMP_ROOT_DIR, "session-active-async-capacity");
11
+ export const DEFAULT_ABANDONED_SLOT_RELEASE_AFTER_MS = 20 * 60 * 1000;
12
+ export const MIN_ABANDONED_SLOT_RELEASE_AFTER_MS = 5 * 60 * 1000;
13
+ export const MAX_ABANDONED_SLOT_RELEASE_AFTER_MS = 24 * 60 * 60 * 1000;
10
14
 
11
15
  export interface ActiveAsyncCapacityOwnerV1 {
12
16
  version: 1;
@@ -29,6 +33,7 @@ export interface ActiveAsyncCapacityHandle {
29
33
  markStarted(runnerProcessInstanceId: string): void;
30
34
  markWorkflowStarted(): void;
31
35
  rollback(): boolean;
36
+ rollbackBeforeRunnerProceed(runnerProcessInstanceId: string): boolean;
32
37
  reconcile(liveWorkflowRunIds?: ReadonlySet<string>): ActiveAsyncCapacitySnapshot;
33
38
  }
34
39
 
@@ -36,11 +41,22 @@ interface CapacityOptions {
36
41
  rootDir?: string;
37
42
  now?: () => number;
38
43
  token?: () => string;
44
+ abandonedSlotReleaseAfterMs?: number | false;
45
+ pidLiveness?: (pid: number) => PidLiveness;
39
46
  afterSlotRename?: (releasedDir: string) => void;
47
+ writeOwner?: (filePath: string, owner: ActiveAsyncCapacityOwnerV1) => void;
48
+ }
49
+
50
+ export interface ActiveAsyncCapacityReleaseEvidence {
51
+ releasedBy: "abandoned-timeout";
52
+ processProof: "unknown";
53
+ runnerPid: "gone";
54
+ lastActivityAgeMs: number;
55
+ abandonedSlotReleaseAfterMs: number;
40
56
  }
41
57
 
42
58
  export type ActiveAsyncCapacityReleaseVerdict =
43
- | { state: "releasable"; reason: string }
59
+ | { state: "releasable"; reason: string; evidence?: ActiveAsyncCapacityReleaseEvidence }
44
60
  | { state: "retained"; reason: string }
45
61
  | { state: "not-owned"; reason: string };
46
62
 
@@ -66,6 +82,12 @@ export function resolveMaxActiveAsyncRunsPerSession(value: unknown): number | un
66
82
  return value === 0 ? undefined : value;
67
83
  }
68
84
 
85
+ export function resolveAbandonedSlotReleaseAfterMs(value: unknown): number | false {
86
+ if (value === false) return false;
87
+ if (typeof value !== "number" || !Number.isInteger(value) || value < 1) return DEFAULT_ABANDONED_SLOT_RELEASE_AFTER_MS;
88
+ return value;
89
+ }
90
+
69
91
  export function activeAsyncCapacitySessionKey(sessionId: string): string {
70
92
  return createHash("sha256").update(sessionId).digest("hex");
71
93
  }
@@ -154,7 +176,7 @@ function withSlotClaim<T>(dir: string, operation: () => T): { acquired: true; va
154
176
  }
155
177
  }
156
178
 
157
- function removeOwnedSlot(dir: string, expected: ActiveAsyncCapacityOwnerV1, options: CapacityOptions, requireUnstarted = false): boolean {
179
+ function removeOwnedSlot(dir: string, expected: ActiveAsyncCapacityOwnerV1, options: CapacityOptions, requireUnstarted = false, release?: ActiveAsyncCapacityReleaseVerdict): boolean {
158
180
  if (requireUnstarted && (expected.runnerProcessInstanceId || expected.runnerStartedAt)) return false;
159
181
  const claimed = withSlotClaim(dir, () => {
160
182
  const current = matchingOwner(dir, expected);
@@ -162,17 +184,36 @@ function removeOwnedSlot(dir: string, expected: ActiveAsyncCapacityOwnerV1, opti
162
184
  const releasedDir = path.join(path.dirname(dir), `.${path.basename(dir)}.released-${randomUUID()}`);
163
185
  fs.renameSync(dir, releasedDir);
164
186
  options.afterSlotRename?.(releasedDir);
187
+ if (release?.state === "releasable" && release.evidence) {
188
+ appendAbandonedReleaseEvent(expected.asyncDir, expected, release.evidence, options.now?.() ?? Date.now());
189
+ }
165
190
  fs.rmSync(releasedDir, { recursive: true, force: true });
166
191
  return true;
167
192
  });
168
193
  return claimed.acquired && claimed.value;
169
194
  }
170
195
 
196
+ function appendAbandonedReleaseEvent(asyncDir: string, owner: ActiveAsyncCapacityOwnerV1, evidence: ActiveAsyncCapacityReleaseEvidence, now: number): void {
197
+ try {
198
+ const eventsPath = path.join(asyncDir, "events.jsonl");
199
+ fs.mkdirSync(path.dirname(eventsPath), { recursive: true });
200
+ fs.appendFileSync(eventsPath, `${JSON.stringify({
201
+ type: "subagent.capacity.released",
202
+ ts: now,
203
+ runId: owner.runId,
204
+ sessionId: owner.ownerSessionId,
205
+ ...evidence,
206
+ })}\n`, "utf-8");
207
+ } catch {
208
+ // Capacity release must not fail because its diagnostic event cannot be written.
209
+ }
210
+ }
211
+
171
212
  function terminalState(state: AsyncStatus["state"]): boolean {
172
213
  return state !== "queued" && state !== "running" && state !== "paused";
173
214
  }
174
215
 
175
- function runnerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus | null): ActiveAsyncCapacityReleaseVerdict {
216
+ function runnerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus | null, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
176
217
  if (!status) return { state: "retained", reason: "status file is missing or unreadable" };
177
218
  if (!owner.runnerProcessInstanceId) return { state: "retained", reason: "runner process identity has not been recorded" };
178
219
  if (status.sessionId !== owner.ownerSessionId) return { state: "retained", reason: `status session ${status.sessionId ?? "unknown"} does not match owner session ${owner.ownerSessionId}` };
@@ -191,7 +232,34 @@ function runnerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: AsyncSt
191
232
  && proof.runId === owner.runId
192
233
  && proof.runnerProcessInstanceId === owner.runnerProcessInstanceId
193
234
  ? { state: "releasable", reason: "matching observed process-terminal proof is present" }
194
- : { state: "retained", reason: `process-terminal proof is ${proof?.state ?? "missing"}` };
235
+ : abandonedRunnerReleaseVerdict(status, proof?.state ?? "missing", options);
236
+ }
237
+
238
+ function abandonedRunnerReleaseVerdict(status: AsyncStatus, proofState: string, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
239
+ const proofReason = `process-terminal proof is ${proofState}`;
240
+ const thresholdMs = resolveAbandonedSlotReleaseAfterMs(options.abandonedSlotReleaseAfterMs);
241
+ if (thresholdMs === false) return { state: "retained", reason: `${proofReason}; abandoned-timeout policy is disabled` };
242
+ if (status.state !== "failed") return { state: "retained", reason: `${proofReason}; abandoned-timeout policy requires a failed run, not ${status.state}` };
243
+ if (typeof status.pid !== "number" || !Number.isInteger(status.pid) || status.pid < 1) return { state: "retained", reason: `${proofReason}; runner PID is missing or invalid` };
244
+ const liveness = (options.pidLiveness ?? checkPidLiveness)(status.pid);
245
+ if (liveness !== "dead") return { state: "retained", reason: `${proofReason}; runner PID liveness is ${liveness}` };
246
+ const lastActivityAt = status.lastActivityAt ?? status.lastUpdate ?? status.endedAt;
247
+ if (typeof lastActivityAt !== "number" || !Number.isFinite(lastActivityAt)) return { state: "retained", reason: `${proofReason}; last activity timestamp is missing or invalid` };
248
+ const now = options.now?.() ?? Date.now();
249
+ const lastActivityAgeMs = Math.max(0, now - lastActivityAt);
250
+ if (lastActivityAgeMs <= thresholdMs) return { state: "retained", reason: `${proofReason}; last activity age ${lastActivityAgeMs}ms has not exceeded abandoned-timeout ${thresholdMs}ms` };
251
+ const evidence: ActiveAsyncCapacityReleaseEvidence = {
252
+ releasedBy: "abandoned-timeout",
253
+ processProof: "unknown",
254
+ runnerPid: "gone",
255
+ lastActivityAgeMs,
256
+ abandonedSlotReleaseAfterMs: thresholdMs,
257
+ };
258
+ return {
259
+ state: "releasable",
260
+ reason: `${evidence.releasedBy}: ${proofReason}; runner PID is gone; process proof unknown; last activity age ${lastActivityAgeMs}ms exceeds ${thresholdMs}ms`,
261
+ evidence,
262
+ };
195
263
  }
196
264
 
197
265
  function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: AsyncStatus | null, liveWorkflowRunIds: ReadonlySet<string>): ActiveAsyncCapacityReleaseVerdict {
@@ -203,7 +271,6 @@ function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: Async
203
271
  if (liveWorkflowRunIds.has(owner.runId)) return { state: "retained", reason: "workflow controller is still live" };
204
272
  for (const step of status.steps ?? []) {
205
273
  const label = step.workflowKey ?? step.agent;
206
- if (step.status === "pending" || step.status === "running" || step.status === "paused") return { state: "retained", reason: `workflow child ${label} is still ${step.status}` };
207
274
  if (typeof step.async !== "boolean") return { state: "retained", reason: `workflow child ${label} is missing async classification` };
208
275
  if (!step.async) continue;
209
276
  if (!step.runId) return { state: "retained", reason: `async workflow child ${label} is missing run id` };
@@ -222,10 +289,10 @@ function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: Async
222
289
  return { state: "releasable", reason: "workflow is terminal, controller is gone, and async children have observed proof" };
223
290
  }
224
291
 
225
- function ownerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, liveWorkflowRunIds: ReadonlySet<string>): ActiveAsyncCapacityReleaseVerdict {
292
+ function ownerReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, liveWorkflowRunIds: ReadonlySet<string>, options: CapacityOptions): ActiveAsyncCapacityReleaseVerdict {
226
293
  const status = readStatus(owner.asyncDir);
227
294
  return owner.kind === "runner"
228
- ? runnerReleaseVerdict(owner, status)
295
+ ? runnerReleaseVerdict(owner, status, options)
229
296
  : workflowReleaseVerdict(owner, status, liveWorkflowRunIds);
230
297
  }
231
298
 
@@ -262,7 +329,7 @@ export function inspectActiveAsyncCapacityOwner(
262
329
  release: { state: "not-owned", reason: `slot was transferred to ${owner.runId}` },
263
330
  };
264
331
  }
265
- return { owner, relation: "current", slotDir: dir, release: ownerReleaseVerdict(owner, liveWorkflowRunIds) };
332
+ return { owner, relation: "current", slotDir: dir, release: ownerReleaseVerdict(owner, liveWorkflowRunIds, options) };
266
333
  }
267
334
  }
268
335
  return { relation: "none", release: { state: "not-owned", reason: "no active-capacity slot records this run" } };
@@ -281,9 +348,10 @@ export function reconcileActiveAsyncCapacity(
281
348
  if (!owner
282
349
  || owner.ownerSessionId !== sessionId
283
350
  || owner.ownerSessionKey !== activeAsyncCapacitySessionKey(sessionId)
284
- || path.basename(dir) !== `slot-${owner.slot}`
285
- || ownerReleaseVerdict(owner, liveWorkflowRunIds).state !== "releasable") continue;
286
- removeOwnedSlot(dir, owner, options);
351
+ || path.basename(dir) !== `slot-${owner.slot}`) continue;
352
+ const release = ownerReleaseVerdict(owner, liveWorkflowRunIds, options);
353
+ if (release.state !== "releasable") continue;
354
+ removeOwnedSlot(dir, owner, options, false, release);
287
355
  }
288
356
  return snapshotFor(sessionId, limit, rootDir);
289
357
  }
@@ -313,6 +381,7 @@ function createSlot(poolDir: string, owner: ActiveAsyncCapacityOwnerV1): boolean
313
381
 
314
382
  function handleFor(owner: ActiveAsyncCapacityOwnerV1, limit: number, options: CapacityOptions, rollbackOwner?: ActiveAsyncCapacityOwnerV1): ActiveAsyncCapacityHandle {
315
383
  const rootDir = options.rootDir ?? ACTIVE_ASYNC_CAPACITY_DIR;
384
+ const writeOwner = options.writeOwner ?? writePrivateAtomicJson;
316
385
  const dir = slotDir(sessionDir(owner.ownerSessionId, rootDir), owner.slot);
317
386
  return {
318
387
  owner,
@@ -321,14 +390,10 @@ function handleFor(owner: ActiveAsyncCapacityOwnerV1, limit: number, options: Ca
321
390
  const current = matchingOwner(dir, owner);
322
391
  if (!current) return false;
323
392
  const next = { ...current, runnerProcessInstanceId, runnerStartedAt: options.now?.() ?? Date.now() };
324
- // Mark memory first. If persistence fails after the process starts, caller
325
- // cleanup must retain the occupied slot instead of rolling it back.
393
+ // Mark memory first so pre-proceed cleanup can distinguish a failed durable
394
+ // bind from an unrelated unstarted reservation.
326
395
  Object.assign(owner, next);
327
- try {
328
- writePrivateAtomicJson(path.join(dir, "owner.json"), next);
329
- } catch (error) {
330
- console.error(`Failed to bind active async capacity to runner '${runnerProcessInstanceId}'; capacity will remain occupied:`, error);
331
- }
396
+ writeOwner(path.join(dir, "owner.json"), next);
332
397
  return true;
333
398
  });
334
399
  if (!claimed.acquired || !claimed.value) throw new Error(`Active async capacity ownership changed for run '${owner.runId}'.`);
@@ -360,6 +425,26 @@ function handleFor(owner: ActiveAsyncCapacityOwnerV1, limit: number, options: Ca
360
425
  });
361
426
  return claimed.acquired && claimed.value;
362
427
  },
428
+ rollbackBeforeRunnerProceed(runnerProcessInstanceId) {
429
+ const claimed = withSlotClaim(dir, () => {
430
+ const current = matchingOwner(dir, owner);
431
+ if (!current) return false;
432
+ const boundToRunner = current.runnerProcessInstanceId === runnerProcessInstanceId;
433
+ const bindingFailedBeforeProceed = current.runnerProcessInstanceId === undefined && current.runnerStartedAt === undefined && owner.runnerProcessInstanceId === runnerProcessInstanceId;
434
+ if (!boundToRunner && !bindingFailedBeforeProceed) return false;
435
+ if (rollbackOwner) {
436
+ writePrivateAtomicJson(path.join(dir, "owner.json"), rollbackOwner);
437
+ Object.assign(owner, rollbackOwner);
438
+ return true;
439
+ }
440
+ const releasedDir = path.join(path.dirname(dir), `.${path.basename(dir)}.released-${randomUUID()}`);
441
+ fs.renameSync(dir, releasedDir);
442
+ options.afterSlotRename?.(releasedDir);
443
+ fs.rmSync(releasedDir, { recursive: true, force: true });
444
+ return true;
445
+ });
446
+ return claimed.acquired && claimed.value;
447
+ },
363
448
  reconcile(liveWorkflowRunIds) {
364
449
  return reconcileActiveAsyncCapacity(owner.ownerSessionId, limit, { ...options, rootDir, liveWorkflowRunIds });
365
450
  },